Содержание CLAUDE.md

Автономия и подтверждения

• Локальные действия — сам. Чтение файлов, правки, локальные сборки, запуск тестов, эмуляторы/симуляторы, форматтеры, линтеры, локальные скрипты — выполняются автоматически, без вопросов.
• Внешние изменения — только после подтверждения. Всё, что меняет состояние за пределами рабочей копии (заливка на хостинг/деплой, операции с удалёнными системами, внешние API, которые что-то записывают) — сначала спросить и дождаться явного «да» по каждой операции отдельно.

Режим разрешений — без окна «Allow this command?»

• Системное окно харнесса на запуск команд не должно всплывать на каждую мелочь. Рабочий механизм — широкий allow-список в глобальном ~/.claude/settings.json: правила уровня инструмента (Bash, WebFetch, WebSearch) разрешают такие вызовы без подтверждения во всех проектах.
• Это не отменяет гейт выше: внешние изменения всё равно проходят через явное «да» — гейт живёт на уровне инструкций, а не харнесса.
• deny-список (деструктивные команды) перебивает общий allow и остаётся жёстким страховочным барьером.

Архитектура: объясняй до и после

Для всего сложного (новый сервис/приложение, новые эндпойнты, новое хранилище или схема БД, интеграция с внешним API, фоновые воркеры, схема авторизации, миграции, заметный рефактор):

• ДО работы — разложи план и жди подтверждения. Не начинать код, пока не объяснил: (1) какие компоненты появляются и как связаны, (2) структура API — каждый эндпойнт: метод, путь, тело запроса/ответа, коды ошибок, доступ, (3) структура хранилища — таблицы/файлы, поля с типами, ключи, связи, (4) авторизация и где секреты, (5) риски и альтернативы с обоснованием выбора, (6) этапы. Большую задачу — предложить разбить и согласовать первый этап.
• ПОСЛЕ работы — объясни, что получилось. Итоговая структура API и хранилища, что изменилось относительно плана и почему, какие грабли вылезли, что осталось на будущее. Это же зафиксировать в tech-документации.
• Простые задачи — исключение: правка текста, мелкий фикс, стилевая мелочь, разовый скрипт — сразу, без выкладок.

Тестируй перед сдачей — всегда

Работа не сделана, пока не проверена вживую. «Скомпилировалось» / «типы сходятся» / «задеплоил» — это не проверка.

• После любой правки — прогон реального сценария. Фронтенд — через браузерную автоматизацию Playwright (кликнуть, ввести, увидеть результат, снять скриншот и измерить геометрию, если правил вёрстку); API — реальный запрос с реальными данными и разбор ответа; фоновые процессы — довести хотя бы одно задание до конца.
• Прогон Playwright-сценариев запускать сабагентами — так основной контекст не забивается дампами DOM и логами; наверх возвращается только вывод: что прошло, что упало, где. Удобно гонять несколько сценариев параллельно, по субагенту на сценарий.
• Проверяй оба состояния, а не только «счастливый путь»: с данными и без, до и после, включённое и выключенное.
• Правил вёрстку — измеряй, а не «на глаз»: координаты, перекрытия, отступы, влезает ли в экран.
• Докладывай честно. Не проверено — так и скажи; тест упал — покажи вывод.

Стандарты сервисов

• Комментарии в коде — на английском (inline-комментарии, докстринги, описания эндпойнтов). Языка документации для пользователя это не касается.
• Грамотная обработка ошибок. Любая операция, которая может упасть (сетевой вызов, парсинг, доступ к БД, AI-запрос), оборачивается в проверку с понятным сообщением пользователю и логом для разработчика. Не глотать молча: на бэке корректный HTTP-код, на фронте — человеческое сообщение. Никаких неперехваченных rejection-ов.
• Мобильная вёрстка. Любой фронтенд работает от ~320px: layout через flex/grid, единицы rem/%/vh/vw, viewport-meta, touch-цели минимум 44×44px.

Документация и структура файлов

Документация и логи живут на двух уровнях — репозитория и отдельного проекта:

• Уровень репозитория (общий для всех проектов): CLAUDE.md — правила и технические принципы, касающиеся всех проектов (грузится в контекст в начале каждой сессии); корневой user_commands.md — лог общей / инфраструктурной работы, не привязанной к конкретному проекту.
• Уровень каждого проекта (только про этот проект): user_instructions.md — для пользователя, весь видимый функционал (каждая функция/экран/кнопка/жест); tech_instructions.md — для разработчика (стек, структура файлов, ключевые модули, потоки данных, грабли); user_commands.md — лог работы именно по этому проекту.

Файлы проекта обновляем в той же правке, что и код. Зачем: когда у модели закончится контекст, именно эти файлы позволяют восстановить полную картину без чтения всего кода.

Единый дизайн

Все фронтенды — в одном стиле, референс shadcn/ui:

• Чистый минималистичный «системный» вид; нейтральная база + один акцентный цвет; дизайн-токены как CSS-переменные; светлая и тёмная темы.
• Аккуратные карточки и кнопки с тонкими border, мягкие тени, скругления через --radius, заметные focus-ring.
• Системный sans-serif, спокойные размеры, ограниченная ширина контента. Без агрессивных градиентов и неона.
• Никаких эмодзи в интерфейсе. Иконки — Lucide (inline-SVG, stroke: currentColor). Эмодзи — только там, где нет CSS (текст в буфер/мессенджер) и как «знак» приложения (фавиконка, OG-теги, лого в шапке).

Скиллы

Каждый скилл — отдельная папка со своими файлами. Для него действуют те же правила документации, что и для проектов: user_instructions.md (весь функционал) и tech_instructions.md (устройство). Создаём оба сразу и обновляем в той же правке, что и код скилла.

Лог команд

• Лог называется user_commands.md и ведётся на двух уровнях: корневой в репозитории — для общих / инфраструктурных задач, и отдельный user_commands.md в папке каждого проекта — для работы именно по нему.
• После выполненной просьбы — короткая запись в соответствующий лог: суть запроса + что сделано.
• Формат: под текущей датой, буллетами, кратко, со ссылками на файлы. Делать самому, без напоминаний.

Гигиена .gitignore

• Держи .gitignore актуальным: как только появляются новые сборочные/служебные артефакты (output сборки, кэши, локальные конфиги, ключи, зависимости) — сразу дополняй, чтобы мусор не попадал в репозиторий.
• Релизные артефакты (собранные бинарники под распространение) наоборот держим под версиями — это удобный способ их раздавать; игнорим только промежуточные каталоги сборки.