Imagina um piloto de Fórmula 1 sentado num banco de praça. Ele sabe pilotar. Mas sem o carro, sem o volante, sem a telemetria, sem o box, ele não corre.
O modelo de IA é o piloto. O harness é o carro inteiro.
Cursor, Kiro, Claude Code, Windsurf, Cline. Essas não são "IDEs com chat". São agentes de codificação: o modelo, mais o harness do fornecedor (system prompt, ferramentas, orquestração), mais o harness do usuário que você coloca no seu sistema. O modelo opera em loop, lê arquivos, executa comandos e decide o próximo passo. O ChatGPT web? Ele já tem peças de harness: memória entre conversas, agent mode e, no developer mode, cliente MCP completo. No meu setup, ele fica de fora do loop de código: uso como chat, pergunto e ele responde.
A diferença: no chat com a IA generativa, você pergunta e ele fala. No agent de sessão com harness, você pede e ele faz.
Esse "faz" tem cinco camadas. Memory, context e skills alimentam o agent. Tools são as mãos dele. Se você pular uma, o agent opera no escuro.
As cinco são o que você configura por dentro. O arco de fora é outro: harness do usuário (guia antes de gerar, sensor depois), harness do fornecedor (o que a ferramenta já traz) e o modelo no centro. Nesta lista, agents é o loop que decide o próximo passo. Não é uma caixa irmã do modelo.
No Fowler, além de guia e sensor, há três eixos: maintainability, architecture fitness e behaviour. Pensa assim: as cinco camadas são o motor (memória, contexto, skills, agent, tools); os três eixos são o painel (código saudável, arquitetura coerente, negócio certo). Motor sem painel: você acelera no escuro.
O que você leva daqui: o modelo mental das cinco camadas (memory, context e skills alimentando o agent, e o agent usando tools), guia/sensor, os três eixos Fowler e a analogia motor × painel, um caso real de decisão, e o checklist antes de dar autonomia.
Índice
- 1. O harness e as cinco camadas
- 2. Memory: o índice da biblioteca
- 3. Context: a mesa de trabalho
- 4. Skills e steerings: o manual do funcionário
- 5. Agents: quem decide o próximo passo
- 6. Tools e MCP: o crachá universal
- 7. Dois cérebros, duas perguntas
- 8. Caso: quando o vault corrigiu uma hipótese errada
- 9. Checklist antes de dar autonomia
1. O harness e as cinco camadas
Harness é o andaime do modelo. É a infraestrutura que envolve ele: quem define o que ele pode ler, o que ele pode executar, quais regras ele segue, e quando ele para pra perguntar.
O modelo sozinho é capaz. Mas sem harness, ele não tem:
- Memória do que você já decidiu
- Contexto do projeto que você está trabalhando
- Regras de como o time opera
- Ferramentas pra acessar sistemas reais
- Política de quando parar e pedir confirmação
| Ferramenta | O que é | Harness? |
|---|---|---|
| ChatGPT web | Chat com memória, agent mode e MCP (developer mode) | Pode ser: com agent mode e MCP, vira harness. No meu setup, fica como chat |
| Cursor | IDE com agent integrado | ✅ Sim: lê código, executa, decide |
| Kiro | IDE agentic (specs, steerings) | ✅ Sim: sessões estruturadas |
| Claude Code | Terminal agentic | ✅ Sim: executa no shell |
Sim, na tabela, quer dizer que a ferramenta já traz harness de fornecedor e aceita o do usuário. O agente de codificação é o conjunto, não só o modelo.
O diagrama mostra a relação certa: o agent no centro, memory, context e skills alimentando ele, e tools como o que ele executa. Tools não são um andar acima do agent. São o que o agent usa pra agir:
Memory → o índice da biblioteca (vault hub-first)
Context → a mesa de trabalho (só o que entra no prompt agora)
Skills → o manual do funcionário (receitas por domínio)
Agents → quem decide o próximo passo (loop com política)
└─ Tools → o crachá universal que o agent usa (acesso ao mundo externo)
O que acontece sem cada camada
O agent não quebra com erro. Ele degrada. E degradação silenciosa é pior que crash.
| Camada faltando | O que o agent faz | O sintoma que você vê |
|---|---|---|
| Sem Memory | Começa do zero toda sessão. Não lembra o que você decidiu ontem. | Você repete contexto. Ele contradiz decisões anteriores. |
| Sem Context | Opera no escuro ou com contexto genérico. | Inventa nomes de arquivo, sugere padrões que não existem no projeto. |
| Sem Skills | Aplica conselho genérico. | Code review vira KISS/YAGNI de manual, não do seu time. |
| Sem Agents | Você vira o orquestrador manual. | Copia/cola entre chats. Decide cada passo. |
| Sem Tools | Só lê e escreve texto. | Não consulta Jira, não vê o Sentry, não abre PR. |
2. Memory: o índice da biblioteca
Imagina uma biblioteca com 10 mil livros e um índice de 50 páginas. Você tem 10 mil livros (decisões técnicas, contexto de domínio, convenções do time, o que funcionou e o que não).
Sem índice, cada sessão começa do zero. O modelo procura no escuro. Abre gaveta por gaveta. Inventa o que não acha.
Com índice, ele abre a seção certa e segue os links.
Memória não é o histórico do chat. É o que você decide preservar. A forma mais simples é um vault de arquivos markdown. Logseq, Obsidian, uma pasta no git. O formato importa menos que a convenção.
Hub-first: organiza por escopo (ops, carreira, pessoal) e cada escopo tem uma entrada principal. Quando o agent precisa de contexto, ele abre o hub e segue os links. Não fica fazendo grep no escuro.
Uma regra prática que funciona no meu setup: mirar guia always-loaded curto e com sinal alto. No meu harness, steerings inclusion: always com teto de ~200 linhas no CI (check-shared-context.sh no agent-harness). A Anthropic recomenda manter o CLAUDE.md under roughly 200 lines; a doc do Claude Code repete: target under 200 lines per CLAUDE.md file - arquivo longo consome contexto e reduz aderência. Não é limite rígido do produto; é teto de qualidade. Nas best practices, o teste por linha é: se eu tirar isso, o agente erra? Se não, corta. Passou do teto, parto em dois: skill manual, steering com #tag, ou regra com escopo de path.
3. Context: a mesa de trabalho
Pensa numa mesa de trabalho. Quanto mais papel espalhado, mais difícil achar o que importa.
Você não resolve isso comprando uma mesa maior. Resolve com organização. Só o que você precisa agora fica na mesa. O resto volta pro arquivo.
Context window não é disco. Tudo que entra no prompt custa token e ocupa espaço que poderia ser resposta. Context é a seleção do que o modelo precisa saber nesta sessão específica.
Três fontes de contexto:
Arquivos do projeto. O modelo lê o código, a estrutura, os testes. Mas você decide o escopo.
Memória selecionada. Do vault, só o hub do escopo relevante e os arquivos que ele aponta. Não toda a memória de uma vez.
Instrução da tarefa. O que você quer que aconteça nessa sessão. Quanto mais específico, menos o modelo inventa pra preencher lacuna.
O teste prático: se você tapasse o prompt e pedisse pra um colega reconstruir o que o modelo sabe, ele conseguiria em 30 segundos? Se não, o contexto está gordo ou vago.
4. Skills e steerings: o manual do funcionário
Imagina um funcionário novo. Ele sabe fazer o trabalho (o modelo é capaz), mas não conhece o jeito da casa.
O manual do funcionário resolve isso. Convenções, regras, o que pode e o que não pode. Ele não precisa perguntar toda vez. Consulta o manual.
Com modelos é igual. Skills e steerings são o manual.
Manual é guia: entra antes da geração. Quando a skill roda um script e o script recusa o passo (teste, lint, checagem que barra um comando), ela vira sensor. Quem para o loop é o sensor.
No Harness engineering for coding agent users (Birgitta Böckeler), cada peça também tem tipo: computacional (determinístico, rápido) ou inferencial (semântico, mais caro). Guia e sensor são ortogonais ao tipo.
| Peça | Direção | Tipo | Exemplo |
|---|---|---|---|
AGENTS.md, skill de convenção |
feedforward (guia) | inferencial | regras antes de gerar |
LSP, script, kb validate
|
feedback (sensor) | computacional | recusa com exit code |
| Instrução de code review | feedback (sensor) | inferencial | Fowler: instructions how to review são sensor, não só manual antes |
Skill é uma receita sob demanda. Quem ativa é o modelo: ele lê a descrição de cada skill e carrega a receita quando o pedido bate com um domínio específico (code review, auditoria de segurança, escrita de artigo). Você também pode chamar direto, com /nome-da-skill.
Por exemplo: o modelo com a skill de code review não aplica só KISS e YAGNI genérico. Ele conhece as convenções do time: micro-PR sem teste é padrão aceito em certos repos (não cobrar), título de PR só com o código do card pede mais rastreabilidade, commit sem escopo ganha sugestão de conventional commit. Contexto real do time, não conselho genérico.
Steering é regra de projeto, e cada arquivo declara quando entra. No Kiro são quatro modos (docs): always (toda interação), fileMatch (quando você mexe em arquivo que bate com o padrão), manual (você chama com #nome) e auto (entra quando o pedido bate com a descrição). A steering de naming do Jira é always: a convenção já está lá quando você menciona um card. Quando você abre um arquivo de dashboard, a steering de Grafana (fileMatch) já trouxe as 10 regras.
| Skill | Steering | |
|---|---|---|
| Ativação | O modelo decide pela descrição (ou você chama com /) |
Pelo modo do arquivo: always, fileMatch, manual ou auto |
| Escopo | Domínio amplo (code review, AppSec) | Tarefa específica (criar card, criar doc) |
| Custo | Carregada quando precisa | Sempre disponível, entra só quando relevante |
5. Agents: quem decide o próximo passo
Imagina um gerente que delega tarefas. Ele olha o que precisa ser feito, escolhe quem faz, acompanha o resultado, e decide o próximo passo.
Agent é o modelo operando nesse modo. Não é um serviço separado. É o mesmo modelo, com permissão pra decidir o próximo passo sem você confirmar cada ação.
Agent de sessão vs agent loop
Agent de sessão. Você abre, trabalha junto, fecha. Cursor, Kiro, Claude Code, Windsurf. O agent lê o contexto, executa ações, vê o resultado, e decide o próximo passo. Quando você fecha a IDE, o ciclo para. É interativo: você está na cadeira.
Agent loop (full-time). Roda contínuo em background, sem precisar de você na cadeira. O agent monitora, decide, age. Você configura a política e ele executa 24/7. O custo de governança é maior: sem você no loop, a política precisa ser mais restrita.
Trabalho longo com plano e verificação (Ralph loop) para quando o sensor passa: teste, log. O loop de exemplo roda o plano, chama o sensor e fecha quando ele passa, com teto de iterações. Loop em background é outra política. Ele vigia porque você mandou, não porque a tarefa fechou.
O cap que funciona no meu setup
Três agents é o que funciona pra mim. Um pra orquestrar (decide o que fazer), dois especialistas (back, front). Mais que isso e eu começo a depurar agent, não código. Esse número não é regra universal: times com domínios mais complexos ou pipelines de ML podem precisar de mais. O ponto é: comece com poucos e só adicione quando a limitação ficar clara.
Agent é caro. Cada instância carrega contexto, mantém estado, consome tokens por turno. Tudo que cabe numa skill não precisa de um agent novo.
Agent orquestra, skill informa.
6. Tools e MCP: o crachá universal
Imagina um estagiário com crachá universal. Ele entra em qualquer sistema da empresa: Jira, Sentry, banco, Git. Não porque sabe tudo sobre cada sistema. Porque tem o crachá.
O que ele faz com o acesso ainda depende do briefing que recebeu (memory), do que está na mesa dele agora (context), e do manual que consultou (skills).
Tool é a ponte entre o modelo e os sistemas reais. Sem tools, o modelo só lê e escreve texto. Com tools, ele pode consultar o Jira, ler logs do Sentry, fazer query no banco, abrir um PR.
MCP (Model Context Protocol) é o padrão que tornou isso portátil. O modelo se conecta a um servidor MCP e ganha acesso às ferramentas daquele sistema. Mesmo vault, mesmas skills, MCPs de Jira/Sentry/Git conectados, e o harness funciona no Cursor, no Kiro, no que vier.
O que MCP não resolve: tool mal desenhada vira ruído no contexto. Se o servidor retorna 80 campos quando a pergunta precisava de 3, você não resolveu o problema. Empurrou ele pra frente.
Leitura vs escrita não andam no mesmo cano. Ferramenta de leitura (grep, git log, jira_get_issue) não é risco zero. Tudo que ela lê entra no contexto: um card, um README ou uma página com instrução escondida vira prompt injection. E a mesma leitura alcança .env e chaves, que depois vazam por outra tool (um comentário, um request, um PR). Leitura precisa de escopo: allowlist de paths, segredos fora do alcance, conteúdo externo tratado como não confiável. Ferramenta de escrita (git push, HTTP DELETE, deploy) precisa de gate.
7. Dois cérebros, duas perguntas
Esse é o ponto que mais gera confusão: Graphify não substitui o Logseq. São dois cérebros pra duas perguntas diferentes.
| Pergunta | Cérebro certo |
|---|---|
| "O que ficou decidido no incidente do mês passado?" | Vault (Logseq) |
"Quais serviços chamam o RefundService?" |
Graphify (code graph) |
| "Por que escolhi hub-first em vez de embeddings?" | Vault |
| "Qual o blast radius de mudar essa interface?" | Graphify |
A regra prática: se a pergunta tem "código" ou "dependência" no centro, Graphify. Se tem "decisão", "incidente" ou "contexto de domínio", vault. Quando a pergunta mistura os dois, começo pelo vault. É mais barato estar errado ali.
Onde entram os modelos open-source
Modelos proprietários (Claude, GPT, Gemini): latência previsível, sem infra local, custo por token via API.
Modelos open-source (Llama, Mistral, Hermes): pesos abertos, você escolhe como rodar.
A distinção que importa: modelo open-source não significa inferência local gratuita. Se você roda local, troca custo de API por custo de GPU, energia, manutenção. Se você roda via provider (Together, Replicate, Groq), ainda paga por token, só que com modelo de pesos abertos.
Onde modelos open-source entram:
- Dados sensíveis que não podem sair da rede (compliance, regulação)
- Tarefas repetitivas de baixo risco onde o custo de API não compensa
- Fallback quando o provider principal está fora
Onde não entram: substituir o vault ou as skills. O modelo muda. O harness fica.
8. Caso: quando o vault corrigiu uma hipótese errada
Semana passada, investigando um bug, o agent sugeriu que o problema era uma condição de corrida num serviço compartilhado. A sugestão fazia sentido técnico. O stack trace apontava pra lá.
Mas antes de abrir PR, consultei o vault. Hub de ops → incidentes → histórico do módulo. Três meses atrás, investigamos sintoma parecido. A causa raiz era outra: um cache que não invalidava corretamente depois de uma atualização de configuração. O fix foi no cache, não na concorrência.
Sem o vault, eu teria seguido a hipótese do agent. PR no lugar errado. Tempo perdido. Com o vault, o contexto de domínio corrigiu o raciocínio do modelo antes da ação.
O que mudou: não foi o modelo que "aprendeu". Foi o harness que deu contexto. A skill de investigação puxa o hub de incidentes antes de propor fix. O agent continua capaz. O vault é quem evitou o false positive.
Esse é o ponto: as cinco camadas não são teoria. São o que decide se você age no lugar certo ou perde tempo no lugar errado.
9. Checklist antes de dar autonomia
Antes de soltar o agent numa tarefa com consequências, passo por essas perguntas:
Contexto: o que ele precisa saber? Está escrito?
Ferramentas: quais ele pode usar? Quais estão proibidas?
Permissões: read-only por padrão? Ações sensíveis pedem confirmação?
Input não confiável e segredos: o que ele lê (card, README, página, resposta de tool) pode trazer instrução injetada? .env, tokens e chaves estão fora do alcance das tools de leitura?
Sandbox: ele pode fazer algo destrutivo? Tem contenção?
Avaliação: como você sabe se ele fez certo?
Logs: você consegue reconstruir o que aconteceu?
Se você não consegue responder, o harness não está pronto.
Qual dessas cinco camadas você ainda não tem no seu setup: memory, context, skills, agents ou tools?
Outros posts da série Building AI Agents
- Mesmo com GraphRAG, o agent se perde sem contrato de memória
- RAG e MCP, na prática. Cole o prompt e monte os dois
- LangGraph versus LangChain: a conta é cadeia, grafo ou harness
- IA generativa e agentic: o README diz agent. O git não mudou
- Harness Engineering: as 5 camadas do agent (este post)
Para debater: das 5 camadas (memória, contexto, skills, subagentes e ferramentas), qual delas tem gerado mais context drift ou surpresas na fatura no seu dia a dia?
Top comments (0)