005ПИШЕМ РАБОЧИЙ КОД С ПЕРВОГО РАЗА

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

Что это даёт продукту

Без /plan: типичная фича из 5 файлов проходит через 2-3 итерации «агент сделал, мы заметили баг, агент починил». Каждая итерация — 30-90 минут активного внимания человека. Итого 1.5-4 часа на не-сложную фичу.

С /plan: 30 минут на согласование замысла + 1-3 часа автономной работы агента + 15 минут на финальный обзор. Активного человеческого внимания тратится в 2-3 раза меньше.

Сколько стоит подключить

— Один раз: настроить структуру .claude/memory/plans/ в проекте (5 минут). — На каждую новую фичу: 20-30 минут на согласование замысла перед стартом. — Регулярно: GLM-ревью текста перед публикацией, Kimi-ревью вёрстки. Стоимость — копейки (доли центра за прогон).

Что меняется в работе

— Вы говорите «что» и «почему», а не «как» (это техника). — Вы видите план до начала, а не оправдания после. — Если задача слишком большая — вы это видите сразу, а не через 3 дня. — Если агент пошёл не туда — это видно после первой фазы, а не после релиза.

Когда срочно подключать

Когда у вас:

• Уже было 2+ ситуации, где «работающий» код упал в проде через час.
• Есть длинная задача (3+ дня работы), и хочется делегировать «на ночь».
• Несколько агентов или несколько разработчиков работают над одной фичей, и они расходятся в понимании, что делают.
• Готовите PR на критическую систему (биллинг, auth, миграция схемы) — план становится журналом, по которому через полгода можно ответить «почему мы такое решение приняли».

Без кода. Что и в каком порядке делать.

Главный смысловой блок. Объясняем на пальцах, без файлов и команд, как устроен план изнутри и почему он работает на длинных задачах.

4.1. Структура папки плана

Главный технический блок. Конкретные файлы, паттерны, регэкспы.

4.1. Структура папки плана

Папка плана — это реальный шкаф с шестью полками. На каждой полке лежит один документ, и у каждого документа одна простая роль.

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

Полка вторая — «СЛОВАРЬ». Если в обсуждении есть слова, которые мы понимаем по-своему («заказ», «корзина», «активный пользователь»), мы их фиксируем тут одним предложением. Чтобы агент не подумал, что «активный» — это вчера, когда мы имели в виду «за последние 30 дней».

Полка третья — «КЛЮЧЕВЫЕ РЕШЕНИЯ». Список из десятка-полутора пунктов вида «мы делаем так, потому что — и НЕ делаем эдак, потому что —». Без этой полки агент не отвечает на «почему именно так» — а это вопрос номер один через три месяца, когда никто из команды уже не помнит обсуждения.

Полка четвёртая — «ЗАПРЕТЫ». Чего категорически нельзя делать, даже если очень хочется или «так короче». Например: «не списывать деньги до того, как пришёл результат». Эту полку агент перечитывает перед каждым новым шагом.

Полка пятая — «ТЕХНИЧЕСКИЙ РОУДМАП». Разбиение работы на 3-7 этапов. Не «вот тебе задача, иди делай», а «сначала вот это, потом вот это, потом вот это». Между этапами агент останавливается, показывает результат, и только потом идёт дальше.

Полка шестая — «ПРОВЕРКА В ПРОДУКТЕ». Сценарии, которые нужно прокликать в готовой фиче, чтобы убедиться: работает. Написаны человеческим языком, чтобы не-разработчик мог пройти их сам.

Подставь агента к этому шкафу, и он сам разберётся. Любая локальная неопределённость («куда списывать деньги?») имеет ответ ровно на одной из шести полок. Ему не нужно перечитывать чат двухдневной давности и гадать.

Минимальная папка .claude/memory/plans/<slug>/:

intent.md             # ← продуктовый замысел, §-секции (что, зачем, не путать с, цитаты)
glossary.md           # ← словарь терминов с потенциально неоднозначным значением
decisions.md          # ← D1, D2, ... — архитектурные/продуктовые решения с альтернативами
constraints.md        # ← запреты и обязательства (Initial + Live)
plan.md               # ← техническая декомпозиция на 3-7 фаз
verification.md       # ← продуктовые сценарии проверки для не-разработчика
index.md              # ← генерируется автоматически (граф + метаданные)
graph.json            # ← reverse-index фаз ↔ решений ↔ замысла
reviews/              # ← логи Kimi/GLM ревью по циклам

intent.md — корневой файл. Кривой intent ломает всё следом: decisions/plan/verification ссылаются на него, и если §-секции написаны мутно, эти ссылки указывают в туман. Пример минимального intent для фичи фоновой генерации:

# Intent — bg-image-generation

## §1 Что мы строим
Endpoint /api/images/v3/generate — пользователь нажимает «сгенерируй»,
получает HTTP 202 + generation_id, фоновая задача делает работу, результат
прилетает через SSE. Если страница перезагружена — состояние сохранено в БД,
работа продолжается на бэкенде.

## §2 Зачем
Раньше синхронная генерация (10-90 сек). При reload — потеря HTTP-связи,
rollback в БД, потеря деньег API + потеря результата для пользователя.
Это критическая проблема UX на мобайле.

## §3 Что НЕ делаем
Не пишем новый WebSocket. Используем существующий PG NOTIFY trigger через
SSE endpoint /api/conversations/{id}/stream.

Этот замысел существует ДО первого коммита кода. Когда агент на фазе 3 пишет endpoint, он перечитывает §2 и понимает: списание должно быть устойчиво к reload. Не «вижу синхронный запрос — списываю при ответе» (это сломалось бы при reload), а «вижу запрос — создаю pending Generation сразу + списываю только при success в фоновой задаче».

4.2. Проект A: фоновая генерация изображений — production с первого захода

«с одного захода сделал полностью рабочий функционал для прода и сразу правильно биллинг подключил» — про эту фичу.

4.2. Проект A: фоновая генерация изображений — production с первого захода

«с одного захода сделал полностью рабочий функционал для прода и сразу правильно биллинг подключил» — про эту фичу.

У нас был сервис, который умеет рисовать картинки примерно двумя десятками разных моделей — это один из наших продуктов в проде. Раньше схема была простая и плохая: пользователь нажал кнопку «сгенерируй», ждёт 30-60 секунд с открытой страницей. Случайно обновил вкладку — деньги списались, картинка не приехала. На мобильнике переключился в другое приложение — то же самое. Саппорт каждый день разбирал «верните деньги, я ничего не получил».

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

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

Когда эти правила записаны в плане ДО кода, агент не может «забыть про биллинг». Не потому что он молодец, а потому что правило «спиши только после успешной картинки» лежит в одной из полок шкафа, и оно одно. В коде физически нет другого места, куда можно вписать списание — иначе план запрещает.

Дальше эту большую работу разбили на шесть маленьких этапов по 0.5-3 часа каждый. После каждого этапа — пауза, проверка, фиксация в репозитории. Если на этапе номер три случайно сломали что-то из этапа номер два — это видно сразу, а не через месяц в проде.

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

Это опорный кейс выпуска. Производственная фоновая генерация изображений в одном из наших проектов (далее «проект A»): 21 модель × 9 провайдеров, единый endpoint /api/images/v3/generate, в проде с первой попытки, биллинг подключён правильно, без починок «после факта». Хочется разобрать четыре подпункта.

(а) Что лежало в плане ДО первой строки backend-кода

Перед стартом фазы 6.2.2 (когда писался ImageGenerationDispatcher — главный сервис) в decisions.md уже было зафиксировано 10 решений (D1-D10):

• D1: один endpoint + PROVIDER_MAP (21 модель → 9 провайдеров), а не 5 отдельных endpoint'ов для разных провайдеров. Альтернатива отвергнута: дублирование billing и валидации на каждой кнопке, легко забыть при добавлении новой модели.
• D2: фоновая задача через FastAPI BackgroundTasks, не Celery, не asyncio.create_task. Альтернатива отвергнута: Celery — overkill на 10-90 сек задачи; asyncio.create_task — нет lifecycle hook для DB session, тихо съест exception'ы.
• D3: HTTP 202 + immediate state persistence ДО вызова провайдера. Альтернатива отвергнута: без immediate commit reload теряет состояние.
• D8: атомарное списание только при success + один и тот же db.commit(). Альтернатива отвергнута: eager-charge + refund — race conditions, мусор в истории транзакций.

Когда фаза 6.2.3 написала backend (за 3 часа активной работы), агент перечитывал эти решения. Биллинг не мог быть забыт — он зашит в D8 как «атомарно с записью результата». Структурно «куда списывать» лежит ровно в одной строке, и эта строка зафиксирована в decisions.md.

(б) Как зафиксировали замысел против «забыл биллинг»

Тройной слой защиты:

1. **intent.md §2** прямо описывает failure mode: «при reload теряются деньги API + результат — это критическая проблема UX».
2. **decisions.md D8** фиксирует политику списания: success-only, атомарно.
3. **plan.md Phase 6.2.3 Task** содержит пункт «endpoint вызывает background task → background task в свою очередь делает charge_balance + commit в одной транзакции» — это в списке задач фазы, не в комментарии.

В коде это превращается в одну функцию complete_generation(result), которая делает три шага в одной транзакции. Невозможно её обойти, потому что вокруг нет других вариантов charge'а — фаза 6.2.3 запрещает добавлять другие.

(в) Как декомпозиция отсекла дрейф

Phase 6.2 разбита на 6 подфаз с явными границами:

Между каждой подфазой — commit в git, auto-checks (типы + тесты), и code-validator критик. Если фаза 6.2.3 случайно сломала контракт Dispatcher из 6.2.2 — критик это поймает на этапе фазы.

(г) Что увидел читатель плана через три месяца

Спустя три месяца я открыл intent.md этой фичи в новой сессии. Я не пересматривал коммиты. Я прочёл четыре §-секции (что строим, зачем, что не делаем, цитаты автора) — и понял, что именно делает этот endpoint и почему он не падает на reload. Не пришлось гадать. Хороший intent.md отвечает на главный вопрос («что мы строим и почему») без помощи git blame.

4.3. Проект B × 2 — одна машинка, два разных применения

4.3. Проект B × 2 — одна машинка, два разных применения

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

Первая фича — агент-помощник по рекламным кампаниям. Пользователь жмёт «оптимизируй мою кампанию», и в фоне ему 30-90 секунд работает агент: ходит по статистике, смотрит активные объявления, читает свежие алёрты, прикидывает несколько вариантов улучшения. Потом этот черновик прогоняется через шесть параллельных проверяющих. И тут важный момент: не все проверяющие — это дорогая модель. Половина проверок — простая арифметика и формат («бюджет не превышает лимит», «ключевые слова не дублируются», «структура объявления не сломана»). Это делается обычным кодом, без вызова ИИ. И только две проверки из шести — реально нужны ИИ-моделью: смысловая чистота текста и совпадение с тоном бренда. Дешёвых проверок гораздо больше, потому что они закрывают большую часть ошибок. Дорогие — только там, где без понимания смысла никак.

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

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

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

Совершенно разные задачи. Одна — интерактивная, с участием человека, с короткими паузами на одобрение. Вторая — ночная, без человека, чисто фоновая. Но обе уложились в один и тот же скелет плана: что строим, какие правила зафиксировали ДО кода, на сколько этапов разбили, как проверять. Меняются конкретные решения внутри — не меняется скелет.

Чтобы показать, что workflow /plan+/work универсальный и не привязан к доменам, разберём две разные фичи в другом нашем проекте (далее «проект B»). Обе — production. Обе используют тот же план-механизм. Но это два разных архитектурных шаблона.

Кейс A: Direct-агент для аналитики рекламных кампаний (interactive LLM-loop)

Фича оптимизирует рекламные кампании. Пользователь нажимает «оптимизируй», агент ходит по контексту (API рекламной системы, метрики аналитики, статистика запросов, активные алёрты) через несколько LLM-итераций, генерирует несколько вариантов плана, прогоняет их через 6 параллельных критиков, возвращается с черновиком.

Архитектура:

• Long-running: ≤6 итераций Claude Sonnet 4.6 + ≤5 enrichment-tool вызовов + ≤2 user clarification раундов = 30-90 секунд end-to-end.
• Persisted state: таблица direct_builder_drafts с колонками plan JSONB, critics JSONB, created_yandex_ids JSONB, error_message TEXT. Статус-машина из 9 состояний: drafting → critics_running → awaiting_approve_1 → creating → awaiting_approve_2 → launching → launched (плюс терминальные cancelled и failed). Двойной approval-gate потому что план сначала генерируется как чёрновик, потом одобряется юзером и переотправляется в боевую систему рекламы — нужны два независимых чека юзером.
• Polling: клиент опрашивает каждые 2 сек, sticky-scroll heuristic чтобы не пинать UI на нон-терминальных статусах.
• 6 параллельных критиков (verified в lib/direct/agents/critics/index.ts): wordstat / budget / copy / negative / structure / brand_purity. Из них copy.ts использует Claude Sonnet 4.6, brand-purity.ts использует Claude Haiku 4.5 для семантики бренда, остальные четыре — детерминированная валидация без LLM-вызова (бюджеты, негативные ключи по паттернам, структура объявлений, статистика запросов). Это важно — не каждый критик нужен дорогой моделью, дешёвые heuristic'и закрывают большую часть проверок.
• Resilience: prompt caching на стабильный системный префикс (значительная экономия input-токенов от turn 2), network drop recovery с toast'ами на 0/401/403/409/5xx, loadDraft() при потере response mid-transmission.

29 sequential PR'ов в диапазоне #228-#256 демонстрируют фазированный rollout: каждый добавляет layer валидации (L0 Zod → L1 business rules → L1.5 data sufficiency → L2 LLM critic fail-open).

Кейс B: i18n-worker для автоперевода интерфейсного контента (autonomous queue)

Фича переводит названия направлений, районов, поля профилей с RU на EN автоматически. Полностью без участия юзера — DB-триггер на изменение source-таблицы → запись в очередь → worker подхватывает → переводит → пишет в таблицу переводов.

Архитектура (verified против scripts/i18n-translation-worker.ts):

• Long-running: background systemd-сервис, batch processing задач из очереди.
• Returned control: DB-trigger enqueue не блокирует основной поток приложения.
• Persisted state: dedicated queue table i18n_translation_queue (migration 058), статусы (pending → processing → done | failed), retry counter.
• Coordination: PostgreSQL LISTEN/NOTIFY на канал i18n_translate. Trigger в schema посылает pg_notify() на insert/update.
• Atomic task claim: SELECT ... FOR UPDATE SKIP LOCKED чтобы несколько worker'ов не подхватили один и тот же job. Это важный трюк, который без плана легко забыть и получить duplicate translations + double-charge.
• Recovery: drainQueue() запускается на старте сервиса — обрабатывает всё, что застряло после рестарта.
• Retry: MAX_ATTEMPTS = 3. После трёх попыток статус становится failed, отправляется Telegram-алёрт.
• Graceful shutdown: 30 секунд таймаут на завершение in-flight задач, потом process exit → systemd рестартует.
• Model: Claude Sonnet 4.6 (claude-3-5-sonnet-4-6 в anthropic.messages.create). Изначально планировалось взять Haiku ради экономии, но качество перевода на доменных терминах (направления, методики, имена преподавателей) — критично, и Sonnet даёт заметно меньше ошибок согласования. Это решение через D-пункт в плане: «качество перевода доменной лексики выше cost-optimization». Будь иначе — клиент с большим объёмом контента получит «фриформ»-английский, который потом руками чистить дороже чем выиграли на токенах.
• Glossary: 117 терминов в lib/translation/domain-glossary.ts (30 стилей + 29 поз + 22 концепции + 15 доменных терминов). Подмешивается в каждый промпт перевода для стабильности терминологии.

Почему оба важны

Direct-агент — это interactive LLM workflow с multi-step reasoning + user-driven approval gates. i18n-worker — autonomous queue worker без user interaction. Это два разных шаблона одного и того же архитектурного паттерна (long-running operation → persisted state → recovery → cost-tracking). Workflow /plan+/work одинаково ложится на оба.

4.4. Делегирование фаз и --auto режим

4.4. Делегирование фаз и --auto режим

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

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

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

Главный фокус всей этой схемы в одном: каждый из помощников получает на вход тот же план. Тот же замысел, тот же список решений, те же запреты. Поэтому они не расходятся между собой и не пишут «каждый своё». У них общий источник правды — папка плана.

Параллельно можно запускать только те этапы, которые не пересекаются по файлам. Текст и картинки можно делать параллельно (разные файлы) — экономит часа два. Текст и проверку готового текста параллельно делать нельзя (нужен сначала текст, потом проверка).

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

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

В большом плане (8-12 часов работы, 7+ фаз) --auto ставит вопрос: всё ли исполняет одна модель Claude?

Не обязательно — можно подключить других агентов к конкретным фазам через MCP-делегацию или CLI-вызовы. Это опциональная архитектура, не часть базового /plan + /work. Конкретно эту публикацию я собирал так:

• Claude local — фазы research/text-writing/orchestration/deploy. Текст intent-critical, не делегирую.
• Gemini (через mcp__gemini__*) — фаза визуального дизайна SVG-диаграмм. Большой контекст + multi-modal — он лучше принимает референс-картинку и стайл-гайд.
• GLM (через mcp__glm__*) — фаза логического ревью текста. Внешний глаз: ловит противоречия и дубликаты, которые автор уже не видит.
• Kimi (через CLI kimi --print) — фаза e2e verstka review mobile + desktop. Опционально применяет CSS-фиксы.

Это специфика моей сессии, а не универсальный паттерн /work. У вас может быть один Claude на всё, могут быть свои делегаты, может вообще не быть external-моделей — base workflow /plan + /work от этого не зависит.

Что важно для делегации: каждый external-агент **получает на вход тот же intent.md + decisions.md + constraints.md**, что и main-Claude. Это и есть та причина почему делегирование работает — у всех агентов один источник правды.

Параллельные группы (если делегируете):

• Параллелить можно фазы у которых нет общих Touches (модифицируемых файлов) и нет Dependencies друг от друга.
• В моём случае фазы 2 (текст) и 3 (визуалы) параллельны — экономит ~2 часа.

Stop-conditions --auto:

• Auto-check провалился (типы, тесты).
• Critic-pass провалился (build/intent/code).
• Контекст ≥ 70%.
• Прошло 5 фаз подряд (защита от тихого drift).
• Юзер ввёл новый constraint в чат (constraint emergency rule).

4.5. Автономность как побочный эффект

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

4.5. Автономность как побочный эффект

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

Главный неожиданный эффект всей этой схемы — даже не качество кода. Качество кода — это следствие. Главное в другом: агент перестаёт переспрашивать.

Когда замысел, словарь, решения и запреты лежат в файлах, у помощника есть критерии правильности на каждый локальный вопрос. Не нужно перечитывать чат двухдневной давности и догадываться, что имелось в виду. Ответ на «как нам правильно» лежит на одной из шести полок шкафа.

Это меняет три вещи в работе.

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

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

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

Автономность тут означает не «AI сам решает что делать» — это была бы лотерея. А «AI сам решает локальные вопросы внутри явного плана» — это уже инженерный процесс.

Самая интересная часть workflow'а — даже не качество кода. Качество кода — следствие. Главный эффект: агент перестаёт переспрашивать.

Когда замысел зафиксирован в intent.md, словарь в glossary.md, решения в decisions.md, ограничения в constraints.md — у агента есть критерии правильности на каждое локальное решение. Не нужно перечитывать чат двухдневной давности, не нужно догадываться, что имелось в виду.

Это меняет три вещи:

1. Длинные задачи (4+ часа активной работы) становятся делегируемыми. До плана: на 3-м часу агент начинает делать «не то». С планом: критик-pass между фазами ловит drift, а замысел в файлах не даёт уехать в овраг.

1. Многоагентные пайплайны работают. Когда Gemini делает визуалы, а Claude пишет текст параллельно — оба читают один intent.md. Не нужно «передавать контекст» через диалог.

1. /work --auto через ночь — реалистичный сценарий для разработки. Когда задача — реализация фичи с понятным контрактом (API + БД + UI), /work --auto через ночь даёт production-ready код. С фоновой генерацией в проекте A это подтверждено: за неделю после merge ноль hot-fix коммитов в той фиче. На задачах принципиально другого типа (нарратив, копирайтинг, авторская статья) тот же workflow даёт куда хуже — в финале расскажу почему.

4.6. Цикл ревью и почему именно Kimi

На каждом этапе после написания кода — три отдельные проверки, в таком порядке:

1. Автоматические тесты и проверки типов (build-grade). Самое быстрое и тупое: запускается команда «проверь типы», «прогони линтер», «прогони тесты». Если красное — фикс, повтор. Дорого ошибиться тут только за время.
2. Проверка соответствия замыслу (intent-grade). Внешняя модель (другая, не та что писала код) читает: что мы решили в плане, что разрешено и что запрещено, какие термины использовать в коде, что должно лежать в этой фазе и не больше. Сверяет с реальным результатом этапа. Это ловит: «делал фоновую генерацию, забыл биллинг», «использовал отвергнутую альтернативу из decisions», «вышел за границы фазы и тронул лишнее».
3. Проверка качества кода (code-grade). Та же модель, другой угол: нет ли заглушек вместо реализации (типа «всегда возвращает True»), реально ли работает алгоритм или это видимость, есть ли обработка ошибок на критичных путях, нет ли хардкода секретов, тесты реально что-то проверяют или просто «assert True».

Каждая проверка возвращает один из трёх вердиктов: «прошло», «нужны правки» (пауза, юзер решает), «провалилось» (откат коммита, фикс, перепроверка — до трёх попыток).

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

Почему внешняя модель — Kimi, а не тот же агент. Если автор плана и проверяющий — одна модель, она сама себе ставит вердикт. Это не проверка, это самоодобрение. Поэтому правило: проверяющий должен быть другой моделью, чем основной автор. Я выбрал Kimi K2.6 потому что он специально заточен под такие задачи (читать код, читать структуру проекта, давать структурированный вердикт), у него есть доступ к инструментам через которые он сам читает реальный код и реальные документы, а не верит на слово плану. Если в плане сказано «таблица содержит колонку X», Kimi реально открывает миграцию и проверяет — есть колонка или придумали. На моей памяти это ловило выдуманные сущности больше десятка раз.

Цикл ревью на этапе создания плана работает чуть по-другому: внешний проверяющий читает весь план целиком и до трёх раз возвращает «нужны правки» — пока не достигнет «готово к работе». Если после трёх циклов остался блокер — план не закрывается, я сажусь дорабатывать вручную. Если только мелкие замечания — я выбираю: продолжать циклы, принять с оговорками (записывается в файл, показывается в начале каждого /work), или прерваться и доработать руками.

4.6. Цикл ревью и почему именно Kimi

На каждой фазе цикл проверок устроен так:

• 4d. Build-grade — code-validator subagent (read-only), spawned после auto-checks. JSON-vердикт pass/fail. Этот критик намеренно ограничен «build/type/import errors, structural mismatches между Task и implementation, missing files, files modified без авторизации Task». Не оценивает business logic. Max 3 attempts.
• 4f. Intent-grade — kimi-review.sh phase_intent <N> <plan_dir>. Conditional по полю Review фазы (запускается только если Review ∈ {intent, both, both+cumulative}). Категории: drift / term_misuse / constraint_violation / scope_creep / incomplete_task. Verdict: pass / concern (пауза, показ issues, юзер решает) / fail (revert commit, fix, re-commit, re-run; max 3 attempts).
• 4g. Code-grade — kimi-review.sh phase_code <N> <plan_dir>. Conditional по Review (запускается если Review ∈ {code, both, both+cumulative}). Проверяет 6 категорий: incomplete_impl (заглушки), fake_logic (видимость работы), error_handling, quality, security, test_quality.
• 4g-cum. Cumulative drift check — только Review=both+cumulative или каждые 3 фазы в --auto. Смотрит весь накопленный diff branch (не только текущую фазу). Vердикт: on_track / drift_concern / drift_critical.

Каждый из 4f/4g/4g-cum — это отдельный вызов Kimi с отдельным system-промптом. Kimi не один общий ревьюер с большим контекстом, а четыре специализированных режима. Каждый получает только релевантные срезы: для phase_intent — §-секции intent, D-decisions, glossary-термины из References фазы + полный constraints + git diff фазы. Не «весь план целиком», а sliced по anchor'ам.

Шесть режимов kimi-review.py

Dual-backend (CLI с MCP vs HTTP fallback)

Каждый режим запускается через одну функцию kimi_agent_cli или kimi_chat:

• CLI backend (default): kimi --print --final-message-only --yolo -w <cwd> -p <combined-prompt>. Kimi работает как агент с полным MCP-доступом (codegraph, serena, context7, playwright, gitlab). Реально читает intent.md/decisions.md/git diff/код через инструменты, не через prompt-stuffing. Это критично — Kimi ловит выдуманные сущности через codegraph_query, проверяет API библиотек через context7, находит точные места использования символов через serena. Timeout 900s.
• HTTP backend (fallback): plain POST к ${LLM_BASE_URL}/chat/completions. Без tools, без MCP. Используется когда kimi binary недоступен. Timeout 90s. thinking: disabled — review-задача с фиксированной JSON-схемой, thinking-режим съест max_tokens до того как модель дойдёт до verdict (известный gotcha).

Backend выбирается автоматически: если /root/.local/bin/kimi и /root/.kimi/mcp.json существуют — CLI, иначе HTTP. Override через KIMI_REVIEW_BACKEND=cli|http.

Selective context loading в phase_intent/phase_code

Не передаются ВСЕ intent/decisions/glossary в Kimi. Из plan.md вытаскивается блок Phase N (через regex), парсятся References (bare anchors, splitter — только запятая, многословные термины как один токен, аннотации в скобках типа §3 (partially) auto-stripped). По якорям через extract_section достаются только нужные секции:

refs = parse_phase_refs(plan_md, phase_n)
intent_sections = "\n\n".join(extract_section(intent, a) for a in refs["intent"])
decision_sections = "\n\n".join(extract_section(decisions, a) for a in refs["decisions"])
glossary_sections = "\n\n".join(extract_section(glossary, a) for a in refs["glossary"])
phase_block = extract_phase(plan_md, phase_n)
diff = git_diff_for_phase(plan_dir, phase_n)

Без этого slicing-а планы из 1000+ строк intent уезжают за context window каждой следующей фазы.

Почему именно Kimi (без цен, по архитектуре)

1. Decision tree в моём skill kimi-integration прямо: «coding-агент с tool calls + reasoning» → kimi-k2.6. Plan-review это ровно «coding-agent с tool calls + reasoning», не bulk, не realtime web, не vision, не critical customer service.
2. Reviewer должен быть другой моделью, чем primary author. Иначе тот же агент что писал план — себе же ставит verdict. Independence нужна архитектурно, не «потому что Kimi лучше». Если бы я писал Kimi'ем — ревьюером был бы Claude.
3. Tool calls + MCP надёжно — Kimi через CLI реально читает код/диф/доки через codegraph/serena/context7, не догадывается на основе текста плана.
4. Reliability gap некритичен — известный ~13pp gap vs Claude в TAU-bench (customer-service) для plan-review не релевантен: это batch-задача с фиксированной JSON-схемой output, retry до 3 раз, failure mode — переспросить.
5. Long-horizon stability — для длинных --auto прогонов (10+ фаз, каждая делает 5-15 tool calls) Kimi стабильнее на 200+ tool calls без drift.
6. Model preferences моего проекта: GPT/Grok/Codex выпилены отдельным правилом. Остаются Claude (primary author), Gemini (вне coding-agent скоупа), DeepSeek (bulk, недостаточно reasoning), Kimi.