Implementation Plan: риски и проверки

1. Карта — ещё не маршрут

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

Investigation Note отвечает на вопрос «Где живёт проблема?». Но это ещё не план — это карта местности, а не маршрут. Карта показывает мост и реку, но не говорит, ехать через мост или объезжать, потому что он в ремонте. С кодом так же: баг связан с OrderController, OrderService, GlobalExceptionHandler и тестами checkout — но где ставить защиту, как вернуть 400 и чем доказать, что валидный checkout не сломан, ещё непонятно.

Удобно держать в голове очень простую цепочку:

Issue Intake Note → Investigation Note → Approved plan → только потом изменения

Если перескочить через утверждённый план, Claude превращается в очень старательного помощника, который отремонтирует полквартиры, пока вы просили подтянуть дверную ручку. Он не злой, он помогает слишком широко. Ваша задача — дать ему не только направление, но и границы.

2. Слово approved решает всё

Теперь давайте заземлим термин. Implementation Plan — не документ «для порядка» и не любовь к табличкам, а согласованный человеком черновик будущей реализации. Живёт рядом с Issue Intake Note или отдельным блоком в TASK_SPEC.md. Смысл один: до старта кодовых изменений вы фиксируете маршрут и проверяете, что он адекватен.

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

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

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

Подготовь черновик плана по задаче про empty cart в checkout.
Не меняй код.
Верни: goal, scope, non-goals, affected files, steps, risks,
verification strategy, stop conditions.
Если доказательств не хватает, пометь unknown, а не угадывай.

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

3. Каждая секция — на свой вопрос

Когда вы впервые видите хороший Implementation Plan, возникает странное ощущение: он одновременно очень простой и очень дисциплинирующий. Лишней философии в нём нет, зато каждая секция отвечает на отдельный практический вопрос. А если какая-то секция отсутствует — это почти всегда не мелочь, а дырка, через которую позже вылезет scope creep или непроверенный риск.

Для нашего Commerce OS давайте возьмём реалистичный тикет: при POST /api/orders с пустым списком товаров backend возвращает 500, а должен 400 с понятной validation error. Ниже — не огромный документ, а удобная карта секций, которые в плане должны быть.

Goal

Scope

Non-goals

Affected files

Ordered steps

Risks

Verification strategy

Stop conditions

Rollback note

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

## Цель
Не давать POST /api/orders с пустым items[] падать в 500;
вернуть понятную validation error.

## Область изменений
Проверка empty cart в checkout, error mapping и связанные тесты.

## Не-цели
Не меняем UI корзины, happy-path checkout и unrelated pricing code.

## Затронутые файлы
OrderService, GlobalExceptionHandler, OrderControllerWebTest
и при необходимости точка входа в OrderController.

Важно ещё одно правило: не копируйте в план весь Issue Intake Note и весь Investigation Note. План — рабочий документ для реализации, а не архив узнанного. Если 90% текста повторяют уже найденные факты, перед вами не маршрут, а пересказ прошлых шагов самому себе.

4. Task risk list: риски лучше назвать до кода

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

Для начинающего разработчика полезно мыслить о рисках не как о чём-то страшном, а как о соседних поверхностях, которые задевает задача. Вокруг empty-cart кейса в Commerce OS обычно всплывают пять типов рисков.

calculateTotal()

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

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

5. Verification strategy: как доказать результат

Вот здесь план перестаёт быть просто «списком шагов» и становится инженерным документом. Потому что любую задачу можно красиво описать, но без verification strategy у вас остаётся только надежда. А надежда, как известно, прекрасное человеческое чувство и очень слабый технический инструмент.

В этом курсе вы уже видели базовый план проверки. Здесь мы используем ту же идею, только применяем её к конкретной крупной задаче. Не пугайтесь слова strategy: речь не про многостраничную QA-методологию. На этом уровне это очень приземлённый ответ на вопрос: что именно мы запускаем, проверяем и считаем достаточным доказательством.

Для нашего примера с empty cart секция может выглядеть так:

## Стратегия проверки
1. Запустить targeted web/API test на POST /api/orders с пустым items[].
2. Добавить сценарий: empty cart возвращает 400, а не 500.
3. Проверить ручным запросом, что response body остаётся в согласованном validation format.
4. Убедиться, что валидный checkout с непустым items[] ведёт себя как раньше.
5. Если выяснится, что нужен общий redesign error schema, остановиться.

Заметьте: хорошая verification strategy всегда конкретна. Фраза «погонять тесты» — плохая. Она не говорит, какие именно тесты, на каком уровне и что будет считаться успехом. А вот формулировка «добавить сценарий, где empty cart возвращает 400, а не 500» уже подходит: она измеряема, понятна и привязана к задаче.

Очень важно не перепутать verification strategy с полным дизайном тестов. Здесь мы ещё не проектируем всю test strategy и не обсуждаем весь локальный harness. Мы просто фиксируем нижний контракт проверки для этой задачи. Иначе говоря: что вы должны увидеть, чтобы честно сказать «да, это изменение работает и не разнесло соседнее поведение».

Для начинающего разработчика полезно запомнить ещё один нюанс. Ручная проверка здесь не запрещена. Если вы не можете покрыть всё автоматикой немедленно, ручной шаг допустим — но он должен быть узким и воспроизводимым. «Потыкать руками, вроде ок» — плохая проверка. «Отправить POST /api/orders с пустым items[] и убедиться, что приходит согласованная validation error» — нормальная. Разница маленькая по словам и огромная по пользе.

Если задача подходит для работы по цели — этот режим мы вводили в уровне 6, а на TDD разбираем дальше в курсе, — то verification strategy должна явно содержать машинно-проверяемое условие финиша: список команд и ожидаемых результатов, по которым автоматический цикл понимает, что задача завершена. Тогда план перестаёт быть «списком шагов для человека» и становится спецификацией для цикла «по цели» — через slash-команду вроде /goal или скриптованный цикл claude -p (точное имя и доступность могут меняться от версии к версии). Если хотя бы один пункт готовности субъективен, условие финиша разделяется на машинную часть для автоматического цикла и человеческую — для одобрения.

6. Stop conditions и rollback notes

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

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

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

## Заметка про откат
Изменение должно помещаться в один логический откат.
Схемных и data-миграций в рамках задачи не допускается.
Если новая обработка empty cart ведёт себя неверно,
мы откатываем локальный fix целиком и возвращаемся
к последнему стабильному поведению ветки без каскадных изменений.

Чем скучнее rollback note, тем лучше. Серьёзно. Если для отката нужна отдельная баллада о доблести и жертвах, значит, задача с самого начала была слишком широкой.

7. Три артефакта — три вопроса

Когда документов вокруг одной задачи становится больше одного, начинаются первые путаницы. Это нормально. Особенно если названия кажутся похожими и везде есть «goal», «risks» и «files». Поэтому здесь полезно один раз очень чётко разложить роли артефактов. После этого работать становится заметно легче.

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

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

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

8. Сквозной пример Commerce OS: approved plan

Давайте соберём всё вместе в одном компактном примере, чтобы у вас остался не абстрактный набор терминов, а вполне осязаемый образ готового документа. Возьмём наш Commerce OS и задачу про пустую корзину в checkout. Intake уже сделан, investigation уже нашёл нужные сервисы, тесты и unknowns. Теперь из этого рождается утверждённый человеком план.

Сначала полезно попросить Claude собрать черновик, а не финальное решение:

На основе intake и investigation подготовь черновик плана.
Не меняй код.
Нужно вернуть только:
goal, scope, non-goals, affected files, ordered steps,
task risk list, verification strategy, stop conditions.
Не придумывай то, чего нет в evidence.

После этого вы правите черновик глазами инженера, а не человека, которому уже очень хочется нажать Enter и увидеть diff. В итоге план может принять примерно такую форму:

## Цель
Не давать POST /api/orders с пустым items[] падать в 500;
вернуть согласованную validation error на HTTP-уровне.

## Область изменений
Валидация empty cart в checkout, error mapping и связанные API tests.

## Не-цели
Не меняем UI корзины, happy-path checkout и unrelated pricing logic.

## Затронутые файлы
OrderService.java, OrderController.java,
GlobalExceptionHandler.java, OrderControllerWebTest.java.

## Упорядоченные шаги
1. Добавить reproducing check для POST /api/orders с пустым items[].
2. Закрыть empty-cart validation рядом с calculateTotal() не меняя unrelated pricing behavior.
3. Переиспользовать текущий error mapping или минимально расширить его,
   чтобы вернуть 400 вместо 500.
4. Прогнать targeted tests и воспроизводимый запрос;
   подтвердить, что валидный checkout unchanged.

Потом к нему добавляются список рисков и стратегия проверки — и вот здесь план становится по-настоящему approved, а не просто «звучит разумно».

## Список рисков задачи
- medium: можно задеть shared callers calculateTotal()
- medium: фронтенд может зависеть от текущего error format
- high: если для фикса нужен общий redesign error schema,
  задача выходит за scope

## Стратегия проверки
- targeted web/API test на empty cart
- ручной POST /api/orders с пустым items[]
- подтверждение, что валидный checkout с непустыми товарами
  не изменил поведение

## Условия остановки
- нужен общий redesign error schema
- неясны shared callers calculateTotal()
- diff уходит в unrelated checkout/pricing модули

Если хотите добавить ещё один предохранитель, можно прогнать этот план через reviewer-agent из вашего Workflow Kit — не для того, чтобы он «разрешил» изменения, а чтобы он нашёл дыры в доказательной базе или слишком широкие шаги.

Проверь черновик плана как reviewer.
Смотри только на полноту и границы:
есть ли лишний scope, не пропущены ли риски,
привязаны ли шаги к verification.
Код не меняй.

В этот момент уверенное «кажется, мы поняли задачу» превращается в спокойное «мы знаем, что именно делаем, чем рискуем и как поймём, что сделали правильно». Это документ, который можно показать другому инженеру, обсудить, поправить, разрезать на reviewable slices и только потом отдавать в реализацию.

Отдельный случай — когда план приходит из облачного планировщика, который мы упоминали в предыдущей теме этого уровня (условно /ultraplan). Формат результата обычно сразу содержит все три артефакта — план реализации, список рисков, стратегию проверки — и часто заметки самопроверки. Читать и утверждать такой план нужно по той же схеме, что и план, собранный локально: проверить границы задачи, non-goals, затронутые файлы, последовательность шагов, риски и команды для проверки. Облачный планировщик не заменяет ваше одобрение — он ускоряет черновую проработку и расширяет контекст исследования.

1

Задача

Claude code, 17 уровень, 3 лекция

Недоступна

Draft Implementation Plan внутри Claude CLI

Draft Implementation Plan внутри Claude CLI

Открыть

1

Задача

Claude code, 17 уровень, 3 лекция

Недоступна

Подготовка полного Implementation Plan

Подготовка полного Implementation Plan

Открыть