Skill — Dev Harness Architect

Harness de desenvolvimento é tudo que envolve o agente de codificação além do próprio modelo: instruções, configuração e sensores que aumentam a qualidade e a segurança do que ele produz. Este skill audita, diagnostica e desenha essa camada — não o runtime de agentes do produto (se houver um), só o harness que governa quem escreve o código.

Antes de qualquer ação, leia reference/harness-model.md se ainda não tiver o modelo carregado nesta sessão — ele tem o quadrante completo guias×sensores e a tabela de adaptação por stack.

Modelo em uma tabela

Eixo	Inferencial (linguagem natural)	Computacional (mecânico)
Guia (feedforward — o que o agente sabe antes de agir)	Arquivo raiz (CLAUDE.md/AGENTS.md), regras de arquitetura, skills, prompts situacionais	Config de linter/formatter/type-checker, manifest de dependências, config de editor
Sensor (feedback — o que verifica o que foi produzido)	Skill de code-review, segundo agente avaliador, revisão humana	Pre-commit hooks, CI em tiers, fitness functions (testes estruturais), guardrails de runtime (hook PreToolUse, gateway de filesystem)

Regra de prioridade: sempre que uma regra puder ser verificada deterministicamente, prefira o sensor computacional. Reserve sensores inferenciais para julgamentos semânticos que código não captura (isso é raro de precisar mudar — quando um sensor inferencial falha repetidamente no mesmo padrão, ele deveria ter virado sensor computacional).

Modo 1 — Auditoria de um harness existente

Objetivo: descobrir o que já está implementado e onde estão os buracos.

1. Procure guias inferenciais: arquivo raiz do agente (CLAUDE.md, AGENTS.md, .github/copilot-instructions.md, .cursor/rules/), diretórios de skills (.claude/skills/, .github/skills/), prompts situacionais (.github/prompts/*.prompt.md, .claude/commands/).
2. Procure guias computacionais: config de editor (.vscode/settings.json, .editorconfig), config de linter/formatter/types (varia por stack — veja a tabela de adaptação), manifest de dependências com versões fixas.
3. Procure sensores rápidos: .pre-commit-config.yaml, hooks git nativos (.git/hooks/), Husky (.husky/), fastlane lanes de lint.
4. Procure sensores de CI: .github/workflows/*.yml, .gitlab-ci.yml, Bitrise/Xcode Cloud config. Identifique os "tiers" (lint/types → testes+cobertura → segurança → arquitetura) — se não há tiers, o CI provavelmente roda tudo num job só e falha lento.
5. Procure sensores estruturais/fitness functions: testes que verificam regras de arquitetura em vez de comportamento (nomes como test_architecture, ArchitectureTests, DependencyRuleTest, config de dependency-cruiser, regras custom de Detekt/SwiftLint).
6. Procure guardrails de runtime: um gateway único de escrita em filesystem (equivalente a PathGuard), uma allowlist de comandos de shell, hooks PreToolUse do Claude Code ou equivalente do Copilot.
7. Reporte em formato de tabela (guia/sensor × presente/ausente × arquivo) e proponha os 2-3 buracos de maior risco primeiro — normalmente: (a) nenhum gateway de escrita/shell, (b) nenhuma fitness function para regras já documentadas em prosa, (c) CI sem tier de segurança.

Modo 2 — Diagnóstico: "por que essa regra não está sendo seguida"

Siga este checklist na ordem — pare no primeiro "não":

1. A regra está documentada? grep -r "<palavra-chave>" <arquivo-raiz-do-agente> <diretório-de-skills> Se não → falta um guia inferencial. Adicione a regra no arquivo raiz, com um exemplo correto e um incorreto. Seja específico: "nunca use URLSession fora de Networking/" é melhor que "use boas práticas de rede".

2. A regra tem um sensor que a verifica? Procure em pre-commit, CI, testes estruturais. Se não → falta um sensor. Veja o skill architecture-fitness-functions para converter a regra num teste determinístico.

3. O sensor está rodando de fato? Rode os comandos de verificação localmente (lint, types, testes estruturais). Um sensor que existe no repo mas não está no CI nem no pre-commit é decorativo.

4. O sensor é forte o suficiente? Se um sensor inferencial (skill de review, segundo agente) falha repetidamente no mesmo tipo de erro → converta para sensor computacional (teste ou grep determinístico no CI).

Modo 3 — Desenhar um harness do zero

Para um projeto novo (qualquer stack):

1. Rode o Modo 1 primeiro — mesmo em projeto novo pode haver config de editor ou CI já herdada de um template.
2. Escolha o arquivo raiz único: se o projeto vai ser trabalhado por mais de um agente de codificação (Claude Code + Copilot, por exemplo), crie um arquivo raiz fino (CLAUDE.md) que só aponta para uma única fonte de verdade (AGENTS.md ou equivalente) — nunca duplique regras em dois lugares, porque eles divergem silenciosamente. Modelo em reference/harness-model.md.
3. Use a tabela de adaptação por stack para escolher as ferramentas computacionais (linter, type-checker, test runner, coverage, security scan).
4. Defina os tiers de CI: Tier 1 lint+types (segundos), Tier 2 testes+cobertura (minutos), Tier 3 security scan (dependências + secrets), Tier 4 arquitetura/fitness functions. Sensores lentos vão para CI; só os rápidos (<5s) vão para pre-commit/hook local.
5. Se o projeto vai usar mudança em fases (proposta → implementação, ex. OpenSpec), use o skill install-dev-harness para materializar os hooks de gate de fase.
6. Escreva pelo menos uma fitness function desde o commit inicial para a regra de arquitetura mais importante do projeto (normalmente: direção de dependência entre camadas, ou um gateway único para uma operação perigosa — escrita em disco, rede, shell).

Sinais de saúde do harness

Sinal observado	Diagnóstico	Ação
Sensor nunca dispara	Cobertura de teste do sensor é fraca, ou o código realmente nunca viola a regra	Adicione um teste negativo (fixture que viola a regra de propósito) para confirmar que o sensor funciona
Guia é ignorado repetidamente pelo agente	Guia inferencial não é suficiente para essa regra	Converta para sensor computacional
PRs sempre reprovam no mesmo tipo de erro	Falta sensor rápido (pre-commit) — o erro só é pego tarde, no CI ou na revisão humana	Adicione o check em pre-commit/hook local
Agente repete o mesmo erro em sessões diferentes	Guia inferencial ausente ou fraco (não estava no arquivo raiz)	Adicione o guia com exemplo concreto
Sensores lentos bloqueando o desenvolvedor local	Sensor pesado demais para pre-commit	Mova para CI, deixe só os sensores <5s localmente

Saída esperada

Ao final de uma auditoria ou desenho, produza:

• Uma tabela guias×sensores do estado atual (ou do estado alvo, no Modo 3).
• Lista priorizada de buracos, cada um com o guia/sensor concreto a adicionar e o arquivo onde vive.
• Se aplicável, aponte para install-dev-harness (esqueleto de fase) e architecture-fitness-functions (converter regra em teste).