1. Старт нового блока не с кода
После большого блока про skills, agents и MCP легко поймать ложное ощущение, будто дальше всё сводится к одному нажатию кнопки: запустил умный workflow — и Claude сам как-нибудь добежит до PR. На практике всё менее романтично, зато куда полезнее. Утром в трекере лежит issue, и кто-то должен превратить его в инженерную задачу.
Возьмём наш Commerce OS. Представьте, что в трекере появляется такой тикет:
Issue #482
Не оформляется заказ, если корзина пустая.
На фронте показывается общая ошибка.
Ожидаем понятное сообщение для пользователя.
Наверное, надо добавить проверку в OrderController.
Скриншот и stack trace приложены.
На первый взгляд всё ясно. Ну что тут думать, правда? Открыли Claude и написали: «Исправь empty cart в checkout». Но если присмотреться, тикет полон неопределённости. Что значит «не оформляется»? Где рождается ошибка — в OrderController, в сервисе или в общей обработке исключений? Пустая корзина — невалидный checkout или допустимое промежуточное состояние? Достаточно 400, нужен ли отдельный error code, чего ждёт фронтенд? Почему уверены, что дело в OrderController, а не глубже? И есть ли уже тесты, или их придётся написать?
Профессиональная разработка начинается здесь — когда вы признаёте: сырой issue это ещё не инструкция к изменению, а входящий сигнал. Иногда хороший, иногда опасно туманный. Стартуете с кода слишком рано — получите красивый diff, который исправил что-то не то. Программирование в жанре «ну вроде стало лучше». А «ну вроде» в кодовой базе заканчивается очень конкретно.
2. Полная карта issue-to-PR loop
Чтобы не превращать каждый тикет в импровизацию на тему «сейчас разберёмся по ходу», полезно увидеть весь цикл целиком. Тогда становится ясно: код — это только часть маршрута, а не весь маршрут. Сильный workflow — не один промпт, а цепочка небольших решений, у каждого свой вход, выход и цель.
Упрощённо:
Issue
↓
Issue Intake Note
↓
Investigation Note
↓
Implementation Plan
↓
PR slices
↓
Код и проверки
↓
Diff review
↓
PR
Если разложить это чуть аккуратнее, получается такая карта:
| Этап | Что делаем | Что остаётся на выходе |
|---|---|---|
| Issue | Читаем задачу как инженерный документ | Исходный сигнал из трекера |
| Intake | Выделяем проблему, влияние, известные факты и неизвестное | |
| Investigation | Исследуем codebase без правок, ищем точки изменения и риски | |
| Plan | Формулируем порядок действий, scope, verification, stop conditions | |
| Decomposition | Режем задачу на маленькие шаги, удобные для ревью | список PR slices |
| Implementation | Вносим изменения маленькими шагами | diff |
| Verification | Гоняем нужные проверки | test/build/check evidence |
| Review | Читаем diff, проверяем scope и риски | PR-ready change |
Очень важно понять одну вещь: в текущем модуле нас интересует прежде всего первая половина этой цепочки. Не «как быстрее написать код», а «как сделать так, чтобы код вообще было безопасно писать». Это страховка от хаоса: авансом немного времени, чтобы потом не чинить последствия неверно понятой задачи.
И да, здесь уместна простая аналогия. Писать код по сырому тикету без intake и плана — это как чинить машину по голосовому «там что-то стучит справа». Иногда угадаете. Но чаще сначала надо открыть капот, послушать, понять, что сломалось, — и только потом брать инструменты. Даже Claude не стоит чинить всё по звуку из голосового.
3. Роль Claude Code и зона вашей ответственности
На этом этапе особенно полезно снять одну опасную иллюзию: issue-to-PR loop — это не соревнование, кто «главнее», а разделение труда. Claude ускоряет анализ, поиск, черновики планов, формулировку рисков, PR-описание. Но инженерные решения он не принимает — ответственность за изменение лежит на разработчике и команде.
Удобно мыслить так:
| Где помогает Claude Code | Что всё равно решаете вы |
|---|---|
| читает issue и комментарии | достаточно ли понята задача |
| ищет релевантные файлы и тесты | какой scope принимаем |
| предлагает implementation plan | какой план утверждаем |
| перечисляет риски и open questions | какие риски допустимы |
| помогает собрать verification steps | что считаем достаточной проверкой |
| позже готовит diff summary и PR draft | можно ли это мёржить |
Если перевести это на практический язык, то для нашей checkout-задачи с empty cart Claude включается уже на первом шаге. Например, так:
Прочитай issue #482 через issue-tracker.
Пока не меняй файлы.
Собери короткую заметку:
- в чем проблема,
- на кого она влияет,
- что уже известно,
- что пока неясно,
- какие риски видны уже сейчас.
А чуть позже — уже так:
На основе intake и investigation подготовь черновик плана.
Не редактируй код.
Верни:
- цель,
- scope,
- non-goals,
- затронутые файлы,
- шаги,
- риски,
- проверки,
- условия остановки.
Обратите внимание на повторяющийся мотив: пока не меняй файлы. Это по-настоящему взрослая фраза. Она отделяет анализ от редактирования. Новичок часто хочет смешать всё в один запрос, потому что кажется, будто так быстрее — но только до первого неверного поворота. Дальше — «подправь ещё это», «верни как было», «а почему тесты упали», и сессия превращается в археологический раскоп.
Здесь же естественно возвращаются инструменты из Workflow Kit. issue-analysis skill держит структуру intake, issue-tracker MCP приносит контекст тикета без копипаста, reviewer-agent ловит пропущенные риски или scope creep. Даже если названия команд в вашей версии Claude Code отличаются, ориентир прежний: текущий /help, актуальная документация и настройки проекта. Логика цикла не меняется.
4. Bug fix, feature и refactor по одному маршруту
На этом месте многие удивляются. Кажется, будто bug fix — одно, feature request — другое, а refactor вообще живёт в параллельной вселенной, где ходят в водолазках и произносят слово «архитектура» с опасной интонацией. Но на практике все эти задачи идут одним маршрутом. Меняется не workflow, а контракт результата.
| Тип задачи | Что меняется в критериях приемки |
|---|---|
| Bug fix | баг воспроизводился до изменения и больше не воспроизводится после; желательно есть regression evidence |
| Feature | появился новый пользовательский сценарий или новое поведение |
| Refactor | внешнее поведение сохраняется, код становится проще или чище |
| Docs update | документация соответствует реальному коду и командам запуска |
| Migration | сохраняется нужная совместимость, есть валидация и продуманный rollback |
Самое важное здесь — refactor. Многие разработчики любят относиться к нему как к чему-то в духе «слегка улучшу по пути». Но как только вы улучшаете «по пути», refactor маскирует отдельную задачу. В issue-to-PR loop он остаётся тем же issue, просто с другим acceptance criterion: behavior preserved. Старое поведение прежнее, а существующие проверки не должны внезапно поседеть от ужаса.
Это разгружает голову: не пять процессов для пяти типов задач, а один цикл, где меняется только нижний контракт. Когда workflow один, вы реже теряетесь, а Claude Code становится помощником, а не генератором хаоса с очень хорошей дикцией.
5. Артефакты, которые не дают задаче расползтись
Разговор о workflow быстро становится абстрактным, если не зафиксировать его в артефактах. «Мы всё поняли» — плохой формат памяти. Особенно если «мы» — это вы в 11 утра, Claude в длинной сессии и будущий вы в 16:40, который уже не помнит, почему решили не трогать API-контракт.
Поэтому цикл держится на документах-переходниках. Issue Intake Note — ранний, обогащённый тикетом черновик уже знакомого вам TASK_SPEC.md; Investigation Note привязывает задачу к реальным файлам, тестам и evidence; Implementation Plan фиксирует маршрут, границы, риски и проверку; PR slices режут approved plan на порции под ревью. Не зоопарк новых сущностей — просто способ не держать весь маршрут в голове.
Обратите внимание: эти документы не «про бюрократию». Они про управление изменением. Есть intake note — не спорите с тикетом на уровне впечатлений. Есть investigation note — не гадаете, где живёт проблема. Есть approved plan и slices — не импровизируете при соблазне «а давай заодно ещё чуть-чуть почистим».
Есть хороший, немного самоироничный способ это запомнить: артефакты существуют не потому, что команда любит markdown, а потому что память у человека конечна, у длинной AI-сессии ещё более конечна, а diff всё равно приходится читать глазами. Документ — не наказание, а внешняя память вашей инженерной дисциплины. И важен не сам факт будущего кода, а reviewable implementation path: цепочка документов и решений, по которой другой инженер поймёт происходящее ещё до первой правки.
6. Workflow Kit возвращается в работу
Может показаться, что с переходом к issue-to-PR мы будто бы «оставили позади» весь предыдущий блок про Workflow Kit. На самом деле всё ровно наоборот: теперь Kit наконец работает по-настоящему, а не в режиме демонстрации, — на реальной задаче Commerce OS.
| Артефакт Workflow Kit | Где помогает в цикле |
|---|---|
|
превращает сырой тикет в структурированный intake |
|
приносит issue, комментарии и labels в контекст |
|
проверяет draft плана и позже diff свежим взглядом |
| project CLAUDE.md | напоминает о границах, командах и правилах проекта |
То есть сегодня мы не «изучаем новый skill» — используем знакомый issue-analysis по назначению. Не «создаём нового агента» — даём reviewer-agent нормальную работу: посмотреть на черновик и сказать, не забыли ли риск, не расползся ли scope, не собираемся ли тронуть пол-проекта, хотя тикет был про один checkout-сценарий.
Workflow Kit не висит рядом с Commerce OS как отдельная витрина — он становится набором рабочих инструментов команды. А Commerce OS из «учебной кодовой базы, где мы иногда что-то ищем», становится нормальным продуктом, где есть issue, ambiguity, risk и необходимость думать до кода.
7. Цена просьбы Claude «просто сделать issue»
Под конец полезно честно посмотреть на самый соблазнительный анти-паттерн. Звучит он очень просто: «Да задача и так понятна, пусть Claude сразу исправит». Этой фразой вы молча склеиваете несколько решений в одно — будто проблема понятна, scope согласован, риски приняты, критерии проверки придуманы. Хотя ничего из этого не произошло.
Вот наивный старт:
Вы: Исправь issue про empty cart в checkout.
Claude: Готово. Я добавил проверку в OrderController,
подправил обработку ошибок, обновил ответ API
и заодно немного упростил related checkout code.
На бумаге звучит даже мило. На практике здесь спрятаны все будущие головные боли. Почему именно OrderController? Кто решил менять формат ответа? Зачем «заодно» упрощать related code? Почему уверены, что дело не в OrderService.calculateTotal() или в общей обработке исключений? Где план проверки? Почему задача распухла раньше, чем мы договорились, что именно исправляем?
Взрослый старт скучнее, но надёжнее:
Пока не меняй файлы.
Сначала верни:
- как сейчас проходит POST /api/orders с пустым items[],
- где именно рождается 500,
- какие тесты уже есть,
- что в тикете остаётся неясным,
- какие границы изменения ты предлагаешь.
Именно такая скучность потом экономит часы. Она отделяет понимание от действия и даёт шанс вовремя остановиться. Если issue шире, чем казалось. Если для «простого исправления» нужно менять общий формат ошибки. Если у того же расчёта есть ещё один consumer, и «маленький fix» превращается в полноценное изменение поведения.
В хорошей работе с Claude Code нет ничего героического — и это отличная новость. Не надо надеяться на магию одного промпта. Надо просто не давать неопределённости прятаться внутри красивого diff. Как только задача переходит из режима «сделай issue» в режим issue → intake → investigation → plan → slices, вы уже работаете как инженер. И только после этого имеет смысл открывать файлы.
ПЕРЕЙДИТЕ В ПОЛНУЮ ВЕРСИЮ