OpenAI's Codex now includes AGENTS.md, a project-level instruction file that automatically loads team coding standards into every developer session, eliminating the need to repeat constraints manually. Unlike traditional documentation that developers might forget or ignore, AGENTS.md becomes part of the model's context from the moment a session starts, making it a foundational shift in how teams coordinate AI-assisted development at scale.

What Is AGENTS.md and How Does It Work?

AGENTS.md functions as an "open-format README for agents," according to OpenAI's official documentation. When a developer starts a Codex session, the system automatically reads AGENTS.md before any work begins, loading team rules into the model's context. This is fundamentally different from Skills, which are reusable task workflows activated only for specific situations. AGENTS.md is always on; Skills are off by default and invoked for particular kinds of work.

The system uses a layered loading approach that respects both global defaults and project-specific overrides. Codex first checks for a global AGENTS.md file in the user's home directory, then walks down from the Git repository root to the current working directory, looking for project-level and subdirectory-specific instruction files. Files closer to the current directory take precedence, allowing teams to set broad standards while letting individual services or modules enforce stricter rules without overwriting repository-level defaults.

Why Should Teams Care About AGENTS.md?

Without AGENTS.md, every Codex session starts from scratch. Engineers must either remember to include relevant constraints in every prompt or rely on the model to infer conventions from the codebase alone. This creates friction and inconsistency, especially in distributed teams where different developers might phrase the same rule differently. AGENTS.md removes that overhead by encoding rules once, version-controlling them, and making them automatically available to every session, whether it's an interactive CLI session, a colleague's automation, or a Codex Cloud task triggered from a GitHub issue.

The practical impact is significant. A payments service can enforce stricter rules than the rest of the repository without overwriting repository-level defaults. Database access can be restricted to a single module. Production deployment commands can be explicitly forbidden. All of this happens automatically, without requiring developers to remember or type constraints repeatedly.

What Should Go Into AGENTS.md?

OpenAI's best practices documentation describes AGENTS.md as the place for "durable guidance." The most effective AGENTS.md files follow a structured approach that covers several key categories:

• Architectural Rules: Constraints about how the codebase is organized, such as "all database access goes through src/db/repository.py" or "the payments module has its own auth flow separate from the main auth system." These are rules the model might not infer correctly from code alone.
• Testing and Review Expectations: Specific commands to run before opening a pull request, such as "run pytest tests/ -v before any PR" or "tag @security-review on any PR touching src/auth/." This ensures consistency in code quality gates.
• Forbidden Paths and Risky Commands: Explicit boundaries like "do not modify files in vendor/ or third_party/" and "do not run make deploy or scripts/provision.sh." These prevent accidental damage to production environments or dependencies.
• Subdirectory Overrides: Service-specific rules for monorepos, such as "use make test-payments instead of npm test for the payments service" or "all transaction processing must pass audit-trail-check.sh."

What Are the Limits of AGENTS.md?

AGENTS.md is a text file that shapes behavior through instruction, not enforcement. If a developer writes "never modify vendor/," Codex is more likely to avoid that directory, but it is not locked out. A long, complex session where the model loses track of earlier context might drift from the instructions. A model that makes an incorrect inference about what a task requires might violate a rule despite having read it.

This is a meaningful limitation. OpenAI's own documentation notes that Codex "should echo guidance from global and project files" and includes test patterns for verifying the instructions loaded correctly. The test tells you the instructions were included in context, not that every future action will comply with them. For actions where rule violations would be irreversible or high-cost, such as production deployments or database operations, the right safeguard is a combination of AGENTS.md instructions and explicit approval gates in execution policies or sandbox configuration, not AGENTS.md alone.

How Does AGENTS.md Compare to Codex Skills?

The confusion between AGENTS.md and Skills stems from the fact that both answer the underlying question: "How do I make Codex follow my team's patterns?" They are both answers, just to different sub-questions. If you want Codex to always run your linter before a pull request, that belongs in AGENTS.md. If you want Codex to follow a specific code review workflow when you explicitly ask it to review a PR, that is a Skill. AGENTS.md is context you load into every session. Skills are behavior you activate for specific sessions. Both shape what Codex does, but at different layers of the system.

How to Set Up AGENTS.md for Your Team

• Start with /init: Run the /init slash command inside a Codex CLI session to scaffold a starter AGENTS.md in your current directory. This provides a useful starting point, though the output needs editing to match how your team actually builds, tests, reviews, and ships code.
• Define Architectural Constraints: Document how your codebase is organized and which modules handle which responsibilities. Include any patterns the model might not infer from code alone, such as "all database access goes through a single repository module" or "the payments service has its own authentication flow."
• Specify Testing Requirements: List the exact commands developers should run before opening a pull request, including integration tests, security linters, and any service-specific test suites. Be explicit about which tests are required for which parts of the codebase.
• Establish Forbidden Boundaries: Explicitly list paths and commands that Codex should never modify or execute. This is more effective than relying on the model to infer boundaries from code structure alone.
• Layer Rules for Monorepos: If your team uses a monorepo, create subdirectory-specific AGENTS.override.md files that enforce stricter rules for sensitive services without overwriting repository-level defaults.
• Version Control and Review: Treat AGENTS.md like any other code file. Version control it, review changes in pull requests, and update it when team standards evolve.

The total instruction size is capped at 32 kilobytes by default, which is enough for most teams to encode comprehensive guidance without hitting limits. Codex skips empty files and stops loading once the combined size reaches the cap.

What Does This Mean for the Future of AI-Assisted Development?

AGENTS.md represents a shift toward treating AI coding agents as team members that need explicit onboarding. Rather than hoping the model infers your team's standards from code, you now document them explicitly and make them always available. This approach scales better as teams grow and as AI agents take on more complex, autonomous tasks. It also creates a clear separation between what the model should do (encoded in AGENTS.md) and what it actually does (subject to model limitations and context drift). For teams using Codex across CLI, VS Code extensions, and Codex Cloud, this consistency matters significantly, as the same AGENTS.md applies to all surfaces.

The practical implication is that teams can now enforce coding standards at the infrastructure level, not just through code review. A Codex Routine set up in the web UI can trigger agent runs that use the same AGENTS.md your CLI sessions use, creating a unified standard across all development workflows.