Phase 14 - Lesson 33

Instruções de Agente como Restricções Executáveis

Instruções escritas como prosa são desejos. Instruções escritas como restrições são testes. A bancada de trabalho transforma cada regra em algo que um agente pode verificar em tempo de execução e um revisor pode verificar após o fato.

Tipo: Build Linguagens: Python (stdlib) Pré-requisitos: Fase 14 · 32 (Bancada de Trabalho Mínima) Tempo: ~50 minutos

Objetivos de Aprendizado

  • Separar prosa de roteamento de regras operacionais.
  • Expressar regras de inicialização, ações proibidas, definição de pronto, tratamento de incerteza e limites de aprovação como restrições verificáveis por máquina.
  • Implementar um verificador de regras que pontua uma execução em relação ao conjunto de regras.
  • Tornar o conjunto de regras amigável a diffs para que a revisão possa ver o que mudou.

O Problema

Um arquivo AGENTS.md típico é lido como documentação de integração (onboarding). Ele diz ao agente para "ter cuidado", "testar exaustivamente" e "perguntar se não tiver certeza". Três dias depois, o agente envia uma alteração sem testes, grava em um diretório proibido e nunca pergunta porque nunca soube onde estava o limite.

As instruções são poderosas quando são operacionais e fracas quando são aspiracionais. O solução é escrever regras que a bancada de trabalho possa interpretar e o revisor possa pontuar.

O Conceito

As regras pertencem a docs/agent-rules.md, longe do roteador raiz curto. Cada regra tem um nome, uma categoria e uma verificação.

flowchart LR
  Router[AGENTS.md] --> Rules[docs/agent-rules.md]
  Rules --> Checker[rule_checker.py]
  Checker --> Report[rule_report.json]
  Report --> Reviewer[Revisor]

Cinco categorias que cobrem a maioria das regras

Categoria Pergunta que a regra responde Exemplo
Inicialização O que deve ser verdade antes de o trabalho começar? "o arquivo de estado existe e é recente"
Proibido O que nunca deve acontecer? "não editar scripts/release.sh"
Definição de pronto O que prova que a tarefa está concluída? "pytest sai com 0 e a linha de aceitação passa"
Incerteza O que o agente faz quando não tem certeza? "abrir uma nota de pergunta em vez de adivinhar"
Aprovação O que exige aprovação humana? "qualquer nova dependência, qualquer gravação em produção"

Uma regra que não se encaixa em uma dessas cinco geralmente quer ser dividida em duas regras. Force a divisão.

Regras são legíveis por máquina

Cada regra tem um identificador (slug), uma categoria, uma descrição de uma linha e um campo check que nomeia uma função em rule_checker.py. Adicionar uma regra significa adicionar uma verificação; o verificador cresce com a bancada de trabalho.

Regras são amigáveis a diffs

As regras vivem uma por título em um único arquivo markdown. Renomeações são visíveis em diffs. Novas regras ficam no topo de sua categoria. Regras obsoletas são excluídas, não comentadas, porque a bancada de trabalho é a fonte da verdade, não o registro de chat de como a equipe se sentia no trimestre passado.

Regras versus salvaguardas de framework

As salvaguardas de framework (salvaguardas do SDK do OpenAI Agents, interrupções do LangGraph) aplicam as regras no nível do tempo de execução. O conjunto de regras nesta lição é o contrato legível por humanos e revisável que essas salvaguardas implementam. Você precisa de ambos: o tempo de execução captura as violações durante uma iteração, o conjunto de regras prova que o tempo de execução está fazendo a coisa certa.

Construa

O arquivo code/main.py entrega:

  • O analisador de agent-rules.md que carrega as regras em uma dataclass.
  • Funções verificadoras de estilo de rule_checker.py, uma por referência de check.
  • Uma execução de demonstração de agente que viola duas regras e uma etapa de verificação que as captura.

Execute:

python3 code/main.py

Saída: conjunto de regras analisado, rastreamento da execução, aprovação/falha por regra e um rule_report.json salvo ao lado do script.

Padrões de produção na prática

Três padrões separam um conjunto de regras que dura um trimestre de um que decai em uma semana.

Marcação de gravidade no momento da escrita. Cada regra carrega uma gravidade (severity): block, warn ou info. O verificador relata as três; o tempo de execução só recusa em caso de block. A maioria das equipes superestima a gravidade no início e depois a enfraquece silenciosamente sob a pressão do prazo de entrega; a marcação no momento da escrita força a calibração antecipada. Combine com o portão de verificação (Fase 14 · 38), que assina qualquer substituição de uma regra block em um registro de auditoria overrides.jsonl.

Expiração de regras como uma função de indução. Cada regra carrega uma data de expiração expires_at (padrão de 90 dias a partir da criação). O verificador emite um aviso quando uma regra não expirada teve zero violações por 60 dias consecutivos; a próxima revisão trimestral justifica mantê-la, enfraquece-a para info ou a exclui. Os dados de revisão de código de IA de produção da Cloudflare (abril de 2026, 131.246 execuções de revisão em 5.169 repositórios em 30 dias) mostraram que conjuntos de regras com expiração explícita permaneceram abaixo de 30 regras por repositório; conjuntos sem expiração cresceram para mais de 80, com a maioria nunca sendo acionada.

Markdown como origem, JSON como cache. O arquivo agent-rules.md é o arquivo de origem; agent-rules.lock.json is a cache que o verificador lê no caminho crítico de execução. O lock é regenerado por um gancho de pré-commit (pre-commit hook). Os diffs em markdown são fáceis de revisar; a análise de JSON fica de fora de cada iteração do agente. Mesma estrutura de package.json / package-lock.json e Cargo.toml / Cargo.lock.

Use

Em produção:

  • Claude Code, Codex e Cursor leem as regras no início da sessão e as citam ao recusar ações. O verificador as executa novamente em CI para capturar desvios silenciosos.
  • As salvaguardas do SDK do OpenAI Agents registram as mesmas verificações como salvaguardas de entrada e saída. O markdown é a interface de documentação; o SDK é a interface de tempo de execução.
  • As interrupções do LangGraph são acionadas quando um nó em execução viola uma regra. O manipulador de interrupções lê a regra, pergunta ao humano e continua.

O conjunto de regras é portátil entre as três opções porque é apenas markdown combinado com nomes de funções.

Entregue

O arquivo outputs/skill-rule-set-builder.md entrevista o proprietário de um projeto, classifica suas instruções em prosa existentes nas cinco categorias e emite um agent-rules.md com versão, além de um esboço do verificador (checker stub).

Exercícios

  1. Adicione uma sexta categoria se o seu produto genuinamente precisar dela. Defenda por que ela não se reduz a uma das cinco.
  2. Estenda o verificador para que uma regra possa ter uma gravidade (block, warn, info) e o relatório faça a agregação correspondente.
  3. Conecte o verificador ao CI: falhe o build se uma regra de gravidade block falhar na execução mais recente do agente.
  4. Adicione um campo de expiração por regra. Após 90 dias sem falhas de verificação, a regra deve ser revisada.
  5. Encontre um AGENTS.md real e reescreva-o como regras de cinco categorias. Quantas de suas linhas eram operacionais? Quantas eram aspiracionais?

Termos-Chave

Termo O que as pessoas dizem O que realmente significa
Regla operacional "Uma instrução real" Uma regra que a bancada de trabalho pode verificar em tempo de execução
Regra aspiracional "Tenha cuidado" Uma regra sem verificação; deve ser excluída ou atualizada
Definição de pronto "Aceitação" Uma prova objetiva baseada em arquivo de que a tarefa está concluída
Gravidade de bloqueio "Regra rígida" A violação interrompe a execução; não pode ser silenciada sem um operador
Expiração de regra "Limpeza de regras obsoletas" Uma regra sem falhas em N dias está sujeita a aposentadoria

Leituras Adicionais

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