Cases / Agente com limites verificados

Agente de IA com limites verificados — contenção, guardas e publicação

Um agente que executa tarefas de uma especificação precisa de limites que se possam checar, e não só de limites declarados. O case descreve um pipeline de cinco etapas automatizadas, entre duas decisões humanas, com um único agente executor, e mostra, para cada princípio, o mecanismo que o implementa e a verificação que o exercita.

FunçãoAnalista de requisitos e desenvolvedor (projeto autoral)
PeríodoOut 2026
SituaçãoFluxo assistido
Screenshot ampliado — Agente com limites verificados

O problema

Uma especificação diz o que fazer; ela não diz o que o leitor não pode fazer. Quando o leitor é um agente, as duas perguntas passam a importar: o que ele não deve conseguir, mesmo errando, e como saber que esse limite existe de fato, e não só no documento. O case «Especificação para dois leitores» trata de como escrever para esse leitor; este trata da operação.

Decisões técnicas

  • O pipeline. O fluxo tem cinco etapas automatizadas: preflight, uma sessão do agente por tarefa, relatório, política sobre o diff e publicação. Duas decisões ficam com o dono: aprovar a spec e as tarefas, e mesclar o PR. Entre elas há um único agente executor, e as etapas passam o estado adiante em arquivos. O agente é uma etapa entre scripts, e o que vale é o que os scripts medem.
  • Spec e tarefas como contrato. Spec e tarefas são redigidas num chat de planejamento e aprovadas pelo dono. O tasks.md é o contrato com o agente: cada tarefa declara seu nível de risco (de 1 a 3), os caminhos que pode alterar, as ferramentas que pode usar, o comando de aceite e se declara parada antes do commit. O preflight valida esses campos antes de o agente subir. O nível 3 só é aceito com essa parada declarada e com liberação explícita. A spec.md é a porta de entrada, com aprovação datada e sem marcador de pendência, e o Claude Code carrega o CLAUDE.md do projeto na sessão.
  • Aceite executável. O aceite é um comando com resultado esperado, e por isso um erro na própria especificação aparece como falha, e não como dúvida. No piloto manual de 17 e 18/10, o aceite de uma tarefa contava, com grep, as linhas que citavam caminhos do Windows em cinco documentos do repositório e esperava 13 linhas; o padrão tinha as barras invertidas do caminho escapadas do jeito errado, e a parte dele que buscava o caminho não casava nenhuma linha. O aceite falhou, o erro estava na spec, e a spec foi corrigida.
  • Privilégio mínimo e saída negada por padrão. O agente roda num ambiente isolado, sem privilégio de administrador, sem acesso ao servidor de contêineres da máquina, sem credenciais de acesso remoto nem do GitHub e sem escrita no histórico do repositório. Cada tarefa lista as ferramentas que pode usar, e o preflight recusa as que dão acesso a git, rede, contêineres ou privilégio elevado. A saída de rede é negada por padrão: só passa pelo intermediário, que recusa o resto. Oito verificações de contenção exercitam esses acessos, e cada acesso nomeado tem ao menos uma. O operador usa skills de invocação manual no host; o ambiente do agente não herda as skills do host.
  • Falha fechada. Na dúvida, o pipeline não segue. O preflight junta todas as faltas e, havendo uma, o agente não sobe: numa fixture descartável, com o run.sh e o Docker reais, uma tarefa sem aceite terminou com código 1, nenhum container de agente foi criado e o remoto local não ganhou nenhuma branch agent/*. A política sobre o diff funciona igual: numa fixture descartável, um .env real no diff fez a política bloquear e nada foi publicado, e o mesmo cenário sem o .env publicou a branch. No piloto manual de 17 e 18/10, quando a verificação de que quatro variáveis de configuração não eram mais usadas falhou, porque um teste ainda as lia, o agente parou em vez de contornar.
  • Separação de funções. Quem executa não valida o aceite. Depois da sessão, o report.sh roda o comando de aceite de cada tarefa num container novo e compara o código de saída; a marca de tarefa concluída que o agente põe no arquivo é ignorada. Na execução real de 26/10, o agente conferiu os três aceites pela contagem do grep -c, porque o echo do código de saída foi bloqueado. O código que consta no registro.md (“Esperado: 0; obtido: 0”) veio do script, e não do agente.
  • Mutação nas guardas. O autoteste aplica um operador de mutação simples a cada guarda: troca a linha marcada por um comando vazio, numa cópia, e exige que a verificação correspondente passe a falhar. É a ideia do teste de mutação aplicada às guardas e não ao código de produção: se a verificação continua passando sem a guarda, ela não testa a guarda. São 22 guardas, em quatro grupos: antes da sessão (10), sobre o diff (6), no relatório (3) e na publicação (3), como spec sem aprovação datada, arquivo .env real no diff e branch de destino já existente. Ao neutralizar cada linha, a verificação correspondente falhou, como deveria.
  • Existir não é executar. O pré-commit do repositório Compras Públicas SC foi versionado em 19/08/2026 com modo 100644, e com esse modo o git não executa o hook; passou a 100755 em 28/10/2026. Numa cópia descartável, com um IP de documentação num arquivo .md, o commit passou com o modo antigo e foi bloqueado com o novo. Esse hook protege commits feitos no host, não o ambiente do agente. A varredura do histórico de 19/08 a 28/10/2026 (gitleaks em 148 commits e uma busca de IPv4 válido em arquivos .md de 48 commits) não achou nada e não depende do hook.
  • Rastreabilidade e humano no circuito. A rastreabilidade vai da spec ao relatório: a branch é agent/ mais o id da spec, a mensagem do commit leva o mesmo id, e o registro.md vai no commit e serve de corpo do PR, com o commit base e, por tarefa, comando, código esperado e código obtido. O código chega à main por pull request, e a decisão final é humana: o PR da execução real, de 26/10/2026, foi mesclado pela conta do dono.

Resultado

Escopo. O fluxo atende hoje tarefas pequenas e assistidas: um piloto manual em 17 e 18/10 e uma execução real em 26/10, que alterou uma linha. O que se verifica aqui é a contenção e a execução das guardas.