AGENTS.md for Codex Teams

Codex app 26.616 should trigger a small workflow check, not a scramble: make sure your AGENTS.md tells Codex how to edit, verify, and explain changes. OpenAI Codex, OpenAI's coding agent for software teams, is most useful when the Codex CLI starts with clear repo rules and ends with reviewable diffs.

AGENTS.md is a repository instruction file that gives a Codex agent durable context about how your team wants work done. In practical Codex CLI training, the file is less about clever prompting and more about boring reliability: scope, MCP access, verification, and review notes.

Treat app 26.616 as a workflow checkpoint

As of June 18, 2026, the official Codex changelog marks Codex app 26.616. The useful team move is to rerun your operating checklist after the app update: open a real task, ask Codex for a small change, inspect the diff, and confirm the verification loop still matches your repo.

Do this in a production-shaped branch, not a toy folder. For example, ask Codex CLI to update a validation helper in packages/billing, run the same lint and test commands a human would run, and return a PR-ready summary.

The trap is treating a version marker as permission to loosen process. Changelogs tell you what shipped; your AGENTS.md tells Codex what is safe in your codebase. Keep those concerns separate.

For the broader practice, keep this convention near your team's Codex CLI workflows topic so engineers learn it as part of the normal loop, not as tribal knowledge.

Put durable rules in AGENTS.md

Use AGENTS.md for rules that should survive many tasks: architecture boundaries, package managers, test commands, naming conventions, and review expectations. Whether your team calls it AGENTS.md for Codex, codex agents md, or simply repo instructions, the file should answer one question: what would a careful teammate check before touching this code?

A good root file might say that API changes require contract tests, migrations must include rollback notes, and generated files should not be edited by hand. A nested packages/mobile/AGENTS.md can then add platform-specific commands without making the root file noisy.

The trap is dumping everything into one giant root instruction file. Local scope matters. Put shared rules at the root, package rules beside the package, and task-specific details in the Codex prompt or issue.

Keep MCP access explicit

Model Context Protocol, the open protocol for connecting agents to external systems, is powerful because it lets Codex work with context outside the repo. That also makes it worth naming the boundary in AGENTS.md.

A simple MCP boundary note might say: GitHub is read-only unless the task explicitly asks for a PR, Jira can be read for acceptance criteria, and production databases are never queried from the agent session. That gives Codex useful rails without pretending every integration is equally safe.

Before letting Codex read or write through MCP, run the habit in Check Codex MCP Access. The trap is granting broad access and relying on the final diff to reveal mistakes. By then, the agent may already have touched systems you did not mean to involve.

Make Codex prove the change

A Codex workflow should end with evidence, not vibes. Ask for the smallest diff, the commands run, the result, and any blocker that prevented verification.

For a TypeScript service, that might mean pnpm lint, pnpm test -- --runInBand, and a focused integration test for the changed route. If your repo has a pre-push hook, put the hook command in AGENTS.md so Codex and humans share the same finish line.

The trap is accepting a polished explanation without a reproducible check. Codex can be helpful and still miss a package-specific test, a generated file, or a migration edge case. Review the diff as code, not as a conversation transcript.

Adopt the convention like code

Paste this into a root AGENTS.md, then trim it to match your repo. Keep the commands real. A wrong command in AGENTS.md is worse than no command because it teaches every future Codex run the same mistake.

# AGENTS.md

## Purpose
This repository uses OpenAI Codex through the Codex CLI for small, reviewable changes.
Codex should optimize for clear diffs, repeatable verification, and honest handoff notes.

## Working rules
- Read this file and the nearest nested AGENTS.md before editing.
- Prefer the smallest diff that solves the task.
- Do not reformat unrelated files.
- Do not edit generated files unless the task says to regenerate them.
- Ask before changing public APIs, database schemas, auth logic, or billing behavior.

## Repo commands
- Install dependencies: pnpm install
- Lint: pnpm lint
- Unit tests: pnpm test -- --runInBand
- Typecheck: pnpm typecheck
- Pre-push hook equivalent: pnpm lint && pnpm typecheck && pnpm test -- --runInBand

## MCP boundaries
- GitHub MCP: read issues, PRs, and CI results; only create or update PRs when requested.
- Jira MCP: read acceptance criteria and linked design notes; do not change ticket state.
- Database MCP: do not query production data.
- Never request secrets, tokens, or credentials in chat.

## Verification loop
Before the final response, Codex should report:
- Files changed.
- Commands run and whether they passed.
- Commands not run, with the exact blocker.
- Risky areas a reviewer should inspect.

## Review checklist
- The diff matches the requested task.
- The smallest reasonable set of files changed.
- Tests, lint, or typecheck results are listed.
- MCP access stayed within the boundary above.
- Public API, migration, auth, and billing changes are called out.

Adoption should be lightweight. One engineer proposes the AGENTS.md change in a normal PR, the owning team reviews it like production code, and the file lives at the repo root with nested copies only where local rules differ.

The review rule is simple: any PR created with Codex should include verification notes that match AGENTS.md. If the notes are missing, stale, or hand-wavy, ask for a rerun before reviewing the code.

Common questions

• How should AGENTS.md work with Codex?

  Use AGENTS.md as the durable instruction layer for Codex, not as a task prompt. The practical agents md codex convention is to keep repo rules, verification commands, MCP boundaries, and review expectations there, then put one-off goals in the Codex CLI prompt or issue. Nested AGENTS.md files should override broad root guidance when a package needs special handling.

• What is a Codex agent?

  A Codex agent is an OpenAI Codex session that can reason over code, propose edits, and help run a coding workflow through surfaces such as the Codex CLI. Treat it like a fast teammate with limited local knowledge: give it repository rules, constrain tool access, and require a reviewable diff before merging.

• Should AGENTS.md include MCP permissions?

  Yes, include MCP boundaries when Codex can reach external systems. The file should say which systems are read-only, which write actions require explicit task approval, and which systems are off limits. This is especially useful for GitHub, Jira, document stores, and databases where the cost of a mistaken write is higher than a bad code suggestion.

• What is the OpenAI codex-1 agent maximum context tokens limit?

  Do not hard-code a context-token number in AGENTS.md unless your team has verified it against current OpenAI documentation. Search results for openai codex-1 agent maximum context tokens 2025 can be stale, and limits may vary by model, product surface, or date. As of June 2026, write instructions that stay concise instead of relying on one remembered limit.

• Do we still need code review if Codex ran the tests?

  Yes, code review still matters. Tests prove selected behavior, while review checks intent, maintainability, architecture, security, and whether the diff belongs in the codebase at all. Your Codex workflow should make review easier by producing small diffs and clear verification notes, not by asking reviewers to trust the agent.

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
• OpenAI Developers — Codex changelog

Start with one repo

Pick one active service, add the AGENTS.md convention, and require Codex verification notes on the next three agent-assisted PRs. If reviewers stop asking the same setup questions, promote the pattern to the rest of the team.

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.