zov-tech/CLAUDE.md

Claude — правила работы с проектом zov-tech

---

🪪 ИДЕНТИФИКАЦИЯ АГЕНТА — ОБЯЗАТЕЛЬНО В КАЖДОМ ОТВЕТЕ

Каждый ответ в этом проекте НАЧИНАЕТСЯ с одной строки-бейджа:

Кто отвечает	Бейдж
Общение, планирование, координация	🤖 КООРДИНАТОР
Код, баги, рефакторинг	🔧 DEV
VPS, деплой, инфраструктура	⚙️ DEVOPS
CSS, UI, прототипы	🎨 DESIGN
Новый функционал, продуктовые решения	🧩 FEATURE
Тесты, качество, покрытие	🧪 TEST
Сводный отчёт по всем агентам	🔍 REVIEW

Формат строки:

---
🔧 DEV
---

Правила:

• Бейдж всегда первая строка ответа, до любого текста
• Один ответ = один бейдж (если несколько ролей — выбрать основную)
• Если задача переключает роль — бейдж меняется
• Без бейджа ответ не считается правильным

---

🧠 Принципы работы Claude в этом проекте

1. ОСПАРИВАЙ РЕШЕНИЯ. Если подход плохой — скажи прямо. Не соглашайся только потому что попросили. Лучше короткий аргумент «это плохо потому что…» чем молчаливое выполнение.

2. СТРУКТУРА КАЖДОГО ОТВЕТА:

   • ✅ Что сделано
   • ❓ Что нужно от тебя (если нужно что-то)
   • ➡️ Следующий шаг

3. ПОСЛЕ КАЖДОЙ ЗАДАЧИ — предлагай что улучшить или автоматизировать. Одно-два конкретных предложения, не список на 10 пунктов.

4. ВСЁ ЧТО МОЖЕТ ДЕЛАТЬ CLAUDE — ДЕЛАЕТ CLAUDE. Цель — освободить время владельца. Не спрашивать разрешения на очевидные технические шаги. Делать, потом сообщать.

---

⚠️ ОБЯЗАТЕЛЬНЫЙ АГЕНТ ПРОВЕРКИ ПЕРЕД ЛЮБЫМ UI/CSS КОММИТОМ

Перед каждым git commit с изменениями в miniapp/ — запустить:

/project:ui-check

Агент читает изменённые файлы, проходит чеклист и выдаёт вердикт. Коммит только после вердикта ✅.

---

Детальный чеклист (используется агентом /project:ui-check)

Перед каждым git commit с изменениями в miniapp/ — пройти все пункты:

1. Цвет и читаемость

• Используется ли color: transparent для скрытия текста? (НЕ var(--card) — она зависит от Telegram-темы и может быть не нужным цветом)
• Нет ли текста, где color и background одинаковы только в светлой теме?
• Проверены ли все 4 темы: Default, Foundry, Boardroom, Atelier — в каждой из них --card, --paper, --ink, --muted могут быть разными
• Если добавляется новый CSS-класс — указан ли явный color: (не наследование)?

2. Новые CSS-классы

• Для каждого нового класса (.foo) — проверить, что стили явно определены и не полагаются на наследование от body
• Добавлены ли стили для всех тем (ищи блоки [data-theme="foundry"], [data-theme="boardroom"], [data-theme="atelier"] в styles.css)?

3. Версия кэша

• Бамп ?v= в index.html для каждого изменённого .css или .js файла
• Формат: ?v=YYYYMMDD[буква] — буква растёт по алфавиту в течение дня

4. Деплой

• После git push — GitHub Actions деплоит ~1-2 мин (смотреть на вкладке Actions в GitHub)
• VPS (бот + бэкенд) обновляется отдельно: ssh root@94.241.170.144 "cd /opt/zov-tech && git pull && docker compose -f deploy/docker-compose.yml up -d --build bot"

---

Архитектура проекта

miniapp/          → статика, деплой через GitHub Pages (github.com/wasrusgen/zov-tech)
bot/              → Telegram-бот, работает на VPS 94.241.170.144
backend-py/       → FastAPI-бэкенд, работает на VPS
deploy/           → docker-compose.yml, Caddyfile.snippet

• MINIAPP_URL: https://wasrusgen.github.io/zov-tech/
• API: https://api.wasrusgen1.pro
• VPS SSH: ssh -i ~/.ssh/zov_vps_ed25519 root@94.241.170.144

CSS-переменные по темам

Переменная	Default (светлая)	Foundry	Boardroom	Atelier
--card	tg-section-bg (≈белый)	#EAE3CC	#EDE5D0	#FFFFFF
--ink	tg-text-color	#1A150E	#1A150E	тёмный
--muted	серый	#7A6E5F	#6B6256	серый

⚠️ var(--card) в дефолтной теме читается из --tg-theme-section-bg-color Telegram. В тёмном Telegram-клиенте это НЕ белый цвет. Для полного скрытия текста — только color: transparent.

Типичные ошибки (уже были)

1. color: var(--card) для скрытия текста → не работает: --card зависит от Telegram-темы и может не совпадать с фактическим фоном
2. color: transparent для скрытия текста → НЕ использовать: создаёт "дырку" — буквы просвечивают фон страницы за карточкой, силуэт текста виден
3. Правильный способ скрыть текст → opacity: 0 — элемент невидим полностью, место сохраняет, никаких артефактов
4. Новый JS-класс без CSS → текст наследует color: var(--ink) от body → видим на фоне карточки
5. Не бамп версии → WebView грузит старый кэш → изменения не видны
6. var(--card) как фон у hero-секции → при изменении темы текст становится невидимым (светлый текст на светлом фоне). Решение: явный color: var(--ink) inline