spec-driven — плагин для Claude Code: что делает и как установить
Плагин spec-driven ведёт фичу через три фазы: требования в нотации EARS, дизайн и список задач. Дальше реализацию выполняет агент.
MIT ★ 1 596 обновлён 2026-10-29
/plugin marketplace add hashgraph-online/awesome-codex-plugins
/plugin install spec-driven@awesome-codex-pluginsЧто делает spec-driven
Плагин превращает идею фичи в формальную спеку до первой строки кода. Команда /spec <name> создаёт каталог .claude/specs/<name>/ с тремя файлами: requirements.md (истории с критериями приёмки в нотации EARS), design.md (архитектура и план работ) и tasks.md (задачи со статусом, проверкой и зависимостями). Требования собираются за пару раундов вопросов.
Реализация идёт из скриптов в каталоге scripts/. bash scripts/spec-exec.sh --spec-name <name> делает одну итерацию, spec-loop.sh крутит цикл до исчерпания --max-iterations. Перед каждой итерацией loop ставит checkpoint-коммит: если агент упал с ненулевым кодом, ветка откатывается к последнему чекпоинту. Спеки ссылаются друг на друга через раздел ## Depends On в requirements.md, и скрипт не начнёт работу, пока у зависимостей не проверены все задачи.
В Codex те же команды вызываются с $ вместо /, а корень спек задаётся переменной SPEC_ROOT; каталог .codex/specs/ читается как запасной вариант при переезде. После реализации есть необязательный хвост: spec-accept.sh для приёмки, spec-docs.sh, spec-release.sh и spec-verify.sh с --url для смоук-тестов. Последний отдаёт 0 при успехе и 1 при провале, поэтому его ставят в CI обычным шагом.
Какие задачи решает
- Разложить идею фичи на требования, дизайн и задачи до начала кодинга
- Записать критерии приёмки в нотации EARS, чтобы каждый можно было проверить
- Прогнать автономный цикл реализации с откатом к чекпоинту при падении агента
- Связать спеки зависимостями и не запускать работу раньше времени
- Встроить смоук-тесты после деплоя в CI по коду выхода
Примеры запросов агенту
- Запусти
/spec user-authenticationи проведи меня по трём фазам - Крути
/spec-loop, пока все задачи вtasks.mdне закроются - Покажи
/spec-status: что готово и какие зависимости мешают
Как установить spec-driven
Через маркетплейс плагинов
/plugin marketplace add hashgraph-online/awesome-codex-plugins/plugin install spec-driven@awesome-codex-pluginsПо шагам, с командами для каждой платформы: Плагины Claude Code: маркетплейсы, установка и как собрать свой
Вопросы о spec-driven
Как установить spec-driven в Claude Code?
Сначала добавьте маркетплейс: /plugin marketplace add hashgraph-online/awesome-codex-plugins. Потом поставьте сам плагин: /plugin install spec-driven@awesome-codex-plugins.
Что делает spec-driven?
Проводит фичу через три фазы: требования с критериями приёмки, дизайн и задачи. После этого скрипты запускают автономную реализацию по этим задачам.
Где лежат файлы спеки?
В .claude/specs/<feature-name>/: requirements.md, design.md и tasks.md. Путь меняется переменной SPEC_ROOT.
Исходный текст
spec-driven-plugin · MIT
# Spec-Driven Development Plugin
A structured workflow plugin for Claude Code & Codex that transforms feature ideas into formal specifications before implementation.
## Overview
This plugin guides you through three phases:
1. **Requirements** - User stories with EARS notation and acceptance criteria
2. **Design** - Technical architecture, sequence diagrams, implementation considerations
3. **Tasks** - Discrete, trackable implementation items that mirror to Claude Code's todo system
## Commands
Commands use `/` prefix in Claude Code and `$` prefix in Codex.
### Core Workflow
| Claude Code | Codex | Description |
|-------------|-------|-------------|
| `/spec-brainstorm` | `$spec-brainstorm` | Brainstorm a feature idea before spec creation |
| `/spec <name>` | `$spec <name>` | Start a new feature spec with interactive 3-phase workflow |
| `/spec-bugfix <name>` | `$spec-bugfix <name>` | Start a new bugfix spec with defect analysis and regression prevention |
| `/spec-refine` | `$spec-refine` | Refine requirements/design for current spec |
| `/spec-tasks` | `$spec-tasks` | Regenerate tasks from updated spec |
| `/spec-status` | `$spec-status` | Show spec progress, task completion, and dependency status |
| `/spec-validate` | `$spec-validate` | Validate spec completeness and consistency |
### Research & Navigation
| Claude Code | Codex | Description |
|-------------|-------|-------------|
| `/research` | `$research` | Deep parallel research before planning — searches docs, web, and codebase |
| `/zoom-out` | `$zoom-out` | Map modules, interfaces, and callers for unfamiliar code |
| `/ubiquitous-language` | `$ubiquitous-language` | Extract domain terms into a canonical glossary with flagged ambiguities |
### Implementation
| Claude Code | Codex | Description |
|-------------|-------|-------------|
| `/spec-exec` | `$spec-exec` | Run one autonomous implementation iteration |
| `/spec-loop` | `$spec-loop` | Loop implementation until all tasks complete |
### Post-Completion (Optional)
| Claude Code | Codex | Description |
|-------------|-------|-------------|
| `/spec-accept` | `$spec-accept` | Run user acceptance testing for formal sign-off |
| `/spec-docs` | `$spec-docs` | Generate documentation from spec and implementation |
| `/spec-release` | `$spec-release` | Generate release notes and deployment checklist |
| `/spec-verify` | `$spec-verify` | Run post-deployment smoke tests |
| `/spec-retro` | `$spec-retro` | Run a retrospective on a completed spec |
| `/spec-complete` | `$spec-complete` | Run full post-completion pipeline (accept → docs → release → retro) |
## Usage
### Starting a New Spec
**Claude Code:**
```
/spec user-authentication
```
**Codex:**
```
$spec user-authentication
```
This will:
1. Create `.claude/specs/user-authentication/` directory
2. Gather requirements interactively (2-3 rounds of questions)
3. Guide you through Design phase (architecture docs)
4. Generate Tasks with explicit status, wiring, verification, and dependencies
### Spec Files Location
Specs are stored in `.claude/specs/<feature-name>/` by default. Existing `.codex/specs/<feature-name>/` directories are supported as a migration fallback, or set `SPEC_ROOT` explicitly:
```
.claude/specs/user-authentication/
├── requirements.md # User stories with acceptance criteria
├── design.md # Architecture and implementation plan
└── tasks.md # Trackable implementation tasks
```
### Cross-Spec Dependencies
Specs can declare dependencies on other specs via a `## Depends On` section in requirements.md:
```markdown
## Depends On
- auth-system
- database-migrations
```
Execution scripts check dependencies before running. A dependency is considered complete when all its tasks are verified. `/spec-status` shows dependency status.
## Implementation
After creating a spec, run autonomous implementation:
```bash
# single task
bash scripts/spec-exec.sh --spec-name user-authentication
# loop until all tasks complete
bash scripts/spec-loop.sh --spec-name user-authentication --max-iterations 20
```
Scripts live in the plugin's `scripts/` directory. If only one spec exists, `--spec-name` is auto-detected.
### Post-Completion (Optional)
After implementation completes, optionally run:
```bash
# user acceptance testing
bash scripts/spec-accept.sh --spec-name user-authentication
# generate documentation
bash scripts/spec-docs.sh --spec-name user-authentication
# release notes and deployment checklist
bash scripts/spec-release.sh --spec-name user-authentication
# post-deployment smoke tests
bash scripts/spec-verify.sh --spec-name user-authentication --url https://staging.example.com
# retrospective analysis
bash scripts/spec-retro.sh --spec-name user-authentication
# or run all at once
bash scripts/spec-complete.sh --spec-name user-authentication
```
### Checkpoint Recovery
`spec-loop.sh` creates checkpoint commits before each iteration. If the agent crashes or exits non-zero, the branch is rolled back to the last checkpoint automatically.
### CI/CD Integration
The verification script returns exit codes for CI pipelines:
- `spec-verify.sh` exits `0` on PASS, `1` on FAIL (promise markers: `VERIFIED` / `VERIFICATION_FAILED`)
- `spec-accept.sh` outputs `<promise>ACCEPTED</promise>` or `<promise>REJECTED</promise>`
- `spec-loop.sh` outputs `<promise>COMPLETE</promise>` when all tasks are done
Example CI stage:
```bash
bash scripts/spec-verify.sh --spec-name user-authentication --url "$STAGING_URL" --scope quick || exit 1
```
## Spec-Loop Performance
The loop script includes optimizations for long-running specs:
- **Progress tail**: Only the last 20 progress entries are included in the prompt (configurable via `--progress-tail`)
- **Lightweight Step 1**: Iterations 2+ skip full environment checks
- **Spec reference**: Requirements and design are referenced by path (not inlined) after iteration 1
- **Timing**: Each iteration prints elapsed time
## EARS Notation
Requirements use EARS (Easy Approach to Requirements Syntax):
```
WHEN [condition/trigger]
THE SYSTEM SHALL [expected behavior]
```
Example:
```
WHEN a user submits invalid form data
THE SYSTEM SHALL display validation errors inline
```
## Installation
### Claude Code
Add to your `~/.claude/settings.json`:
```json
{
"enabledPlugins": {
"spec-driven@spec-driven": true
},
"extraKnownMarketplaces": {
"spec-driven": {
"source": {
"source": "url",
"url": "https://github.com/Habib0x0/spec-driven-plugin.git"
}
}
}
}
```
Then restart Claude Code.
### Codex
This repository includes a Codex plugin manifest at `.codex-plugin/plugin.json`.
Install from GitHub:
```bash
codex plugin marketplace add Habib0x0/spec-driven-plugin
```
Or test the local checkout:
```bash
codex plugin marketplace add /path/to/spec-driven-plugin
```
Override the agent backend:
```bash
export SPEC_ROOT=.codex/specs
export SPEC_AGENT_CMD='codex exec --full-auto -'
bash scripts/spec-exec.sh --spec-name user-authentication
```
#### Usage in Codex
Codex commands use `$` prefix instead of `/`:
```
$spec user-authentication
$spec-status
$spec-exec
```
You can also invoke the skill by typing one of its default prompt phrases:
| Prompt | Action |
| --- | --- |
| `Create a spec for this feature` | Start a new spec workflow |
| `Validate the current spec` | Run validation on the active spec |
| `Break this design into tasks` | Regenerate tasks from the design doc |
Or reference it by display name: `Use Spec Driven to plan user authentication`.
**Plan mode vs build mode:** Works in both. Plan mode generates the spec for review before writing; build mode writes files directly. Implementation scripts (`spec-exec.sh`, `spec-loop.sh`) run from your terminal.
All generated spec files live in `.codex/specs/<feature-name>/` when running under Codex.
## Inspiration
This plugin was inspired by [Kiro](https://kiro.dev)'s spec-driven development functionality. Kiro introduced the concept of structured specification workflows that guide developers through requirements gathering, design, and task breakdown before implementation.
Key concepts borrowed from Kiro:
- **Three-phase workflow**: Requirements → Design → Tasks
- **EARS notation**: Structured acceptance criteria format
- **Spec file organization**: Dedicated spec directories with separate documents for each phase
- **Task traceability**: Linking implementation tasks back to requirements
## License
MIT
© habib0x · MIT · hashgraph-online/awesome-codex-plugins