Пишіть CLAUDE.md як конституцію: заборони, правила поведінки, рішення за замовчуванням. 92 коміти за 5 днів без відхилень.
За 5 днів я зробив 92 коміти й випустив продукт у прод (github.com/defi-io/smarts). Без аварій, без відкатів, без великих рефакторингів. Не тому, що Claude — геній. А тому, що в корені проєкту лежить CLAUDE.md на 565 рядків.
Ця стаття — про те, як написати 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. За замовчуванням обирай варіант, який дозволяє соло-розробнику швидше ітерувати
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