Ir para o conteúdo

Feature Development Flow
Tipo Feature (nova funcionalidade / melhoria significativa)
Trigger /feature <ticket>
Fases Specify → (Design) → (Tasks) → Execute — auto-sized por complexidade
Agentes architecture-agent → (ux-design-agent, se UI) → builder-agent → code-reviewer-agent → test-validator → pr-generator → release-agent → learning-agent
Checkpoints humanos 2 (Small/Medium) ou 4 (Large/Complex)
Base NS Flow Kit + TLC Spec-Driven Development (SDD)

Pré-requisito: instalação concluída — ver 00 — Instalação e Setup.

1. O que é e quando usar

O Feature Flow aplica Spec-Driven Development: a feature nunca começa por código. Ela percorre fases ordenadas, e o número de fases ativas se adapta ao tamanho da demanda (auto-sizing).

Use quando: vai construir funcionalidade nova ou uma melhoria com escopo relevante.

Não use quando: é defeito reportado (→ Bug Flow), ajuste trivial de texto/label (→ Small Improvement) ou mudança só de banco (→ Data Fix).

Convergência das esteiras: uma story criada pela Esteira de Produto (/discover) já chega com FEAT-{N} prontos — rode /feature {STORY_ID} e a Specify apenas confirma. E toda a entrega passa pela Esteira de Qualidade (4 gates) antes do PR.

2. Como o SDD é aplicado (fase → princípio)

Fase Pergunta que responde Princípio do SDD Artifact
Specify O QUÊ construir Requisitos testáveis e rastreáveis (FEAT-01...) spec.md
Design COMO construir Knowledge Verification Chain, respeito a ADRs (+ UX se toca UI) arch-guidance.md (+ ux-guidance.md)
Tasks Em que ordem Tasks atômicas com dependências e critérios tasks.md
Execute Implementar + revisar Minimum Viable Patch + RED→GREEN + commits atômicos + code review commits + code-review.md + validation.md

3. Auto-sizing — quais fases são ativadas

Antes do Specify, o agente classifica o tamanho e declara explicitamente:

Tamanho Critério Fases ativas Arquivos gerados
Small ≤3 arquivos, escopo em 1 frase Quick mode (Specify inline + Execute) só spec.md
Medium Feature clara, <10 tasks óbvias Specify + Execute spec.md
Large Multi-componente, decisões arquiteturais Specify + Design + Tasks + Execute spec.md + arch-guidance.md + tasks.md
Complex Ambiguidade alta, domínio novo, integrações externas Specify + Discuss + Design + Tasks + Execute + UAT todos acima

Válvula de segurança: mesmo quando Tasks é pulado, o Execute começa listando os passos atômicos inline. Se a lista revelar >5 passos ou dependências complexas → PARE e crie um tasks.md formal.

4. Visão geral do fluxo

/feature <ticket>
    └── Speckit lookup         → restrições e ADRs relevantes
    └── [Specify]              → spec.md com requisitos rastreáveis
             ↓
    ⚡ CHECKPOINT 1 — humano aprova escopo e plano de fases
             ↓
    └── [Design]*              → arch-guidance.md   (* se Large/Complex)
    └── ux-design-agent*       → ux-guidance.md     (* se a feature toca UI)
    └── [Tasks]*               → tasks.md           (* se Large/Complex)
             ↓
    ⚡ CHECKPOINT 2 — humano aprova plano antes da implementação
             ↓
    └── [Execute]              → commits atômicos por task
    └── code-reviewer-agent    → CodeReviewReport (antes dos gates/PR)
    └── test-validator         → ValidationReport
             ↓
    Esteira de Qualidade: /qa-plan → Gate 1 (1a cobertura + 1b execução no dev) → Gate 2 (smoke) → Gate 3 (E2E) → /qa-gate
             ↓
    /open-pr <ticket>          → PR Description + Rollback Plan
             ↓
    ⚡ CHECKPOINT 3 — reviewer aprova o PR
             ↓
    /release-check <ticket>    → ReleasePackage
             ↓
    ⚡ CHECKPOINT 4 — humano aprova o deploy
             ↓
    [deploy via pipeline] → learning-agent → atualiza Speckit

5. Passo a passo

Passo 0 — Bootstrap do workspace (automático no /feature)

Cria state e spec vazios e consulta o Speckit: - .ns-flow/state/<ticket>-state.md (de state-template.md) - .ns-flow/design/<ticket>-spec.md - Lê .speckit/domain/, .speckit/architecture/risk-map.md, .speckit/decisions/, .speckit/known-issues/ - Grava as restrições encontradas no spec como "Restrições do Speckit".

Passo 1 — Specify (sempre obrigatória)

Captura o QUÊ. Faz perguntas de clarificação, classifica o tamanho, escreve requisitos com IDs rastreáveis em formato Gherkin (QUANDO {condição} ENTÃO {resultado}). Output: .ns-flow/design/<ticket>-spec.md

Passo 2 — ⚡ Checkpoint 1 (escopo)

O agente para e apresenta: ticket, tamanho, escopo, requisitos, restrições do Speckit, plano de fases, próximo passo. Nenhum código antes da aprovação.

Passo 3 — Design (Large/Complex) — architecture-agent (+ ux-design-agent se UI)

Define o COMO. Segue a Knowledge Verification Chain: Codebase → .speckit/architecture/ → documentação oficial → sinalizar "não sei". Hotspot do risk-map → Mini RFC obrigatória. Se a feature toca UI, o ux-design-agent descobre o design system real do produto, define a janela de modernização (preservar + modernizar) e valida contra ux-consistency-policy (identidade nova / one-off → bloqueado). Output: .ns-flow/design/<ticket>-arch-guidance.md (+ .ns-flow/design/<ticket>-ux-guidance.md se UI)

Passo 4 — Tasks (Large/Complex)

Quebra em tasks atômicas: O quê / Onde / Depende de / Reutiliza / Requisito / Concluído quando / Commit. Tasks paralelas marcadas com [P]. Output: .ns-flow/design/<ticket>-tasks.md

Passo 5 — ⚡ Checkpoint 2 (plano)

Aplicável quando há Design/Tasks formais. Aprovação do plano de implementação.

Passo 6 — Execute (sempre) — builder-agent + test-validator

Ciclo por task: Planejar → Implementar → Verificar → Commitar → Próxima. - Mudanças cirúrgicas; scope creep → "Deferred Ideas" no state, não implementado. - test-validator escreve teste de regressão que falha antes do fix (RED→GREEN). - Um commit por task (Conventional Commits). - Para features com comportamento de usuário complexo → UAT interativo antes do PR. Output: commits + .ns-flow/delivery/<ticket>-validation.md

Passo 6a — Code review — code-reviewer-agent (antes dos gates)

Revisa o diff da feature (escopo, corretude, segurança, reuso, testes e — se toca UI — consistência de UX contra o ux-guidance). Finding Blocker volta ao builder-agent antes do PR. Output: .ns-flow/delivery/<ticket>-code-review.md

Passo 6b — Esteira de Qualidade (4 gates) — antes do PR

Nada vai para o PR sem os 4 gates verdes (ver Quality Layer): - Gate 1 — Cobertura + Execução no dev: /run-regression (1a diff coverage + RED→GREEN · 1b QA Plan no dev/stg) - Gate 2 — smoke: /smoke (caminho crítico) - Gate 3 — E2E: /validacao-testes (100% dos FEAT-{N} com evidência) → alimenta o Checkpoint 3 - Meta-gate: /qa-gate consolida os 4; o release-agent recusa o release sem ele.

(A estratégia de teste por camada já nasce no /qa-plan, idealmente no discovery — shift-left.)

Passo 7 — /open-pr <ticket> → ⚡ Checkpoint 3

pr-generator cria PR linkando os requisitos do spec + rollback plan + checklist. Output: .ns-flow/delivery/<ticket>-pr-description.md

Passo 8 — /release-check <ticket> → ⚡ Checkpoint 4

release-agent verifica quality gates e gera o release package. Output: .ns-flow/delivery/<ticket>-release.md

Passo 9 — Pós-deploy — learning-agent

Atualiza .speckit/known-issues/, risk-map.md, decisions/ (novos ADRs) e .speckit/incidents/metrics-feed.jsonl (type: "feature"). Encerra o ticket.

6. Checkpoints humanos

# Quando Quem aprova Verifica
1 Após Specify Dev/PO Escopo reflete o ticket? Tamanho correto? Restrições do Speckit consideradas?
2 Após Design/Tasks (L/C) Tech Lead Arquitetura respeita ADRs? Tasks cobrem todos os requisitos? Sem scope extra?
3 No PR Reviewer Descrição completa? Rollback executável? Homologação feita?
4 Antes do deploy Responsável de release Gates ✅? Janela adequada? On-call ciente?

Small/Medium: os checkpoints 1 e 2 colapsam em um só — o humano vê o plano de implementação e aprova antes de qualquer código.

7. Pastas e arquivos gerados

Fase Arquivo
State (sessão) .ns-flow/state/<ticket>-state.md
Specify .ns-flow/design/<ticket>-spec.md
Design (L/C) .ns-flow/design/<ticket>-arch-guidance.md
Design de UX (se UI) .ns-flow/design/<ticket>-ux-guidance.md
Tasks (L/C) .ns-flow/design/<ticket>-tasks.md
Execute commits atômicos no repo + testes
Code Review .ns-flow/delivery/<ticket>-code-review.md
Validação .ns-flow/delivery/<ticket>-validation.md
PR .ns-flow/delivery/<ticket>-pr-description.md
Release .ns-flow/delivery/<ticket>-release.md
Encerramento atualizações em .speckit/ + linha em metrics-feed.jsonl

8. Aplicação pelo time (papéis)

Papel Responsabilidade no fluxo
Dev / PO Dispara /feature, responde clarificações, aprova o escopo (CP1)
Tech Lead Aprova arquitetura e plano de tasks (CP2); decide Mini RFC em hotspots
Dev Conduz Execute task a task; mantém o patch dentro do escopo
Reviewer Aprova o PR (CP3)
Release / On-call Aprova o deploy (CP4); confirma o deploy para acionar o learning-agent

Gate de encerramento: o ticket só fecha quando o learning-agent roda após o deploy confirmado. Sem isso, o Speckit fica desatualizado e os próximos tickets ficam mais lentos.

Referências

Voltar ao topo