Um livro aberto, em português, sobre a disciplina de construir o scaffolding que envolve agentes de IA — escrito a partir do estudo sistemático de harnesses de código aberto reais.
Este é o repositório oficial de escrita do projeto. Todos os estudos, análises de código, avaliações e comparativos são reportados aqui, e o conjunto forma um livro sobre engenharia de harness: a disciplina de projetar entrega de contexto, interfaces de ferramentas, artefatos de planejamento, loops de verificação, sistemas de memória e sandboxes que determinam se um agente de IA tem sucesso ou falha em tarefas reais.
O método do livro é empírico: em vez de teorizar no abstrato, lemos o código-fonte de harnesses reais (opencode, gemini-cli, OpenHarness, e outros por vir) e extraímos os padrões, as convergências e as divergências de implementação.
| Parte | Conteúdo |
|---|---|
| 00 — Introdução | O que é um harness, por que a disciplina existe, método do livro |
| 01 — Fundamentos | Definições, teoria, artigos canônicos, taxonomia por problema |
| Capítulos por funcionalidade | |
| 02 — Loop do Agente | O ciclo prompt → decisão → ferramenta → resultado |
| 03 — Entrega de Contexto | System prompts, arquivos de regras, montagem hierárquica |
| 04 — Compactação | Gestão da janela de contexto: prune, sumarização, truncamento |
| 05 — Design de Ferramentas | Tools built-in, schemas, seleção por modelo |
| 06 — MCP | Model Context Protocol: transportes, OAuth, descoberta |
| 07 — Permissões e Sandboxing | Modos de aprovação, policy engines, sandbox de SO |
| 08 — Memória e Estado | Sessões, persistência, memória de longo prazo, checkpointing |
| 09 — Planejamento | Plan mode, todo lists, decomposição de tarefas |
| 10 — Subagentes e Orquestração | Delegação, isolamento, times, protocolos (A2A) |
| 11 — Verificação e Evals | Testes do harness, evals comportamentais, LSP em runtime |
| 12 — Extensibilidade | Hooks, plugins, skills, provedores de modelo |
| 13 — Interfaces | TUI, headless, IDE, CI, chat |
| 14 — Convergências e Tendências | O que a indústria já padronizou e a "cláusula de expiração" |
| 15 — O Harness Embutido | Agentes dentro de motores de workflow (n8n): o harness invertido |
| 16 — Aprendizado e Auto-melhoria | O harness que se escreve: dois designs nível 3 (Hermes autônomo × gemini-cli inbox) |
| 17 — A Camada de Protocolos | MCP, A2A, ACP, agentskills.io, AGENTS.md — com matriz de adoção medida no código |
| Bibliografia | Referências científicas por capítulo, com status de validação |
| Histórico | Livro vivo: edições datadas, snapshot por capítulo e o registro de expiração (placar das previsões) |
Trilha prática do livro: um harness completo construído do zero, uma etapa por capítulo (Python + FastAPI + chat mínimo), com arquitetura hexagonal por refatoração e DDD leve. Método pedagógico: Backward Design + 4C/ID + Diátaxis + Carga Cognitiva (ver parecer editorial). Etapas 0 (chat + porta LLM) e 1 (o loop) prontas e testadas — mapa completo.
Seção empírica do livro: avaliação padronizada de harnesses de código aberto, por dimensão, com escala 0–3 e exigência de evidência no código-fonte.
- Metodologia — escala, regras de evidência, categorias, fila
- Template de avaliação — 12 dimensões + 2 suplementares
- Comparativo consolidado — tabelas por categoria, campeões por dimensão, achados transversais
- Avaliações — código: gemini-cli (36) · Codex CLI (35) · Goose (34) · opencode (31) · OpenHarness (29) · Aider (28) · OpenHands (27*) — agentes pessoais: OpenClaw (36) · Hermes (35) · IronClaw (34) — embutidos: n8n (29)
Status: exploratório, rodada 2 concluída (11 harnesses, 3 categorias). Notas provisórias, por leitura assistida de código com evidência por arquivo.
| Harness | Stack | Categoria / arquétipo |
|---|---|---|
| gemini-cli | TypeScript | Código — controle e verificação |
| Codex CLI | Rust (97 crates) | Código — contenção de SO em 3 camadas |
| Goose | Rust | Código — MCP-nativo |
| opencode | TypeScript + Effect-TS | Código — arquitetura de contexto/estado |
| OpenHarness | Python | Código — port didático + swarm |
| Aider | Python | Código — context-first (repo-map) |
| OpenHands | Python + React | Código — control-plane multi-harness |
| OpenClaw | Node.js/TS | Pessoal — plataforma completa (23 canais) |
| Hermes Agent | Python | Pessoal — aprendizado auto-evolutivo |
| IronClaw | Rust (63 crates) | Pessoal — kernel de autoridade zero-trust |
| n8n (nó AI Agent) | TypeScript/LangChain | Embutido — o harness invertido |
Referencial teórico: awesome-harness-engineering (~426 recursos curados, taxonomia por problema).
sync-forks.ps1— script PowerShell para rodar localmente e manter todos os forks do projeto sincronizados com seus upstreams (clona se faltar,fetch upstream+ merge fast-forward-only + push para o fork). Uso:.\scripts\sync-forks.ps1(opções:-BaseDir,-Only repo1,repo2,-NoPush). O merge é ff-only de propósito: commits locais divergentes geram aviso, nunca sobrescrita.
O livro cresce por estudo: cada novo harness avaliado alimenta os capítulos com novos padrões de implementação. Avaliações seguem o template — afirmações sobre um harness exigem evidência (caminho de arquivo no código-fonte).
Esta obra é um livro vivo: cada edição é datada e versionada. O registro de DOI (via Zenodo/DataCite) segue o mesmo modelo — um concept DOI para a obra como um todo (sempre a versão mais recente) e um DOI de versão para cada edição.
Cite assim (o GitHub também mostra um botão "Cite this repository" a partir do CITATION.cff):
Darú, Gilsiley Henrique. Engenharia de Harness — Um livro vivo sobre o scaffolding que envolve agentes de IA. 2026. https://doi.org/10.5281/zenodo.21632412
Autoria e método: obra co-produzida por humano e IA, sob responsabilidade e curadoria humanas; o autor (creator) é Gilsiley Henrique Darú (ORCID 0000-0002-8979-0461) e a assistência de IA é declarada abertamente (Guia Editorial §6), sem figurar como autora (ICMJE/COPE).
Licenciamento duplo, por natureza da obra: