Como Montar seu Próprio Harness de IA com Claude Code

Harness, no contexto de IA, é o container arquitetural que executa modelos de linguagem de forma estruturada, com contexto persistente, memória e regras explícitas. Não é o modelo em si — é o sistema em volta dele. Claude Code, Cursor, Windsurf, OpenCode e Hermes são todos harnesses; Claude, GPT, Gemini são modelos.

A distinção importa porque a maior parte das promessas frustradas sobre IA vem de confundir os dois. Trocar de modelo dentro do mesmo harness é trivial. Trocar de harness sem reescrever o sistema é o problema real — é o que Felipe chama de vendor lock-in de plataforma, tratado em detalhe na Aula 02.

Na prática, um harness bem construído transforma o modelo de um chat que responde perguntas em um sistema operacional que executa tarefas encadeadas, lê o projeto inteiro antes de escrever código, mantém memória entre sessões e escala em complexidade sem perder consistência.

Todo harness funcional tem três camadas que se comunicam: contexto, memória e execução. Reduzir o harness a essas três camadas é o mental model que Felipe usa para explicar qualquer sistema de agentes — seja o próprio PD Framework, o HIVE (versão open source), o BMAD, ou frameworks proprietários.

Camada 1 — Contexto: define quem o agente é, o que ele faz, o que ele não faz. No Claude Code, materializa-se como CLAUDE.md em cascata (global, projeto, subpasta). É o que dá personalidade, escopo, regras e restrições de ambiente ao agente.

Camada 2 — Memória: o que já aconteceu e o que está em progresso. No PD Framework é o STATE.md por squad, com três níveis: L1 (status agora), L2 (em progresso), L3 (backlog/decisões). Sem memória, cada sessão começa do zero — o agente esquece decisões anteriores e repete erros.

Camada 3 — Execução: o que o agente sabe fazer de forma repetível. Materializa-se como skills (comportamentos encapsulados invocáveis com `/nome`) e workers (scripts determinísticos que rodam fora do agente, em cron ou hook). Skills atômicas, workers determinísticos: a divisão que permite escalar sem perder previsibilidade.

CLAUDE.md é o arquivo de contexto que o Claude Code lê automaticamente ao abrir um projeto. É onde vive a identidade do agente: quem ele é, qual é o escopo, o que não pode fazer, quais convenções seguir, quais restrições de ambiente respeitar. Felipe descreve como "o manual do chef" — sem ele, o agente é preguiçoso e chuta; com ele, executa com previsibilidade.

Estrutura típica de um CLAUDE.md útil: identidade e persona, stack e tecnologias, convenções de código, regras absolutas (o que nunca fazer), operações destrutivas que exigem confirmação, credenciais e onde ficam, restrições conhecidas do ambiente, comandos e CLIs disponíveis.

CLAUDE.md funciona em cascata — o Claude Code lê o CLAUDE.md global (`~/.claude/CLAUDE.md`), do projeto (raiz do repositório) e de subpastas em ordem, do mais amplo ao mais específico. Isso permite reaproveitar regras universais (segurança, credenciais) e sobrescrever comportamento por área. É a diferença entre "IA que às vezes acerta" e "sistema que executa com previsibilidade em escala".

Um squad é um agente com contexto e memória próprios, escopo delimitado e conjunto de skills específico. Em vez de um agente generalista que tenta fazer tudo mal, o harness organiza o trabalho em múltiplos agentes especializados — cada um com seu CLAUDE.md, seu STATE.md e suas skills.

Padrão que Felipe usa no PD Framework: um squad por área da empresa — Comercial (prospecção, propostas, funil), Marketing (posicionamento, conteúdo, tráfego), CS (onboarding, retenção), Dev (arquitetura, code review), Financeiro (NF, DRE), Produto (roadmap, decisões). Cada squad tem persona, escopo e memória de sua área — o agente do Comercial não sabe o que o Dev está construindo, e é assim que deve ser.

A vantagem principal é contexto enxuto. Quando você abre o squad Comercial, o agente carrega só o que interessa pra Comercial. Isso torna o agente mais rápido, mais barato (menos tokens por chamada) e mais previsível — não há oportunidade para o modelo se distrair com contexto irrelevante.

Dentro de um harness com múltiplos squads, dois papéis se destacam: o orquestrador e os workers. O orquestrador é o agente que decide o que precisa acontecer, delega para o squad certo e coordena a execução. Ele não faz tudo — ele encaminha. No PD Framework, esse papel é do Stamper, o Chief of Staff persistente do Felipe.

Workers são agentes de execução específica. Um worker é chamado, faz sua tarefa determinística e devolve o resultado. Pode ser um squad especializado invocado pelo orquestrador ou um script Python rodando em cron. A regra é: orquestrador decide e delega, worker executa e reporta.

A separação orquestrador/worker resolve escalabilidade, previsibilidade e custo. Você não precisa carregar o contexto do sistema inteiro em toda sessão. Você abre o Stamper, ele identifica que a tarefa é do Comercial e abre o squad Comercial — que carrega só o contexto de comercial. É o mesmo padrão que separa um CEO de um analista.

Hooks são gatilhos que o Claude Code executa automaticamente em pontos específicos do fluxo: antes de usar uma ferramenta (PreToolUse), depois (PostToolUse), quando a sessão encerra (Stop), quando o usuário submete um prompt (UserPromptSubmit). Cada hook é um comando shell configurado no settings.json — o hook não é código dentro do agente, é o harness executando algo automaticamente.

No PD Framework, hooks fazem trabalho invisível mas crítico: criar branch de sessão automaticamente ao primeiro edit, fazer merge no Stop, injetar lookup de conhecimento em prompts com keywords sensíveis (deploy, drop, migration), alertar sobre operações destrutivas.

A regra mental é simples: se você fala 'toda vez que X acontecer, faça Y', isso é um hook — não é memória, não é preferência, não é instrução que o agente lê. O harness executa fora do agente, com garantia de execução. Hooks são o que faz o sistema rodar mesmo quando você não está pedindo.

Uma skill é um comportamento reutilizável que o agente pode invocar com `/nome`. Cada skill é um arquivo Markdown (SKILL.md) com objetivo, steps, inputs, outputs e guardrails. Skills atômicas — pequenas, focadas, com uma responsabilidade cada — são muito melhores que skills grandes que tentam fazer tudo.

Anatomia útil de uma skill: seção Quando ativar (gatilhos que fazem o agente invocá-la), Argumentos (o que ela recebe), Fluxo (steps sequenciais com comandos shell ou operações de arquivo), Pré-condições, Saída esperada, Skills complementares.

Padrão que se repete: skills que geram deploy, skills que documentam, skills que rodam code review, skills que abrem um squad, skills que fecham uma issue no Linear. Cada uma pequena, testável, versionada no repositório. Quando você tem 100+ skills, elas viram uma biblioteca de operações repetíveis que qualquer agente (ou você mesmo, no terminal) pode executar sem precisar reescrever a lógica toda vez.

MCP (Model Context Protocol) é o padrão aberto que permite conectar o Claude a serviços externos sem escrever integração customizada. Notion, Supabase, GitHub, Linear, Google Drive, Slack — todos têm servidores MCP que expõem suas funções ao agente. Você configura o servidor no settings.json, o agente ganha acesso às funções como se fossem tools nativas.

MCP resolve dois problemas de uma vez: elimina o boilerplate de integração (autenticação, paginação, tratamento de erro) e padroniza a forma como o agente vê o mundo externo. O mesmo servidor MCP roda em qualquer harness que fale o protocolo — MCP no Claude Code funciona igual no Cursor, no Windsurf, no OpenCode.

Cuidado prático: cada MCP conectado injeta schema no contexto do agente — dezenas ou centenas de funções que consomem tokens em toda chamada. Conectar tudo por padrão infla o contexto e piora o desempenho. A regra de higiene do PD Framework é manter conectados só os MCPs de uso frequente e desligar os pontuais assim que a tarefa termina.

Usar um único modelo para tudo é caro e inconsistente. Modelos diferentes foram treinados de formas diferentes e têm forças distintas — o fundador da OpenRouter chama isso de neurodiversidade de LLMs, conceito que Felipe explora em profundidade na Aula 03.

Padrão de uso multi-model que Felipe recomenda: Claude Code para construir e orquestrar (contexto grande, ferramentas nativas), Codex/OpenAI para code review (encontra bugs que outros modelos deixam passar), Gemini para geração de imagem (Identity Lock, edição), GPT para classificação e extração estruturada, modelos menores (Haiku, GPT-mini) para tarefas mecânicas de alto volume.

A regra do Felipe: "Barato que não funciona é o mais caro que existe — mas caro pra tarefa simples é dinheiro jogado fora." Cada modelo tem seu papel; o harness bem construído deixa fácil trocar de modelo por tarefa, sem reescrever nada. É essa flexibilidade que separa quem opera IA de quem paga pela IA errada.

Definir limites é tão importante quanto definir capacidades. No settings.json do Claude Code você configura três coisas: quais ferramentas o agente pode usar automaticamente (allow), quais precisam de confirmação (ask), quais estão banidas (deny). Sem essa configuração, cada tool call vira uma pergunta — atrito insuportável — ou pior, tudo passa direto sem controle.

Regras absolutas do Felipe: operações destrutivas (delete de arquivo/tabela, git reset --hard, git push --force, drop, unpublish, kill de processo, mudança em pipeline CI) sempre exigem confirmação textual explícita. Deploy em produção nunca é automático — o agente abre PR, notifica no WhatsApp, espera autorização. "Autorizar merge de X não é autorizar merge de tudo."

A dimensão psicológica também importa. Um agente com permissões amplas demais quebra a confiança rapidamente — um único erro destrutivo custa horas de recuperação e mina a disposição de usar IA. Um agente com permissões restritas demais vira um chatbot glorificado. O ponto de equilíbrio é o padrão que o PD Framework consolidou: leitura livre, mutação com confirmação por contexto, destruição só com autorização textual.