Разработка через спецификации с ИИ-агентами: гайд

Разработка через спецификации (spec-driven development) — это способ работы с ИИ-агентами для кода, при котором письменная спека появляется раньше любого кода. Вы описываете, что строить, зачем и как вы поймёте, что работа закончена. Агент превращает спеку в технический план, разбивает план на небольшие задачи, выполняет их по одной, а результат проверяется по критериям приёмки из спеки. Спека, план и задачи — это файлы в вашем репозитории, а не сообщения, затерянные в чате, поэтому они переживают сессию и ревьюятся так же, как код.

В этом руководстве разобран сам цикл, сравниваются инструменты, которые его поддерживают по состоянию на октябрь 2026 года (GitHub Spec Kit, спеки Kiro, OpenSpec и plan mode в Claude Code и Codex), показан небольшой пример с настоящим файлом спеки и промптами, а в конце перечислены типичные ошибки. Данные об инструментах сверены в октябре 2026 года с официальной документацией и репозиторием каждого проекта.

Почему с агентами спека важнее

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

Спека закрывает этот разрыв тремя способами:

• Она заставляет принять решения заранее. Пограничные случаи, ошибки и то, что не входит в задачу, записаны до того, как агент решит за вас.
• Она даёт каждому шагу один источник истины. План, задачи и ревью ссылаются на один файл, а не на ваши воспоминания о разговоре.
• Она делает «готово» проверяемым. Критерии приёмки превращают ревью из «вроде нормально» в «критерий 3 проходит, вот тест».

Ничего нового здесь нет: требования и приёмочные тесты придуманы давно. Изменилось другое: агенты настолько быстры, что медленной и ценной частью теперь стало написание спеки, а дешёвой — код.

Цикл: спека, план, задачи, реализация, проверка

Цикл держится на двух правилах. Первое: спека описывает поведение, а план — реализацию. «Пользователь может сбросить пароль по почте» — это спека; «добавить таблицу reset_tokens» — это план. Второе: останавливайтесь и проверяйте на каждом шаге. Все инструменты ниже построены вокруг этой паузы; если её пропускать, разработка через спецификации снова превращается в длинный промпт.

Инструменты для разработки через спецификации

GitHub Spec Kit

Spec Kit — набор инструментов GitHub для разработки через спецификации. В этом году он дошёл до 1.0, а последняя версия по состоянию на октябрь 2026 года — v1.2.4. Он не заменяет вашего агента: CLI specify ставит в проект шаблоны и команды, а шаги вы запускаете в чате агента. Нужны Python 3.11 или новее, uv и поддерживаемый агент на macOS, Linux или Windows.

uv tool install specify-cli
specify init my-project --integration claude
# в существующем репозитории:
specify integration install claude

В списке интеграций больше 40 агентов, среди них Claude Code (claude), Codex CLI (codex), Gemini CLI (gemini), GitHub Copilot (copilot), Cursor (cursor-agent), Kiro CLI (kiro-cli), opencode, Qwen Code и Amp. В документации команды записаны как /speckit.specify и так далее; как их набирать, зависит от агента. В Claude Code они ставятся как skills в .claude/skills/ и вызываются через /speckit-specify, в Codex — через $speckit-specify.

Короткий путь — specify → plan → tasks → implement → converge. Для фич, которые пойдут в продакшен, документация советует полный путь:

1. /speckit-constitution — один раз на проект, для принципов вроде правил тестирования.
2. /speckit-specify пишет спеку фичи по простому описанию.
3. /speckit-clarify задаёт до пяти точечных вопросов и вносит ответы в спеку.
4. /speckit-plan пишет технический план с учётом вашего стека и ограничений.
5. /speckit-checklist создаёт «юнит-тесты для ваших требований».
6. /speckit-tasks выдаёт tasks.md, упорядоченный по зависимостям.
7. /speckit-analyze — проверка согласованности спеки, плана и задач только на чтение.
8. /speckit-implement выполняет задачи по порядку.
9. /speckit-converge сверяет код со спекой и дописывает пропущенную работу в tasks.md.

Implement и converge повторяются, пока converge не ответит Converged. Документация советует запускать каждую команду отдельно и проверять результат перед следующей.

Спеки Kiro

Kiro встраивает спеки прямо в продукт. У каждой спеки три файла в .kiro/specs/<имя>/: requirements.md (или bugfix.md для бага), design.md и tasks.md. Требования пишутся в нотации EARS по шаблону «WHEN [условие] THE SYSTEM SHALL [поведение]». Спека фичи может начинаться с требований или с дизайна, а Quick Spec генерирует все три файла за один проход без промежуточных остановок на одобрение.

В Kiro CLI вы начинаете с /spec new <имя> и запускаете задачи через /spec run <имя>. Когда вы запускаете все задачи, Kiro строит граф зависимостей по tasks.md и выполняет независимые задачи параллельными волнами. По состоянию на октябрь 2026 года у Kiro есть бесплатный тариф с 50 кредитами и платные тарифы от 20 $ за пользователя в месяц.

Kiro — лучший выбор, если вам нужен процесс со спеками и встроенным интерфейсом ревью и вас устраивает работать внутри Kiro. Если хотите остаться в Claude Code или Codex, лучше подойдут Spec Kit или OpenSpec.

OpenSpec

OpenSpec — более лёгкая альтернатива под лицензией MIT, построенная вокруг изменений. /opsx:propose add-dark-mode создаёт openspec/changes/add-dark-mode/ с proposal.md, папкой specs/ с требованиями и сценариями, design.md и tasks.md. /opsx:apply выполняет задачи, а /opsx:archive переносит изменение в архив и обновляет спеки. /opsx:explore — шаг на подумать, прежде чем браться за предложение.

npm install -g @fission-ai/openspec@latest   # нужен Node.js 20.19.0+
cd your-project
openspec init

Есть также отдельный бинарник и формула Homebrew. Написание команд зависит от агента, например в Codex это $openspec-propose; openspec init показывает правильную форму для выбранных инструментов. Последняя версия по состоянию на октябрь 2026 года — v1.15.0.

Plan mode в Claude Code и Codex

Plan mode закрывает один шаг цикла — план. В plan mode Claude Code агент читает файлы, изучает код и предлагает план, а правки остаются заблокированными, пока вы не одобрите. Включается через Shift+Tab, /plan перед промптом или claude --permission-mode plan.

В Codex CLI есть /plan: команда переводит чат в plan mode и может сразу принять первый запрос, например /plan Propose a migration plan for this service. Ещё в Codex есть /goal, которая задаёт постоянную цель для большой задачи; её можно приостановить, возобновить или сбросить.

Plan mode хорошо подходит для работы через спеки без дополнительных инструментов. Не хватает только постоянства: попросите агента записать одобренный план и задачи в файлы, чтобы следующая сессия начиналась с них, а не с нуля.

Пример: файл спеки и четыре промпта

Вот вариант «своими руками», который работает с Claude Code, Codex или любым агентом, умеющим читать файлы. Фича: ограничить неудачные попытки входа в небольшом веб-приложении.

1. Напишите спеку

Сохраните это как specs/login-rate-limit/spec.md:

# Login rate limiting

## Goal
Slow down password guessing on POST /login without bothering normal users.

## Non-goals
- No CAPTCHA.
- No change to how passwords are stored.

## Acceptance criteria
1. WHEN an IP has 5 failed logins within 15 minutes,
   THE SYSTEM SHALL answer further attempts with HTTP 429 for 15 minutes.
2. WHEN a login succeeds, THE SYSTEM SHALL reset that IP's failure count.
3. The 429 response SHALL include a Retry-After header in seconds.
4. Limits SHALL be configurable through LOGIN_MAX_FAILS and LOGIN_WINDOW_MIN.
5. Existing login tests SHALL still pass, and new tests SHALL cover 1–4.

## Constraints
- Use the existing Redis connection; no new services.

## Open questions
- Should the limit be per IP, per account, or both?

Уложитесь в один экран. Раздел с открытыми вопросами добавлен намеренно: у агента появляется место, чтобы возразить до планирования. Спеку можно писать и по-русски — агенты читают оба языка.

2. Уточните и спланируйте

Начните в plan mode и укажите агенту на файл:

Read specs/login-rate-limit/spec.md and the auth code.
First, ask me about anything ambiguous, starting with the open questions.
Then write a plan to specs/login-rate-limit/plan.md: files to change,
data stored in Redis and its expiry, how each acceptance criterion
will be tested, and risks. Don't edit any source files.

Ответьте на вопросы, затем прочитайте план. Возражайте против всего, что игнорирует ограничения.

3. Разбейте на задачи

Turn plan.md into specs/login-rate-limit/tasks.md: a numbered checklist
of tasks small enough to review in one diff. For each task, list the
files it touches and the test that proves it. Order them by dependency.

4. Реализуйте по одной задаче

Do task 1 from specs/login-rate-limit/tasks.md only. Run the tests,
tick the task in tasks.md, and stop. Tell me if the spec or plan
turned out to be wrong.

Одна задача на промпт держит диффы маленькими и даёт естественную точку для ревью. Если задача показала, что спека неверна, сначала исправьте спеку, потом продолжайте.

5. Проверьте по спеке

Когда задачи закончены, сверьте результат со спекой — лучше в новой сессии или другим агентом, чтобы проверял не тот, кто писал код:

Read specs/login-rate-limit/spec.md. For each acceptance criterion,
find the code and the test that cover it, run the tests, and report
PASS or FAIL with evidence. Don't change any code.

Вот и весь цикл. Коммитьте папку specs/ вместе с кодом, чтобы следующий человек или следующий агент видел, почему код устроен именно так. О том, как писать сами промпты, читайте в статье промпты для ИИ-агентов.

Типичные ошибки

• Спеки, которые на самом деле планы. Если спека называет таблицы и функции, агент не может предложить дизайн получше, а ревьюер не отличает поведение от реализации. «Как» держите в plan.md.
• Слишком длинные спеки. Десятистраничная спека съедает контекст, и её никто не читает, включая агента. Один экран на фичу — хороший предел; большие фичи делите.
• Одобрение без чтения. Непрочитанная спека или план — это просто более медленный промпт. Весь смысл в паузе на ревью.
• Слишком крупные задачи. Если задача даёт дифф, который нельзя проверить за один подход, разделите её.
• Устаревающая спека. Когда код открывает что-то новое, обновите спеку. Спека, противоречащая коду, хуже, чем никакой.
• Проверка руками автора. Агент, который написал код, склонен подтверждать собственную работу. Для финальной проверки берите новую сессию, другую модель или человека.
• Применение ко всему подряд. Однострочному исправлению спека не нужна. Оставьте процесс для фич с пограничными случаями или несколькими файлами.
• Правила проекта в каждой спеке. Постоянные правила вроде команд тестов и стиля кода место в CLAUDE.md или AGENTS.md или в constitution Spec Kit, а не в каждой спеке фичи.

Разработка через спецификации в AgentVera

AgentVera — десктопное приложение для macOS, Windows и Linux, которое запускает Claude Code, Codex, Kiro и другие CLI для кода бок о бок. Каждая панель — это настоящий CLI, поэтому команды Spec Kit, команды OpenSpec, /spec в Kiro и plan mode работают там так же, как сами по себе. Некоторые функции AgentVera повторяют ту же схему: спека, план, сборка, проверка.

• Линия задач: постоянная линия агентов Анализа, Плана, Сборки и Ревью. У каждой задачи есть критерии приёмки, Анализ пишет 01-analiz.md, План — 02-plan.md, а ревьюер отмечает каждый критерий с доказательством. Отклонённая задача возвращается в Сборку вместе с замечаниями.
• AgentVera Verify: берёт критерии приёмки из сообщения, которое вы отправляете агенту, а когда его ход заканчивается, отдельный проверяющий читает дифф, запускает разрешённые тестовые команды и отмечает каждый критерий как пройденный или проваленный. Проверяющий не может редактировать файлы.
• Параллельная команда: агент делит большую работу максимум на 8 частей, у каждой свой промпт, критерии приёмки, ожидаемые файлы и зависимости, запускает их в отдельных worktree и сводит в одну ветку и один PR.
• Командный канбан: карточку можно отправить агенту для кода как задачу, а его ответ вернётся комментарием. См. канбан для ИИ-агентов.
• Автоматическое код-ревью: когда ход заканчивается, выбранная вами модель Claude проверяет код и выдаёт замечания со ссылками файл:строка.

Линия задач, Verify, параллельная команда и командный канбан входят в тарифы Pro и Team. Если вам нужны только файлы спек и команды, Spec Kit и OpenSpec бесплатны и работают в любом терминале; AgentVera пригодится, когда по спекам одновременно работают несколько агентов.

Подведём итог

Разработка через спецификации сводится к тому, чтобы записать «что» и «как я пойму, что готово» до того, как агент начнёт писать код, а затем привязать к этому файлу каждый следующий шаг. Начните с spec.md на один экран и plan mode. Переходите на Spec Kit или OpenSpec, когда понадобятся шаблоны и проверки согласованности, или на Kiro, если хотите процесс прямо в редакторе. Что бы вы ни выбрали, проверяйте на каждом шаге и сверяйтесь с критериями, а не с резюме агента.

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

• Plan mode в Claude Code
• Промпты для ИИ-агентов
• Линия задач

Чтобы попробовать AgentVera, скачайте её.