Oi, como você está? Eu sou Lena. Alguns meses atrás, eu estava assistindo um agente percorrer um código e ele simplesmente… continuava. Sem pausa, sem checagem. Ele reescreveu três arquivos que eu não tinha pedido, e então, de forma prestativa, sugeriu que poderia fazer o mesmo com mais quatro. O código não estava errado, exatamente. Mas também não estava certo da maneira que eu precisava.

Foi então que comecei a prestar mais atenção em como esses agentes são realmente restritos — não sobre se eles podem fazer algo, mas sobre como você lhes diz o que eles devem fazer. E, mais importante, o que você lhes diz para nunca fazer sem perguntar antes.

É isso que as pessoas querem dizer quando falam sobre "superpoderes" em fluxos de trabalho de agentes. É uma palavra um pouco enganosa. O superpoder não é capacidade pura. É a habilidade de moldar como essa capacidade é usada — de forma consistente, repetível, em cada sessão que o agente executa.

O Que "Superpoderes" Realmente Significa em Fluxos de Trabalho de Agentes

Não são funcionalidades — sistemas de restrição de comportamento

Continuo vendo a palavra "superpoderes" usada para descrever funcionalidades: execução de código, pesquisa na web, acesso a ferramentas. Essa é uma interpretação. Mas, quando observo pessoas que realmente utilizam agentes em produção, a conversa quase sempre é sobre outra coisa.

Trata-se de sistemas de restrição.

A questão não é "o que este agente pode fazer?". A questão é "como eu faço para impedir que ele faça algo que eu não queria, enquanto ainda permito que ele faça o que eu queria?". Isso é um problema de governança. E governança requer regras que são aplicadas de forma consistente — não lembretes que você cola em um prompt na esperança de que sejam seguidos.

Por que os agentes precisam de regras, não apenas de ferramentas

Aqui está algo que percebi bem cedo: agentes sem restrições comportamentais não são ruins, eles são imprevisíveis. Eles vão acertar a resposta metade das vezes e, na outra metade, fazer algo completamente inesperado — não porque o modelo esteja quebrado, mas porque não há nada ancorando o comportamento aos seus padrões.

Ferramentas dão alcance a um agente. Restrições dão direção a um agente.

A maioria das equipes tropeça nessa distinção por acidente. Elas adicionam ferramentas, observam o agente em ação, se surpreendem com algo que ele decidiu por conta própria, e então começam a escrever regras. O modo de falha ensina qual deveria ter sido a restrição.

Como os Superpoderes Funcionam em Principais Ferramentas

Claude Code — habilidades, CLAUDE.md e escopo de permissões

Claude Code tem o que eu considero a abordagem mais estruturada para esse problema. O mecanismo principal é o arquivo SKILL.md — um arquivo markdown com frontmatter em YAML que agrupa instruções, scripts e referências em algo que Claude pode carregar dinamicamente quando for relevante.

O que acho realmente interessante nesse design é o que a Anthropic chama de "divulgação progressiva". Quando uma sessão começa, Claude carrega apenas o nome e a descrição de cada habilidade instalada — não o conteúdo completo. As instruções completas só são carregadas quando Claude determina que a habilidade é relevante para a tarefa atual. Como descreve a documentação oficial de habilidades do agente: a habilidade é como um guia de integração para um novo funcionário, e o agente lê apenas os capítulos de que precisa.

Há também o CLAUDE.md — um arquivo persistente que vive na raiz do seu projeto e carrega instruções permanentes durante toda a sessão. Diferente das habilidades, ele está sempre presente. Pense nele como o contrato base: suas decisões de arquitetura, suas convenções de arquivos, as coisas que você nunca quer que o agente assuma ou pule.

O escopo de permissões funciona no nível da ferramenta. Você define o allowed-tools no frontmatter em YAML da habilidade para restringir quais comandos bash, operações de arquivo ou APIs a habilidade pode invocar. Esse detalhe levou um tempo para eu apreciar plenamente. Não se trata apenas do que o agente sabe — é sobre o que o agente tem permissão para acessar.

Uma coisa sobre a qual ainda não tenho certeza completa: quão bem essas restrições se mantêm depois que uma sessão fica longa e a janela de contexto começa a se comprimir. Os docs do Claude Code mencionam que a auto-compação carrega as habilidades invocadas para frente, mas habilidades mais antigas podem ser descartadas se você carregou muitas em uma sessão. Notei desvios de comportamento que podem estar relacionados a isso. Talvez eu esteja lendo demais nisso, mas não parece aleatório.

Cursor — regras, .cursorrules e o formato MDC

O Cursor adota uma abordagem em camadas. Você tem três níveis: Regras do Usuário (globais, aplicam-se a tudo), Regras do Projeto (versionadas, vivem em .cursor/rules/), e o mais antigo arquivo .cursorrules na raiz do projeto. O formato .cursorrules ainda funciona desde o início de 2026, mas a documentação oficial do Cursor deixa claro que está obsoleta — o caminho recomendado é migrar para o sistema de regras de projeto .mdc para melhor escopo e controle.

O formato MDC adiciona uma camada de metadados que .cursorrules não possui: você pode definir se uma regra é alwaysApply, vinculada a globos de arquivo específicos ou só carregada quando o agente determinar que é relevante. Essa última opção — regras solicitadas pelo agente — é mais interessante do que parece. Isso significa que o sistema de regras pode ser sensível ao contexto: regras frontend não carregam para arquivos backend, restrições de serviços de pagamento não se misturam a módulos não relacionados.

O que descobri quando passei um tempo com isso: as regras que funcionam melhor são específicas e imperativas, não vagas e aspiracionais. "Use TypeScript para todos os arquivos novos" é válido. "Escrever código limpo e mantido" não faz nada. Quanto mais precisamente você descreve o que quer — ou o que explicitamente não quer — mais consistentemente o agente segue isso.

Agora também existe AGENTS.md no Cursor, que é uma alternativa simples para descontos para projetos que não precisam de toda a sobrecarga de metadados. Mais simples, um pouco menos flexível.

! [imagem] (https://cdn.10b.ai/1776238760917-2.png)

Codex CLI — Descoberta de instruções AGENTS.md e em camadas

A CLI do Codex da OpenAI tem uma hierarquia de instruções limpa que acho que vale a pena entender. Quando uma sessão começa, o Codex constrói o que sua documentação chama de "cadeia de instruções" — ele lê do seu ~/.codex/AGENTS.md global, depois desce da raiz do projeto até seu diretório atual, pegando quaisquer arquivos AGENTS.md encontrados pelo caminho. Arquivos mais próximos do seu diretório atual sobrepõem orientações anteriores.

De acordo com a documentação de instruções personalizadas do Codex, você também pode colocar arquivos AGENTS.override.md em qualquer nível para tornar explícita a intenção de sobreposição. Para equipes com monorepos ou serviços com requisitos muito diferentes — a equipe de pagamentos, por exemplo, versus a equipe de análise — isso significa que você pode ter regras de linha de base compartilhadas e restrições específicas de serviço que nunca se misturam acidentalmente.

O Codex também adotou recentemente o mesmo padrão de SKILL.md. A documentação de habilidades do Codex descreve a mesma abordagem progressiva de divulgação: metadados da habilidade carregam primeiro, instruções completas somente quando a habilidade é invocada. O ecossistema está convergindo para uma linguagem de design compartilhada aqui, mesmo entre diferentes provedores.

Aprovações rigorosas e permissões de sandbox estritas são o padrão correto — afrouxe-as apenas para fluxos de trabalho específicos onde você entende o raio da explosão.

! [imagem] (https://cdn.10b.ai/1776238762264-3.png)

O Padrão: GitFlow + TDD + Revisão de Código, Automatizado

Brainstorming → planos de escrita → execução de planos

Este é o padrão de fluxo de trabalho ao qual continuo voltando. A estrutura: quebrar uma tarefa de agente em fases distintas, com uma habilidade diferente governando cada fase.

Uma habilidade de brainstorming abre o espaço do problema, gera opções, destaca casos extremos. Nenhum código é escrito. Então, uma habilidade de planejamento assume — plano estruturado, arquivos a serem tocados, testes a serem escritos primeiro. Só depois que um plano existe é que uma habilidade de execução começa a fazer mudanças reais.

Isso espelha GitFlow + TDD + revisão de código — exceto que o agente desempenha os três papéis, com um perfil comportamental diferente para cada um. A habilidade de brainstorming pode especular. A habilidade de execução é limitada a seguir o plano aprovado.

Por que isso reduz falhas: cada fase tem um critério de sucesso mais estreito. Um agente que está "fazendo brainstorming" não escreve acidentalmente código de produção. Um agente que está "executando" não redesenha a arquitetura no meio da implementação.

Comecei a usar esse padrão depois de assistir a um agente passar quarenta minutos em círculos em um refatoramento porque continuava reavaliando suas próprias decisões. Separar as fases não tornou o agente mais inteligente. Tornou o processo mais estável.

Restrições vs Governança

Regras de comportamento local vs ciclo de vida da capacidade em nível de rede

Aqui está o gap que continuo notando, e honestamente ainda não sei como interpretá-lo.

Todos os sistemas de restrição que descrevi acima são limitados à sessão. Eles são locais — vivem em arquivos, são carregados no início da sessão, e se resetam quando a sessão termina. São excelentes para definir comportamento para uma base de código conhecida, uma equipe conhecida, um conjunto de padrões conhecido.

Mas eles não resolvem uma classe diferente de problema: o que acontece com o comportamento de um agente ao longo de todo o seu ciclo de vida? Como saber se uma restrição válida três meses atrás ainda se aplica depois que o modelo subjacente melhorou? Como propagar padrões de comportamento verificados em agentes que não compartilham uma base de código?

Restrições baseadas em arquivos não têm respostas para essas perguntas. Elas não foram projetadas para isso. É aqui que a governança — e não apenas regras — começa a importar. Restrições locais são o primeiro passo. Mas governança significa rastrear se as restrições ainda estão funcionando e ter um mecanismo para propagar atualizações através de uma rede de agentes, em vez de um projeto por vez.

Ainda estou descobrindo como isso se parece na prática.

O que acontece quando as restrições não são suficientes

Uma restrição diz a um agente como se comportar. Ela não diz se o agente se comportou corretamente depois do fato. Esses são problemas diferentes.

O modo de falha que vejo com mais frequência não é um agente que ignora suas regras. É um agente que segue suas regras perfeitamente — em um contexto para o qual as regras não foram escritas. As regras estavam corretas; as regras simplesmente não cobriam a nova situação.

Limites e Compromissos

Deriva de restrição — regras que ficam obsoletas

Regras ficam obsoletas. Uma regra que estava exatamente certa há seis meses pode estar um pouco errada agora — os padrões do modelo mudaram, a base de código mudou, ou o padrão citado pela regra foi atualizado a montante.

Nenhum arquivo de regras se mantém sozinho. Os sistemas de restrições do Claude Code, Cursor e Codex compartilham o mesmo ponto cego: não há mecanismo para detectar que uma regra se tornou desatualizada. Ela simplesmente para de funcionar como esperado. A documentação do Cursor e vários praticantes recomendam auditorias periódicas das regras — não porque as regras sejam frágeis, mas porque o ambiente ao redor delas continua mudando.

Sem persistência — restrições são redefinidas a cada sessão

Este é o ponto ao qual volto sempre.

Cada sessão começa limpa. O CLAUDE.md é relido. O AGENTS.md é relido. Habilidades são redescobertas. O agente não tem memória do que funcionou da última vez, de onde estão os modos de falha sutis, ou do que você aprendeu ao longo de três semanas de depuração.

Você pode codificar esse aprendizado em seus arquivos de regras — e deve. Mas codificá-lo é manual. O sistema de restrições não aprende. Você aprende, então escreve o que aprendeu, e então o sistema de restrições reflete isso.

Essa é uma limitação real. Não tenho certeza se pode ser corrigida dentro da arquitetura atual. Mas vale a pena ser claro sobre isso.

FAQ

O que são superpoderes em fluxos de trabalho de agentes de IA?

Não possui — sistemas de restrições. A capacidade de definir regras de comportamento consistentes, escopos de permissões e instruções específicas de fase que o agente segue em cada sessão.
Como definir restrições de comportamento no Claude Code?

Através dos arquivos SKILL.md (frontmatter YAML + instruções em markdown, armazenados em .claude/skills/) e um arquivo CLAUDE.md para instruções permanentes. Permissões em nível de ferramenta vão no campo allowed-tools. O repositório do GitHub com as habilidades oficiais da Anthropic tem exemplos reais.
Qual a diferença entre .cursorrules e CLAUDE.md?

Eles são para ferramentas diferentes. .cursorrules (obsoleto em favor do .cursor/rules/*.mdc) é o formato do Cursor; CLAUDE.md é o arquivo de instruções persistentes do Claude Code. Ambos carregam regras permanentes durante uma sessão, mas os mecanismos de abrangência são diferentes.

As restrições do agente podem persistir entre sessões?

Não nativamente. Os arquivos de regras são relidos no início da sessão. O agente não tem memória de sessões anteriores. Você codifica o comportamento aprendido nesses arquivos manualmente — o que é a abordagem correta — mas o próprio sistema de restrições não acumula experiência.
Qual é o padrão de habilidade brainstorming-escrita-execução?

Um fluxo de trabalho onde habilidades diferentes governam fases diferentes: brainstorming abre o espaço do problema sem escrever código; planejamento produz uma proposta estruturada; execução implementa de acordo com o plano aprovado. Cada fase tem critérios de sucesso mais restritos, o que reduz repetição e mudanças na arquitetura durante a implementação.

Provavelmente continuarei observando como isso evolui. Os sistemas de restrição estão ficando mais sofisticados, e a convergência entre ferramentas para SKILL.md como formato compartilhado é algo que quero acompanhar mais de perto. Mas a limitação no escopo da sessão parece um teto que nenhuma das ferramentas atuais descobriu como elevar. Algo está acontecendo aqui — eu só não vejo completamente ainda.

Superpoderes do Agente: Restrições de Comportamento Que Funcionam