Phase 14 - Lesson 32

The Minimal Agent Workbench

Tipo: Construir Linguagens: Python (stdlib) Pré-requisitos: Fase 14 · 31 (Por Que Modelos Capazes Ainda Falham) Tempo: ~45 minutos

Objetivos de Aprendizado

  • Definir os três arquivos que formam a bancada de trabalho mínima viável.
  • Explicar por que um roteador raiz curto supera um arquivo AGENTS.md longo e monolítico.
  • Construir um arquivo de estado que o agente possa ler a cada turno e escrever no final.
  • Construir um quadro de tarefas que sobreviva a trabalhos de múltiplas sessões sem histórico de chat.

O Problema

A maioria das equipes tenta criar uma bancada escrevendo um arquivo AGENTS.md de 3000 linhas e considerando o trabalho concluído. O modelo o carrega, ignora as partes que não consegue resumir e ainda falha nas mesmas superfícies de sempre.

Você precisa do oposto. Um arquivo raiz minúsculo que direcione o agente para arquivos mais profundos apenas quando for relevante. Estado durável que o agente lê antes de agir e escreve depois. Um quadro de tarefas que diz o que está em andamento, o que está bloqueado e o que vem a seguir.

Três arquivos. Cada um com uma função. Cada um legível por máquina o suficiente para evoluir para um sistema real mais tarde.

O Conceito

flowchart LR
  Agent[Loop do Agente] --> Router[AGENTS.md]
  Router --> State[agent_state.json]
  Router --> Board[task_board.json]
  State --> Agent
  Board --> Agent

AGENTS.md é um roteador, não um manual

Um bom AGENTS.md é curto. Ele aponta o agente para:

  • O arquivo de estado (onde você está).
  • O quadro de tarefas (o que resta).
  • As regras mais profundas (sob docs/agent-rules.md).
  • O comando de verificação (como saber se funciona).

Qualquer coisa mais longa vai para documentos mais profundos, carregados apenas quando necessário. Manuais longos são ignorados. Roteadores curtos são seguidos.

agent_state.json é o sistema de registro

O estado carrega: o active task id, os arquivos modificados (touched files), as premissas adotadas, os bloqueadores e a próxima ação. O agente o lê a cada turno. A próxima sessão o lê em vez de reproduzir o chat.

O estado reside em um arquivo porque o histórico de chat não é confiável. Sessões expiram. Conversas são cortadas. O arquivo permanece.

task_board.json é a fila

O quadro de tarefas carrega cada tarefa com o status todo | in_progress | done | blocked. É a fila da qual o agente consome quando o estado está vazio, e a fila que você lê quando quer saber se o agente está no caminho certo.

Uma tarefa no quadro tem um id, um objetivo (goal), um proprietário (builder, reviewer ou human) e critérios de aceitação. O quadro é pequeno de propósito: quando ele cresce mais do que uma tela, você tem um problema de planejamento, não de quadro.

Três arquivos é o piso, não o teto

Lições posteriores adicionam contratos de escopo, executores de feedback, portões de verificação, listas de verificação do revisor e pacotes de transição. Os três arquivos aqui são o que todos eles assumem.

Construa

code/main.py escreve a bancada mínima em um repositório vazio e demonstra um único turno do agente que:

  1. Lê agent_state.json.
  2. Puxa a próxima tarefa de task_board.json se o estado estiver vazio.
  3. Modifica um único arquivo dentro do escopo.
  4. Grava de volta o estado atualizado.

Execute-o:

python3 code/main.py

O script cria workdir/ ao lado de si mesmo, define os três arquivos, executa um turno e imprime o diff. Execute-o novamente para ver como o segundo turno recomeça de onde o primeiro parou.

Use-o

Dentro de produtos de agentes em produção, os mesmos três arquivos aparecem sob nomes diferentes:

  • Claude Code: AGENTS.md ou CLAUDE.md para o roteador, armazenamentos no estilo .claude/state.json para o estado, hooks para o quadro.
  • Codex / Cursor: regras do espaço de trabalho (workspace rules) para o roteador, memória de sessão para o estado, tarefas enfileiradas na barra lateral do chat para o quadro.
  • Custom Python agent: os mesmos arquivos que você acabou de escrever.

Os nomes mudam. O formato não.

Padrões de produção em uso real

A bancada mínima sobrevive ao contato com monorepos reais quando três padrões são aplicados sobre ela. Eles são independentes; escolha aqueles de que seu repositório realmente precisa.

Arquivos AGENTS.md aninhados com precedência de proximidade. A OpenAI envia 88 arquivos AGENTS.md em seu repositório principal, um por subcomponente. Codex, Cursor, Claude Code e Copilot percorrem o caminho a partir do arquivo de trabalho em direção à raiz do repositório e concatenam cada AGENTS.md que encontram no caminho. Arquivos de subdiretório estendem o arquivo raiz. O Codex adiciona AGENTS.override.md para substituir em vez de estender; o mecanismo de override é específico do Codex e deve ser evitado em trabalhos entre ferramentas. A medição da Augment Code é a métrica que importa: os melhores arquivos AGENTS.md proporcionam um salto de qualidade equivalente a atualizar do Haiku para o Opus; os piores tornam a saída pior do que se não houvesse arquivo nenhum.

Antipadrões a recusar, mesmo quando parecem dar cobertura. Instruções conflitantes silenciosamente rebaixam o agente do modo interativo para o modo guloso (greedy) (ICLR 2026 AMBIG-SWE: taxa de resolução de 48.8% → 28%); numere as prioridades em vez de listá-las de forma plana. Regras de estilo não verificáveis ("siga o Google Python Style Guide") sem comando de execução permitem que o agente invente a conformidade; associe cada regra de estilo ao comando exato de lint. Começar com estilo em vez de comandos enterra o caminho de verificação; comandos primeiro, estilo por último. Escrever para humanos em vez de agentes desperdiça orçamento de contexto; concisão é uma virtude.

Links simbólicos entre ferramentas. Um único arquivo raiz com links simbólicos (ln -s AGENTS.md CLAUDE.md, ln -s AGENTS.md .github/copilot-instructions.md, ln -s AGENTS.md .cursorrules) mantém todos os agentes de codificação sob a mesma fonte de verdade. O nx ai-setup da Nx automatiza isso no Claude Code, Cursor, Copilot, Gemini, Codex e OpenCode a partir de uma única configuração.

Envie

outputs/skill-minimal-workbench.md gera a bancada de três arquivos para qualquer novo repositório: um roteador AGENTS.md ajustado ao projeto, um agent_state.json com as chaves corretas e um task_board.json semeado com o backlog atual.

Exercícios

  1. Adicione um timestamp last_run ao agent_state.json. Recuse a execução se o arquivo tiver mais de 24 horas, a menos que um operador confirme.
  2. Adicione um campo priority ao quadro de tarefas e altere o extrator para sempre escolher o todo de maior prioridade.
  3. Migre task_board.json para JSON Lines para que cada tarefa seja uma linha e os diffs fiquem limpos no controle de versão.
  4. Escreva um lint_workbench.py que falhe se AGENTS.md tiver mais de 80 linhas ou fizer referência a um arquivo que não existe.
  5. Decida qual dos três arquivos causaria mais impacto se fosse perdido. Defenda sua resposta.

Termos-Chave

Termo O que as pessoas dizem O que realmente significa
Roteador AGENTS.md Arquivo raiz curto que aponta o agente para documentos e arquivos mais profundos
Arquivo de estado "As notas" Registro legível por máquina de onde o agente está, gravado a cada turno
Quadro de tarefas "O backlog" Fila de trabalho em JSON com status, proprietário e aceitação
Sistema de registro "Fonte de verdade" O arquivo que a bancada trata como autoritativo quando o chat se vai

Leitura Adicional

0 lifetime access. Curriculum based on AI Engineering from Scratch by Rohit Ghumare (MIT, used under attribution).