ТЗ для агента: як перетворити ідею на завдання

Два запити агенту, один за одним. Перший: "збери сторінку за ТЗ із файлу TZ_LANDING.md". За кілька хвилин у папці з'являється index.html, і має він такий вигляд, як задумано. Другий, того ж вечора: "збери гру 2048". І тут агент або ставить п'ять запитань поспіль, або мовчки збирає поле 5×5 із кнопкою скасування ходу, якої ніхто не просив.

Різниця не в агенті. Різниця в тому, що він отримав на вході. У цій статті розберемо, з чого складається ТЗ для маленького завдання, де взяти зміст, який у нього записати, що робити, коли відомий лише напрямок, і чому після "готово" ви перевіряєте результат за тими самими рядками, що написали до початку.

1. Ідея ще не завдання

"Хочу 2048". "Зроби гарну сторінку". "Зроби нову гру, цікавішу". Усе це ідеї, і в них одна спільна біда: у голові у вас ціла картинка, а в тексті два слова. Агент бачить лише текст.

З порожнім місцем у проханні в агента два шляхи. Перший - запитати. Другий - закрити його самому: вибрати поле, придумати правило, додати кнопку. Другий шлях тихіший і тому небезпечніший. ви не помітите, що рішення ухвалено за вас, доки не побачите результат. Кожне незаповнене місце в проханні - це рішення, яке хтось ухвалить, і за замовчуванням це будете не ви.

"Усі знають, як грати у 2048" - це у вас у голові. Агент це "усі знають" не читає. Яке поле? Звідки беруться нові плитки й коли? Які зливаються і в що? Коли перемога, коли кінець? Для вас одне слово, для нього - порожнє, доки не розкладено на правила. У чаті це має такий вигляд:

Ви:    збери гру 2048
Агент: Уточню перед початком:
       1. Яке поле, 4×4?
       2. Що вважати перемогою?
       3. Чи потрібне скасування ходу?

Це хороший варіант. Буває й інший, на той самий запит:

Ви:    збери гру 2048
Агент: Готово. Гра у файлі index.html:
       - поле 5×5
       - кнопка скасування останнього ходу
       - таблиця рекордів у localStorage

Це не помилка агента. Це три ваші порожні місця, закриті без вас.

Такий вигляд має шлях від ідеї до результату, якому можна довіряти. Стаття проходить його зліва направо. А останній крок повертає до третього: перевірили, знайшли дірку, дописали рядок у ТЗ і віддали агенту знову.

2. Звідки береться зміст

Каркас сторінки чи гри агент збирає за хвилини, і це справді не найважча частина. Важке - знати, що на сторінці має бути і в що взагалі граємо. Цього в коді немає. Це в головах людей, іноді у вас самих, а дещо знає й агент. Добувається воно запитаннями, і джерел три: люди, ви самі, агент.

Люди - це той, хто замовив, і той, хто буде користуватися. Запитання їм краще ставити пачкою. Список із п'яти-шести пунктів за раз, а не по одному запитанню на день. Пачка здається нав'язливою, знаю. Насправді вона економить усім тиждень листування.

Коли замовник - ви самі (своя гра, своя сторінка), запитання ставите собі, і тут головна спокуса відповісти "ну це ж очевидно". Очевидне записується так само, як неочевидне. "Поле 4×4" - це дві секунди, а агенту вони закривають цілу розвилку.

Третє джерело - агент, і тут є пастка, про яку варто знати заздалегідь: ви не можете запитати про те, чого не знаєте. Чи вважається ходом хід, який нічого не зсунув? Чи потрібен свайп на телефоні? Чи показувати рахунок? Ці запитання не спадають на думку, доки гра не опиниться перед очима. А агент бачив тисячу таких ігор і знає, де зазвичай спотикаються. Тому замість "збери" іноді корисніше почати з "давай обговоримо":

Хочу зібрати гру 2048 у браузері. Поки нічого не пиши.
Постав мені запитання, без яких не зможеш почати. Усі одразу, списком.
Я відповім, і потім зберемо ТЗ у файл TZ_2048.md.

Два правила для такої розмови, інакше вона не закінчується. Перше: обговорення закінчено, коли заповнені чотири опори з наступного розділу, і його підсумок - файл, а не чат. Друге: запитання агента - це варіанти, а не вимоги. Він охоче запитає "а таблицю рекордів робимо?", і "ні" - нормальна відповідь. Таке "ні" теж рядок ТЗ, тільки в "не робимо".

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

Три джерела ліворуч, одне місце призначення праворуч. Пунктирна стрілка вниз - шлях, яким відповіді йдуть найчастіше: залишилися в чаті, і через десять повідомлень їх уже не знайти. Стрілка на схемі є, а файлу в її кінці немає.

Агента можна попросити й про більше: не лише запитати, а й самому накидати чернетку ТЗ за вашими відповідями, заповнивши те, чого ви не сказали. Що потім робити з тим, що він додумав, - у розділі 4. Спочатку про те, з чого ТЗ складається.

3. Чотири опори ТЗ

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

# ТЗ: 2048

МЕТА:      браузерна гра 2048, відкривається з файлу, без встановлення.
           HTML, CSS і JavaScript, без збірки

ПРАВИЛА:   поле 4×4
           на старті й після кожного ходу з'являється нова плитка: 2 або 4
           стрілки рухають усі плитки в один бік, до упору
           дві однакові плитки під час зіткнення зливаються в одну із сумою
           перемога: на полі з'явилася плитка 2048
           поразка: ходів немає, поле забите, зливати нічого

НЕ РОБИМО: таблицю рекордів, анімації, скасування ходу

ПЕРЕВІРКА: відкрити index.html у браузері, побачити поле і стартові плитки
           зробити три ходи стрілками, після кожного з'являється нова плитка
           звести дві двійки, отримати четвірку
           дограти до кінця, побачити екран поразки

Далі по одній опорі, і кожна на двох завданнях: гра і сторінка-запрошення на зустріч клубу настільних ігор.

Мета

Перший рядок. Прочитавши його, людина має уявити результат, а не код. "Браузерна гра 2048, відкривається з файлу, без встановлення". "Сторінка-запрошення на зустріч клубу: людина розуміє, що це за зустріч, і записується через кнопку".

Перевірка мети: якщо, читаючи її, ви бачите код, а не те, що побачить людина, - це вже не мета. "Зробити функцію злиття плиток" - не мета, це шматок роботи.

Сюди ж одним рядком "чим збираємо": HTML, CSS і JavaScript, без збірки. Без цього рядка агент вибере сам, і не факт, що вибере те, що ви вмієте запустити.

А "зроби гарно" метою бути не може. Незрозуміло, кому гарно і де це побачити.

Що має відбуватися

Найдовша опора, і для гри вона вже написана вище. Правило одне: рядок хороший, якщо після запуску на нього можна подивитися і сказати "так" або "ні". "Поле 4×4" - так або ні. "Дві однакові плитки зливаються в одну із сумою" - так або ні. "Цікавішу" - ні так, ні ні, і такому рядку в ТЗ не місце.

Одна думка на рядок. "Плитки з'являються і зливаються" - це дві перевірки, отже, два рядки.

Для сторінки те саме, тільки замість правил - що на ній є: "шапка з назвою і датою", "три блоки: що буде, для кого, де", "кнопка Записатися веде на адресу форми". Кожну можна відкрити й побачити.

Такий список здається нудним поруч з ідеєю. Нудно - це і є добре. нудне перевіряється.

Чого в першій версії не буде

Єдина опора, про яку зазвичай забувають, і тому найцінніша. Порожнє місце агент закриває сам, і найохочіше - додаванням. Таблиця рекордів, анімація плиток, кнопка скасування ходу, темна тема. Усе це корисно, і всього цього ви не просили.

Пишеться поіменно. Не "нічого зайвого" - це не межа, а побажання, - а "не робимо: таблицю рекордів, анімації, скасування ходу". Для сторінки: "не робимо: саму форму запису, оплату, галерею фотографій". Трьох імен зазвичай вистачає, десять усе одно ніхто не напише.

Навіщо це вам, а не агенту. Що менше зібрано, то менше перевіряти. І легше зрозуміти, звідки взялося те, що зламалося: у шести рядках шукати простіше, ніж у шести екранах. Ознака того, що межі немає: у вашому проханні або у відповіді агента зачастило слово "заразом".

Як перевіримо

Кожен рядок із "що має відбуватися" - це одна перевірка після того, як агент сказав "готово". Відкрили гру - поле 4×4, так. Натиснули стрілку - плитки поїхали, з'явилася нова, так. Звели дві двійки - четвірка, так. Список перевірок ви не пишете окремо, він уже написаний.

Плюс два-три рядки "перевірка" в самому ТЗ: що саме зробити руками. "Відкрити файл у браузері, зробити три ходи, програти до кінця". Ці рядки пишуться до запиту, а не після. Після результату їх непомітно підганяють під те, що вийшло, - це відбувається саме собою, і з вами теж буде.

"Готово" від агента - репліка, а не перевірка. Перевірка - ваша, за вашими рядками.

Тепер практика. Візьміть прохання "зроби гарну сторінку для зустрічі клубу настільних ігор" і розкладіть його на чотири опори, по рядку-два на кожну. Відповідь одразу нижче, звіртеся:

# ТЗ: сторінка-запрошення

МЕТА:        сторінка-запрошення на зустріч клубу настільних ігор:
             людина розуміє, що це за зустріч, коли і де, і записується через кнопку.
             один файл HTML, стилі всередині

НА СТОРІНЦІ: шапка з назвою клубу і датою зустрічі
             три блоки: що буде, для кого, де
             кнопка "Записатися" веде на адресу форми

НЕ РОБИМО:   саму форму запису, оплату, галерею фотографій

ПЕРЕВІРКА:   відкрити в браузері, побачити шапку і три блоки
             натиснути кнопку, потрапити на адресу форми

Зауважте, що слово "гарну" в ТЗ не потрапило зовсім. Воно не перевіряється. Якщо краса справді важлива, вона розкладається на рядки так само, як усе інше: "одна картинка в шапці", "не більше двох кольорів", "усе вміщається на екран телефону". Це вже можна відкрити й подивитися.

Назви блоків у двох прикладах різні: для гри "правила", для сторінки "на сторінці". Це не важливо, назвіть як зручно. Важливо, що в кожному є чотири опори:

4. Чиє це рішення

У ТЗ з'являються рішення, яких ніхто не погоджував, і трапляється це двома способами. Перший: ви дозволили агенту закрити дірки "чимось розумним", щоб отримати чернетку зараз, а не чекати відповідей до вівторка. Другий: ви самі вирішили за замовника, бо нема в кого запитати або нема коли.

Обидва випадки нормальні. Ненормально - забути, що це припущення. За тиждень ніхто не згадає, хто придумав, що кнопка веде на пошту, а не на форму, і сперечатися будуть саме про це.

Для першого випадку запит агенту має такий вигляд:

Збери чернетку ТЗ для сторінки-запрошення за цими відповідями.
Де відповідей немає - придумай розумне і окремим списком
перелічи, що придумав сам. Запиши у файл TZ_INVITE.md.

Список додуманого читаєте першим, до самого ТЗ. Це рішення, ухвалені за вас: кожне або йде на погодження тому, хто в темі, або залишається в ТЗ із позначкою.

Для другого випадку - позначка в самому файлі. Рядок "припущення:" перед рішенням або просто знак питання в кінці рядка: "кнопка веде на пошту клубу (?)". Коли відповідь прийде, одразу видно, що змінювати. і не треба згадувати, звідки це взялося.

Позначка працює в обидва боки. Агент, якому дали ТЗ зі знаками питання, зазвичай запитує про них насамперед: для нього це такий самий сигнал, як для вас.

5. Пісочниця замість запитань

Буває, що чотири опори не пишуться, скільки не сиди. "Хочу щось на кшталт 2048, але не знаю, чи потрібен рахунок, чи потрібні свайпи, і чи взагалі потрібне поле 4×4". Це не ТЗ і навіть не ідея у звичному сенсі. Це орієнтир: напрямок зрозумілий, результат - ні. Запитання тут не допомагають: відповідей поки немає ні у вас, ні в замовника, а варіанти від агента вам нема з чим порівняти.

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

Пісочниця - це теж ТЗ на чотири опори, тільки мета інша:

# ТЗ: пісочниця 2048

МЕТА:      подивитися, як грати в 2048 у браузері, і зрозуміти, чого хочу.
           HTML, CSS і JavaScript, без збірки

ПРАВИЛА:   поле 4×4
           стрілки рухають плитки, однакові зливаються
           після ходу з'являється нова плитка

НЕ РОБИМО: усе інше: перемогу, поразку, рахунок, свайпи, оформлення

ПЕРЕВІРКА: пограти п'ять хвилин і записати, чого не вистачає і що зайве

Подивіться, що змінилося. Мета - не гра, а розуміння. "Не робимо" - найдовший рядок, у ньому все, у чому ви не впевнені. А перевірка - не "чи працює", а "що я тепер знаю". Пограли п'ять хвилин - і запитання, які не можна було поставити на початку, з'являються самі: свайпи не потрібні, за комп'ютером грають стрілками; рахунок потрібен, без нього нудно; 4×4 мало, хочеться спробувати 5×5; поразку треба показувати, бо інакше незрозуміло, що гра скінчилася.

Ось це і є результат пісочниці. Не код, а відповіді. З них пишеться справжнє ТЗ, і збирається воно з нуля, у чистій папці, однією фразою: "збери гру за ТЗ із файлу". Пісочниця свою справу зробила.

Це той самий ланцюжок із першого розділу, тільки крок "Запитання" тут замінила петля: коли запитати нема про що, спочатку дивимося, потім записуємо. Вниз, у ТЗ, іде одне - відповіді. У пісочниці немає стрілки до агента, і це не забудькуватість: справжню версію він збирає в чистій папці, з нуля. далі все за ланцюжком.

6. ТЗ живе у файлі

Чому файл, а не листування. Листування губиться: через десять повідомлень правило про злиття плиток уже не знайти. Файл лежить у папці проєкту поруч із кодом, агент читає його сам, коли ви на нього вкажете, а поправити й віддати знову можна тією самою фразою. Ім'я будь-яке: TZ_2048.md, TZ_LANDING.md, хоч zavdannia.txt. Це звичайний текстовий файл, жодного спеціального формату він не має.

Віддається він однією фразою. Порівняйте:

Було: "збери гру 2048, ну ти зрозумів яку, цікавішу".

Стало: "збери гру за ТЗ із файлу TZ_2048.md".

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

Що змінювати у файлі, а що казати словами. Орієнтир такий: змінилося правило або межа - правимо файл і віддаємо знову ("перемога при 2048, а не при 1024" - це у файл). Змінилася дрібниця вигляду, яка на правила не впливає, - можна словами ("зроби кнопку синьою"). Сумніваєтеся - у файл: зайвий рядок дешевший за забуте правило.

Про розмір. Для маленького завдання це шість-вісім рядків, як блок для 2048 вище. Якщо ТЗ на гру на один вечір розтяглося на дві сторінки, найімовірніше, у нього потрапило те, що мало потрапити в "не робимо".

І останнє перед тим, як віддати файл агенту: прочитайте його один раз як чужий. Рядок, який не можна перевірити, знайдеться майже завжди. у мене знаходиться.

7. Що агент робить із ТЗ, а що залишається вам

Зберемо все в одну картину: що в цій схемі робить Claude Code, а що залишається на вашому боці. Парами.

Сенс ТЗ не в тому, щоб агент зрозумів. Він і за двома словами щось збере. Сенс у тому, щоб ви самі знали, що замовили, і могли це перевірити.