Scaffold de Spec-Driven Development (SDD) para agentes de IA — Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI e Windsurf. Em qualquer projeto, rode um comando e ganhe a esteira completa: Lean Inception → DDD → Technical Design Docs → SDD, com skills, templates, gates de qualidade e continuidade entre sessões.
# no diretório do seu projeto (menu interativo pergunta quais clientes gerar)
npx @igoruehara/spec-driven
# ou criando numa pasta nova
npx @igoruehara/spec-driven meu-projeto
# não-interativo: escolha os clientes pela flag (ao menos um é obrigatório)
npx @igoruehara/spec-driven --agent=claude,cursor # Claude + CursorO Claude é a fonte canônica do conteúdo (formato mais rico), mas é um cliente escolhível
como qualquer outro — nenhum entra por padrão e é obrigatório selecionar ao menos um. Os demais
clientes são views geradas a partir do mesmo conteúdo — escolha quais no menu interativo ou via --agent.
| Cliente | Instruções | Skills / commands |
|---|---|---|
| Claude Code | CLAUDE.md |
.claude/skills/*/SKILL.md (+ hook SessionStart) |
| Codex | AGENTS.md |
.agents/skills/*/SKILL.md |
| Cursor | .cursor/rules/sdd.mdc |
.cursor/commands/*.md |
| GitHub Copilot | .github/copilot-instructions.md |
.github/prompts/*.prompt.md |
| Gemini CLI | GEMINI.md |
.gemini/commands/*.toml |
| Windsurf | .windsurf/rules/sdd.md |
.windsurf/workflows/*.md |
O
AGENTS.mddo Codex também é lido nativamente por Cursor, Copilot, Gemini e Windsurf — então ele já cobre a camada de instruções de quase todo o ecossistema. As views nativas de cada cliente são geradas só quando você as pede.
| Prática | Sentido aqui | O que aporta à esteira |
|---|---|---|
| Lean Inception | workshop de descoberta (Paulo Caroli) | visão, personas e MVP — o que construir primeiro |
| DDD | Domain-Driven Design (Eric Evans) | linguagem ubíqua e bounded contexts — o modelo do negócio |
| TDD | Technical Design Doc / RFC | design antes de codar, com alternativas — como no nível de sistema |
| SDD | Spec-Driven Development | a spec é a fonte da verdade — o contrato que dirige a implementação |
Encadeadas: Lean Inception (descobrir) → DDD (modelar) → TDD (desenhar) → SDD (especificar e implementar).
seu-projeto/
├── CLAUDE.md # convenções que o agente segue (verificação de conhecimento, camadas, DoD)
├── README.md # o manual da esteira SDD
├── .claude/skills/ # 15 skills (ver abaixo) — + as views dos clientes extras escolhidos
├── .spec-driven/manifest.json # quais clientes foram gerados (usado pelo update)
├── .github/workflows/ # esteira.yml — gate de conformidade na CI
├── scripts/ # audit-esteira.mjs + validate-mermaid.mjs + eval-spec-fidelity.mjs
├── docs/
│ ├── glossary.md · STATE.md
│ ├── product/ # vision · stakeholders · journeys · features · mvp-canvas · roadmap
│ ├── architecture/ # overview (5 eixos) · context-map · diagrams · assessment · adr/
│ └── engineering/ # TESTING · metrics · integrations · agentic-layer (+ _templates)
├── specs/ # uma pasta por feature (0001-…) + quick/ + _templates/
└── src/ # estrutura em camadas DDD
| Skill | Responsabilidade |
|---|---|
/kickoff |
orquestra a constituição do projeto (greenfield ou brownfield) |
/integracoes |
ferramentas do time + MCPs (read-first, trava de conta/workspace) |
/mapear |
mapeia um codebase existente → assessment.md |
/diagramar |
arquitetura de alto nível em Mermaid → diagrams.md |
/roadmap |
constrói/revisa o roadmap com o time |
/camada-agentica |
gera rules, subagents, skills e workflows/CI |
/nova-feature |
abre uma feature no padrão SDD (tier → spec → tasks) |
/clarificar |
sabatina: entrevista implacável (uma pergunta por vez) que afia spec/design ambíguos antes de construir |
/validar |
UAT: gates, AC→teste, SPEC_DEVIATION, DoD |
/revisar-pr |
gate de conformidade SDD no PR/MR |
/setup-ci |
pipeline CI/CD que materializa os gates |
/metricas |
Lead Time, Throughput e maturidade de Continuous Delivery/Deployment |
/auditar |
valida a conformidade da esteira (frontmatter, links, rastreabilidade) |
/evals |
mede fidelidade spec→código (AC cobertos por task/teste, SPEC_DEVIATION) |
/handoff |
pausa/retoma a sessão via docs/STATE.md |
examples/pulse/ é um produto fictício levado pela esteira ponta a ponta —
discovery (vision/features) → spec (AC) → tasks → código → testes — com audit e eval verdes e
os testes passando. A prova de que o fluxo fecha, não só artefatos soltos.
npx @igoruehara/spec-driven [diretório-alvo] [opções]npx @igoruehara/spec-driven # scaffolda no diretório atual
npx @igoruehara/spec-driven meu-projeto # cria/usa a pasta ./meu-projeto
npx @igoruehara/spec-driven . --force # sobrescreve arquivos existentes
npx @igoruehara/spec-driven update # atualiza só a esteira, preserva seus docs| Comando | O que faz |
|---|---|
| (init) | scaffolda a esteira completa. Arquivos existentes são mantidos (use --force). |
update |
atualiza só a maquinaria (skills, hooks, _templates, scripts, CI). Preserva seus docs/specs e mostra o diff antes de aplicar. |
| Opção | O que faz |
|---|---|
--agent=a,b |
clientes a gerar (claude,codex,cursor,copilot,gemini,windsurf); pula o menu; exige ≥ 1 |
--all |
gera as views de todos os clientes suportados (inclui Claude) |
--force |
sobrescreve arquivos que já existem |
--yes, -y |
pula a confirmação interativa (exige --agent= ou --all p/ saber os clientes) |
No
update,--agent=adiciona um cliente novo a um projeto já existente (ex.:npx @igoruehara/spec-driven update --agent=codexmaterializa o Codex e o mantém atualizado).
🔒 Seguro em projeto existente: no init, arquivos existentes são mantidos (nada sobrescrito sem
--force). Noupdate, só a maquinaria da esteira é refeita — seus docs e specs ficam intactos.
git init(se ainda não for um repo).- No Claude Code, aprove o hook de contexto na 1ª sessão — um
SessionStart(.claude/settings.json) que carrega o contexto base (STATE, vision, roadmap) automaticamente. Requer Node na máquina. - Rode
/integracoes(se já conhece o ferramental) →/kickoff. - Comece a primeira feature com
/nova-feature.
MIT