Como o harness de IA funciona por baixo do capô

26 de setembro de 2026 · 7 min de leitura

Uso um vault do Obsidian como camada de contexto do Claude Code. Esse post explica como o mecanismo funciona de verdade, peça por peça, em linguagem comum e com o trecho de código real quando dá pra mostrar.

Primeiro, os nomes

O Claude Code é um agente de IA. A diferença pra um chat comum é que você entrega uma tarefa e ele executa os passos sozinho: abre arquivos, edita, roda comandos, confere o resultado. Só que ele começa cada conversa sem lembrar de nada e sem conhecer as regras da minha casa.

O vault do Obsidian é uma pasta de notas em texto simples (Markdown). O Obsidian é o aplicativo que uso pra ler e organizar essas notas. Nessa pasta ficam meus projetos, estudos, livros e também as regras de como tudo deve ser escrito.

Harness é o nome que se dá ao conjunto de coisas que você monta em volta do agente pra ele trabalhar do seu jeito: regras, conferências automáticas, conexões com outras ferramentas. Não existe um harness pronto pra instalar. O meu é feito de peças pequenas, cada uma resolvendo um problema específico:

  • Hooks: pequenos programas que disparam sozinhos depois que o agente escreve algo, e avisam quando saiu do padrão
  • Skills: manuais de procedimento que o agente consulta quando a tarefa aparece, em vez de eu repetir as instruções toda vez
  • MCP: o padrão que liga o agente a uma ferramenta externa (no meu caso, o próprio Obsidian)
  • Agente autônomo: um segundo agente que roda num servidor, sem ninguém olhando, e escreve nas mesmas pastas que eu

Isoladas, cada uma resolve pouco. É o encaixe entre elas que faz o mecanismo funcionar.

Peça 1: hook conferindo o que entra

Toda nota do vault começa com um cabeçalho de campos, o frontmatter, que funciona como uma ficha cadastral: numa nota de livro, por exemplo, tem autor, idioma, formato e status de leitura. É esse cabeçalho que permite filtrar e montar painéis depois.

Agente de IA erra ficha com frequência. Esquece um campo, inventa um status que não existe. Revisar isso na mão, nota por nota, não escala. Então uso um hook, que é um gatilho: o Claude Code chama um script meu toda vez que termina de gravar um arquivo. Pense no corretor ortográfico que sublinha a palavra em vermelho enquanto você digita. Ele não impede você de escrever, só avisa na hora.

const required = ['tags', 'status', 'formato', 'autor', 'idioma'];
const missing = required.filter((field) => !new RegExp(`^${field}:`, 'm').test(fm));

if (missing.length > 0) {
  console.log(JSON.stringify({
    systemMessage: `Aviso: nota de livro ${filePath} sem campo(s): ${missing.join(', ')}.`,
  }));
}

Esse trecho é de um hook real do vault, o que confere nota de livro. Lendo sem saber programar: a primeira linha é a lista de campos obrigatórios; a segunda procura quais deles faltam no cabeçalho; se faltar algum, o script devolve um aviso dizendo qual. O agente recebe esse aviso na mesma hora e corrige. Nada trava, e ninguém precisa revisar linha por linha.

Peça 2: MCP ligando o agente ao Obsidian

Por padrão, o Claude Code não sabe conversar com o Obsidian. Pra isso existe o MCP (Model Context Protocol), um padrão aberto lançado pela Anthropic em novembro de 2024 pra conectar aplicações de IA a sistemas externos. A comparação que a própria documentação usa é a de uma porta USB-C: um encaixe único, e qualquer ferramenta que siga o padrão pode ser plugada no agente.

Do lado do Obsidian, um plugin da comunidade abre essa porta. Do lado do agente, basta um arquivo de configuração dizendo onde ela fica:

{
  "mcpServers": {
    "obsidian": {
      "type": "http",
      "url": "http://127.0.0.1:27123/mcp/",
      "headers": {
        "Authorization": "Bearer ${OBSIDIAN_API_KEY}"
      }
    }
  }
}

Isso fica no arquivo .mcp.json do repositório. Dois detalhes valem pra quem se preocupa com segurança: o endereço 127.0.0.1 significa “este mesmo computador”, então a conexão nunca sai da máquina; e a chave de acesso não está escrita no arquivo, só o nome de uma variável que cada computador guarda localmente. Com o Obsidian aberto, o agente lista, lê e escreve notas como faria com qualquer outra ferramenta, do mesmo jeito que acessaria um banco de dados ou um sistema da empresa.

Peça 3: skill como memória entre sessões

Toda conversa com o agente começa do zero. Sem skill, eu teria que reexplicar em cada sessão como classificar uma captura ou como preencher a ficha de um projeto. Uma skill é um arquivo de texto com nome, descrição e o passo a passo da tarefa, parecido com o procedimento padrão que você entrega a um funcionário novo. O agente lê a descrição e decide sozinho quando precisa abrir aquele manual, sem eu colar o mesmo prompt de novo. O vault tem uma skill por tarefa recorrente (capturar uma fonte, triar o inbox por relevância, auditar um projeto).

Peça 4: o agente que roda sem mim

Um segundo agente roda numa VPS (um servidor alugado na nuvem, ligado o tempo todo), sozinho, e edita o mesmo vault que eu edito no notebook. Ele nem é o Claude Code: é o Hermes Agent, de código aberto, da Nous Research. Os dois nunca conversam entre si, só compartilham os arquivos. Algumas coisas o Hermes não consegue resolver sem mim, como uma operação que exige o Obsidian aberto na minha máquina. Essas vão pra uma fila, anotada numa nota do próprio vault. Na rodada seguinte, do meu lado, eu esvazio essa fila. A IA faz o que dá pra fazer sem supervisão e me entrega só o que sobrou.

Pra quem quer replicar

Nada daqui depende do Obsidian, e nada depende do Claude Code. Hoje o vault é lido e escrito por dois agentes de empresas diferentes, e poderia ser o Codex, o OpenCode ou qualquer outro agente que leia Markdown. O conhecimento fica em arquivo de texto, fora de qualquer ferramenta: se amanhã eu trocar de agente, as regras, os projetos e o histórico continuam onde estão.

Muda a parte mecânica. O hook do jeito que mostrei é recurso do Claude Code, e cada agente tem seu jeito de disparar uma conferência. Skill e MCP já são padrões aceitos por vários deles. O que faz o conjunto funcionar, em qualquer agente, é o hábito de escrever a regra uma vez, num lugar que ele lê, em vez de repetir de memória a cada sessão.

Não sou o único fazendo isso. Karol Attekita, do canal Attekita Dev, mostra num vídeo como documenta em Markdown, pro Claude Code ler, o que o código sozinho não conta: bug já resolvido, decisão técnica, falha intermitente que só aparece dependendo da ordem em que duas tarefas terminam. O formato muda de pessoa pra pessoa, mas a ideia de dar ao agente o contexto por escrito é a mesma.

Quem já usa Obsidian e não quer escrever as próprias skills do zero pode começar pelas de Steph Ango, CEO do Obsidian. Ele publica em github.com/kepano/obsidian-skills um conjunto gratuito que ensina o agente a criar nota com wikilink (o link entre notas) e frontmatter corretos, e a mexer em Bases (as tabelas filtradas do Obsidian) e em Canvas (o quadro visual) sem quebrar o formato. É o mesmo tipo de skill da peça 3, já pronto.

Se faltar alguma peça, me chama no LinkedIn.