Seu agente vai entregar código quebrado.
O spec-agent é o contrato que não deixa. Um gate determinístico, regras de projeto que ele de fato aplica, e aprendizado durável — para Claude Code, Copilot, Cursor & Codex. Não substitui seu agente. Diz não pra ele.
npx @marcusbarcelos/spec-agent init --id meu-projeto --agents claudeO agente diz done. O gate diz: ainda não.
Um checkpoint determinístico entre o seu agente finalizar e o código entrar — não é um prompt. Veja ele barrar um bug real, devolver, e só passar depois de corrigido.
- const slug = name.trim().replace(/\s+/g, "-") // "a b" → "a-b" ✗ colapsa repetições
+ const slug = name.trim().replace(/\s/g, "-") // "a b" → "a--b" ✓SPEC-AGENT VERDICT: PASSED — done means verified
Sem o spec-agent, aquele primeiro diff entra — o agente achou que tinha terminado. Rode você mesmo em 30s: examples/idempotency-demo.
Por que um gate vence um prompt melhor →Agentes de IA são rápidos. E também confiantemente errados.— um agente sem gate é um junior confiante demais
Quando o modelo base já é capaz, prompt sozinho move pouco. A alavanca é governança — barrar o trabalho objetivamente errado e ensinar ao modelo seus invariantes, pra ele aplicá-los em vez de re-deduzi-los errado.
O spec-agent é o contrato de qualidade entre seu repositório e seu agente de código. O tech lead automático que diz "Não. Isso não passa."
Poucas peças. Cada uma para uma falha distinta.
Gate de verificação
Um Stop-hook determinístico que barra o "done" enquanto lint, typecheck ou testes falham no que foi tocado. Pega o erro que o modelo não enxerga em si mesmo.
Project learning & skill-forge
Vira um erro recorrente numa regra imperativa e reaproveitável que o modelo de fato aplica — onde, sem ela, ele sabe a regra e a quebra mesmo assim.
Context-economy
Disciplina de tokens em prompt, tool input e resposta. Um grafo de código no lugar de reler arquivos.
Agent-council
Revisão multi-perspectiva reservada a decisões ambíguas de alto risco — migrações de DB, quebra de contrato, segurança, arquitetura. Não para o dia a dia.
Faça done ser exigível, não um feeling.
spec-agent verify roda seu gate e imprime um veredito que lê como code review — verde no CI, bloqueando no PR, com exit não-zero quando bloqueia.
# .github/workflows/spec-agent.yml - run: npx @marcusbarcelos/spec-agent verify SPEC-AGENT VERDICT: BLOCKED ✗ domain contract node --test idempotency invariant failed: duplicate ledger entry for sale-1 Blocked: 1 check(s) failed. Fix and re-run. Run summary: 1 check · 1 blocked · 0 passed · 127ms
Os checks vivem no .spec/manifest.yaml — seus testes, lint, typecheck, qualquer comando. É aqui que o spec-agent deixa de ser assistente e vira o guardião do repositório.
Demo rodável: examples/idempotency-demo — um ledger de comissão que precisa ser idempotente por sale_id.
Um método reprodutível, e um primeiro sinal honesto.
Um benchmark pequeno e tamper-isolated — o agente nunca vê os checkers. Um método mais um primeiro sinal, não prova. N pequeno, dito abertamente.
| achado | sinal |
|---|---|
| O gate é o ganho | Recuperou uma falha objetiva que o modelo entregou — tarefas-alvo foram de 80% → 100% via o fix-loop. Regras de prompt sozinhas moveram ~0 num modelo capaz. |
| Conhecimento durável muda comportamento | Uma regra de projeto aprendida flipou uma resposta errada pra certa — o modelo sabia a regra e a violou sem a skill. |
| O nicho do council é calibração | Em tradeoffs ambíguos-mas-sãos ele nunca bloqueou à toa (0/4), onde um único pass bloqueou. Real, mas estreito. |
Método e ressalvas completos: RESULTS · SKILLFORGE · COUNCIL. N pequeno — indicativo, não prova estatística.
Funciona com o meu agente? →Funciona com seu agente. Um loss-model honesto.
Harness completo no Claude Code; em outros agentes roda degradado-mas-funcional, com as lacunas registradas no loss_report do manifest.
| capacidade | Claude Code | outros agentes |
|---|---|---|
| gate de verificação | Stop hook | git pre-commit / CI |
| aprendizado durável | skills + memória nativas | .spec/learning/ |
| multi-agent (council) | subagents nativos | simulação single-thread |
| grafo de código | graphify CLI | graphify CLI |
Enhancers específicos de um agente (claude-mem, superpowers, rtk, graphify) são opcionais — nunca dependências.
Três comandos.
# scaffolda .spec/ + adapters no repo atual npx @marcusbarcelos/spec-agent init --id meu-projeto --agents claude,agents-md # re-projeta adapters quando o engine evolui (não toca seu estado durável) npx @marcusbarcelos/spec-agent sync # roda o gate você mesmo (CI / PR) — veredito + exit não-zero se bloquear npx @marcusbarcelos/spec-agent verify
Requer Node ≥ 20. O harness roda dentro do agente de código que você já usa.
Marcus Vinicius Barcelos
Engenheiro de Software Sênior