Regras de Agente (.cursorrules / CLAUDE.md / AGENTS.md)

1. Visão geral do conceito e o problema sistêmico

Os LLMs modernos são treinados em gigabytes de código aberto do GitHub, por isso geram, por padrão, um código "mediano": versões majoritárias desatualizadas de bibliotecas, padrões caóticos de importação, uso de any no TypeScript ou abordagens ineficientes para tratamento de erros. Quando um engenheiro trabalha na paradigma de vibe coding sem regras fixas, cada novo prompt se torna uma loteria:

• O agente instala moment.js ou axios desatualizados em vez de usar nativamente date-fns ou fetch.
• O agente mistura camadas arquiteturais (por exemplo, acessa o banco de dados diretamente de um componente React do lado do cliente).
• O agente inventa seus próprios comandos de compilação ou teste em vez de usar os scripts existentes no projeto.

As Agent Rules (arquivos .cursorrules, CLAUDE.md, AGENTS.md, .cursor/rules/*.mdc) resolvem o problema da deriva da base de código. Elas transformam as convenções internas da equipe em um contrato sistêmico, lido pelo ambiente de desenvolvimento ou pelo agente de terminal antes mesmo que qualquer geração de código comece.

2. Taxonomia arquitetural e modelo mental

As regras do repositório dividem-se em três níveis de isolamento e ativação:

┌─────────────────────────────────────────────────────────────┐
│                   NÍVEIS DE REGRAS DO AGENTE                │
├─────────────────────────────────────────────────────────────┤
│ 1. Camada Global / Máquina (~/.cursorrules, ~/.claude.json)   │
│    Preferências do desenvolvedor específico (idioma, estilo   │
│    de resposta)                                              │
├─────────────────────────────────────────────────────────────┤
│ 2. Camada Central do Repositório (CLAUDE.md, AGENTS.md,      │
│    regras raiz)                                              │
│    Stack global, bibliotecas proibidas, comandos lint / test │
├─────────────────────────────────────────────────────────────┤
│ 3. Regras Escopadas / Orientadas a Eventos                    │
│    (.cursor/rules/*.mdc)                                     │
│    Ativação por padrão glob (ex.: rotas de API, UI, DB)      │
└─────────────────────────────────────────────────────────────┘

1. Regras Globais do Repositório (Core Repository Contract):
   • Localizam-se na raiz do projeto (CLAUDE.md para Claude Code, AGENTS.md ou .cursorrules para editores).
   • Descrevem o mínimo crítico: versões do ambiente (Node.js 22, Bun, Python 3.12), gerenciador de pacotes (pnpm), linter obrigatório e instruções sobre a estrutura dos commits.
2. Regras Contextuais de Módulos (Scoped Domain Rules):
   • Arquivos com metadados e glob patterns (por exemplo, .cursor/rules/database.mdc com filtro src/db/**/*.ts).
   • São carregadas na memória de trabalho do modelo apenas quando o agente planeja editar arquivos de migração ou modelos ORM.
3. Restrições Operacionais (Operational Guardrails):
   • Restrições negativas claras (Negative Constraints): "NUNCA execute git push --force", "NUNCA modifique .env.production", "NÃO adicione novas dependências sem o consentimento explícito do engenheiro".

3. Pipeline técnico e mecânica interna

O ciclo de vida das regras durante uma sessão de vibe coding:

1. Inicialização da sessão e varredura do repositório: A IDE ou o agente CLI, ao iniciar, escaneia a pasta raiz e os diretórios de serviço .cursor/rules/ ou .agents/rules/.
2. Análise de intenção e correspondência de máscaras (Glob Matching): O usuário envia uma solicitação ("Crie um novo endpoint para pagamento de assinatura"). O agente prevê alterações nos arquivos em src/app/api/stripe/route.ts. O motor de regras ativa as regras para src/app/api/**/*.ts e stripe.mdc.
3. Montagem do system prompt estendido: O motor concatena:
   • O System Prompt base do modelo;
   • O conteúdo do arquivo de contrato global;
   • As regras modulares encontradas;
   • A árvore atual dos arquivos abertos e a solicitação do usuário.
4. Geração de código com conformidade forçada de invariantes: O modelo formula a chamada de ferramenta ou o código, tratando as regras como contexto sistêmico obrigatório.
5. Validação pós-geração: Se o agente tiver acesso ao terminal, ele executa o comando de validação especificado nas regras (por exemplo, pnpm typecheck) antes de retornar o relatório final ao engenheiro.

4. Cenários práticos de engenharia em produção

01. Fronteiras arquiteturais no Next.js 15+ App Router

O arquivo .cursor/rules/nextjs.mdc com máscara src/app/**/*.tsx previne erros clássicos no uso de componentes server-side e client-side:

---
description: Padrões de arquitetura do Next.js App Router
globs: src/app/**/*.tsx, src/components/**/*.tsx
---
- Por padrão, todos os componentes são Server Components.
- A diretiva 'use client' deve ser adicionada APENAS se houver useState, useEffect ou manipuladores de eventos onClick/onChange.
- É PROIBIDO importar utilitários do servidor (db, segredo de autenticação) em arquivos com 'use client'.
- Todas as mutações de dados devem ser executadas exclusivamente através de Server Actions no diretório `src/actions/`.

02. Execução determinística de testes para Claude Code

A configuração CLAUDE.md garante que o agente de terminal use exclusivamente os scripts de teste corretos, sem tentar executar um jest global incompatível:

# Diretrizes do Repositório para Claude Code

## Comandos
- Build: `pnpm build`
- Verificação de tipos: `pnpm tsc --noEmit`
- Testes unitários: `pnpm test:unit`
- Testes E2E: `pnpm test:e2e`

## Disciplina de Fluxo de Trabalho
Antes de notificar sobre a conclusão bem-sucedida da tarefa:
1. Execute `pnpm tsc --noEmit`. Se houver erros de tipagem, corrija-os.
2. Execute `pnpm test:unit` para os módulos modificados.
3. Não crie novos arquivos sem antes verificar se já existem utilitários correspondentes em `src/lib/`.

03. Segurança de tipos forçada e validação Zod na API

A regra para o backend impede o uso de payloads JSON não tipados nos controladores:

---
description: Padronização de endpoints do backend
globs: src/server/api/**/*.ts
---
- Todos os argumentos de entrada das requisições devem ser validados por meio de esquemas Zod (`schema.parseAsync(req.body)`).
- O tipo `any` é estritamente proibido; ao trabalhar com dados desconhecidos, utilize `unknown` seguido de narrowing de tipo.
- Em caso de erros de negócio, lance um `TRPCError` tipado ou um `HttpError` com o código de status apropriado.

5. Armadilhas, erros comuns e segurança

• Inchaço de Regras (Rule Bloat & Attention Saturation): Tentar colocar toda a documentação do projeto no arquivo de regras resulta em arquivos com mais de 500 linhas. Isso dilui a atenção do modelo ("Lost in the Middle") e faz com que ele ignore diretrizes cruciais. Divida as regras em escopos modulares.
• Regras conflitantes ou contraditórias: Se o CLAUDE.md global exigir o uso de pnpm, mas um README.md antigo ou uma regra local contiver npm install, o modelo pode entrar em loop alucinando sobre o gerenciador de pacotes.
• Risco de vazamento de dados sensíveis: Nunca inclua tokens de acesso, senhas de bancos de teste ou chaves pessoais de API nas regras do repositório. Todas as variáveis de ambiente devem ser descritas apenas como nomes abstratos (por exemplo, DATABASE_URL is required in .env.local).
• Ausência de versionamento: As regras dos agentes devem evoluir junto com a base de código no sistema de controle de versão Git. Mudanças no stack tecnológico devem ser acompanhadas por uma atualização atômica dos arquivos de regras relevantes no mesmo commit.