Перевод с разбором · для Вани

Claude Code: best practices от Anthropic

Это официальный документ Anthropic про то, как правильно работать с Claude Code. Он не про язык программирования и не про конкретный стек — он про дисциплину работы с агентом, который читает ваши файлы, запускает команды, правит код и сам решает, что делать дальше. Для вас это самое главное: Claude Code в вашем лестничном проекте — это не «умный автокомплит», а исполнитель, которому надо давать понятные задачи и оставлять способ проверить результат.

Anthropic с самого начала задаёт рамку: «Claude Code is an agentic coding environment. Unlike a chatbot that answers questions and waits, Claude Code can read your files, run commands, make changes, and autonomously work through problems while you watch, redirect, or step away entirely». Перевод: «Claude Code — это агентная среда для кода. В отличие от чат-бота, который отвечает на вопрос и ждёт, Claude Code может читать ваши файлы, запускать команды, вносить изменения и сам прорабатывать задачу, пока вы смотрите, направляете или вообще отошли». Поэтому вы перестаёте писать код сами и просить ревью — вы описываете, чего хотите, а Claude исследует, планирует и реализует.

Главная сквозная идея статьи

Anthropic пишет: «Most best practices are based on one constraint: Claude's context window fills up fast, and performance degrades as it fills». Контекстное окно — это вся история разговора плюс все файлы, которые Claude прочитал, плюс вывод всех команд. Оно ограниченное, и качество модели падает, когда оно заполняется. Почти все советы ниже — про то, как не дать контексту мусориться и забиваться лишним.

Дайте Claude способ проверить свою работу

Anthropic называет это «the single highest-leverage thing you can do» — самое выгодное вложение усилий. Идея проста: если у Claude нет способа проверить, что он сделал правильно, единственным проверяющим становитесь вы. И каждая ошибка требует вашего внимания.

Что значит «способ проверить» в вашем случае:

• тесты, которые можно запустить — у вас уже есть IntegrationTestBase и JwtFilterTest, этого достаточно, чтобы Claude после правки в OrderService мог сам прогнать и убедиться, что ничего не сломалось;
• линтер или компилятор: «исправь и убедись, что ./gradlew build проходит» — это уже способ проверки;
• скриншоты или ожидаемый вывод: «вот скриншот, как должна выглядеть форма заказа — реализуй и сравни»;
• конкретные тест-кейсы: «функция расчёта наценки на markupMaterialsPct должна на входе 1000 и 15% дать 1150».

Anthropic в табличке прямо противопоставляет плохие и хорошие формулировки. Плохо: «implement a function that validates email addresses». Хорошо: «write a validateEmail function. example test cases: user@example.com is true, invalid is false, user@.com is false. run the tests after implementing». Разница не в длине, а в том, что во втором варианте у Claude есть автоматический способ понять, что он закончил.

И отдельный пункт, который вам важен: «Address root causes, not symptoms» — «лечите причину, а не симптом». Если сборка падает, задача формулируется как «вот ошибка, найди причину и почини», а не «сделай так, чтобы сборка проходила». Иначе Claude обернёт проблемное место в try/catch и пойдёт дальше.

Сначала исследовать, потом планировать, потом писать код

Это вторая большая идея. Anthropic называет её прямо: «Letting Claude jump straight to coding can produce code that solves the wrong problem». Если сразу прыгнуть в код, можно с большим усердием решить не ту задачу.

Рекомендуемый рабочий процесс — четыре фазы. Они опираются на plan mode — это специальный режим Claude Code, не slash-команда. В plan mode Claude читает файлы и отвечает на вопросы, но не вносит изменений.

1. Исследование (в plan mode)

read /src/auth and understand how we handle sessions and login.
also look at how we manage environment variables for secrets.

В вашем случае это звучало бы как: «прочитай OrderService, OrderCalculationService, OrderRepository и расскажи, как сейчас устроен расчёт стоимости заказа, где берутся проценты наценки и где хранится материал».

2. План (в plan mode)

I want to add Google OAuth. What files need to change?
What's the session flow? Create a plan.

Anthropic подсказывает: «Press Ctrl+G to open the plan in your text editor for direct editing before Claude proceeds» — план можно открыть в редакторе и поправить руками, прежде чем Claude перейдёт к исполнению.

3. Реализация (нормальный режим)

implement the OAuth flow from your plan. write tests for the
callback handler, run the test suite and fix any failures.

4. Коммит

commit with a descriptive message and open a PR

Когда plan mode не нужен

«Plan Mode is useful, but also adds overhead. For tasks where the scope is clear and the fix is small (like fixing a typo, adding a log line, or renaming a variable) ask Claude to do it directly.» Если правка умещается в одно предложение «измени X на Y в файле Z» — план только мешает. Plan mode полезен, когда вы не уверены в подходе, изменение задевает несколько файлов или вы плохо знаете тот код, который трогаете.

Давайте конкретный контекст в промптах

«The more precise your instructions, the fewer corrections you'll need» — чем точнее инструкция, тем меньше поправок понадобится. Claude умеет догадываться, но мысли читать не умеет.

Четыре приёма из таблицы Anthropic, переведённые на ваш стек:

• Ограничьте задачу. Плохо: «добавь тесты для MaterialService». Хорошо: «напиши тест для MaterialService на случай, когда у материала пустой склад. Без моков, через IntegrationTestBase».
• Указывайте источник. Плохо: «почему у OrderRepository такой странный API?». Хорошо: «посмотри git-историю OrderRepository и опиши, как этот API сложился».
• Ссылайтесь на существующие паттерны. Плохо: «добавь экран отчёта по прибыли». Хорошо: «посмотри, как сделан экран списка заказов — там типовой паттерн с React-компонентом и Ktor-эндпоинтом. Сделай по такому же шаблону экран отчёта по прибыли с фильтром по периоду. Никаких новых библиотек, бери только то, что уже в проекте».
• Описывайте симптом. Плохо: «почини баг с расчётом». Хорошо: «при заказе на 1000 ₽ с markupMaterialsPct = 15 получается 1149.99 вместо 1150. Похоже на округление в OrderCalculationService. Напиши падающий тест, воспроизводящий проблему, потом почини».

Подавайте «жирный» контекст

Anthropic перечисляет несколько способов:

• Подтянуть файл через @. Вместо «посмотри в районе OrderService» — пишете @src/main/kotlin/.../OrderService.kt, и Claude прочитает файл целиком, прежде чем отвечать.
• Вставить картинку. Скриншот формы, макет от дизайнера, фотография путаницы в Excel — всё можно перетащить или вставить в промпт.
• Дать URL — на документацию, API-референсы. Через /permissions можно занести часто используемые домены в белый список.
• Подать данные через пайп: cat error.log | claude — содержимое файла уйдёт Claude'у напрямую.
• Дать Claude самому собрать контекст — попросить запускать Bash, читать файлы, ходить по MCP-инструментам.

Настройте окружение

Напишите хороший CLAUDE.md

Это самый важный для вас раздел. CLAUDE.md — обычный markdown-файл, который Claude автоматически читает в начале каждой сессии. Туда кладутся вещи, которые Claude не может вытащить из самого кода: команды сборки, стиль, рабочие процессы, особенности проекта.

Anthropic советует: «Run /init to generate a starter CLAUDE.md file based on your current project structure, then refine over time». Команда /init сама пробежит по проекту, найдёт build-систему и тесты, и сделает заготовку. Дальше дорабатываете руками.

Пример из оригинала:

# Code style
- Use ES modules (import/export) syntax, not CommonJS (require)
- Destructure imports when possible (eg. import { foo } from 'bar')

# Workflow
- Be sure to typecheck when you're done making a series of code changes
- Prefer running single tests, and not the whole test suite, for performance

А вот как такой файл может выглядеть в вашем лестничном проекте:

# Стек
- Backend: Kotlin + Ktor + JDBI + PostgreSQL
- Frontend: React (внутри /web)
- Тесты: JUnit5 через IntegrationTestBase (поднимает testcontainers)

# Команды
- Сборка: ./gradlew build
- Один тест: ./gradlew test --tests "JwtFilterTest"
- Запуск локально: ./gradlew run
- Миграции: ./gradlew flywayMigrate

# Стиль
- Сервисы называем XxxService (OrderService, MaterialService).
  Бизнес-расчёты — в XxxCalculationService, не в репозитории.
- Репозитории — XxxRepository, только SQL и маппинг.
- Деньги — BigDecimal, не Double. Округление — HALF_UP, 2 знака.
- Проценты в БД храним как доли (0.15), в API отдаём как
  markupMaterialsPct = 15.

# Workflow
- ВАЖНО: после серии правок ВСЕГДА запускать ./gradlew build
- Тесты на бизнес-логику обязательны, через IntegrationTestBase
- Миграции пишем в src/main/resources/db/migration, имя V{N}__name.sql
- В PR — что меняли в БД, что в API

# Чего не делать
- Не добавлять новые библиотеки без согласования
- Не менять подпись публичных Ktor-роутов без обновления фронта

Anthropic несколько раз настаивает на одном и том же: «Keep it concise. For each line, ask: Would removing this cause Claude to make mistakes? If not, cut it. Bloated CLAUDE.md files cause Claude to ignore your actual instructions!». Для каждой строки задавайте вопрос: «если её убрать, Claude начнёт ошибаться?». Если нет — убирайте. Раздутые CLAUDE.md заставляют Claude игнорировать важные правила, потому что они теряются в шуме.

Полезная таблица — что класть и что не класть:

Класть	Не класть
Bash-команды, которые Claude не угадает	То, что Claude и так поймёт из кода
Правила стиля, отличные от стандартных	Стандартные конвенции языка
Как запускать тесты, какой раннер	Подробный API-референс (лучше ссылку)
Соглашения о PR и ветках	То, что часто меняется
Архитектурные решения именно вашего проекта	Длинные объяснения и туториалы
Особенности окружения (нужные env-переменные)	Описание каждого файла кодбазы
Грабли и неочевидное поведение	Очевидное вроде «пиши чистый код»

Anthropic добавляет важный диагностический приём: «If Claude keeps doing something you don't want despite having a rule against it, the file is probably too long and the rule is getting lost». Если Claude упорно делает то, что у вас в CLAUDE.md прямо запрещено — значит, файл слишком длинный, и правило тонет в шуме. Лечится не добавлением новых «ВАЖНО», а вычищением мусора.

Ещё совет: «You can tune instructions by adding emphasis (e.g., "IMPORTANT" or "YOU MUST") to improve adherence». Капсом и словами «ВАЖНО», «ОБЯЗАТЕЛЬНО» можно подчёркивать критичные правила — модель действительно лучше их соблюдает. Только не злоупотребляйте, иначе перестанет работать.

CLAUDE.md можно подключать друг к другу через @path/to/import:

See @README.md for project overview and @package.json for available npm commands.

# Additional Instructions
- Git workflow: @docs/git-instructions.md
- Personal overrides: @~/.claude/my-project-instructions.md

Где CLAUDE.md можно класть:

• ~/.claude/CLAUDE.md — личный, действует во всех ваших проектах;
• ./CLAUDE.md в корне проекта — коммитится в git, делится с командой;
• ./CLAUDE.local.md — личные заметки по проекту, добавляйте в .gitignore;
• В родительских папках — полезно для монорепо;
• В подпапках — например, web/CLAUDE.md с правилами по фронту, который Claude подтянет, только когда работает с файлами в этой папке.

Настройте permissions

По умолчанию Claude Code спрашивает разрешения почти на всё, что меняет систему. Anthropic честно признаёт: «After the tenth approval you're not really reviewing anymore, you're just clicking through». После десятого «разрешить» вы уже ничего не проверяете, а просто кликаете. Это опасно: вы перестаёте быть фильтром.

Три способа уменьшить поток вопросов:

• Auto mode — отдельная модель-классификатор смотрит на команды и блокирует только то, что выглядит рискованно (незнакомая инфраструктура, выход за рамки задачи, действия из чужого ввода). Подходит, когда вы доверяете направлению задачи.
• Allowlist через /permissions — разрешить конкретные команды: ./gradlew build, ./gradlew test, git commit, flywayMigrate.
• Sandboxing — изоляция на уровне ОС: Claude может работать свободнее в заданных границах, но не выйдет за них.

Используйте CLI-утилиты

«CLI tools are the most context-efficient way to interact with external services». CLI — самый дешёвый по контексту способ общаться с внешними системами. Anthropic советует ставить gh (GitHub CLI), aws, gcloud — Claude умеет ими пользоваться. Без gh Claude всё равно сходит в API GitHub, но без авторизации упрётся в rate-limit.

Для вашего проекта это значит: установить gh, держать под рукой psql для проверки запросов к Postgres, держать ./gradlew в проекте — Claude разберётся с остальным.

Хуки

Anthropic чётко разделяет: «Unlike CLAUDE.md instructions which are advisory, hooks are deterministic and guarantee the action happens». Инструкции в CLAUDE.md — рекомендательные. Хуки — детерминированные: они срабатывают всегда. Хуки настраиваются в .claude/settings.json и запускают скрипты в определённые моменты — например, после каждой правки файла.

Для вас осмысленный сценарий: хук, который после каждого Edit в *.kt-файле запускает ./gradlew ktlintCheck, или хук, который блокирует запись в src/main/resources/db/migration/ без явного подтверждения (миграции — не та папка, где должны случайно появляться файлы).

Subagents

Subagent (английский термин) — это «специализированный помощник», которого Claude может позвать на изолированную задачу. У него собственное контекстное окно и собственный набор разрешённых инструментов. Anthropic объясняет ценность так: «They're useful for tasks that read many files or need specialized focus without cluttering your main conversation».

Если попросить subagent'а «проверь весь backend на потенциальные SQL-инъекции», он прочитает кучу файлов в своём окне, а в основной разговор вернёт только короткий отчёт. Ваш основной контекст не забивается. Subagents задаются файлами в .claude/agents/.

Общайтесь с Claude эффективно

Задавайте вопросы по кодбазе

«Ask Claude questions you'd ask a senior engineer» — задавайте Claude те же вопросы, которые задали бы старшему коллеге. Это реально работает в незнакомой кодбазе.

В ваших терминах:

• «Как у нас устроен расчёт прибыли по заказу?»
• «Где я добавляю новый Ktor-эндпоинт и как подключаю его к JwtFilter?»
• «Какие edge cases обрабатывает OrderCalculationService?»
• «Почему здесь зовут save вместо upsert на 88-й строке?»

Никакой особой магии в промпте не нужно — спрашивайте напрямую. Это, кстати, отличный способ онбординга: вместо того, чтобы час дёргать живого человека, спросите Claude.

Пусть Claude интервьюирует вас

Очень мощный приём для крупных фич. Anthropic предлагает шаблон:

I want to build [brief description]. Interview me in detail using the AskUserQuestion tool.

Ask about technical implementation, UI/UX, edge cases, concerns, and tradeoffs. Don't ask obvious questions, dig into the hard parts I might not have considered.

Keep interviewing until we've covered everything, then write a complete spec to SPEC.md.

Перевод сути: вы говорите «хочу сделать X», просите Claude допросить вас подробно — про техническую реализацию, UX, edge cases, компромиссы. Claude задаёт вопросы, которые вы могли не учесть. По итогу пишет SPEC.md. Дальше начинаете свежую сессию с чистым контекстом и реализуете уже по спецификации.

Для вашего лестничного проекта это бесценно. Вместо «сделай отчёт по прибыли» вы запускаете интервью, и Claude спросит: «за какой период? как считать прибыль — по отгрузке или по оплате? что делать с заказами в работе? нужна ли группировка по клиентам?» — и так далее.

Управляйте сессией

Поправляйте Claude рано и часто

«Correct Claude as soon as you notice it going off track». Чем раньше вы заметите, что Claude свернул не туда, тем дешевле обходится коррекция. Инструменты:

• Esc — остановить Claude посреди действия. Контекст сохраняется, можно перенаправить.
• Esc + Esc или /rewind — откатиться к предыдущему состоянию: код, разговор или и то и другое.
• «Undo that» — попросить Claude откатить изменения.
• /clear — сбросить контекст между несвязанными задачами.

Очень важная цитата, которую вам стоит запомнить дословно: «If you've corrected Claude more than twice on the same issue in one session, the context is cluttered with failed approaches. Run /clear and start fresh with a more specific prompt that incorporates what you learned. A clean session with a better prompt almost always outperforms a long session with accumulated corrections.»

Перевод: если вы поправили Claude больше двух раз по одному и тому же вопросу в одной сессии — контекст уже замусорен неудавшимися подходами. Запустите /clear и начните заново, с более точным промптом, в который включите то, что узнали. Чистая сессия с хорошим промптом почти всегда обыгрывает длинную сессию с накопленными правками.

Управляйте контекстом агрессивно

• /clear — между несвязанными задачами. Не жалейте: это бесплатно и полезно.
• Когда контекст приближается к лимиту, Claude автоматически «компактит» историю — сжимает в краткое содержание. Можно и явно: /compact <инструкция>, например /compact Focus on the API changes.
• Если хотите сжать только часть разговора — Esc + Esc или /rewind, выбираете точку, «Summarize from here».
• Anthropic советует прописать в CLAUDE.md правила сжатия, например: «When compacting, always preserve the full list of modified files and any test commands». Это страховка, чтобы при авто-сжатии не потерялся список изменённых файлов.

Subagents для исследования

Anthropic ставит это сильно: «Since context is your fundamental constraint, subagents are one of the most powerful tools available». Контекст — это ваш главный ограниченный ресурс, поэтому subagent — один из самых мощных инструментов.

Пример из оригинала:

Use subagents to investigate how our authentication system handles token
refresh, and whether we have any existing OAuth utilities I should reuse.

На вашем стеке: «Используй subagent, чтобы изучить, как у нас сейчас работает JwtFilter, какие есть утилиты для подписи токенов и где они вызываются». Subagent прочитает 20 файлов в своём окне, а вам отдаст краткий отчёт. Основной контекст остаётся свежим для реализации.

Чекпоинты

Каждое действие Claude автоматически создаёт чекпоинт. Двойной Escape или /rewind — открывается меню отката: можно откатить только разговор, только код, или и то и другое. Anthropic подбадривает: «Instead of carefully planning every move, you can tell Claude to try something risky. If it doesn't work, rewind and try a different approach.» Не бойтесь рискованных экспериментов — есть кнопка «назад».

Чекпоинты — не замена git

«Checkpoints only track changes made by Claude, not external processes. This isn't a replacement for git.» Чекпоинты ловят только то, что менял сам Claude. Внешние процессы — миграции, ручные правки в IDE, чужие коммиты — туда не попадают. Поэтому коммитьте часто, отдельно от чекпоинтов.

Возврат к прошлым сессиям

claude --continue    # Resume the most recent conversation
claude --resume      # Select from recent conversations

Через /rename сессии можно называть осмысленно: «order-pricing-refactor», «materials-import», «jwt-bug». Тогда через неделю не придётся гадать, какая из десяти сессий была про что.

Типичные ошибки и как их избежать

Anthropic называет пять «failure patterns». Проходитесь по ним как по чек-листу — это самая полезная часть статьи именно для вашего случая, потому что про них вы узнаёте до того, как в них влетели.

• The kitchen sink session. Начали с одной задачи, спросили что-то несвязанное, вернулись к первой. Контекст забит мусором.
  Лечение: /clear между несвязанными задачами.
• Correcting over and over. Claude делает не то, вы поправляете, он опять не то, вы опять поправляете. Контекст забит провалившимися попытками.
  Лечение: после двух неудачных коррекций — /clear и новый, более точный промпт, в который вы заложили то, что узнали.
• The over-specified CLAUDE.md. CLAUDE.md слишком длинный, важные правила тонут.
  Лечение: безжалостно режьте. Если Claude и без инструкции делает правильно — удалите её или превратите в хук.
• The trust-then-verify gap. Claude выдал правдоподобный код, который не обрабатывает edge cases.
  Лечение: всегда давайте способ проверить — тесты, скрипты, скриншоты. «If you can't verify it, don't ship it.»
• The infinite exploration. Просите «исследуй X» без рамок, Claude читает сотни файлов, контекст переполнен.
  Лечение: либо узко формулируйте задачу, либо делегируйте subagent'у.

Все пять — это ровно то, на чём вы споткнулись в прошлый раз с большим проектом без CLAUDE.md и без плана. Распечатайте этот список и держите рядом, пока не запомните на автомате.

Развивайте интуицию

Anthropic заканчивает статью важным замечанием: «The patterns in this guide aren't set in stone. They're starting points that work well in general, but might not be optimal for every situation». Эти правила — не догма. Иногда стоит позволить контексту накапливаться, потому что вы глубоко в одной сложной задаче. Иногда стоит пропустить план, потому что задача исследовательская. Иногда расплывчатый промпт — это именно то, что нужно, чтобы увидеть, как Claude интерпретирует проблему.

«Pay attention to what works.» Замечайте, что у вас работает. Когда Claude выдаёт хороший результат, обращайте внимание: какой был промпт, какой контекст, в каком режиме. Когда буксует — задавайтесь вопросом, почему. Со временем интуиция нарастёт, и никакая статья её не заменит.

Что отсюда сразу взять в работу

1. Завести CLAUDE.md в корне лестничного проекта по образцу выше — стек, команды, стиль, что не делать. Закоммитить.
2. Перед каждой нетривиальной задачей включать plan mode и не переходить в нормальный режим, пока план вас не устраивает.
3. В каждом промпте давать способ проверки: тест, ./gradlew build, конкретные числа.
4. После двух неудачных коррекций — /clear и новый промпт.
5. Между несвязанными задачами — /clear без сожалений.
6. Длинные исследования делегировать subagent'у, чтобы не забивать основной контекст.
7. gh, psql, скрипты сборки — держать под рукой, чтобы Claude не выдумывал свои способы.

Это не «продвинутые трюки», это базовая дисциплина. Один CLAUDE.md плюс привычка планировать перед кодом плюс привычка чистить контекст — и качество того, что выдаёт Claude Code, поднимается на порядок.