Curated Shared Instructions: O Novo Padrão dos Agents

O Technology Radar Vol. 34 da Thoughtworks colocou Curated shared instructions for software teams em Adopt. Isso parece um detalhe de processo, mas é uma das mudanças mais importantes para times que usam coding agents em 2026.

O recado é simples: depender de cada dev escrevendo prompt do zero virou anti-pattern. Se o time tem padrões de arquitetura, testes, lint, deploy, segurança e review, esses padrões precisam estar em arquivos compartilhados, versionados e embutidos nos templates de serviço.

Em outras palavras: AGENTS.md, CLAUDE.md, .cursorrules, skills e prompts de time deixam de ser truque individual e viram asset de engenharia.

---

Prompt Individual Não Escala

Todo time começa assim. Um dev descobre uma combinação boa de instruções para Claude Code. Outro cria um prompt excelente para revisar PR. Um terceiro monta regras no Cursor. Funciona por alguns dias, mas o conhecimento fica espalhado.

O problema aparece rápido. Dois devs usando o mesmo agente recebem padrões diferentes. Um lembra de pedir testes, outro não. Um protege arquitetura, outro aceita refactor gigante. O agente vira reflexo da maturidade individual de quem está operando.

Isso é aceitável para experimentação. Não é aceitável para produção. Se o time quer usar IA como parte do workflow, precisa tratar instrução como código.

Curated shared instructions resolvem esse ponto: o conhecimento do time fica em lugar previsível, revisável e herdado por novos projetos.

---

Templates De Serviço Como Distribuição

O ponto mais forte do Radar é ancorar instruções diretamente em service templates. Quando um novo serviço nasce, ele já vem com regras para agentes: comandos de setup, testes, arquitetura, convenções, limites e exemplos.

Isso é muito mais poderoso que um prompt library genérico. Prompt library depende da pessoa lembrar de copiar a instrução certa. Template entrega o padrão no repositório desde o dia um.

Para plataforma interna, isso muda bastante. O template deixa de criar apenas pasta, Dockerfile, CI e README. Ele passa a criar também o ambiente cognitivo do agente.

Novo serviço, novo agente orientado corretamente.

---

AGENTS.md Como README Para Agentes

O formato AGENTS.md ganhou tração porque resolve uma lacuna óbvia: README é para humanos. Agentes precisam de outro tipo de contexto.

Um bom AGENTS.md responde perguntas práticas: como instalar dependências, como rodar testes, quais comandos são seguros, quais arquivos são gerados, quais padrões de código seguir e quais áreas exigem cuidado.

Isso reduz o primeiro erro do agente. Em vez de adivinhar se o projeto usa npm, pnpm, poetry, Maven ou Gradle, ele lê a regra local. Em vez de inventar estilo, segue convenção.

O ganho não é mágico. É engenharia básica: reduzir ambiguidade antes da execução.

---

CLAUDE.md, .cursorrules e Skills

Cada ferramenta tem seu próprio jeito de carregar instruções. Claude usa CLAUDE.md. Cursor usa .cursorrules. Codex, Gemini, Copilot e outros agentes convergem em formatos parecidos ou em arquivos de contexto.

O risco é criar múltiplas fontes de verdade. Um arquivo diz uma coisa, outro diz outra, e o agente escolhe o que viu primeiro.

Por isso a estratégia boa é ter um conteúdo canônico e bridges finas para cada ferramenta. O time define regra em um lugar principal e gera adaptações quando necessário.

Skills entram como complemento. Em vez de colocar tudo em um arquivo gigante, você modulariza instruções: revisão, testes, migration, segurança, API, frontend. O agente carrega só o que precisa.

---

O Lado De Segurança

Instrução compartilhada também vira superfície de ataque. Se AGENTS.md, CLAUDE.md ou SKILL.md podem influenciar um agente, então um PR malicioso pode tentar alterar essas instruções.

Relatórios recentes da Cloud Security Alliance alertam para context poisoning e ataques contra arquivos de instrução. Isso muda o processo de review: arquivo de contexto de agente precisa ser tratado como arquivo sensível.

Se alguém altera regra para "ignore testes" ou "envie logs para este endpoint", o impacto pode ser maior do que uma mudança de código pequena.

Minha regra: mudanças em instruções de agente exigem code owner e revisão explícita. Não devem entrar escondidas no meio de PR gigante.

---

Como Implementar No Time

Comece pequeno. Crie um AGENTS.md por repo com setup, comandos de validação, estrutura do projeto e restrições. Não tente escrever constituição de 40 páginas.

Depois mova padrões repetidos para o template de serviço. Todo novo repo já nasce com o mesmo baseline. Isso evita que cada squad reinvente prompt.

Terceiro passo: crie revisão periódica. A cada incidente, bug ou retrabalho, pergunte: faltou instrução? A instrução estava errada? O agente ignorou porque estava confusa?

Curated shared instructions vivem. Elas melhoram conforme o time aprende.

---

O Que Deve Entrar No Primeiro AGENTS.md

Um bom arquivo de instruções compartilhadas não precisa ser grande. Ele precisa ser útil no momento em que o agente está prestes a agir. Se o agente precisa descobrir o comando de teste lendo cinco READMEs, ele já começou mal.

Eu colocaria cinco blocos no primeiro AGENTS.md. Primeiro: visão rápida do projeto, com linguagem, framework, runtime e diretórios principais. Segundo: comandos oficiais de instalação, lint, typecheck, teste e build. Terceiro: regras de escopo, incluindo arquivos gerados, áreas sensíveis e padrões que não devem ser tocados sem motivo. Quarto: critérios de validação por tipo de tarefa. Quinto: formato esperado do resumo final.

Esse último bloco parece detalhe, mas ajuda muito. Se todo agente termina dizendo quais arquivos alterou, quais comandos rodou, quais testes falharam e quais riscos ficaram, o revisor humano ganha tempo. O resumo deixa de ser "pronto" e vira evidência.

Exemplo simples de regra útil: "Mudanças em autenticação exigem teste de autorização e revisão humana. Mudanças em componente visual exigem validação em mobile e desktop. Mudanças em dependência exigem justificativa e changelog." Isso é muito melhor do que "siga boas práticas".

---

Instruções Boas São Específicas

O erro comum é escrever instruções genéricas demais. "Escreva código limpo", "faça testes", "seja cuidadoso" e "siga padrões do projeto" não ajudam tanto quanto parecem. O agente pode concordar com tudo isso e ainda errar.

Instrução boa reduz decisão ambígua. Em vez de "faça testes", diga "para mudança em regra de negócio, adicione ou atualize teste unitário em tests/domain; para mudança em API, rode teste de contrato; para mudança em UI, valide rota real no navegador". Agora o agente sabe o que fazer.

Também vale evitar instrução contraditória. Se um arquivo diz para usar npm e outro diz para usar pnpm, o agente pode escolher qualquer um. Se um padrão manda criar abstração e outro manda evitar abstração, o resultado vira loteria.

Curadoria é isso: não é acumular instruções. É remover ruído, resolver conflito e deixar o caminho certo óbvio.

---

Service Templates Como Produto Interno

Muitos times já têm templates internos para serviços. Eles criam CI, Dockerfile, observabilidade, estrutura de pastas e padrões de deploy. A novidade é tratar instruções para agentes como parte desse template.

Isso faz sentido porque a primeira interação do agente com o serviço acontece cedo. Se o projeto já nasce com AGENTS.md, comandos oficiais e documentação de arquitetura, o agente trabalha no trilho certo desde o primeiro PR.

O template também pode incluir skills específicas. Um serviço backend pode trazer uma skill de API contract. Um frontend pode trazer validação visual. Um serviço de dados pode trazer regra de migração, privacidade e schema evolution.

Essa abordagem reduz variação entre squads. Não elimina autonomia, mas cria baseline. Cada time pode evoluir regras locais, desde que preserve os contratos mínimos de engenharia.

---

Como Manter Sem Virar Documento Morto

Toda documentação corre risco de apodrecer. Instrução para agente apodrece mais rápido, porque ferramenta muda, comando muda e padrão de uso muda. Por isso manutenção precisa estar dentro do ciclo normal de desenvolvimento.

Uma prática boa é criar gatilhos. Se um agente errou por falta de contexto, atualize instrução. Se um review aponta o mesmo problema pela terceira vez, transforme em regra. Se um comando mudou, atualize AGENTS.md no mesmo PR da mudança.

Outra prática útil é revisar instruções em retrospectiva. Pegue três PRs gerados com apoio de agente e pergunte: o agente seguiu o que esperávamos? Onde ele precisou de intervenção? Qual instrução teria evitado retrabalho?

O objetivo não é criar um manual perfeito. É criar um loop de aprendizado. O time aprende com o agente, e o agente passa a herdar esse aprendizado.

---

Relação Com Context Engineering

Curated shared instructions são uma peça de context engineering. Elas controlam o contexto estável: regras, comandos, padrões e limites do projeto. Isso evita que cada conversa precise reexplicar tudo.

Mas elas não substituem contexto dinâmico. Issue, diff, logs, resultado de testes e comentários de review continuam importantes. A arquitetura boa separa os dois tipos de contexto.

Contexto estável fica versionado no repo. Contexto dinâmico vem da tarefa. O agente combina ambos para agir. Quando esses dois mundos se misturam demais, o prompt fica gigante e frágil.

Essa separação também ajuda custo. Se o agente sabe onde buscar instruções, não precisa carregar uma enciclopédia em toda chamada. Ele pode usar disclosure progressivo: começa com regras gerais e carrega detalhes quando a tarefa pede.

---

O Que O Tech Lead Deve Cobrar

Tech lead deve cobrar três coisas. Primeiro: existe uma fonte canônica de instruções? Segundo: novos serviços já nascem com ela? Terceiro: mudanças nessas instruções passam por review adequado?

Também vale cobrar evidência. Um PR feito por agente deve dizer quais instruções seguiu e quais validações rodou. Se o agente não consegue explicar isso, o processo ainda está imaturo.

Outra cobrança importante é segurança. Arquivo de instrução não pode ser alterado sem atenção. Se uma mudança em AGENTS.md entra escondida no meio de um PR grande, o time deve tratar como alerta.

Em times grandes, eu criaria ownership claro. Plataforma pode manter baseline. Squads podem complementar. Segurança revisa regras sensíveis. Arquitetura revisa padrões transversais.

---

Erros Comuns Que Eu Evitaria

O primeiro erro é criar um arquivo enorme. Agente não precisa de romance. Precisa de instrução clara. Arquivo longo demais vira ruído e aumenta chance de conflito.

O segundo erro é copiar template genérico da internet. Cada repo tem comandos, riscos e convenções. Use exemplos externos como ponto de partida, não como verdade.

O terceiro erro é não testar a instrução. Peça para o agente executar uma tarefa pequena e observe onde ele tropeça. A instrução só é boa se muda comportamento.

O quarto erro é deixar cada ferramenta com regra diferente. Se Claude, Cursor, Codex e Copilot recebem instruções divergentes, o time perde previsibilidade. Bridge é útil; duplicação manual é perigosa.

---

Exemplo De Estrutura Inicial

Uma estrutura inicial poderia ser assim: contexto do projeto, comandos, padrões de edição, testes obrigatórios, áreas sensíveis, instruções de segurança e formato de entrega. Isso cabe em uma página bem escrita.

Também vale adicionar links para documentos maiores. O AGENTS.md não precisa conter todo guia de arquitetura. Ele pode apontar para onde buscar. O importante é o agente saber qual documento é fonte de verdade.

Para times com muitos serviços, padronize seções. Se todo repo tem a mesma estrutura de instruções, agentes e humanos encontram informação mais rápido.

Essa previsibilidade é o ganho invisível. Menos tempo perguntando "como funciona esse repo?", mais tempo resolvendo tarefa.

---

Principais Aprendizados

• Prompt individual não escala em times com coding agents.
• Instruções compartilhadas devem ser versionadas como código.
• Service templates são o melhor mecanismo de distribuição.
• AGENTS.md, CLAUDE.md e .cursorrules precisam de fonte canônica.
• Arquivos de instrução viram superfície de segurança e exigem review.

---

Conclusão

Curated shared instructions parecem simples porque são simples. E justamente por isso funcionam. Elas pegam o conhecimento tácito do time e colocam no caminho do agente antes que ele faça besteira.

Para tech leads, essa é uma das práticas de maior ROI em desenvolvimento agêntico. Antes de comprar mais ferramenta, garanta que seus agentes estão lendo as regras certas.

---

Fontes e Referências

• Thoughtworks Radar - Curated shared instructions for software teams
• Thoughtworks Technology Radar Vol. 34 - Techniques
• AGENTS.md
• Cloud Security Alliance - SKILL.md agent context poisoning
• Cloud Security Alliance - README instruction injection