What Directory Conventions and Code Styles Do Codex and Claude Code Follow Well?
Codex and Claude Code do not inherently prefer a particular programming language, framework, indentation width, or folder layout. The environments they can follow relatively reliably are those where existing repository conventions are consistent, the scope of required rules is clear, and changes can be validated automatically. The goal, therefore, is not to invent a structure that an AI might like, but to make project conventions that people and new contributors can understand short and verifiable. openai.comcode.claude.com
Here, Codex and Claude Code refer to coding-agent tools that can read files in a repository, consult instructions, modify code, or run commands. Such tools gain many clues from the code itself, but they cannot always infer product domain terminology, prohibited changes, pre-deployment checks, or exception rules for specific folders accurately. Repository structure, instruction files, and executable validation procedures fill that gap. cdn.openai.com
Why Is Consistency More Important Than the “Right Folder Structure”?
For example, one team might organize src/payments/ and src/users/ by feature, while another might organize src/controllers/, src/services/, and src/repositories/ by layer. There is no basis for conclusively saying that either approach is automatically better for Codex or Claude Code. What matters is that responsibilities of the same kind have similar locations within a repository, new files are placed according to the same criteria, and tests and import styles follow existing patterns.
The same applies when an agent adds a new payment feature. If the existing payment module shows how request validation, error handling, data access, and tests are arranged, continuing that pattern is safer. Conversely, if every new feature introduces new file names and layers, or if a single folder mixes domain code with build artifacts and temporary files, both agents and people will have difficulty determining where to make changes and what those changes affect.
Directory conventions are therefore not merely rules of appearance. They are a navigation system that reveals where to find code, what to change together, and which validation to run. The more stable the names and boundaries are, the less need there is to repeat lengthy explanations in instruction files.
Where Should the Repository’s Basic Guidance Live?
In Codex, AGENTS.md generally serves as the project instruction file. Code style, structure, naming, and testing instructions in this file apply to the directory containing it and its subtree, while instructions in deeper locations can act as more specific guidance when conflicts arise. Personal-environment instructions and overrides through AGENTS.override.md are also supported. openai.com
In Claude Code, CLAUDE.md or .claude/CLAUDE.md can serve as the center for project memory and guidance. A CLAUDE.md in a parent path can be provided as context at startup, while files in subdirectories are loaded as needed when handling files at those paths. You can also use CLAUDE.local.md for per-user settings and files at the home-directory level. code.claude.com
Although the two files have similar names, their automatic discovery behavior is not the same. In particular, do not assume that Claude Code automatically reads AGENTS.md as shared instructions. When using both tools, import the shared file in CLAUDE.md with @AGENTS.md, or explicitly define a connection that suits the team’s operating model. code.claude.com
It is best to keep the root guidance file closer to an entry map than an encyclopedia describing the entire repository at length. It is enough to show the commands a new contributor needs first, the top-level structure, key invariants, and the locations of detailed documentation. A long, single instruction file consumes context that should be used for actual code and task requirements, and can make critical constraints harder to notice. An OpenAI Codex-related example also presents a combination of a short, map-like file of around 100 lines and separate documentation. openai.com
What Should AGENTS.md and CLAUDE.md Include?
Good instructions do not extensively duplicate facts that are already obvious from the code. Instead, they prioritize information that is hard to learn from code alone or costly to infer incorrectly. Codex-related materials identify naming conventions, domain language, known constraints and dependencies, and build and test procedures as information worth placing in AGENTS.md. cdn.openai.com
Root instructions can concisely answer questions such as:
- Which commands run formatting, static analysis, type checking, and tests after an initial change?
- Where are source code, tests, design documentation, and operational documentation located?
- What file-naming, import, error-handling, and testing conventions should be followed when extending an existing module?
- May generated files, build artifacts, lock files, and secrets be modified or included in the repository?
- Do high-risk areas require a plan, additional review, or particular tests?
- Which documents contain detailed design and operating procedures?
By contrast, broad statements such as “write clean code,” “prioritize security,” or “do your best” are difficult to turn into executable rules. A statement such as “use the existing validation module for external input, and add the corresponding integration test for every new API route” is more useful because it can be observed and verified. Claude Code guidance likewise emphasizes writing project-specific rules concretely and reviewing and organizing instructions regularly as they grow. code.claude.com
Instructions should be a compressed record of decision criteria, not a document that dictates every implementation detail. Knowledge that is lengthy and likely to change—such as how to use a particular library, API contracts, or incident-response order—is easier to maintain when moved to an appropriate document under docs/, while root instructions indicate its location and conditions of use.
When Are Rules for Individual Subdirectories Needed?
Subdirectory rules are not files to add mechanically to every folder. Where shared root rules are enough, separate files can instead increase navigation overhead and the potential for conflicts. They are best reserved for boundaries that clearly depart from general rules or where mistakes have significant consequences.
For example, src/payments/ can document how monetary calculations should be expressed, how mocks for external payment providers should be used, and which specific integration-test command to run. infra/ can require a plan before changes, checks before applying them, and limits on which environment-specific files may be modified. generated/ can state that direct edits are prohibited and identify the source and generation command. The purpose of these rules is not to make the folder seem special, but to provide the actual constraints of that area precisely in the working context.
For Codex, a nested AGENTS.md applies beneath its directory, and deeper files can provide more specific rules. Claude Code can likewise accumulate multiple CLAUDE.md files as context, so it is safer for nested files to add concrete conditions needed only in that area rather than make ambiguous declarations that overturn parent files. openai.comcode.claude.com
For instance, the root might say, “Run tests for the package you changed,” while the payments folder says, “If the payment contract changes, run both unit and integration tests.” In contrast, writing “Tests must always be run” at the root and “Do not run tests” in a subfolder leaves not only tools but also people unsure which rule to follow.
How Should Claude Code’s .claude/rules/ Be Split Up?
In Claude Code, you can place global rules that are always needed in CLAUDE.md, and split rules with distinct topics or path-dependent behavior into small files under .claude/rules/. Rule files can be organized recursively, and path conditions can apply rules only to particular files or areas. code.claude.com
The criterion for splitting is not the number of files, but the cohesion of rules that change together. For example, test commands and principles for test data can go in testing.md; exceptions for imports, naming, and formatting can go in code-style.md; and constraints involving secrets, external requests, and permissions can go in security.md. Each file should address a single topic, and its title should make it clear when it needs to be read.
The advantage of this approach is that unnecessary instructions do not have to be read in full all the time. For example, if the complete database migration rules remain mixed into work that only edits documentation, they can obscure the key instructions. However, splitting rules too finely makes their locations difficult to find. A balanced approach is to briefly introduce the major rule groups and their purposes in the root CLAUDE.md, while keeping the actual content in topic-specific files.
After separating rules, avoid copying the same obligation into multiple files. Copies easily drift apart over time. Keeping shared principles in one place and recording only exceptions and additional conditions in path-specific files reduces conflicts.
How Should Code Style Be Specified?
“AI-friendly code style” does not mean one universal choice such as tabs versus spaces or functional versus object-oriented programming. The more important criterion is whether the repository’s local conventions can be reproduced. Reviews and maintenance become easier when a new module follows existing modules’ file-naming patterns, export style, import order, error-handling paths, and test structure.
Any choice the project makes that differs from common conventions for the language is especially worth documenting. Claude Code documentation uses project-specific code style such as ES modules or named-import destructuring as examples. In other words, rather than rewriting every default rule of a language, it is more efficient to describe “what our project does differently from the default.” code.claude.com
The following table provides simple criteria for deciding on style guidance.
| Area | Easier to leave to code and tools | Better to state in instructions |
|---|---|---|
| Formatting | Formatter configuration is in the repository and the command is defined | Certain file types require formatter exceptions |
| Imports | Existing files follow a uniform pattern | There are unique rules, such as prohibiting default exports or using internal aliases |
| Error handling | Shared error types and handling flows are consistent | Domain constraints exist, such as prohibiting retries or separating user-facing messages |
| Tests | Test locations and names are consistent | Certain changes require contract tests or integration tests |
| Naming | Domain terms are used consistently in the code | There are official names or prohibited terms for easily confused concepts |
Formatters, linters, and type checkers make style mechanically testable instead of enforcing it through prose. Therefore, it is better for instructions to specify the actual commands to run and the expected handling of failures than to say “format things nicely.” Claude Code best practices also recommend clear project instructions and verifiable development workflows. code.claude.com
What Directory Structure Can You Start With?
The following is an example you can use when considering Codex and Claude Code together. It is not a required standard, but one possible starting point that separates shared instructions, detailed documentation, and area-specific exceptions.
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
Here, README.md can contain the information people need to get started with the repository, ARCHITECTURE.md can describe the system’s major boundaries and structure, and docs/ can hold lengthy, detailed design, product, and operational knowledge. The actual layout of src/ and tests/ should primarily follow the project’s existing structure. .claude/rules/ is a location for topic-specific or path-specific rules for Claude Code. code.claude.com
If you are concerned about having many files at the root, the key issue is not the number of file names but the separation of responsibilities. If one file takes on project introduction, system design, operational response, detailed API conventions, and style rules all at once, it becomes difficult to know which information is essential for the current task. In contrast, a short root guide that points to the required detailed documents lets contributors explore only as deeply as necessary.
The same principle applies when placing instruction files in feature-specific folders. Do not add one unless the feature has dedicated rules; add one only when there is a clear reason, such as sensitive data handling or an automated generation process. Frequent proliferation of rule files can complicate the structure itself instead of explaining it.
How Can You Reduce Duplicate Rules When Using Both Tools?
One option is to keep the canonical shared development conventions in AGENTS.md, import it from the root CLAUDE.md, and then append only content that Claude Code needs. For example:
@AGENTS.md
## Claude Code only
- Present a plan before changing `src/payments/`.
- Follow the path-specific rules in `.claude/rules/`.
This setup reduces the need to maintain test commands, common naming rules, and generated-file principles repeatedly in both files. At the same time, it preserves Claude Code-specific rules and a .claude/rules/-based configuration. However, as noted above, Claude Code does not automatically read AGENTS.md as shared instructions, so you must actually configure an import or equivalent connection. code.claude.com
Where to place the shared file can depend on the team’s relative use of the tools and existing repository conventions. If Codex is used most often, AGENTS.md is an easy canonical source; if operations center on Claude Code’s rule system, CLAUDE.md can be the canonical source instead. Regardless of the choice, the key is to designate one authoritative original for each rule, and leave only references or tool-specific additions in the other file.
It is best to separate individual preferences from team conventions. Command aliases in a personal environment, local tool choices, and personal work habits may belong in personal override files. In contrast, testing procedures, security constraints, and code structure that everyone cloning the repository must know should remain in version-controlled project instructions. Both Codex and Claude Code support project-level and personal-level instruction configurations. openai.comcode.claude.com
Why Should Validation Commands Be Central to Instructions?
A coding agent’s proposals or changes may look plausible, but they do not automatically guarantee correctness, compatibility, or security. Codex-related guidance also explains that human review and validation of output are still necessary. openai.com
For that reason, good repository instructions explain not only “how to code,” but also “how to check.” Where possible, list formatting, linting, type checking, unit testing, integration testing, and build commands in forms that can actually be run. For large repositories where requiring full validation for every task is impractical, you can distinguish minimum validation by change location from conditions that require full validation.
For example, documentation updates may require only link checking or a documentation build, while changes to a public API contract may require both unit and integration tests. Changes that are difficult to reverse, such as database schemas or infrastructure configuration, may require an additional review stage. The important thing is not to expect the tool to assess risk magically, but to explicitly record the validation paths the team already knows in the repository.
Generated code and build artifacts should also be clearly distinguished from a validation perspective. If files must not be edited directly, document their source location and generation procedure; if editing an artifact is permitted, state which command updates it. It is also safer to make clear the principle that secrets and environment-specific personal settings do not belong in the repository, the location of example files, and the required validation steps.
What Are Common Misconceptions and Failure Patterns?
The first misconception is that “more instructions lead to better compliance.” In practice, long documents can bury the most important rules. If instructions have grown too long, remove duplicated explanations, rules that are already automated, and exceptions that are no longer valid, then move detailed knowledge into separate documents. code.claude.comopenai.com
The second is that “every folder needs an instruction file.” Nested instructions are useful only where there are special constraints. A nested file without specificity merely adds another file to read and can make its relationship with parent rules unclear.
The third is that “matching style rules is enough.” Even if formatting is consistent, a change is not necessarily good if tests were not run, domain rules were violated, or generated files were edited directly. Style automation and testing and review procedures are not substitutes; they are safeguards that work together.
The fourth is that “the tool will resolve contradictions in documentation on its own.” When parent and child instructions, or shared and tool-specific instructions, conflict, the result becomes difficult to predict. Keep the same rule in one place, and make the scope and additional conditions of child rules clear. Since Claude Code’s memory configuration also handles hierarchical instructions, designing rules to avoid conflicts is important. code.claude.com
Finally, avoid treating an instruction file as a quality guarantee. Instructions provide context that supports the judgment of agents and people; they are not mechanisms that guarantee the correctness, security, or passing tests of generated code. Reviewing changes and performing necessary validation remain essential. openai.com
What Should We Apply First in Our Repository?
You do not need to redesign the entire folder structure from the start. It is more realistic to begin with small improvements based on recurring confusion in the current repository. For example, if new contributors cannot find the test command, add it to root instructions. If the same mistakes occur repeatedly in the payment module, add specific rules only for that path. If design documents are mixed with code and difficult to navigate, first distinguish document types within docs/.
You can use an assessment sequence like this:
- Identify the file placement, naming, and testing conventions that genuinely recur in the current codebase.
- Organize the commands and failure conditions for formatters, linters, type checks, and tests.
- Identify domain constraints, no-edit areas, and generation procedures that are difficult to understand from code alone.
- Write only the most important content concisely in the root
AGENTS.mdorCLAUDE.md. - Add nested instructions or path-specific rules only to sensitive areas that general rules cannot explain.
- Designate one original source for shared rules, and leave only references and tool-specific rules in files for the other tool.
- Review regularly whether instructions were helpful in real work and whether they contain unnecessary or contradictory statements.
In this process, you do not have to treat “easy for tools to understand” and “easy for people to maintain” as opposing goals. Short, accurate documentation, predictable module boundaries, and automatically executable validation help both. Conversely, trying to compensate for a structure that is difficult even for people to explain using instruction files alone is likely to make the documentation unwieldy.
Conclusion: Which Conventions Should You Choose?
The key to directory conventions and code styles suitable for Codex and Claude Code is not adopting a particular trendy structure. A practical approach is to maintain the existing codebase’s conventions consistently, keep a short guide at the root, separate detailed knowledge into appropriate documents, and add narrowly scoped rules only where needed.
For Codex, you can use AGENTS.md; for Claude Code, CLAUDE.md and, when needed, .claude/rules/. If you use both tools, designate a single source for shared rules and explicitly connect the shared file in Claude Code to reduce duplication. Above all, combine instructions with formatters, linters, type checks, tests, and human review. Because product-specific instruction interpretation can change by version, it is advisable to keep rules small and clear while checking the official documentation for the tools you actually operate. openai.comcode.claude.com