Не давай Claude Code писать код, пока не утвердишь plan.md

737 поинтов и 460+ комментариев на Hacker News за сутки. Борис Тане (Boris Tane) — фаундер Baselime (теперь часть Cloudflare, где он лидит Observability) — написал гайд о том, как он использует Claude Code. Не очередной «топ-10 промптов», а целая методология, которую он обкатывал 9 месяцев на реальных продакшн-задачах.

TL;DR: Никаких магических промптов. Claude Code сначала изучает кодовую базу (research.md), потом пишет план (plan.md), потом вы правите этот план 1-6 раз в текстовом редакторе — и только после этого даёте команду «implement it all». Разработчик — архитектор, Claude — исполнитель.

Главный тезис

Бóльшая часть гайдов по AI-кодингу сводится к магии промптов: добавь «step by step», напиши «think carefully», засунь few-shot примеры. Борис идёт от другого — не давать модели написать ни строчки кода, пока вы не утвердите текстовый план. Не встроенный plan mode, а свой собственный .md-файл, который вы открываете в редакторе и правите руками.

Звучит просто? Меняет всё. Вместо борьбы с кривым сгенерированным кодом — борьба с текстом. А текст — дёшево. По токенам, по времени, по нервам.

Фаза 1: Research — заставьте модель РЕАЛЬНО читать

Первый шаг — не кодинг. Claude должен глубоко изучить ту часть кодовой базы, которую вы собираетесь менять. Результат — файл research.md.

Ключевой момент: обычный промпт «изучи эту папку» не работает. Claude пробежится по сигнатурам функций и доложит «готово». Борис акцентирует внимание на специфической лексике:

read this folder in depth, understand how it works deeply, 
what it does and all its specificities. 
when that's done, write a detailed report

Слова «deeply», «in great details», «intricacies» — не декорация. На HN развернулась любопытная дискуссия: одни объясняют это тем, что LLM при обучении видели подробные объяснения рядом с такими маркерами, другие ссылаются на исследования «emotion prompting», где эмоционально окрашенные инструкции реально улучшают качество ответов. Механизм спорный, но результат работает.

Зачем фиксировать всё в research.md? Это первая точка контроля. Вы читаете отчёт и сразу видите: Claude понял систему кэширования? Заметил конвенции ORM? Знает про retry-логику в очереди? Если нет — поправляете ДО планирования, а не после того как модель уже наломала дров.

Фаза 2: Plan — маркдаун, а не чат

На основе ресёрча Claude генерирует plan.md — детальную стратегию с файлами, зависимостями, кусками кода и trade-offs.

Важный нюанс: Борис специально не использует встроенный plan mode Claude Code. Свой .md-файл даёт полный контроль — открываете в VS Code, добавляете inline-заметки, сохраняете как артефакт проекта. Его можно ревьюить, диффить, коммитить.

I want to build [feature] that extends the system 
to perform [outcome]. write a detailed plan.md

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

Фаза 3: Annotation Cycle — ядро методологии

Здесь происходит вся магия. Цикл:

1. Claude пишет plan.md
2. Вы открываете файл в редакторе
3. Добавляете inline-заметки прямо в документ
4. Отправляете назад с ключевой фразой: «don't implement yet»
5. Claude обновляет план
6. Повторяете 1-6 раз, пока план не станет идеальным

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

• Доменное знание: «use drizzle:generate for migrations, not raw SQL»
• Отклонение подхода: «remove this section entirely»
• Ограничения: «the queue consumer already handles retries, so this retry logic is redundant»
• Структурные: «this visibility field needs to be on the list itself, not items»

Фраза «don't implement yet» — ваш предохранитель. Без неё Claude может начать писать код посреди обсуждения плана.

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

Фаза 4: Implementation — одна команда, без остановок

Когда план отшлифован, даётся финальная команда:

implement it all. when you're done with a task or phase, 
mark it as completed in the plan document. 
do not stop until all tasks and phases are completed. 
do not add unnecessary comments or jsdocs, 
do not use any or unknown types. 
continuously run typecheck

Каждая часть важна:

• «implement it all» — делай всё, не пропускай шаги
• «mark it as completed» — plan.md становится live-трекером прогресса
• «do not stop» — не останавливайся переспросить (Claude обожает это делать на полпути)
• «no unnecessary comments» — никакого AI-мусора вроде «// Helper function to process data»
• «continuously run typecheck» — ловить баги в зародыше, а не в конце

Имплементация должна быть скучной и механической. Вся творческая работа уже сделана в цикле аннотаций.

Обратная связь: коротко и жёстко

Если Claude свернул не туда в процессе имплементации, Борис не пишет сложные промпты. Три стратегии:

Короткие тычки: «You didn't implement the deduplicateByTitle function», «move it to admin app», «wider», «2px gap». Никаких объяснений — только факт.

Ссылка на существующий код: «this table should look exactly like the users table». Claude прочитает файл-референс и скопирует паттерн. Надёжнее любого текстового описания.

Откат вместо патчинга: Если подход сломался — не пытайтесь чинить промптами. git checkout ., сужение scope, новый заход. Борис формулирует так: «I reverted everything. Now all I want is...»

Когда это оверкилл

Честно: на мелких багфиксах и задачах на 5 минут весь этот воркфлоу избыточен. research.md → plan.md → annotation cycle для фикса опечатки? Смешно.

Методология заточена под фичи средней и крупной сложности в зрелых кодовых базах. Там, где неправильная имплементация сломает кэширование, нарушит конвенции или продублирует логику. Для быстрых правок — обычный чат с Claude Code без церемоний.

На HN несколько разработчиков с большими кодовыми базами (30K+ LOC) предложили компромисс: разбивать план на серию маленьких пакетов, реализуемых атомарными коммитами. Не один гигантский plan.md, а цепочка коротких планов. Так откат дешевле, и каждый кусок проверяем по отдельности.

Что на самом деле тут важно

Самый точный комментарий на HN: суть не в плане как таковом, а в том, что модель вынуждена выложить свои предположения до того, как закодирует их. Когда Claude пишет research.md — вы видите, что он понял, а что нет. Когда пишет plan.md — видите, куда собирается двигаться. И каждый раз можете скорректировать курс текстом, а не дебагом.

Это сдвиг от «prompt engineering» к «architecture engineering». Кто умеет проектировать системы — тот выигрывает с AI-кодингом. Остальные продолжают подбирать магические слова.

Кому это важно

• Разработчику — попробуй этот воркфлоу на следующей фиче среднего размера. Создай research.md и plan.md до первой строчки кода. Сравни результат с обычным подходом.
• Тимлиду — plan.md можно ревьюить вместе с командой ДО имплементации. Это сокращает количество итераций на PR и ловит архитектурные ошибки раньше.
• Следишь за рынком — тренд: AI-кодинг сдвигается от промпт-инжиниринга к архитектурному мышлению. Ценность разработчика — не в том, чтобы набирать код, а в том, чтобы проектировать правильный план.

Как попробовать

1. Установите Claude Code, если ещё нет: npm install -g @anthropic-ai/claude-code
2. На следующей фиче начните с research — попросите Claude изучить нужную часть проекта с «deeply, in great details» и записать результат в research.md
3. Попросите написать plan.md и добавьте «don't implement yet» — пройдите 2-3 цикла правок в редакторе
4. Когда план готов — одна команда: «implement it all, do not stop, continuously run typecheck»
5. Для обратной связи — короткие тычки и ссылки на существующий код, не длинные промпты
6. Полная статья Бориса Тане — там больше примеров и нюансов, а обсуждение на HN стоит прочитать ради альтернативных подходов