Claude Harness

Um framework de uso do Claude Code para não desenvolvedores (product managers, founders, operadores) entregarem software com pipeline de qualidade — sem precisar julgar arquitetura, segurança ou tradeoffs de baixo nível.

A ideia central: o humano toma decisões de produto (o que construir, aceitar/recusar risco); o sistema resolve a engenharia (como construir, testar, revisar) dentro de um loop de agentes especializados.

Filosofia barbell: orquestração barata no alto volume, raciocínio caro só nas pontas. Um orquestrador Sonnet coordena e delega ao Opus apenas nos gates de fronteira. Mais fundo ainda: as mãos que escrevem código (executor, sniper, test-author) rodam em modelos Ollama baratos, enquanto os olhos que julgam (planner, compliance, adversary, security) ficam em Claude — strong eyes, cheap hands. O que mantém isso seguro não é confiar no modelo barato — são trilhos determinísticos (hooks, guards, plano resolvido, teste congelado, captura independente) que carregam o julgamento crítico.

Como uma tarefa flui

Toda interação passa primeiro pela triagem, que roteia para um de quatro caminhos:

flowchart TD
    R([Pedido do operador]) --> T{triaging-requests}
    T -->|pergunta / leitura| NC[Resposta direta<br/>sem cerimônia]
    T -->|hotfix óbvio · 1-2 arquivos| Q[QUICK<br/>implementa inline + commit]
    T -->|feature pequena · escopo claro| L[LIGHT]
    T -->|multi-arquivo · alta severidade · domínio sensível| F[FULL]
    L --> OD[orchestrating-delivery]
    F --> OD
    classDef gate fill:#2d6cdf,stroke:#1b4ba8,color:#fff;
    class T gate;

Para LIGHT e FULL, o orquestrador roda a pipeline completa de entrega:

flowchart TD
    OD([orchestrating-delivery]) --> SPEC[Spec<br/>user journeys + acceptance criteria]
    SPEC --> ADV1[adversary ataca a spec<br/>antes de escrever o plano]
    ADV1 --> G1{{HARD-GATE 1<br/>aprovar spec}}
    G1 --> PLAN[planner gera<br/>execution-plan.json]
    PLAN --> PRV[plan-reviewer<br/>audita a engenharia]
    PRV --> SP{path sensível?}
    SP -->|auth / payment / .sql / migrations| FORCE[força FULL]
    SP -->|não| G2
    FORCE --> G2{{HARD-GATE 2<br/>aprovar plano}}
    G2 --> LOOP

    subgraph LOOP ["Loop por task — autônomo entre os gates"]
        direction LR
        EX[executor] --> CO[compliance] --> AD[adversary] --> SE[security] --> SN[sniper] --> GA[gates<br/>tsc · test · lint]
    end

    LOOP --> FDR[final dual review<br/>compliance + adversary]
    FDR --> DEMO[demo validada<br/>contra os ACs]
    DEMO --> HARV[harvester<br/>memória · kaizen · custo]
    HARV --> SHIP[shipper<br/>commit + PR]

    classDef hard fill:#e8a13a,stroke:#a8701b,color:#fff;
    class G1,G2 hard;

Os três HARD-GATES humanos — aprovar spec, aprovar plano, testar demo — são as únicas decisões pedidas ao operador, sempre em linguagem de produto. O loop entre eles é totalmente autônomo.

Roteamento de modelos (barbell)

O orquestrador é o maior consumidor de tokens → é onde está a economia. Mais fundo, as mãos rodam fora do Claude (Ollama barato); os olhos Claude entram só nos pontos certos, por override no dispatch:

flowchart LR
    subgraph MAOS ["Mãos — escrevem código, Ollama barato"]
        EXE["executor<br/><i>hand_tiers</i>"]
        SNP["sniper<br/><i>hand_tiers</i>"]
        TAU["test-author<br/><i>hand_tiers</i>"]
    end
    subgraph MEIO ["Meio — alto volume, Claude barato"]
        ORC["orquestrador<br/><b>Sonnet</b>"]
        CMP["compliance<br/><b>Sonnet</b>"]
    end
    subgraph OLHOS ["Olhos — julgam, Claude caro"]
        PLA["planner<br/><b>Opus</b>"]
        PRG["plan-reviewer<br/><b>Opus</b>"]
        FAG["adversary final<br/><b>Opus</b>"]
        SEG["security<br/><b>Opus</b>"]
    end
    ORC -.dispatcha.-> PLA
    ORC -.dispatcha.-> PRG
    ORC -.dispatcha.-> FAG
    ORC -.dispatcha.-> SEG
    ORC -.spawn-hand.-> EXE
    ORC -.spawn-hand.-> SNP
    ORC -.spawn-hand.-> TAU
    ORC --> CMP

| Papel | Modelo | Por quê | |---|---|---| | orquestrador (main loop) | Sonnet | maior volume de tokens → a economia real | | executor / sniper / test-author | mão Ollama (hand_tiers) | escrevem código — barato, contido pelo trilho determinístico | | compliance | Sonnet | spec-vs-implementação | | planner | Opus | raciocínio nível arquitetura | | plan-reviewer (gate inicial) | Opus | audita o plano antes da execução | | adversary (por task) | Opus | já forte; sobe effort antes de subir tier | | adversary (gate final) | Opus | última fronteira antes da entrega | | security | Opus | auditor condicional |

As mãos resolvem o modelo de hand_tiers no dispatch (ladder cravado glm-5.1 → deepseek-v4-pro → kimi-k2.7-code). Um alias Claude pode ser posto direto num tier para uma task sensível. Os olhos são sempre Claude — não-negociável. A economia vem das mãos baratas no alto volume de escrita; o Opus nas pontas é investimento de qualidade, não economia.

Trilho determinístico de entrada

Como o orquestrador é um modelo barato, as decisões críticas não ficam a cargo do julgamento dele — são travadas por hooks do Claude Code. O entry-gate bloqueia o dispatch de agentes de entrega sem a cerimônia cumprida:

sequenceDiagram
    participant O as Orquestrador (Sonnet)
    participant H as Hook entry-gate
    participant A as Agente planner (Opus)
    O->>H: dispatch do planner
    H->>H: triage.json existe?<br/>brainstormed + adversary_fired?
    alt cerimônia incompleta
        H-->>O: DENY (nomeia o que falta)
    else ok
        H-->>A: ALLOW
    end

Outros trilhos: o guard <PLANNER-ONLY> impede o orquestrador de gerar o plano inline (força o dispatch do planner Opus); o override de path sensível é um check de glob; o roteamento de modelo é uma tabela fixa. Quanto mais barato o orquestrador, mais os trilhos carregam o julgamento.

Strong eyes, cheap hands

As mãos que escrevem código rodam num modelo Ollama barato, fora da subscription Claude. O que torna isso seguro não é confiar na mão — é nunca acreditar na prosa dela. Cada task é um par freeze → impl com captura independente:

flowchart TD
    PIN["planner pina<br/>asserção observável"] --> TA["test-author (mão Ollama)<br/>transcreve 1 teste"]
    TA --> CV["compliance (olho Claude)<br/>valida fidelidade"]
    CV --> FRZ[("teste congelado<br/>content-hash manifest")]
    FRZ --> SPAWN["spawn-hand<br/>claude -p contra ollama.com<br/>token só no env"]
    SPAWN --> HAND["mão escreve o diff<br/>contra o teste read-only"]
    HAND --> CAP["captura INDEPENDENTE<br/>git diff + node --test"]
    CAP --> V{outcome?}
    V -->|DONE| OK[task verde]
    V -->|FAILED / NOT_DONE| ESC["escalação K=1<br/>autorizada por record on-disk"]
    classDef rail fill:#2d6cdf,stroke:#1b4ba8,color:#fff;
    class FRZ,CAP rail;

O que carrega a segurança:

• Teste congelado antes da implementação. O planner pina uma asserção observável, a mão test-author a transcreve, um olho Claude (compliance) valida a fidelidade, e o teste é congelado por content-hash. A mão de implementação escreve contra um teste read-only que não pode tocar.
• Captura independente é o gate de registro. O resultado da task não vem da prosa da mão — o harness reconstrói o diff via git diff --name-only <freeze_sha> ∪ git ls-files --others e roda node --test por conta própria (com guard anti-verde-vazio). Escopo, manifest congelado e teste verde são verificados pelo harness, não relatados pelo modelo.
• Escape on-disk não-forjável. Uma escalação para uma mão Claude (K=1) só é liberada quando existe um run-record on-disk — escrito pela captura independente — cujo outcome é uma run genuína não-DONE, ancorada ao freeze_commit_sha. Um ticket forjado por echo não autoriza nada.
• Token nunca vaza. O auth do Ollama vive só no env do processo filho (~/.claude/.dev.vars, resolvido uma vez), nunca em argv/brief/settings; redação on-disk; fail-close se vazar no descriptor.

Provado ao vivo: uma mão qwen3-coder-next autorou um diff in-scope e o teste congelado ficou verde na captura independente (outcome DONE) — sem gastar um token da subscription na escrita.

Cross-family eyes — uma segunda família julga ao lado

Um olho julga melhor quando uma segunda família de modelo julga junto: cada família enxerga os modos de falha que os vieses (priors) da outra deixam passar. O módulo opt-in codex-adversary roda uma segunda família (GPT, via o CLI codex logado por subscription) ao lado do olho Claude — em todo checkpoint que roda um olho crítico: o adversary (na spec, por task, e no dual review final), o security e o plan-reviewer.

flowchart TD
    EYE([checkpoint roda um olho]) --> CL["olho Claude<br/>produz findings/verdict"]
    EYE --> CX["olho Codex/GPT<br/>read-only, mesma role"]
    CL --> MG{{"merge · policy B"}}
    CX --> MG
    MG -->|ambas concordam| KEEP[finding mantido]
    MG -->|só uma família viu| XC["a outra família tenta refutar<br/>mantido salvo refutação"]
    classDef fam fill:#d2691e,stroke:#8a4513,color:#fff;
    class CX fam;

O nudge determinístico (codex-eye-nudge). O risco real não era qualidade — era o orquestrador esquecer de rodar a segunda família (a instrução vivia em prosa, lida no início da sessão). A correção não é uma catraca que bloqueia (rejeitada: forjável + deadlock fail-closed) — é um nudge: um hook PostToolUse[Agent] que, no instante em que o orquestrador despacha um olho elegível, injeta automaticamente o lembrete pra rodar o Codex e mergear. Advisory, nunca bloqueia; cobre todo checkpoint por subagent_type. Não se adiciona gate onde nada está quebrado — os olhos Claude já rodam confiáveis; só a segunda família era pulada.

Merge — policy B (nunca voto de maioria). Uma finding levantada por uma única família é mantida, a menos que a outra família a refute explicitamente. Para o security, o veredito SECURE|UNSAFE continua autoritativo do Claude — uma finding só-do-Codex só escala o gate depois da sua refutação-Claude (precondição de gate-state), então um falso-positivo do Codex nunca vira REVISE/UNSAFE espúrio pelas costas do orquestrador.

Fail-open total — nunca uma dependência rígida. Tudo é opt-in pelo switch HARNESS_CODEX_ADVERSARY. Com o módulo ausente, o switch desligado, em headless sem OPENAI_API_KEY, ou com o codex inalcançável → cada checkpoint roda só-Claude exatamente como hoje. A segunda família é sempre read-only e Claude-tier — um olho, nunca uma mão barata. O valor é comprovado em uso: nesta própria entrega, em cada gate o Codex pegou furos que o Claude não viu (e vice-versa) — a tese, dogfoodada.

Dois modos de execução

A pipeline é a mesma; muda quem ocupa os pontos de decisão humana.

| | Local (interativo) | Headless (routine na nuvem) | |---|---|---| | Quem está no loop | o operador, em tempo real | ninguém — roda sozinho | | Decisões humanas | gates ao vivo (aprovar spec/plano/demo) | simuladas por agentes; o gate real é a revisão do PR | | Entrega | merge com OK do operador | abre PR draft pra revisão assíncrona | | Onde roda | máquina do operador (~/.claude) | cloud routine, lendo o .claude/ commitado no repo |

O modo headless não substitui o local — é uma variante autônoma da mesma pipeline, ativada pela instrução no prompt da routine.

Memória e conhecimento

O harness usa stores nativos, repo-relativos (pra a nuvem enxergar). Ao fim de cada entrega, o harvester roteia o aprendizado durável por blast-radius:

flowchart TD
    RUN["Run buffers efêmeros<br/>findings.md · shared_context.md"] -->|harvester roteia| BR{blast-radius?}
    BR -->|padrão de projeto| MEM[".claude/memory/*.md<br/>committed · planner lê"]
    BR -->|lei de uma pasta| NEST["CLAUDE.md aninhado<br/>da pasta"]
    BR -->|convenção global| KAI[".claude/kaizen.md<br/>proposta · humano revisa"]
    BR -->|one-off| GIT["só no git"]
    RUN -.deletado no fim.-> X[(apagado)]

kaizen.md é uma caixa de saída de propostas de melhoria do próprio harness — nunca auto-aplicadas; o humano revisa e promove. Memória e kaizen são commitados (nunca segredos/PII).

Medidor de custo

No fim de cada entrega, o harvester reporta — em linguagem de produto — o custo da sessão (equivalente-API, breakdown por modelo) e a tendência semanal de consumo do Claude Code, via ccusage sobre o transcript local. O semanal abrange todos os projetos: é um proxy real de consumo, não % da subscription (que é opaca). Fail-soft quando ccusage não está acessível.

Estrutura

core/                 # núcleo distribuível → vai pro .claude/ do projeto
  agents/             # agentes de delivery (planner, executor, adversary, …)
  skills/             # skills da pipeline (triaging, orchestrating, …)
    orchestrating-delivery/references/   # runners da mão barata
                      #   spawn-hand · dispatch-hand · capture-hand (Ollama)
  rules/              # rules universais (git, security, code-quality, architecture, …)
  hooks/              # trilhos determinísticos (entry-gate, plan-write-gate,
                      #   codex-eye-nudge — nudge da segunda família, …)
  CLAUDE.md           # entry-policy genérica (zero dado pessoal)
  settings.json       # permissões mínimas, sem flags perigosas
  memory/             # memória repo-relative
modules/              # add-ons opt-in — nunca dependência do core
  codex-adversary/    #   segunda família de olhos (Codex/GPT), fail-open
  rtk/ · mv/          #   token-killer · knowledge graph
docs/                 # o estudo: constraints da nuvem, auditoria, desenho

Estado em disco por run:

.claude/plans/
  .state/<session_id>/      # efêmero: gate-state.json, triage.json (oculto)
  <feature_id>/             # durável: execution-plan.json, shared_context.md

Como usar

Primeira adoção num projeto novo (máquina de dev) — um comando:

npx @orobsonn/claude-harness setup-local     # (alias: init)

Vendora o harness no .claude/ do diretório atual (idempotente, non-clobber — preserva memory/, kaizen.md, settings.json), pinado na última release. Revise e commite o .claude/. Por baixo é o mesmo vendor-core do updating-harness.

Ligar o motor autônomo + notificações Telegram (na VPS) — wizard interativo:

npx @orobsonn/claude-harness setup-vps

Roda na VPS. Pergunta o projeto/repo/paths e o Telegram (token, chat_id, thread_id, heartbeat), explica como conseguir cada valor (BotFather, getUpdates, topic id), grava o token só no ~/.claude/.dev.vars (0600, fora do git) e registra os crons + notify via install-crons. Notificações são opt-out e fail-open — sem token, o motor roda idêntico.

Ver docs/usage.md — instalar/atualizar o harness num projeto (vendor-core), o padrão de issues (harness-ready), configurar a routine no Claude Code, e setar o modelo do orquestrador.

Para o desenho e as decisões: docs/design.md · docs/cloud-routines.md · docs/audit.md.

OpenCode (dual-runtime) e cutover global

O harness tem layout dual-runtime em core/:

| Pasta | Papel | |---|---| | core/shared/ | libs puras (nunca throw) — paths, validate-plan, merge, capture-oracle, … | | core/claude-code/ | shell Claude Code (agents/skills/hooks) | | core/opencode/ | shell OpenCode (agents/skills/plugin/tools + harness.routing.json) | | core/vps/ | motor headless VPS (fase 2 OC driver fora do DoD fase 1) |

Vendor OpenCode num projeto:

npx @orobsonn/claude-harness init --target opencode

Isso cria .opencode/ no projeto (plugins com paths relativos). O harness global em ~/.config/opencode não deve carregar agents/plugins de delivery depois do cutover — senão o projeto não fica isolado.

Cutover do harness global (T10, depois da parity T11):

./scripts/cutover-opencode-global.sh                 # preflight only (nunca apaga)
./scripts/cutover-opencode-global.sh --apply --i-confirm-cutover   # backup + remove harness

Runbook completo: scripts/cutover-opencode-global.md. Mantém auth de provider, MCP e skills pessoais; remove só o harness. Rollback a partir de ~/.config/opencode/.backup-cutover-<stamp>/.

Release minor (pós DoD fase 1): após TRACK fase 1 completo, publicar minor via skill releasing-versions / release-please. Fase 2 (T12–T14) não entra nesse release.

Spec pack: docs/specs/oc-port/.

Status

Em evolução ativa. Versionado por marco (ver CHANGELOG.md e os releases). Núcleo da pipeline, trilho determinístico de entrada, mão barata Ollama com captura independente (strong eyes, cheap hands) e medidor de custo já operacionais. Dual-runtime OpenCode (fase 1) + cutover global documentado; motor VPS OC é fase 2.

Publicação no npm (mantenedor)

O workflow .github/workflows/npm-publish.yml dispara automaticamente em release: [published].

Setup único (primeira vez):

1. No GitHub → Settings → Secrets and variables → Actions → New repository secret
2. Nome: NPM_TOKEN
3. Valor: token de publish do npm (com permissão para o pacote scoped @orobsonn/claude-harness)
4. A primeira publicação (≥0.40.0) pode exigir OTP/2FA manual do mantenedor no npm.

Subsequentes publicações são automáticas, sem passos manuais.