--- title: claude-code-best-practices desc: Що реально впливає на якість роботи Claude Code: CLAUDE.md, контекст, plan mode, сабагенти, хуки, MCP, дозволи, verification loop. Плюс огляд патернів caveman і ponytail. locked: true order: 4 --- # Claude Code: практики, які дають різницю Не переказ релізноутів. Список того, що змінює результат, згруповане за тим, де саме воно ламається. --- ## CLAUDE.md Стартувати з `/init` — він підтягне наявні `.cursor/rules`, `.cursorrules`, `.github/copilot-instructions.md`. **Ліміт — 200 рядків.** Далі модель починає семплити файл, а не читати, і справжні правила губляться серед вати. Тест на кожен рядок: *чи зробить модель помилку, якщо цей рядок прибрати?* Якщо ні — прибрати. | Класти | Не класти | |---|---| | bash-команди, які неможливо вгадати | те, що видно з коду | | стильові правила, які відрізняються від дефолтних | стандартні конвенції мови | | який тест-раннер і як його запускати | API-документацію (лінк замість неї) | | етикет репозиторію, квірки середовища | опис кожного файлу | | архітектурні рішення й граблі | те, що швидко змінюється | Інші деталі, які економлять години: - Файли вантажаться широкий→вузький і **конкатенуються**: managed policy → `~/.claude/CLAUDE.md` → `./CLAUDE.md` → `./CLAUDE.local.md`. Підкаталожні — ліниво. - `AGENTS.md` **не читається**. Треба `CLAUDE.md` із рядком `@AGENTS.md`. - Імпорти `@path/to/file` (до 4 хопів) організовують, але **не економлять контекст** — усе вантажиться на старті. - Великі шматки → `.claude/rules/*.md` з `paths:` у фронтметрі: вантажаться тільки коли читається відповідний файл. - Блокові HTML-коментарі вирізаються перед інжектом — безкоштовне місце для нотаток собі. - Перевірка, що воно взагалі завантажилось: `/context` → «Memory files». Дебаг — хук `InstructionsLoaded`. `/doctor` запропонує, що зрізати. - CLAUDE.md — це контекст, **не примус**. Гарантія — тільки `PreToolUse` хук або `permissions.deny`. --- ## Контекст - `/clear` між незв'язаними задачами. Після **двох невдалих виправлень поспіль** — не продовжувати діалог, а `/clear` і переписати промпт із нуля. Третя спроба в тому ж контексті майже ніколи не працює. - `/compact <фокус>` руками перед новою великою задачею краще, ніж автокомпакція, яка вгадує сама. - Компакцію **переживають**: кореневий CLAUDE.md, нескоуплені правила, авто-пам'ять. **Гинуть**: правила зі `paths:`, вкладені CLAUDE.md, лістинг скілів. - Тіла викликаних скілів переінжектяться, але з лімітом 5k токенів на скіл і 25k загалом, обрізка **згори** — тому найважливіше в `SKILL.md` має стояти першим. - `/btw` — питання збоку в оверлеї, який не потрапляє в історію. - `Esc+Esc` / `/rewind` уміє часткову компакцію («summarize from here»). Чекпоінти **не покривають** змін, зроблених через Bash. --- ## Plan mode, effort, thinking - Plan mode (`Shift+Tab`, `/plan`, `--permission-mode plan`) — для багатофайлової чи незнайомої роботи. Якщо дифф описується одним реченням — це зайвий ритуал. - `Ctrl+G` відкриє запропонований план у редакторі: правити план дешевше, ніж правити реалізацію. - «think hard» / «think more» **більше не ключові слова**. Лишився `ultrathink` як разова ескалація, решта — через `/effort` (`low|medium|high|xhigh|max|ultracode`). - `effort:` виставляється поскілово і посабагентно у фронтметрі. - Схема під велику фічу: інтерв'ю через `AskUserQuestion` → `SPEC.md` → **свіжа сесія** на реалізацію. Планування і виконання в одному контексті труять одне одного. --- ## Сабагенти - Делегувати те, що породжує багато виводу, до якого потім не повертаються: дослідження кодової бази, розкопки логів. Назад приїде тільки підсумок. - **Не** делегувати ітеративну роботу, багатофазну роботу зі спільним контекстом і дрібні правки, де важлива затримка. - Не-fork сабагент стартує **холодним**: без історії, без авто-пам'яті, без output style. Всі обмеження треба переказати в промпті. - Вбудовані `Explore` і `Plan` взагалі не читають CLAUDE.md і git status. `Explore` можна перевизначити своїм із `model: haiku` — дешевше. - Скоупити через фронтметр: `tools:`, `disallowedTools:`, `model:`, `isolation: worktree`, `memory:`, `skills:`. - Adversarial review: `/code-review` або «сабагент перевіряє дифф проти PLAN.md; репортити прогалини, не стиль». Без цієї приписки повернеться over-engineering. --- ## Хуки Детерміновані shell-команди на подіях життєвого циклу. Для того, що **мусить** статися щоразу: формат після редагування, блокування запису в `migrations/`, реінжект контексту після компакції. - **Exit 2 блокує дію**, а stderr їде моделі як фідбек. Просто stdout при exit 0 йде в дебаг-лог, не в транскрипт. - Найцінніші події: `PreToolUse`, `PostToolUse`, `Stop` (закрити хід тільки якщо перевірка пройшла — перебивається після 8 блокувань поспіль), `SessionStart`, `PostCompact`, `InstructionsLoaded`, `FileChanged`, `WorktreeCreate`. - Хуки простіше попросити написати саму модель. Дивитись через `/hooks`. --- ## Слеш-команди та скіли - **Кастомні слеш-команди тепер це скіли** — `.claude/skills//SKILL.md`, не `.claude/commands/`. Аргументи через `$ARGUMENTS`, `$1`… - `disable-model-invocation: true` тримає скіл повністю поза контекстом, поки його не викличуть руками. Для всього, що має сайд-ефекти — обов'язково. - Доменні знання «іноді потрібні» переносити з CLAUDE.md у скіли: у контексті лишається лише однорядковий опис. --- ## MCP - **Tool search увімкнений за замовчуванням**: спочатку вантажаться тільки імена інструментів, схеми — на вимогу. Додавання сервера більше не рве контекст. - Крутилки: `ENABLE_TOOL_SEARCH=auto` / `auto:5` / `false`. - Де є CLI (`gh`, `aws`, `sentry-cli`) — брати CLI, а не MCP. Найдешевше по контексту. - Вивід MCP попереджає після 10k токенів і ріжеться на 25k (`MAX_MCP_OUTPUT_TOKENS`). `/mcp` показує кількість інструментів по серверах. - Скоупи: `local` (дефолт) > `project` (`.mcp.json`, комітиться) > `user`. --- ## Дозволи, headless, worktrees - Режими: `default`, `acceptEdits`, `plan`, `auto` (через класифікатор), `dontAsk` (лок для CI), `bypassPermissions` (**тільки** контейнер/VM). - `auto` при вході скидає широкі allow-правила (`Bash(*)`, вайлдкард-інтерпретатори, `Agent`). Вузькі на кшталт `Bash(npm test)` виживають. - Обмеження, сказані в чаті («не пушити»), класифікатор поважає, але вони **гинуть при компакції**. Тверда гарантія — тільки `deny`-правило. - Захищені шляхи (`.git`, `.claude`, shell rc, `.mcp.json`) не автоапрувляться ніколи поза bypass-режимом, і `permissions.allow` цього не перебиває. - Headless: `claude -p` + `--allowedTools`, `--output-format json|stream-json`, `--json-schema`, `--append-system-prompt`, `--continue`/`--resume`. - `--bare` у CI: пропускає дискавері хуків, скілів, плагінів, MCP, пам'яті й CLAUDE.md — заради відтворюваності. - Fan-out — цикл `claude -p` по списку файлів. Промпт спершу обкатати на 2–3 файлах. - Worktrees: `claude --worktree ` або `#1234` для PR; `.claude/worktrees/` у gitignore; `.worktreeinclude` щоб затягнути `.env`. Прогони через `-p` **не прибирають** за собою worktree. --- ## Verification loop — те, без чого решта не має сенсу Модель мусить мати команду, яка скаже «зроблено правильно» без участі людини: тести, exit code білда, лінтер, дифф фікстури, порівняння скріншотів. **Без цього роль верифікатора виконує людина** — і саме тут згорає весь виграш у швидкості. Способи прив'язати: - прямо в промпті: «приклади кейсів: …; після реалізації прогнати тести» - як умову `/goal`, яку евалюатор переперевіряє щоходу - як `Stop`-хук Скріншот-цикл: кинути макет → «зроби, зніми скріншот результату, порівняй, перелічи відмінності, виправ». TDD-розкладка: одна сесія пише тести, **друга, зі свіжим контекстом**, пише код під них. Той самий розкол працює для пари Writer/Reviewer. І головне: вимагати **доказ** (команда + вивід), а не заяву «готово, все працює». --- ## Антипатерни, за які платять усі - Сесія-смітник: п'ять непов'язаних задач в одному контексті. - Спіраль виправлень: третій, четвертий, п'ятий «ні, не так» у тому самому контексті. - Перероздутий CLAUDE.md, у якому справжні правила потонули. - Розрив довіри: «сказав що готово» без прогнаного тесту. - Нескоуплене «розберись з X», після якого прочитано пів репозиторію. - **Skill sprawl** — бібліотека на 40–50 скілів, де топ-5 дають більшість викликів. Тримати в межах ~20 і чистити щокварталу. - Хуки на кожну подію → сповіщення мутять і не читають. Лишити `Stop`/`SubagentStop`. - Дрейф allowlist'а: правила, додані рік тому під разову задачу. - Сабагенти й скіли без власника й ревʼю. `.claude/agents/` — це прод, а не чернетки. - Протухлий CLAUDE.md піврічної давності, який тепер активно бреше моделі. - Постмортем у стилі «модель тупить» замість розбору дозволів, скоупу й контролю. --- ## Чекліст на щодня - [ ] CLAUDE.md коротший за 200 рядків і кожен рядок заслуговує там бути? - [ ] Є runnable-перевірка, яку модель може прогнати сама? - [ ] Нова задача → новий контекст (`/clear`), а не продовження старого? - [ ] Дві невдалі спроби → переписати промпт, а не третя спроба? - [ ] Багатофайлова робота почалась із plan mode? - [ ] Сайд-ефектні скіли позначені `disable-model-invocation: true`? - [ ] Тверді заборони — у `permissions.deny`, а не в тексті чату? - [ ] Замість MCP-сервера можна взяти CLI? {: .task }
P.S. — caveman і ponytail
Два ком'юніті-скіли, які постійно згадують поруч, хоча вони про різне. Обидва — не від Anthropic. **caveman** — «why use many token when few token do trick». Наказує агенту викинути з відповіді артиклі, прийменники, преамбули й метакоментарі, лишивши телеграфні уламки; код, команди й помилки не чіпаються. Стиснення **вихідних** токенів, на вхід і на reasoning не впливає взагалі. Народилось анонімним постом на r/ClaudeAI (~10K апвоутів, весна 2026), потім затверділо в інсталябельні скіли. Заявлено −65 % виводу; незалежний бенчмарк JetBrains поміряв **−8.5 %** по сесії цілком — бо основна маса токенів у агентній сесії це не проза моделі, а вивід інструментів. - [github.com/juliusbrussee/caveman](https://github.com/juliusbrussee/caveman) — режими lite/normal/ultra/wenyan, `/caveman` тоглом - [blog.jetbrains.com — виміряні цифри](https://blog.jetbrains.com/ai/2026/07/speak-to-ai-agents-like-cavemen-tosave-tokens/) - [decrypt.co](https://decrypt.co/363440/devs-claude-talk-like-caveman-cut-costs-work-better) · [pcworld.com](https://www.pcworld.com/article/3115406/claude-users-are-teaching-it-to-talk-like-a-caveman-heres-why.html) **ponytail** — скіл Dietrich Gebert, який змушує агента поводитись як «найлінивіший сеньйор у кімнаті»: той, з хвостиком і овальними окулярами, що працює тут довше за систему контролю версій. Перед написанням коду проганяє драбину рішень: чи це взагалі має існувати (YAGNI) → чи цього вже нема в кодовій базі → чи це не робить stdlib/платформа → чи не можна одним рядком. Лікує over-engineering, не багатослівність. У репо заявлено 293 → 47 рядків і ~4× швидше на п'яти задачах. - [github.com/DietrichGebert/ponytail](https://github.com/DietrichGebert/ponytail) (MIT) - [бенчмарк JetBrains](https://blog.jetbrains.com/ai/2026/07/ponytail-skill-claude-tested/) · [скептичний розбір](https://blog.stackademic.com/does-the-ponytail-skill-actually-improve-claude-code-or-just-cut-its-line-count-9e2f31a3b32a) Коротко: **caveman стискає прозу, ponytail стискає код**. Із двох другий важливіший — рядок, який не написано, не треба ні читати, ні тестувати, ні підтримувати.
P.P.S. — економіка оптимізації
```jd ЗАЯВЛЕНО −65% ТОКЕНІВ ВИМІРЯНО −8.5% ┌──────────────────┐ ┌──────────────────┐ │ ████████████████ │ │ ██ │ └──────────────────┘ └──────────────────┘ ▲ ▲ │ │ пресреліз той самий скіл, але з секундоміром ── куди пішли токени насправді ────────────────── вивід інструментів ██████████████████████ 71% вміст файлів ████████ 19% системний промпт ███ 7% проза моделі █ 3% ← ось тут ми героїчно зрізали дві третини ```
Класика: оптимізували 3 % на 65 %, отримали 2 % і статтю в Decrypt.