Desvendando as Camadas de AI

Um e-book para desenvolvedores que querem se tornar AI-native — não só usar o chat, mas entender e construir os sistemas agênticos por baixo dele.

Você já programa. Sabe ler um stack trace, desenhar um schema, discutir um trade-off de arquitetura. Mas o vocabulário novo chega rápido demais: LLM, harness, agent, subagent, context, skill, plugin, MCP, CLI. Todo mundo usa esses termos como se fossem óbvios, e raramente alguém mostra onde cada um encaixa e como se conectam.

Este e-book resolve isso de um jeito específico: em vez de definir cada palavra isolada, ele constrói uma camada de cada vez em cima de um exemplo único e concreto, e a cada capítulo amarra de volta à camada central — o agent.

Para quem é

• Desenvolvedores que já programam e querem dominar a arquitetura de sistemas agênticos.
• Quem usa Claude Code (ou ferramentas similares) no dia a dia mas trata tudo como caixa-preta.
• Times que querem padronizar como constroem, empacotam e compartilham agentes.

Não é um tutorial de "como usar o chat". É sobre como o stack funciona por dentro e como você projeta em cima dele.

O fio condutor

Todo capítulo usa a mesma tarefa concreta:

Construir um sistema universal de CRUD de Pedidos (Orders).

Uma tarefa real de engenharia de software, que qualquer desenvolvedor reconhece e que possui a complexidade ideal para demonstrar quase todas as camadas agênticas. Vamos ver:

• por que o LLM sozinho sabe descrever uma API de pedidos, mas não consegue escrever os arquivos ou rodar o banco;
• como o harness dá olhos e mãos ao modelo para criar e alterar arquivos;
• como um agent (agent-order-orchestrator) transforma o modelo genérico em um especialista de domínio;
• como uma squad de subagents divide a tarefa em frentes de produto, arquitetura, backend, frontend, QA e infra;
• e como context, skill, plugin, MCP e CLI entram para tornar essa operação robusta, reaproveitável, segura e eficiente.

O modelo mental

As camadas não são uma pilha rígida de cima para baixo — elas se compõem. Mas há uma ordem de dependência que ajuda a pensar:

graph TD
    LLM["LLM — o cérebro: prevê o próximo token"]
    HARNESS["Harness — o corpo: loop, ferramentas, permissões"]
    AGENT["Agent — o especialista: prompt + modelo + ferramentas"]
    SUB["Subagent — a squad: delegação em contexto próprio"]
    CTX["Context — o que o agente enxerga"]
    SKILL["Skill — conhecimento sob demanda"]
    MCP["MCP — conexão com o mundo externo"]
    PLUGIN["Plugin — empacotamento distribuível"]
    CLI["CLI — onde você opera tudo"]

    LLM --> HARNESS
    HARNESS --> AGENT
    AGENT --> SUB
    CTX -.alimenta.-> AGENT
    SKILL -.estende.-> AGENT
    MCP -.conecta.-> AGENT
    PLUGIN -.empacota.-> AGENT
    CLI -.opera.-> HARNESS

Leia assim: o LLM é o cérebro. O harness é o corpo que dá a ele olhos, mãos e um loop de ação. O agent é uma configuração desse conjunto para um trabalho específico. Tudo o mais — subagent, context, skill, plugin, MCP, CLI — existe para tornar o agent mais capaz, mais confiável ou mais fácil de operar.

Capítulos

Como ler

Linear, do 01 ao 10, é a forma recomendada na primeira vez — cada capítulo assume o anterior. Mas o capítulo 03 (agent) é o centro de gravidade: se você só tem 20 minutos, leia o 01, o 02 e o 03 nessa ordem e já terá o modelo mental que sustenta o resto.

Cada capítulo segue a mesma disciplina pedagógica:

1. Exemplo primeiro. Você vê o conceito em uso antes de qualquer definição.
2. Definição depois. Só então formalizamos o termo.
3. Amarração com o agent. Toda camada fecha mostrando como se conecta ao capítulo-âncora.
4. Trade-offs reais. O que custa, onde falha, quando não usar.
5. Fontes primárias. Docs oficiais e papers, não blogs de terceiros.

Convenções

• Idioma: português brasileiro. Estes .md são a única fonte da verdade. Versões em outros idiomas são geradas depois, a partir do HTML — o conteúdo-fonte nunca é replicado por idioma.
• Modelos citados: a família Claude 4.X é usada como referência concreta — Opus 4.8 (claude-opus-4-8), Sonnet 4.6 (claude-sonnet-4-6), Haiku 4.5 (claude-haiku-4-5). Os conceitos valem para qualquer LLM moderno.
• Voz: a inspiração em educadores como Andrej Karpathy (código primeiro) e em autores de engenharia como Robert C. Martin e Martin Fowler (clareza de princípios) é tom, não citação. Nenhuma frase é colocada na boca de pessoas reais.

Comece pelo Capítulo 01 — O LLM.

Capítulo 01 — O LLM

Um LLM é um previsor do próximo token. Poderosíssimo no que sabe; cego para o que não está na frente dele.

TL;DR: O LLM prevê o próximo token e raciocina sobre o mundo, mas não tem memória, olhos nem mãos — todas as outras camadas deste e-book existem para dar isso a ele.

Antes de falar de agentes, harness e MCP, precisamos do tijolo de baixo. Todas as camadas deste e-book existem para compensar o que o LLM não faz sozinho. Então vamos começar vendo exatamente onde ele brilha e onde ele para.

Primeiro, o LLM em ação (e sua limitação)

Cole isto num chat de LLM puro, sem nenhuma ferramenta:

> Como eu crio uma API de CRUD de Pedidos (Orders) no meu sistema?

A resposta vem confiante e útil em geral:

Para criar um CRUD de Pedidos, você normalmente:
1. Expõe um endpoint POST `/orders` para criar o pedido com status inicial `created`.
2. Expõe um endpoint GET `/orders/:id` para recuperar os detalhes.
3. Expõe um endpoint PUT `/orders/:id` para atualizar dados ou transicionar o estado (ex.: `created` -> `paid`).
4. Expõe um endpoint DELETE `/orders/:id` para efetuar o cancelamento ou exclusão lógica.

Correto, genérico, e inútil para o seu caso específico. Por quê? Porque o modelo:

• não sabe se o seu serviço está em orderController.ts ou OrderService.java;
• não sabe que o seu banco é o PostgreSQL e que você utiliza o Prisma ORM;
• não pode abrir o seu repositório, rodar um teste, nem lembrar do que disse ontem;
• vai inventar nomes de função plausíveis se você pedir o código — e errar os seus.

O modelo é um excelente raciocinador sobre conhecimento geral do mundo. Mas ele não tem olhos para o seu projeto, mãos para agir, nem memória entre conversas. Guarde essa frase: o LLM é o cérebro; ele ainda não tem corpo.

O que é um LLM

Um LLM (Large Language Model, modelo de linguagem de grande escala) é uma rede neural treinada para prever o próximo token de uma sequência, a partir de um enorme corpus de texto e código.

"Token" é um pedaço de texto — pode ser uma palavra, parte de uma palavra ou um sinal de pontuação. O modelo recebe uma sequência de tokens (o seu prompt) e produz uma distribuição de probabilidade sobre qual token vem em seguida. Escolhe um, anexa, e repete. Texto inteiro sai um token de cada vez.

Parece simples demais para explicar o que vemos. A intuição que falta é a escala: quando você treina um previsor de próximo token bom o suficiente, em dados suficientes, prever a continuação exige modelar gramática, fatos, estilos de código, raciocínio passo a passo — porque tudo isso aparece nos dados. A capacidade emerge da tarefa simples levada ao extremo.

Como funciona, em três níveis de zoom

Zoom 1 — a tarefa. Dado "o céu é", o modelo atribui alta probabilidade a "azul". Dado "def soma(a, b): return", ele atribui alta probabilidade a "a + b". A mesma máquina, domínios diferentes.

Zoom 2 — a arquitetura. Praticamente todo LLM moderno é um Transformer, a arquitetura introduzida no paper "Attention Is All You Need" (Vaswani et al., 2017). A peça central é a atenção: para prever o próximo token, o modelo pondera quais tokens anteriores importam mais. É isso que permite manter coerência ao longo de um texto longo.

Zoom 3 — o que você controla. Dois botões importam no dia a dia:

• Temperatura: o quão "ousado" é o sorteio do próximo token. Temperatura baixa → respostas mais determinísticas e repetíveis; alta → mais variadas e criativas. Para tarefas de engenharia, baixa costuma ser melhor.
• Janela de contexto: quantos tokens o modelo consegue "ver" de uma vez (prompt + resposta). Tudo que não cabe na janela, o modelo não enxerga. Esse limite é tão central que merece um capítulo só: Capítulo 05 — O Context.

O que o LLM não faz sozinho

Esta lista é o motivo de existirem todas as outras camadas:

Nenhuma dessas é um "bug" do modelo. São consequências diretas do que ele é: um previsor de tokens, não um sistema com estado e acesso ao mundo. As camadas seguintes são, literalmente, o trabalho de dar estado e acesso a esse cérebro.

Model routing: nem todo cérebro para toda tarefa

LLMs vêm em tamanhos. Na família Claude 4.X usada como referência neste e-book:

• Opus 4.8 (claude-opus-4-8): o mais capaz. Raciocínio profundo, trade-offs ambíguos, arquitetura. Mais caro e mais lento.
• Sonnet 4.6 (claude-sonnet-4-6): equilíbrio. Ótimo para execução de padrões já definidos, volume de código.
• Haiku 4.5 (claude-haiku-4-5): o mais rápido e barato. Ideal para passes mecânicos — lint, normalização, classificação simples.

Escolher o modelo certo para cada tarefa chama-se model routing. Não é detalhe de custo: é casar a dificuldade da tarefa com a capacidade do modelo. É também por isso que o frontmatter do agent (Capítulo 03) tem um campo model — você decide, por papel, qual cérebro roda.

Como isso se conecta ao agent

O agent do Capítulo 03 não é o LLM — ele configura o LLM. Quando você escreve no frontmatter:

model: opus

você está dizendo "este especialista usa o cérebro mais potente, porque o trabalho dele (decisões de arquitetura) é ambíguo". Trocar para model: haiku mantém o mesmo prompt, o mesmo papel, as mesmas ferramentas — mas com um cérebro mais rápido e mais barato, adequado a tarefas mecânicas. O agent é a configuração; o LLM é a peça configurável mais importante dela.

E todo o resto do e-book — harness, context, tools, MCP — existe para entregar a esse cérebro o que ele não tem: olhos, mãos e memória.

Trade-offs e armadilhas

• Confiança ≠ correção. O modelo soa igualmente seguro quando acerta e quando alucina. Para fatos e APIs específicas, verifique — não confie na fluência.
• Maior nem sempre é melhor. Usar o modelo mais caro para tudo é desperdício e mais lento. Roteie por dificuldade.
• Conhecimento tem data. O treino tem um corte temporal. Para "o que mudou ontem", o modelo precisa de contexto fresco vindo de fora (tools), não da memória dele.
• A janela é finita. Encher o contexto de coisa irrelevante degrada a resposta tanto quanto faltar informação. Mais sobre isso no Capítulo 05.

Como saber se você entendeu

Você dominou este capítulo se consegue:

• explicar por que o modelo fala sobre CRUD de Pedidos mas não consegue mexer no seu código;
• dizer o que o model routing decide e quando usar opus, sonnet ou haiku;
• citar três coisas que o LLM não faz sozinho e qual camada resolve cada uma.

Fontes

• Andrej Karpathy — nanoGPT, implementação mínima de um GPT treinável (boa intuição para previsão de próximo token): https://github.com/karpathy/nanoGPT
• Vaswani et al., "Attention Is All You Need" (2017) — o paper do Transformer: https://arxiv.org/abs/1706.03762
• Anthropic — modelos Claude (capacidades, tamanhos, IDs): https://docs.anthropic.com/en/docs/about-claude/models
• Anthropic — pesquisa: https://www.anthropic.com/research

Síntese

O LLM é um previsor de próximo token treinado em escala suficiente para raciocinar sobre o mundo. É o cérebro do stack. Mas é um cérebro num pote: sem memória, sem olhos, sem mãos. Tudo que vem a seguir neste e-book é o trabalho de dar corpo a ele.

O primeiro passo é o corpo mais básico: o programa que roda o modelo num loop e o conecta a ferramentas. É o harness.

Próximo: Capítulo 02 — O Harness.

Capítulo 02 — O Harness

O harness é o programa que dá olhos, mãos e um loop ao LLM. Sem ele, o modelo só fala. Com ele, o modelo age.

TL;DR: O harness envolve o LLM com um loop, ferramentas e permissões — é o que transforma um previsor de tokens num agente que age.

No capítulo anterior, o LLM puro respondeu sobre o CRUD de Pedidos de forma genérica e não pôde tocar no seu código. Agora vamos dar um corpo a ele e ver a diferença.

Primeiro, o harness em ação

Mesma pergunta de antes — mas agora dentro do Claude Code, no terminal, dentro do repositório:

> Como eu crio uma API de CRUD de Pedidos (Orders) no meu sistema?

Desta vez a sequência é outra. Em vez de responder de cara, o sistema age:

• Procurando arquivos de pedido…
  grep "Order" → src/orders/OrderService.ts
• Lendo src/orders/OrderService.ts (110 linhas)
• Lendo src/orders/types.ts
• Rodando os testes existentes… 8 passaram

Encontrei. Seu OrderService gerencia pedidos na memória. Para virar um CRUD persistente de verdade, precisamos conectá-lo a um banco de dados (ex. PostgreSQL) e expor os endpoints REST. Antes de eu propor o código, há uma decisão de arquitetura aqui — quer que eu acione o arquiteto de pedidos para desenhar as transições de estado e persistência?

A diferença não está no cérebro — é o mesmo LLM. A diferença é que agora ele:

1. enxergou o seu código (grep, depois Read);
2. agiu no seu ambiente (rodou os testes);
3. decidiu sozinho a sequência de passos (procurar → ler → testar → responder).

Quem deu esses olhos e mãos ao modelo, e quem rodou esse ciclo de passos, foi o harness.

O que é um harness

Um harness é o programa que envolve o LLM e o torna útil: ele monta o contexto, oferece ferramentas, executa as ferramentas que o modelo pede, devolve os resultados ao modelo e repete esse ciclo até a tarefa terminar — tudo sob um modelo de permissões.

O nome vem de "arreio/cabresto": é o equipamento que controla e direciona um cavalo. Aqui, o cavalo é o LLM. O Claude Code é um harness. O Cursor é um harness. Um script TypeScript que chama a API da Anthropic num loop while com tool use também é, em miniatura, um harness.

A frase de bolso: o LLM é o cérebro; o harness é o corpo e o sistema nervoso.

O loop agêntico: o coração do harness

A peça mais importante de um harness é o loop. Em TypeScript/JavaScript moderno:

interface Message {
  role: 'system' | 'user' | 'assistant' | 'tool';
  content: string;
  toolCallId?: string;
}

async function runAgentLoop(
  systemPrompt: string,
  userMessage: string,
  availableTools: Record<string, Function>
): Promise<string> {
  const context: Message[] = [
    { role: 'system', content: systemPrompt },
    { role: 'user', content: userMessage }
  ];

  while (true) {
    // 1. O LLM analisa o contexto e decide o próximo passo
    const response = await llm.complete(context, Object.keys(availableTools));

    if (response.wantsToUseTool) {
      // 2. O harness intercepta e executa a ferramenta de forma síncrona/assíncrona
      const toolResult = await availableTools[response.toolName](response.arguments);
      
      // 3. O harness atualiza o contexto com o pedido e o resultado
      context.push({ role: 'assistant', content: response.text });
      context.push({ role: 'tool', toolCallId: response.toolCallId, content: JSON.stringify(toolResult) });
      
      // 4. Loop continua (pensar -> agir -> observar)
      continue;
    } else {
      // O LLM decidiu que concluiu a tarefa
      return response.text;
    }
  }
}

Releia o exemplo do CRUD de Pedidos com esse loop na cabeça:

1. O modelo recebe o pedido e decide: "preciso achar onde os pedidos são criados ou armazenados" → pede Grep.
2. O harness executa o Grep, devolve o caminho do arquivo OrderService.ts.
3. O modelo decide: "preciso ler esse arquivo" → pede Read.
4. O harness lê, devolve o conteúdo de OrderService.ts.
5. O modelo decide: "vou validar a suite rodando os testes" → pede Bash.
6. O harness roda os testes locais, devolve a saída.
7. O modelo conclui que tem o necessário para a decisão arquitetural e responde — saindo do loop.

Cada volta no while é uma decisão do modelo seguida de uma ação do harness. É essa alternância pensar → agir → observar que diferencia um agente de um chat.

As quatro responsabilidades do harness

graph LR
    subgraph Harness
        T["Ferramentas<br/>(tools)"]
        P["Permissões"]
        C["Gestão de contexto"]
        L["Loop agêntico"]
    end
    LLM["LLM"] <--> L
    L --> T
    L --> C
    T --> P

1. Ferramentas (tools). São as funções que o modelo pode chamar: Read, Write, Edit, Bash, Grep, Glob, busca na web, e outras. Cada ferramenta tem um nome, uma descrição e um schema de argumentos. O modelo não executa nada — ele pede ao harness para executar. (Mais ferramentas, para sistemas externos, chegam via MCP no Capítulo 08.)

2. Permissões. Antes de executar uma ferramenta sensível — editar um arquivo, rodar um comando — o harness aplica uma política: pergunta ao usuário, ou consulta uma allowlist, ou bloqueia. É a fronteira de segurança entre "o modelo quer fazer X" e "X acontece de verdade". Restringir as tools de um agent (Capítulo 03) é uma forma de definir essa fronteira por design.

3. Gestão de contexto. A janela de contexto é finita (Capítulo 01). O harness decide o que entra: quais arquivos, quanto do histórico, resultados de quais ferramentas. Quando a conversa fica longa demais, ele compacta — resume o que passou para liberar espaço. Boa gestão de contexto é o que separa um harness que se perde de um que mantém o fio. É o tema do Capítulo 05.

4. Loop agêntico. O while que vimos. É o que transforma uma resposta única numa sequência autônoma de passos.

Hooks: estendendo o loop de forma determinística

Além das quatro responsabilidades fundamentais, harnesses modernos como o Claude Code trazem suporte a Hooks. Um hook é um script ou comando de terminal que o harness executa de forma automática em resposta a eventos específicos do ciclo de vida agêntico — como antes de rodar uma ferramenta (PreToolUse), após a execução (PostToolUse), ou ao encerrar a sessão (Stop).

Isso abre portas para controles e automações determinísticas fora da rede neural:

• Hooks de som / feedback sonoro: Disparar um áudio no terminal informando se o build ou teste que o agente rodou quebrou. Exemplo de hook disparado após PostToolUse com comando Bash:

  # Se o comando executado pelo agente falhar, toca um som de erro no macOS
  if [ $EXIT_CODE -ne 0 ]; then
    say "Build falhou" || afplay /System/Library/Sounds/Basso.aiff
  fi
  

• Notificação via OS/Terminal: Mandar alertas visuais no desktop para o desenvolvedor saber que o agente concluiu uma sub-tarefa longa enquanto ele estava em outra aba.

  # Notifica o OS usando osascript (macOS)
  osascript -e 'display notification "O agente completou o CRUD de Pedidos!" with title "Claude Code"'
  

Hooks deixam você injetar política e automação sem mudar o modelo. Voltamos a eles no Capítulo 07.

Como isso se conecta ao agent

Esta é a relação mais importante do e-book, então vale a pena ser explícito:

O agent é a configuração. O harness é o motor que roda essa configuração.

Quando você cria o agent-order-architect (Capítulo 03) com tools: Read, Grep, Glob e model: opus, você não está construindo um programa novo. Você está dando ao harness uma configuração: "quando este papel for acionado, monte o contexto com este system prompt, ofereça estas ferramentas, e rode o loop com este modelo".

O mesmo harness roda o agent-order-architect, o agent-order-backend e o assistente padrão. O que muda entre eles é só a configuração — o prompt, as ferramentas, o modelo. Por isso um agent é tão barato de criar: ele reaproveita todo o motor que já existe.

graph TD
    H["Harness (motor único)"]
    A1["agent-order-architect<br/>opus · Read/Grep/Glob"]
    A2["agent-order-backend<br/>sonnet · Read/Write/Edit/Bash"]
    A3["assistente padrão<br/>todas as ferramentas"]
    H --> A1
    H --> A2
    H --> A3

Trade-offs e armadilhas

• O harness define a superfície de risco. Dar Bash sem política de permissão é dar ao modelo um shell. As permissões existem por isso — não as desligue por conveniência.
• Loop sem limite gasta tokens e tempo. Um bom harness tem teto de iterações e sabe parar. Tarefa mal definida vira loop caro.
• Contexto mal gerido degrada tudo. Encher a janela de arquivos irrelevantes piora a resposta. O harness escolher o que o modelo vê é metade do resultado.
• Harness não conserta um cérebro ruim. Se o modelo é fraco para a tarefa, mais ferramentas não salvam. Casar modelo↔tarefa (Capítulo 01) continua valendo.

Como saber se você entendeu

Você dominou este capítulo se consegue:

• descrever o loop pensar → agir → observar com as suas próprias palavras;
• listar as quatro responsabilidades do harness;
• explicar a frase "o agent é a configuração; o harness é o motor".

Fontes

• Yao et al., "ReAct: Synergizing Reasoning and Acting in Language Models" (2022) — o padrão de raciocínio + ação que fundamenta o loop do harness: https://arxiv.org/abs/2210.03629
• Claude Code — visão geral (o harness de referência deste e-book): https://code.claude.com/docs/pt/overview
• Anthropic — "Building effective agents" (o loop de ferramentas, agentes vs. workflows): https://www.anthropic.com/research/building-effective-agents
• Anthropic — uso de ferramentas (tool use) na API: https://docs.anthropic.com/en/docs/build-with-claude/tool-use

Síntese

O harness é o que transforma um previsor de tokens num agente que faz coisas. Ele dá ferramentas, aplica permissões, gerencia o contexto e roda o loop pensar→agir→observar. O Claude Code é exatamente isso: um harness operado pelo terminal.

Mas até aqui temos um harness genérico, que faz um pouco de tudo. O próximo passo é especializá-lo para um trabalho — dar a ele um papel, um modelo e limites. Isso é o agent.

Próximo: Capítulo 03 — O Agent.

Capítulo 03 — O Agent

Um agent é um LLM rodando dentro de um harness, configurado por um arquivo .md para fazer um trabalho específico, bem.

TL;DR: Um agent é um arquivo .md que especializa o LLM+harness para um trabalho — prompt, modelo e ferramentas. É software versionável, não prompt descartável.

Este é o capítulo-âncora. Tudo que vem antes (LLM, harness) existe para chegar aqui; tudo que vem depois (subagent, context, skill, plugin, MCP, CLI) existe para deixar o agent mais capaz. Se você só ler um capítulo, leia este.

Primeiro, o agent em ação

Você está no terminal, no repositório, e digita:

> Preciso criar um sistema robusto de CRUD de Pedidos (Orders). Antes de escrever código,
  quero a arquitetura: transições de estado, concorrência e o que decidir primeiro.

Em vez de o modelo genérico começar a cuspir código, um especialista assume a tarefa. Ele lê o código existente, identifica a modelagem de entidades atual e responde algo como:

[agent-order-architect]

Decisões antes de codar:
1. Concorrência: Atualizações simultâneas de status do Pedido (ex.: transição para `paid`
   e `cancelled` ocorrendo no mesmo milissegundo) podem causar race conditions.
   → Decisão: Usar optimistic locking com uma coluna `version` na tabela de pedidos.
2. Integridade de Estado: Transições ilegais como pular de `draft` direto para `paid` ou
   pagar um pedido já cancelado quebram o fluxo de negócios.
   → Decisão: Implementar uma máquina de estados estrita no OrderService.
3. Auditoria: Alterações críticas no ciclo de vida do pedido devem ser rastreáveis.
   → Decisão: Tabela de `order_events` registrando transição, payload e ator.

Diagrama da máquina de estados proposto: [...]
NÃO escrevi código — esse é trabalho do agent-order-backend.

Repare em três coisas:

1. Ele tem um nome e um papel (agent-order-architect) — não é "a IA", é o arquiteto.
2. Ele tem um escopo — projeta, não implementa. Ele mesmo diz que não escreve código.
3. Ele leu o seu código antes de responder — não inventou o fluxo, descobriu.

Um agent, no Claude Code, é um arquivo Markdown com um cabeçalho YAML (o frontmatter) e um corpo. O frontmatter configura; o corpo é o system prompt — as instruções que o modelo recebe antes de qualquer conversa. Salve isto em .claude/agents/agent-order-architect.md:

---
name: agent-order-architect
description: Projeta a arquitetura técnica do domínio de pedidos (Orders)
  antes da implementação. Use quando há decisão de design, modelagem de
  entidades, definição de máquina de estados ou trade-offs de concorrência.
model: opus            # raciocínio profundo p/ trade-offs
tools: Read, Grep, Glob   # read-only: o arquiteto propõe, não implementa
skills: [improve-codebase-architecture, diagnose]
---

# Order Architect

Você projeta a arquitetura do domínio `order` (pedidos). Seu produto é uma
**decisão**, não código.

## O que você entrega
- Decisões de design numeradas, cada uma com a justificativa e o risco
  que ela mitiga.
- Um diagrama textual (Mermaid) do fluxo ou máquina de estados proposta.
- A lista de riscos abertos e o que precisa ser validado antes de codar.

## Como você trabalha
1. Leia o código atual antes de opinar (Read/Grep/Glob). Nunca presuma
   o fluxo — descubra-o.
2. Prefira padrões consolidados: máquina de estados explícita, optimistic
   locking para concorrência e auditoria por eventos.
3. Exponha trade-offs reais. Se há duas opções, mostre as duas e
   recomende uma com motivo.

## Restrições
- NÃO escreva código de produção. Isso é trabalho do agent-order-backend.
- NÃO decida sozinho o que é regra de negócio — sinalize para o
  agent-order-product-manager.

Cada linha desse arquivo faz um trabalho. Vamos por partes.

O frontmatter, campo a campo

Duas observações honestas sobre o frontmatter:

• Os campos centrais e documentados do Claude Code são name, description, tools e model. O description e o name são obrigatórios; tools e model são opcionais e têm defaults sensatos (herdar todas as ferramentas, herdar o modelo da conversa).
• O campo skills aparece no nosso exemplo como uma forma declarativa de dizer "este agent costuma usar estas skills". A associação agent↔skill é o assunto do Capítulo 06; aqui basta saber que o frontmatter é o lugar onde você expressa as intenções do agent.

O description é a parte que mais importa

Iniciantes acham que o corpo (o system prompt) é o que define o agent. Na prática, o description é o que decide se o agent é acionado. Quando você digita um pedido, o sistema compara sua intenção com os description de todos os agents disponíveis e delega ao que melhor casa.

Um description ruim:

description: Agente de pedidos.

Um description bom:

description: Projeta a arquitetura técnica do domínio de pedidos (Orders)
  antes da implementação. Use quando há decisão de design, modelagem de
  entidades, definição de máquina de estados ou trade-offs de concorrência.

A diferença: o segundo diz quando acionar (gatilhos: "decisão de design", "trade-off"), não só o que o agent é. Escreva description como se estivesse ensinando um colega a saber quando chamar você. Esse é, segundo a documentação do Claude Code, o fator que mais afeta se o agent é usado no momento certo.

O que é um agent, afinal

Agora a definição, depois do exemplo (como prometido):

Um agent é uma instância de um LLM, rodando dentro de um harness, especializada por um system prompt e restringida por uma configuração (modelo, ferramentas, contexto) para executar um tipo de tarefa de forma autônoma.

Decompondo:

• Instância de um LLM: o cérebro é o modelo (Capítulo 01). O agent não substitui o modelo — ele o configura.
• Dentro de um harness: o agent precisa do loop, das ferramentas e do gerenciamento de contexto que o harness fornece (Capítulo 02). Um agent sem harness é só um prompt.
• Especializado por um system prompt: o corpo do .md. É o que transforma "um modelo genérico" in "o arquiteto de pedidos".
• Restringido por configuração: model, tools. Restrição não é limitação acidental — é design. Dar só Read, Grep, Glob ao arquiteto é o que garante que ele não consiga escrever código mesmo que tente.
• De forma autônoma: você descreve o objetivo; o agent decide os passos.

A frase de bolso: um agent é um LLM com um trabalho, ferramentas e limites.

Como o agent funciona por dentro

Quando o agent é acionado, o harness roda um loop (o mesmo do Capítulo 02, agora com a configuração do agent):

sequenceDiagram
    participant U as Você
    participant H as Harness
    participant A as agent-order-architect
    participant LLM as LLM (opus)

    U->>H: "Criar sistema robusto de CRUD de Pedidos — quero a arquitetura"
    H->>A: aciona (match no description)
    A->>LLM: system prompt + pedido
    LLM-->>A: "preciso ver o código atual"
    A->>H: Read(src/orders/OrderService.ts)
    H-->>A: conteúdo do arquivo
    A->>LLM: system prompt + pedido + código
    LLM-->>A: decisões + diagrama + riscos
    A-->>U: resposta final (sem código)

O ponto-chave: o agent não responde de cara. Ele entra num ciclo de pensar → usar ferramenta → observar resultado → pensar de novo até ter o suficiente para responder. As ferramentas que ele pode usar nesse ciclo são exatamente as do campo tools. Por isso restringir tools é restringir o que o agent consegue fazer, não só o que ele deveria fazer.

Como construir um agent, na prática

1. Defina o trabalho em uma frase. "Projeta arquitetura de pedidos, não implementa." Se você não consegue resumir em uma frase, o agent está grande demais — quebre em dois.
2. Escreva o description pensando no gatilho. Quando este agent deve ser chamado? Liste situações concretas.
3. Escolha o modelo pela dificuldade. Trade-offs ambíguos pedem opus; execução de padrão conhecido roda bem em sonnet; passes mecânicos, haiku. (Esse é o assunto de model routing, que revisitamos no Capítulo 09.)
4. Restrinja as ferramentas pelo princípio do menor privilégio. Um arquiteto read-only não deveria ter Write nem Bash. Toda ferramenta a mais é uma forma a mais de errar.
5. Escreva o system prompt como contrato. O que entrega, como trabalha, o que NÃO faz. As três seções do nosso exemplo (## O que você entrega, ## Como você trabalha, ## Restrições) são um molde reutilizável.
6. Teste o gatilho. Faça um pedido vago e veja se o agent certo é acionado. Se não, o problema quase sempre está no description.

Como o agent se conecta a todas as outras camadas

Aqui está a espinha dorsal do e-book. Guarde este mapa — cada item é um capítulo:

• LLM (Cap. 01): é o cérebro que o agent configura. Trocar model: opus por model: haiku muda o agent sem mudar uma linha do prompt.
• Harness (Cap. 02): é o que roda o loop do agent e executa suas ferramentas. O agent é a configuração; o harness é o motor.
• Subagent (Cap. 04): quando um trabalho é grande demais para um agent, ele delega a subagents. O agent-order-architect é, na squad completa, um subagent do agent-order-orchestrator.
• Context (Cap. 05): o que o agent "enxerga" — system prompt, pedido, resultados de ferramentas. Engenheirar esse contexto é o que faz o arquiteto ler o arquivo certo e não os 200 errados.
• Skill (Cap. 06): Conhecimento sob demanda. O skills: [improve-codebase-architecture] do frontmatter diz quais pacotes de know-how o agent carrega quando precisa.
• Plugin (Cap. 07): Empacota o agent (e seus colegas de squad, skills e hooks) para você instalar em outro repositório com um comando.
• MCP (Cap. 08): Dá ao agent ferramentas para o mundo externo — consultar o banco Postgres ou chamar APIs — via um protocolo padrão.
• CLI (Cap. 09): É onde você invoca o agent de verdade: o Claude Code no terminal.

Toda vez que um capítulo seguinte introduzir uma camada, ele vai voltar a este agent e mostrar o que muda nele.

Trade-offs e armadilhas

• Não crie um agent para tudo. Se a tarefa é única e simples, o assistente padrão resolve. Agent é para um papel recorrente com um escopo estável.
• Agents largos demais falham. Um agent-order-tudo que projeta, implementa, testa e faz deploy não tem foco — e o description fica genérico, então ele é acionado na hora errada. Um trabalho por agent.
• tools em excesso é dívida de segurança. Cada ferramenta extra amplia a superfície de erro. Comece restrito; abra quando doer.
• O modelo errado custa caro nos dois sentidos. opus para um passe mecânico é desperdício; haiku para um trade-off arquitetural é risco. Casar modelo↔tarefa é uma decisão de engenharia, não um detalhe.

Como saber se você entendeu

Você dominou este capítulo se consegue:

• escrever um description que diz quando acionar o agent, não só o que ele é;
• justificar a escolha de model e a restrição de tools de um agent;
• explicar como o agent se conecta a cada uma das outras oito camadas.

Fontes

• Anthropic — anthropic-cookbook, exemplos práticos de padrões de agentes e uso de ferramentas: https://github.com/anthropics/anthropic-cookbook
• Claude Code — Subagents (definição, frontmatter, description, tools, model): https://code.claude.com/docs/en/sub-agents
• Claude Code — Visão geral: https://code.claude.com/docs/pt/overview
• Anthropic — "Building effective agents" (quando usar agentes vs. workflows): https://www.anthropic.com/research/building-effective-agents

Síntese

Um agent é um arquivo. Esse arquivo pega o cérebro genérico (LLM), coloca dentro de um corpo com loop (harness), dá a ele um papel (system prompt), uma capacidade (model) e limites (tools). O resultado é um especialista que você pode versionar, revisar em pull request e compartilhar — software, não prompt descartável.

Mas um especialista sozinho não constrói um CRUD de pedidos de alta confiabilidade. Para isso ele precisa de uma equipe. No próximo capítulo, transformamos este agent em um membro de uma squad.

Próximo: Capítulo 04 — O Subagent. Antes dele, se você pulou: Capítulo 01 — O LLM e Capítulo 02 — O Harness.

Capítulo 04 — O Subagent

Um subagent é um agent acionado por outro agent, que roda em seu próprio contexto isolado e devolve só o resultado. É como você divide um problema grande em especialistas.

TL;DR: Subagent é um agent acionado por outro, em contexto isolado — é como você divide um problema grande numa squad sem estourar o contexto do orquestrador.

No capítulo anterior, construímos o agent-order-architect. Ele projeta bem. Mas projetar não é entregar. Quem implementa os endpoints REST? Quem valida as transições de estado concorrentes? Quem instrumenta as métricas de latência do banco? Um especialista sozinho trava nessa pergunta. A resposta é uma squad.

Primeiro, o subagent em ação

Você dá um objetivo amplo ao orquestrador da squad de pedidos:

> Implemente o CRUD de Pedidos de ponta a ponta: do requisito ao deploy monitorado.

Em vez de tentar fazer tudo sozinho (e estourar o próprio contexto), o agent-order-orchestrator delega:

[agent-order-orchestrator]

Decompondo em frentes e acionando a squad:

→ agent-order-product-manager: definir regras e ciclo de vida do pedido
   ← entregou: 5 estados (draft, created, pending, paid, cancelled), regras de expiração
→ agent-order-architect: desenhar esquema de tabelas e concorrência
   ← entregou: schema SQL + optimistic locking + tabela order_events para auditoria
→ agent-order-backend: implementar controller, service e repositório
   ← entregou: 6 arquivos, 15 testes passando
→ agent-order-qa: testar transições ilegais e atualizações concorrentes
   ← entregou: 2 bugs de concorrência detectados e corrigidos
→ agent-order-observer: instrumentar logs de erro e alerta de pedidos presos
   ← entregou: tracing de transição + alerta de pedido pendente > 24h

Integração concluída. CRUD de Pedidos implantado em produção com total segurança.

Cada seta é um subagent sendo acionado, fazendo seu trabalho em separado, e devolvendo um resultado conciso. O orquestrador nunca viu os 6 arquivos do backend nem os logs do observer — só recebeu os resumos. Isso é proposital, e é o ponto técnico mais importante deste capítulo.

O que é um subagent

Um subagent é um agent invocado por outro agent (em vez de diretamente por você), que executa sua tarefa em uma janela de contexto própria e isolada e retorna apenas o resultado final ao agent que o chamou.

Três palavras carregam o peso:

• Invocado por outro agent: a única diferença entre "agent" e "subagent" é quem chama. O agent-order-architect do Capítulo 03 é um agent quando você fala com ele direto; é um subagent quando o orquestrador o aciona. Mesmo arquivo, papel relacional diferente.
• Contexto próprio e isolado: cada subagent começa com a janela de contexto limpa. Ele recebe só a tarefa que o pai delegou, não toda a conversa anterior. Os detalhes do trabalho dele também não voltam para o pai — só a conclusão.
• Retorna o resultado final: o pai recebe um resumo, não o passo a passo. É isso que mantém o contexto do orquestrador enxuto mesmo coordenando nove especialistas.

Por que o contexto isolado é o ponto-chave

Imagine se o orquestrador fizesse tudo numa única conversa: leria os 6 arquivos do backend, os logs do observer, os schemas do banco. Em poucas etapas, a janela de contexto (Capítulo 05) estaria entupida, e a qualidade despencaria — o modelo se perde quando o contexto fica cheio de detalhe irrelevante.

Delegar a subagents resolve isso por construção:

graph TD
    O["agent-order-orchestrator<br/>(contexto: só objetivos + resumos)"]
    PM["product-manager<br/>(contexto próprio)"]
    AR["architect<br/>(contexto próprio)"]
    BE["backend<br/>(contexto próprio: 6 arquivos)"]
    QA["qa<br/>(contexto próprio)"]
    OB["observer<br/>(contexto próprio: logs)"]

    O -->|delega tarefa| PM
    O -->|delega tarefa| AR
    O -->|delega tarefa| BE
    O -->|delega tarefa| QA
    O -->|delega tarefa| OB
    PM -.resumo.-> O
    AR -.resumo.-> O
    BE -.resumo.-> O
    QA -.resumo.-> O
    OB -.resumo.-> O

O backend pode mergulhar em 6 arquivos sem poluir o contexto de ninguém. O orquestrador mantém a visão de cima. Esse padrão — um coordenador que distribui para trabalhadores especializados — é o que a Anthropic chama de orchestrator-workers em "Building effective agents". Subagents são a implementação concreta dele.

Estudo de caso: a squad order completa

Aqui está a squad real, com todos os campos preenchidos e justificados. O domínio é domains/order; o agent-order-orchestrator coordena oito subagents, cada um com um papel distinto, um modelo casado à dificuldade da tarefa e skills reais do repositório.

Repare no model routing da squad: três opus onde há decisão e ambiguidade (PM, architect — e o orquestrador, abaixo), quatro sonnet onde há execução de um padrão definido, e dois haiku para trabalho mecânico de alto volume. Isso não é economia mesquinha — é casar a dificuldade de cada papel com a capacidade do cérebro, exatamente como discutimos no Capítulo 01.

O orquestrador, por completo

Salve em .claude/agents/agent-order-orchestrator.md:

---
name: agent-order-orchestrator
description: Coordena a squad do domínio order de ponta a ponta — do
  requisito ao deploy monitorado. Use para tarefas amplas de pedidos
  que cruzam várias frentes (produto, arquitetura, backend, frontend,
  QA, observabilidade), como lançar um novo fluxo ou transições de estado.
model: opus            # decompõe objetivos ambíguos e integra resultados
tools: Agent, Read, Grep, Glob   # delega (Agent) e lê para integrar; não codifica
skills: [to-issues]    # quebra o objetivo em frentes rastreáveis
---

# Order Orchestrator

Você coordena a squad de pedidos. Você NÃO implementa: você decompõe,
delega ao subagent certo e integra os resultados.

## Como você trabalha
1. Quebre o objetivo em frentes (produto → arquitetura → implementação →
   QA → observabilidade) usando a skill to-issues.
2. Acione cada subagent com uma tarefa fechada e o contexto mínimo que
   ele precisa — nunca despeje a conversa inteira.
3. Respeite as dependências: requisitos antes de arquitetura; arquitetura
   antes de implementação; implementação antes de QA.
4. Integre os resumos devolvidos e reporte o estado consolidado.

## Subagents disponíveis
- agent-order-product-manager — requisitos e regras de negócio
- agent-order-architect — design técnico e concorrência (read-only)
- agent-order-backend — implementação de endpoints e banco
- agent-order-frontend — listagens e formulários web
- agent-order-designer — fluxo visual e estados da tela
- agent-order-qa — testes de carga e concorrência
- agent-order-observer — alertas e métricas
- agent-order-analytics — métricas de funil e conversão

## Restrições
- NÃO escreva código de produção.
- NÃO pule a etapa de QA antes de declarar "pronto".
- Delegue ao subagent de menor privilégio capaz de fazer a tarefa.

Um subagent executor, por completo

Contraste com o orquestrador: o backend é read-write, roda em sonnet, e tem um escopo de execução. Salve em .claude/agents/agent-order-backend.md:

---
name: agent-order-backend
description: Implementa o lado servidor do CRUD de Pedidos — endpoints REST,
  validação de máquina de estados e persistência com optimistic locking.
  Use quando há um design aprovado e é hora de codar o backend de orders.
model: sonnet          # execução de padrão definido, com volume
tools: Read, Write, Edit, Bash
skills: [tdd, error-fix-loop]
---

# Order Backend

Você implementa o backend de pedidos a partir de um design já
decidido pelo agent-order-architect.

## Como você trabalha
1. Comece pelos testes (skill tdd): escreva o teste de comportamento
   antes do código que o satisfaz.
2. Garanta concorrência segura: utilize optimistic locking com verificação
   de versão a cada alteração de status do pedido.
3. Modele as transições como máquina de estados explícita; nada de alterar status sem validar o estado anterior.
4. Ao quebrar, use a skill error-fix-loop até os testes passarem.

## Restrições
- NÃO decida arquitetura — se o design estiver ambíguo, devolva a dúvida
  ao orquestrador para acionar o architect.
- NÃO faça deploy. Sua entrega é código testado e verde.

Os outros seis subagents seguem o mesmo molde — name, description com gatilho claro, model casado à dificuldade, tools no menor privilégio, skills reais, e um corpo com "como trabalha" + "restrições". Nenhum campo fica vazio; cada papel é distinto e não se sobrepõe ao vizinho.

Como isso se conecta ao agent

A ligação é direta, e fecha o arco do capítulo anterior:

Um subagent não é uma coisa nova. É o agent do Capítulo 03, agora acionado por outro agent em vez de por você.

O agent-order-architect que construímos campo a campo no Capítulo 03 aparece aqui sem nenhuma mudança no arquivo — apenas com um novo chamador. O que muda é o relacionamento: ele virou um trabalhador na squad do orquestrador. Essa é a beleza do modelo: você projeta agents como unidades autônomas e os compõe em hierarquias conforme o problema cresce, sem reescrever nada.

E como cada subagent roda em contexto isolado, eles dependem diretamente da próxima camada — a gestão de contexto. O que o pai passa ao filho, e o que o filho devolve ao pai, é uma decisão de context engineering.

Trade-offs e armadilhas

• Delegar tem custo. Cada subagent é uma nova rodada de modelo, com seu próprio contexto montado do zero. Para uma tarefa pequena, delegar é mais lento e mais caro que fazer direto. Use squad para problemas que realmente têm frentes distintas.
• Contexto isolado corta os dois lados. O subagent não vê o que o pai sabe, a menos que o pai passe explicitamente. Esquecer de passar o contexto necessário é a causa nº 1 de subagent que "faz a coisa errada com competência".
• Fan-out paralelo multiplica tokens. Acionar oito subagents de uma vez é poderoso e caro. Paralelize quando as frentes são independentes; serialize quando há dependência (requisito → arquitetura → código).
• Orquestrador que implementa vira gargalo. Se o coordenador começa a codar, ele perde a visão de cima e entope o próprio contexto. Mantenha o orquestrador como coordenador puro (note o tools: Agent, Read, Grep, Glob — sem Write).
• Hierarquia profunda demais confunde. Subagent chamando subagent chamando subagent fica difícil de depurar. Uma camada de orquestração costuma bastar.

Como saber se você entendeu

Você dominou este capítulo se consegue:

• explicar por que o contexto isolado mantém o orquestrador enxuto;
• justificar o model routing da squad (quem é opus, sonnet, haiku e por quê);
• decidir quando vale delegar a subagents e quando não compensa.

Fontes

• Anthropic — courses, materiais oficiais sobre construir aplicações com Claude (inclui padrões de orquestração): https://github.com/anthropics/courses
• Anthropic — "Building effective agents" (padrão orchestrator-workers, quando dividir o trabalho): https://www.anthropic.com/research/building-effective-agents
• Claude Code — Subagents (definição, contexto isolado, invocação): https://code.claude.com/docs/en/sub-agents
• Claude Code — visão geral: https://code.claude.com/docs/pt/overview

Síntese

Subagent é como você escala um agent de "especialista solo" para "squad". A mecânica é simples — um agent aciona outro — mas a consequência arquitetural é grande: cada subagent roda em contexto isolado, mantém o pai enxuto e divide um problema grande em pedaços que cabem na cabeça de um modelo. A squad order, com seu orquestrador e oito especialistas, é esse padrão levado a sério.

E tudo isso gira em torno de uma pergunta: o que cada agent enxerga? A resposta é a próxima camada.

Próximo: Capítulo 05 — O Context.

Capítulo 05 — O Context

Context é tudo que o modelo enxerga em uma única chamada. É um recurso finito. Engenheirar o que entra nele é metade do resultado.

TL;DR: Context é a memória de trabalho finita do modelo; curar o que entra — recuperar, isolar, compactar, persistir — é metade do resultado.

Nos capítulos anteriores, o agent-order-architect "leu o seu código" antes de opinar, e cada subagent rodou em "contexto isolado". Agora abrimos essa caixa: o que exatamente o modelo vê, por que isso é limitado, e como você controla.

Primeiro, o context em ação

Quando o agent-order-architect é acionado, o modelo não recebe "o seu projeto". Ele recebe uma montagem específica de texto — a janela de contexto daquela chamada:

┌─ Janela de contexto (uma chamada ao LLM) ────────────────────┐
│ [system prompt]                                              │
│   "Você projeta a arquitetura do domínio order..."           │
│   (o corpo do .md do agent — sempre presente)                │
│                                                              │
│ [memória do projeto]                                         │
│   CLAUDE.md: "Pedidos usam optimistic locking e Postgres."   │
│                                                              │
│ [mensagem do usuário]                                        │
│   "Criar sistema robusto de CRUD de Pedidos — arquitetura"   │
│                                                              │
│ [resultado de ferramenta]                                    │
│   Read(src/orders/OrderService.ts) → 110 linhas              │
│                                                              │
│ [resultado de ferramenta]                                    │
│   Grep("version") → version: number;                         │
└──────────────────────────────────────────────────────────────┘
                         ↓
              o modelo responde com base
              SOMENTE no que está aí dentro

Duas conclusões saltam:

1. Se algo não está na janela, para o modelo não existe. O Grep("version") encontrou a propriedade version — então o modelo conclui, corretamente, que há controle de versão ativo. A presença ou ausência são informações chave.
2. A janela tem um tamanho máximo. Não cabe o repositório inteiro. Alguém precisa escolher quais 110 linhas entram. Esse alguém é o harness, guiado pelo que o agent pede.

O que é o context

O context (ou janela de contexto) é o conjunto total de tokens que o LLM recebe em uma chamada: o system prompt, a memória carregada, o histórico da conversa, os resultados de ferramentas e quaisquer arquivos recuperados. É a única coisa sobre a qual o modelo raciocina — e tem um limite rígido de tamanho.

Pense no context como a memória de trabalho (a RAM) do modelo, não o disco. O modelo não "lembra" do seu projeto entre chamadas; a cada chamada, o que importa precisa estar carregado na janela. Quando a chamada termina, some.

O que vive na janela

A soma de tudo isso precisa caber no limite da janela. Estourou, algo é cortado ou compactado.

Context engineering: o trabalho de curar a janela

Como a janela é finita e o modelo raciocina só sobre ela, decidir o que entra é uma disciplina de engenharia. A Anthropic chama isso de context engineering — a evolução do "prompt engineering" quando o que importa não é só a frase que você escreve, mas todo o estado que o modelo recebe.

O princípio central: sinal sobre ruído. Tanto faltar informação quanto sobrar lixo degradam a resposta. Encher a janela com 50 arquivos "por garantia" não ajuda — piora, porque o modelo se distrai e perde o que importa no meio (o fenômeno lost in the middle, em que informação no meio de um contexto longo é menos aproveitada que no início ou no fim).

As técnicas que você já viu, agora nomeadas:

• Recuperação seletiva. Trazer só os arquivos relevantes (via Grep/Glob antes de Read), não o repositório inteiro. O architect achou OrderService.ts com um grep, não lendo tudo.
• Isolamento por subagent (Capítulo 04). Delegar mantém o contexto do orquestrador limpo: o backend mergulha em 6 arquivos no seu contexto; o pai só recebe o resumo.
• Compactação. Quando a conversa fica longa, o harness resume o histórico antigo para liberar espaço, preservando as decisões e descartando o ruído. É como o agente "anota o que importa e esquece o resto".
• Memória persistente. O que precisa sobreviver entre sessões não vive na conversa — vive em arquivos de memória. No Claude Code, o CLAUDE.md (ou AGENTS.md) carrega convenções e fatos do projeto em toda sessão, e há memória de longo prazo em arquivos dedicados. Foi assim que "locking, Postgres" apareceu na janela sem você redigitar.
• Hooks que injetam contexto. Eventos do harness podem inserir informação na janela automaticamente (por exemplo, lembrar uma regra antes de uma ferramenta rodar). Voltamos a hooks no Capítulo 07.

Como isso se conecta ao agent

A relação é dupla, e define a qualidade do agent:

O system prompt do agent é a parte permanente do contexto; tudo o mais é montado em volta dele a cada chamada.

1. O .md do agent ocupa contexto sempre. Por isso um system prompt enxuto e preciso vale mais que um prolixo — cada token de instrução é um token a menos para o trabalho. O contrato em três seções (o que entrega / como trabalha / restrições) do Capítulo 03 é curto de propósito.
2. As tools do agent moldam o que entra depois. Dar Grep, Glob ao architect é o que permite a ele encontrar o arquivo certo antes de lê-lo — recuperação seletiva por design. Um agent sem ferramentas de busca tende a pedir arquivos errados e a entupir o contexto.
3. model define o tamanho da janela disponível. Modelos diferentes têm janelas diferentes; escolher o modelo (Capítulo 01) é também escolher quanto contexto cabe.

Em uma frase: o agent é, em boa parte, uma decisão de context engineering congelada em um arquivo. O que he instrui, o que ele pode buscar e qual cérebro ele usa determinam o que cabe na janela quando ele trabalha.

Trade-offs e armadilhas

• Mais contexto não é melhor contexto. Passar tudo "por segurança" dilui o sinal e custa mais tokens. Curar é melhor que despejar.
• Contexto é dinheiro e latência. Cada token na janela é cobrado e processado. Janelas enormes são lentas e caras — use o espaço com intenção.
• O que não entra, não existe. Bugs de agente frequentemente são bugs de contexto: a informação certa nunca chegou à janela. Antes de culpar o modelo, pergunte "ele viu o que precisava ver?".
• Compactação perde nuance. Resumir libera espaço mas pode descartar um detalhe que importava. Decisões críticas merecem virar memória persistente, não ficar à mercê da compactação.
• Lost in the middle. Em contextos longos, ponha o mais importante no começo ou no fim, não enterrado no meio.

Como saber se você entendeu

Você dominou este capítulo se consegue:

• listar o que vive na janela de contexto;
• explicar o fenômeno lost in the middle e como mitigá-lo;
• justificar por que "o que não entra no contexto não existe para o modelo".

Fontes

• Liu et al., "Lost in the Middle: How Language Models Use Long Contexts" (2023) — o estudo por trás do fenômeno citado: https://arxiv.org/abs/2307.03172
• Anthropic — "Effective context engineering for AI agents": https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents
• Anthropic — engenharia de prompt (boas práticas que valem para o contexto): https://docs.anthropic.com/en/docs/build-with-claude/prompt-engineering/overview
• Claude Code — memória (CLAUDE.md, memória de projeto e de usuário): https://code.claude.com/docs/en/memory

Síntese

Context é a memória de trabalho do modelo: finita, montada a cada chamada, e a única coisa sobre a qual ele raciocina. Engenheirar o que entra — recuperar o relevante, isolar por subagent, compactar o histórico, persistir o essencial em memória — é o que separa um agente que acerta de um que alucina por falta de informação. O agent, no fundo, é uma curadoria de contexto salva em disco.

Mas há um tipo de conhecimento que você não quer recarregar a cada chamada nem deixar morrer na compactação: o know-how reutilizável. Para isso existe uma camada própria.

Próximo: Capítulo 06 — A Skill.

Capítulo 06 — A Skill

Uma skill é conhecimento empacotado, carregado sob demanda. Ela estende um agent sem inchar o contexto dele — só entra na janela quando é relevante.

TL;DR: Skill é conhecimento empacotado, carregado sob demanda por progressive disclosure — estende o agent sem inchar o system prompt.

No capítulo anterior vimos que o contexto é finito e que o system prompt do agent ocupa espaço o tempo todo. Surge um problema: e o conhecimento especializado que o agent só precisa às vezes? Colocar tudo no prompt incha a janela em toda chamada. Não colocar nada deixa o agent ignorante. A skill resolve esse dilema.

Primeiro, a skill em ação

O agent-order-architect está desenhando o fluxo do CRUD de Pedidos (Orders) e chega no ponto crítico: concorrência e transições inválidas. Isso exige conhecimento específico — optimistic locking, controle de versão (version) e modelagem rígida de máquina de estados. Esse know-how não está no system prompt dele (que é curto). Ele está numa skill, que o agente carrega no momento certo:

[agent-order-architect]

A tarefa envolve concorrência e integridade de transição de status.
→ Carregando skill: improve-codebase-architecture

  (a skill traz para o contexto: padrões de concorrência com optimistic locking,
   regras estritas de transições de máquina de estados e logs de auditoria)

Com esse material, a decisão fica:
- Concorrência = optimistic locking via verificação incremental do campo `version`.
- Transições válidas = draft -> created -> pending -> paid | cancelled.
- Auditoria = gravar transição na tabela order_events no mesmo transaction block.

Antes dessa tarefa, o conhecimento de padrões de concorrência e integridade não ocupava nenhum espaço no contexto do agente. Ele entrou só quando a tarefa pediu, e poderia sair depois. Esse carregamento sob demanda é a essência da skill.

O que é uma skill

Uma skill é uma capacidade empacotada — uma pasta com um arquivo SKILL.md (instruções + metadados) e, opcionalmente, recursos como scripts e documentos de referência — que o agente carrega sob demanda, quando a tarefa atual casa com a descrição da skill.

A anatomia mínima, no Claude Code:

.claude/skills/improve-codebase-architecture/
├── SKILL.md            # frontmatter (name, description) + instruções
├── reference.md        # material aprofundado (carregado só se preciso)
└── scripts/
    └── analyze.ts      # código que a skill pode rodar (ex.: TypeScript CLI)

E o SKILL.md em si, no mesmo formato dos que já existem neste repositório:

---
name: improve-codebase-architecture
description: Encontra oportunidades de aprofundar a arquitetura de um
  código. Use ao melhorar arquitetura, achar refatorações, consolidar
  módulos acoplados ou tornar o código mais testável. Inclui padrões
  de concorrência, máquina de estados e auditoria de eventos.
---

# improve-codebase-architecture

## Padrões de Concorrência
- Controle concorrente com optimistic locking via versão (`version` check).

## Máquina de Estados
- Modele transições válidas de forma explícita; barre transições proibidas (ex. de cancelado para pago).

## Quando NÃO aplicar
- ...

Note: o formato é exatamente o que você já viu nas skills do repo — frontmatter com name e description, e um corpo em Markdown. A skill é, literalmente, conhecimento escrito como documento, com metadados que dizem quando usá-lo.

Progressive disclosure: o truque que torna skills baratas

Aqui está o mecanismo que faz skills funcionarem sem entupir o contexto — progressive disclosure (revelação progressiva), em três níveis:

graph TD
    N1["Nível 1: só o description<br/>(sempre no contexto, ~1 linha)"]
    N2["Nível 2: o SKILL.md inteiro<br/>(carregado quando a tarefa casa)"]
    N3["Nível 3: reference.md, scripts<br/>(carregados só se realmente precisar)"]
    N1 -->|tarefa casa com o gatilho| N2
    N2 -->|precisa de detalhe/execução| N3

• Nível 1 — sempre presente, custo mínimo. Só a description de cada skill fica no contexto o tempo todo. É como um índice: dezenas de skills custam pouquíssimos tokens, porque só os "títulos" estão carregados.
• Nível 2 — sob demanda. Quando a tarefa atual casa com a description de uma skill, o SKILL.md completo entra na janela. Foi o que aconteceu quando o architect chegou em "idempotência".
• Nível 3 — só se necessário. Arquivos de referência e scripts dentro da pasta só são lidos se a tarefa exigir aquele detalhe. O agente carrega o reference.md apenas se o resumo do SKILL.md não bastar.

É o mesmo princípio do Capítulo 05 (sinal sobre ruído) aplicado ao conhecimento: você pode ter centenas de skills disponíveis, mas só paga o contexto das que de fato usa, no momento em que usa. Por isso a description da skill é tão crítica quanto a do agent — é ela que decide se a skill é "descoberta" na hora certa.

Skill, agent e subagent: quem é o quê

Esses três se confundem. A distinção:

A frase de bolso: um agent é quem faz; uma skill é o que ele sabe. Uma mesma skill (tdd, por exemplo) pode ser usada pelo agent-order-backend e pelo agent-order-qa — o conhecimento é compartilhado, os trabalhadores são distintos.

Skills vs Commands (Slash Commands)

Com a evolução das ferramentas CLI como o Claude Code, surge outra distinção vital: as skills vs. os commands (slash commands).

• Skills: São carregadas pelo harness de forma semântica e implícita. O agente lê o histórico de conversa, percebe a necessidade ("preciso de concorrência") e puxa o SKILL.md correspondente. É um fluxo transparente e orientado à cognição.
• Commands (Slash Commands): São chamados imperativos e explícitos disparados por você no terminal (ex.: /goal, /schedule, /grill-me). Eles iniciam fluxos de controle estruturados ou scripts determinísticos, sem depender do julgamento do modelo para ativação.

A frase de bolso: Skills estendem a cognição do agente de forma implícita; Commands estendem a capacidade de operação da cabine (CLI) de forma explícita.

Skills Auto-Melhoráveis: O Próximo Nível

Uma categoria emergente do ecossistema são as Skills Auto-Melhoráveis (self-improving skills). Um exemplo real do repositório é o harness de feedback-loop (ex.: skill-recursiva-feedback-loop-harness). Essas skills não contêm apenas instruções estáticas; elas contêm loops estruturados de auto-correção que instruem o agente a entrar em ciclos recursivos de:

1. Propor uma correção de código.
2. Rodar a suite de verificação/testes via tool (Bash).
3. Se falhar, consumir o log de erro, alimentar a própria memória de trabalho e ajustar recursivamente o código sem pedir intervenção humana.

Isso automatiza o fluxo de "Error Fix Loop" (EFL), minimizando a latência de desenvolvimento.

Recomendação CRÍTICA: Evite a Explosão de Tokens

[!IMPORTANT] O desenvolvedor deve testar o uso sem skills primeiro para evitar a explosão de tokens.

Embora skills sejam úteis, toda skill ativa consome o limite da janela de contexto (RAM) com tokens adicionais. Para tarefas triviais ou mecânicas, confie na inteligência bruta do modelo e nas diretrizes simples do CLAUDE.md. Ative ou crie skills apenas quando houver necessidade real de know-how denso e reutilizável.

Como isso se conecta ao agent

Lembra do frontmatter do Capítulo 03?

skills: [improve-codebase-architecture, diagnose]

Agora essa linha tem significado completo:

A skill é como você estende o que um agent sabe fazer sem inchar o system prompt dele.

1. O agent declara afinidade com skills. O campo skills diz quais pacotes de conhecimento aquele papel costuma precisar. É uma dica de quais skills são relevantes para o trabalho dele.
2. O conhecimento fica fora do prompt. Em vez de despejar "como projetar concorrência" no system prompt do architect (custando contexto em toda chamada), isso vive na skill e entra só quando a tarefa pede. O prompt do agent continua curto; a competência, sob demanda.
3. Skills são compartilhadas entre agents. A squad inteira do Capítulo 04 referencia skills reais (tdd, frontend-design, ui-ux-pro-max…). Cada subagent puxa o conhecimento de que precisa, sem duplicar nada.

Skill está para conhecimento como subagent está para trabalho: as duas camadas existem para manter cada agent focado e enxuto, delegando o que não precisa estar sempre presente.

Trade-offs e armadilhas

• A description é tudo. Se ela não descreve bem quando usar a skill, a skill nunca é carregada — vira código morto. Escreva o gatilho com situações concretas, como no description do agent.
• Skill não é agent. Não tente colocar "comportamento autônomo" numa skill. Skill é material que um agent consome; quem age é o agent.
• Excesso de skills polui o nível 1. Cada skill custa sua description no contexto permanente. Centenas de skills mal descritas viram ruído de índice. Mantenha o catálogo curado.
• Conhecimento desatualizado é pior que ausente. Uma skill com um padrão obsoleto faz o agent errar com confiança. Skills precisam de manutenção como qualquer documentação.

Como saber se você entendeu

Você dominou este capítulo se consegue:

• explicar os três níveis do progressive disclosure;
• diferenciar skill, command, agent e subagent;
• justificar por que testar sem skills primeiro é uma prática recomendada de economia de tokens.

Fontes

• Anthropic — courses, exemplos oficiais de capacidades e padrões com Claude: https://github.com/anthropics/courses
• Claude Code — Skills (estrutura, SKILL.md, progressive disclosure): https://code.claude.com/docs/en/skills
• Anthropic — "Equipping agents for the real world with Agent Skills": https://www.anthropic.com/news/agent-skills
• Claude Code — visão geral: https://code.claude.com/docs/pt/overview

Síntese

Skill é conhecimento como documento, carregado sob demanda por progressive disclosure: só a descrição fica sempre no contexto; o conteúdo entra quando a tarefa casa. Isso permite que um agent enxuto tenha acesso a muita competência sem pagar o contexto dela o tempo todo. O skills: [...] do agent é a ponte entre o trabalhador e o que ele sabe.

Já temos agents, subagents, contexto e skills. Mas como você empacota tudo isso — uma squad inteira com suas skills, hooks e conexões — para instalar em outro repositório com um comando? Essa é a próxima camada.

Próximo: Capítulo 07 — O Plugin.

Capítulo 07 — O Plugin

Um plugin empacota agents, skills, comandos, hooks e configuração de MCP em uma unidade instalável. É como você distribui uma squad inteira entre times com um comando.

TL;DR: Plugin empacota agents, skills, comandos, hooks e MCP numa unidade versionada e instalável — é a unidade de entrega do que o agent precisa para funcionar em outro lugar.

Você construiu a squad order: nove agents, suas skills, suas convenções. Funciona no seu repositório. Agora o time de outro produto quer a mesma coisa. Como você entrega? Copiando dezenas de arquivos à mão? Há uma camada para isso.

Primeiro, o plugin em ação

Sem plugin, "compartilhar a squad" significa copiar .claude/agents/*.md (nove arquivos), .claude/skills/* (as skills referenciadas), os hooks, a configuração de MCP — e torcer para não esquecer nada nem versão. Com plugin, é um comando:

> /plugin marketplace add minhaempresa/order-squad
> /plugin install order-squad

Instalado order-squad v1.2.0:
  • 9 agents (orchestrator + 8 subagents)
  • 4 skills (concorrência, auditoria, ...)
  • 2 hooks (valida concorrência antes de commit; bloqueia segredo em log)
  • 1 servidor MCP (database inspector)
  • 1 comando: /order-new-field

Em uma linha, o outro time ganhou a squad completa, versionada, com tudo que ela precisa para funcionar. Atualizou? /plugin update order-squad e todos recebem a v1.3.0. Isso é distribuição de verdade, não copia-e-cola.

O que é um plugin

Um plugin é um pacote distribuível que agrupa um ou mais componentes do Claude Code — agents, skills, comandos (slash commands), hooks e configuração de servidores MCP — sob um manifesto versionado, instalável a partir de um marketplace.

O plugin não é uma camada nova de capacidade. É uma camada de empacotamento e distribuição das camadas que você já conhece. Ele responde à pergunta "como eu levo isto para outro lugar de forma confiável?".

Anatomia de um plugin

order-squad/
├── .claude-plugin/
│   └── plugin.json          # manifesto: nome, versão, descrição, autor
├── agents/                  # os 9 agents da squad
│   ├── agent-order-orchestrator.md
│   ├── agent-order-architect.md
│   └── ...
├── skills/                  # skills que a squad usa
│   └── improve-codebase-architecture/SKILL.md
├── commands/                # slash commands
│   └── order-new-field.md
├── hooks/                   # automações por evento
│   └── hooks.json
└── .mcp.json                # servidores MCP que a squad conecta (Cap. 08)

E o manifesto, plugin.json:

{
  "name": "order-squad",
  "version": "1.2.0",
  "description": "Squad completa do domínio order: orquestrador, 8 subagents, skills de concorrência e máquina de estados.",
  "author": "minhaempresa"
}

O marketplace é só um repositório (git, por exemplo) com um catálogo desses plugins. /plugin marketplace add <repo> registra a fonte; /plugin install <nome> instala dali. É o mesmo modelo mental de um gerenciador de pacotes — npm/cargo para extensões do seu agente.

Hooks: a peça que o plugin frequentemente carrega

Mencionamos hooks de passagem nos capítulos 02 e 05. Aqui eles ganham forma, porque plugins são o jeito comum de distribuí-los.

Um hook é um comando de shell que o harness dispara automaticamente em um evento do ciclo de vida — antes de uma ferramenta rodar (PreToolUse), depois (PostToolUse), quando a sessão tenta encerrar (Stop), entre outros.

Exemplo concreto, no hooks.json do plugin:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          { "type": "command", "command": "scripts/bloqueia-segredo-em-log.sh" }
        ]
      }
    ]
  }
}

Esse hook roda antes de qualquer Bash e pode barrar um comando que vaze segredo em log. O ponto: hooks impõem política deterministicamente, fora do modelo. O LLM pode "querer" rodar algo perigoso; o hook decide se acontece — exatamente a fronteira de permissões do Capítulo 02, agora programável e distribuível dentro do plugin.

Como isso se conecta ao agent

A relação fecha a pergunta de distribuição:

O agent é o arquivo. O plugin é o formato de distribuição que leva esse arquivo — e tudo de que ele depende — para outro lugar, versionado.

1. O plugin empacota agents. A squad order inteira (Capítulo 04) cabe num plugin. Quem instala recebe o orquestrador e os oito subagents prontos.
2. E empacota o que os agents precisam. Um agent sozinho não basta: ele referencia skills (Capítulo 06), conecta servidores MCP (Capítulo 08) e depende de hooks de política. O plugin junta tudo isso, então o agent funciona igual no destino.
3. Versiona o conjunto. agent-order-architect v1.2.0 vem com as skills e a configuração de MCP daquela versão. Atualizar o plugin atualiza o conjunto coerente, não peças soltas que podem divergir.

Em uma frase: se o agent é a unidade de trabalho, o plugin é a unidade de entrega.

Trade-offs e armadilhas

• Instalar plugin é confiar. Um plugin pode trazer hooks (comandos de shell) e servidores MCP (acesso a sistemas). Instalar um plugin de terceiro é rodar o código dele na sua máquina. Trate marketplaces como você trata dependências: audite a fonte.
• Versão acopla componentes. A vantagem (conjunto coerente) é também o risco: um bug numa skill do plugin afeta todos os agents que a usam. Versione com cuidado e teste antes de subir.
• Marketplace exige curadoria. Um catálogo cheio de plugins redundantes ou mal descritos vira ruído. Mantenha o seu enxuto e bem documentado.
• Nem tudo precisa ser plugin. Para um agent usado só no seu repo, o arquivo em .claude/agents/ basta. Plugin é para o que você distribui.

Como saber se você entendeu

Você dominou este capítulo se consegue:

• listar o que um plugin pode empacotar;
• explicar o papel de um hook PreToolUse na fronteira de permissões;
• justificar por que instalar um plugin de terceiros é uma decisão de confiança.

Fontes

• Anthropic — anthropic-cookbook, exemplos de extensão e automação com Claude: https://github.com/anthropics/anthropics-cookbook
• Claude Code — Plugins (estrutura, plugin.json, instalação): https://code.claude.com/docs/en/plugins
• Claude Code — Plugin marketplaces (publicar e instalar): https://code.claude.com/docs/en/plugin-marketplaces
• Claude Code — Hooks (eventos, PreToolUse/PostToolUse/Stop): https://code.claude.com/docs/en/hooks

Síntese

Plugin é a camada de empacotamento: ele pega agents, skills, comandos, hooks e configuração de MCP e os transforma em uma unidade versionada e instalável, distribuída por um marketplace. É o que faz a sua squad order deixar de ser "um monte de arquivos no meu repo" e virar "um pacote que qualquer time instala em um comando".

Sobrou uma dependência que o plugin empacota mas ainda não explicamos: como o agent fala com o mundo externo — o Postgres, o banco de dados de produção de verdade. Esse é o protocolo da próxima camada.

Próximo: Capítulo 08 — O MCP.

Capítulo 08 — O MCP

MCP (Model Context Protocol) é o padrão aberto que conecta o agente ao mundo externo — o banco de dados Postgres, APIs externas e sistemas legados — por uma interface única, em vez de uma integração ad hoc para cada sistema.

TL;DR: MCP é o padrão aberto que dá ao agente uma porta única para sistemas externos — um servidor embrulha o Postgres ou APIs externas e expõe ferramentas ao loop do agente.

Até aqui, as ferramentas do agente agiam na sua máquina: Read, Edit, Bash, Grep. Mas o agent-order-backend precisa saber se as tabelas do banco de dados de verdade estão com o schema correto em produção, e o agent-order-analytics precisa consultar dados consolidados de pedidos. Isso é fora da máquina local. Como o agente alcança esses sistemas? Com MCP.

Primeiro, o MCP em ação

O agent-order-architect quer validar uma suposição: o schema da tabela de pedidos no banco de dados local ou de staging já suporta optimistic locking? Em vez de você abrir um cliente SQL e rodar queries, o agente consulta direto, por uma ferramenta MCP:

[agent-order-architect]

Verificando o schema da tabela de pedidos no banco de dados…
→ mcp__postgres__describe_table(table_name: "orders")
  ← columns: [
      { name: "id", type: "uuid" },
      { name: "status", type: "varchar" },
      { name: "version", type: "integer" }
    ]

Confirmado: a tabela possui a coluna "version" necessária para a implementação do optimistic locking no service do backend.

A chamada mcp__postgres__describe_table() não é um arquivo local nem um comando de shell direto. É uma ferramenta exposta por um servidor MCP que embrulha a conexão ao banco Postgres. Para o agente, ela aparece como mais uma ferramenta no loop do Capítulo 02 — ele pede, o harness executa, o resultado volta para a janela de contexto. A diferença é que, por baixo, isso falou com o banco de dados por um protocolo padronizado.

O que é o MCP

O MCP (Model Context Protocol) é um padrão aberto, publicado pela Anthropic em novembro de 2024, para conectar aplicações de LLM a fontes de dados e ferramentas externas. Ele define como um cliente (o harness) conversa com servidores que expõem ferramentas, dados e prompts de forma uniforme.

A analogia que a própria Anthropic usa: MCP é como uma porta USB-C para aplicações de IA. Antes do USB-C, cada aparelho tinha seu conector; integrar N ferramentas a M aplicações dava N×M integrações sob medida. Com um padrão, cada lado implementa a interface uma vez e tudo conversa. MCP faz isso para conectar agentes a sistemas: o Postgres expõe um servidor MCP uma vez, e qualquer harness compatível passa a usá-lo — sem código de integração específico.

Como funciona: cliente e servidor

graph LR
    subgraph "Seu ambiente"
        H["Harness<br/>(cliente MCP)"]
        A["agent-order-backend"]
    end
    subgraph "Servidores MCP"
        S1["Servidor Postgres<br/>(embrulha o banco)"]
        S2["Servidor GitHub<br/>(embrulha a API)"]
    end
    A --> H
    H <-->|protocolo MCP| S1
    H <-->|protocolo MCP| S2
    S1 --> DB["Banco Postgres (orders)"]
    S2 --> API["API GitHub (PRs)"]

• Cliente MCP: o harness (Claude Code). Ele descobre quais ferramentas cada servidor oferece e as apresenta ao modelo.
• Servidor MCP: um processo que expõe capacidades por três tipos de primitiva:
  • Tools — ações que o modelo pode chamar (ex.: run_query, describe_table). É o que mais usamos.
  • Resources — dados que o servidor disponibiliza para leitura (ex.: logs ou schemas de banco).
  • Prompts — modelos de prompt reutilizáveis que o servidor sugere.
• Transporte: cliente e servidor falam por stdio (processo local) ou HTTP (servidor remoto). O protocolo é o mesmo; muda só o canal.

Como você conecta um servidor

A configuração vive num arquivo (.mcp.json), e o plugin do Capítulo 07 pode trazê-la pronta:

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": { "PG_CONNECTION_STRING": "${PG_CONNECTION_STRING}" }
    }
  }
}

Conectado o servidor, suas ferramentas aparecem para o agente com o prefixo mcp__<servidor>__<ferramenta> — foi de onde veio o mcp__postgres__describe_table do exemplo. Do ponto de vista do agente, são apenas mais ferramentas no loop.

Como isso se conecta ao agent

A relação amarra de volta ao Capítulo 02 (ferramentas) e ao Capítulo 03 (o campo tools):

MCP estende o conjunto de ferramentas do agent para além da máquina local. O que Read e Bash são para arquivos e shell, as ferramentas MCP são para sistemas externos.

1. As ferramentas MCP entram no loop como qualquer outra. O agente não sabe (nem precisa saber) que mcp__postgres__run_query fala com um servidor remoto. Para ele, é uma ferramenta — pensar → chamar → observar, igual ao Capítulo 02.
2. O tools do agent controla o acesso. Você pode dar ao agent-order-analytics acesso ao servidor MCP do Postgres (leitura), mas negar a ele ferramentas de alteração. O princípio do menor privilégio do Capítulo 03 vale também — e principalmente — para ferramentas que tocam sistemas reais.
3. O plugin distribui a conexão. A squad order empacotada (Capítulo 07) já vem com o .mcp.json do database inspector. Quem instala o plugin ganha o agente e a porta para o banco de dados que ele precisa.

MCP vs CLI: Raciocinando sobre Performance e Economia de Tokens

Uma dúvida frequente é se devemos expor uma capacidade local como um servidor MCP ou como uma ferramenta CLI nativa executada via shell (Bash).

Aqui reside uma regra de ouro de performance e token economy: Use o CLI local para operações locais de desenvolvimento (compilar, rodar testes, lint).

• Explosão de contexto e latência: Embrulhar um compilador (como o tsc) em um servidor MCP adiciona camadas de serialização JSON, latência de IPC local, e inunda a janela de contexto com o overhead do protocolo de metadados do MCP.
• Superioridade do CLI: Deixar o agente rodar os testes e linters diretamente via terminal/shell (tools: Bash) aproveita o processo do OS nativo. É infinitamente mais rápido, consome menos recursos, e preserva a janela de contexto mantendo apenas a saída essencial.
• Quando usar o MCP: O MCP brilha na conexão de sistemas externos (como APIs de terceiros, painéis SaaS, bancos de dados corporativos) que não possuem uma interface CLI local acessível de forma trivial ou segura.

A frase de bolso: O CLI é para as ferramentas do próprio desenvolvedor no ambiente de trabalho local; o MCP é a porta USB-C para o ecossistema externo.

Em uma frase: MCP é como o agent deixa de raciocinar só sobre o seu código e passa a agir sobre o seu negócio.

Trade-offs e armadilhas

• Conectar um servidor MCP é conceder acesso. Um servidor com credenciais de escrita no banco de produção pode apagar dados. Trate credenciais de MCP como você trata qualquer segredo de produção: menor privilégio, escopo restrito, rotação.
• Injeção de prompt via resultado de ferramenta. O texto que um servidor MCP devolve entra na janela de contexto e o modelo pode segui-lo como instrução. Um servidor comprometido (ou um dado malicioso no banco) pode tentar "instruir" o agente. Não confie cegamente no que volta de uma ferramenta externa.
• Latência e disponibilidade. Cada chamada MCP é uma ida à rede ou a outro processo. Servidor lento ou fora do ar trava o loop do agente. Considere timeouts e fallback.
• Confiança no servidor. Use servidores MCP oficiais ou auditados. Um servidor de terceiro roda no seu ambiente e vê o que você passa a ele.

Como saber se você entendeu

Você dominou este capítulo se consegue:

• explicar a relação cliente (harness) ↔ servidor MCP;
• justificar a diferença entre usar uma ferramenta CLI local vs. um servidor MCP;
• citar dois riscos de segurança de conectar um servidor MCP.

Fontes

• Model Context Protocol — servidores de referência (implementações oficiais open source): https://github.com/modelcontextprotocol/servers
• Anthropic — anúncio do MCP (novembro de 2024): https://www.anthropic.com/news/model-context-protocol
• Especificação e documentação do MCP (padrão aberto): https://modelcontextprotocol.io
• Claude Code — MCP (configurar servidores, .mcp.json): https://code.claude.com/docs/en/mcp

Síntese

MCP é o padrão aberto que dá ao agente uma porta única para o mundo externo: em vez de uma integração sob medida para cada sistema, um servidor MCP embrulha o Postgres ou APIs externas e expõe ferramentas que entram no loop do agente como qualquer outra. É o que transforma um agente que conhece o seu código num agente que opera o seu banco de dados — com todo o cuidado de segurança que essa ponte exige.

Temos agora todas as camadas conceituais. Falta o lugar concreto onde você opera tudo isso, no dia a dia, no terminal.

Próximo: Capítulo 09 — O CLI.

Capítulo 09 — O CLI

O CLI é onde você opera todas as camadas anteriores: o terminal como cabine de comando do harness. É onde o agente encontra o seu ambiente real — arquivos, git, shell, testes.

TL;DR: O CLI é a cabine onde você opera todas as camadas — aciona agents, troca de modelo, instala plugins, conecta MCP — e, em modo headless, vira etapa de pipeline.

Falamos de LLM, harness, agent, subagent, context, skill, plugin e MCP como conceitos. Mas em que lugar concreto você roda tudo isso? Para a maioria dos desenvolvedores, a resposta é a linha de comando. O Claude Code é, na sua forma pri## Primeiro, o CLI em ação

Você abre o terminal no repositório do e-commerce e digita:

$ claude

A sessão começa, e tudo dos capítulos anteriores acontece aqui:

> Criar sistema robusto de CRUD de Pedidos. Quero a arquitetura antes do código.

• Acionando agent-order-architect (model: opus)        ← agent + LLM
• Read(src/orders/OrderService.ts)                       ← harness + tools
• mcp__postgres__describe_table() → [orders, events]     ← MCP
• Carregando skill improve-codebase-architecture         ← skill
• [hook PreToolUse: validar-concorrencia.sh] ok          ← plugin/hook

Decisões de arquitetura: [...]

Cada linha dessa sessão é uma camada deste e-book em operação — e o CLI é o lugar onde elas se encontram. O terminal não é um detalhe de interface: é onde o agente toca o seu ambiente de desenvolvimento de verdade.

O que é o CLI

Um CLI (Command-Line Interface, interface de linha de comando) é um programa operado por texto no terminal. No nosso contexto, o Claude Code é um CLI: o ponto de entrada pelo qual você inicia uma sessão, conversa com o agente e o deixa agir sobre o seu projeto.

O Claude Code também existe em outras formas — extensão de IDE (VS Code, JetBrains), app de desktop e web. Mas o CLI é a forma canônica, e por um bom motivo: é onde o desenvolvimento de verdade já acontece. O agente que vive no terminal está a um Bash de distância dos seus testes, do seu git, do seu build.

Por que o terminal importa

O CLI dá ao harness acesso direto ao ambiente onde você trabalha:

• Sistema de arquivos: ler e editar o código no lugar, sem upload.
• Shell: rodar testes, build, linters, git — as ferramentas Bash do Capítulo 02 operam no seu shell real.
• Composição Unix: a saída do agente pode ser canalizada (|) para outras ferramentas, e ele pode consumir a saída delas.
• Versionamento: como agents, skills e plugins são arquivos, eles entram no git junto com o código — revisados em pull request como qualquer mudança.

Comandos Customizados (Slash Commands)

O CLI permite a você interagir de forma imediata via Slash Commands (como /goal, /schedule, /grill-me). Mais do que usar os comandos padrão, você pode customizar e estender a cabine de comando criando novos atalhos no repositório. Esses comandos são definidos salvando arquivos Markdown em .claude/commands/<nome-do-comando>.md. Quando digitados, eles forçam uma instrução específica ou script determinístico diretamente na sessão, pulando o loop cognitivo do assistente geral.

Git Worktrees: Isolamento Total para Operações Agênticas

Uma das melhores práticas avançadas ao operar agentes no terminal é o uso de Git Worktrees. Muitas vezes, uma tarefa agêntica longa (como um /goal para reescrever um CRUD inteiro) pode durar minutos e travar o seu repositório local, impedindo você de trabalhar em outros arquivos ou ramos paralelos.

• Como funciona: O Git Worktree permite que você crie um diretório físico totalmente separado no disco, mas conectado ao mesmo repositório git (git worktree add ../orders-refactor feat/orders-refactor).
• Vantagem para Agentes: Você pode inicializar a sessão do CLI do agente apontando para esse worktree isolado. O agente pode fazer alterações profundas, rodar scripts agressivos de compilação, quebrar códigos intermediários e testar em background, enquanto o seu diretório de trabalho principal (main ou develop) continua limpo e disponível para seu fluxo de trabalho pessoal.

O CLI como cabine das camadas anteriores

O que você aprendeu nos capítulos anteriores aparece, no CLI, como controles concretos:

O CLI é o denominador comum: o lugar onde todas essas peças, definidas em arquivos, ganham vida em uma conversa.

Modo headless: o CLI sem você na frente

Há um recurso do CLI que destrava automação séria — o modo headless (não interativo). Em vez de uma conversa, você passa o pedido como argumento e captura a saída:

$ claude -p "Rode os testes de orders e resuma as falhas" > relatorio.txt

Isso transforma o agente em um passo de pipeline. Você pode chamá-lo de um script, de um hook de git, de um job de CI — o mesmo agente que você usa interativamente, agora dentro de uma automação. É a ponte entre "assistente que eu converso" e "etapa programável do meu fluxo".

Como isso se conecta ao agent

O fechamento do arco:

O CLI é a cabine onde você invoca e opera o agent. Se o agent é o especialista e o harness é o motor, o CLI é o painel de controle.

1. É onde o agent é acionado. Você descreve a tarefa no terminal; o harness casa com o description e aciona o agent-order-architect. O ciclo inteiro dos capítulos anteriores começa com você digitando no CLI.
2. É onde você ajusta a configuração ao vivo. /model opus antes de uma decisão difícil; /plugin install order-squad para trazer a squad; conectar um servidor MCP. O CLI é onde as decisões dos capítulos 01–08 viram comandos.
3. É onde o agent vira automação. Em modo headless, o mesmo agent-order-architect pode rodar num CI a cada PR, revisando a arquitetura automaticamente. O agente sai do terminal interativo e entra no pipeline.

Em uma frase: o CLI é onde o e-book inteiro deixa de ser teoria e vira o seu fluxo de trabalho.

Trade-offs e armadilhas

• Poder no terminal exige permissões sérias. Um agente com Bash no seu shell pode fazer estrago. Use os modos de permissão; não rode tudo em "aceitar tudo" por preguiça.
• Headless remove o humano do loop. Automação é ótima até o agente fazer a coisa errada sem ninguém olhando. Em CI, restrinja ferramentas e dê escopo apertado — o menor privilégio do Capítulo 03 vale dobrado sem supervisão.
• CLI tem curva. Para quem vive em GUI, o terminal assusta no começo. Mas é justamente a integração com shell/git/arquivos que dá ao agente o acesso que o torna útil.
• Saída para pipeline precisa ser estável. Em scripts, prefira formatos previsíveis e trate o agente como um comando que pode falhar — com timeout e verificação do resultado.

Como saber se você entendeu

Você dominou este capítulo se consegue:

• mapear pelo menos quatro camadas anteriores aos controles do CLI;
• explicar o que o modo headless habilita e quais riscos ele traz;
• descrever como os Git Worktrees auxiliam no isolamento de sessões agênticas longas.

Fontes

• Anthropic — anthropic-sdk-typescript, o SDK oficial para automações e integrações TypeScript/JS: https://github.com/anthropics/anthropic-sdk-typescript
• Claude Code — referência do CLI (comandos, flags, modo headless): https://code.claude.com/docs/en/cli-reference
• Claude Code — visão geral (formas: CLI, IDE, desktop, web): https://code.claude.com/docs/pt/overview
• Claude Code — Git Worktrees: https://code.claude.com/docs/pt/worktrees

Síntese

O CLI é onde tudo se encontra: o terminal como cabine de comando do harness, com acesso direto aos arquivos, ao shell, ao git e aos testes do seu projeto. É lá que você aciona agents, troca de modelo, instala plugins, conecta MCP — e, em modo headless, transforma o agente em uma etapa do seu pipeline. As camadas anteriores são definições em arquivos; o CLI é onde elas viram trabalho feito.

Temos o stack inteiro. No último capítulo, montamos tudo de uma vez e seguimos a tarefa de CRUD de Pedidos da primeira à última camada, sem cortes.

Próximo: Capítulo 10 — Síntese.

Capítulo 10 — Síntese

Nove camadas, um ecossistema. Aqui consolidamos todo o stack sob uma tarefa de CRUD de Pedidos real, rastreando o fluxo do primeiro token ao deploy, e mapeando as ferramentas que definem o estado da arte do desenvolvimento agêntico.

TL;DR: O stack completo opera de forma coesa para entregar um CRUD de Pedidos com isolamento via Git Worktrees, otimização de tokens com proxies locais (como RTK/Caveman), automações com Slash Commands e Skills recursivas, e feedbacks de ambiente em tempo real com Hooks e notificações do OS.

Você começou este e-book com uma lista desordenada de termos: LLM, harness, agent, subagent, context, skill, plugin, MCP, CLI. O objetivo deste trabalho foi transformar esse vocabulário solto em um sistema arquitetural estável: peças interdependentes onde cada camada resolve exatamente o gargalo que a camada anterior não consegue cobrir.

O stack em uma visão sistêmica

graph TD
    CLI["CLI — Cabine de Comando (Operação local & Shell)"]
    HARNESS["Harness — Loop, Processos, Permissões & Hooks"]
    LLM["LLM — Cérebro (Opus/Sonnet/Haiku - Model Routing)"]
    AGENT["Agent — Especialista (Instruções e Regras em Markdown)"]
    SUB["Subagents — Squad de Especialistas em Sandbox"]
    CTX["Context — Engenharia de Contexto (CLAUDE.md & RAM)"]
    SKILL["Skills — Comportamentos declarativos sob demanda"]
    MCP["MCP — Portas externas estáveis (Bancos, APIs)"]
    PLUGIN["Plugin — Pacote de distribuição de Agents, Skills & Hooks"]

    CLI --> HARNESS
    HARNESS --> LLM
    HARNESS --> AGENT
    AGENT --> SUB
    CTX -.alimenta.-> AGENT
    SKILL -.estende.-> AGENT
    MCP -.conecta.-> HARNESS
    PLUGIN -.empacota.-> AGENT
    PLUGIN -.empacota.-> SKILL
    PLUGIN -.empacota.-> MCP

Analisando a topologia do fluxo de execução:

• Fluxo Descendente (Comando): Você digita no CLI, que aciona o harness local. O harness inicializa a sessão carregando o context otimizado, interpretando os plugins instalados, estendendo capacidades através de skills e abrindo conexões MCP declaradas. O harness então invoca o agent correto, que gerencia e delega tarefas complexas a subagents especializados, orquestrando as chamadas de inferência no LLM adequado.
• Fluxo Ascendente (Execução): O LLM gera a decisão lógica que o harness intercepta, valida com hooks determinísticos locais e executa no ambiente nativo do seu repositório via CLI, garantindo segurança e controle.

O CRUD de Pedidos pelo fluxo agêntico

Vamos traçar a jornada de ponta a ponta para implementar um CRUD de Pedidos (Orders) robusto — completo com tratamento de concorrência por optimistic locking e histórico de transições de estados — mapeando exatamente onde e por que cada camada entra em ação.

1. Preparando a cabine com Git Worktrees no CLI

Antes de iniciar a sessão com o agente, você quer evitar que arquivos temporários, builds inacabados ou testes quebrados interrompam seu trabalho paralelo no ramo principal. Você inicializa um Git Worktree dedicado para a tarefa:

$ git worktree add ../orders-sandbox feat/orders-crud
$ cd ../orders-sandbox
$ claude

O CLI do Claude Code é inicializado nesse diretório limpo e isolado. O CLI apresenta uma vantagem técnica gritante em relação a interfaces web ou extensões genéricas de IDE: o CLI atua diretamente no host, acessando processos de shell nativos. Isso significa que ferramentas de linters (eslint), testes unitários (jest/vitest), compiladores (tsc) e comandos de versionamento (git) rodam sem o overhead de serialização, rede ou latência inerentes aos protocolos de rede. É a superioridade de performance e tokens do CLI em ação: chamadas diretas de shell local poupam milhares de tokens que seriam desperdiçados descrevendo o estado do sistema de arquivos pela API.

> /goal Implementar o CRUD de Pedidos com controle de concorrência e fila de eventos.

2. O Harness e a Curadoria de Contexto

Ao ler a instrução, o harness é ativado. Ele carrega as diretrizes do arquivo CLAUDE.md e do indexador de instruções AGENTS.md do projeto.

A engenharia de contexto atua aqui como uma memória RAM limpa. Em vez de enviar toda a árvore de arquivos ao LLM, o harness usa indexação seletiva. O sinal-sobre-ruído é mantido alto: apenas a convenção de nomenclatura de TypeScript, o padrão de design do repositório e os schemas SQL relevantes das tabelas orders e order_events são puxados para a janela ativa.

3. O Agent Especialista e a Squad de Subagents

O harness avalia as descrições dos agentes disponíveis e aciona o especialista agent-order-architect. Roteado automaticamente para rodar no Claude 3.5 Sonnet ou no Claude 3 Opus (devido à complexidade do desenho de concorrência), o arquiteto analisa a tarefa e percebe que codificar, testar e documentar tudo de uma vez estourará o limite cognitivo de uma única sessão.

Ele decide criar uma squad de subagents isolados em sandboxes dedicadas:

1. product-manager: Analisa as regras de negócio para as transições de estado (draft -> created -> pending_payment -> paid -> cancelled) e gera os critérios de aceitação.
2. backend-coder: Escreve o serviço em TypeScript (OrderService.ts), aplicando concorrência otimista com verificação de versão da linha (version + 1) e persistência das transições na tabela order_events.
3. qa-tester: Gera testes automatizados de integração concorrente simulando requisições paralelas para garantir que nenhuma transição de estado seja sobrescrita indevidamente.

Cada subagent trabalha com ferramentas limitadas (princípio do menor privilégio) e relata apenas o resultado compilado ao orquestrador, mantendo o contexto principal limpo.

4. Custom Slash Commands vs. Skills no Loop

Durante a implementação, o desenvolvedor pode interagir com a sessão usando atalhos rápidos. É crucial entender a diferença de finalidade de cada um:

• Slash Commands (Comandos Customizados): São atalhos de automação focados no fluxo do usuário (salvos em .claude/commands/<nome>.md, como /goal ou /grill-me). Eles forçam um comportamento determinístico de controle de sessão ou injetam prompts estruturados de forma imediata na pilha de execução.
• Skills (Conhecimento Comportamental): São arquivos de habilidades declarativas salvas em .claude/skills/<nome>/SKILL.md que o agente carrega de forma dinâmica somente se identificar que a tarefa atual necessita daquela habilidade.

Para garantir a qualidade, o agente carrega a skill recursiva de auto-melhoria skill-recursiva-feedback-loop-harness. Esta skill executa um ciclo autônomo (EFL - Error Fix Loop): compila o código TypeScript com npx tsc --noEmit, roda os testes com npm run test e, se encontrar falhas, lê as mensagens de erro, ajusta o código e repete o ciclo recursivamente até que a execução esteja livre de erros e em total conformidade técnica.

[!WARNING] Aviso Crítico de Economia: Sempre teste a execução básica do seu código sem skills ativas primeiro. Carregar múltiplas skills pesadas de forma contínua em tarefas simples gera uma explosão de tokens desnecessária, consumindo rapidamente a cota de processamento. Use skills complexas apenas quando a automação de correção de falhas for estritamente necessária.

5. Gateways Externos via MCP

Para persistir os dados e disparar notificações reais para sistemas de terceiros, o harness se conecta a servidores locais e remotos usando o Model Context Protocol (MCP).

• O agente utiliza a ferramenta do MCP de banco de dados (mcp__postgres__query) para inspecionar os índices das tabelas e garantir que o campo order_id na tabela order_events possui a indexação correta para buscas de auditoria rápidas.
• O agente utiliza o MCP de mensageria para validar a fila de transição de status no sistema de mensagens externas.

O MCP atua como uma interface padronizada estável para o agente acessar o mundo externo sem precisar codificar conexões brutas em nível de soquete em cada execução.

6. Hooks e Notificações de Ambiente

Antes de consolidar as alterações, o harness aciona os Hooks de pré-execução declarados no manifesto do plugin do projeto:

• O hook PreToolUse executa um script bash local (validar-typescript.sh) para assegurar que nenhum tipo any implícito foi adicionado no serviço de pedidos.
• Quando o /goal longo de reestruturação é concluído com sucesso e a branch do Git Worktree está pronta, o hook de finalização de tarefa dispara uma notificação física para o desenvolvedor: um aviso sonoro no terminal (beep) e um pop-up visual no sistema operacional. Isso evita que você precise policiar o terminal em tarefas demoradas, permitindo que você retorne à cabine assim que o trabalho agêntico for finalizado.

# Exemplo de script de notificação física acionado por Hook pós-sucesso
osascript -e 'display notification "CRUD de Pedidos implementado e testado com sucesso no Git Worktree!" with title "Claude Code"'
echo -e "\a" # Emite um sinal sonoro (beep) no terminal host

O Ecossistema da Comunidade e a Economia de Tokens

O desenvolvimento AI-native moderno não se limita às ferramentas oficiais da Anthropic. Existe uma comunidade vibrante que cria ferramentas fundamentais para otimização de custos, gerenciamento de memória e indexação de bases de código:

1. Economia de Tokens e Proxy de Linha de Comando:
   • RTK (Rust Token Killer) (github.com/rtk-ai/rtk): Um proxy otimizado escrito em Rust que intercepta e comprime logs de terminal, outputs de linters e testes gigantescos antes de enviá-los ao LLM, gerando economias drásticas de 60% a 90% em operações diárias de desenvolvimento.
   • Caveman (github.com/JuliusBrussee/caveman): Uma alternativa focada no controle rígido de consumo de tokens em ambientes CLI locais.
2. Repositórios de Skills e Plugins:
   • aitmpl.com/skills/ e skills.sh: Marketplaces públicos e repositórios comunitários para descobrir, compartilhar e baixar skills prontas de auditoria, refatoração de código, testes e deploys.
   • context-7 (context7.com): Plataforma de documentação em tempo real que alimenta agentes (como Cursor e Claude Code) com referências atualizadas e exemplos práticos via CLI (npx ctx7 setup) ou servidores MCP para evitar alucinações de APIs obsoletas.
   • frontend-design (github.com/anthropic/frontend-design-skill): Skill oficial de curadoria visual da Anthropic, direcionando o LLM a adotar estéticas profissionais premium, banir clichês ("AI slop") e fontes padrão de navegador.
   • ui-ux-pro-max (github.com/nextlevelbuilder/ui-ux-pro-max-skill): Base de conhecimento e gerador inteligente de sistemas de design, cobrindo mais de 50 estilos visuais, paletas curadas e guias de acessibilidade para Next.js, React e SwiftUI.
3. Gerenciamento de Memória Persistente:
   • claude-mem (github.com/thedotmack/claude-mem): Um utilitário de persistência de memória a longo prazo para o Claude Code que estende as capacidades nativas do agente de recordar preferências, padrões de arquitetura e decisões de sessões passadas entre reinicializações de máquina.
4. Indexação com Grafos de Dependência:
   • lemon-code-graph (github.com/Andersonlimahw/lemon-code-graph): Ferramenta que gera grafos de chamadas e mapeamentos de arquivos no repositório local, otimizando o envio de dependências cruzadas para a janela de contexto do agente.
   • Open Graph (github.com/colbymchenry/codegraph): Analisador de grafos de código para contextualização agêntica aprofundada.
5. LLM-Wiki de Karpathy:
   • O guia definitivo e minimalista de referência de arquitetura mental de LLMs mantido por Andrej Karpathy: LLM-Wiki Gist.

Ferramentas e CLIs Equivalentes ao Claude Code

Para além do Claude Code, o cenário de desenvolvimento AI-native conta com diversas alternativas e proxies equivalentes focados em comandos via terminal e automação nativa:

Síntese Prática: O Modelo Mental Cristalizado

Se você precisar reter apenas a essência deste e-book para guiar seu fluxo de trabalho amanhã:

LLM é o cérebro. Harness é o corpo físico e executor. Agent é o especialista contextualizado por arquivos markdown. Subagents representam a squad operando em sandbox. Context é a memória de trabalho (RAM) limpa e curada. Skills são as competências declarativas que o agente aprende sob demanda. MCP representa os canais e pontes estáveis para o mundo externo. Plugins são os pacotes de distribuição e compartilhamento desse ecossistema. E o CLI é a sua cabine de controle direto no host.

Por onde começar amanhã

Teoria sem aplicação prática é rapidamente esquecida. Comece a transformar seu fluxo de trabalho em AI-native seguindo estes passos incrementais:

1. Crie seu primeiro Agent customizado: Mapeie uma tarefa puramente sua (ex: criar changelogs com base em commits do git ou rodar migrations de banco) e escreva um arquivo .claude/agents/changelog-builder.md com name, description e regras estritas de atuação.
2. Defina um Custom Command: Crie uma automação em .claude/commands/deploy-check.md para rodar linters, testar tipos e gerar um relatório unificado de saúde do código antes de commits importantes.
3. Monitore e Economize: Adicione o proxy rtk na frente do seu terminal e monitore os ganhos de tokens diários ao rodar sessões repetidas.
4. Utilize Git Worktrees: Nunca mais trave sua branch principal com sessões longas de agentes /goal. Crie um diretório temporário conectado ao git e deixe o agente trabalhar isoladamente enquanto você continua desenvolvendo em paralelo.

O stack está montado e ao seu alcance. A cabine de comando do terminal está aberta. É hora de projetar e operar com a sua própria squad de engenharia agêntica.

Fontes de Referência e Estudo Contextual

• Anthropic Agent SDK: Referência de design para o ciclo de vida do Agent Loop: https://code.claude.com/docs/pt/agent-sdk/agent-loop
• Claude Code CLI & Worktrees: Melhores práticas e isolamento de processos agênticos: https://code.claude.com/docs/pt/worktrees
• Best Practices Anthropic: Recomendações oficiais de uso de ferramentas locais no host: https://code.claude.com/docs/pt/best-practices
• Ecosystem and Memory: Estudo sobre o comportamento de engenharia de contexto e memória: https://code.claude.com/docs/pt/memory
• Lemon Blog: Para aprofundar nos fundamentos de agentes e como escrever instruções ricas, veja o artigo: Como criar agents customizados com Claude Code
• Lemon Blog: Para entender mais sobre otimização do ciclo de desenvolvimento com ferramentas de economia de tokens, leia: Entendendo a economia de tokens em CLI agênticos
• Lemon Blog: Para compreender o funcionamento interno e a arquitetura por trás da correção recursiva de erros, confira: Implementando loops recursivos de correção em AI Harness

Voltar ao índice.