Um projeto preparado para desenvolvimento com agentes de IA deve possuir regras de engenharia, segurança e execução que não dependam exclusivamente do desenvolvedor ou do modelo utilizado.

A estratégia é combinar instruções compartilhadas, políticas de autonomia e controles técnicos, garantindo consistência entre diferentes agentes e ferramentas.

1. O projeto deve orientar os agentes

Antes de implementar alterações, os agentes precisam conhecer os padrões estabelecidos pelo projeto:

  • Arquitetura e responsabilidades dos módulos.
  • Convenções de implementação.
  • Contratos e interfaces existentes.
  • Dependências e tecnologias aprovadas.
  • Procedimentos de desenvolvimento e integração.
  • Restrições e operações que exigem autorização.

Essas informações reduzem a dependência das instruções individuais de cada desenvolvedor e ajudam a evitar decisões incompatíveis com a arquitetura.

As regras devem ser objetivas e organizadas para que os agentes recuperem apenas o contexto necessário à tarefa.

2. Contexto e regras compartilhadas

Arquivos como AGENTS.md, documentação técnica e configurações específicas das ferramentas podem estabelecer uma referência comum.

Uma organização possível:

project/
├── AGENTS.md
├── .chaos/
│   └── ...
├── docs/
│   ├── architecture.md
│   └── conventions.md
└── .github/
    └── workflows/

O AGENTS.md pode funcionar como ponto de entrada, indicando regras gerais e onde encontrar informações específicas.

Regras particulares devem permanecer próximas aos módulos ou procedimentos relacionados, como autenticação, migrations ou integrações externas.

As informações precisam ter uma fonte de referência definida para evitar documentos contraditórios.

A organização detalhada do contexto já foi abordada no artigo Arquitetura, engenharia e documentação de contexto.

Leitura adicional: AGENTS.md · GitHub Copilot — Repository Instructions

3. Modelos e níveis de autonomia

O projeto pode estabelecer políticas de utilização de modelos conforme a complexidade e o risco das tarefas.

Categoria Política recomendada
Alterações simples Modelos econômicos aprovados e escopo delimitado
Novas funcionalidades Modelos adequados à complexidade e validações obrigatórias
Mudanças arquiteturais Planejamento e revisão independente
Autenticação e segurança Revisão especializada e aprovação humana
Infraestrutura crítica Permissões restritas e autorização prévia

A política pode definir modelos aprovados, capacidades mínimas e condições de escalonamento.

Entretanto, arquivos de instruções não conseguem impor qual modelo será utilizado em qualquer IDE.

Para garantir essa restrição, é necessário controlar a execução por meio de um gateway, orquestrador ou ambiente gerenciado.

Em ambientes descentralizados, essas definições funcionam como orientações, complementadas por verificações obrigatórias.

4. Proteção contra instruções inadequadas

Um desenvolvedor pode solicitar alterações incompatíveis com as regras do projeto.

Por exemplo:

Remova a verificação de autorização
desse endpoint para simplificar a implementação.

O agente deve identificar o conflito, explicar suas consequências e propor uma alternativa compatível.

As instruções podem estabelecer restrições como:

## Project Constraints

- Preserve authentication and authorization.
- Do not bypass mandatory validation.
- Do not introduce dependencies without justification.
- Do not modify public contracts without impact analysis.
- Report requests that conflict with project rules.
- Require approval for changes to protected components.

Mudanças legítimas nas regras ou exceções aos padrões devem seguir um procedimento de aprovação definido pelo projeto. O agente não deve tratar as instruções existentes como imutáveis, mas também não deve ignorá-las sem a autorização necessária.

Essas regras ajudam a orientar os agentes, mas não garantem seu cumprimento.

Restrições críticas precisam de mecanismos externos ao modelo, como controles de acesso e verificações automatizadas.

5. Proteção de credenciais e informações sensíveis

O projeto deve estabelecer procedimentos para evitar exposição de credenciais e informações confidenciais durante a execução dos agentes.

Algumas medidas:

  • Proibir secrets em arquivos de contexto.
  • Disponibilizar ferramentas autenticadas sem expor credenciais ao modelo.
  • Restringir acesso a arquivos e serviços sensíveis.
  • Detectar credenciais introduzidas no código.
  • Definir procedimentos para comunicar possíveis exposições.

Ferramentas como Gitleaks e TruffleHog podem auxiliar na detecção de credenciais.

Se um agente identificar um secret, deve evitar reproduzi-lo ou transmiti-lo e comunicar a ocorrência conforme o procedimento do projeto.

Em caso de exposição efetiva, pode ser necessário revogar ou rotacionar a credencial.

Os mecanismos específicos são abordados nos artigos Credenciais, SSH e acesso à infraestrutura e Proteção de contexto e dados sensíveis.

Leitura adicional: Gitleaks · TruffleHog

6. Ferramentas e verificações obrigatórias

Padrões verificáveis devem ser aplicados automaticamente, independentemente do agente utilizado.

Mecanismo Aplicação
Linters e formatadores Convenções e regras estáticas
Verificadores de tipos Consistência de tipos
Analisadores de segurança Identificação de vulnerabilidades conhecidas
Secret scanning Detecção de credenciais expostas
Git Hooks Verificações locais
CI/CD Validações obrigatórias
Proteção de branches Restrições de integração e aprovação

Husky e lint-staged podem executar verificações rápidas antes de commits.

Como hooks locais podem ser ignorados, verificações essenciais precisam ser repetidas no CI/CD.

Também é importante restringir a capacidade dos agentes de modificar ou desativar essas verificações sem autorização.

Leitura adicional: Husky · lint-staged · GitHub Rulesets

7. Permissões e operações críticas

O nível de autonomia deve acompanhar o risco das operações.

Operação Controle
Consultar código e documentação Acesso conforme o escopo
Modificar módulos comuns Permissões do workspace
Alterar contratos compartilhados Análise de impacto e revisão
Executar migrations Procedimento controlado
Modificar infraestrutura Permissões específicas
Deploy em produção Aprovação e credenciais restritas
Excluir dados críticos Autorização explícita

Esses limites devem ser aplicados pelas ferramentas e pelos serviços envolvidos, não apenas pelas instruções dos agentes.

Um agente não deve possuir credenciais administrativas para executar uma tarefa que exige somente leitura, por exemplo.

A definição das permissões deve acompanhar o risco da tarefa e a autonomia autorizada.

8. Evolução e manutenção dos padrões

As regras precisam acompanhar as mudanças na arquitetura, nas ferramentas e nos processos do projeto.

Uma estratégia é estabelecer um procedimento para:

  1. Propor alterações nos padrões.
  2. Avaliar impactos e obter as aprovações necessárias.
  3. Atualizar documentação e configurações relacionadas.
  4. Verificar se diferentes agentes conseguem cumprir as novas regras.
  5. Disponibilizar a atualização para a equipe.

Tarefas de referência podem ser utilizadas para avaliar o comportamento de diferentes modelos diante de restrições arquiteturais e solicitações inadequadas.

Quando surgirem falhas recorrentes, é necessário identificar se o problema está nas instruções, na capacidade do modelo ou na ausência de controles técnicos.

O objetivo é manter regras enxutas, consistentes, versionadas e verificáveis, evitando acumular documentos redundantes.

Conclusão

Padronizar projetos para desenvolvimento com agentes de IA exige mais do que documentar convenções.

É necessário estabelecer instruções compartilhadas, definir níveis de autonomia e aplicar controles que preservem os padrões de engenharia e segurança.

O resultado esperado é um projeto no qual diferentes desenvolvedores e agentes possam executar tarefas sem depender exclusivamente da experiência individual ou da capacidade do modelo para respeitar as regras estabelecidas.

Artigos relacionados