Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/orobsonn/claude-harness

Harness de entrega determinística para Claude Code: toda tarefa passa por triagem → spec → plano → execução → review adversarial → harvest. Orquestrador Sonnet barato delega aos modelos premium só nos gates de fronteira. Hooks de entrada determinísticos, memória nativa no repo e rotinas headless na nuvem.
https://github.com/orobsonn/claude-harness

ai-agents claude claude-code harness-engineering

Last synced: about 6 hours ago
JSON representation

Harness de entrega determinística para Claude Code: toda tarefa passa por triagem → spec → plano → execução → review adversarial → harvest. Orquestrador Sonnet barato delega aos modelos premium só nos gates de fronteira. Hooks de entrada determinísticos, memória nativa no repo e rotinas headless na nuvem.

Awesome Lists containing this project

README 

          
# Claude Harness



![version](https://img.shields.io/badge/version-0.18.4-blue) ![for](https://img.shields.io/badge/for-Claude%20Code-8A2BE2) ![mode](https://img.shields.io/badge/modes-local%20%C2%B7%20headless-success) ![eyes](https://img.shields.io/badge/eyes-cross--family%20(Claude%20%2B%20Codex)-orange)



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:



```mermaid

flowchart TD

    R([Pedido do operador]) --> T{triaging-requests}

    T -->|pergunta / leitura| NC[Resposta direta
sem cerimônia]

    T -->|hotfix óbvio · 1-2 arquivos| Q[QUICK
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:



```mermaid

flowchart TD

    OD([orchestrating-delivery]) --> SPEC[Spec
user journeys + acceptance criteria]

    SPEC --> ADV1[adversary ataca a spec
antes de escrever o plano]

    ADV1 --> G1{{HARD-GATE 1
aprovar spec}}

    G1 --> PLAN[planner gera
execution-plan.json]

    PLAN --> PRV[plan-reviewer
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
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
tsc · test · lint]

    end



    LOOP --> FDR[final dual review
compliance + adversary]

    FDR --> DEMO[demo validada
contra os ACs]

    DEMO --> HARV[harvester
memória · kaizen · custo]

    HARV --> SHIP[shipper
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:



```mermaid

flowchart LR

    subgraph MAOS ["Mãos — escrevem código, Ollama barato"]

        EXE["executor
hand_tiers"]

        SNP["sniper
hand_tiers"]

        TAU["test-author
hand_tiers"]

    end

    subgraph MEIO ["Meio — alto volume, Claude barato"]

        ORC["orquestrador
Sonnet"]

        CMP["compliance
Sonnet"]

    end

    subgraph OLHOS ["Olhos — julgam, Claude caro"]

        PLA["planner
Opus"]

        PRG["plan-reviewer
Opus"]

        FAG["adversary final
Opus"]

        SEG["security
Opus"]

    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:



```mermaid

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?
brainstormed + adversary_fired?

    alt cerimônia incompleta

        H-->>O: DENY (nomeia o que falta)

    else ok

        H-->>A: ALLOW

    end

```



Outros trilhos: o guard `` 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:



```mermaid

flowchart TD

    PIN["planner pina
asserção observável"] --> TA["test-author (mão Ollama)
transcreve 1 teste"]

    TA --> CV["compliance (olho Claude)
valida fidelidade"]

    CV --> FRZ[("teste congelado
content-hash manifest")]

    FRZ --> SPAWN["spawn-hand
claude -p contra ollama.com
token só no env"]

    SPAWN --> HAND["mão escreve o diff
contra o teste read-only"]

    HAND --> CAP["captura INDEPENDENTE
git diff + node --test"]

    CAP --> V{outcome?}

    V -->|DONE| OK[task verde]

    V -->|FAILED / NOT_DONE| ESC["escalação K=1
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 ` ∪ `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`.



```mermaid

flowchart TD

    EYE([checkpoint roda um olho]) --> CL["olho Claude
produz findings/verdict"]

    EYE --> CX["olho Codex/GPT
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
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**:



```mermaid

flowchart TD

    RUN["Run buffers efêmeros
findings.md · shared_context.md"] -->|harvester roteia| BR{blast-radius?}

    BR -->|padrão de projeto| MEM[".claude/memory/*.md
committed · planner lê"]

    BR -->|lei de uma pasta| NEST["CLAUDE.md aninhado
da pasta"]

    BR -->|convenção global| KAI[".claude/kaizen.md
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](https://ccusage.com) 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//      # efêmero: gate-state.json, triage.json (oculto)

  /             # durável: execution-plan.json, shared_context.md

```



---



## Como usar



**Primeira adoção num projeto novo — um comando:**



```bash

npx @orobsonn/claude-harness 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`.



Ver **[`docs/usage.md`](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/design.md) · [`docs/cloud-routines.md`](docs/cloud-routines.md) · [`docs/audit.md`](docs/audit.md).



---



## Status



Em evolução ativa. Versionado por marco (ver [`CHANGELOG.md`](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.