Issue-to-PR workflow: від тикета до плану

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 Note

Investigation Note

Implementation Plan

Дуже важливо зрозуміти одну річ: у поточному модулі нас цікавить насамперед перша половина цього ланцюжка. Не «як швидше написати код», а «як зробити так, щоб код взагалі було безпечно писати». Це страховка від хаосу: трохи часу наперед, щоб потім не лагодити наслідки неправильно зрозумілої задачі.

І так, тут доречна проста аналогія. Писати код за сирим тикетом без intake і плану — це як ремонтувати машину за голосове «там щось стукає праворуч». Іноді вгадаєте. Але частіше спершу треба відкрити капот, послухати, зрозуміти, що зламалося, — і лише потім брати інструменти. Навіть Claude не варто лагодити все по звуку з голосового.

3. Роль Claude Code і зона вашої відповідальності

На цьому етапі особливо корисно зняти одну небезпечну ілюзію: issue-to-PR loop — це не змагання, хто «головніший», а розподіл праці. Claude прискорює аналіз, пошук, чернетки планів, формулювання ризиків, PR-опис. Але інженерні рішення він не ухвалює — відповідальність за зміну лежить на розробнику та команді.

Зручно мислити так:

Якщо перевести це на практичну мову, то для нашої 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, а контракт результату.

Найважливіше тут — refactor. Багато розробників люблять ставитися до нього як до чогось на кшталт «трохи покращу по дорозі». Але щойно ви покращуєте «по дорозі», refactor маскує окрему задачу. В issue-to-PR loop він залишається тим самим issue, просто з іншим acceptance criterion: behavior preserved. Стару поведінку збережено, а наявні перевірки не мають раптово посивіти від жаху.

Це розвантажує голову: не п’ять процесів для п’яти типів задач, а один цикл, де змінюється лише нижній контракт. Коли workflow один, ви рідше губитеся, а Claude Code стає помічником, а не генератором хаосу з дуже доброю дикцією.

5. Артефакти, які не дають задачі розповзтися

Розмова про workflow швидко стає абстрактною, якщо не зафіксувати її в артефактах. «Ми все зрозуміли» — поганий формат пам’яті. Особливо якщо «ми» — це ви о 11:00, 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.

skills/issue-analysis/

mcp/issue-tracker.json

agents/reviewer.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
і заодно трохи спростив повʼязаний checkout code.

На папері звучить навіть мило. На практиці тут сховані всі майбутні головні болі. Чому саме OrderController? Хто вирішив змінювати формат відповіді? Навіщо «заодно» спрощувати related code? Чому ви впевнені, що справа не в OrderService.calculateTotal() або в загальній обробці винятків? Де план перевірки? Чому задача роздулася раніше, ніж ви домовилися, що саме виправляєте?

Дорослий старт нудніший, але надійніший:

Поки не змінюй файли.
Спочатку поверни:
- як зараз проходить POST /api/orders з порожнім items[],
- де саме виникає 500,
- які тести вже є,
- що в тикеті залишається неясним,
- які межі зміни ти пропонуєш.

Саме така нудьга потім економить години. Вона відокремлює розуміння від дії і дає шанс вчасно зупинитися. Якщо issue ширше, ніж здавалося. Якщо для «простого виправлення» потрібно змінювати загальний формат помилки. Якщо в того самого розрахунку є ще один consumer, і «маленький fix» перетворюється на повноцінну зміну поведінки.

У хорошій роботі з Claude Code немає нічого героїчного — і це чудова новина. Не треба сподіватися на магію одного промпта. Треба просто не давати невизначеності ховатися всередині гарного diff. Щойно задача переходить із режиму «зроби issue» в режим issue → intake → investigation → plan → slices, ви вже працюєте як інженер. І лише після цього має сенс відкривати файли.