Спецификация для Claude Code: почему провалы

Меня зовут Арина Михална, и я считаю, что спецификация для Claude Code проваливается не потому, что она плохо написана, а потому что в ней нет критериев приёмки и явных границ — агент честно делает то, что написано, но не то, что ты имел в виду. Хорошая спека — это не абзац текста про фичу, а пять обязательных разделов: цель, контекст, ограничения, критерии приёмки, что не трогать. Ниже — шаблон и чек-лист, по которым можно проверить свою спеку за пять минут.

Почему «хорошая на вид» спека всё равно проваливается

Смотришь на спецификацию — вроде всё есть: что делать, зачем, какой стек. А Claude Code через полчаса выдаёт код, который технически работает, но не решает задачу. Знакомо.

Дело в том, что «подробно» и «однозначно» — разные вещи. Спека может быть на три экрана текста с описанием фичи, дизайна, пользовательских историй — и при этом ни строчки о том, как понять, что задача закончена. Агент дочитывает описание, пишет код, запускает — компилируется, тесты (если есть) зелёные — и останавливается. Он сделал ровно то, что было формально написано. Просто написано было не то, что нужно на самом деле.

Сама несколько раз ловила себя на том, что пишу спеку как для человека — рассчитываю, что агент «поймёт по контексту», что фича должна работать вот так, а не только компилироваться. Не понимает. Контекст для него — это буквально то, что лежит в файле, а не то, что я держу в голове.

Вторая причина провала — отсутствие явных границ. В спеке написано «добавь пагинацию к списку заказов», а не написано, что при этом нельзя трогать существующий API-контракт. Агент добросовестно меняет и то, и другое — и ты получаешь сломанный фронтенд, который об этом контракте ничего не знал.

CLAUDE.md, spec.md, Plan Mode, Beads — кто за что отвечает

Частая путаница — все эти форматы решают разные задачи, и смешивать их означает получить кашу вместо системы. Разложу по таблице, чтобы не гадать каждый раз, что куда писать.

Формат	Что решает	Живёт как	Когда применять
CLAUDE.md	постоянный контекст проекта: стек, конвенции, структура папок	файл в корне репо, обновляется редко	всегда, для любого проекта в Claude Code
spec.md (разовая спека)	конкретная задача/фича: цель, ограничения, критерии приёмки	одноразовый файл, коммитится и архивируется	одна фича, один разработчик, задача на 1–3 сессии
Plan Mode	план действий агента перед правкой кода, обсуждается до запуска	временный, живёт в сессии чата	быстрая задача, план нужен для контроля, но не для истории
Spec Kit	структурированный цикл Specify → Plan → Tasks с шаблонами	набор файлов в репозитории, версионируется в git	команда, задачи регулярные, нужна воспроизводимость процесса
Beads	трекер задач с жизненным циклом (open → in progress → done) для агентов	база задач, синхронизируется между сессиями	параллельная работа нескольких агентов/сессий, поток задач

Если ты один и задача разовая — не тащи в проект Spec Kit ради ритуала, файла spec.md на пять разделов достаточно. Если у тебя команда и агенты работают параллельно над разными кусками — вот тут уже нужен трекер типа Beads, иначе задачи теряются между сессиями.

Шаблон спецификации, который реально работает

Вот структура, которую можно скопировать в spec.md прямо сейчас. Пять разделов, ни одного лишнего — заказчик хорошей спеки хочет пять минут на её написание, а не два часа документации ради документации.

# Спецификация: {{название фичи}}

## Цель
{{что должно работать после выполнения — одно предложение}}

## Контекст
{{зачем это нужно, какая проблема решается, ссылка на
issue/задачу если есть}}

## Ограничения
- {{технические рамки: какие библиотеки/паттерны
использовать}}
- {{что должно остаться совместимым — API, схема БД,
контракты}}

## Критерии приёмки
- [ ] {{проверяемое условие 1 — что можно
запустить/увидеть}}
- [ ] {{проверяемое условие 2}}
- [ ] {{проверяемое условие 3}}

## Не трогать
- {{файлы/модули/API, которые агент не должен менять}}

Разберу на примере: добавляем пагинацию в список заказов в интернет-магазине.

# Спецификация: пагинация списка заказов

## Цель
Список заказов в админке грузит по 20 штук на странице
вместо всех 4000 сразу.

## Контекст
Страница /admin/orders виснет на 8+ секунд при загрузке,
потому что тянет
все заказы разом. Нужна постраничная навигация без изменения
существующего API-контракта.

## Ограничения
- Использовать существующий query-параметр `page` в роуте,
он уже зарезервирован
- Не менять формат ответа API — только добавить поля total и
pageCount
- Стиль пагинации — как на странице /admin/products, там уже
есть готовый компонент

## Критерии приёмки
- [ ] Страница /admin/orders грузится быстрее 1 секунды при
4000+ заказах
- [ ] Переключение страниц не перезагружает всю страницу
(SPA-навигация)
- [ ] Существующие тесты на /admin/orders всё ещё зелёные
- [ ] Прямая ссылка вида /admin/orders?page=3 открывает
нужную страницу

## Не трогать
- API-контракт GET /api/orders (другие клиенты на него
завязаны)
- Компонент фильтрации заказов выше таблицы

Разница с типичной спекой из топа выдачи — здесь критерии приёмки проверяемы буквально, без интерпретаций. «Быстрее 1 секунды» агент может замерить сам, а «страница должна быть удобной» — не может, и в итоге придумывает удобство по своему разумению.

Чек-лист: спека готова к передаче агенту

Перед тем как бросить файл в Claude Code, прогони его по этим семи пунктам. Если хотя бы два не выполнены — спека не готова, доработай, не запускай.

1. Цель формулируется одним предложением, без «и», «а также», «в том числе».
2. Есть хотя бы один критерий приёмки, который можно проверить автоматически (тест, команда, метрика).
3. Есть хотя бы один критерий, который проверяется глазами (внешний вид, поведение UI).
4. Явно написано, какие файлы/модули/контракты трогать нельзя.
5. Указаны технические ограничения (библиотеки, паттерны, совместимость), а не оставлены «на вкус агента».
6. Спека не смешана с постоянным контекстом проекта — в ней нет описания стека или структуры папок (это в CLAUDE.md).
7. Спеку можно прочитать за 2 минуты — если длиннее, скорее всего в неё влезла лишняя вода вместо конкретики.

По материалам: разбор spec-driven development на Analytics Vidhya, практики работы с Claude Code от Anthropic, репозиторий Spec Kit на GitHub.

Читайте также

• Как проверять код после AI-агента: чек-лист 2026
• Claude Code API в 2026: как подключить, сколько стоит и когда он нужен
• Подписка Claude Code в 2026: тарифы и что входит
• Как установить Claude Code в 2026: пошаговый гайд для новичков
• На портале «Мастерская нейросетей»: Как зарабатывать на нейросетях с Claude Code без навыков программирования

Если после чек-листа спека всё ещё кажется тебе шаткой — это нормальный сигнал, не повод стыдиться. Я, Арина Михална, регулярно пишу про то, как вообще строить работу с агентами так, чтобы они не разваливали задачи по мелочам, в канале «А.М. решает вопросы» — там разбираю живые случаи, а не абстрактные советы. В боте у меня лежит гайд по установке Claude из России и по первым шагам с агентом — забрать его можно за подписку на канал, подписаться и получить доступ к разборам.