Пишите CLAUDE.md как конституцию: запреты, правила поведения, решения по умолчанию. 92 коммита за 5 дней без отклонений.
За 5 дней я сделал 92 коммита и выкатил продукт в продакшн (github.com/defi-io/smarts). Без аварий, без откатов, без больших рефакторингов. Дело не в том, что Claude гениален. Дело в 565 строках CLAUDE.md, которые лежат в корне проекта.
Эта статья — про то, как написать CLAUDE.md, который работает как конституция, и что происходит после.
Многие пишут CLAUDE.md как README — что за проект, как запустить. Это растрата.
README — для людей. CLAUDE.md — для Claude. Claude автоматически загружает его в начале каждой сессии. Каждая строка, которую вы туда положите, становится предусловием для всех его последующих решений.
В стиле README получаете вот что: Claude примерно понимает, что за проект, знает, как запускать тесты, но каждое техническое решение принимает с нуля.
В стиле конституции получаете вот что: Claude знает, какие пути закрыты, какие конвенции обязательны, в какую сторону по умолчанию сворачивать на каждой развилке, и когда нужно остановиться и спросить.
Разница: первый «попутно» подтянет новую зависимость, добавит слой абстракции, поправит Gemfile. Второй — нет.
Проект, который я делаю, называется smarts.md — платформа, которая генерирует live docs и MCP-серверы для смарт-контрактов. Его CLAUDE.md — 565 строк, разбит так:
1. Идентичность проекта (5 строк)
2. Ядро продукта (определение в одну строку + структурные отличия от конкурентов)
3. Стек (жёсткие ограничения, формат YAML)
4. Список запретов (явные пункты ❌)
5. Область охвата (жёсткие границы MVP)
6. Архитектура (с ASCII-диаграммой)
7. Структура каталогов (ответственность по файлам)
8. Соглашения по коду на Ruby (со сниппетами «делай / не делай»)
9. Стратегия кэширования (таблицей)
10. Требования к тестам
11. Детали деплоя
12. Git-воркфлоу
13. Правила использования Claude Code (поведенческие инструкции)
14. 90-дневные вехи
15. Ключевые принципы
Ни один блок не для красоты. Ниже выберу несколько и объясню, почему они написаны именно так.
Мой выглядит так:
❌ Без сервисов на TypeScript / Node.js
❌ Без ethers.js / web3.js
❌ Без Sidekiq (используем Solid Queue)
❌ Без React / Vue / Svelte (используем Hotwire)
❌ Без Redis (Solid Cache / Solid Queue / Solid Cable покрывают всё)
❌ Без неверифицированных контрактов (только верифицированные на Etherscan)
❌ Без Solana / Bitcoin / Move (только EVM)
Это Web3-проект. По умолчанию в Web3 — TypeScript + ethers.js + Redis + React. Я иду против. Причины у меня есть, но Claude их не знает. Без списка запретов Claude построит рекомендации на «отраслевом здравом смысле», зашитом в его обучающие данные — и это почти наверняка путь TypeScript.
Со списком запретов Claude перестаёт спрашивать «может, добавим Node-сервис, чтобы крутить web3.js?». Этот путь по умолчанию закрыт.
Главное: каждый пункт должен быть явным и абсолютным. Не пишите «постарайся избегать TypeScript». Пишите «без TypeScript». Всё нечёткое Claude прочитает как «можно обсуждать».
Последний крупный блок CLAUDE.md — «Правила использования Claude Code»:
### Когда я говорю «начинай делать X»
1. Сначала проверь, разрешает ли подход ограничения CLAUDE.md
2. Затем посмотри, есть ли уже близкая реализация в коде (не изобретай велосипед)
3. Перед написанием кода открой новую ветку
4. После реализации запусти тесты
5. Не делай авто-коммит — когда код написан и тесты зелёные, остановись
и доложи. Жди, пока я явно скажу "commit"
### Когда я говорю «у меня есть идея»
Не пиши код сразу. Сначала:
1. Подтверди понимание (перескажи)
2. Сравни с ограничениями CLAUDE.md
3. Укажи возможные проблемы или альтернативы получше
4. Дождись моего подтверждения, потом действуй
### При технической развилке
Когда CLAUDE.md ничего не указывает:
1. По умолчанию выбирай вариант «ближе к Rails-native»
2. По умолчанию выбирай вариант с меньшим числом зависимостей
3. По умолчанию выбирай вариант, который позволяет solo-разработчику быстрее итерировать
4. При сомнении — остановись и спроси
Этот раздел в десять раз важнее, чем «используй snake_case».
Стиль кода Claude учит, читая код. Но «когда останавливаться и спрашивать», «услышав „у меня есть идея", сначала перескажи, а не сразу пиши код» — это поведенческие шаблоны. По одному коду их не выучить.
Самая важная строка: в какую сторону по умолчанию сворачивать на развилке. Это правило одно решает, что делает Claude, когда вас нет в комнате (когда вы просто говорите «начинай X» и уходите). Пропишите её ясно — и сможете отпускать Claude работать без надзора.
В шапке CLAUDE.md написано:
Этот документ — «первоисточник» проекта. Загружается автоматически в начале каждой сессии Claude Code. При смене технических решений сначала меняем здесь, код подтягивается следом.
Это договор о воркфлоу. Когда я решаю сменить какое-то техническое решение — скажем, поднять основную AI-модель с gpt-5-mini до gpt-5 — первый шаг не в том, чтобы лезть в initializer. Первый шаг — отредактировать этот фрагмент в CLAUDE.md:
ai:
fast: gpt-5-mini # до
fast: gpt-5 # после
Потом я даю Claude перечитать CLAUDE.md и привести код в соответствие.
Почему? Потому что если вы поменяли значение в коде, а CLAUDE.md отстал, в следующий раз Claude прочтёт CLAUDE.md, увидит старое значение и «по доброте» откатит ваш код. Корень конфликта — единая точка отказа: CLAUDE.md отстал. Конституция, отстающая от реальности, — так начинаются гражданские войны.
Относиться к CLAUDE.md как к конституции значит одно: он всегда бежит впереди кода.
smarts.md, 5 дней, 92 коммита:
Средняя жизнь PR — 30 минут. Без больших рефакторингов. Без «погоди, направление не то, откатываем».
Не потому, что Claude — магия. А потому, что в каждой сессии он бежал по 565-строчным рельсам. Знал, что нельзя тащить TypeScript, знал, что Solid Queue — очередь по умолчанию, знал, что view-функции кэшируются 60 секунд, знал, что каждый service должен реализовать классовый метод call, знал, что перед коммитом надо ждать моего подтверждения.
Уберите половину этих ограничений — получите: 30 минут в день на объяснение «почему мы не используем X», 5 минут на ревью зависимости, которую он добавил «попутно», и Gemfile, медленно расползающийся по швам.
Не начинайте с пустого файла. Начните с самого свежего решения, которое сделало больно.
Если в последнее время Claude «постоянно тянет новые зависимости» — пишите список запретов.
Если «чуть что меняет архитектуру» — диаграмма архитектуры + «новые микросервисы, смена БД и т.п. — только с подтверждением».
Если «не пишет тесты» — «что обязательно покрывается юнит-тестами».
Если «коммитит слишком агрессивно» — «без авто-коммита, ждать явной команды».
На каждую боль — одна запись. Остальное пока не пишите.
Через три месяца у вас будет CLAUDE.md строк на 500, и за каждой строкой стоит конкретное «не хочу, чтобы он так делал». Этот документ сильнее любого шаблона, потому что он точно подогнан под ваш проект, ваш воркфлоу, вашу команду (даже если вы сами по себе).
Конституция не пишется одним махом. Она кристаллизуется из конкретных конфликтов, по одному.
Исходники: github.com/defi-io/smarts