| name | scaffolding-agent-harness |
| description | Use quando o usuário pedir para "gerar um harness", "criar a estrutura de agentes", "fazer o scaffold do .claude/", "configurar agentes/hooks/rules para este projeto" ou equivalente para OpenCode. Constrói do zero um harness de agentes (orquestrador + agents de domínio + reviewer, com hooks/plugins de escopo, guard e stop, rules, skills e commands) para o PROJETO ATUAL, derivando tudo dos artefatos (CLAUDE.md/AGENTS.md/SPEC/PLAN/código) e materializando para Claude Code (.claude/) e/ou OpenCode (.opencode/ + opencode.json). |
Scaffold de harness .claude/ e .opencode/ específico do projeto
Você vai construir, do zero, um harness de agentes para o projeto em que esta
skill está rodando. A arquitetura (a "forma") é fixa e comum aos dois runtimes; todo
o conteúdo (quais domínios existem, que pastas cada agente controla, quais comandos
rodam build/test/lint, quais são as regras invioláveis) é descoberto a partir deste
projeto — nunca copiado de outro.
⚠️ Regra de ouro deste gerador: nada de hardcode de um projeto específico.
Se você se pegar escrevendo "NFe", "SEFAZ", "multi-tenant", "Prisma", "Vercel"
sem ter encontrado isso nos artefatos DESTE projeto, pare — você está copiando,
não derivando. Cada domínio, escopo, comando e regra precisa ter origem
rastreável no CLAUDE.md / SPEC / PLAN / código deste repositório.
$ARGUMENTS (ou o pedido do usuário) pode conter dicas (ex.: "foque em backend", "use
opus no reviewer", "não crie skills", "só Claude Code", "só OpenCode"). Respeite-as.
Quando usar
- O usuário pede para gerar/criar/scaffoldar a estrutura de agentes do projeto.
- Há um
CLAUDE.md / AGENTS.md / SPEC / PLAN e o usuário quer transformá-lo em
um harness operacional de subagentes com escopo fechado.
Quando NÃO usar
- Para editar um único agent já existente (faça direto).
- Para tarefas de produto (escrever código de feature) — isto cria a infra de agentes.
Alvos de runtime
Esta skill materializa a mesma "forma" em um ou ambos os runtimes:
A topologia comum (orquestrador, agents de domínio, reviewer, gates) está em
references/architecture.md. Leia o(s) reference(s) do(s)
alvo(s) escolhido(s) antes de escrever arquivos.
Fase 0 — Descoberta (read-only, obrigatória antes de escrever)
Não escreva nenhum arquivo ainda. Primeiro entenda o projeto:
- Leia os artefatos de especificação, na ordem em que existirem:
CLAUDE.md (raiz e aninhados), AGENTS.md, GEMINI.mdSPEC.md / spec.md, PLAN.md / plan.md, README.md.cursor/rules, docs/ relevantes
- Inspecione a estrutura real com Glob/Grep/Bash:
- layout de pastas de topo (monorepo? app único? packages?)
package.json (workspaces, scripts: o que é build/test/lint/typecheck?)- linguagem(ns), framework(s), gerenciador de pacotes, runner de testes
- se já existe
.claude/ ou .opencode/ — leia o que houver e estenda/atualize
em vez de duplicar
- Detecte o ambiente de hook disponível (para o alvo Claude Code):
- há
python3? jq? (prefira jq, senão python3, senão fallback grep/sed —
escolha UM e use consistente)
- shell padrão; os scripts usam
#!/usr/bin/env bash
- Para OpenCode: confirme que há Node/Bun para os plugins TS (o runtime do OpenCode
já provê; os plugins são
.ts).
- Derive o mapa de domínios. Liste os domínios reais e, para cada um: as
pastas/globs que controla, sua responsabilidade, e os comandos de
verificação que se aplicam. Exemplos do tipo de eixo (NÃO use estes nomes se não
couberem): camada de dados, API/serviço, UI/frontend, lógica de domínio/núcleo,
infra/build/config, testes/qualidade. Use os nomes e fronteiras reais do repo.
- Derive as regras invioláveis. Procure "Nunca fazer", "Constraints", "Segurança",
invariantes de arquitetura, fronteiras de pacote, contratos de API, convenções de
nomenclatura/tipagem. Essas viram as
rules/.
Ao final da Fase 0, apresente ao usuário um plano curto (em texto): a lista de
agents com o escopo de cada um, as rules, skills e commands, o comando de verificação
principal detectado, e qual(is) runtime(s) você vai gerar (Claude Code / OpenCode /
ambos — pergunte se $ARGUMENTS não disser). Peça OK. Só prossiga após confirmação
(a menos que $ARGUMENTS já autorize seguir sem perguntar).
Use a língua predominante dos artefatos do projeto para os textos gerados.
Arquitetura a reproduzir (a "forma")
Ver references/architecture.md para a topologia completa.
Resumo: para cada runtime escolhido, sempre há um orquestrador (primário; coordena,
não escreve código de produto), um agent por domínio real (escopo fechado por
hooks/plugins), e um reviewer read-only (último a ser chamado). Adapte a
quantidade de domínios ao projeto (2 num projeto pequeno; 6+ num monorepo). Não
invente domínios que o projeto não tem; não funda dois domínios reais em um só.
Fase 1 — Agents
Crie um agent por domínio descoberto, mais o orquestrador e o reviewer.
Para ambos, o corpo do agent contém: papel, skills a carregar antes (se houver),
responsabilidades, os padrões DESTE projeto (extraídos do CLAUDE.md/rules), uma seção
"NUNCA faça" com as violações do domínio, e uma seção "Verificação antes de
concluir" com o comando real a rodar e exigência de evidência (saída real) antes de
afirmar que passa.
O orquestrador mantém um "Mapa de agentes especializados" (domínio → quando chamar),
o fluxo clarificação → plano (TodoWrite/todos) → execução via delegação → review →
entrega com saída real; sabe contratar novos agentes quando um pedido cai em domínio
não coberto (avisa, pede OK, cria agent + hooks + rule no mesmo padrão); nunca pede ao
usuário para rodar comandos.
O reviewer é read-only: audita o diff contra as rules, roda build/lint/test/typecheck
mas nada que mude o repo, e emite achados [SEVERIDADE] título / File / Rule / Detail / Fix (BLOQUEANTE / IMPORTANTE / SUGESTÃO) + Summary com saída real e veredito de merge.
Além disso, o reviewer mede e reporta as métricas de qualidade sobre o código tocado
pelo diff e as aplica como gate (BLOQUEANTE acima dos limiares):
- complexidade ciclomática, índice de manutenibilidade (0–100) e duplicação de
código (%) — ver references/code-metrics.md;
- cobertura de código (do diff), pirâmide de testes (unit/integração/E2E conforme
o domínio tocado) e segurança & dependências (audit de deps, SAST, secret scan) —
ver references/test-and-quality-gates.md.
Ferramentas e limiares saem do projeto (derive, não hardcode).
Fase 2 — Hooks (Claude Code) / Plugins (OpenCode)
O mecanismo que torna o escopo real (não só texto no prompt):
- Claude Code: crie
.claude/hooks/<dominio>/ com pre-edit-scope.sh,
pre-bash-guard.sh, post-edit-test.sh (se há testes), stop-<gate>.sh, e o
pre-tool-use.sh do reviewer. Especificação completa em
references/claude-code-target.md. chmod +x em
todos os .sh.
- OpenCode: crie
.opencode/plugin/*.ts com os equivalentes usando os hooks de
evento (tool.execute.before para escopo/guard, tool.execute.after/event para o
gate de stop, negação total de mutação no plugin do reviewer). Especificação completa
em references/opencode-target.md.
Em ambos: bloquear = impedir a ação com mensagem clara em stderr/erro dizendo o
porquê e para qual agente redirecionar; permitir = deixar passar. Garanta que os
caminhos declarados nos agents batem com os arquivos criados.
Fase 3 — Rules
Crie .claude/rules/ (e/ou referencie nas prompts dos agents OpenCode):
- Rules incondicionais na raiz: uma para constraints/segurança invioláveis (cada
regra com o porquê — o que quebra se violar), e uma de convenções gerais (tipagem,
nomenclatura, formato de resposta/erro, fonte de verdade de tipos, fronteiras de pacote,
política de testes). Não invente constraints que o projeto não tem.
- Rule de métricas de código (
rules/metricas-de-codigo.md): os limiares de
complexidade ciclomática, índice de manutenibilidade, duplicação, cobertura de código
(do diff), pirâmide de testes (que tipo de teste cada domínio exige) e
segurança & dependências (deps com HIGH/CRITICAL, SAST, segredos), além das
ferramentas escolhidas — fonte de verdade compartilhada pelo reviewer e pelo command de
entrega. Use os limiares do projeto se ele declarar algum; senão, os padrões de
references/code-metrics.md e
references/test-and-quality-gates.md.
- Rules de domínio em
rules/<dominio>/<regra>.md: os gotchas de cada domínio
que não se inferem lendo um arquivo isolado.
- Cada rule: título curto, bullets densos, links
[[nome]] para rules relacionadas. Só
o que não é óbvio do código.
No OpenCode, como não há diretório rules/ nativo equivalente, materialize as rules como
arquivos em .opencode/rules/ e cite-as explicitamente no prompt de cada agent (e no
reviewer), já que o carregamento condicional difere — ver reference do OpenCode.
Fase 4 — Skills
Crie skills para operações recorrentes e arriscadas DESTE projeto — onde vale um
procedimento guiado (criar um artefato no padrão da casa, um "guarda" que audita as
regras antes de finalizar, um fluxo com ordem/contratos rígidos). Não crie skills
genéricas.
- Claude Code:
.claude/skills/<nome>/SKILL.md.
- OpenCode:
.opencode/skill/<nome>/SKILL.md (mesmo formato de frontmatter).
Cada SKILL.md: frontmatter com name e description (gatilhos concretos); corpo com
"Quando usar"/"Quando NÃO usar", procedimento passo a passo, red flags ✅/🚩, exemplo
input→output, checklist final. Material de apoio em references/ dentro da skill.
Se $ARGUMENTS pedir para pular skills, pule esta fase.
Fase 5 — Commands
Crie commands que despacham o orquestrador para os fluxos recorrentes:
- um comando de implementação ponta-a-ponta (clarificação → plano → execução TDD →
verificação → review);
- um comando de review read-only do diff (despacha só o reviewer) que, além dos
achados, mede e reporta complexidade ciclomática, índice de manutenibilidade,
duplicação, cobertura do diff, pirâmide de testes e segurança & dependências,
bloqueando acima dos limiares;
- comandos de diagnóstico de bug (read-only) e correção de bug (corrige na
causa-raiz com TDD, fecha com reviewer);
- um comando de deploy/entrega que roda os verificadores reais e todos os medidores
de métricas antes de qualquer publicação, não libera se alguma métrica estourar o
limiar, e só faz git/deploy sob pedido explícito.
Os medidores, limiares e a detecção de ferramenta por linguagem estão em
references/code-metrics.md (complexidade, manutenibilidade,
duplicação) e em references/test-and-quality-gates.md
(cobertura, pirâmide de testes, segurança & dependências) — leia ambos antes de gerar os
commands de review e entrega.
Locais: Claude Code .claude/commands/<nome>.md; OpenCode .opencode/command/<nome>.md.
Cada command: frontmatter com description; corpo com fases, Uso (/<comando> <args>)
e agentes/refs envolvidos. Nada de passos manuais para o usuário — tudo via ferramenta.
Fase 6 — Fechamento
- Valide os hooks/plugins: confira que cada
.sh é executável, tem shebang, parseia
o stdin pelo método detectado, e que os caminhos nos agents existem; teste rápido de
um hook de scope com JSON de exemplo (path dentro vs fora do escopo) → exit 0 vs
exit 2. Para OpenCode, confira que os .ts exportam o plugin no formato esperado e
referenciam os globs corretos.
- Não rode build/test/deploy do projeto inteiro (a menos que o usuário peça) — você
só criou a infra de agentes.
- Relate: a árvore gerada (por runtime), o que cada agent cobre, os comandos de
verificação detectados e ligados aos gates, e decisões em aberto (model, skills
futuras). Aponte como contratar um novo domínio depois (o orquestrador já sabe).
Red flags ✅/🚩
- ✅ Cada domínio/glob/comando/regra tem origem rastreável neste projeto.
- 🚩 Você escreveu um nome de domínio/tecnologia que não encontrou nos artefatos → está copiando.
- ✅ O escopo fechado é imposto por hook/plugin, não só por texto no prompt.
- 🚩 O reviewer tem Edit/Write, ou seu guard não bloqueia mutação de fato.
- ✅ Os gates de stop exigem verde real (test/build/validate) com saída colada.
- ✅ Os commands de review e entrega medem e reportam complexidade ciclomática,
manutenibilidade, duplicação, cobertura do diff, pirâmide de testes e
segurança & dependências, com saída real, e bloqueiam acima dos limiares.
- 🚩 Você "estimou" as métricas de cabeça em vez de rodar um medidor real → meça, cole a saída.
- 🚩 Você gerou um technical-debt ratio composto (Sonar) como gate → não é padrão deste
harness; só se o projeto já o usa e o usuário pediu.
- 🚩 Você criou domínio/skill/command que o projeto não justifica → menos, porém certo.
- ✅ Se já existe
.claude//.opencode/, você estendeu preservando customizações.
Checklist final
