09 — Cursor multi-agentes + Spec Kit

Visão geral

Dois papéis complementares:

Expand table full width

O Spec Kit diz o quê construir. O Cursor diz quem executa — um agente por spec, ou vários em paralelo quando não há dependência entre specs.

Regras automáticas para o agente: .cursor/rules/spec-kit*.mdc · ops prod: .cursor/rules/server-ssh.mdc
Guia completo (Spec Kit + servidor/psql + prompts): CURSOR.md · Scripts: scripts/README.md

Modos de uso

Uma spec, um agente

Fluxo mais comum no dia a dia:

1. Spec pronta em specs/NNN-nome/ (spec.md, plan.md, tasks.md)
2. No chat: /speckit.implement ou "Implemente a spec specs/NNN-nome/ inteira"
3. Agente lê a spec, executa todas as tasks, marca [x] em tasks.md

Várias specs em paralelo (multi-agent)

Quando o portfólio de specs está definido (Fase 3 do PLAYBOOK):

1. Chat orquestrador — você pede implementação de um intervalo (ex.: specs 006–010)
2. Orquestrador lê specs/README.md (dependências, status shipped)
3. Agrupa specs independentes em ondas e dispara 1 subagente por spec
4. Entre ondas: merge, build, revisão — depois a próxima onda

Você          →  "Desenvolver specs 006 a 010 em multi-agent"
Orquestrador  →  plano de ondas + prompts por spec
Subagente A   →  specs/006-analyzer/ inteira
Subagente B   →  specs/007-metrics/ inteira
   …

Cada subagente deve trabalhar isolado (branch ou worktree separado). Não coloque duas specs no mesmo subagente.

Spec Kit antes do código (BDFU)

Multi-agent acelera a Fase 4 (implementação), não substitui a Fase 3 (specs). Cada módulo de docs/product/04-features-modules.md precisa existir em specs/NNN-nome/ antes de pedir implementação em lote.

Workflow Spec Kit: 03-spec-implementation-flow

Comandos Spec Kit

Expand table full width

Lean (feature pequena): Chat 1 (spec completa) → /speckit.implement

Completo (auth, billing, pagamento): incluir clarify, checklist, analyze

Comandos pnpm (terminal)

Expand table full width

Atalho: CURSOR.md — pipeline, prompts e exemplos.

Cheat sheet — prompts no chat

Expand table full width

Prompt — portfólio (várias specs)

Desenvolver specs 006 a 010 em multi-agent.

Regras:
- 1 agente = 1 spec inteira
- Ler specs/README.md (dependências e status shipped)
- Pular specs shipped salvo gaps explícitos
- Rodar em ondas; merge entre ondas
- Não commitar

Comece pelo plano das ondas. Aguarde meu OK para disparar agentes.

Prompt — uma spec

Implemente a spec specs/NNN-nome-curto/ inteira.
Leia spec.md, plan.md e tasks.md.
Marque tasks concluídas em tasks.md.
Não altere outras specs.

Dependências entre specs

O orquestrador deve consultar a coluna Depende de em specs/README.md. Specs com dependência não entram na mesma onda.

Exemplo (plataforma boilerplate):

Onda 1 → 001, 005
Onda 2 → 003
Onda 3 → 002, 004
Onda 4+ → módulos do produto (006+), conforme índice do fork

No fork: defina dependências ao criar cada spec no índice.

Tasks [P] (opcional)

Marcador [P] em tasks.md indica tasks paralelizáveis dentro da mesma spec (arquivos diferentes, sem dependência). É convenção do Spec Kit — o Cursor não distribui [P] automaticamente.

Para a maioria dos casos: 1 agente = 1 spec inteira basta. Use [P] só se uma spec for muito grande e quiser subdividir manualmente.

Dicas

• Peça em português simples; não precisa termos técnicos no prompt.
• Garanta spec.md + plan.md + tasks.md antes de implementar.
• Billing, auth e pagamento: caminho completo Spec Kit (clarify + security + analyze).
• Após merge: pnpm lint nos apps afetados.
• Peça commit explicitamente; o agente não commita por padrão.
• Atualize specs/README.md quando uma spec for para shipped.

Evite

• Implementar specs que ainda não existem em specs/
• Dois agentes na mesma branch sem isolamento
• Reimplementar specs já shipped sem motivo
• Pular Spec Kit e pedir “faz o módulo X” sem spec

Relacionamentos

Expand table full width