Quais Convenções de Diretórios e Estilos de Código Codex e Claude Code Seguem Bem?

Codex e Claude Code não têm uma preferência inerente por determinada linguagem de programação, framework, largura de indentação ou organização de pastas. Os ambientes que eles conseguem seguir com relativa confiabilidade são aqueles em que as convenções existentes do repositório são consistentes, o escopo das regras necessárias é claro e as alterações podem ser validadas automaticamente. Portanto, o objetivo não é inventar uma estrutura que uma IA possa gostar, mas tornar as convenções do projeto curtas e verificáveis para que pessoas e novos colaboradores possam entendê-las. openai.com↗code.claude.com↗

Aqui, Codex e Claude Code se referem a ferramentas de agentes de programação que podem ler arquivos em um repositório, consultar instruções, modificar código ou executar comandos. Essas ferramentas obtêm muitos indícios do próprio código, mas nem sempre conseguem inferir com precisão a terminologia do domínio do produto, alterações proibidas, verificações pré-implantação ou regras de exceção para pastas específicas. A estrutura do repositório, os arquivos de instruções e os procedimentos de validação executáveis preenchem essa lacuna. cdn.openai.com↗

Por Que a Consistência É Mais Importante do Que a “Estrutura de Pastas Correta”?

Por exemplo, uma equipe pode organizar src/payments/ e src/users/ por funcionalidade, enquanto outra pode organizar src/controllers/, src/services/ e src/repositories/ por camada. Não há base para afirmar conclusivamente que uma das abordagens é automaticamente melhor para Codex ou Claude Code. O que importa é que responsabilidades do mesmo tipo tenham localizações semelhantes no repositório, que novos arquivos sejam posicionados segundo os mesmos critérios e que testes e estilos de importação sigam os padrões existentes.

O mesmo se aplica quando um agente adiciona uma nova funcionalidade de pagamentos. Se o módulo de pagamentos existente mostra como são organizados a validação de requisições, o tratamento de erros, o acesso a dados e os testes, é mais seguro dar continuidade a esse padrão. Por outro lado, se cada nova funcionalidade introduz novos nomes de arquivo e camadas, ou se uma única pasta mistura código de domínio com artefatos de build e arquivos temporários, tanto os agentes quanto as pessoas terão dificuldade para determinar onde fazer alterações e o que elas afetam.

Assim, convenções de diretórios não são meramente regras de aparência. Elas são um sistema de navegação que mostra onde encontrar código, o que deve ser alterado em conjunto e qual validação executar. Quanto mais estáveis forem os nomes e os limites, menor será a necessidade de repetir explicações extensas nos arquivos de instruções.

Onde Deve Ficar a Orientação Básica do Repositório?

No Codex, AGENTS.md geralmente funciona como o arquivo de instruções do projeto. As instruções de estilo de código, estrutura, nomenclatura e testes desse arquivo se aplicam ao diretório que o contém e à sua subárvore, enquanto instruções em locais mais profundos podem atuar como orientações mais específicas quando surgem conflitos. Também há suporte para instruções de ambiente pessoal e substituições por meio de AGENTS.override.md. openai.com↗

No Claude Code, CLAUDE.md ou .claude/CLAUDE.md pode servir como centro de memória e orientação do projeto. Um CLAUDE.md em um caminho pai pode ser fornecido como contexto na inicialização, enquanto arquivos em subdiretórios são carregados conforme necessário ao lidar com arquivos nesses caminhos. Você também pode usar CLAUDE.local.md para configurações por usuário e arquivos no nível do diretório inicial. code.claude.com↗

Embora os dois arquivos tenham nomes semelhantes, seu comportamento de descoberta automática não é igual. Em especial, não presuma que o Claude Code lê automaticamente AGENTS.md como instruções compartilhadas. Ao usar ambas as ferramentas, importe o arquivo compartilhado em CLAUDE.md com @AGENTS.md ou defina explicitamente uma conexão adequada ao modelo operacional da equipe. code.claude.com↗

É melhor manter o arquivo de orientação na raiz mais próximo de um mapa de entrada do que de uma enciclopédia que descreve todo o repositório extensamente. Basta mostrar os comandos de que um novo colaborador precisa primeiro, a estrutura de nível superior, as principais invariantes e os locais da documentação detalhada. Um arquivo de instruções único e longo consome contexto que deveria ser usado para o código real e os requisitos da tarefa, além de poder tornar restrições críticas mais difíceis de notar. Um exemplo relacionado ao OpenAI Codex também apresenta a combinação de um arquivo curto, semelhante a um mapa, de cerca de 100 linhas, com documentação separada. openai.com↗

O Que AGENTS.md e CLAUDE.md Devem Incluir?

Boas instruções não duplicam extensivamente fatos que já são óbvios pelo código. Em vez disso, priorizam informações difíceis de aprender somente pelo código ou cujo entendimento incorreto é custoso. Materiais relacionados ao Codex identificam convenções de nomenclatura, linguagem do domínio, restrições e dependências conhecidas, além de procedimentos de build e teste, como informações adequadas para AGENTS.md. cdn.openai.com↗

As instruções na raiz podem responder de forma concisa a perguntas como:

• Quais comandos executam formatação, análise estática, verificação de tipos e testes depois de uma alteração inicial?
• Onde ficam o código-fonte, os testes, a documentação de design e a documentação operacional?
• Quais convenções de nomes de arquivo, importações, tratamento de erros e testes devem ser seguidas ao estender um módulo existente?
• Arquivos gerados, artefatos de build, arquivos de lock e segredos podem ser modificados ou incluídos no repositório?
• Áreas de alto risco exigem um plano, revisão adicional ou testes específicos?
• Quais documentos contêm procedimentos detalhados de design e operação?

Em contrapartida, afirmações amplas como “escreva código limpo”, “priorize a segurança” ou “faça o seu melhor” são difíceis de transformar em regras executáveis. Uma instrução como “use o módulo de validação existente para entradas externas e adicione o teste de integração correspondente para cada nova rota de API” é mais útil porque pode ser observada e verificada. A orientação do Claude Code também enfatiza escrever regras específicas do projeto de forma concreta e revisar e organizar as instruções regularmente à medida que crescem. code.claude.com↗

As instruções devem ser um registro condensado dos critérios de decisão, não um documento que dite cada detalhe de implementação. Conhecimento extenso e propenso a mudanças — como o uso de determinada biblioteca, contratos de API ou a ordem de resposta a incidentes — é mais fácil de manter quando transferido para um documento apropriado em docs/, enquanto as instruções na raiz indicam sua localização e condições de uso.

Quando São Necessárias Regras para Subdiretórios Individuais?

Regras de subdiretórios não são arquivos que devem ser adicionados mecanicamente a todas as pastas. Onde as regras compartilhadas da raiz bastam, arquivos separados podem aumentar a sobrecarga de navegação e o potencial de conflitos. Eles devem ser reservados para limites que se afastam claramente das regras gerais ou onde erros têm consequências significativas.

Por exemplo, src/payments/ pode documentar como cálculos monetários devem ser expressos, como mocks de provedores de pagamento externos devem ser usados e qual comando específico de teste de integração executar. infra/ pode exigir um plano antes das alterações, verificações antes de aplicá-las e limites sobre quais arquivos específicos de ambiente podem ser modificados. generated/ pode informar que edições diretas são proibidas e identificar a origem e o comando de geração. O propósito dessas regras não é fazer a pasta parecer especial, mas fornecer com precisão as restrições reais daquela área no contexto de trabalho.

Para o Codex, um AGENTS.md aninhado se aplica abaixo de seu diretório, e arquivos mais profundos podem fornecer regras mais específicas. O Claude Code também pode acumular vários arquivos CLAUDE.md como contexto; portanto, é mais seguro que arquivos aninhados acrescentem condições concretas necessárias apenas naquela área, em vez de fazer declarações ambíguas que revoguem arquivos pais. openai.com↗code.claude.com↗

Por exemplo, a raiz pode dizer: “Execute os testes do pacote alterado”, enquanto a pasta de pagamentos diz: “Se o contrato de pagamento mudar, execute os testes unitários e de integração.” Em contraste, escrever “Os testes devem sempre ser executados” na raiz e “Não execute testes” em uma subpasta deixa não apenas as ferramentas, mas também as pessoas sem saber qual regra seguir.

Como Dividir .claude/rules/ do Claude Code?

No Claude Code, você pode colocar regras globais sempre necessárias em CLAUDE.md e dividir regras com tópicos distintos ou comportamento dependente de caminho em pequenos arquivos sob .claude/rules/. Os arquivos de regras podem ser organizados recursivamente, e condições de caminho podem aplicar regras somente a determinados arquivos ou áreas. code.claude.com↗

O critério para a divisão não é o número de arquivos, mas a coesão das regras que mudam juntas. Por exemplo, comandos de teste e princípios para dados de teste podem ficar em testing.md; exceções de importações, nomenclatura e formatação podem ficar em code-style.md; e restrições relacionadas a segredos, requisições externas e permissões podem ficar em security.md. Cada arquivo deve tratar de um único tópico, e seu título deve deixar claro quando ele precisa ser lido.

A vantagem dessa abordagem é não precisar ler integralmente instruções desnecessárias o tempo todo. Por exemplo, se as regras completas de migração de banco de dados permanecerem misturadas a um trabalho que apenas edita documentação, elas podem obscurecer as instruções principais. Contudo, dividir as regras de forma excessivamente granular dificulta encontrar seus locais. Uma abordagem equilibrada é apresentar brevemente os principais grupos de regras e seus propósitos no CLAUDE.md da raiz, mantendo o conteúdo real em arquivos específicos por tópico.

Depois de separar as regras, evite copiar a mesma obrigação em vários arquivos. Cópias podem divergir facilmente com o tempo. Manter princípios compartilhados em um único lugar e registrar apenas exceções e condições adicionais nos arquivos específicos por caminho reduz conflitos.

Como o Estilo de Código Deve Ser Especificado?

“Estilo de código amigável para IA” não significa uma escolha universal, como tabs em vez de espaços ou programação funcional em vez de orientada a objetos. O critério mais importante é se as convenções locais do repositório podem ser reproduzidas. Revisões e manutenção se tornam mais fáceis quando um novo módulo segue os padrões dos módulos existentes para nomes de arquivo, estilo de exportação, ordem de importação, fluxos de tratamento de erros e estrutura de testes.

Qualquer escolha do projeto que difira das convenções comuns da linguagem merece documentação especial. A documentação do Claude Code usa estilo de código específico do projeto, como módulos ES ou desestruturação de importações nomeadas, como exemplos. Em outras palavras, em vez de reescrever todas as regras padrão de uma linguagem, é mais eficiente descrever “o que nosso projeto faz de forma diferente do padrão”. code.claude.com↗

A tabela a seguir oferece critérios simples para decidir orientações de estilo.

Formatadores, linters e verificadores de tipo tornam o estilo testável mecanicamente, em vez de impô-lo por meio de texto. Portanto, é melhor que as instruções especifiquem os comandos reais a executar e o tratamento esperado de falhas, em vez de dizer “formate as coisas de forma bonita”. As práticas recomendadas do Claude Code também indicam instruções claras de projeto e fluxos de desenvolvimento verificáveis. code.claude.com↗

Com Qual Estrutura de Diretórios Você Pode Começar?

O exemplo a seguir pode ser usado ao considerar Codex e Claude Code em conjunto. Não é um padrão obrigatório, mas um possível ponto de partida que separa instruções compartilhadas, documentação detalhada e exceções específicas por área.

repo/
├── AGENTS.md
├── CLAUDE.md
├── README.md
├── ARCHITECTURE.md
├── docs/
│   ├── design-docs/
│   ├── product-specs/
│   ├── runbooks/
│   └── generated/
├── src/
│   ├── feature-a/
│   └── feature-b/
├── tests/
└── .claude/
    ├── rules/
    │   ├── testing.md
    │   ├── code-style.md
    │   └── security.md
    └── settings.json

Aqui, README.md pode conter as informações de que as pessoas precisam para começar a trabalhar com o repositório; ARCHITECTURE.md pode descrever os principais limites e a estrutura do sistema; e docs/ pode conter conhecimento extenso e detalhado sobre design, produto e operações. A organização real de src/ e tests/ deve seguir prioritariamente a estrutura existente do projeto. .claude/rules/ é um local para regras específicas por tópico ou caminho do Claude Code. code.claude.com↗

Se você se preocupa com muitos arquivos na raiz, a questão principal não é o número de nomes de arquivos, mas a separação de responsabilidades. Se um arquivo assume ao mesmo tempo a apresentação do projeto, o design do sistema, a resposta operacional, convenções detalhadas de API e regras de estilo, fica difícil saber quais informações são essenciais para a tarefa atual. Em contraste, um guia curto na raiz que aponta para os documentos detalhados necessários permite que colaboradores explorem apenas a profundidade necessária.

O mesmo princípio se aplica ao posicionamento de arquivos de instruções em pastas específicas por funcionalidade. Não adicione um a menos que a funcionalidade tenha regras dedicadas; adicione-o somente quando houver uma razão clara, como tratamento de dados sensíveis ou um processo de geração automatizada. A proliferação frequente de arquivos de regras pode complicar a própria estrutura em vez de explicá-la.

Como Reduzir Regras Duplicadas ao Usar Ambas as Ferramentas?

Uma opção é manter as convenções de desenvolvimento compartilhadas e canônicas em AGENTS.md, importá-lo do CLAUDE.md da raiz e acrescentar somente o conteúdo de que o Claude Code precisa. Por exemplo:

@AGENTS.md

## Claude Code only
- Present a plan before changing `src/payments/`.
- Follow the path-specific rules in `.claude/rules/`.

Essa configuração reduz a necessidade de manter repetidamente comandos de teste, regras comuns de nomenclatura e princípios sobre arquivos gerados nos dois arquivos. Ao mesmo tempo, preserva regras específicas do Claude Code e uma configuração baseada em .claude/rules/. Porém, como observado acima, o Claude Code não lê AGENTS.md automaticamente como instruções compartilhadas; portanto, você precisa de fato configurar uma importação ou conexão equivalente. code.claude.com↗

O local do arquivo compartilhado pode depender do uso relativo das ferramentas pela equipe e das convenções existentes no repositório. Se o Codex é usado com mais frequência, AGENTS.md é uma fonte canônica simples; se as operações se concentram no sistema de regras do Claude Code, CLAUDE.md pode ser a fonte canônica. Independentemente da escolha, o essencial é designar uma origem autoritativa para cada regra e deixar somente referências ou adições específicas da ferramenta no outro arquivo.

É melhor separar preferências individuais das convenções da equipe. Aliases de comandos em um ambiente pessoal, escolhas de ferramentas locais e hábitos pessoais de trabalho podem pertencer a arquivos de substituição pessoais. Em contraste, procedimentos de teste, restrições de segurança e estrutura de código que todos que clonam o repositório precisam conhecer devem permanecer nas instruções do projeto controladas por versão. Tanto Codex quanto Claude Code oferecem suporte a configurações de instruções no nível do projeto e no nível pessoal. openai.com↗code.claude.com↗

Por Que os Comandos de Validação Devem Ser Centrais nas Instruções?

As propostas ou alterações de um agente de programação podem parecer plausíveis, mas não garantem automaticamente correção, compatibilidade ou segurança. A orientação relacionada ao Codex também explica que a revisão humana e a validação da saída continuam necessárias. openai.com↗

Por esse motivo, boas instruções de repositório explicam não só “como programar”, mas também “como verificar”. Quando possível, liste comandos de formatação, lint, verificação de tipos, testes unitários, testes de integração e build em formatos que possam realmente ser executados. Em repositórios grandes, nos quais exigir validação completa para cada tarefa é impraticável, é possível distinguir a validação mínima por local da alteração das condições que exigem validação completa.

Por exemplo, atualizações de documentação podem exigir apenas verificação de links ou um build da documentação, enquanto alterações em um contrato público de API podem exigir testes unitários e de integração. Mudanças difíceis de reverter, como esquemas de banco de dados ou configuração de infraestrutura, podem exigir uma etapa adicional de revisão. O importante não é esperar que a ferramenta avalie o risco magicamente, mas registrar explicitamente no repositório os caminhos de validação que a equipe já conhece.

Código gerado e artefatos de build também devem ser claramente diferenciados sob a perspectiva de validação. Se os arquivos não devem ser editados diretamente, documente sua localização de origem e o procedimento de geração; se a edição de um artefato for permitida, informe qual comando o atualiza. Também é mais seguro deixar claro o princípio de que segredos e configurações pessoais específicas de ambiente não pertencem ao repositório, além da localização dos arquivos de exemplo e das etapas de validação exigidas.

Quais São os Equívocos e Padrões de Falha Comuns?

O primeiro equívoco é que “mais instruções levam a melhor conformidade”. Na prática, documentos longos podem ocultar as regras mais importantes. Se as instruções ficaram longas demais, remova explicações duplicadas, regras que já são automatizadas e exceções que não são mais válidas; em seguida, mova o conhecimento detalhado para documentos separados. code.claude.com↗openai.com↗

O segundo é que “toda pasta precisa de um arquivo de instruções”. Instruções aninhadas são úteis somente onde há restrições especiais. Um arquivo aninhado sem especificidade apenas acrescenta mais um arquivo para ler e pode tornar pouco clara sua relação com as regras pai.

O terceiro é que “basta seguir regras de estilo”. Mesmo que a formatação seja consistente, uma alteração não é necessariamente boa se os testes não foram executados, se regras de domínio foram violadas ou se arquivos gerados foram editados diretamente. Automação de estilo, testes e procedimentos de revisão não são substitutos; são salvaguardas que trabalham juntas.

O quarto é que “a ferramenta resolverá sozinha contradições na documentação”. Quando instruções pai e filhas, ou instruções compartilhadas e específicas de ferramenta, entram em conflito, o resultado se torna difícil de prever. Mantenha a mesma regra em um só lugar e deixe claro o escopo e as condições adicionais das regras filhas. Como a configuração de memória do Claude Code também lida com instruções hierárquicas, é importante projetar regras para evitar conflitos. code.claude.com↗

Por fim, evite tratar um arquivo de instruções como garantia de qualidade. As instruções fornecem contexto que apoia o julgamento de agentes e pessoas; elas não são mecanismos que garantem a correção, a segurança ou a aprovação nos testes do código gerado. Revisar as alterações e realizar a validação necessária continua sendo essencial. openai.com↗

O Que Devemos Aplicar Primeiro em Nosso Repositório?

Não é necessário redesenhar toda a estrutura de pastas desde o início. É mais realista começar com pequenas melhorias baseadas em confusões recorrentes no repositório atual. Por exemplo, se novos colaboradores não conseguem encontrar o comando de teste, adicione-o às instruções da raiz. Se os mesmos erros ocorrem repetidamente no módulo de pagamentos, adicione regras específicas somente para esse caminho. Se documentos de design estão misturados com código e são difíceis de navegar, primeiro diferencie os tipos de documentos em docs/.

Você pode usar uma sequência de avaliação como esta:

1. Identifique as convenções de posicionamento de arquivos, nomenclatura e testes que realmente se repetem na base de código atual.
2. Organize os comandos e as condições de falha para formatadores, linters, verificações de tipo e testes.
3. Identifique restrições de domínio, áreas sem edição e procedimentos de geração que são difíceis de entender somente pelo código.
4. Escreva somente o conteúdo mais importante de forma concisa no AGENTS.md ou CLAUDE.md da raiz.
5. Adicione instruções aninhadas ou regras específicas por caminho apenas a áreas sensíveis que as regras gerais não conseguem explicar.
6. Designe uma única fonte original para regras compartilhadas e deixe somente referências e regras específicas da ferramenta nos arquivos da outra ferramenta.
7. Revise regularmente se as instruções foram úteis no trabalho real e se contêm declarações desnecessárias ou contraditórias.

Nesse processo, você não precisa tratar “fácil de entender para ferramentas” e “fácil de manter para pessoas” como objetivos opostos. Documentação curta e precisa, limites previsíveis entre módulos e validação executável automaticamente ajudam ambos. Em contrapartida, tentar compensar apenas com arquivos de instruções uma estrutura que até mesmo as pessoas têm dificuldade de explicar provavelmente tornará a documentação difícil de manejar.

Conclusão: Quais Convenções Você Deve Escolher?

A chave para convenções de diretórios e estilos de código adequados ao Codex e ao Claude Code não é adotar uma estrutura específica que esteja em moda. Uma abordagem prática é manter consistentemente as convenções da base de código existente, conservar um guia curto na raiz, separar o conhecimento detalhado em documentos apropriados e adicionar regras de escopo restrito apenas onde forem necessárias.

Para o Codex, você pode usar AGENTS.md; para o Claude Code, CLAUDE.md e, quando necessário, .claude/rules/. Se usar as duas ferramentas, designe uma única fonte para as regras compartilhadas e conecte explicitamente o arquivo compartilhado no Claude Code para reduzir duplicação. Acima de tudo, combine instruções com formatadores, linters, verificações de tipo, testes e revisão humana. Como a interpretação de instruções específicas de produtos pode mudar conforme a versão, é aconselhável manter as regras pequenas e claras enquanto consulta a documentação oficial das ferramentas que você realmente opera. openai.com↗code.claude.com↗