Codex CLI boundaries

The fastest Codex CLI workflow is the one a reviewer can trust without replaying the chat, so the real job is to make the work reviewable before it gets clever. Codex CLI is OpenAI's coding agent that runs in your terminal, reads repo instruction files, and turns a task into a diff you can inspect. Most teams stall not because the model is weak but because the handoff is vague and the repo's own rules are buried where the agent never looks.

A bigger context window helps, but it is not the operating model. The operating model is three things you control: the repo instruction chain, the connector boundary, and the check that turns raw output into a diff someone can defend.

Write repo rules where the work lives

If you have shipped AI code, you have hit the moment where the task was clear to you and invisible to the agent. It had no local rule for architecture, naming, or how much to test, so it improvised.

Codex reads AGENTS.md and AGENTS.override.md, and it reads the nearest one first. Use that. Instead of one giant root file, write small nested instructions next to the code they govern. A rule about the payments module belongs in the payments folder, not in a 400-line note at the repo root.

The payoff is fewer "why did it do that?" reviews and more diffs that match the repo's existing habits. Put the rule where the work happens, and the agent stops guessing.

Treat MCP as a boundary, not a shortcut

MCP, the Model Context Protocol, is the standard way an agent connects to outside systems like a database, an issue tracker, or a deploy tool. The mistake is wiring in a connector and then acting surprised when the agent reaches further than you meant.

Write a short boundary note for every connector. Three lines is enough: what it may read, what it may write, and what needs a human yes before any write happens. This keeps external systems from turning into quiet side doors during a run.

The reward is cleaner review scope. When the boundary is written down, nobody has to reverse-engineer what the agent could have touched.

Run the verification loop every time

Codex CLI is strongest as a headless automation surface, not a one-shot prompt box. The difference is the loop you run around it.

Ask for the smallest useful change. Run the repo's own check. Read the diff for intent. If the check fails, rerun with the failure in view rather than rewriting the prompt from scratch. That loop is what moves a change from "looks right" to "can be trusted," and it is also what gets teams to stop arguing about style and start talking about behavior.

Here is the loop as a checklist you can paste into a repo today:

# Codex CLI verification loop

- [ ] Read the nearest AGENTS.md and any AGENTS.override.md files.
- [ ] Confirm the task scope in one sentence.
- [ ] List any MCP connectors involved and their write boundaries.
- [ ] Run Codex CLI with the smallest useful change.
- [ ] Verify the result with the repo's own test or check command.
- [ ] Inspect the diff for intent, not just syntax.
- [ ] Record what changed, what was verified, and what still needs human review.
- [ ] If the check fails, rerun with the failure in view.

It is plain on purpose. One operational habit beats five competing ones.

Hand reviewers a change, not a blob

Many Codex pilots lose their time here. The output may be correct, but the reviewer cannot see what was intended, what was verified, and what is still risky, so they re-run the whole conversation in their head.

Give them a small pack instead: one task, one scope, one verification note, one clear diff. The CLI keeps the work narrow, and the pack keeps the review narrow. Less back-and-forth, fewer "please explain this file" comments.

For repeat work, package the steps as a shared SKILL.md so the team is not starting from scratch every time. Use a skill when the steps are reusable across tasks, and keep the rule in AGENTS.md when it belongs to one codebase. That split keeps your Codex setup useful without turning every repo into a prompt museum.

Common questions

• What is the maximum context window for the Codex CLI agent?

  OpenAI's codex-1 model carries a large context window, and the official Codex docs at developers.openai.com/codex/cli are the place to check the current number since it changes across releases. More useful than the exact figure: context size is not your operating model. A clear AGENTS.md, a written connector boundary, and a verification loop do more for output quality than any token count.

• Where does Codex CLI read its instructions from?

  Codex reads AGENTS.md files, starting with the one nearest to the work, plus any AGENTS.override.md. This means you can nest small, specific rules deep in the tree rather than maintaining one giant root file. The nearest file wins, so put module-specific guidance in the module's folder and keep the root note short.

• How do I keep an MCP connector from reaching too far?

  Write a boundary note for each connector that lists what it may read, what it may write, and what requires human approval before a write. Codex respects the permissions you set, but the note is what keeps your team aligned on intended scope. Without it, reviewers cannot tell what the agent could have touched during a run.

• Why review the diff if the tests pass?

  Tests confirm behavior, but they do not confirm intent. Read the diff to check that the change matches what you asked for, stays inside the agreed scope, and leaves nothing risky behind. A passing suite on an over-broad change is still a problem. The diff review is where you catch scope creep that the checks happily ignore.

• When should I use a skill instead of an AGENTS.md rule?

  Use a SKILL.md when the steps are repeatable across many tasks and you want a reusable handoff. Use AGENTS.md when the rule belongs to a specific codebase and travels with it. The quick test: if you would copy the steps into another repo, it is a skill. If it only makes sense next to this code, it is a repo instruction.

Start with one artifact

Pick a single repo, write one short AGENTS.md and one connector boundary note, then run the verification loop above on a small change. For patterns to take into a team setting, see the related training topic.