1. Постановка задачи рождается не с первой попытки
Идеальный запрос с первого раза и безупречный diff в ответ — миф. Рабочая постановка задачи созревает ко второй-третьей версии. Это не слабость: значит, задача настоящая, а не учебная загадка на три строки.
Пример из Commerce OS: возвраты на сумму больше 100 долларов уходят в автообработку, хотя по бизнес-правилам должны ждать ручного подтверждения оператором. Напишете «почини обработку возвратов» — Claude начнёт чинить. Но что он сочтёт проблемой: порог суммы, UI, API, таблицу статусов, очередь задач, поле в базе? Угадывать вашу мысль он не обязан.
Сырая постановка и шаг к рабочей:
Плохо:
«Сделай нормальную обработку возвратов в Commerce OS.»
Чуть лучше:
«Исправь сценарий, при котором возвраты свыше 100 долларов
уходят в автообработку без ручного подтверждения.»Второй вариант описывает наблюдаемую проблему, но и он не финал. Дальше вылезают вопросы. Порог в 100 долларов — жёсткое правило или настройка? Кто подтверждает возврат: оператор, менеджер, финансовый администратор? Менять только серверную логику или ещё показывать в UI статус «ожидает подтверждения»? Что делать с уже созданными возвратами «между мирами»? Нужна ли обратная совместимость для API?
Итерация — не бюрократия, а инженерная работа: идея проблемы → сужение → отделение фактов от предположений → ограничения и проверки. На выходе — рабочий контракт между вами, Claude и кодовой базой.
Правило: задача трогает больше одного файла, меняет заметное поведение или пахнет деньгами, доступами, конфигом — первая формулировка будет черновиком. Хуже самообман «и так понятно», за которым три часа разгребания гигантского diff.
2. Claude interview pattern — вопросы до кода
Задача не умещается в один прозрачный запрос — не пишите сразу полный TASK_SPEC.md. Используйте Claude interview pattern: вы приносите рабочую заготовку, Claude вопросами вытаскивает недостающие детали. На первом шаге он не пишет код — он технический интервьюер.
Паттерн хорош, когда проблема понятна по бизнес-смыслу, но не по инженерным границам. С возвратами так и есть: high-value refund нельзя автоодобрять, но где проходит граница изменений — неясно.
Короткий цикл:
flowchart TD
A[Короткое описание проблемы] --> B[Claude задаёт уточняющие вопросы]
B --> C[Вы отвечаете и сужаете границы]
C --> D[Собирается финальный TASK_SPEC.md]
D --> E[Новая чистая сессия на implementation]
| Шаг | Что происходит | Зачем это нужно |
|---|---|---|
| 1 | Вы даёте краткое описание задачи | Чтобы не писать огромную spec вслепую |
| 2 | Claude задаёт уточняющие вопросы | Чтобы найти пробелы в scope, constraints и verification |
| 3 | Вы отвечаете фактами, а не ощущениями | Чтобы гипотезы не стали ложными «истинами» |
| 4 | Из ответов собирается финальная spec | Чтобы implementation стартовал на понятной базе |
| 5 | Работа начинается в новой сессии | Чтобы не тащить в кодовую фазу черновой шум |
Смотрите, как это может выглядеть на живом примере:
Вы: В Commerce OS возвраты свыше 100 долларов иногда уходят
в автообработку. Не редактируй код. Сначала задай вопросы,
которых тебе не хватает для task spec.
Claude: 1) Где сейчас проверяется сумма возврата?
2) Порог 100 долларов жёстко задан или приходит из настройки?
3) Нужно ли блокировать только автообработку или и ручное создание тоже?
4) Какой статус должен видеть оператор в UI?
5) Что считается успешной проверкой после фикса?Claude вытаскивает неочевидное, и не только про код: настройки, UX, границы поведения, верификацию. После ваших ответов spec крепнет — порог лежит в конфиге refund.autoApprovalThreshold, схему базы не трогаем, публичный API не меняем, оператор видит статус «ожидает ручного подтверждения». «Почини возвраты» становится контролируемой работой с ясным scope.
Нюанс: Claude помогает сформулировать задачу, но не утверждает её — это делаете вы. Лишний вопрос отбрасываете, недостающий риск добавляете сами. Иначе схема опасная: Claude сам придумал ограничения, сам проверил, сам объявил победу.
Признак, что pattern сработал: текста не больше — неопределённости меньше.
3. Implementation — старт в новой сессии
Раунд вопросов прошёл, контекст тёплый — тянет тут же попросить Claude писать код. Здесь начинается болото. Сборка spec и реализация — две разные фазы, и жить им полезно отдельно.
Пока вы обсуждали задачу, в контексте осели черновые гипотезы, отброшенные варианты, старые допущения. Для вас это мышление. Для модели — рабочий материал, который она продолжает учитывать. Так рождается загрязнённая сессия: слишком много следов временных решений.
Разделяйте фазы явно:
Сессия 1: refund-approval-spec
Результат:
- TASK_SPEC.md
- EVIDENCE_LOG.md
Сессия 2: refund-approval-implementation
Вход:
- финальный TASK_SPEC.md
- подтверждённый пакет доказательствТри выигрыша. Implementation стартует на чистом контракте, а не на полутора десятках сообщений. Сломалось — spec не теряется, живёт отдельным артефактом. Следующему человеку не нужно перечитывать весь диалог, чтобы отличить финальную мысль от вчерашней догадки в 22:47.
Загрязнение распознаётся по земным признакам:
| Признак | Что это обычно означает |
|---|---|
| Claude ссылается на старую гипотезу, которую вы уже отбросили | В контексте осталось слишком много чернового шума |
| Он предлагает исправлять сразу несколько несвязанных вещей | Scope начал расплываться |
| Вы сами уже не уверены, что в этой сессии финальное, а что временное | Пора фиксировать spec отдельно |
| После каждого нового сообщения diff становится только шире | Implementation идёт без опоры на контракт |
Новая сессия — не потеря прогресса, а способ сохранить здравый смысл. Длинная беседа без чёткой границы работает против вас.
Правило: задача прошла через вопросы, уточнения и сбор TASK_SPEC.md — значит, заслуживает чистого старта на реализации. Иначе вы построили чертёж, а пишете по памяти, поглядывая на неактуальные черновики.
4. Анти-паттерны в prompting
Анти-паттерн — это не только плохая фраза. Чаще ломается поведение: запрос вежливый, а процесс выстроен так, что задача обречена на хаотичный diff и слабую приёмку. Это повторяющиеся сбои workflow.
Самые вредные:
| Анти-паттерн | Что ломается | Чем заменить |
|---|---|---|
| Fix everything / «почини всё» | Claude сам выбирает scope и почти всегда расширяет его | Дать одну проблему, границы и non-goals |
| Нет критериев приёмки | Непонятно, по чему принимать результат | Описать наблюдаемое поведение до implementation |
| Нет плана проверки | Проверка превращается в импровизацию после diff | Спроектировать проверки заранее |
| Feature + refactor в одном diff | Нельзя понять, что именно сломалось или улучшилось | Разнести на две отдельные задачи |
| «Claude said it works» | Решение принимается по уверенности текста, а не по доказательствам | Читать diff, запускать checks, сверять с готовностью задачи |
| Продолжение polluted session | Старые гипотезы продолжают влиять на implementation | Завершить spec, открыть fresh session |
Два самых коварных стоит разобрать. Fix everything для Commerce OS опасен: возвраты, заказы, поддержка и платежи выглядят связанными, и Claude заодно «подчистит» сервис, DTO, UI-статусы и пару тестов в соседнем модуле. Итог — огромный diff.
Claude said it works означает одно: модель сформулировала уверенное предложение на естественном языке. diff себя не прочитал, тесты себя не интерпретировали, границы никто не проверил. Уверенный тон — не доказательство.
5. Финальный шаблон Task Spec
Теперь у вас есть всё для финального шаблона, который не стыдно отдать Claude, коллеге и себе завтра. Это рабочий контракт, не бумажка для порядка. Заполнен по-настоящему — снимает кучу хаоса до первой правки. Заполнен формально — красивый бесполезный ритуал.
Верх шаблона — Цель и желаемый результат, Текущее поведение и желаемое, Границы задачи, Ограничения — был нужен и раньше. Сегодня добавляем фактическую базу, критерии приёмки, план проверки, Готовность задачи и ожидаемый workflow:
# TASK_SPEC.md
## Цель и желаемый результат
## Текущее поведение и желаемое
## Границы задачи (scope и non-goals)
## Ограничения и границы изменений
## Пакет доказательств (краткая выжимка + ссылка на EVIDENCE_LOG.md, если он вынесен отдельно)
## Критерии приёмки
## План проверки
## Готовность задачи
## Ожидаемый workflow
## Ожидаемый артефактЗа каждой строкой — работа. Верхние секции защищают задачу от расползания и «полезного, но опасного» overreach. Пакет доказательств привязывает её к фактам; если полный журнал в EVIDENCE_LOG.md, здесь хватит выжимки и ссылки. Критерии приёмки, План проверки, Готовность задачи заранее отвечают, по чему принимаете результат. Ожидаемый workflow напоминает маршрут для нетривиальной задачи: Explore → Plan → Implement → Verify → Review → Commit/PR. Ожидаемый артефакт фиксирует, что хотите на выходе: анализ, diff, tests, документацию или изменение под ревью.
Заполните шаблон под Commerce OS — и абстракция станет рабочей вещью. Открываете его в новой сессии: «Вот утверждённая spec. Работай только в этих границах. Упрёшься в противоречие — остановись и задай вопрос». Взрослая позиция не в длине документа, а в том, что главные инженерные решения приняты заранее: что меняем, чего не меняем, как проверяем и когда задача готова.
ПЕРЕЙДИТЕ В ПОЛНУЮ ВЕРСИЮ