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 harnesses — ambientes completos onde o modelo opera em loop, lê arquivos, executa comandos, e decide o próximo passo. O chat do ChatGPT web? No meu setup, não funciona como harness. É uma janela de texto onde o modelo responde e acabou — sem loop, sem ferramentas, sem memória entre sessões. Isso pode mudar com plugins ou GPTs configurados, mas o padrão é chat puro.
A diferença: no chat com a IA generativa, você pergunta e ele fala. No harness, você pede e ele faz.
Esse "faz" tem cinco camadas. Cada uma é o chão da próxima. Se você pular uma, a de cima não sustenta.
O que você leva daqui: o modelo mental das cinco camadas (memory → context → skills → agents → tools), 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 modelo | Depende do setup — padrão é chat puro, sem loop |
| 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 |
A ordem importa porque cada camada é o chão da próxima:
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 (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: arquivo de memória com ~200 linhas. Passou disso, provavelmente está tentando fazer duas coisas — parto em dois. Esse número não é universal: depende da densidade do conteúdo e de como você organiza. O ponto é ter uma heurística que force revisão quando o arquivo cresce demais.
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.
Skill é uma receita sob demanda. Você ativa quando precisa de um domínio específico: code review, auditoria de segurança, escrita de artigo.
Por exemplo: o modelo com a skill de code review não aplica só KISS e YAGNI genérico. Ele sabe que um dev do time faz micro-PRs sem testes (é o padrão dele, não cobrar), que outro colega coloca só o código do card no título (pedir rastreabilidade), que uma terceira pessoa às vezes omite escopo no commit (sugerir conventional commit). Contexto real do time, não conselho genérico.
Steering é uma regra automática. Não precisa ser ativada. Dispara por contexto. Quando você menciona Jira, a steering de naming já carregou a convenção. Quando você abre um arquivo de dashboard, a steering de Grafana já trouxe as 10 regras.
| Skill | Steering | |
|---|---|---|
| Ativação | Você pede | Automática |
| 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.
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) tem risco baixo. 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?
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 Genesia
- GraphRAG, contrato de steering, agentes com memória
- RAG, vetor e MCP na prática
- LangGraph vs LangChain — quando usar framework de agents
- IA generativa e agentic — do README ao código
- Harness Engineering: as 5 camadas do agent (este post)
Top comments (0)