Від prompting до task spec: як перетворити розпливчасте прохання на інженерне формулювання задачі

1. «Зроби нормально» — це не задача

У чаті можна говорити по-людськи: «підправ тут», «зроби акуратніше». Claude Code працює з файлами, командами й Git — розпливчастість тут коштує дорого.

«Додай нотатки до повернення» зрозуміло тому, хто тримає в голові бізнес-контекст та архітектуру. Claude — ні. Для нього за фразою одразу йде пачка недомовлених рішень: поле лише у формі чи ще й у базі? Показувати в картці? Надсилати в події refund.created? І чи можна «заодно» підправити сусідній код, який «виглядає не дуже»? Це «заодно» і є helpful overreach — самодіяльність за межами задачі, яку потім хочеться відкотити.

Порівняйте:

Погано:
Додай notes до повернення.

Краще:
Додай необов’язкове поле notes у сценарій створення refund-request
в адмінці. Поле має зберігатися разом із поверненням і відображатися
в картці повернення. Не змінюй пороги auto/manual approval.
Покажи змінені файли та підсумковий diff.

У другому формулюванні в Claude є межі — не бюрократія, а страховка від сюрпризів.

Розпливчастий prompt → Claude домислює відсутнє → зміна розповзається → ви довго дивитеся в git diff, бажаючи одне поле, а отримавши міні-реформу модуля повернень.

2. Що таке task spec

Інженерна специфікація задачі, або просто task spec, — це коротка специфікація задачі для coding agent. Не трактат на сорок сторінок і не документ, який треба друкувати на гербовому папері. Це робоча угода між вами та Claude Code: що саме змінюємо, навіщо змінюємо, де проходять межі й який результат на виході вважається правильним.

Якщо хочеться аналогії, task spec схожий на добре складене технічне завдання для майстра. Фраза «зробіть мені кухню затишнішою» — це побажання. Фраза «замінити стільницю, не чіпати проводку, зберегти стару мийку, закінчити до пʼятниці» — уже інженерне формулювання. Claude Code, як не дивно, любить другий варіант не менше за людей.

Дуже важливо не плутати task spec з CLAUDE.md. Різниця між ними проста:

Якщо правило звучить як «у цьому проєкті не додаємо залежностей без обговорення», йому місце в CLAUDE.md. Якщо правило звучить як «у цій задачі не чіпаємо пороги approval», це вже частина task spec.

Ще одна корисна думка: хороший issue в трекері й хороший task spec дуже схожі. Не тому, що хтось любить копіювати текст між файлами, а тому, що обидва артефакти відповідають на одні й ті самі базові запитання. Різниця лише в адресаті. Issue допомагає команді зрозуміти задачу. Task spec допомагає Claude виконати її без зайвих фантазій.

3. Вісім запитань, які тримають задачу в межах

Щоб task spec не перетворювався на потік свідомості, зручно проганяти його через вісім простих запитань. Це не магічна методика й не секретний ритуал. Просто добрий каркас, який не дає задачі розповзтися. І так, саме на такому каркасі потім зручно збирати TASK_SPEC.md draft.

Ось ці вісім запитань:

Зверніть увагу на останній рядок. Це запитання новачки часто забувають. Іноді Claude потрібен не код, а, наприклад, лише аналіз або список зачеплених файлів. Іноді потрібен саме reviewable diff із тестами. Іноді — короткий план. Якщо ви не називаєте очікуваний артефакт, Claude знову починає домислювати за вас, а ця звичка, як ми вже помітили, рідко закінчується нудно.

На практиці ці вісім запитань найкорисніші як перевірочний список. На його основі потім зазвичай збирають більш компактний робочий каркас: спочатку формулюють Goal, потім фіксують Current behavior і Desired behavior, далі обмежують поверхню змін через Scope, Non-goals і Affected area, а вже після цього додають Constraints. Питання «Як перевіримо результат?» краще тримати в голові вже зараз, щоб задача не закінчувалася словом done, але при цьому не роздувати її відразу в окремий шар формальної верифікації. А питання про артефакт частіше взагалі живе як коротка позначка: потрібен аналіз, спочатку план або diff, який зручно переглядати.

Важливо інше: поки документ відповідає на ці запитання й не залишає задачу розпливчастим побажанням, він працює як task spec.

4. Tiny spec і full spec: розмір залежно від ризику задачі

Тут часто кидає з однієї крайності в іншу. Одні починають писати розгорнуту специфікацію навіть на виправлення описки, ніби збираються запускати супутник. Інші, навпаки, приходять із фразою з трьох слів до задачі, яка чіпляє форму, базу, події та бізнес-правила. І те, й інше незручно. Добрий стиль — добирати розмір task spec під ризик задачі.

Зручно дивитися на це так:

Tiny spec — це не халтура. Це просто компактне формулювання, коли задача справді маленька. Наприклад:

Виправити підпис `Refund requset` на `Refund request`
у заголовку форми повернення в адмінці.
Нічого, крім тексту заголовка, не змінювати.
На виході потрібен невеликий diff в одному файлі.

Цього досить. Тут майже немає простору для творчої самодіяльності. Claude розуміє, де зона змін і що вважати готовим.

А ось задача рівня Commerce OS з полем notes у refund-request уже просить іншого формату:

Додати необов’язкове поле `notes` у сценарій створення refund-request.
Поле має бути доступне оператору в адмінці, зберігатися разом із поверненням
і відображатися в картці повернення. Не змінювати поточні пороги auto/manual approval.
Потрібен reviewable diff зі змінами у формі, збереженні даних і пов’язаних тестах.

Це все ще не величезний документ. Але це вже full spec, тому що задача зачіпає поведінку системи в кількох місцях і легко може «зачепити» сусідню логіку.

Якщо зовсім просто, tiny spec підходить, коли ви майже не ризикуєте. Full spec потрібен, коли Claude може зробити щось розумне, але не те. А саме такі помилки обходяться найдорожче: вони виглядають корисними, доки ви не доходите до перегляду diff.

5. Перетворюємо raw issue на чернетку task spec

Тепер візьмемо реалістичний приклад із Commerce OS. Нехай у трекері лежить задача F-03: Add notes field to refund-request. Для людини вона вже на рівні issue може виглядати цілком пристойно:

F-03: Додати поле notes у refund-request

Операторам потрібна вільна нотатка під час створення refund-request з адмінки.
Нотатка має бути видима фінансовим ревʼюерам пізніше.
Додати нотатку в payload події `refund.created`.
Поточні пороги approval мають залишитися без змін.

Для команди це вже непоганий запис. Зрозуміла бізнес-мета, зрозумілий очікуваний ефект, і навіть одне важливе обмеження вже названо. Але для Claude Code такого issue все ще недостатньо. Не тому, що Claude «дурний», а тому, що coding agent працює буквально. Якщо не назвати зону змін, межі, формат результату та спосіб перевірки, він знову почне доповнювати пропущене власними здогадками.

У issue й task spec тут виникає дуже корисний поділ:

Тобто issue відповідає на запитання «навіщо ця задача потрібна бізнесу й команді», а task spec — на запитання «як Claude має працювати з нею в репозиторії».

Це важливий перехід. Ви не переписуєте issue заради гарного Markdown. Ви переводите людський опис задачі в інженерну форму, придатну для роботи coding agent. І саме тут закінчується просто prompting і починається інженерна робота з AI як частиною процесу.

6. Перший TASK_SPEC.md draft для Commerce OS

Нижче — перша робоча чернетка для задачі F-03. Це не фінальний вигляд файла на всі випадки життя, а стартова чернетка, де поруч лежать і основні частини специфікації, і дві допоміжні позначки про перевірку та очікуваний формат відповіді. Так простіше спочатку побачити всю карту задачі, а потім стиснути її до стійкіших блоків. І цього вже достатньо, щоб Claude почав працювати не як ворожка, а як акуратний виконавець у межах репозиторію.

# TASK_SPEC.md

## Що змінюємо
Додаємо необов’язкове поле `notes` у сценарій створення `refund-request`
в адміністративній частині Commerce OS.

## Навіщо
Оператору потрібен спосіб передати контекст щодо повернення, щоб фінансовий
ревʼюер пізніше бачив причину й деталі рішення прямо в картці повернення.

## Де змінюємо
Ймовірно, зачеплені: форма створення повернення в адмінці, backend-flow
створення повернення, зберігання даних повернення, картка повернення та подія
`refund.created`.

## Що входить у scope
Поле у формі, збереження значення, відображення в detail view,
передавання поля в `refund.created`, оновлення пов’язаних тестів.

## Що не входить
Не змінюємо thresholds для auto/manual approval, не чіпаємо payment processing,
не робимо refactor сусіднього коду «заодно», не змінюємо unrelated formatting.

## Які обмеження діють
Не додавати нові залежності без явної потреби.
Diff має залишатися невеликим і reviewable.
Якщо зі схемою зберігання є неясність, спочатку повернути короткий план, а не правити навмання.

## Як перевіряємо
Показати список змінених файлів.
Підтвердити, що `notes` зберігається, відображається і потрапляє в подію.
Запустити пов’язані тести й повідомити про ризики, що залишилися.

## Який артефакт очікуємо
Невеликий reviewable diff + оновлені тести за зачепленим сценарієм.

Два останні розділи — це позначки, а не повноцінні блоки. Як перевіряємо нагадує, що задача не закінчується словом готово, але повноцінний шар критеріїв приймання та верифікації тут ми ще не розгортаємо. Який артефакт очікуємо уточнює формат відповіді — план, аналіз або diff, який зручно переглядати.

Тон змінюється: немає «зроби добре» — є зона роботи, бізнес-сенс, заборони, очікування й формат результату. Задача не стала простою, але стала керованою. Тут prompt перестає бути просто prompt — він стає task spec.