ddd-architect

Constrói sistemas a partir de um mini-mundo, em quatro fases checkpointadas — e evolui sistemas já construídos em fatias, no modo evolução. Cada fase produz um artefato em docs/ddd/ (no projeto target, não na skill). O usuário revisa cada artefato antes da próxima fase.

Fluxo

Dois modos:

Greenfield (do mini-mundo à v1):

A fase 4 se decompõe em sub-fases (4.0 contratos → 4.1 domínio ∥ → 4.2 aplicação ∥ → 4.3 adapters → 4.4 composition).

Evolução (brownfield — entrada é um CHG-NNN da feature-loop):

Protocolo de ativação

Ao ativar a skill:

1. Detectar o modo. Se a entrada é um CHG-NNN em docs/changes/ (handoff da feature-loop) ou o usuário pede pra evoluir/mudar/consertar um sistema que já tem docs/ddd/ + código construído → modo evolução: leia phases/evolution.md e siga por ele (as fases 1–4 abaixo são o repertório, não o roteiro). Caso contrário, greenfield.
2. Detectar estado (greenfield). Verifique se docs/ddd/ existe no projeto. Se sim, liste os artefatos presentes e pergunte: retomar, revisar fase específica, ou recomeçar. Pule fases já concluídas a menos que o usuário peça revisão.
3. Obter o mini-mundo. Se o usuário não forneceu, peça. Sondar: atores, eventos de negócio, restrições, integrações, escala.
4. Detectar stack. Default Go. Se o usuário passou stack=<nome> ou mencionou outra stack, use-a. Leia templates/stacks/<stack>.md. Se o arquivo não existir, pare e peça ao usuário as convenções; escreva o arquivo de stack antes de prosseguir.
5. Rodar fase a fase, com checkpoint. Leia o arquivo de método da fase, conduza o trabalho em conversa, escreva o artefato usando o template correspondente, apresente, pause. Não avance sem ordem do usuário.

Protocolo de checkpoint

Após cada fase ou sub-fase (4.0, 4.1, 4.2, 4.3.X, 4.4) — antes de propor commit:

1. Atualizar docs/ddd/04-build-log.md com a nova seção (campos mínimos: iniciada/concluída, modo, resultados build/test, arquivos criados/modificados, decisões tomadas, ambiguidades flagadas, ajustes pós-review). Antes do commit, não depois.
2. Verificar build/test verde — go build/vet/test ./... (ou equivalente da stack). Não propor commit com vermelho.
3. Invocar revisões pré-commit quando aplicável:
   • cardpay-skills:review-go — projetos Go (já no CLAUDE.md global).
   • code-review (skill do marketplace oficial) — sempre que houver mudança significativa (≥50 LOC, ≥3 arquivos, ou camada nova). Pedir effort=high pra cobertura ampla.
   • Apresentar achados ao usuário; aplicar os que ele aprovar; documentar os mantidos com justificativa no build log.
4. Salvar artefato no caminho documentado + apresentar ao usuário.
5. Pausar — não avançar sem ordem.

Se o usuário editar o .md manualmente, a versão editada vira a fonte da verdade — a próxima fase lê do disco, não da memória da conversa.

Regras transversais

• Os artefatos são o contrato entre fases. A fase N+1 nunca usa informação da fase N que não esteja escrita no artefato. Se o artefato está vago, conserte o artefato — não compense na próxima fase.
• Seja explícito sobre incerteza. Ao propor um modelo ou decisão, liste alternativas consideradas e o porquê da escolha. Tradeoffs vão no artefato, não só na conversa.
• Não superdesenhe. Calibre a complexidade pelo mini-mundo. Sistema pequeno não precisa de 5 bounded contexts e outbox. A fase 3 explicita esse julgamento.
• Não invente regras de negócio. Se o usuário não disse, não escreva como se ele tivesse dito. Quando faltar info, pergunte.
• Em modo evolução: editar, não reescrever; escopo = fatia; sem commit de entrega. A análise de impacto (o que muda? que trade-offs?) precede qualquer código e para no checkpoint humano. Exceção nomeada — o commit de congelamento: os contratos compartilhados da sub-fase (tático revisado + contracts.go) são commitados antes do despacho dos agents (docs(ddd): congela contratos da fatia CHG-NNN), porque são o contrato de convergência e o hash é o registro da versão que cada agent leu. Cobre artefato de contrato, nunca código de produção nem a entrega; a aterrissagem confere. Artefatos existentes são editados com entrada no histórico de revisões (CHG-NNN), nunca regenerados. A suíte inteira verde é o detector de preservação. Lacuna de produto na história devolve o card à feature-loop — não se remenda aqui.

Agents (dependências)

A fase 4 despacha agents dedicados em paralelo (não general-purpose). Eles devem estar instalados em ~/.claude/agents/:

Os agents são versionados junto com a skill (mesmo repo).

Se o cumprimento de uma instrução depende de um parâmetro de tool, a instrução nomeia o parâmetro — ou é decoração. "Despache ambos em Sonnet" não garante nada: sem model na chamada da tool Agent, o agent herda o modelo da sessão — sem erro, sem aviso, e a instrução parece cumprida. Vale para model, isolation, subagent_type e execução em background.

isolation: "remote" tem uma pré-condição silenciosa: o estado que o agent vai ler precisa existir no remoto. Antes de despachar remoto, verifique e reporte: (a) a branch tem upstream; (b) HEAD está publicado; (c) os artefatos que o agent precisa ler (tático, contratos) estão rastreados e commitados. Se qualquer um falhar, apresente a escolha ao usuário (publicar × rodar local) em vez de despachar — o modo de falha não é um erro, são agents trabalhando contra a árvore errada. Publicar é ação externa: decisão humana, nunca passo automático.

Agent faltante — diagnostique antes de prescrever. Agent type '<nome>' not found tem dois modos de falha, com remediações diferentes e incompatíveis. Rode ls ~/.claude/agents/ antes de reportar:

• arquivo ausente → instalar o agent (estão em agents/ no repo da skill);
• arquivo presente, tipo não registrado → a lista de agents de uma sessão em execução não relê o disco. Só sessão nova resolve; pedir recarga em sessão viva não tem efeito e queima um ciclo de ida e volta com o usuário.

Agent que morreu no meio pode ter entregado. Estouro de limite de gasto, timeout ou interrupção deixam o que já foi escrito intocado em disco — o que não voltou foi o relato, não necessariamente o trabalho. Antes de propor reexecução, liste os artefatos que ele deveria ter produzido e reporte o que existe. Reexecutar às cegas paga de novo exatamente quando o orçamento acabou, e o agent novo pode sobrescrever com outra variante arquivos que o par cego já consumiu.

Arquivos

• phases/01-strategic.md — método estratégico (domínio, subdomínios, linguagem ubíqua, bounded contexts, mapa de contextos)
• phases/02-tactical.md — método tático (entidades, VOs, agregados, repositórios, invariantes, eventos)
• phases/03-architecture.md — árvore de decisão arquitetural (topologia, comunicação, consistência, padrões de leitura, evolução)
• phases/04-implementation.md — orquestrador da fase de código
• phases/evolution.md — modo evolução (brownfield): análise de impacto com checkpoint duro → construção cirúrgica → evolução de artefatos; entrada CHG-NNN, entrega sem commit (exceto o congelamento dos contratos)
• phases/04-0-contracts.md — geração de contratos compartilhados
• phases/04-1-domain.md — domínio em paralelo (testes ∥ código via subagents)
• phases/04-2-application.md — aplicação em paralelo (testes ∥ código via subagents)
• phases/04-3-adapters.md — adapters (sequencial: código → testes de integração)
• phases/04-4-composition.md — composition root, main, smoke test
• templates/01-strategic.md.tmpl — template do artefato estratégico
• templates/02-tactical.md.tmpl — template do artefato tático
• templates/03-architecture-adr.md.tmpl — template do ADR de arquitetura
• templates/stacks/go.md — convenções Go (default)