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 проходит по инструкциям, правилам и скилам и ищет указания, написанные под старые модели, ссылки на несуществующие файлы и противоречия между файлами; правки он предлагает, но без спроса ничего не меняет.
Правила лежат отдельными файлами в каталоге правил, по файлу на тему, и грузятся так же. Их можно ограничить масками путей, и тогда правило подтянется только когда агент трогает подходящие файлы:
---paths: - "src/api/**/*.ts" - "apps/backend/**/*.ts"---
# Правила для API
- Каждый эндпоинт валидирует вход, без исключений.- Ошибки отдаются в общем формате из `ErrorResponse`.- Новый эндпоинт сначала описывается в api.md, потом пишется код.Правило с масками подтягивается, когда агент читает или правит подходящий файл. Нюанс, о котором легко не знать: при сжатии контекста такое правило уходит вместе с историей и вернётся, только когда агент снова тронет подходящий файл. Правила без масок и корневой файл инструкций после сжатия перечитываются с диска.
Скилы — знание по требованию. Каталог с файлом внутри; тело попадает в контекст, только когда задача ему соответствует или когда вы вызвали скил сами. Поэтому большие справочники должны быть скилами: в спящем состоянии от них в контексте только имя и описание. А процедуру с побочными эффектами, вроде выпуска релиза, стоит пометить disable-model-invocation: true: тогда сам агент её не запустит, только вы командой /имя, и в списке она места не занимает.
Раскладка, которой пользуюсь я:
- факт, нужный всегда → инструкции проекта;
- обязательное поведение → правило;
- процедура или справочник, нужные иногда → скил;
- то, что обязано происходить (или не происходить) всегда, без участия модели → хук или запрет в настройках разрешений.
Последний пункт стоит особняком. Всё, что выше, — текст, который модель читает и обычно выполняет. Хук — код, который выполнится независимо от её решения. Критичное поведение должно быть хуком, а не абзацем в инструкциях. Обратное тоже верно: хук на то, что на деле предпочтение, вреден. У предпочтений бывают исключения, и модель, видя перед собой код, обычно лучше рассудит, подходит ли правило к случаю, чем вы, написав его заранее. Anthropic советует держать набор жёстких запретов маленьким: если их набралось под сорок, большинство — вкусовщина. Разбор хуков со всеми событиями и рабочими примерами у меня в отдельной статье.
И всё это — промпты
Мысль, до которой я дошёл не сразу, а стоило бы с самого начала.
Инструкции проекта, правила, скилы, описания подагентов — это не конфигурация. Это системные промпты, которые кто-то (вы) пишет один раз, а модель читает в каждой сессии. Разница между «агент постоянно делает не то» и «агент работает предсказуемо» очень часто оказывается разницей между небрежно и аккуратно написанным промптом.
Что из техник промпт-инжиниринга реально окупается в этих файлах:
- Структура и разделители. Заголовки, списки, явные блоки: модель разбирает структурированный текст надёжнее сплошной прозы, а вы получаете возможность сослаться на конкретный кусок из другого правила. Подробнее про разделители и структуру промпта.
- Иерархия правил. Когда правил больше пяти, они начинают конфликтовать, и надо прямо написать, какое из них главнее. У меня, например, правило «не коммить без просьбы» стоит выше правила про проверку перед коммитом, и в тексте это сказано словами, а не подразумевается. Про то, как задавать иерархию правил, есть отдельный раздел.
- Позитивные формулировки вместо запретов. «Оставь изменения в рабочем дереве и расскажи, что сделал» работает лучше, чем «не коммить». Одни запреты оставляют модель без образца поведения.
- Спокойный тон вместо крика. IMPORTANT и заглавные буквы были нужны старым моделям. Нынешние следуют спокойно сформулированной строке, а от нажима начинают применять правило слишком широко, и там, где оно не подходит.
- Примеры вместо описаний. Пара «так плохо / так хорошо» в правиле стоит трёх абзацев объяснения. Это обычный few-shot, просто применённый к конфигурации проекта.
- Явный формат ответа. Если вы хотите определённую форму отчёта, её надо описать, а лучше показать. Про контроль формата ответа — там же.
- Экономия контекста. Каждая строка инструкций и правил оплачивается в каждой сессии, поэтому лишнее слово здесь дороже, чем в обычном промпте. Это ровно то, что в статье про промпты называется контекст-инжинирингом.
Ещё одно наблюдение из практики: описывать надо не только что делать, но и какую ошибку правило предотвращает. Модель, которая понимает, от чего её страхуют, гораздо лучше применяет правило к ситуации, не описанной дословно. Половина моих правил поэтому начинается с абзаца «известный сценарий провала выглядит так».
Полный разбор техник — в статье про промпт-инжиниринг; дальше по тексту я буду ссылаться на конкретные разделы оттуда.
Как это выглядит на живом проекте
Дальше показываю на рабочем репозитории в том виде, в каком он был в августе 2026 года: девять правил, справочник по API, сто два скила и трекер задач прямо в проекте. Всё это выросло не сразу, а из ситуаций, когда одно и то же приходилось объяснять по третьему разу.
Правила
Правило — то, что агент обязан соблюдать всегда. Каждое лежит отдельным файлом и заканчивается чек-листом: по нему видно, соблюдено оно или нет.
Вот как выглядит правило целиком, самое короткое из моих:
# Никаких коммитов, пока не попросили
**Не запускать `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:
---name: dev-backend-new-endpointdescription: Процедура добавления HTTP-эндпоинта: контракт, валидация, слои, тесты, регенерация клиента. Применять при создании нового эндпоинта или модуля на бэкенде.---
# Новый эндпоинт
1. Описать контракт в `api.md` — до кода, иначе файл и код разойдутся.2. Контроллер только принимает и отдаёт; логика в сервисе, доступ к данным в репозитории.3. Валидация входа обязательна, ошибки — общим форматом.4. Тесты: успешный путь, отказ валидации, отсутствие прав.5. Перегенерировать клиент фронтенда и проверить, что он собирается.
## Чек-лист- [ ] api.md обновлён до кода- [ ] логика вне контроллера- [ ] три теста на месте- [ ] клиент перегенерирован, сборка зелёнаяОписание — самое важное поле: по нему агент решает, подходит ли скил задаче. «Справочник по FastAPI» работает плохо. «Архитектура и продакшн-практики FastAPI; применять при создании и ревью сервисов на FastAPI» — хорошо. В списке описание вместе с полем when_to_use обрезается на 1536 символах, так что главный сценарий ставьте первым.
По сути это маленький промпт маршрутизации: он должен содержать и предмет, и условие срабатывания. Тело скила при этом держат коротким, потому что после загрузки оно остаётся в разговоре до конца сессии и едет в каждом следующем запросе. А после сжатия контекста от каждого вызванного скила возвращается только начало — первые пять тысяч токенов, и на все скилы вместе не больше двадцати пяти тысяч, — поэтому самое важное ставят в начало файла. Здесь работают те же соображения, что и в контекст-инжиниринге: длинный справочник лучше разбить, вынеся детали в соседние файлы, на которые скил ссылается.
Требования как скилы. Скил с требованиями выглядит как нормальный документ аналитика. Сценарии со своими номерами, персонажи, границы, критерии приёмки. Ничего «под агента» в нём нет:
## 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Что это даёт. Агент видит задачу целиком, не выходя из проекта, вместе с требованием, на которое она ссылается, и кодом, который она правит; запись живёт в той же истории, что и код, поэтому всегда видно, каким коммитом она закрыта и что по ней менялось по дороге. Два человека (или два агента) над разными записями физически не редактируют один файл, так что конфликтов слияния не бывает по построению — это, пожалуй, главный аргумент против одного большого файла со списком задач, к которому все привыкли. Плюс всё работает офлайн, без аккаунтов и токенов.
Как выглядит запись
Вот реальный шаблон бага, только с выдуманным содержимым:
---id: BUG-003title: 'Sign-in loops on an expired token'severity: P1status: CONFIRMEDmodule: autharea: 'sign-in / refresh token'found: 2026-08-04closed: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.Заводится командой, а не копированием файла руками:
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"Скрипт выдаёт следующий свободный номер, кладёт файл в папку модуля и пересобирает индекс месяца. Индекс выглядит так:
# 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:
---id: ADR-0001title: Where user sessions are stored: database or cachestatus: Proposeddate: 2026-07-31deciders: Engineering lead / Architectrelated: - 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 несёт ссылку на место в коде, откуда он взят.
Толк простой: спор, который решается один раз, потом не всплывает заново каждые два месяца.
Журнал сессий, который пишется сам
Третья часть учёта, и её никто не ведёт руками. Хук записывает всё, что происходило в сессии: ваши запросы, вопросы агента и что вы выбрали, статистику по каждому ходу, изменённые файлы с числом строк, финальный отчёт. Файл на сессию, папка на день, папка на разработчика.
Выглядит так:
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-purposesession 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, побочные задачи — форкам, и запускает их в фоне, чтобы основной разговор не стоял.
Своего подагента описывают одним файлом:
---name: security-reviewerdescription: Ревью изменений на предмет уязвимостей. Запускать перед релизом и при правках в авторизации, загрузке файлов, работе с БД.tools: Read, Grep, Glob, Bashmodel: opus---
Ты старший инженер по безопасности. Смотри изменения на предмет:- инъекций (SQL, XSS, команды оболочки);- дыр в аутентификации и авторизации;- секретов в коде;- небезопасной работы с пользовательскими данными.
Указывай конкретные строки и предлагай исправление. Стилистику не трогай.Тело такого файла — системный промпт отдельной модели, а не заметка для себя. Работает всё то же самое: заданная роль, явные границы («стилистику не трогай»), формат ответа и условие вызова в описании. Про то, как писать промпты для агентов и вызова инструментов, есть отдельный раздел в статье о промптах.
Ещё одно применение — независимая проверка. Тот, кто писал код, плохой проверяющий: он видит не diff, а свои намерения. Просить подагента стоит конкретно:
Подагентом проверь изменения против PLAN.md. Убедись, что каждое требованиереализовано, что на перечисленные пограничные случаи есть тесты и чтоничего вне задачи не изменилось. Пиши про пробелы, а не про вкусовщину.Оговорка, которую лучше знать заранее: проверяющий, которого попросили найти недостатки, их найдёт. Даже когда работа сделана хорошо, потому что его об этом попросили. Гнаться за каждым замечанием — прямой путь к лишним слоям абстракции и тестам на невозможные случаи.
И про деньги. Подагенты не бесплатны: каждый шлёт свои запросы, и они идут в те же лимиты, что и основной разговор. Свежему подагенту ещё и приходится заново собирать контекст, который у основной сессии уже был, так что иногда он выходит даже медленнее. Веер из десяти стоит примерно как десять сессий. Сэкономить можно на модели: простую работу вроде сбора файлов, которые импортируют модуль, отдают подагенту на Haiku, строчкой model: haiku в его описании. Правка в одном-двух файлах всегда быстрее в основной сессии.
Отдельная история — несколько параллельных сессий. Проще всего разводить их по рабочим деревьям гита: у каждой свой каталог и своя ветка, правки не сталкиваются. claude -w имя сразу запускает сессию в новом рабочем дереве, а игнорируемые гитом файлы вроде .env, которых в свежем дереве нет, Claude Code скопирует сам, если перечислить их в .worktreeinclude в корне репозитория. Схема «один пишет, другой проверяет» работает по той же причине, что и подагент-ревьюер: свежий контекст не заражён рассуждениями автора.
Контекст на практике
Приёмы, которыми пользуюсь постоянно:
Первая минута. Смотрите, куда пошёл агент, и жмите Esc, как только он свернул не туда: он остановится, сохранив всё сделанное, и можно поправить курс.
Новая задача — чистый контекст. Очистка между несвязанными задачами дешевле любой оптимизации. Хвост чужой задачи — это и лишние токены, и лишние поводы отвлечься. /clear ничего не стоит, а с именем, /clear oauth, ещё и подписывает сессию, к которой потом можно вернуться.
Две неудачные попытки — стоп. Поправили дважды и всё ещё не то? Дело уже не в формулировке: контекст забит неудачными подходами. Чистая сессия с более точной постановкой почти всегда обгоняет длинную с накопленными исправлениями.
Сжатие настраивается. Перед заполнением окна история сжимается автоматически. Можно сжать и вручную, с акцентом на нужном (/compact оставь изменения API и команды тестов), а в инструкциях проекта указать, что сохранять обязательно:
При сжатии контекста обязательно сохраняй: список изменённых файлов,команды запуска тестов и принятые архитектурные решения с их причинами.Только помните, что сжатие длинной сессии само по себе большой запрос: модель перечитывает весь разговор, чтобы его пересказать. Если история не нужна, /clear дешевле.
Откат вместо осторожности. Каждый ваш запрос — точка возврата: /rewind или Esc дважды на пустой строке, и вернуть можно переписку, файлы или и то и другое. Это меняет стиль работы: вместо долгого обдумывания рискованного шага проще попробовать и откатиться. Только помните, что откат не заменяет гит: он помнит лишь файлы, которые агент правил своими инструментами в основном разговоре, а изменения через командную строку не отслеживает.
Короткий вопрос в сторону. Для мелочи вроде «что делает этот флаг» есть /btw: ответ не попадает в историю.
Строка состояния и /usage. Размер контекста и расход лучше держать перед глазами: в строке состояния — постоянно. А /usage на подписке раскладывает расход по скилам, подагентам, плагинам и MCP-серверам и сам подсказывает, что поменять.
Разрешения
Режимов разрешений несколько, и по умолчанию теперь работает не самый строгий. Интерактивные сессии в терминале и VS Code стартуют в автоматическом режиме: отдельная модель-классификатор смотрит действие до выполнения и останавливает то, что остановили бы и вы, — curl | bash, деплой и миграции на проде, force push поверх чужой работы, отправку чувствительных данных наружу, действия, которые похожи на команды из прочитанного агентом текста, а не от вас. После трёх блокировок подряд или двадцати всего режим сдаётся и снова спрашивает человека. Если неинтерактивный запуск claude -p идёт в автоматическом режиме, спрашивать некого: заблокированное действие просто не выполняется, и Claude продолжает работу без него.
На другом конце — ручной режим, где вы подтверждаете каждую правку и каждую команду, кроме чтения. Безопасно и невыносимо: после десятого подтверждения вы уже не читаете, а кликаете. А режим совсем без проверок, bypassPermissions, имеет смысл только в одноразовом контейнере. Режимы, включая планирование, переключаются по Shift+Tab.
Автоматический режим — это суждение модели, а не правило, и он может ошибиться. Поэтому всё, что «никогда», записывается так, чтобы держал сам инструмент: запретами в настройках и хуками. Запреты и хуки PreToolUse действуют в любом режиме, включая автоматический и bypassPermissions, и срабатывают раньше, чем классификатор вообще увидит действие:
{ "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. Оно было важным и до агентов, а сейчас важнее: модель охотно правит то, о чём не просили, и заодно приводит в порядок соседний файл.
Когда никто не смотрит
Всё сказанное выше вдвойне важно, когда агент работает без вас. Пока вы смотрите, пропущенный кусок контекста — не беда: заметите через сообщение-другое. Запустили задачу на ночь — и утром узнаёте, что всю ночь она строилась на неверном предположении.
Перед таким запуском стоит пройтись по пяти вопросам, именно для этой задачи:
- Знает ли агент, как выглядит «готово»? Условие цели, файл спецификации, падающий тест, который надо сделать зелёным.
- Может ли он проверить себя? Тесты, хук
Stop, шаг ревью. - Что ему можно трогать? Правила разрешений, песочница, отдельное рабочее дерево, единственная ветка, куда можно пушить.
- Что его остановит?
--max-turns,--max-budget-usd, лимит расходов. - Куда пойдёт результат и кто его примет? Pull request или отчёт — и человек, который одобряет слияние.
Сам запуск — claude -p "задача" в скрипте или CI. С --permission-mode dontAsk всё, что не разрешено заранее через --allowedTools, отклоняется, а не висит в ожидании ответа. Повторять задачу по таймеру в открытой сессии умеет /loop, а /schedule заводит облачную задачу по расписанию, которая работает и при закрытом ноутбуке. Начинайте с трёх файлов, а не с трёхсот: посмотрите, что пошло не так, поправьте запрос, потом запускайте остальное.
Модели, усилия и деньги
Работа агента состоит из шагов очень разной сложности. Разобраться в задаче, найти файлы, применить правку, проверить результат. Держать на всех шагах самую дорогую модель незачем.
Практика такая: основная сессия на сильной модели, механическая работа делегируется подагентам на модели попроще, уровень усилий повышается только там, где есть трудная развилка. И скилы, и подагенты умеют задавать модель и усилия для себя, так что маршрутизацию можно описать один раз:
---name: dev-changelogdescription: Собрать changelog из истории коммитов между двумя тегами.model: haikueffort: lowdisable-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 сам отдаёт подагенту, но границы задаёте вы: ограничивайте область.
Коротко
Если забирать из статьи одно: сначала настройте среду, потом просите код. Только настраивайте то, чего агент не увидит сам: остальное он прочитает в коде.
Проверка, которую агент может запустить сам. Короткие инструкции проекта, где только то, чего он не найдёт в коде. Правила для обязательного поведения, скилы для знания по требованию, хуки и запреты для того, что должно происходить всегда или никогда. Учёт задач рядом с кодом. Осознанное отношение к контексту — ради цены и фокуса.
Работа разовая, окупается в каждой сессии. И разница между «агент постоянно делает не то» и «агент делает что нужно» обычно именно здесь, а не в модели и не в формулировке очередного запроса.
И ещё раз про то, с чего начинал: всё это — промпты. Инструкции, правила, скилы, описания подагентов. Написанные небрежно, они дают ровно тот результат, который дают небрежные промпты, только вы платите за него в каждой сессии, а не один раз. Техники, которые тут работают, разобраны в статье про промпт-инжиниринг.
Про хуки — механизм, который делает поведение агента детерминированным, — отдельная статья со всеми событиями и тремя рабочими примерами.