От 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

Engineering task specification, или просто 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.