Claude Code / Codex
Coleção de Prompts e Modelos de Instruções

Leia o arquivo de instruções que você (este agente) carrega (CLAUDE.md / AGENTS.md, etc.),
aponte os pontos fracos que os agentes de IA tendem a ignorar e, em seguida, reescreva-o
em um formato eficaz.

Pontos a observar:
- Transforme expressões vagas em imperativos (sempre faça X / nunca faça Y)
- Adicione uma \'definição de pronto\' e etapas de verificação (executar lint / test)
- Torne as proibições concretas até o alvo (nomes de diretórios, nomes de comandos)
- Se estiver longo demais, reduza para apenas o núcleo que você quer impor

Primeiro liste os pontos fracos em tópicos, depois produza a versão reescrita
completa e aplique-a a esse arquivo de instruções.

Depois de identificar os comandos reais de build / test / lint deste repositório,
adicione uma seção \'Definição de Pronto\' ao arquivo de instruções que você carrega
(CLAUDE.md / AGENTS.md, etc.).

Requisitos:
- Faça uma checklist no formato \'não reporte pronto até que tudo a seguir seja atendido\'
- Declare explicitamente os comandos reais de lint e test
- Inclua: não deixar nenhum TODO ou log de depuração nos arquivos alterados, e reler o seu próprio diff

Não quebre o conteúdo existente; apenas adicione a seção.

Detecte automaticamente a linguagem e o framework deste repositório e adicione as
regras de boas práticas correspondentes ao arquivo de instruções que você carrega
(CLAUDE.md / AGENTS.md, etc.).

Exemplos:
- Next.js: limite Server/Client (o padrão é Server, mantenha use client ao mínimo)
- Laravel: validação via Form Requests, convenções de migração
- Python: anotações de tipo, nunca sobrescrever ou fabricar dados brutos

Adicione uma nota de uma linha sobre a base da sua detecção (de quais arquivos você concluiu)
antes de anexar. Não duplique nada que já esteja escrito.

Adicione as seguintes \'regras absolutas\' ao arquivo de instruções que você carrega
(CLAUDE.md / AGENTS.md, etc.), sob medida para a configuração deste repositório.

- Nunca commitar segredos, .env ou credenciais
- Nunca fazer push / force-push a menos que seja instruído
- Validar a entrada no limite / nunca afrouxar a autenticação ou autorização por conta própria
- Nunca executar comandos destrutivos (DROP / TRUNCATE / migrate:fresh, etc.) no banco de dados de produção
- Sempre que você mudar o comportamento, sempre adicione ou atualize testes

Se regras semelhantes já existirem, não as duplique; apenas preencha o que estiver faltando.

Converta o conteúdo deste `CLAUDE.md` para o formato `AGENTS.md` do
OpenAI Codex e escreva-o.

- Mantenha o significado, mas reorganize em uma estrutura fácil de ler para o Codex
  (títulos, tópicos)
- Mantenha os comandos, as regras absolutas e a definição de pronto como estão
- Produza-o como `AGENTS.md` na raiz

Converta o conteúdo deste `CLAUDE.md` para o formato Project Rules do Cursor
(arquivos `.mdc` em `.cursor/rules/`).

- Divida as regras em unidades significativas
- Separe as regras que devem sempre ser aplicadas das regras que se aplicam
  apenas a tipos de arquivo específicos
- Defina as condições de aplicação apropriadas (globs, etc.) no topo de cada arquivo

Inspecione a estrutura deste monorepo e crie os arquivos de instruções que você
(este agente) carrega (o Claude Code usa CLAUDE.md, o Codex usa AGENTS.md, etc.),
divididos da seguinte forma.

- Na raiz: regras comuns a todo o repositório
  (convenções de commit, proteção de segredos, a definição de pronto geral)
- Em cada diretório de pacote/app: apenas as regras e comandos específicos daquela stack

Evite duplicação e adicione uma nota de uma linha em cada pacote dizendo \'siga as
regras comuns na raiz\'. Ao final, reporte uma lista do que você colocou em qual diretório.

# Projeto: <name>

## O que é isto
Uma visão geral do app em um parágrafo. O que ele faz, quem o usa e a stack de
tecnologia (linguagem, framework, DB, runtime).

## Comandos
- Servidor de desenvolvimento: `npm run dev`
- Build:      `npm run build`
- Test:       `npm test`
- Lint:       `npm run lint`

## Convenções
- A linguagem é TypeScript (strict). Não use `any`.
- Siga o estilo do arquivo que você está editando no momento. Sempre passe pelo Lint antes de terminar.
- Mantenha as mudanças mínimas; não toque em linhas não relacionadas (sem reformatação não relacionada).

## Regras absolutas (estritamente impostas)
- Antes de reportar pronto, sempre execute os testes e o Lint acima e faça-os passar.
- Nunca, jamais, commite segredos, .env ou artefatos de build.
- Prefira editar arquivos existentes a criar novos.
- Quando os requisitos forem vagos, faça exatamente uma pergunta de esclarecimento antes de uma mudança grande.

## Fora dos limites (a menos que seja instruído o contrário)
- Configuração de CI, versões de dependências, configuração de infraestrutura.

# <name>

- Stack: <ex.: Next.js + TypeScript + PostgreSQL>
- Sempre execute antes de terminar: `npm run lint` e `npm test` (ambos devem passar)
- Siga o estilo existente. Não reformate linhas não relacionadas.
- Não commite segredos ou .env. Não faça push até ser instruído.
- Quando estiver vago, não adivinhe; faça exatamente uma pergunta.

# Next.js (App Router) + TypeScript

## Stack
Next.js (App Router), TypeScript strict, Tailwind CSS, <your-ORM>

## Comandos
- Dev:   `npm run dev`
- Build: `npm run build`   # deve passar sem erros de tipo
- Lint:  `npm run lint`
- Test:  `npm test`

## Regras de arquitetura
- Use Server Components por padrão. Adicione "use client" apenas quando state, effects ou
  APIs do navegador forem necessários. Mantenha os Client Components pequenos e nas folhas.
- Busque dados em Server Components ou Route Handlers.
  Não busque os dados iniciais em useEffect.
- Co-localize os componentes com o respectivo segmento de rota. A UI compartilhada vai em `components/`.
- Sempre valide o esquema da entrada externa no limite (por exemplo, Zod).

## Convenções
- Sem `any`. Dê tipos de retorno explícitos às funções públicas.
- Use os design tokens / classes do Tailwind existentes. Não adicione cores por conta própria.
- Mantenha o `page.tsx` enxuto; empurre a lógica para funções e componentes.

## Definição de pronto
`npm run build`, `npm run lint` e `npm test` passam todos com código de saída 0.
Sem `any`, sem exports não utilizados, sem console.log esquecido.

# React (Vite) + TypeScript

## Comandos
- Dev:   `npm run dev`
- Build: `npm run build`
- Lint:  `npm run lint`
- Test:  `npm test` (Vitest + Testing Library)

## Regras
- Apenas componentes de função e Hooks. Não use componentes de classe.
- Mantenha o estado ao mínimo, na ordem "local -> Context -> biblioteca de estado".
  Não eleve o estado para o global desnecessariamente.
- Confine efeitos colaterais ao useEffect e escreva o array de dependências corretamente.
- Separe a UI da lógica. Agrupe a busca de dados em hooks dedicados (useXxx).
- Acessibilidade: dê aos elementos interativos papéis apropriados e operação por teclado.

## Convenções
- Sem `any`. Defina props com tipos.
- Siga o estilo dos componentes e estilos existentes.

## Definição de pronto
`npm run build`, `npm run lint` e `npm test` passam com código de saída 0.

# API Node.js (Express / Hono) + TypeScript

## Comandos
- Dev:   `npm run dev`
- Build: `npm run build`
- Test:  `npm test`
- Lint:  `npm run lint`

## Regras
- Valide o esquema de toda a entrada (body, query, params, headers) no limite.
- Não engula erros. Retorne-os tipados por meio de um manipulador de erros central.
- Leia segredos a partir de variáveis de ambiente. Não os escreva fixos no código.
- Separe o acesso ao DB em camadas (route -> service -> repository).
- Retorne um formato JSON consistente (unifique os formatos de sucesso e falha).

## Regras absolutas
- Não pule nem afrouxe a lógica de autenticação / autorização por conta própria.
- Sempre verifique a autorização ao adicionar um endpoint exposto publicamente.
- Não registre informações pessoais, tokens ou senhas nos logs.

## Definição de pronto
`npm test` (caminho feliz + casos de erro) e `npm run lint` passam.

# Laravel + PHP

## Comandos
- Serve:   `php artisan serve`
- Migrate: `php artisan migrate`
- Test:    `php artisan test`
- Format:  `./vendor/bin/pint`   # execute antes de terminar

## Convenções (siga o jeito Laravel)
- Use relações do Eloquent. Evite SQL bruto sem um motivo claro.
- Valide a entrada em classes Form Request. Não faça isso dentro dos controllers.
- Mantenha os controllers enxutos. Empurre a lógica de negócio para Services / Actions.
- Toda mudança de esquema gera uma nova migração. Não edite as já executadas.
- Use rotas nomeadas e route model binding.

## Regras absolutas
- Nunca, jamais, commite `.env` ou credenciais reais.
- Não execute comandos destrutivos como `migrate:fresh` no banco de dados de produção.
- Sempre que você mudar o comportamento, sempre adicione ou atualize testes (`php artisan test`).

## Definição de pronto
Tanto `php artisan test` quanto `./vendor/bin/pint --test` passam.

# Python / análise de dados

## Ambiente
- Use o venv do projeto `.venv`. Não instale globalmente.
- Instalar: `pip install -r requirements.txt`
- Executar: `python -m src.main`
- Test: `pytest`
- Format: `ruff check .` e `ruff format .`

## Convenções
- Adicione anotações de tipo a toda assinatura de função. Execute `mypy src` se configurado.
- Não coloque lógica em notebooks. Código reutilizável vai em `src/`.
- Fixe a seed em qualquer coisa que use aleatoriedade, para que os resultados sejam reprodutíveis.

## Regras absolutas de dados (mais importantes)
- Não preencha em silêncio nem fabrique valores ausentes. Se houver valores
  ausentes, reporte-os e confirme como tratá-los.
- Não sobrescreva arquivos de dados brutos. Escreva a saída em `data/processed/`.
- Documente todas as premissas (filtros, linhas excluídas, unidades) em comentários no código.

## Definição de pronto
`pytest` passa, `ruff check .` está limpo e os resultados se reproduzem a partir de um estado limpo.

# Go

## Comandos
- Build:  `go build ./...`
- Test:   `go test ./...`
- Format: `gofmt -w .` e `go vet ./...`

## Convenções
- Não engula erros. Sempre trate-os com `if err != nil` e retorne-os
  com contexto (`fmt.Errorf("...: %w", err)`).
- Mantenha o aninhamento raso com early returns.
- Use concorrência apenas quando necessário. Cuidado com vazamentos de goroutine e corridas
  (faça `go test -race` passar).
- Comente os símbolos exportados. Prefira a biblioteca padrão.

## Regras absolutas
- Não adicione abstrações ou interfaces desnecessárias (crie-as quando forem necessárias).
- Antes de adicionar uma dependência, verifique primeiro se a biblioteca padrão é suficiente.

## Definição de pronto
`go build ./...`, `go vet ./...` e `go test -race ./...` passam todos.

# Rust

## Comandos
- Build:  `cargo build`
- Test:   `cargo test`
- Lint:   `cargo clippy -- -D warnings`
- Format: `cargo fmt`

## Convenções
- Não use `unwrap()` / `expect()` de forma descuidada em código de produção.
  Trate `Result` / `Option` corretamente com `?` ou match.
- `unsafe` é proibido em princípio. Se for realmente necessário, declare o motivo em um comentário.
- Siga o compilador quanto a borrowing e lifetimes. Repense o design antes de
  escapar com `clone()`.
- Torne os tipos de erro significativos com `thiserror` / `anyhow`, etc.

## Definição de pronto
`cargo build` e `cargo test` passam, e
`cargo clippy -- -D warnings` reporta zero avisos.

# Ruby on Rails

## Comandos
- Serve:   `bin/rails server`
- Migrate: `bin/rails db:migrate`
- Test:    `bin/rails test` (ou `bundle exec rspec`)
- Format:  `bundle exec rubocop -A`

## Convenções (siga o jeito Rails)
- Respeite \'convenção sobre configuração\'; não invente a sua própria estrutura.
- Evite controllers / models inchados. Empurre a lógica para Services / Concerns.
- Restrinja a entrada com strong parameters.
- Evite N+1 (use `includes`).
- Mudanças de esquema geram uma nova migração. Não edite as já executadas.

## Regras absolutas
- Nunca, jamais, commite `.env` ou credenciais.
- Não execute comandos destrutivos no banco de dados de produção.
- Quando você mudar o comportamento, adicione ou atualize testes.

## Definição de pronto
Os testes e `bundle exec rubocop` passam.

# SQL / migrações de banco de dados

## Regras absolutas (a proteção dos dados vem primeiro)
- Não execute operações destrutivas nos dados de produção por conta própria
  (DROP / TRUNCATE / DELETE ou UPDATE sem condição).
- As migrações devem fornecer um procedimento de rollback, não apenas a direção de avanço.
- Não edite migrações já executadas. Sempre adicione novas.
- Exclua ou renomeie colunas em etapas ("adicionar -> migrar -> aposentar"); não faça de uma só vez.

## Convenções de consulta
- Evite `SELECT *`; especifique as colunas de que você precisa.
- Confirme que as condições de WHERE / JOIN podem usar um índice.
- Divida atualizações grandes em lotes para manter o tempo de lock curto.
- Para consultas de verificação destrutivas, primeiro confirme a contagem afetada com um `SELECT` antes de executar.

## Definição de pronto
Tanto a aplicação quanto o rollback têm sucesso em um ambiente equivalente ao de staging, e você
confirmou que não há mudanças não intencionais nos dados existentes.

# Abordagem orientada a testes

Ao mudar o comportamento, siga este laço todas as vezes:
1. Escreva primeiro um \'teste que falha\' que expresse o comportamento desejado.
2. Execute o teste e confirme que ele falha pelo motivo certo.
3. Escreva o mínimo de código necessário para fazer o teste passar.
4. Execute a suíte de testes completa e confirme que tudo está verde.
5. Refatore mantendo tudo verde.

## Regras absolutas
- Não exclua nem pule testes para fazer a suíte passar.
- Não enfraqueça asserções para deixar tudo verde.
- Se um teste realmente estiver errado, explique por quê antes de alterá-lo.
- Código novo sem testes não está \'pronto\'.

## Definição de pronto
A suíte completa passa, a cobertura não caiu e reverter a
implementação faz o novo teste falhar (ou seja, é um teste significativo).

# Abordagem de depuração

Prossiga nesta ordem. Não corrija por adivinhação:
1. Estabeleça os passos de reprodução (como disparar o bug).
2. Escreva o comportamento esperado e o comportamento real, uma frase cada.
3. Formule uma hipótese. Verifique-a com logs ou uma reprodução mínima antes de corrigir.
4. Depois de identificar a causa, aplique a correção mínima.
5. Após corrigir, confirme que o bug sumiu pelos passos de reprodução e que os testes existentes passam.
6. Se possível, adicione um teste de regressão que capture este bug.

## Regras absolutas
- Não mude vários lugares ao mesmo tempo enquanto a causa for desconhecida.
- Não pare em \'funciona por enquanto\'. Explique por que foi corrigido.
- Não misture refatoração não relacionada à depuração.

# Abordagem de refatoração

## Princípio central
Não mude o comportamento observável externamente. Não mude as saídas nem os efeitos
colaterais para nenhuma entrada que seja.

## Etapas
1. Confirme primeiro que existem testes para a área alvo e que estão verdes.
   Se não houver, escreva primeiro testes de caracterização que fixem o comportamento atual.
2. Mude em etapas pequenas e únicas, executando os testes após cada etapa.
3. Mantenha um commit = um tipo de melhoria.

## Regras absolutas
- Não misture adições de funcionalidades ou correções de bugs na refatoração (faça-as como trabalhos separados).
- Se um teste ficar vermelho, pare ali mesmo. Não prossiga.
- Não mude assinaturas de API pública por conta própria (confirme antes se necessário).

## Definição de pronto
Todos os testes permanecem verdes, e o código fica mais legível, com menos duplicação.

# Como escrever um documento de design

Antes de implementar, escreva primeiro o seguinte em prosa (não escreva código):

## 1. Objetivo
O problema a resolver e as condições para considerá-lo alcançado (critérios de sucesso).

## 2. Estado atual e restrições
A configuração existente, as dependências e as restrições a respeitar (desempenho, compatibilidade, prazo).

## 3. Proposta de design
- A abordagem escolhida e as abordagens que você considerou e rejeitou (e por quê).
- O fluxo de dados, as principais interfaces e os arquivos a alterar.

## 4. Riscos e questões em aberto
O que pode quebrar, as premissas que precisam de confirmação e os pontos que exigem uma decisão.

## 5. Plano
Divida a implementação em etapas pequenas, ordenadas em unidades verificáveis.

## Regras
- Não comece a implementar até que este design seja aprovado.
- Liste as incógnitas em \'questões em aberto\'; não as preencha com as suas próprias suposições.

# Como fazer grandes mudanças

## Princípio central
Evite uma mudança gigante. Divida-a de modo que cada etapa seja revisável,
testável e (idealmente) implantável de forma independente.

## Etapas
1. Decomponha as mudanças que levam à forma final em uma sequência de etapas
   pequenas e independentes, e apresente-a.
2. Para cada etapa, escreva \'o quê / por quê / escopo de impacto\' em 1-2 linhas.
3. Após cada etapa, execute a suíte de testes completa e confirme que está verde antes de seguir.
4. Prossiga preservando a compatibilidade retroativa (adicionar -> migrar -> aposentar o caminho antigo).

## Regras absolutas
- Não reescreva uma área ampla de uma só vez e \'teste tudo junto depois\'.
- Se uma etapa ficar grande demais, divida-a ainda mais.
- Mantenha cada etapa em uma granularidade que possa ser revertida.

## Definição de pronto
Os testes estão verdes após a conclusão de todas as etapas, e todo commit intermediário também não está quebrado.

# Instruções de revisão de código

Revise as mudanças, agrupe-as por severidade e reporte nesta ordem:
1. CRITICAL - brechas de segurança, perda de dados, crashes, autenticação quebrada
2. HIGH     - bugs de lógica, condições de corrida, tratamento de erros ausente
3. MEDIUM   - problemas de desempenho, testes ausentes, nomes confusos
4. LOW      - implicâncias menores de estilo (apenas se não houver problemas de nível mais alto)

## Como reportar
- Para cada achado: arquivo:linha / o que está errado / por que importa / uma correção concreta.
- Cite apenas o menor trecho relevante. Não cole o arquivo inteiro.
- Se uma mudança estiver correta, diga isso explicitamente. Não fabrique problemas.

## Coisas a não fazer
- Não enterre bugs reais sob uma pilha de implicâncias LOW.
- Não reescreva arquivos inteiros. Proponha o menor diff.
- A menos que haja dano real, não aponte linhas fora do escopo do diff.

## Saída
Termine com um veredito de uma linha: APPROVE / REQUEST CHANGES / BLOCK, com um motivo.

# Regras de Git / PR

## Commits
- Use Conventional Commits: `type(scope): summary`
  type: feat, fix, refactor, test, docs, chore.
- Um commit = uma mudança lógica. Mantenha-o pequeno e revisável.
- No corpo, escreva o \'porquê\' em vez do \'o quê\'.

## Regras absolutas
- Não faça `git push` a menos que seja instruído.
- Não faça force-push, rebase ou amend em branches compartilhadas / main.
- Não commite segredos, .env, credenciais ou binários grandes.
- Adicione arquivos pelo nome. Não arraste tudo com `git add -A`.

## Pull requests
- Título com até 70 caracteres. Corpo é \'Resumo\' + \'Plano de teste (checklist)\'.
- Anote quaisquer mudanças que quebrem compatibilidade.
- Não faça merge. Crie o PR e reporte a URL.

# Instruções de revisão de segurança

Verifique as mudanças, em ordem, sob os seguintes ângulos, e reporte quaisquer
problemas encontrados com uma classificação de severidade:
- Validação de entrada ausente (injeção: SQL / comando / XSS / SSRF)
- Lacunas de autenticação/autorização (verificações de permissão ausentes, escalada de privilégio)
- Exposição de segredos (chaves/tokens fixos no código, saída para logs)
- Padrões inseguros (exposição excessiva, CORS frouxo, redirecionamentos não validados)
- Vulnerabilidades conhecidas em dependências, uso inseguro de criptografia / RNG

## Como reportar
- Para cada achado: local / cenário de ataque (como poderia ser explorado) / uma correção concreta.
- Sinalize suspeitas das quais você não tem certeza como \'precisa de confirmação\' (não as pule em silêncio).
- Se não houver problema, declare \'sem problemas\' junto com os ângulos que você verificou.

## Coisas a não fazer
- Não gere código de ataque real nem passos de exploração (mostre apenas correções).

# Regras de trabalho com Docker / infraestrutura

## Regras absolutas (evitar a destruição vem primeiro)
- Não execute comandos destrutivos em ambientes de produção ou compartilhados por conta própria
  (`docker system prune`, exclusão de volumes, `down -v`, etc.).
- Fixe as imagens em tags fixas. Não dependa de `latest`.
- Passe segredos via variáveis de ambiente / gerenciamento de segredos.
  Não os embuta no Dockerfile ou na imagem.
- Mantenha as portas expostas e os privilégios (privileged, etc.) ao mínimo necessário.

## Convenções
- Mantenha os Dockerfiles pequenos com builds multi-estágio, atento ao cache de camadas.
- Execute como um usuário não-root.
- Após as mudanças, faça build e suba localmente para verificar antes de reportar.

## Definição de pronto
`docker build` passa, o contêiner sobe, e o health check / operação
básica pode ser confirmado.

# Regras de dependências

## Regras absolutas
- Antes de adicionar uma dependência, verifique se a biblioteca padrão ou uma
  dependência existente é suficiente.
- Ao adicionar uma nova dependência, acrescente uma nota de uma linha sobre seu propósito,
  alternativas e estado de manutenção.
- Não suba versões major por conta própria (apenas quando instruído).
- Não regenere arquivos de lock (package-lock.json, etc.) por conta própria.
- Evite pacotes de origem duvidosa ou com pouquíssimas estrelas ou manutenção precária.

## Etapas
1. Declare o motivo da adição ou atualização.
2. Depois de adicioná-la, confirme que o build e os testes passam.
3. Confirme que a licença não entra em conflito com o seu caso de uso.

## Definição de pronto
O build e os testes passam após a mudança de dependência, e você consegue explicar o diff no arquivo de lock.