Практичний посібник з написання ефективного файлу CLAUDE.md

Минулого місяця розробник скоротив файл CLAUDE.md, який зростав протягом року, на 340 рядків.

Розмір файлу постійно збільшувався. Щоразу, коли Claude Code поводився дратівливо, додавалося нове правило. Щоразу, коли яке-небудь правило не спрацьовувало, під ним додавалася ще довша версія. До серпня кількість рядків у файлі сягнула 400, а поведінка Claude стала значно гіршою, ніж тоді, коли у файлі було лише 60 рядків.

Після скорочення кількості рядків до 61 покращення стало помітним вже того ж дня.

Це насправді не урок особистої дисципліни. Це урок про те, для чого існує файл правил. Це не список бажань, який накопичується з часом. Це набір інструкцій, які модель читає на початку кожної сесії, і кожен додатковий рядок мусить конкурувати за увагу з усім іншим, що вже там є.

Нижче наведено 21 правило, які пройшли відбір, разом із обґрунтуванням кожного з них.

Справжня вартість перевантаженого CLAUDE.md

У серпні 2026 року хтось із спільноти Claude Code вирішив перевірити те, що здається очевидним, але чого ніхто насправді не підтверджував: чи справді Claude дотримується інструкцій CLAUDE.md, які йому надано.

Початковий аналіз показав, що 55,7% правил у типовому файлі принципово можна було перевірити. Після ручного огляду цей показник знизився до 18%, потім до 8,75%, і врешті-решт залишився на рівні 6,67%.

Зупиніться на хвилину та подумайте над цим числом. У типовому CLAUDE.md лише близько однієї з п’ятнадцяти правил може бути фактично перевірена. Решта чотирнадцять – це радше принципи на кшталт „писати чистий код“, „дотримуватися найкращих практик“, „бути обережними щодо продуктивності“. Ніхто, ні модель, ні ви, не може визначити, чи справді цими принципами дотримувалися.

Ось у чому справжня ціна надмірно великого файлу. Справа не лише у тому, що неперевірні правила ігноруються. Проблема в тому, що вони все одно займають місце у вікні контексту на кожному кроці, займаючи простір у правилах, які могли б бути справді важливими.

Приблизно в той самий час інженери компанії Anthropic зробили подібне спостереження щодо системних запитів у своїй системі: після досягнення певної довжини додавання більше інструкцій погіршує продуктивність замість того, щоб її покращувати. Їхні найновіші моделі тепер постачаються з системними запитами, розмір яких значно менший, ніж раніше.

Ваш файл CLAUDE.md дотримується абсолютно такої ж схеми. 21 правило нижче розроблено для того, щоб зберегти продуктивність у корисному діапазоні.

Правила 1–7: Зупинити шкоду

Ці перші правила існують для того, щоб запобігти ситуації, коли Claude перетворює просте завдання на катастрофу.

Правило 1: Робіть лише точкові зміни

## Editing
Change the minimum number of lines needed.
Do not reformat, reorder, or rename anything you were not asked to change.
Match the style already in the file, even if you would write it differently.

Чому це працює: Без цього обмеження Claude схильний „покращувати“ кожен файл, який він торкається. Ви просите виправлення у одному рядку, але замість цього отримуєте диференцію на 200 рядків, де ваше справжнє виправлення заховане десь всередині. Це, мабуть, найпоширеніша скарга щодо кодувальних агентів, і водночас одна з найпростіших для вирішення.

Раніше: Ви просите виправити помилку типу „off-by-one“ у функції-колбеку. Натомість код перетворюється на async/await, три змінні отримують нові імена, а первинна помилка залишається.

Після: Змінюється лише один рядок. Його перегляд займає близько чотирьох секунд.

Правило 2: Ніколи не переписувати мої тести

## Tests
Do not edit existing tests to make failing code pass.
If a test fails, fix the code.
If you believe the test itself is wrong, say so and stop. Do not edit it.

Чому це працює: Модель, якій наказано зробити тести успішними, завжди обере найкоротший доступний шлях, а переписування тестових умов є простішим, ніж фактичне виправлення основної помилки. Це правило повністю усуває такий швидкий спосіб.

Раніше: Три тести стали зеленими. Два з них тепер перевіряють щось некоректне.

Після: Claude повідомляє, що тест очікує значення 404, тоді як код повертає 500, а потім запитує, який з них насправді є неправильним.

Правило 3: Не додавайте залежності

## Dependencies
Do not add packages. Use what is already in package.json.
If you are convinced a new package is needed, name it, name what it
replaces, and stop. Wait for approval.

Чому це працює: Кожен інструмент для програмування звертається до нової бібліотеки так само, як це може зробити початківець-розробник. Якщо не контролювати це, у результаті з’являється три окремі бібліотеки для обробки дат та розмір пакету, який ніхто не може пояснити.

Раніше: Просте завдання форматування дати у чотири рядки перетворюється на нову залежність та зміну файлу блокування.

Після: Ті самі чотири рядки, створені за допомогою вже наявного API Intl.

Правило 4: Не використовувати обробку помилок для ситуацій, які неможливо отримати

## Error Handling
Handle errors that can actually occur here.
Do not add try/catch around code that cannot throw.
Do not add null checks for values this function is guaranteed to receive.

Чому це працює: Захисний код, написаний для запобігання неможливим станам, насправді не є засобом безпеки — це зайвий шум. Він приховує два перевірки, які справді мають значення, та подвоює довжину функції без жодної користі.

Раніше: Функція з 12 рядками, доповнена чотирма захисними клозулами, три з яких ніколи не можуть бути активовані.

Після: Та сама функція з 12 рядками, у якій залишається лише одна перевірка, яка може реально зазнати невдачі.

Правило 5: Не торкайтеся того, про що вас не просили

## Scope
Work only on what was asked.
Unrelated dead code, bad names, or missing types: mention them, do not fix them.
Remove imports and variables that YOUR change made unused. Nothing else.

Чому це ефективно: Розширення області видимості, приховане всередині порівняння, залишається непомітним доти, доки хтось його не перегляне, а до того часу це вже витрачає реальний час. Чітке визначення меж заздалегідь усуває необхідність здогадок щодо того, що вважається допустимим.

Правило 6: Ніколи не зберігати секрети

## Security
Never write a key, token, password, or connection string into a file.
Never commit .env, .env.*, or any credentials file.
If a value is needed, reference the environment variable by name.

Чому це ефективно: Це один із рідкісних випадків, коли одна помилка є непоправною. Інструкція є короткою, безумовною та легкою для перевірки, що саме відповідає ідеальній формі хорошого правила.

Правило 7: Запитуйте перед виконанням будь-яких руйнівних дій

## Destructive Actions
Stop and ask before: dropping a table, deleting a branch, force pushing,
rewriting history, deleting a file you did not create, or running a
migration against anything that is not local.

Чому це працює: У моделі немає вбудованого розуміння того, що можна, а що не можна скасувати. З її точки зору, зміна історії операцій та форматування текстового файлу — це однакові дії: просто ще один виклик інструменту. Це правило надає їй категорію ризиків, яку вона інакше не змогла б самостійно розпізнати.

Правила 8–14: Правила написання, яких вона може справді дотримуватися

Це розділ, який стосується основної проблеми низького рівня дотримання правил. Ці правила не стосуються безпосередньо поведінки, а стосуються того, як сформулювати правила, що регулюють поведінку.

Правило 8: Кожне правило має бути перевірним

Bad:  Write clean, maintainable code.
Good: Functions over 40 lines must be split.

Чому це працює: Якщо ви не можете швидко переглянути результат та відповісти «так» чи «ні», це правило нічого не робить, окрім як займає місце в коді. Перш ніж додати новий рядок до цього файлу, запитайте себе, які докази покажуть, що воно було порушене. Якщо ви не можете на це відповісти, не додавайте це правило.

Раніше: Така інструкція, як «писати чистий та легко підтримуваний код», залишалася невикористаною у вашому файлі протягом місяців. Вона жодного разу не вплинула на результат та ви ніколи не могли навести приклад її порушення.

Після: У документі з відмінностями з’являється функція з 61 рядком, і ви можете безпосередньо вказати правило, яке вона порушує. Потім або це правило починають дотримуватися, або його видаляють. Обидва результати сприяють прогресу.

Правило 9: Одне правило — один рядок

Bad:  When you are working on components, please try to keep them
      focused and reasonably small, and generally avoid mixing data
      fetching with presentation where that makes sense.
Good: Components do not fetch data. Fetch in the route, pass props down.

Чому це працює: Правило, сформульоване у вигляді нейтральних формулювань, звучить як м’яка пропозиція. Пропозиції завжди поступаються тому, до чого модель вже схильна робити.

Правило 10: Називайте файл, а не емоції

Bad:  Follow our API conventions.
Good: New routes follow the shape in src/api/users/route.ts.

Чому це працює: Фраза на кшталт „наші конвенції“ має сенс лише для вас, людини. Шлях до файлу — це те, що модель може фактично відкрити та прочитати. Посилання на реальний, існуючий код краще за будь-який опис цього коду у текстовій формі.

Правило 11: Забороняйте, а не заохочуйте

Bad:  Prefer simple solutions.
Good: Do not add an interface with one implementation.
      Do not add a config option for a value that never changes.

Чому це працює: Такі слова, як „воліти“, діють лише як критерій для вирішення суперечок, і лише тоді, коли модель вже не впевнена у своєму рішенні. Натомість фраза „Не робіть“ слугує чітким заборонним сигналом. Майже кожне правило, яке не спрацьовує на практиці, так це тому, що воно сформульоване як заохочення, а не як заборона.

Є простий тест на це: прочитайте правило та запитайте себе, чи модель, яка вирішила зробити те, що ви намагаєтесь запобігти, все одно може технічно дотримуватися цього правила у його нинішньому вигляді. Якщо так, то те, що ви написали, є лише перевагою, а не правилом.

Правило 12: Розмістіть правило там, де відбувається робота

Core rules live in the root CLAUDE.md, not only in path-scoped rule files.

Чому це працює: Цей момент легко проігнорувати, і це може спричинити справжню проблему, якщо це станеться. У серпні 2026 року була подана скарга на Claude Code, у якій описувалося, як файли з правилами, що діють у певному шляху, можуть мовчки не завантажуватися, коли агент змінює файли за допомогою команд оболонки замість вбудованого інструменту редагування, оскільки вставка правил пов’язана саме з цим способом редагування. Інші користувачі також повідомляли про такі проблеми з правилами, які зберігаються у вкладених файлах підкаталогів.

Цей урок залишається актуальним незалежно від того, чи буде ця конкретна проблема виправлена. Усе, що дійсно не можна дозволити собі проігнорувати, має знаходитися у кореневому файлі, який завжди завантажується, а не у умовному файлі, який завантажується лише іноді.

Правило 13: Обмежте довжину файлу

CLAUDE.md stays under 60 lines. If you need line 61, delete something first.

Чому це працює: Саме це правило найбільше покращило фактичну налаштованість одної команди, і воно суперечить інтуїції. Розтягування файлу до 400 рядків не означає наявності 400 правил, за якими може діяти модель. Це лише створює щільний блок тексту, де критичні інструкції змішуються з додатковим контентом.

Шістдесят рядків — це не якийсь магічний поріг. Важлива сама обмеження: додавання нового правила має коштувати вам відмови від старого, тож залишаються лише ті правила, які варто зберегти.

Правило 14: Зберігайте правила, навички та робочі процеси в окремих місцях

CLAUDE.md      : rules that apply to every single task
.claude/skills : reference material, read only when relevant
.claude/commands : fixed step sequences, invoked by name

Чому це працює: Більшість файлів з правилами надмірного розміру виникають через те, що до них насправді вкладені три різні типи документів. Опис схеми вашої бази даних — це не правило. Послідовність розгортання також не є правилом. Як тільки цей матеріал буде переміщений, залишені правила знову стануть видимими, а не залишаться прихованими.

Правила з 15 по 21: Забезпечення дії правил протягом тривалої сесії

Правило, яке модель дотримується на третьому кроці, але забуває на сороковому, насправді ніколи не було правилом. Цей набір рекомендацій спрямований на те, щоб інструкції залишалися актуальними протягом усієї сесії.

Правило 15: Зберігайте правила у файлі, а не лише під час розмови

Any instruction that must hold for the whole project belongs in this file.
Instructions given in conversation apply to the current task only.

Чому це працює: Довгі сесії з часом стискаються. Коли відбувається це стиснення, деталі розмови узагальнюються, тоді як файли завантажуються повністю. Один з записів з серпня 2026 року чітко ілюструє це: користувач по черзі двічі попросив модель ніколи не підвищувати версію пакета, стиснення відбулося на середині процесу, а до сорокового запиту версія все одно була підвищена. Нічого не зламалося та не виникло помилок — інструкція просто перестала існувати в робочому контексті моделі.

Якщо ви помічаєте, що багато разів повторюєте одну й ту саму інструкцію в чаті, сприймайте це як сигнал. Вона має знаходитися у файлі, а не у ваших дописах.

Правило 16: Завантажте файл правил після стиснення

After any context compaction, re-read CLAUDE.md before the next edit.

Чому це працює: Це недорогий захід проти саме тієї несправності, про яку йдеться у Правилі 15, і це одне з небагатьох правил, де можна безпосередньо підтвердити дотримання просто шляхом перегляду запису.

Правило 17: Вказати точну команду, яка використовується для перевірки роботи

## Verification
Before saying a task is done, run:
  npm run typecheck && npm test -- --run
Paste the final line of output. If it fails, fix it. Do not report success.

Чому це працює: Інструкція на кшталт "переконайтеся, що тести пройшли" не дає моделі нічого конкретного для виконання. Буквальна команда терміналу дає таку можливість, а вимога надати результат виконання дозволяє миттєво перевірити твердження про успіх, замість того щоб вірити йому на слово.

Правило 18: Чітко описати, що насправді означає "зроблено"

## Done
A task is done when: the change is made, typecheck passes, tests pass,
and you have stated in one sentence what changed and why.
Not done: "this should work", "you may want to verify".

Чому це працює: Якщо цей параметр залишити невизначеним, модель сама визначатиме, що означає завершення роботи, і це визначення зазвичай є просто „Я створив певний текст“. Це єдине правило більше, ніж будь-яке інше, допомагає зменшити кількість випадків, коли через годину з’ясовується, що процес будування насправді зламаний.

Правило 19: Обмежуйте зворотний зв’язок однією конкретною дією

When something did not work, name ONE thing to change and why.
Do not list five options.

Чому це працює: Надання п’яти різних варіантів у разі збою насправді є способом ухилення від прийняття рішення. Це також унеможливлює визначити, що саме вирішило проблему, оскільки неможливо визначити, яка з п’яти пропозицій була ключовою.

Правило 20: Запитуйте, а не здогадувайтесь

If you need information you do not have, output:
MISSING: <exactly what you need>
and stop. Do not assume a plausible value and continue.

Чому це працює: Це, можливо, найцінніша рядок у всьому файлі. Майже кожен серйозний інцидент з агентом виникає через те, що він упевнено заповнює бракуючу деталь, замість того щоб зупинитися та запитати. Відмова коштує вам тридцяти секунд. Неправильне припущення, зроблене упевнено, коштує цілої половини дня, і ви зазвичай помічаєте це лише через кілька комітів.

Раніше: Моделі потрібна назва черги, яку ви ніколи не вказували. Вона за замовчуванням бере щось на кшталт default, створює інтеграцію, яка виглядає правильною, а завдання накопичуються у черзі, яку ніхто не споживає. Ви дізнаєтесь про це через кілька днів.

Після: Вона виводить MISSING: the queue name for the retry consumer. Ви надаєте відповідь протягом п’яти секунд, і отриманий код від самого початку є правильним.

Є простий спосіб перевірити, чи справді це правило діє: попросіть щось, що залежить від інформації, яку ви навмисно приховали. Якщо модель все одно відповідає, замість того щоб позначити цю прогалину, значить правило існує лише на папері.

Правило 21: Продовжуйте скорочувати, по одному правилу на місяць

Once a month, remove any rule you have not seen violated recently.

Чому це ефективно: Файли з правилами схильні до нескінченного розширення, адже додавання нового правила здається прогресом, тоді як його видалення — ризикованим кроком. Але якщо правило не використовувалося протягом останніх кількох місяців, це означає, що воно або більше не потрібне, або його ніколи насправді не дотримувалися. У будь-якому разі це відволікає увагу під час кожної взаємодії. Його видалення — це найекономніший спосіб покращити продуктивність.

П’ять правил, які були видалені

Видалення непотрібного було важливішим за все, що додавалося, тому ось п’ять записів, які раніше були у файлі з 400 рядками та відсутні у поточній версії з 61 рядком. Якщо щось із цього здається вам знайомим, ви, ймовірно, зможете видалити це сьогодні ввечері.

„Обміркуйте проблему крок за кроком перед тим, як писати код.“ Це вже є стандартною практикою. Сучасні версії Claude Code спочатку планують свій підхід до роботи з файлами без необхідності додаткових вказівок. Цей запис залишився зі старих звичок та лише займав місце.

„Стежте за проблемами продуктивності.“ Цей запис повністю провалює тест на перевірку — якої бази слід дотримуватися для обережності? Його замінили на два конкретні, перевірювані правила щодо доступу до баз даних, які дійсно виявляють реальні проблеми.

90-рядковий опис схеми бази даних. Це документація, а не правило. Вона має знаходитися у файлі з навичками, який завантажується під час виконання моделлю завдань, пов’язаних із базою даних, а не у файлі, який читається перед кожним завданням, навіть таким простим, як корекція CSS. Видалення цього розділу стало найбільшим скороченням обсягу.

„Ніколи не використовуйте any у TypeScript.“ Це твердження не було хибним, але воно було зайвим — інструмент перевірки вже забороняє його використання. Усе, що вже контролюється інструментальною частиною, не потребує місця у файлі правил. Якщо порушення можна виявити під час CI, нехай саме CI це робить.

«Додавайте корисні коментарі».» Кожна спроба сформулювати це призводила до коментарів, які просто повторювали рядок коду над ними. Рішенням було змінити підхід: не пояснювати, що робить код, а лише чому він це робить. Така версія є більш ефективною та на один рядок коротшою.

# CLAUDE.md

## Stack
Next.js 15 App Router, TypeScript strict, Postgres via Drizzle, Vitest.## Editing
Change the minimum number of lines needed.
Do not reformat, reorder, or rename anything you were not asked to change.
Match the style already in the file.## Scope
Work only on what was asked.
Mention unrelated problems, do not fix them.
Remove imports your change made unused. Nothing else.## Abstractions
Do not add an interface with one implementation.
Do not add a config option for a value that never changes.
Functions over 40 lines must be split.## Tests
Do not edit existing tests to make failing code pass.
If a test is wrong, say so and stop.## Dependencies
Do not add packages. Use what is in package.json.
To add one: name it, name what it replaces, stop, wait.## Error Handling
Handle errors that can actually occur here.
No try/catch around code that cannot throw.## Patterns
New routes follow src/api/users/route.ts.
Components do not fetch data. Fetch in the route, pass props down.
Database access goes through src/db/queries/. Never inline SQL.## Security
Never write a key, token, password, or connection string into a file.
Never commit .env or .env.*.
Reference environment variables by name only.## Destructive Actions
Stop and ask before: dropping a table, deleting a branch, force pushing,
rewriting history, deleting a file you did not create, running a
migration against anything not local.## Verification
Before reporting done, run:
  npm run typecheck && npm test -- --run
Paste the final line. If it fails, fix it. Do not report success.## Done
Done means: change made, typecheck passes, tests pass, and one sentence
saying what changed and why.## When Stuck
If you need information you do not have, output:
MISSING: <what you need>
and stop. Do not assume a value and continue.## Reporting
Name ONE thing to change. Not five options.## Persistence
Rules live here, not in chat. After compaction, re-read this file.

• Переписування файлів припинено. Правило хірургічної edycji існувало також у розширеній версії. Воно почало дотримуватися лише тоді, коли його більше не ховали близько рядка 213.
• Правило MISSING: стало активним. Тепер воно активується приблизно двічі на тиждень, зупиняючись для запиту, а не створюючи значення конфігурації. Раніше обидві ці ситуації призводили до беззвучного, неправильного результату.
• Довгі сеанси більше не „дрейфують“. Проблема з оновленням версії, разом із трьома схожими проблемами, зникла, коли правила були розміщені безпосередньо у файлі, а не розкидані по попередніх повідомленнях у чаті.
• Перевірки стали швидшими, просто тому, що різниці стали меншими. Ось весь механізм — нічого складнішого за це.

Тут немає чіткого порівняння «до» та «після», і його не створять заради гарної історії. Натомість існує файл, який потребує хвилини для читання, разом із поведінкою, яка дійсно відповідає його змісту.

Наступні кроки

1. Відкрийте ваш існуючий CLAUDE.md та порахуйте рядки.
2. Прочитайте його один раз, позначивши кожне правило, щодо якого ви не можете навести конкретний приклад порушення, якщо воно взагалі існує. Видаліть їх.
3. Перетворіть кожне «prefer» та «try to» на чітке «do not».
4. Замініть будь-які посилання на «наші конвенції» на реальний шлях до файлу.
5. Якщо у вас немає чогось на кшталт Правила 20, додайте його. Саме це правило виправдовує всю цю роботу.

Після цього залиште файл недоторканим протягом місяця. Коли повернетеся до нього, знайдіть ще щось для видалення.

Правила, які справді допомагають, мають спільні риси: вони короткі, однозначні та можливі до перевірки. Усе інше — це лише нотатка для себе, яку модель змушена перечитувати сотні разів на день без жодної користі.

Пов’язана література

• Порівняння агентів Frontier AI: Astra, Flash, Fable та Mythos — аналіз того, як останні версії моделей GPT, Gemini та Claude виконують реальні завдання, пов’язані з агентами, такі як програмування, перегляд інформації та використання інструментів, а не лише тестування на стандартних завданнях.
• Вибір фреймворку для агентів AI на Python у 2026 році: практичне порівняння — порівнює п’ять фреймворків для агентів AI на Python за способом роботи з невдачами та складністю, допомагаючи читачам підібрати відповідний інструмент для своєї робочої процедури.