Phase 14 - Lesson 36

Contratos de Escopo e Limites de Tarefas

This lesson includes a graded coding exercise that runs in your browser, unlocked with lifetime access.

O modelo não sabe onde o trabalho termina. Um contrato de escopo é um arquivo por tarefa que define onde o trabalho começa, onde termina e como reverter caso ele extrapole. O contrato transforma "manter-se no escopo" de um desejo em uma verificação.

Tipo: Build Linguagens: Python (stdlib) Pré-requisitos: Fase 14 · 32 (Minimal Workbench), Fase 14 · 33 (Rules as Constraints) Tempo: ~50 minutos

Objetivos de Aprendizagem

• Escrever um contrato de escopo que um agente lê no início da tarefa e um verificador lê no final.
• Especificar arquivos permitidos, arquivos proibidos, critérios de aceitação, plano de reversão e limites de aprovação.
• Implementar um verificador de escopo que compara um diff com o contrato e sinaliza violações.
• Tornar o desvio de escopo visível, automático e revisável.

O Problema

Os agentes desviam do escopo. A tarefa é "corrigir o bug de login". O diff altera a rota de login, o auxiliar de e-mail, o driver do banco de dados, o README e o script de lançamento. Cada alteração tinha um motivo plausível no momento. Juntas, elas representam uma mudança diferente da que foi revisada.

O desvio de escopo (scope creep) é o modo de falha menos monitorado no trabalho com agentes porque o agente narra cada etapa de boa-fé. A solução não é um prompt mais estrito. A solução é um contrato em disco que diz o que foi prometido e uma verificação que compara o resultado com a promessa.

O Conceito

flowchart LR
  Task[Tarefa] --> Contract[scope_contract.json]
  Contract --> Agent[Loop do Agente]
  Agent --> Diff[diff final]
  Diff --> Checker[scope_checker.py]
  Contract --> Checker
  Checker --> Verdict{dentro do escopo?}
  Verdict -- sim --> Verify[Portão de Verificação]
  Verdict -- não --> Block[bloqueio + pergunta em aberto]

O que vai em um contrato de escopo

Um contrato sem forbidden_files é incompleto. O espaço negativo é metade do contrato.

Globs, não caminhos brutos

Repositórios reais movem arquivos. Vincule contratos a globs (app/**/*.py, tests/test_signup*.py) para que uma refatoração entre sessões não invalide o contrato.

Reversão faz parte do escopo

Listar como reverter força o autor do contrato a pensar no que pode dar errado. Um contrato do qual você não pode reverter é um contrato que não deveria ser aprovado.

Verificação de escopo é uma verificação de diff

O agente gera um diff. O verificador lê o diff, os globs permitidos, os globs proibidos e uma lista de quaisquer comandos de aceitação que foram executados. Cada violação é uma constatação sinalizada que o portão de verificação pode recusar.

Construa

code/main.py implementa:

• Schema de scope_contract.json (subconjunto de JSON Schema, arrays de globs).
• Um analisador (parser) de diff que transforma uma lista de arquivos tocados e uma lista de comandos executados em um RunSummary.
• Um scope_check que retorna (violations, in_scope, off_scope) em relação ao contrato.
• Duas execuções de demonstração: uma que permanece no escopo e outra que se desvia dele. O verificador sinaliza o desvio com o arquivo exato e o motivo.

Execute:

python3 code/main.py

Saída: o contrato, as duas execuções, os vereditos por execução e um scope_report.json salvo.

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

Um profissional que utiliza "specsmaxxing" (contratos de escopo em YAML antes de invocar o agente) relata que a taxa de desvio em "tocas de coelho" caiu de 52% para 21% em três semanas sem alterar o agente. O contrato fez o trabalho, não o modelo. Três padrões fazem com que esse ganho se mantenha.

Orçamentos de violação, não falhas binárias. O agent-guardrails (o portão de mesclagem de código aberto usado pelo Claude Code, Cursor, Windsurf, Codex via MCP) envia um violationBudget por tarefa: desvios menores de escopo dentro do orçamento aparecem como avisos; apenas quando o orçamento é excedido o portão de mesclagem recusa a alteração. Combine com violationSeverity: "error" | "warning". O orçamento é a diferença entre um portão que é implantado e um portão que é desativado pela equipe que o odiou.

Assimetria de severidade por família de caminhos. Gravações fora do escopo em docs/** geralmente geram um aviso (warn); gravações fora do escopo em scripts/**, migrations/**, config/prod/** são sempre bloqueadas (block). Essa assimetria deve residir no contrato, não no ambiente de execução, porque é específica do projeto e muda de acordo com a tarefa.

Orçamentos de tempo e rede ao lado de orçamentos de arquivos. Um campo time_budget_minutes limita o tempo real decorrido; o ambiente de execução se recusa a continuar além dele sem uma nova aprovação. Uma lista de permissões network_egress de hostnames impede que o agente acesse discretamente uma API externa que não fazia parte da tarefa. Essas também são dimensões de escopo; os globs de arquivos são necessários, mas não suficientes.

Semântica de mesclagem de múltiplos contratos (princípio do privilégio mínimo). Quando dois contratos de escopo se aplicam (por exemplo, um contrato para todo o projeto e um específico da tarefa), a mesclagem é: fazer a interseção de allowed_files (ambos os contratos devem permitir o caminho), fazer a união de forbidden_files (qualquer um pode proibir), time_budget_minutes é o mais restritivo (mínimo) e approvals_required acumula. network_egress is None para nenhuma imposição, [] para negar tudo, [...] como lista de permissões; na mesclagem, None delega para o outro lado, duas listas sofrem interseção e negar tudo permanece negar tudo. Declare isso no schema do contrato para que a mesclagem seja mecânica e revisável.

Use

Padrões de produção:

• Comandos de barra do Claude Code. Um comando /scope escreve o contrato e o fixa como contexto da sessão. Os subagentes leem o contrato antes de agir.
• PRs do GitHub. Envie o contrato como um arquivo JSON no corpo do PR ou como um artefato registrado. O CI executa o verificador de escopo contra o diff de mesclagem.
• Interrupções do LangGraph. Uma violação de escopo aciona uma interrupção; o manipulador pergunta ao humano se o contrato precisa ser expandido ou se o agente deve recuar.

O contrato acompanha a tarefa. Quando a tarefa é fechada, o contrato é arquivado em outputs/scope/closed/.

Envie

outputs/skill-scope-contract.md gera um contrato de escopo para uma descrição de tarefa e um verificador compatível com globs que roda no CI a cada diff do agente.

Exercícios

1. Adicione um campo network_egress listando hosts externos permitidos. Recuse execuções que toquem em outros hosts.
2. Estenda o verificador para falhar de forma suave (fail soft) em docs/** e de forma rígida (fail hard) em scripts/**. Justifique a assimetria.
3. Faça o contrato derivar allowed_files de um campo goal usando um conjunto de regras estáticas (sem LLM). O que dá errado no primeiro caso extremo?
4. Adicione um time_budget_minutes e recuse-se a continuar quando o relógio ultrapassar esse limite.
5. Execute dois contratos contra o mesmo diff. Qual é a semântica de mesclagem correta quando ambos se aplicam?

Termos-Chave

Leituras Adicionais

• Interrupções human-in-the-loop do LangGraph
• Políticas de aprovação de ferramentas do OpenAI Agents SDK
• logi-cmd/agent-guardrails — portões de mesclagem e validação de escopo — orçamentos de violação, níveis de severidade
• Dev|Journal, Preventing AI Agent Configuration Drift with Agent Contract Testing — modo --strict sem dependências externas
• Agentic Coding Is Not a Trap (logs de produção) — comprovantes de specsmaxxing: 52% → 21%
• Globs de permissão do OpenCode — escopo detalhado por permissão
• Knostic, AI Coding Agent Security: Threat Models and Protection Strategies — escopo como parte do menor privilégio
• Augment Code, AI Spec Template — sistema de limites de três níveis (must/ask/never)
• Fase 14 · 27 — defesas contra injeção de prompt que se emparelham com bloqueios de escopo
• Fase 14 · 33 — o conjunto de regras que este contrato especializa por tarefa
• Fase 14 · 38 — o portão de verificação no qual o verificador se reporta