@fontdata/ai-harness

O harness de engenharia com IA da Fontdata para o Claude Code: fluxos de trabalho, agents, hooks e contratos de documentação que fazem o agente planejar antes de implementar, provar com testes o que entregou e deixar rastro do que fez — em qualquer stack, inclusive Delphi/Pascal e .NET.

Foco exclusivo em Claude Code.

Por que um harness

Um agente de IA sem restrições toma decisões sozinho no meio da implementação, entrega diffs grandes fora do padrão do projeto e escreve testes que passariam com o código errado. As regras escritas num prompt ajudam, mas nada garante que sejam seguidas. O harness se apoia em cinco apostas:

1. Planejar antes de executar. Uma pergunta durante a execução é falha do plano: dúvida vira bloqueio registrado, não improviso.
2. Nada avança sem critério verificável. TDD com pelo menos 2 testes críticos por task; a task só fecha com a suíte verde registrada.
3. Documentação como contrato. Cada trabalho tem a sua pasta, com spec, plano, decisões, bloqueios e relatórios num formato que ferramentas conseguem ler e validar.
4. Quem implementa não aprova. Agents somente leitura revisam os testes, validam os critérios de aceite e auditam o plano.
5. Garantias fora do prompt. Hooks avisam ou bloqueiam de forma determinística, e o rastro de eventos mostra o que aconteceu — inclusive quando um aviso já pode virar bloqueio.

Modo 1 — rodar sem instalar (recomendado)

Na pasta do projeto, chame o comando pelo nome. O Claude Code abre já executando aquele fluxo, com o pacote carregado como plugin só daquela sessão — nenhum arquivo do harness é escrito no repositório.

# npm / npx
npx @fontdata/ai-harness harness
npx @fontdata/ai-harness resolver-bug "login 500 no refresh token"
npx @fontdata/ai-harness versao minor

# yarn
yarn dlx @fontdata/ai-harness harness

# pnpm
pnpm dlx @fontdata/ai-harness harness

Durante a sessão, todos os 19 comandos ficam disponíveis com o prefixo do plugin — /fontdata:nova-tarefa, /fontdata:resolver-bug etc. —, junto com os hooks e os agents do harness. É isso que faz o /harness, que encadeia 4 comandos, funcionar sem instalação prévia.

O texto depois do nome do comando vira o argumento do fluxo. Tudo depois de -- é repassado ao Claude Code:

npx @fontdata/ai-harness harness -- --model claude-opus-5
npx @fontdata/ai-harness auditar-seguranca -- -p     # headless, para CI

Use run <comando> quando o nome colidir com um subcomando do CLI:

npx @fontdata/ai-harness run git-commit-push

Requisito: o Claude Code no PATH (npm i -g @anthropic-ai/claude-code) e Node.js 22 ou superior.

Modo 2 — instalar como plugin global

claude plugin marketplace add fontdata-tecnologia/ai-harness
claude plugin install fontdata@ai-harness

Os comandos passam a existir em qualquer sessão como /fontdata:<comando>, os agents como fontdata:<agent> e os hooks ficam ativos em todos os projetos.

Modo 3 — instalar no projeto (init)

Para versionar comandos, skills, agents e hooks junto com o código:

npx @fontdata/ai-harness init

O init interativo detecta se o projeto é novo ou existente, pergunta o que instalar e grava um lock com o hash de cada arquivo em .ai-harness/lock.json. Instalados assim, os comandos são invocados sem prefixo: /harness, /resolver-bug...

Sem terminal interativo (em CI, por exemplo), o init só simula; --yes aplica:

npx @fontdata/ai-harness init --escopo recomendado --yes
npx @fontdata/ai-harness init --comandos resolver-bug,nova-tarefa --sem-harness --yes

| Flag | Efeito | |---|---| | --escopo recomendado\|tudo | Conjunto de comandos | | --comandos a,b,c | Seleção manual | | --sem-harness | Não inclui o comando-mestre /harness | | --sem-hooks / --sem-agents | Não instala hooks / agents | | --sem-comentarios | Não instala a rule de comentários, o hook e a catraca do legado e lembra a recusa no config | | --sem-banco-dados | Não registra o servidor MCP de banco no .mcp.json e lembra a recusa no config | | --claude-md criar\|manter\|backup\|sobrescrever | O que fazer com o CLAUDE.md (padrão: criar) | | --conflito sobrescrever\|pular | Arquivos que já existem (padrão: pular) | | --yes | Aplica; sem ele, só simula |

Com o plugin fontdata@ai-harness habilitado, o init não instala os hooks no projeto, para eles não rodarem duas vezes.

Permissões para o modo auto

O init e o update gravam em .claude/settings.json as permissões que os fluxos usam, para rodarem sem pedir aprovação, inclusive no modo auto do Claude Code:

• permissions.allow: o rastro, a checagem de conflitos, o doctor e a memoria do harness; git add, git commit e git push (o /git-commit-push); a abertura de sub-agents (Agent); as ferramentas Read, Grep, Glob e Skill; as quatro ferramentas do servidor MCP de banco, inclusive a consultar, que devolve os dados pessoais mascarados; e consultas só de leitura (git status, diff, log, show, blame, gh pr view, gh pr diff, npm outdated...);
• permissions.deny: o push forçado (--force, -f, --force-with-lease e refspec com +), que vence o allow.

Ficam de fora os comandos de teste e build, que variam por projeto, e os que regravam a instalação (init, update, migrar). O projeto acrescenta os seus no próprio settings.json; o harness nunca remove regras. Nos modos 1 e 2 nada é gravado no projeto: rode npx @fontdata/ai-harness update --yes num projeto já instalado, ou init, para receber as regras.

Conexões de banco de dados

O Claude pode ler o banco do projeto (PostgreSQL, MariaDB ou SQLite) sem que ninguém cole credencial no chat. O jeito recomendado para a equipe é a conexão do projeto: o .ai-harness/config.json (versionado) declara o nome da conexão e o nome da variável de ambiente (dsn_env), e cada dev guarda o DSN nessa variável, no env do .claude/settings.local.json (fora do git), no .env ou no ambiente:

npx @fontdata/ai-harness banco-dados adicionar erp   # na raiz do projeto: pergunta os dados, testa e grava ERP_DATABASE_URL
npx @fontdata/ai-harness banco-dados testar

O adicionar grava { "nome": "erp", "dsn_env": "ERP_DATABASE_URL" } em banco_dados.conexoes e a variável no .claude/settings.local.json; fora da raiz de um projeto (sem .git nem .ai-harness/config.json), ele recusa sem gravar nada. Faça commit do config.json; cada colega roda o mesmo comando, que grava só a variável. "producao": true na entrada vale para a equipe toda, e banco-dados remover erp tira a conexão do projeto. Quem prefere um cadastro por máquina (~/.config/ai-harness/conexoes.json) usa banco-dados adicionar erp-dev --global e banco-dados usar erp-dev no projeto.

O servidor MCP banco_dados entrega ao Claude listar_conexoes, listar_tabelas, descrever_tabela e consultar, tudo somente leitura. Ele vem no plugin; sem plugin, o init e o update o registram no .mcp.json (--sem-banco-dados pula). Conexão de produção nasce bloqueada. Use um usuário de banco só com leitura.

Os dados pessoais (CPF, CNPJ, e-mail, telefone, nome, endereço e afins) saem com mascaramento LGPD, feito no servidor antes de a resposta chegar ao Claude; os filtros rodam sobre o dado real. Por isso a consultar fica liberada nas permissões, sem pedir aprovação. Falsos positivos e colunas extras se ajustam em banco_dados.lgpd.liberar_colunas e banco_dados.lgpd.mascarar_colunas; desligar, só no cadastro da máquina. Conexões do projeto, cadastro, limites do filtro, produção, mascaramento e dúvidas frequentes estão no guia de banco de dados.

Subcomandos do CLI

| Subcomando | O que faz | |---|---| | init [caminho] | Instala comandos, skills, agents e hooks no projeto | | doctor [caminho] | Diagnostica instalação, contrato dos documentos, rastro, bloqueios antigos, citações às pastas antigas de docs/ no código e versão do Node | | update [caminho] | Atualiza o que foi instalado sem sobrescrever alterações locais (--check, --yes, --forcar, --sem-banco-dados, --sem-comentarios) | | migrar [caminho] | Move os documentos do layout anterior para docs/trabalhos/<id>/ (--yes); --reclassificar corrige planos migrados que ficaram em execução | | memoria [caminho] | Índice de quem mexeu em cada arquivo (--arquivo <caminho>, --regressao <id>) | | evento <evento> | Grava no rastro do trabalho (usado por fluxos e agents) | | conflitos <id> | Aponta trabalhos em execução que mexem nos mesmos arquivos; --aguardar espera liberar (usado pelo /executar-plan) | | trabalhos arquivar [caminho] | Simula e, com --yes, move para docs/trabalhos/_arquivo/ os trabalhos concluídos há mais de 60 dias (--antes-de <dias>); --remover apaga do disco os que o commit do índice recupera | | trabalhos listar [caminho] | Uma linha por trabalho, arquivados inclusive (--busca, --tipo, --status, --limite, padrão 20) | | banco-dados <subcomando> | Conexões de banco somente leitura: adicionar, listar, testar, usar, remover | | banco-dados-mcp | Servidor MCP de leitura do banco, iniciado pelo Claude Code | | comentarios [caminho] | Instala o hook do padrão de comentários com a catraca do legado (--yes) | | list | Lista o catálogo |

Modelo de arquivos

| Arquivo | Papel | |---|---| | SPEC.md (raiz) | Definição principal do projeto | | CLAUDE.md (raiz) | Context file lido em toda sessão | | docs/trabalhos/AAAA-MM-DD-<slug>/SPEC.md | Spec do trabalho | | docs/trabalhos/<id>/PLAN.md | Plano: sprints, fases e tasks (as tasks também no frontmatter) | | docs/trabalhos/<id>/DECISOES.md | Decisões tomadas no planejamento e na execução | | docs/trabalhos/<id>/BLOQUEIOS.md | Dúvidas que pararam uma task | | docs/trabalhos/<id>/relatorios/TECNICO.md e CLIENTE.md | Relatório para engenharia e para cliente e suporte | | docs/trabalhos/_arquivo/<ano>/<id>/ e INDICE.jsonl | Trabalhos arquivados pelo trabalhos arquivar e o índice que mantém a memória deles | | .ignore (raiz) | Linha docs/trabalhos/_arquivo/, que tira o histórico do Grep e do Glob dos agentes; o git continua versionando | | docs/eventos/<id>.jsonl | Rastro de eventos (não versionado por padrão) | | .ai-harness/lock.json e config.json | Lock da instalação e configuração dos hooks (versionar) |

Os formatos estão em docs/contratos/ARTEFATOS.md e docs/contratos/EVENTOS.md; o doctor valida os dois.

Garantias

Hooks

| Hook | Quando | Modo inicial | |---|---|---| | lembrete | O pedido parece bug, funcionalidade nova, risco de segurança ou problema de performance: sugere o fluxo certo | aviso | | segredo-no-commit | git commit com chave de acesso, token, chave privada ou senha no diff (em arquivo de teste, só token e chave de verdade) | bloqueio | | proteger-contratos | SPEC, PLAN ou CLAUDE.md reescritos durante a execução de um trabalho | aviso | | task-so-fecha-verde | Task marcada como concluída sem suíte verde no rastro | aviso | | sem-jargao | Termo técnico no relatório para o cliente | aviso |

O modo de cada hook (aviso, bloqueio ou desligado) fica em .ai-harness/config.json. Hook que falha internamente não atrapalha o trabalho — exceto o de segurança em modo bloqueio.

Agents somente leitura

| Agent | Papel | |---|---| | revisor-testes | Os testes da task falhariam com a implementação errada? | | qa | Critérios de aceite com evidência e suíte completa antes do gate | | investigador | Causa raiz de um bug, comprovada ou marcada como hipótese | | auditor-plano | O plano pode ser executado sem ninguém perguntar nada no meio? |

Catálogo

⭐ = incluído no conjunto recomendado. (skill) = fluxo publicado como skill: invocado pelo mesmo nome e também acionado pelo modelo quando o pedido combina.

Setup e contexto

• /sincronizar-claude-md ⭐ — gera o SPEC.md e o CLAUDE.md que faltam e reconcilia os existentes com o código e os agents, inclusive a seção de orquestração
• /evoluir-harness ⭐ (skill) — audita a pasta .claude e cria agents, skills, rules, hooks, code-reviewer e design system do projeto

Orquestração & implementação

• /executar-plan ⭐ (skill) — executa o plano com sub-agents, gates de revisor-testes e qa, portões extras do projeto, bloqueios e retomada

Dia a dia

• /resolver-bug ⭐ (skill) — investiga a causa raiz, corrige com teste de regressão e entrega relatório técnico e para o cliente
• /nova-tarefa ⭐ (skill) — verifica se já existe, gera SPEC e PLAN do trabalho, audita o plano e dispara a execução

Qualidade & manutenção de código

• /gerar-testes — escreve testes para o que não está coberto, sem alterar o código de produção
• /refatorar — refatora em passos pequenos com os testes como rede de segurança, inclusive a remoção de código morto
• /atualizar-deps — atualiza dependências em lotes, testando a cada passo

Documentação & onboarding

• /diagrama — gera diagramas Mermaid fiéis ao código
• /onboarding — gera um guia verificado para quem chega no projeto
• /gerar-env — monta o .env.example a partir das variáveis lidas no código

Avançado

• /memoria (skill) — mostra quem já mexeu num arquivo e por quê e aponta regressões candidatas de um bug
• /auditar-ui (skill) — navega a aplicação via Playwright MCP e audita UX/UI e acessibilidade
• /auditar-performance (skill) — mede e audita gargalos de performance
• /auditar-seguranca (skill) — auditoria defensiva de segurança e conformidade com a LGPD

Utilitário

• /git-commit-push ⭐ — gera a mensagem (PT-BR, Conventional Commits) e faz add, commit e push
• /versao ⭐ — detecta o versionamento da stack e aplica bump e changelog, com aprovação e sem push
• /revisar-pr — revisa um PR ou o diff atual, classifica os achados e, se pedido, organiza as correções num trabalho

Setup guiado

• /harness (skill) — conduz o setup em etapas (ideia, contexto, ignores, plano do start, scaffold, peças do harness, auto-tag e execução); /harness <etapa> roda uma etapa isolada

O padrão de comentários não é um comando: a rule, o hook e a catraca do legado vêm do init e do update. O update também o instala em projetos cujo lock é anterior a ele; um hook próprio que já existe, de versão antiga ou adaptado, é mantido e só entra no lock. Para recusar, use --sem-comentarios no init ou no update: a escolha fica em comentarios.instalar: false no .ai-harness/config.json, e o update a respeita. Para reativar, apague a chave e rode update --yes (ou npx @fontdata/ai-harness comentarios --yes). Sem o padrão e sem a recusa, o doctor avisa com comentarios-ausente.

A skill lgpd-checker, usada pela auditoria de segurança, é uma cópia vendorizada de bittencourtthulio/lgpd-checker; veja templates/skills/lgpd-checker/ORIGEM.md.

Fluxo recomendado

O jeito mais simples é rodar /harness, que pergunta se o projeto é novo ou existente e conduz as etapas:

ideia → /sincronizar-claude-md → ignores → /nova-tarefa (start) → scaffold
→ /evoluir-harness (skills, agents, code-reviewer, rules, hooks e rule de projeto) → auto-tag
→ /executar-plan

Em projeto existente, o /harness pula a ideia, o scaffold e a execução, e começa pelo npx @fontdata/ai-harness doctor.

No dia a dia: /nova-tarefa → /executar-plan para funcionalidades, /resolver-bug para defeitos, /git-commit-push e /versao. De vez em quando: /sincronizar-claude-md e /evoluir-harness.

Exemplos

A pasta exemplos/ traz trabalhos gerados em sessões reais do Claude Code sobre um projeto demo: uma funcionalidade nova, uma correção de bug e uma auditoria de segurança, com os documentos de cada um.

Migrando da 2.0 (ou da 1.x) para a 2.1

Node.js 22 ou superior passa a ser exigido. Num branch do projeto, siga esta ordem:

1. npx @fontdata/ai-harness update --check e depois update --yes. O update faz o seguinte:
   • reconhece a instalação de qualquer versão anterior, mesmo sem lock;
   • troca os comandos que viraram skill ou saíram do catálogo, e renomeia para <id>-legado.md os que você editou;
   • instala agents, hooks, o padrão de comentários e a rule de projeto.
2. Leve o que for do projeto nos arquivos -legado para .claude/rules/harness-projeto.md, ou para skills do projeto com /evoluir-harness, e apague os arquivos.
3. npx @fontdata/ai-harness migrar, que só simula, e depois migrar --yes: move os documentos do layout anterior para docs/trabalhos/<id>/.
4. npx @fontdata/ai-harness doctor até não sobrar erro.

O que quebra: os fluxos viraram skills, o /criar-rag foi substituído pela /memoria, o catálogo passou de 36 para 19 comandos e o /configurar-comentarios saiu (veja o CHANGELOG.md). O guia de migração explica cada aviso do doctor e a ordem sugerida para vários projetos.

Migrando do @fontdata/ai-commands

O pacote foi renomeado de @fontdata/ai-commands para @fontdata/ai-harness na versão 2.0.0.

| Você usava | Passe a usar | |---|---| | npx @fontdata/ai-commands <comando> | npx @fontdata/ai-harness <comando> | | /ai-commands:<comando> | /fontdata:<comando> | | Plugin ai-commands@fontdata | Plugin fontdata@ai-harness (veja abaixo) | | npm i -g @fontdata/ai-commands + fontdata-ai-commands init | npm uninstall -g @fontdata/ai-commands && npm i -g @fontdata/ai-harness + fontdata-ai-harness init | | Comandos instalados via init | Nada muda no nome — rode update para receber a 2.1 |

Para trocar o plugin global:

claude plugin uninstall ai-commands@fontdata
claude plugin marketplace remove fontdata
claude plugin marketplace add fontdata-tecnologia/ai-harness
claude plugin install fontdata@ai-harness

Contribuindo

Veja o CONTRIBUTING.md: ambiente, estrutura do repositório e como criar comando, skill, hook e agent. As mudanças de cada versão estão no CHANGELOG.md.

Licença

MIT — veja LICENSE.