Roman Kryvolapov Engineering Blog

Claude Code — Best Practices

Привет!

Здесь раньше лежала статья про практики работы с Cursor. Я её переписал.

Дело не в том, что Cursor стал хуже. Изменился сам способ работы: агент больше не «умное автодополнение», а исполнитель, которому вы готовите рабочее место, и от того, насколько хорошо это место подготовлено, результат зависит куда сильнее, чем от того, как красиво вы сформулировали запрос. Только готовить — не значит описывать всё подряд: код современная модель прочитает сама, и быстрее, чем вы бы его пересказали. Записывать стоит то, чего в коде нет.

Дальше — про Claude Code. Что положить в репозиторий, как планировать работу, как не сжечь контекст и деньги. Примеры взяты из рабочего проекта, где всё это настроено и обкатано на нескольких месяцах реальной разработки; числа тоже оттуда, а не из головы. Снимок проекта сделан в августе 2026 года, а что в нём поменялось за следующие три месяца и почему — в разделе «Три месяца спустя».

Контекст: не стена, а цена

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

Ещё недавно это был главный ограничитель. Сейчас у большинства моделей окно в миллион токенов, а перед его заполнением Claude Code сам сжимает историю, так что упереться в стену удаётся редко. В официальных рекомендациях Anthropic совет «контекстное окно — главный ограничитель, экономьте его агрессивно» теперь числится среди устаревших.

Но как цена контекст никуда не делся. Каждый запрос отправляет модели весь разговор заново: пока кэш тёплый — со скидкой, после паузы — по полной цене (на подписке кэш живёт около часа, по API-ключу пять минут). Сессия, в которой лежат три несвязанные задачи, на каждом ходу четвёртой перечитывает все три. И как шум тоже: две неудачные попытки, оставшиеся в истории, модель перечитывает вместе с удачной, а договорённость, данная только в чате, может не пережить сжатия.

Отсюда вывод, из которого растёт всё остальное. Контекстом по-прежнему надо управлять сознательно: решать, что туда попадёт, а что нет. Только теперь ради цены и фокуса, а не из страха, что окно кончится.

Дайте агенту способ проверить себя

Это первое, что стоит настроить, и это же чаще всего пропускают.

Агент останавливается, когда работа выглядит сделанной. Если проверить её нечем, «выглядит» — единственный доступный сигнал, и проверяющим становитесь вы. Каждая ошибка ждёт, пока вы её заметите.

Дайте что-то с однозначным «прошло / не прошло», и цикл замкнётся сам. Агент правит, запускает проверку, читает результат, повторяет. Проверкой может быть набор тестов, код возврата сборки, линтер, скрипт сравнения с эталоном, скриншот для сверки с макетом.

Разница видна прямо в формулировке задачи:

✗ сделай функцию валидации email
✓ сделай функцию валидации email. Примеры: user@example.com — верно,
invalid — неверно, user@.com — неверно. После реализации запусти тесты
и покажи вывод
✗ сборка падает
✓ сборка падает вот с этим: [текст ошибки]. Исправь причину, а не симптом,
и убедись, что сборка проходит

У меня в проекте проверка вшита в правило про коммит: перед коммитом обязательно прогоняются проверка типов, сборка и два валидатора контента. Не «желательно», а обязательно, с указанием, что результат гейтов идёт в отчёт настоящим, а не «вроде всё зелено».

Насколько жёстко держать проверку, решаете вы, и ступеней теперь четыре. В запросе: «прогони тесты auth и продолжай, пока не пройдут» — когда хватит, агент решает сам. Целью: /goal задаёт условие, которое после каждого хода сверяет с разговором отдельная модель, и агент работает, пока оно не выполнено; это нужно в основном для долгих фоновых прогонов, где он иногда заканчивает ход отчётом о прогрессе, хотя пункты ещё открыты. Хуком Stop: ваш скрипт запускается всякий раз, когда агент пытается закончить ход, и код выхода 2 возвращает его к работе. Это держит уже сам Claude Code, а не модель. И чужими глазами: /code-review проверяет diff в свежем подагенте, который не видел вашего разговора и не заражён рассуждениями, из которых вырос код.

Для того, что тесты и проверка типов не ловят, есть /verify: агент собирает и запускает само приложение и смотрит на результат.

И просите показывать доказательство: вывод тестов, саму команду, скриншот. Прочитать доказательство быстрее, чем перепроверять руками. А для сессии, за которой вы не следили, это вообще единственный способ понять, что произошло.

Сначала разведка, потом план, потом код

Если сразу просить код, получите аккуратное решение не той задачи.

В Claude Code есть отдельный режим планирования — Shift+Tab или /plan перед одним запросом: агент читает файлы, запускает команды для разведки и пишет план, но исходники не трогает. Рабочий цикл выходит такой: разобраться в нужной части кода → составить план → одобрить его, и режим выключится сам → реализовать → коммит.

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

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

Хочу сделать [одно предложение про фичу]. Проинтервьюируй меня подробно,
через инструмент вопросов.
Спрашивай про реализацию, интерфейс, пограничные случаи, риски и размены.
Очевидное не спрашивай, копай в трудные места, которые я мог не учесть.
Когда закончим — запиши полную спецификацию в SPEC.md.

Только не превращайте это в ритуал. Если правку можно описать одним предложением, план не нужен: лишний круг стоит дороже, чем польза от него. Для понятной задачи обычно хватает первого же простого запроса: нужный код агент прочитает сам.

Три уровня настройки

Знание агенту передаётся тремя способами, и они не взаимозаменяемы.

Инструкции проекта читаются в начале каждой сессии. Сюда идут факты, нужные всегда: как собрать, как запустить тесты, чем этот проект отличается от типового. Рекомендация Anthropic — держаться в пределах двухсот строк, и это не формальность. Чем длиннее файл, тем хуже соблюдаются его же указания.

Хороший тест для каждой строчки: если это убрать, агент начнёт ошибаться? Нет — убирайте. У Anthropic тест ещё строже: может ли агент найти это, прочитав код, и пойдёт ли он смотреть? Если оба ответа «да», строчка лишняя. Поэтому описывать в инструкциях архитектуру и раскладку папок больше незачем: репозиторий агент прочитает сам, и быстрее, чем вы объясните. Нужно то, чего в коде нет: решение, принятое на созвоне, процесс деплоя, который живёт в голове одного человека, переменная окружения для интеграционных тестов, место, где код обманчив.

Начальную версию файла соберёт /init, дальше работа в основном в вычёркивании. А /doctor prompt-audit проходит по инструкциям, правилам и скилам и ищет указания, написанные под старые модели, ссылки на несуществующие файлы и противоречия между файлами; правки он предлагает, но без спроса ничего не меняет.

Правила лежат отдельными файлами в каталоге правил, по файлу на тему, и грузятся так же. Их можно ограничить масками путей, и тогда правило подтянется только когда агент трогает подходящие файлы:

Markdown · .claude/rules/api-endpoints.md
---
paths:
- "src/api/**/*.ts"
- "apps/backend/**/*.ts"
---
# Правила для API
- Каждый эндпоинт валидирует вход, без исключений.
- Ошибки отдаются в общем формате из `ErrorResponse`.
- Новый эндпоинт сначала описывается в api.md, потом пишется код.

Правило с масками подтягивается, когда агент читает или правит подходящий файл. Нюанс, о котором легко не знать: при сжатии контекста такое правило уходит вместе с историей и вернётся, только когда агент снова тронет подходящий файл. Правила без масок и корневой файл инструкций после сжатия перечитываются с диска.

Скилы — знание по требованию. Каталог с файлом внутри; тело попадает в контекст, только когда задача ему соответствует или когда вы вызвали скил сами. Поэтому большие справочники должны быть скилами: в спящем состоянии от них в контексте только имя и описание. А процедуру с побочными эффектами, вроде выпуска релиза, стоит пометить disable-model-invocation: true: тогда сам агент её не запустит, только вы командой /имя, и в списке она места не занимает.

Раскладка, которой пользуюсь я:

  • факт, нужный всегда → инструкции проекта;
  • обязательное поведение → правило;
  • процедура или справочник, нужные иногда → скил;
  • то, что обязано происходить (или не происходить) всегда, без участия модели → хук или запрет в настройках разрешений.

Последний пункт стоит особняком. Всё, что выше, — текст, который модель читает и обычно выполняет. Хук — код, который выполнится независимо от её решения. Критичное поведение должно быть хуком, а не абзацем в инструкциях. Обратное тоже верно: хук на то, что на деле предпочтение, вреден. У предпочтений бывают исключения, и модель, видя перед собой код, обычно лучше рассудит, подходит ли правило к случаю, чем вы, написав его заранее. Anthropic советует держать набор жёстких запретов маленьким: если их набралось под сорок, большинство — вкусовщина. Разбор хуков со всеми событиями и рабочими примерами у меня в отдельной статье.

И всё это — промпты

Мысль, до которой я дошёл не сразу, а стоило бы с самого начала.

Инструкции проекта, правила, скилы, описания подагентов — это не конфигурация. Это системные промпты, которые кто-то (вы) пишет один раз, а модель читает в каждой сессии. Разница между «агент постоянно делает не то» и «агент работает предсказуемо» очень часто оказывается разницей между небрежно и аккуратно написанным промптом.

Что из техник промпт-инжиниринга реально окупается в этих файлах:

  • Структура и разделители. Заголовки, списки, явные блоки: модель разбирает структурированный текст надёжнее сплошной прозы, а вы получаете возможность сослаться на конкретный кусок из другого правила. Подробнее про разделители и структуру промпта.
  • Иерархия правил. Когда правил больше пяти, они начинают конфликтовать, и надо прямо написать, какое из них главнее. У меня, например, правило «не коммить без просьбы» стоит выше правила про проверку перед коммитом, и в тексте это сказано словами, а не подразумевается. Про то, как задавать иерархию правил, есть отдельный раздел.
  • Позитивные формулировки вместо запретов. «Оставь изменения в рабочем дереве и расскажи, что сделал» работает лучше, чем «не коммить». Одни запреты оставляют модель без образца поведения.
  • Спокойный тон вместо крика. IMPORTANT и заглавные буквы были нужны старым моделям. Нынешние следуют спокойно сформулированной строке, а от нажима начинают применять правило слишком широко, и там, где оно не подходит.
  • Примеры вместо описаний. Пара «так плохо / так хорошо» в правиле стоит трёх абзацев объяснения. Это обычный few-shot, просто применённый к конфигурации проекта.
  • Явный формат ответа. Если вы хотите определённую форму отчёта, её надо описать, а лучше показать. Про контроль формата ответа — там же.
  • Экономия контекста. Каждая строка инструкций и правил оплачивается в каждой сессии, поэтому лишнее слово здесь дороже, чем в обычном промпте. Это ровно то, что в статье про промпты называется контекст-инжинирингом.

Ещё одно наблюдение из практики: описывать надо не только что делать, но и какую ошибку правило предотвращает. Модель, которая понимает, от чего её страхуют, гораздо лучше применяет правило к ситуации, не описанной дословно. Половина моих правил поэтому начинается с абзаца «известный сценарий провала выглядит так».

Полный разбор техник — в статье про промпт-инжиниринг; дальше по тексту я буду ссылаться на конкретные разделы оттуда.

Как это выглядит на живом проекте

Дальше показываю на рабочем репозитории в том виде, в каком он был в августе 2026 года: девять правил, справочник по API, сто два скила и трекер задач прямо в проекте. Всё это выросло не сразу, а из ситуаций, когда одно и то же приходилось объяснять по третьему разу.

Правила

Правило — то, что агент обязан соблюдать всегда. Каждое лежит отдельным файлом и заканчивается чек-листом: по нему видно, соблюдено оно или нет.

Вот как выглядит правило целиком, самое короткое из моих:

Markdown · .claude/rules/never-commit-unless-asked.md
# Никаких коммитов, пока не попросили
**Не запускать `git commit` (а также push, PR, merge), пока пользователь
не попросил об этом прямо, своими словами.**
Законченная работа, зелёная сборка и ощущение «вроде готово» разрешением
не являются.
Сделал правки — оставь их в рабочем дереве, коротко расскажи, что изменилось,
и остановись. Сомневаешься, просили или нет, — не коммить, спроси.
## Чек-лист
- [ ] Ни одного коммита, push или PR без явной просьбы своими словами.
- [ ] Работа оставлена в рабочем дереве, изменения описаны.
- [ ] При сомнении задан вопрос, а не сделан коммит.

Выглядит как перебор. До первого раза, когда агент решает, что раз тесты зелёные, то можно и закоммитить, и уносит в историю ваши недоделанные эксперименты.

Дальше пройдусь по остальным восьми. Оригиналы у меня написаны по-английски (так исторически сложилось, правила переезжали между проектами), поэтому цитаты привожу в переводе.

Проверка перед коммитом

Самое длинное правило, вступает в силу когда коммит всё-таки попросили. Четыре стадии: прочитать весь diff по кускам; разобрать всё, чего изменения касаются за пределами diff, то есть вызывающий код, контракты и документацию, которая от этих правок только что устарела; поохотиться за дефектами; вынести вердикт.

Вердиктов ровно три, и написаны они так, чтобы агенту некуда было увильнуть:

PASS — не найдено ничего, либо всё найденное уже исправлено и перепроверено.
FIX, ЗАТЕМ PASS — есть настоящие, но чинибельные находки. Чини их сам,
немедленно, прогони проверку заново по исправленному состоянию и честно
расскажи разработчику, что нашёл и что починил. Чинить — поведение
по умолчанию: проблемы никогда не «оставляют на потом» и никогда
не ограничиваются упоминанием в отчёте.
STOP — серьёзная проблема (потеря данных, дыра в безопасности, сломанный
контракт, изменение противоречит собственному требованию) либо настоящая
развилка, где обе конструкции защитимы и выбор принадлежит разработчику.
Коммита нет. Объясни просто и конкретно, в чём проблема.

Дальше идёт фраза, которую я считаю самой полезной во всём правиле: исправление, сделанное во время проверки, само является изменением и проходит те же четыре стадии заново. Повторять, пока очередной полный проход не найдёт ничего нового. Только это состояние считается чистым.

Ещё оговорено, что --no-verify запрещён: упавший хук чинят, а не глушат.

Отдельно скажу про приём, который здесь работает. Стадии пронумерованы, у каждой свой список того, что проверять, а в конце — обязательный вердикт одним словом. Это тот же контроль формата ответа, что и в обычных промптах: модели гораздо труднее «примерно проверить» и сказать «вроде нормально», когда от неё требуется выбрать один из трёх помеченных исходов.

Стиль ответа

Правило про то, как со мной разговаривать. Начинается оно так:

Пользователь — человек, читающий чат, а не Claude Code.
У него НЕ открыт исходник параллельно, и он НЕ хочет расшифровывать
идентификаторы кода, имена полей и пути к файлам внутри ответа.
Говори с ним как коллега, а не как инструмент код-ревью.
Считай, что читатель — компетентный разработчик, который НЕ погружён
в этот проект. Он умеет писать код, но, скорее всего, ведёт несколько
проектов сразу и не держит специфику этого в голове.

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

Отдельный кусок описывает формат финального отчёта: сделано / осталось / что нужно от человека. И там же пример, взятый из жизни:

✗ «Осталось: своё дерево миграций с проверкой расхождения, образ и манифест,
проводка в скрипте запуска.»
✓ «Осталось:
- Описать изменения базы отдельными шагами обновления: сейчас таблица
создаётся на лету, и на настоящем сервере её просто не будет.
- Собрать образ и добавить в описание кластера, иначе некуда разворачивать.
- Прописать сервис в скрипте запуска, чтобы поднимался вместе с остальными.»

Три разных дела, слепленных в одну строку словами, понятными только тому, кто их только что написал. Читатель кивнёт и не прочитает, а потом окажется, что он согласился на то, чего не понял.

Пара «плохо / хорошо» тут работает лучше любого описания, и это ровно few-shot: один показанный пример заменяет абзац объяснений про самодостаточность формулировок.

Бюджет сессии

Трать токены пропорционально реальной сложности задачи — самым дешёвым
путём, который надёжно её решает, а не самым тщательным, какой позволил бы
бюджет. Лимиты — это ограждение: они показывают, где ты упрёшься в стену
или в ограничение частоты, чтобы остановиться заранее, а не бюджет,
который надо освоить.
ЗЕЛЁНАЯ зона НЕ означает «жги свободно».

Дальше в правиле таблица классов задач: тривиальная — правим сразу, без раздумий и разведки; маленькая — точечные чтения, всё в одном потоке; средняя — один проход планирования и высокие усилия только на трудной развилке; большая — фазами, с контрольной точкой между ними.

И отдельный раздел про подагентов с прямым счётом: веер из N агентов стоит как N сессий, поэтому запускать их имеет смысл только ради явной экономии. Это правило работает в паре с хуком, который приносит живые цифры лимитов, — про него подробно в статье про хуки.

Сомневаешься — ищи в интернете

Короткое правило, семнадцать строк, и почти всё в нём — описание одного сценария:

Известный сценарий провала, которого надо избежать: что-то не работает →
ты применяешь исправление, основанное на том, что «знаешь» → всё равно
не работает → каждое следующее исправление закапывает решение, построенное
на неверном предположении.
Поэтому во ВСЕХ сомнительных случаях — когда что-то неясно, неочевидно,
ведёт себя не так, как ты ожидал, или расходится с твоими знаниями —
ВСЕГДА ищи в интернете, прежде чем чинить дальше, и смотри в первую
очередь на свежую официальную документацию.
Если и поиск не дал решения — ОСТАНОВИСЬ и спроси пользователя.

Обратите внимание на структуру: сначала описан провал, потом требование. Так правило применяется и к ситуациям, которые в нём дословно не описаны, потому что модель понимает, от чего её страхуют.

А вот заглавные буквы я бы сегодня убрал, и в нынешней версии правила их уже нет: почему, сказано выше, в разделе про промпты.

Подтянуть ветку перед работой

Цена пропуска — не конфликт слияния в конце. Это работа, построенная
на базе, которой больше нет: баг, уже починенный кем-то другим; ревью кода,
который с тех пор изменился; номер записи в трекере или временная метка
миграции, уже занятые; решение, принятое по файлу двухнедельной давности.
Ничего из этого не всплывёт, пока работа не будет закончена.

Дальше три шага: получить изменения и посмотреть, насколько ветка отстала; перемотать; прочитать пришедшее, если оно касается вашей области. И отдельный раздел на случай грязного рабочего дерева.

Останавливаться на архитектурных развилках

Пожалуй, самое ценное правило из всех. Начинается с формулировки, которая мне нравится:

Часть решений — это правка. Часть — переписывание. Это правило про второй тип.
Когда ты замечаешь, что работу можно разумно построить более чем одним
способом и выбор дорого отменять, — остановись прежде чем писать код,
разберись в картине целиком и положи развилку перед разработчиком
с предысторией и разложенными вариантами.
Молча выбрать и пойти дальше — вот провал, который это правило
предотвращает: его цена не видна в diff, она всплывает месяцы спустя
в виде работы, которую придётся выбросить.

Дальше — признаки, по которым решение считается развилкой: трудно отменить; расходится больше чем на один компонент или команду; определяет, кто чем владеет и где проходит граница доверия; меняет то, что видно снаружи (развёрнутый компонент, схему данных, контракт API); затрагивает деньги, безопасность или приватность. Два признака и больше — стоп.

А вот вторая половина правила, без которой первая вредна:

Поднять развилку стоит разработчику настоящего внимания. Прежде чем поднимать:
— Обратимо в течение дня? → решай сам.
— Проект уже принимал равнозначное решение? → следуй ему;
прецедент важнее предпочтения.
— Тебя устроил бы любой из вариантов? → это не развилка, это вкус. Выбирай.
— Неясно только потому, что ты не посмотрел? → сначала посмотри.
Большинство «развилок» растворяется при чтении.
Ожидай в проекте несколько настоящих развилок, а не по одной на задачу.
Если ты поднимаешь их еженедельно — фильтр настроен неправильно.

Без этого фильтра правило превращается в свою противоположность: агент начинает спрашивать по любому поводу, человек перестаёт читать вопросы и пропускает тот единственный, который был важным.

Символьная навигация

В проекте подключён сервер, дающий переход к определению, поиск использований и правку по символу. Правило требует пользоваться им вместо чтения файлов целиком, и центральная его часть — таблица соответствий:

| Задача | Инструмент | Вместо чего |
| Понять API файла | обзор символов | чтения всего файла |
| Найти класс или функцию | поиск символа | grep по имени |
| Прочитать тело одного символа | символ с телом | чтения с отступом |
| Узнать, кто это вызывает | поиск ссылок | grep по имени |
| Переименовать по всему проекту | переименование символа | десятков правок |

Дальше — раздел «когда обычные инструменты правильный выбор». Это важная половина: у языкового сервера есть языки, которых он не понимает, и честно перечислить их полезнее, чем требовать невозможного.

Учёт работ

Девятое правило — про трекер: что попадает в задачи и баги, что не попадает никогда, как связаны записи и требования. Оно большое, и разбираю я его ниже отдельным разделом, потому что там интересна не столько формулировка, сколько сама схема учёта.

Скилы — это документация

Главная мысль раздела: скилы у меня не «плагины для агента», а документация проекта. Та самая, которую раньше писали в вики и никто не открывал.

Документация в вики живёт отдельно от кода и медленно с ним расходится. Документация в репозитории правится в том же pull request'е, что и код, и её читает исполнитель. Причём выборочно: тело скила попадает в контекст, только когда задача ему соответствует. Двадцать шесть тысяч строк документации обходятся строчкой в списке на каждый скил, пока не понадобились.

Префикс в имени — это адресат. Скилы разложены не по темам, а по тому, чьей команде адресованы:

.claude/skills/
├── req-uc-auth/SKILL.md требования: сценарии авторизации
├── req-personas/SKILL.md требования: персонажи
├── req-business-rules-core/SKILL.md требования: бизнес-правила
├── ba-acceptance-criteria/SKILL.md бизнес-анализ: как писать критерии
├── qa-bug-report/SKILL.md тестирование: как оформлять находки
├── dev-backend-new-endpoint/SKILL.md разработка: процедура нового эндпоинта
├── dev-tests-backend-unit/SKILL.md разработка: юнит-тесты
└── dev-workflow-git/SKILL.md разработка: конфликты слияния

Приходит новая роль в команде — появляется новый префикс, а не новая вики.

Как выглядит скил. Заголовок с именем и описанием, дальше обычный markdown:

Markdown · .claude/skills/dev-backend-new-endpoint/SKILL.md
---
name: dev-backend-new-endpoint
description: Процедура добавления HTTP-эндпоинта: контракт, валидация, слои,
тесты, регенерация клиента. Применять при создании нового эндпоинта или
модуля на бэкенде.
---
# Новый эндпоинт
1. Описать контракт в `api.md` — до кода, иначе файл и код разойдутся.
2. Контроллер только принимает и отдаёт; логика в сервисе, доступ к данным
в репозитории.
3. Валидация входа обязательна, ошибки — общим форматом.
4. Тесты: успешный путь, отказ валидации, отсутствие прав.
5. Перегенерировать клиент фронтенда и проверить, что он собирается.
## Чек-лист
- [ ] api.md обновлён до кода
- [ ] логика вне контроллера
- [ ] три теста на месте
- [ ] клиент перегенерирован, сборка зелёная

Описание — самое важное поле: по нему агент решает, подходит ли скил задаче. «Справочник по FastAPI» работает плохо. «Архитектура и продакшн-практики FastAPI; применять при создании и ревью сервисов на FastAPI» — хорошо. В списке описание вместе с полем when_to_use обрезается на 1536 символах, так что главный сценарий ставьте первым.

По сути это маленький промпт маршрутизации: он должен содержать и предмет, и условие срабатывания. Тело скила при этом держат коротким, потому что после загрузки оно остаётся в разговоре до конца сессии и едет в каждом следующем запросе. А после сжатия контекста от каждого вызванного скила возвращается только начало — первые пять тысяч токенов, и на все скилы вместе не больше двадцати пяти тысяч, — поэтому самое важное ставят в начало файла. Здесь работают те же соображения, что и в контекст-инжиниринге: длинный справочник лучше разбить, вынеся детали в соседние файлы, на которые скил ссылается.

Требования как скилы. Скил с требованиями выглядит как нормальный документ аналитика. Сценарии со своими номерами, персонажи, границы, критерии приёмки. Ничего «под агента» в нём нет:

Markdown · .claude/skills/req-uc-auth/SKILL.md (фрагмент)
## UC-AUTH-002 Войти по почте и паролю
**Персоны:** PER-001 Агент, PER-002 Менеджер
**Приоритет:** P0
### Критерии приёмки
- AC-UC-AUTH-002-001 — при верных данных сессия открыта и действует
в обоих приложениях без повторного входа.
- AC-UC-AUTH-002-002 — при неверном пароле ответ одинаков независимо
от того, существует ли аккаунт (не подсказываем перебором).
- AC-UC-AUTH-002-003 — после пяти неудач подряд вход по этой почте
блокируется на 15 минут.

А дальше главное: на эти номера ссылаются задачи и баги. В записи трекера стоит не пересказ, а ссылка. Текст требования не копируется никуда и живёт в одном месте. Если запись и требование разошлись — прав документ с требованием.

Лечит знакомую болезнь: критерий, переписанный в задачу, в вики и в тест-кейс, и три его версии через полгода.

Но это лишь один из вариантов

Держать документацию скилами — мой выбор, а не единственно правильный путь. Люди решают эту задачу очень по-разному, и стоит знать, из чего вообще выбирают.

Обычная папка с документацией в репозитории. Самый простой вариант: markdown в docs/, а в инструкциях проекта строчка «документация лежит там-то». Ничего настраивать не надо, читается людьми в GitHub как есть. Минус ровно один, но существенный: агент о ней не вспомнит, пока вы не назовёте файл. Он не знает, что там внутри, и в лучшем случае найдёт нужное поиском по словам.

AGENTS.md. Кросс-инструментальный файл контекста, который читают Codex, Cursor и ещё десяток агентов. Claude Code тоже читает его сам, но только если в проекте нет ни CLAUDE.md, ни CLAUDE.local.md, так что его выключает даже личный CLAUDE.local.md с вашими заметками. Если CLAUDE.md есть, по умолчанию читается он, а AGENTS.md подключают строчкой @AGENTS.md внутри него или настройкой, которая велит читать оба файла. Хороший выбор для команды, где разные люди работают разными агентами. Ограничение то же, что у инструкций проекта: это один файл, и раздувать его до справочника нельзя.

Внешняя вики через MCP. Confluence, Notion, Linear и что угодно ещё: документация остаётся там, где её и так ведут люди, а агент ходит туда по MCP-серверу. Аналитик правит страницу в привычном интерфейсе, с комментариями и историей, а агент читает то же самое. Платой идут сеть, аккаунты и то, что версия документации живёт отдельно от версии кода: страница поменялась вчера, а ветка, которую вы чините, отвечает состоянию месячной давности.

Obsidian и его родня. Локальное хранилище markdown-файлов, к которому агента подключают либо MCP-сервером, либо просто открывая ему каталог. Формат тот же plain-text, поэтому хранилище можно держать в гите, а поверх него работает и человек со своим графом ссылок и поиском, и агент. Люди используют это как общую память между инструментами и сессиями: заметки, решения, наработки в одном месте, доступном и Claude Code, и другому агенту. Для личной базы знаний вариант отличный. Для проектной документации команды слабее: связь с кодом опять теряется, а хранилище живёт своей жизнью.

Платформы документации с MCP и llms.txt. Современные сервисы вроде GitBook или Mintlify отдают документацию сразу в двух видах: человеческий сайт и машиночитаемый слой, вплоть до автоматически поднятого MCP-сервера. Разумно, когда документация публичная и её всё равно надо где-то издавать.

Поиск по большому корпусу. Если документации тысячи страниц, ни один из вариантов выше в контекст не влезет, и вопрос переходит в область поиска: векторная база, гибридный поиск, отдельный сервер, который отдаёт агенту нужные куски. Это уже отдельная инженерия, а не «положил файлы в папку».

Чем скилы выигрывают

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

Дальше по мелочи, но приятно. Документация версионируется вместе с кодом, и в старой ветке лежит та документация, которая соответствует старому коду. Правки проходят обычное ревью в pull request'е. Ничего не надо настраивать, всё работает офлайн, без токенов и внешних сервисов. И формат открытый: скилы Claude Code следуют стандарту Agent Skills, который понимают и другие инструменты.

Чем расплачиваешься

Минусы честнее перечислить сразу.

Список скилов сам занимает контекст. Не тела, а именно перечень имён и описаний, зато в каждой сессии. Бюджет у этого перечня — один процент контекстного окна. Когда скилов столько, что он не помещается, Claude Code выбрасывает описания у тех, которыми пользуются реже всего, и от них остаются одни имена. То есть платите вы уже не столько токенами, сколько невидимостью: без описания агент не поймёт, что скил подходит к задаче. Сколько стоит ваш список, оценит /doctor, а какие скилы почти не используются, покажет /skill-doctor.

Людям читать неудобно. Внутри репозитория нет ни поиска по документации, ни оглавления, ни комментариев на полях, ни удобной работы с картинками. Аналитик, привыкший к Confluence, в GitHub за требованиями не пойдёт. У меня это решается тем, что требования правит тот же человек, который работает с агентом, но в большой команде это станет проблемой.

Нет совместного редактирования и обсуждения. Комментарий к абзацу, обсуждение прямо в документе, уведомление «вас упомянули» — всего этого нет. Есть pull request, что в разы формальнее.

Несколько репозиториев — несколько копий. Общие для компании практики придётся или дублировать, или связывать символическими ссылками, или упаковывать в плагин. В монорепозитории проблемы нет, а вот на пяти репозиториях она заметна.

Соблазн свалить туда всё. Скилы дёшевы, поэтому в них легко накидать сто файлов и получить ту же самую мёртвую вику, только в гите. Одно спасение: описание, по которому агент выбирает скил. Если оно написано небрежно, документ не подтянется никогда, и вы даже не узнаете.

Ролевой фильтрации нет. Скилы аналитика видит разработчик, и наоборот, а платят контекстом все. Про это подробнее ниже, в разделе про роли.

Если сводить к одному правилу: то, что нужно агенту в момент работы над кодом, лучше держать рядом с кодом; то, что нужно людям для обсуждения и планирования, лучше держать там, где люди привыкли работать. У меня граница проходит примерно так: требования и практики — скилами, а планы, сроки и переписка остаются во внешней системе.

Сколько это стоит

Инструкции проекта и правила грузятся в каждую сессию целиком. В августе у меня это составляло 571 строку инструкций плюс 1245 строк правил. Почти две тысячи строк до того, как вы напечатали первое слово.

Заметно больше рекомендованного, и плачу я за это контекстом. Разменял сознательно: предсказуемость в проекте с несколькими приложениями и общей инфраструктурой дороже сэкономленных токенов. Но у размена есть предел. Если бы файл рос дальше, я бы растащил правила по маскам путей.

Кстати, если агент упорно нарушает какое-то правило — дело почти всегда не в формулировке, а в объёме. Правило потерялось. Лечится сокращением, а не добавлением заглавных букв. А если правило не должно знать исключений вовсе, его место не в тексте, а в хуке или запрете.

Три месяца спустя

Размен «предсказуемость дороже токенов» пришлось пересмотреть. Файл инструкций к концу августа дорос до 653 строк, его сократили до 216, а в начале октября проект прошёл полную чистку. После неё в инструкциях около ста пятидесяти строк, а скилов вместо ста двух — тридцать шесть: семьдесят два убрали, а шесть новых за это время добавились.

Что поменялось:

  • Семьдесят два общих скила. Справочники вроде лучших практик FastAPI или производительности Python. Всё это модель знает и без нас, а платили мы за них местом в списке каждой сессии. Остались требования, двадцать четыре скила, и процедуры, которые есть только в этом проекте, вроде ревью pull request'а по правилам команды.
  • Заметки по частям проекта собраны в отдельные CLAUDE.md в папках бэкенда, фронтенда, инфраструктуры и других. Такой файл подгружается, только когда агент начинает работать в своей папке.
  • Файлы .claudeignore. Claude Code их не читает: закрыть файл от агента можно только запретом на чтение в настройках разрешений.
  • Три правила — не коммитить без просьбы, проверка перед коммитом и подтянуть ветку — превратились в два: «перед началом работы» и «завершение работы», где ревизия изменений, коммит только по просьбе и pull request до зелёных проверок. Готовую задачу один раз проверяет отдельный подагент-ревьюер.

Добавились правила про качество кода, про конфликты слияния и про самостоятельную работу: прежде чем спрашивать, поищи сам, и доводи задачу до конца, а не возвращай на полпути. Всего правил теперь одиннадцать плюс справочник по API, около тысячи ста строк, и все, кроме стиля ответа, переписаны заново. Цитаты выше — из августовских версий: как образцы формулировок они по-прежнему годятся.

Вывод совпал с тем, к которому пришла и сама Anthropic: писать агенту стоит только то, чего он не найдёт в коде сам. Как вообще пишут хороший бэкенд, модель и так знает, а вот как принято в вашей команде — нет.

Документация: как и где

Принцип простой. Вся документация, которую читает агент, живёт в инструкциях, правилах и скилах. Отдельной папки «доки для агента» нет вообще — чтобы не было двух источников истины. Это решение конкретного проекта, а не единственно возможное: варианты и их цену я разобрал выше.

Что из этого следует:

Правила и скилы — источник истины. Агенту прямо запрещено придумывать поведение, им противоречащее. Считает документ неправым — говорит человеку, а не действует по-своему.

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

Новое — новый документ, изменение существующего — правка существующего. Иначе через полгода в проекте два скила про одно и то же с разными версиями истины.

Единый шаблон. Есть отдельный скил про то, как писать правила и скилы: структура, формулировки, разделители, обязательный чек-лист в конце. Чек-лист превращает описание в проверяемое требование, а заодно даёт агенту способ самому проверить, выполнил ли он документ.

Этот скил, по сути, свод техник промпт-инжиниринга, приложенный к конфигурации проекта, и правило требует применять его при создании или правке любого правила и любого скила. Звучит бюрократично, но окупается: документы, написанные по одному шаблону, реже противоречат друг другу и лучше соблюдаются. Разбор самих техник — в статье про промпт-инжиниринг.

README для людей, инструкции для агента. Оба нужны, но читатели разные. README объясняет новому человеку, что здесь происходит; агент опирается на инструкции, правила и скилы. Меняется структура проекта — правятся оба, иначе разработчик и агент живут в разных представлениях о репозитории.

Технические справочники отдельно. Развёртывание, миграции, результаты нагрузочных тестов лежат в обычной папке документации в корне. Агенту в работе над кодом они не нужны, а человеку нужны эпизодически.

Трекер задач и багов прямо в репозитории

Самая своеобразная часть моей конфигурации.

Задачи и баги лежат в репозитории обычными markdown-файлами, по файлу на запись. Никакой базы, никакого веб-интерфейса, никаких проверок в CI. Скрипт умеет две вещи: завести запись и пересобрать индекс. На этом автоматизация заканчивается.

management/
├── tasks/
│ ├── auth/TASK-001-one-password-for-both-apps.md
│ ├── billing/TASK-037-invoice-pdf-export.md
│ ├── done/TASK-012-import-legacy-contacts.md
│ ├── INDEX-AUGUST-2026.md
│ └── TEMPLATE.md
├── bugs/
│ ├── auth/BUG-003-sign-in-loops-on-expired-token.md
│ ├── done/BUG-001-avatar-upload-fails-over-2mb.md
│ └── INDEX-AUGUST-2026.md
├── decisions/ADR-0001-where-user-sessions-are-stored.md
├── logs/roman/2026-08-06/a1b2c3d4.log
└── new.py

Что это даёт. Агент видит задачу целиком, не выходя из проекта, вместе с требованием, на которое она ссылается, и кодом, который она правит; запись живёт в той же истории, что и код, поэтому всегда видно, каким коммитом она закрыта и что по ней менялось по дороге. Два человека (или два агента) над разными записями физически не редактируют один файл, так что конфликтов слияния не бывает по построению — это, пожалуй, главный аргумент против одного большого файла со списком задач, к которому все привыкли. Плюс всё работает офлайн, без аккаунтов и токенов.

Как выглядит запись

Вот реальный шаблон бага, только с выдуманным содержимым:

Markdown · management/bugs/auth/BUG-003-sign-in-loops-on-expired-token.md
---
id: BUG-003
title: 'Sign-in loops on an expired token'
severity: P1
status: CONFIRMED
module: auth
area: 'sign-in / refresh token'
found: 2026-08-04
closed:
assignee: ''
req: 'AC-UC-AUTH-002-001'
source: 'QA wave 12'
---
# BUG-003 — Sign-in loops on an expired token
- **Steps:** open the app with a token older than 24h → sign-in screen →
enter valid credentials → back to the sign-in screen.
- **Expected:** AC-UC-AUTH-002-001 — a valid sign-in opens a session.
- **Actual:** the refresh call returns 401 and the client retries forever.
- **Log:**
- 2026-08-04 — filed from the QA wave.
- 2026-08-05 — reproduced on staging, confirmed. Refresh interceptor
does not clear the stale token before retrying.
## Screenshots
- 2026-08-04 — `BUG-003_04-AUGUST-2026_11-20_loop.png` — the loop, three
redirects in the network tab.

Заводится командой, а не копированием файла руками:

Shell
python management/new.py bug --module=auth --severity=P1 \
--title="Sign-in loops on an expired token"
python management/new.py task --module=auth --priority=P1 \
--title="One password for both apps"
python management/new.py attach BUG-003 shot.png --note="the loop after the fix"

Скрипт выдаёт следующий свободный номер, кладёт файл в папку модуля и пересобирает индекс месяца. Индекс выглядит так:

Markdown · management/tasks/INDEX-AUGUST-2026.md
# Task index — AUGUST 2026
**Entries:** 31 · **Open:** 30 · **Closed:** 1
| ID | Prio | Status | Batch | Module | Title |
| --- | --- | --- | --- | --- | --- |
| TASK-029 | P1 | IN_PROGRESS | 2026-08-04-export | billing | Export invoices as PDF from the admin panel |
| TASK-030 | P1 | TODO | PROJ-42 | platform | Choose a feature-flag library |
| TASK-031 | P1 | TODO | PROJ-42 | platform | Set up CI/CD for the staging environment |

Детали, которые важны на практике:

Номера вечные. Не переиспользуются и не перенумеровываются никогда: на них ссылаются коммиты, переписка и другие записи. Сквозную нумерацию, правда, позже пришлось сменить на случайные коды из четырёх символов вроде BUG-2W7F: два человека на двух ветках брали один и тот же «следующий свободный номер», и git спокойно сливал обе записи, ведь имена файлов у них разные. Старые записи свои номера сохранили.

Папки названы по требованиям. Область записи называется так же, как файл требований, который ею владеет: req-uc-auth → папка auth. Задачи и баги делят одни и те же папки. Мелочь, но убирает вечный спор «куда это положить» и соединяет трекер с документацией.

Закрытие через git mv. Меняется статус, ставится дата, дописывается строка в журнал, файл переезжает в папку закрытых. Перемещений git не хранит: git mv даёт тот же результат, что и обычное перемещение, а git log --follow прослеживает файл по сходству содержимого. Поэтому история записи рвётся, только если вместе с переносом файл сильно переписан, и вот этого в закрывающем коммите стоит избегать.

Скриншоты в репозитории. Отдельная команда кладёт картинку в папку вложений, называет по схеме и дописывает строку в запись. Только изображения, до четырёх мегабайт, обрезанные: гит хранит каждый байт навсегда. Видео — ссылкой. Раздел со скриншотами дописывается в конец, потому что баг, живший три недели, несёт снимок на каждое состояние, и старые строки должны показывать, как было тогда.

Язык — английский латиницей. Имя файла строится из заголовка, а трекер читают люди без общего родного языка. Описание можно оставить на языке жалобы, если попросили, но заголовок и служебные поля всегда латиницей.

Что в трекер не попадает никогда

Самое важное правило учёта, и оно противоречит привычке: в трекере только продукт.

Тест ровно один. Работает ли это у заказчика? Приложения, библиотеки, из которых они собраны, данные, инфраструктура — да, это продукт.

Всё, что существует только чтобы нам было удобнее строить продукт, не попадает в трекер вообще. Ни задачей, ни багом, независимо от объёма работы и от того, кто попросил. Документация репозитория, правила, скилы, сам трекер и его скрипт, хуки, служебные скрипты, настройки CI, перекладывание папок. Это просто делается, а записью остаётся коммит и автоматический журнал сессии.

Формулировка в правиле звучит жёстко, и это намеренно:

Ни записи вообще — как бы сломанным оно ни выглядело и сколько бы работы
ни стоило: устаревший документ, мёртвая ссылка, неверный путь в правиле,
дефект в этом самом трекере или в служебном скрипте, хук, неправильно
читающий свой ввод, кривая настройка CI, переименованная папка, правило,
о котором кто-то попросил. До заказчика ничего из этого не доезжает,
значит это не баг. А превратить его в задачу — та же ошибка под другой
вывеской. Не заводите. Сделайте работу, коммит скажет за неё.

Соблазн велик: работы много, хочется, чтобы она была видна. Но трекер, набитый хозяйственными делами, никто не читает, а он заводился ровно ради чтения.

Второе разделение — задачи против багов. Всё, что нашло тестирование, это баг, и только баг. Исправление бага не порождает задачу. Задача — новая функциональность или переделка существующей, о которой попросили.

Решения

Рядом с задачами лежат архитектурные решения, по файлу на решение. Формат обычный, знакомый по ADR:

Markdown · management/decisions/ADR-0001-session-storage.md (структура)
---
id: ADR-0001
title: Where user sessions are stored: database or cache
status: Proposed
date: 2026-07-31
deciders: Engineering lead / Architect
related:
- management/tasks/auth/TASK-001, TASK-002
- Requirements BR-SEC-004 (one session shared by both apps)
supersedes: none
---
## Context что заставило принимать решение и какой вопрос заблокирован
## Decision пронумерованные пункты: что именно решено
## Verified facts (checked in code, not assumed) таблица «факт → где в коде»
## Consequences что это упрощает и чем за это платим
## Alternatives что рассматривали и почему отвергли

Раздел с проверенными фактами придумался после того, как одно решение приняли на основании чужого пересказа, а в коде оказалось иначе. Теперь каждый факт в ADR несёт ссылку на место в коде, откуда он взят.

Толк простой: спор, который решается один раз, потом не всплывает заново каждые два месяца.

Журнал сессий, который пишется сам

Третья часть учёта, и её никто не ведёт руками. Хук записывает всё, что происходило в сессии: ваши запросы, вопросы агента и что вы выбрали, статистику по каждому ходу, изменённые файлы с числом строк, финальный отчёт. Файл на сессию, папка на день, папка на разработчика.

Выглядит так:

management/logs/roman/2026-08-06/a1b2c3d4.log
session start: source=startup · model=claude-opus-5
════════════════════════════════════════════════════════════
prompt:
почини бесконечный редирект на протухшем токене, BUG-003
turn: model=claude-opus-5 · effort=high · 4m 12s · tools=23
(Read 9, Grep 5, Edit 3, Bash 6) · subagents=1
files:
~ apps/web/src/api/interceptors.ts +14/-6 +[41-48,52-57] -[41-46]
~ apps/web/tests/auth.spec.ts +31/-0 +[88-118]
answer:
Причина была в том, что перехватчик повторял запрос со старым токеном...
subagent done: general-purpose
session end: reason=prompt_input_exit · duration=51m

Зачем, если есть сам агент? Затем, что спрашивать у него, что было в сессии, — плохая идея. К концу длинной работы его контекст уже сжат: часть подробностей потеряна, часть пересказана оптимистично. Механическая запись, сделанная не моделью, — единственный честный ответ на вопрос «что вообще произошло».

Сорок семь таких файлов накопилось к августу, к ноябрю их больше семисот. Открывал я их чаще, чем ожидал: обычно чтобы понять, когда и почему появилось странное место в коде. Заодно это ответ на вопрос «а где учитывается работа над самим репозиторием, которую запрещено заводить задачей». Вот здесь. Автоматически, без единой строчки ручного учёта.

Чего у схемы нет

Честно про ограничения. Здесь нет доски, уведомлений, отчётов по спринту, учёта времени. Если менеджмент живёт в Jira, эта схема её не заменяет: у меня, например, метка группировки хранит как раз ключ из Jira.

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

Чего не хватает: роли

Раз уж я разложил скилы по префиксам под разные команды, скажу и про то, чего для этой схемы не хватает в самом инструменте.

Префикс в имени — соглашение, а не механизм. Аналитик, тестировщик и разработчик работают в одном репозитории и получают одну и ту же конфигурацию: одинаковые инструкции, весь набор скилов, одинаковые права на запись.

Три неприятности, и все три я видел живьём. Аналитик просит сверить спецификацию с кодом, а агент, нагруженный инструкциями для разработчика, начинает править исходники. Тестировщик просит воспроизвести дефект, а в общих инструкциях написано «перед проверкой примени миграции», и агент честно применяет их на общем стенде. И тише, но дороже: все платят контекстом за все скилы, включая те, которых их работа не касается никогда.

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

Правильное решение — сделать роль полноценным слоем конфигурации в репозитории. Своя часть инструкций, свой набор скилов и агентов, свои разрешения и, главное, своя область записи, за пределы которой правки не выходят:

.claude/
├── CLAUDE.md общая часть для всех
├── settings.json
├── skills/
└── roles/
├── dev/{CLAUDE.md, settings.json, skills/, agents/}
├── qa/{CLAUDE.md, settings.json} запрет на миграции и деплой
└── ba/{CLAUDE.md, settings.json} запись только в docs/ и specs/

Причём это должно быть запретом на уровне инструмента, а не просьбой в тексте. Разница ровно та же, что между правилом и хуком.

Часть схемы уже можно собрать из того, что есть. --agent даёт сессии инструменты и модель нужного подагента, а файл настроек, переданный через --settings, добавляет запреты и параметром skillOverrides прячет от агента чужие скилы или оставляет от них одни имена. Но выбирается это всё руками при запуске, а не лежит в репозитории готовой ролью.

Я оформил это запросом на добавление ролей в Claude Code: с описанием проблемы, тем, что уже закрывают флаги --agent и --settings, и тем, чего не хватает. Полная версия со схемой слияния настроек (роль может только сужать проектные права, но не расширять) — в первом запросе, который закрыл бот неактивности. Если боль знакома, сходите поддержать — чем больше подтверждений, тем выше шанс, что до этого дойдут руки.

Подагенты

Подагент — отдельная сессия со своим контекстом, своими инструментами и своим системным промптом. Делает часть работы, возвращает результат. Есть и форк: он не начинает с чистого листа, а наследует весь текущий разговор.

Польза не в том, что подагент умнее: по умолчанию это та же модель или попроще, и ту же задачу он решит не лучше основной сессии. Польза в четырёх вещах. Параллельность: независимые куски работы идут одновременно. Шумный вывод — полный прогон тестов, широкий поиск по коду — остаётся у подагента, а не едет потом в каждом запросе основной сессии. Свежий взгляд для проверки. И урезанные права: ревьюер, который может читать, но не может править, и этот запрет держит сам инструмент.

Просить об этом чаще всего не нужно: широкий поиск по коду Claude Code сам отдаёт встроенному подагенту Explore, побочные задачи — форкам, и запускает их в фоне, чтобы основной разговор не стоял.

Своего подагента описывают одним файлом:

Markdown · .claude/agents/security-reviewer.md
---
name: security-reviewer
description: Ревью изменений на предмет уязвимостей. Запускать перед
релизом и при правках в авторизации, загрузке файлов, работе с БД.
tools: Read, Grep, Glob, Bash
model: opus
---
Ты старший инженер по безопасности. Смотри изменения на предмет:
- инъекций (SQL, XSS, команды оболочки);
- дыр в аутентификации и авторизации;
- секретов в коде;
- небезопасной работы с пользовательскими данными.
Указывай конкретные строки и предлагай исправление. Стилистику не трогай.

Тело такого файла — системный промпт отдельной модели, а не заметка для себя. Работает всё то же самое: заданная роль, явные границы («стилистику не трогай»), формат ответа и условие вызова в описании. Про то, как писать промпты для агентов и вызова инструментов, есть отдельный раздел в статье о промптах.

Ещё одно применение — независимая проверка. Тот, кто писал код, плохой проверяющий: он видит не diff, а свои намерения. Просить подагента стоит конкретно:

Подагентом проверь изменения против PLAN.md. Убедись, что каждое требование
реализовано, что на перечисленные пограничные случаи есть тесты и что
ничего вне задачи не изменилось. Пиши про пробелы, а не про вкусовщину.

Оговорка, которую лучше знать заранее: проверяющий, которого попросили найти недостатки, их найдёт. Даже когда работа сделана хорошо, потому что его об этом попросили. Гнаться за каждым замечанием — прямой путь к лишним слоям абстракции и тестам на невозможные случаи.

И про деньги. Подагенты не бесплатны: каждый шлёт свои запросы, и они идут в те же лимиты, что и основной разговор. Свежему подагенту ещё и приходится заново собирать контекст, который у основной сессии уже был, так что иногда он выходит даже медленнее. Веер из десяти стоит примерно как десять сессий. Сэкономить можно на модели: простую работу вроде сбора файлов, которые импортируют модуль, отдают подагенту на Haiku, строчкой model: haiku в его описании. Правка в одном-двух файлах всегда быстрее в основной сессии.

Отдельная история — несколько параллельных сессий. Проще всего разводить их по рабочим деревьям гита: у каждой свой каталог и своя ветка, правки не сталкиваются. claude -w имя сразу запускает сессию в новом рабочем дереве, а игнорируемые гитом файлы вроде .env, которых в свежем дереве нет, Claude Code скопирует сам, если перечислить их в .worktreeinclude в корне репозитория. Схема «один пишет, другой проверяет» работает по той же причине, что и подагент-ревьюер: свежий контекст не заражён рассуждениями автора.

Контекст на практике

Приёмы, которыми пользуюсь постоянно:

Первая минута. Смотрите, куда пошёл агент, и жмите Esc, как только он свернул не туда: он остановится, сохранив всё сделанное, и можно поправить курс.

Новая задача — чистый контекст. Очистка между несвязанными задачами дешевле любой оптимизации. Хвост чужой задачи — это и лишние токены, и лишние поводы отвлечься. /clear ничего не стоит, а с именем, /clear oauth, ещё и подписывает сессию, к которой потом можно вернуться.

Две неудачные попытки — стоп. Поправили дважды и всё ещё не то? Дело уже не в формулировке: контекст забит неудачными подходами. Чистая сессия с более точной постановкой почти всегда обгоняет длинную с накопленными исправлениями.

Сжатие настраивается. Перед заполнением окна история сжимается автоматически. Можно сжать и вручную, с акцентом на нужном (/compact оставь изменения API и команды тестов), а в инструкциях проекта указать, что сохранять обязательно:

Markdown · CLAUDE.md
При сжатии контекста обязательно сохраняй: список изменённых файлов,
команды запуска тестов и принятые архитектурные решения с их причинами.

Только помните, что сжатие длинной сессии само по себе большой запрос: модель перечитывает весь разговор, чтобы его пересказать. Если история не нужна, /clear дешевле.

Откат вместо осторожности. Каждый ваш запрос — точка возврата: /rewind или Esc дважды на пустой строке, и вернуть можно переписку, файлы или и то и другое. Это меняет стиль работы: вместо долгого обдумывания рискованного шага проще попробовать и откатиться. Только помните, что откат не заменяет гит: он помнит лишь файлы, которые агент правил своими инструментами в основном разговоре, а изменения через командную строку не отслеживает.

Короткий вопрос в сторону. Для мелочи вроде «что делает этот флаг» есть /btw: ответ не попадает в историю.

Строка состояния и /usage. Размер контекста и расход лучше держать перед глазами: в строке состояния — постоянно. А /usage на подписке раскладывает расход по скилам, подагентам, плагинам и MCP-серверам и сам подсказывает, что поменять.

Разрешения

Режимов разрешений несколько, и по умолчанию теперь работает не самый строгий. Интерактивные сессии в терминале и VS Code стартуют в автоматическом режиме: отдельная модель-классификатор смотрит действие до выполнения и останавливает то, что остановили бы и вы, — curl | bash, деплой и миграции на проде, force push поверх чужой работы, отправку чувствительных данных наружу, действия, которые похожи на команды из прочитанного агентом текста, а не от вас. После трёх блокировок подряд или двадцати всего режим сдаётся и снова спрашивает человека. Если неинтерактивный запуск claude -p идёт в автоматическом режиме, спрашивать некого: заблокированное действие просто не выполняется, и Claude продолжает работу без него.

На другом конце — ручной режим, где вы подтверждаете каждую правку и каждую команду, кроме чтения. Безопасно и невыносимо: после десятого подтверждения вы уже не читаете, а кликаете. А режим совсем без проверок, bypassPermissions, имеет смысл только в одноразовом контейнере. Режимы, включая планирование, переключаются по Shift+Tab.

Автоматический режим — это суждение модели, а не правило, и он может ошибиться. Поэтому всё, что «никогда», записывается так, чтобы держал сам инструмент: запретами в настройках и хуками. Запреты и хуки PreToolUse действуют в любом режиме, включая автоматический и bypassPermissions, и срабатывают раньше, чем классификатор вообще увидит действие:

JSON · .claude/settings.json
{
"permissions": {
"allow": [
"Bash(npm run test *)",
"Bash(npm run lint)",
"Bash(npm run build)"
],
"ask": ["Bash(git push *)"],
"deny": [
"Read(.env)",
"Read(.secrets/**)"
]
}
}

Записанные без ./, эти правила ловят такой файл на любой глубине под папкой, где запущен Claude Code; Read(./.env) закрыл бы только тот, что лежит в ней самой. Запрет на чтение .env закрывает и инструмент чтения, и cat .env в командной строке: распространённые команды чтения файлов Claude Code узнаёт. Скрипт, который откроет файл сам, он уже не поймает. Разрешать чтение внутри проекта и команды вроде git status или git diff не нужно, подтверждения они не требуют и так. Звёздочка через пробел — нынешняя запись; старая форма test:* работает по-прежнему, но диалог разрешений пишет новую. Весь синтаксис правил — в справочнике по командам и настройкам.

Если классификатор раз за разом останавливает то, что у вас рутина, не подтверждайте вручную, а опишите окружение словами в личных настройках: какие домены свои, какой стенд можно трогать. В ручном режиме помогает обратное: /fewer-permission-prompts просматривает прошлые сессии и добавляет частые безопасные команды в список разрешённых.

Самый строгий вариант — песочница (/sandbox, на macOS, Linux и WSL2): ограничение файловой системы и сети на уровне ОС для команд, которые запускает агент. Она подхватывает и ваши запреты на чтение, так что для всего, что касается безопасности, нужны оба слоя.

Что бы вы ни выбрали, одно правило остаётся. Перед коммитом смотреть полный diff. Оно было важным и до агентов, а сейчас важнее: модель охотно правит то, о чём не просили, и заодно приводит в порядок соседний файл.

Когда никто не смотрит

Всё сказанное выше вдвойне важно, когда агент работает без вас. Пока вы смотрите, пропущенный кусок контекста — не беда: заметите через сообщение-другое. Запустили задачу на ночь — и утром узнаёте, что всю ночь она строилась на неверном предположении.

Перед таким запуском стоит пройтись по пяти вопросам, именно для этой задачи:

  1. Знает ли агент, как выглядит «готово»? Условие цели, файл спецификации, падающий тест, который надо сделать зелёным.
  2. Может ли он проверить себя? Тесты, хук Stop, шаг ревью.
  3. Что ему можно трогать? Правила разрешений, песочница, отдельное рабочее дерево, единственная ветка, куда можно пушить.
  4. Что его остановит? --max-turns, --max-budget-usd, лимит расходов.
  5. Куда пойдёт результат и кто его примет? Pull request или отчёт — и человек, который одобряет слияние.

Сам запуск — claude -p "задача" в скрипте или CI. С --permission-mode dontAsk всё, что не разрешено заранее через --allowedTools, отклоняется, а не висит в ожидании ответа. Повторять задачу по таймеру в открытой сессии умеет /loop, а /schedule заводит облачную задачу по расписанию, которая работает и при закрытом ноутбуке. Начинайте с трёх файлов, а не с трёхсот: посмотрите, что пошло не так, поправьте запрос, потом запускайте остальное.

Модели, усилия и деньги

Работа агента состоит из шагов очень разной сложности. Разобраться в задаче, найти файлы, применить правку, проверить результат. Держать на всех шагах самую дорогую модель незачем.

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

Markdown · .claude/skills/dev-changelog/SKILL.md
---
name: dev-changelog
description: Собрать changelog из истории коммитов между двумя тегами.
model: haiku
effort: low
disable-model-invocation: true
---

Оговорка для скилов: без context: fork модель скила действует в основном разговоре до конца хода. Дешёвая модель тогда получает всю историю, а кэш промпта основной модели на неё не распространяется, так что в длинной сессии экономия может обернуться перерасходом. С context: fork скил запускается в собственном подагенте и видит только свои инструкции.

Главный регулятор того, сколько модель думает, — уровень усилий: low, medium, high, xhigh и max, переключается командой /effort. У Opus 5.5, Sonnet 5.5 и Haiku 5.5 по умолчанию стоит medium, и для обычной работы с понятными границами этого хватает; у остальных моделей с уровнями усилий по умолчанию high, а у Opus 4.7 — xhigh. Поднимать стоит, когда правильность зависит от легко упускаемых случаев: баг в чужом коде, плавающий тест, изменение схемы, у которой надо найти всех читателей. max — для трудной задачи, которую агент решает без вас; на обычной он думает лишнего, и вы платите за ответ не лучше того, что дал бы high. Фразы вроде «подумай хорошенько» в запросе — обычный текст, уровень усилий они не поднимают. А для одного трудного вопроса посреди рутины есть слово ultrathink: оно просит глубже подумать только на этом ходу.

Отдельная тема — лимиты подписки. По умолчанию агент их не видит, поэтому не может соразмерять расход: он одинаково охотно запускает веер подагентов и когда до сброса четыре часа, и когда бюджет на исходе. Человеку их показывает /usage, у запусков из скриптов есть жёсткие пределы --max-turns и --max-budget-usd, а у меня это решено хуком, который приносит живые цифры в контекст и запрещает веерные запуски в горячей зоне. Подробности в статье про хуки.

MCP и консольные утилиты

Два способа дать агенту доступ к внешнему миру.

Консольные утилиты — самый экономный по контексту путь. Есть у сервиса CLI — агент прекрасно им пользуется: заводит задачи, читает комментарии, смотрит логи, разворачивает окружение. Незнакомые утилиты он тоже осваивает, если попросить разобраться по встроенной справке.

MCP-серверы — когда нужен структурированный доступ: база, трекер, макеты, мониторинг. Здесь же живёт полезная категория серверов для работы с самим кодом: символьная навигация вместо чтения файлов целиком экономит на больших репозиториях очень заметно. Для типизированных языков у Claude Code есть и официальные плагины code intelligence на языковых серверах: переход к определению вместо grep и чтения нескольких файлов-кандидатов, а после правки — ошибки типов сразу, без запуска компилятора.

Совет из практики: подключайте только то, чем реально пользуетесь. Полные описания инструментов MCP теперь подгружаются по требованию, но имена инструментов и инструкции сервера лежат в контексте каждой сессии и едут в каждом запросе, так что десяток серверов «на всякий случай» обходится дороже, чем кажется. Ненужные отключаются в /mcp.

Какие советы устарели

Модели заметно подтянулись, и часть советов, которые ещё недавно были верными, теперь мешают. Если что-то из этого осталось у вас в привычках или в инструкциях — смело выбрасывайте:

  • «Контекст — главный ограничитель». Окно в миллион токенов и автоматическое сжатие сделали упор в стену редкостью. Чистить контекст между задачами по-прежнему стоит, но ради цены и фокуса.
  • «Отдавайте работу подагентам, чтобы сберечь контекст». Подагенты хороши для параллельной работы, шумного вывода и независимой проверки, и каждый стоит токенов.
  • «Подагент ответит лучше». Та же модель на той же задаче умнее не станет. Помогает свежий взгляд ревьюера, но это другое.
  • «Подумай хорошенько» в запросе. За глубину отвечает уровень усилий, а эти слова — обычный текст. Работает только ultrathink, и только на один ход.
  • IMPORTANT и заглавные буквы. Нынешние модели от них применяют правило слишком широко. Не держится строчка — значит, файл слишком длинный или это работа для хука.
  • «Не ленись, продолжай до конца». Договорённую задачу модели и так доводят, а такие строки скорее вызывают лишнюю работу. Дать проверку, которую надо пройти, — другое дело, это по-прежнему полезно.
  • Описание архитектуры и раскладки папок в инструкциях. Репозиторий агент читает сам. Пишите только то, чего в нём нет.

Что осталось верным из практик Cursor

Часть советов из старой статьи никуда не делась. Они про работу с моделью вообще.

Декомпозируйте и контролируйте шаги. Просьба «сделай всё» даёт код, который работает не так, как вы ожидали, и разбираться в нём дороже, чем было бы написать. Шаги должны быть самодостаточными: после каждого проект собирается.

Логируйте щедро. Человеку перегруженная логами консоль мешает, агенту помогает: сопоставляя вывод с кодом, он точнее понимает, что сломалось.

Просите свежие версии библиотек и смотрите на лицензии. Модель подставит версию, которую чаще всего видела при обучении, а это редко последняя: данные обучения отстают от релиза модели на месяцы, а частота упоминаний тянет к версиям ещё старше. На лицензию она не смотрит вовсе, а затащить в закрытый проект библиотеку с копилефтом легко.

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

Разные задачи — разные сессии. Совет про новый чат под каждую задачу перекочевал без изменений, только теперь у него есть точное объяснение: это про цену и фокус контекста.

Как всё испортить

Собрал те способы, которые вижу чаще всего. У себя в том числе.

Сессия-помойка. Начали с одной задачи, спросили про другую, вернулись к первой. Контекст забит всем сразу.

Бесконечные исправления. Агент сделал не то, вы поправили, снова не то. После двух кругов дешевле начать заново.

Раздутые инструкции. Файл вырос, половина указаний перестала работать: важное потерялось. Лечится безжалостным сокращением.

Доверие без проверки. Правдоподобная реализация, не покрывающая пограничные случаи. Проверить нечем — не отправляйте.

Бесконечная разведка. «Разберись, как тут всё устроено» без границ, и сессия оплатила двести прочитанных файлов. Широкий поиск Claude Code сам отдаёт подагенту, но границы задаёте вы: ограничивайте область.

Коротко

Если забирать из статьи одно: сначала настройте среду, потом просите код. Только настраивайте то, чего агент не увидит сам: остальное он прочитает в коде.

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

Работа разовая, окупается в каждой сессии. И разница между «агент постоянно делает не то» и «агент делает что нужно» обычно именно здесь, а не в модели и не в формулировке очередного запроса.

И ещё раз про то, с чего начинал: всё это — промпты. Инструкции, правила, скилы, описания подагентов. Написанные небрежно, они дают ровно тот результат, который дают небрежные промпты, только вы платите за него в каждой сессии, а не один раз. Техники, которые тут работают, разобраны в статье про промпт-инжиниринг.

Про хуки — механизм, который делает поведение агента детерминированным, — отдельная статья со всеми событиями и тремя рабочими примерами.