{"id":51310843,"url":"https://github.com/orobsonn/claude-harness","last_synced_at":"2026-07-01T04:00:32.650Z","repository":{"id":364113571,"uuid":"1264224171","full_name":"orobsonn/claude-harness","owner":"orobsonn","description":"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.","archived":false,"fork":false,"pushed_at":"2026-06-26T20:28:02.000Z","size":762,"stargazers_count":0,"open_issues_count":2,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-26T21:10:28.311Z","etag":null,"topics":["ai-agents","claude","claude-code","harness-engineering"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/orobsonn.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-09T17:21:37.000Z","updated_at":"2026-06-26T20:28:04.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/orobsonn/claude-harness","commit_stats":null,"previous_names":["orobsonn/claude-harness"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/orobsonn/claude-harness","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/orobsonn%2Fclaude-harness","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/orobsonn%2Fclaude-harness/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/orobsonn%2Fclaude-harness/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/orobsonn%2Fclaude-harness/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/orobsonn","download_url":"https://codeload.github.com/orobsonn/claude-harness/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/orobsonn%2Fclaude-harness/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34992071,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-01T02:00:05.325Z","response_time":130,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agents","claude","claude-code","harness-engineering"],"created_at":"2026-07-01T04:00:21.987Z","updated_at":"2026-07-01T04:00:32.633Z","avatar_url":"https://github.com/orobsonn.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Claude Harness\n\n![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)\n\nUm 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.\n\nA 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.\n\n\u003e **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.\n\n---\n\n## Como uma tarefa flui\n\nToda interação passa primeiro pela **triagem**, que roteia para um de quatro caminhos:\n\n```mermaid\nflowchart TD\n    R([Pedido do operador]) --\u003e T{triaging-requests}\n    T --\u003e|pergunta / leitura| NC[Resposta direta\u003cbr/\u003esem cerimônia]\n    T --\u003e|hotfix óbvio · 1-2 arquivos| Q[QUICK\u003cbr/\u003eimplementa inline + commit]\n    T --\u003e|feature pequena · escopo claro| L[LIGHT]\n    T --\u003e|multi-arquivo · alta severidade · domínio sensível| F[FULL]\n    L --\u003e OD[orchestrating-delivery]\n    F --\u003e OD\n    classDef gate fill:#2d6cdf,stroke:#1b4ba8,color:#fff;\n    class T gate;\n```\n\nPara **LIGHT** e **FULL**, o orquestrador roda a pipeline completa de entrega:\n\n```mermaid\nflowchart TD\n    OD([orchestrating-delivery]) --\u003e SPEC[Spec\u003cbr/\u003euser journeys + acceptance criteria]\n    SPEC --\u003e ADV1[adversary ataca a spec\u003cbr/\u003eantes de escrever o plano]\n    ADV1 --\u003e G1{{HARD-GATE 1\u003cbr/\u003eaprovar spec}}\n    G1 --\u003e PLAN[planner gera\u003cbr/\u003eexecution-plan.json]\n    PLAN --\u003e PRV[plan-reviewer\u003cbr/\u003eaudita a engenharia]\n    PRV --\u003e SP{path sensível?}\n    SP --\u003e|auth / payment / .sql / migrations| FORCE[força FULL]\n    SP --\u003e|não| G2\n    FORCE --\u003e G2{{HARD-GATE 2\u003cbr/\u003eaprovar plano}}\n    G2 --\u003e LOOP\n\n    subgraph LOOP [\"Loop por task — autônomo entre os gates\"]\n        direction LR\n        EX[executor] --\u003e CO[compliance] --\u003e AD[adversary] --\u003e SE[security] --\u003e SN[sniper] --\u003e GA[gates\u003cbr/\u003etsc · test · lint]\n    end\n\n    LOOP --\u003e FDR[final dual review\u003cbr/\u003ecompliance + adversary]\n    FDR --\u003e DEMO[demo validada\u003cbr/\u003econtra os ACs]\n    DEMO --\u003e HARV[harvester\u003cbr/\u003ememória · kaizen · custo]\n    HARV --\u003e SHIP[shipper\u003cbr/\u003ecommit + PR]\n\n    classDef hard fill:#e8a13a,stroke:#a8701b,color:#fff;\n    class G1,G2 hard;\n```\n\nOs 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.\n\n---\n\n## Roteamento de modelos (barbell)\n\nO 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:\n\n```mermaid\nflowchart LR\n    subgraph MAOS [\"Mãos — escrevem código, Ollama barato\"]\n        EXE[\"executor\u003cbr/\u003e\u003ci\u003ehand_tiers\u003c/i\u003e\"]\n        SNP[\"sniper\u003cbr/\u003e\u003ci\u003ehand_tiers\u003c/i\u003e\"]\n        TAU[\"test-author\u003cbr/\u003e\u003ci\u003ehand_tiers\u003c/i\u003e\"]\n    end\n    subgraph MEIO [\"Meio — alto volume, Claude barato\"]\n        ORC[\"orquestrador\u003cbr/\u003e\u003cb\u003eSonnet\u003c/b\u003e\"]\n        CMP[\"compliance\u003cbr/\u003e\u003cb\u003eSonnet\u003c/b\u003e\"]\n    end\n    subgraph OLHOS [\"Olhos — julgam, Claude caro\"]\n        PLA[\"planner\u003cbr/\u003e\u003cb\u003eOpus\u003c/b\u003e\"]\n        PRG[\"plan-reviewer\u003cbr/\u003e\u003cb\u003eOpus\u003c/b\u003e\"]\n        FAG[\"adversary final\u003cbr/\u003e\u003cb\u003eOpus\u003c/b\u003e\"]\n        SEG[\"security\u003cbr/\u003e\u003cb\u003eOpus\u003c/b\u003e\"]\n    end\n    ORC -.dispatcha.-\u003e PLA\n    ORC -.dispatcha.-\u003e PRG\n    ORC -.dispatcha.-\u003e FAG\n    ORC -.dispatcha.-\u003e SEG\n    ORC -.spawn-hand.-\u003e EXE\n    ORC -.spawn-hand.-\u003e SNP\n    ORC -.spawn-hand.-\u003e TAU\n    ORC --\u003e CMP\n```\n\n| Papel | Modelo | Por quê |\n|---|---|---|\n| **orquestrador** (main loop) | **Sonnet** | maior volume de tokens → a economia real |\n| executor / sniper / test-author | **mão Ollama** (`hand_tiers`) | escrevem código — barato, contido pelo trilho determinístico |\n| compliance | Sonnet | spec-vs-implementação |\n| planner | Opus | raciocínio nível arquitetura |\n| plan-reviewer (gate inicial) | Opus | audita o plano antes da execução |\n| adversary (por task) | Opus | já forte; sobe `effort` antes de subir tier |\n| adversary (gate final) | Opus | última fronteira antes da entrega |\n| security | Opus | auditor condicional |\n\n\u003e 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.\n\n---\n\n## Trilho determinístico de entrada\n\nComo 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:\n\n```mermaid\nsequenceDiagram\n    participant O as Orquestrador (Sonnet)\n    participant H as Hook entry-gate\n    participant A as Agente planner (Opus)\n    O-\u003e\u003eH: dispatch do planner\n    H-\u003e\u003eH: triage.json existe?\u003cbr/\u003ebrainstormed + adversary_fired?\n    alt cerimônia incompleta\n        H--\u003e\u003eO: DENY (nomeia o que falta)\n    else ok\n        H--\u003e\u003eA: ALLOW\n    end\n```\n\nOutros trilhos: o guard `\u003cPLANNER-ONLY\u003e` 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.**\n\n---\n\n## Strong eyes, cheap hands\n\nAs 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:\n\n```mermaid\nflowchart TD\n    PIN[\"planner pina\u003cbr/\u003easserção observável\"] --\u003e TA[\"test-author (mão Ollama)\u003cbr/\u003etranscreve 1 teste\"]\n    TA --\u003e CV[\"compliance (olho Claude)\u003cbr/\u003evalida fidelidade\"]\n    CV --\u003e FRZ[(\"teste congelado\u003cbr/\u003econtent-hash manifest\")]\n    FRZ --\u003e SPAWN[\"spawn-hand\u003cbr/\u003eclaude -p contra ollama.com\u003cbr/\u003etoken só no env\"]\n    SPAWN --\u003e HAND[\"mão escreve o diff\u003cbr/\u003econtra o teste read-only\"]\n    HAND --\u003e CAP[\"captura INDEPENDENTE\u003cbr/\u003egit diff + node --test\"]\n    CAP --\u003e V{outcome?}\n    V --\u003e|DONE| OK[task verde]\n    V --\u003e|FAILED / NOT_DONE| ESC[\"escalação K=1\u003cbr/\u003eautorizada por record on-disk\"]\n    classDef rail fill:#2d6cdf,stroke:#1b4ba8,color:#fff;\n    class FRZ,CAP rail;\n```\n\nO que carrega a segurança:\n\n- **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.\n- **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 \u003cfreeze_sha\u003e` ∪ `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.\n- **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.\n- **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.\n\n\u003e 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.\n\n---\n\n## Cross-family eyes — uma segunda família julga ao lado\n\nUm 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`.\n\n```mermaid\nflowchart TD\n    EYE([checkpoint roda um olho]) --\u003e CL[\"olho Claude\u003cbr/\u003eproduz findings/verdict\"]\n    EYE --\u003e CX[\"olho Codex/GPT\u003cbr/\u003eread-only, mesma role\"]\n    CL --\u003e MG{{\"merge · policy B\"}}\n    CX --\u003e MG\n    MG --\u003e|ambas concordam| KEEP[finding mantido]\n    MG --\u003e|só uma família viu| XC[\"a outra família tenta refutar\u003cbr/\u003emantido salvo refutação\"]\n    classDef fam fill:#d2691e,stroke:#8a4513,color:#fff;\n    class CX fam;\n```\n\n**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.\n\n**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.\n\n**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*.\n\n---\n\n## Dois modos de execução\n\nA pipeline é a mesma; muda **quem ocupa os pontos de decisão humana**.\n\n| | **Local** (interativo) | **Headless** (routine na nuvem) |\n|---|---|---|\n| Quem está no loop | o operador, em tempo real | ninguém — roda sozinho |\n| Decisões humanas | gates ao vivo (aprovar spec/plano/demo) | simuladas por agentes; o gate real é a **revisão do PR** |\n| Entrega | merge com OK do operador | abre **PR draft** pra revisão assíncrona |\n| Onde roda | máquina do operador (`~/.claude`) | cloud routine, lendo o `.claude/` commitado no repo |\n\nO modo headless **não substitui** o local — é uma variante autônoma da mesma pipeline, ativada pela instrução no prompt da routine.\n\n---\n\n## Memória e conhecimento\n\nO 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**:\n\n```mermaid\nflowchart TD\n    RUN[\"Run buffers efêmeros\u003cbr/\u003efindings.md · shared_context.md\"] --\u003e|harvester roteia| BR{blast-radius?}\n    BR --\u003e|padrão de projeto| MEM[\".claude/memory/*.md\u003cbr/\u003ecommitted · planner lê\"]\n    BR --\u003e|lei de uma pasta| NEST[\"CLAUDE.md aninhado\u003cbr/\u003eda pasta\"]\n    BR --\u003e|convenção global| KAI[\".claude/kaizen.md\u003cbr/\u003eproposta · humano revisa\"]\n    BR --\u003e|one-off| GIT[\"só no git\"]\n    RUN -.deletado no fim.-\u003e X[(apagado)]\n```\n\n`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).\n\n---\n\n## Medidor de custo\n\nNo 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.\n\n---\n\n## Estrutura\n\n```\ncore/                 # núcleo distribuível → vai pro .claude/ do projeto\n  agents/             # agentes de delivery (planner, executor, adversary, …)\n  skills/             # skills da pipeline (triaging, orchestrating, …)\n    orchestrating-delivery/references/   # runners da mão barata\n                      #   spawn-hand · dispatch-hand · capture-hand (Ollama)\n  rules/              # rules universais (git, security, code-quality, architecture, …)\n  hooks/              # trilhos determinísticos (entry-gate, plan-write-gate,\n                      #   codex-eye-nudge — nudge da segunda família, …)\n  CLAUDE.md           # entry-policy genérica (zero dado pessoal)\n  settings.json       # permissões mínimas, sem flags perigosas\n  memory/             # memória repo-relative\nmodules/              # add-ons opt-in — nunca dependência do core\n  codex-adversary/    #   segunda família de olhos (Codex/GPT), fail-open\n  rtk/ · mv/          #   token-killer · knowledge graph\ndocs/                 # o estudo: constraints da nuvem, auditoria, desenho\n```\n\n**Estado em disco por run:**\n\n```\n.claude/plans/\n  .state/\u003csession_id\u003e/      # efêmero: gate-state.json, triage.json (oculto)\n  \u003cfeature_id\u003e/             # durável: execution-plan.json, shared_context.md\n```\n\n---\n\n## Como usar\n\n**Primeira adoção num projeto novo — um comando:**\n\n```bash\nnpx @orobsonn/claude-harness init\n```\n\nVendora 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`.\n\nVer **[`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.\n\nPara 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).\n\n---\n\n## Status\n\nEm 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.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Forobsonn%2Fclaude-harness","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Forobsonn%2Fclaude-harness","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Forobsonn%2Fclaude-harness/lists"}