План перед кодом: один чекпоинт в цикле с AI-ассистентом

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

Полный цикл, который автор предлагает держать в голове:

Specify → Inspect → Plan → Review the assumptions → Implement a small change → Run checks → Review the diff → Repeat

Change contract: четыре поля до первого запроса к ассистенту

Перед тем как вовлекать AI-ассистента, автор описывает задачу четырьмя блоками:

1. The outcome I want — какой результат нужен.
2. The relevant repository context — какие части репозитория затронуты.
3. The constraints that must be preserved — что нельзя сломать или изменить.
4. The checks that will demonstrate success — как вы поймёте, что задача выполнена.

В посте приводится пример с кэшированием чтений user profile: без новых зависимостей, без изменения public API, без кэша на неуспешных lookup, при сбое кэша — чтение из БД не блокируется. Критерии приёмки заданы явно, а не отложены на «ассистент разберётся».

Чем конкретнее контракт, тем меньше ассистент расширит scope формулировками вроде «make it production-ready» или «handle all edge cases».

Сильный план ассистента против шаблонного списка задач

Слабый план повторяет запрос: «добавить кэш», «добавить инвалидацию», «добавить тесты» — без признаков, что репозиторий действительно понят. Полезный план отвечает на вопросы ревьюера: нашёл ли существующую абстракцию, меняет ли правильный слой, понимает ли update flow, разумен ли scope, связаны ли тесты с требованием, помечены ли неподдерживаемые допущения.

Ключевой checkpoint-промпт в материале звучит так:

Inspect the relevant files and propose a minimal implementation plan.

1. Summarize the current behavior.
2. Identify the files that would need to change.
3. Explain which existing abstractions should be reused.
4. List assumptions you are making.
5. Describe the tests that would demonstrate success.

Do not modify any files yet.

Явное «Do not modify any files yet» отделяет фазу понимания от фазы записи — для агента с доступом к репозиторию это граница, которую легко перешагнуть одним сообщением «сделай».

Инкрементальные правки: дифф, который можно разобрать по строкам

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

Широкие патчи скрывают лишнюю работу: unrelated formatting, новые абстракции, дублирование, convenience-зависимости, изменение public API, тесты, которые не доказывают поведение. Для агента, который умеет «сделать красиво», инкремент — способ не потерять контроль над scope.

Пример формулировки из поста:

Implement only the cache-read path for getUserById.
Stop before implementing the next part.

Проверки вместо размытых «best practices»

Вместо субъективных инструкций автор предлагает наблюдаемые проверки: сохранён ли public API, использованы ли существующие абстракции, нет ли новой зависимости, есть ли сфокусированные тесты, запущены ли unit tests / type checker / linter. Если команда не выполнилась — ассистент должен сообщить точную причину, а не предполагать успех.

Набор checks зависит от репозитория: unit/integration tests, typecheck, lint, format, schema validation, static analysis, dependency audit, production build. Для AI-assisted coding это замена размытым «используй best practices» — агент получает критерии, по которым вы сами примете или отклоните патч.

Project guide в AGENTS.md и границы ассистента

Полезный project guide отвечает на четыре вопроса: куда класть код, какие паттерны переиспользовать, как верифицировать изменение, какие действия требуют одобрения человека. Автор допускает хранение такого гайда в AGENTS.md, contributing documentation, repository instructions или другом файле, который команда реально поддерживает.

Отдельно зафиксирован принцип работы с capabilities ассистента: Read broadly. Write narrowly. Run locally. Ask before creating external effects. На практике — отдельная ветка или worktree, запись только в релевантные директории, секреты вне окружения, review установки зависимостей, блокировка деплоя, одобрение сетевого доступа, sandbox или container где возможно.

Содержимое репозитория не автоматически заслуживает доверия: инструкции могут жить в issues, comments, docs, зависимостях, generated output, ответах внешних инструментов. Ассистент не должен исполнять всё подряд — и соло-разработчику имеет смысл явно прописать, что требует ручного OK.

Ревью диффа, а не саммари ассистента

После implementation автор смотрит diff, а не summary вроде «Implemented caching with robust error handling». Порядок ревью: Scope → Behavior → Tests → Maintainability → Security — в том числе недоверенный ввод, чувствительные данные в логах и промптах, изменения сети и прав, валидация значений, сгенерированных моделью.

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

Review the current diff as a skeptical maintainer.
List findings in priority order.
Do not rewrite the code yet.

Непроверенное поведение должно быть помечено как assumption, а не угадываться молча: «Do not silently guess project-specific behavior».

Завершающий отчёт ассистента, по замыслу автора, честно отделяет проверенное от unverified items — иначе уверенное объяснение снова подменяет ревью.

---

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

Источники

• A Small Change to Your AI Coding Workflow: Ask for the Plan First — johnnylemonny, Dev.to, опубликовано 28 июля 2026, ~10 мин чтения