Глобальний CLAUDE.md: 1% зусиль, 80% результату

Я розкажу про десяток своїх знахідок для глобального CLAUDE.md файлу і поясню, як вони працюють на практиці.

Поговоримо про глобальний CLAUDE.md, уже можна створювати AGENTS.md, але я буду казати CLAUDE.md. Взагалі глобальний CLAUDE.md, для тих хто не знає, це файл з інструкціями, який знаходиться в файлах налаштування в домашній директорії ~/.claude/CLAUDE.md. І додається на початку кожної сесії кожному агенту. Тому кожен рядок тут на вагу золота - він додається щоразу, його отримують усі агенти, і основний і фонові, в якому б проекті, тобто директорії, вони не працювали. Тобто потрібно тримати тут лише дуже важливі записи тому що вони щоразу коштують нам токенів.

Be brief

Be brief.

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

Перед тим, як його додати я провів deepresearch засобів скорочення виводу і ретельно переглянув усіх кандидатів. Be brief для мене однозначно виграв. За незалежними тестами він скорочує вивід на третину і за моїми спостереженнями звітів про баги я можу це підтвердити. Ще мені подобається що в той час коли в середньому вивід зменшується на 1/3, то в медіані лише на 1/4. Найімовірніше це тому, що текст скорочується коли дійсно є що скоротити, а не завжди на однакову величину, і це прекрасно.

Взагалі Be brief схожий на caveman. Тільки з людським обличчям. Тому що по-перше, текст не спускається до мови печерної людини. А по-друге, не потребує встановлення сторонніх MCP, хуків, плагінів які намагаються підміняти інпут для моделі.

Є і трохи кращі альтернативи, але по-перше, вони встановлюються ззовні і маніпулюють роботою Claude Code, а по-друге, не дають значного ефекту у порівнянні з Be brief.

Пиши мені українською

Write me in Ukrainian. Keep technical terms in English. Do not use transliteration. Other in English only - all code, comments, docs, examples, commits, configs, errors, tests.

Незважаючи на те, що з be brief клод пише коротше, все ж доводиться читати багато текстів. А українською я можу читати швидко, по діагоналі, знаходити потрібний текст просто листаючи. Крім того він же не англійською спілкується, а claudish, як це називається в інтернеті. Як щось напише то це важко зрозуміти. Українською вочевидь простіше. Хоча зараз fable і opus 5.5 рідко до claudish спускаються все ж це трапляється і українською зрозуміти простіше.

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

Не пояснюй свою роботу

Don’t narrate your work. Handle it and report when done.

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

Використовуй традиційний формат повідомлень комітів

Use conventional git commit format: <type>(<optional scope>): <subject> where type = feat|fix|docs|style|refactor|test|chore|perf. Subject: 50 chars max. Prefer one-line commit.

Формат повідомлення в коміті задаю прямо тут. Завжди. Без ніяких скілів з кілобайтами описів як правильно комітити. Тому що цього короткого промпту достатньо. І цей промпт завжди завантажений.

Я пошукав що люди пишуть в інструкціях повідомлень комітів і там гори тексту, роблять це окремими скілами, не розумію для чого. Не потрібно писати що "спочатку перевір git status. Не коміть зайві файли." Клод це знає, і прекрасно сам робить, навіть занадто, як на мене. Не потрібно розказувати "коміть атомарні зміни. Пиши в імперативному стилі не більше 72 символів на рядок." Лише задаємо що це традиційний формат і він вже знає про що мова. Цього достатньо. Запевняю. І цей рядок займає контексту менше ніж не завантажений скіл і працює, що ще потрібно.

Будь грубим і критичним

Correct me when I’m wrong and suggest better approaches. Be blunt, or I may miss the criticism.

Я вже не памʼятаю в кого взяв ідею писати клоду щоб він був критичним. В скілі Андрія Карпати є схожа ідея. У будь-якому разі, авторитетні джерела часто рекомендують додавати AI можливість критики наших ідей. Цей рядок вирішує кілька проблем. По-перше, він зменшує підлабузництво AI. По-друге, змушує його глянути на альтернативні рішення і пропонувати їх нам. І по-третє, це бути прямим коли критикує. Тому що важко вловити цей американський стиль що "ідея гарна, і буде працювати, але тільки тоді коли косинус більше одиниці і варто над цим ще попрацювати." Це взагалі важко помітити коли бігло читаєш трактати клода. "Ідея погана - працювати не буде." Інша ж справа. Правда я не можу сказати що цей промпт точно працює. Це рідкісні випадки щоб я помилявся.

Віддавай перевагу коду, що самодокументується, а не коментарям

Prefer self-documenting code over comments. Before adding a comment, first try to make the intent, deviation, or caveat obvious through naming, structure, or the type system. Comment only when that isn’t practical. Keep a comment to 1-2 lines saying only what the code cannot: an invariant, an outside constraint, a trap the next edit would hit. Not the name, the signature, a disaster narration, rejected alternatives, a rationale that lives elsewhere (point at it), linter meta-commentary, or caps for emphasis.

Оце просто must have! Я не заміряв, але впевнений що працює. 30% коментарів відносно коду я уже не бачу. Насправді все ще потрібно зменшувати коментарі в коді, одного цього промпту явно недостатньо. Тим не менш дуже корисно тримати в його контексті. Хай і такий детальний, щоб він частіше до нього звертався

Тримай в CLAUDE.md тільки те що потрібно для кожної задачі в проекті

CLAUDE.md is loaded every session, so keep only what applies to any task (summary, commands, architecture, index); per-subsystem rationale goes in comments or `docs/`, pointed at from the code.

Знаєте, CLAUDE.md проекту сильно розростається і він постійно туди додає все більше і більше непотрібних деталей. І він же щоразу завантажується. А з цим рядком claude прекрасно перестає писати усе підряд, іноді навіть пропонує видалити зайве з CLAUDE.md. В директорію docs пише тільки тоді коли вона реально присутня у проекті, тому не заважає. І зазвичай все тримає в коментарях до коду. І тримає коротко, як ми уже оптимізували раніше.

YAGNI

Don't build it if it isn't needed (YAGNI). Avoid extra abstractions, premature generalization, indirection and scope creep.

Це я взяв з плагіну ponytail - досить популярний плагін, з гарними відгуками що змушує клод робити мінімалістичні правки і не робити те що його не просили. YAGNI це дуже урізаний варіант плагіну. І на мій погляд цього не достатньо. Плагін не даремно має купу хуків на кожному кроці і інжектить йому YAGNI, YAGNI, YAGNI на кожному кроці. Я вірю розробникам і відгукам що з плагіном це б працювало краще. Але я не люблю хуки, оверинжиніринг і неявну роботу плагінів. Тому YAGNI, просто додай промпт один раз. Але якщо вам хочеться ультимативно то варто спробувати і плагін ponytail.

Використовуй rg fd tree

Use rg, fd, tree; not grep or find.

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

Пісочниця

Start background processes with run_in_background, stop with TaskStop. Never `nohup`/`&` (loses the task ID) or `kill` (sandbox blocks signals).

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

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

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

Ліки для Superpowers

`docs/superpowers/**` contains temporary working plans, not project specs. Use and edit them during planning and implementation, but never reference them from the project or commit them. After implementation, treat them as historical artifacts only.

Ви використовуєте скіли superpowers? Якщо ні - вимикайте відео і йдіть встановлювати через /plugin. Тому що це краще ніж те що я вам оце розказую. Це для тих хто хоче давати клоду великі задачі, щоб він сам їх дробив, і виконував по частинам. Насправді я уже не використовую їх в такому вигляді, а майже повністю переробив, тим не менш дуже гарні скіли для довгих тасок, поставив і він працює кілька годин.

Що ж робить сам промпт? По-перше, сам промпт вочевидь не потрібен без плагіна. По-друге, він дає зрозуміти що плани і специфікації, які написані з плагіном це специфікації станом на момент реалізації. А не специфікації на проект. Тому що інакше він посилається на них, в розмові, в коді, в CLAUDE.md. Коли бачить, що щось не відповідає специфікації - дає про це знати "ай-ай-ай це порушує специфікацію", навіть якщо ця зміна була після створення фічі зі специфікацією. З цим промптом він дивиться на специфікації superpowers тільки для перегляду історії.

Вишенька на торті. Беклог

If you discover unrelated problems, do not fix them opportunistically. Record them in docs/backlog/<subsystem>_<problem>.md. After making such an entry, tell me what you added to the backlog.

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

Завдяки цьому промпту ми отримуємо неймовірну кількість переваг.

• Перше це менше нерелевантних змін.
• Друге це зменшення забивання контексту під поточну задачу, а значить задача робиться швидше, витрачає менше токенів і буде зроблена якісніше.
• Третє - це простіше ревʼювити.
• Четверте - у нас є беклог з проблемами, безкоштовне ревʼю.
• Пʼяте - після закінчення поточної таски, чи на ніч можна попросити глянути беклог і самостійно виправити тривіальні проблеми, виправлення яких нічого не ламають.
• Шосте - кінець тижня, а токенів ще повно? Попросіть запустити субагентів, кожен з яких буде фіксити свою складну проблему в своєму git worktree. Можливо щось і заберете собі, а може і ні, все одно не шкода, токени ж згорять :)

Одні переваги. Ледь пальців на руці вистачило рахувати.

Ще раз повторю - це найважливіший промпт з усього списку. Записуйте, дякувати будете пізніше.

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

Changelog

After changes, update the changelog. Keep entries short, telegraphic, user-facing; omit details and explanations.

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