Codex AGENTS.md Team Rules

Use AGENTS.md to tell Codex the rules that should survive across prompts: repo structure, allowed commands, verification, review expectations, and MCP boundaries. For Codex CLI teams, the best practice is to keep those rules small, scoped, and enforced in code review instead of relying on one perfect prompt.

AGENTS.md is a repository instruction file that gives a coding agent durable, project-specific guidance. OpenAI Codex, OpenAI’s coding agent for software projects, works best in production codebases when that guidance points to real checks and reviewable diffs.

As of the June 18, 2026 Codex app 26.616 changelog entry, the useful team habit is not to chase a version number. It is to keep your Codex workflows boring, testable, and easy for another engineer to audit. For more team-level patterns, see the related training topic.

Keep AGENTS.md small and scoped

Put stable rules in AGENTS.md, not task instructions. Good rules describe architecture boundaries, package managers, test commands, naming conventions, security limits, and how to prepare a pull request.

The trap is writing a long manifesto that Codex has to interpret on every task. If a rule only matters for one migration, put it in the prompt or issue. If it applies to every change in apps/web, put it in apps/web/AGENTS.md instead of the root.

A practical root file might say that backend changes require the API test suite, frontend changes require the component tests, and database changes require a migration plan. A nested file in packages/billing/AGENTS.md can add local rules about money movement, idempotency, and audit logs.

This is the heart of codex agents.md best practices: local context beats one giant root file. The narrower the rule, the easier it is for Codex and reviewers to follow.

Add the team convention

Start with one convention your team can actually enforce. The file below is intentionally short. It gives Codex a workflow, a verification ladder, and an MCP boundary without trying to teach your whole company handbook.

# AGENTS.md

Purpose: Help Codex make small, reviewable changes in this repository.

Scope:
- This file applies to the whole repo.
- More specific AGENTS.md files inside a package or app override these rules for that subtree.

Repository map:
- apps/web is the customer web app.
- apps/api is the HTTP API.
- packages/ui contains shared React components.
- packages/db contains schema, migrations, and query helpers.

Codex workflow:
- Read the issue, then inspect the smallest set of files needed.
- Make the smallest useful diff.
- Do not reformat unrelated files.
- Keep public behavior stable unless the task explicitly asks for a behavior change.
- Before finishing, summarize changed files, tests run, and any follow-up risk.

Verification ladder:
- Documentation-only change: check links and examples.
- Frontend change: run the relevant component or app test.
- API change: run the relevant API test and typecheck.
- Database change: include migration notes and run the affected tests.
- If a check cannot run locally, say why and name the closest substitute.

MCP boundary:
- Use GitHub MCP only to read linked issues, pull requests, and review comments for this task.
- Do not read unrelated private repositories, Slack threads, customer records, or production databases.
- Ask before using any MCP tool that writes data outside the working tree.

Review contract:
- Every Codex-assisted PR must include the verification commands or a clear reason they were not run.
- Every AGENTS.md change must be reviewed by one code owner for the affected area.

Adopt it the same way you adopt production code. One engineer proposes the first version in a normal pull request, the owning team reviews it, and the file lives at the repo root plus any package directory that needs stricter local rules.

The review rule matters more than the prose. Any PR that changes AGENTS.md should include one example task the rule is meant to improve, plus the command or checklist reviewers should expect Codex to follow.

Verify before asking for review

Codex should not stop at a plausible diff. Your team convention should teach the Codex CLI workflow that turns a change into evidence: inspect, edit, run the narrowest check, summarize the result, then ask for review.

For a real web repo, that might mean asking Codex to update a settings form, then running pnpm test apps/web/settings and pnpm typecheck before the PR is marked ready. If the full suite takes 40 minutes, do not pretend every local loop will run it. Name the smaller check and leave the full gate to CI.

The trap is letting Codex produce a clean-looking patch with no receipt. A reviewer should not have to infer what happened. The final note should say what changed, what command ran, what failed if anything, and what still needs human judgment.

If you are tightening review gates at the same time, pair this convention with A Safer Codex Review Loop.

Keep MCP access explicit

MCP is the integration layer that lets tools connect to external systems such as GitHub, document stores, issue trackers, databases, and internal knowledge bases. In Codex workflows, MCP is powerful because it can bring the issue, design note, or PR history into the same loop as the code.

Use AGENTS.md to say which MCP tools are allowed for ordinary work. For example, GitHub read access for linked issues is usually much safer than broad access to every private repo or production data source.

The trap is treating MCP as generic context. It is not. It is access. A good Codex MCP rule names the system, the allowed action, the task boundary, and whether writes require approval.

Longer operating procedures should not live in AGENTS.md. If your team has a reusable release workflow, migration checklist, or review template, move that into a skill or command and keep AGENTS.md as the routing layer that tells Codex when to use it. That is one of the quieter codex best practices: keep durable rules short, and put reusable workflows where they can be maintained.

Common questions

• What are the codex agents.md best practices for a team?

  The practical openai codex agents.md best practices are to keep rules scoped, concrete, and reviewable. A strong first version has four parts: repository map, workflow rules, verification ladder, and MCP boundaries. Avoid vague style preferences unless reviewers will actually enforce them in pull requests.

• Should AGENTS.md live at the repo root or inside each service?

  Use a root AGENTS.md for repo-wide defaults, then add nested files where a service has different rules. One root file can cover package manager commands and PR expectations; a nested apps/api/AGENTS.md can cover migrations, auth, and API tests. The caveat is maintenance: every extra file needs an owner.

• How much MCP access should a Codex agent get?

  Give Codex the least MCP access needed to complete the task. A safe default is read-only access to linked issues and pull requests, with approval required before any write outside the working tree. The important artifact is a boundary note in AGENTS.md, not a verbal agreement in chat.

• Can Codex update AGENTS.md by itself?

  Yes, but treat AGENTS.md changes like changes to build scripts or CI config. Require review from the affected code owner and ask for one example workflow the new rule improves. The caveat is that Codex can propose conventions, but the team owns whether they are true and enforceable.

• How do we know a Codex diff is ready for review?

  A Codex diff is ready when the final note includes changed files, verification run, failures or skipped checks, and remaining risks. Use one small review checklist: scope, tests, unrelated diffs, security boundary, and rollback concern. If any item is missing, ask Codex to tighten the patch before a human review.

Further reading

• OpenAI Developers — Codex quickstart
• OpenAI Developers — Codex CLI
• OpenAI Developers — Codex CLI features
• OpenAI Developers — Codex slash commands
• Model Context Protocol — specification
• GitHub — openai/codex
• GitHub — openai/skills

Put one rule under review

Do not boil the ocean. Open one PR that adds the starter AGENTS.md, run one real Codex task against it, and let the review teach you which rule should become team convention.

One methodology lens

One useful way to read this through our methodology is the Plan step: delegate first-pass decomposition and dependency mapping, review the sequencing and assumptions, and keep ownership of scope and priorities. If that split is still fuzzy, the workflow usually is too.