Tema
Integração de ADRs com SDD/miniSpec
ADRs alimentam e são alimentadas por SDD/miniSpec automaticamente. Esta página detalha o fluxo de integração entre ADRs e os frameworks de geração.
Skills geradoras que detectam candidatos a ADR
Por design embutido, estas skills aplicam heurísticas de detecção durante a geração:
| Skill | Detecta candidato em |
|---|---|
| agent-spec-sdd-generate-tech-spec | Geração do tech_spec.md (decisões técnicas transversais) |
| agent-spec-minispec-generate-scope | Geração do scope.md (decisões de implementação transversais) |
Quando essas skills rodam:
- Lêem
docs/adr/INDEX.md(adr.index_file). - Identificam ADRs relevantes à área da feature.
- Incluem seção
## ADRs referencedno artefato gerado. - Detectam candidatos a ADR nova na decisão em curso.
Heurísticas de detecção
Uma decisão é candidata a ADR nova se TODAS as 3 são verdadeiras:
| Critério | Pergunta | OK se |
|---|---|---|
transversal | A decisão se aplica a outras features ou ao projeto inteiro? | SIM |
tag_alvo | Cai em uma das 14 tags canônicas? | SIM |
custo_reversao | Reverter implica refactor significativo (≥ médio) em múltiplos lugares? | SIM |
Se detectado:
- Skill pausa e apresenta candidato ao usuário.
- Se aceito → sugere rodar agent-spec-adr-create antes de continuar o fluxo.
- Se recusado → registra como decisão feature-específica no tech_spec/scope sem criar ADR.
Seção "ADRs referenced" nos artefatos
Em tech_spec.md (SDD)
markdown
## ADRs referenced
| ADR | Título | Como aplica nesta feature |
|-----|--------|---------------------------|
| ADR-0001 | Repository + Service | Handler → Service → Repository em `internal/pings/` |
| ADR-0004 | HTTP client compartilhado | Envia eventos via `pkg/http` com retry padrão |Em scope.md (miniSpec)
markdown
## ADRs referenced
- ADR-0001 (accepted) — aplica o padrão Repository+Service
- ADR-0003 (accepted) — valida inputs com ZodApplied in na própria ADR
A ADR mantém lista de features que a usaram:
markdown
## Applied in
- /docs/specs/features/backend-figurinhas-copa/v1/ (SDD)
- /docs/specs/features/auth-oauth2/v1/ (SDD)
- /docs/specs/features/catalogo-filtros/v1/ (miniSpec)
- internal/api/middleware/ratelimit.go (módulo)Atualização: hoje a atualização do
Applied iné manual (durante criação ou ao rodar agent-spec-adr-create). agent-spec-adr-review detecta inconsistências bidirecionais (feature → ADR vs ADR → feature).
Validação no Gate 2 (Tech Review)
Durante a execução de tasks (agent-spec-sdd-run-tasks, agent-spec-minispec-run-tasks, agent-spec-taskcard-run), o Gate 2 (agent-spec-staff-architecture-review):
- Sempre lê
docs/adr/INDEX.mdno início da revisão. - Aprofunda em ADRs específicas quando a task toca a área (ex.: task em HTTP client → lê ADR-0004).
- Classifica violações:
| Violação | Severidade |
|---|---|
| Violação clara e não justificada de ADR aceita | critical, category: adr_compliance |
| Desvio parcial sem justificativa | high |
| ADR desatualizada face ao código (ADR diverge da realidade) | medium + sugestão de agent-spec-adr-supersede |
Cada execução de Gate 2 emite
adrs_consultadas[]no JSON — auditável quais ADRs foram consideradas.
Workflow recomendado
Projeto novo
- Comece sem ADRs. Crie a primeira feature em SDD/miniSpec.
- Na geração do
tech_spec.md/scope.md, a skill detecta candidatos (padrões arquiteturais novos). - Rode agent-spec-adr-create para cada candidato aceito.
- Features subsequentes reusam ADRs existentes.
Projeto existente
- Rode agent-spec-adr-bootstrap para capturar decisões já tomadas como ADRs retroativas.
- Revise e aceite as propostas (uma a uma).
- Continue com
/agent-spec-pre-refinement+ SDD/miniSpec normalmente.
Refatoração arquitetural
- Crie nova ADR via agent-spec-adr-create descrevendo a nova direção.
- Use agent-spec-adr-supersede na ADR antiga → aponta para a nova.
- Features futuras usam a nova; código legado continua referenciando a OLD com aviso (estado
superseded-by:NNNNainda é referenciável). - Migre features manualmente — agent-spec-adr-supersede emite relatório das features afetadas.
Auditoria de bidirecionalidade
agent-spec-adr-review verifica:
- ADRs referenciadas em features existem em
docs/adr/. - Features listadas em
Applied inde uma ADR têm referência no seutech_spec.md/scope.md. - Tags fora da lista canônica.
- Status inválidos.
- Divergência entre arquivos ADR e linhas no
INDEX.md.
Inconsistências viram observações no relatório (read-only — não modifica nada).
Próximos passos
- ADR — Visão Geral — quando criar ADR.
- Lifecycle — estados e transições.
- Template Nygard — estrutura canônica.
- agent-spec-adr-bootstrap — popular corpus inicial.
- agent-spec-adr-create — criar ADR nova.
- agent-spec-staff-architecture-review (Gate 2) — agente que valida conformidade durante execução.