Use Codex CLI Docs for Teams

Start with the official OpenAI pages, but do not stop there. For a Codex team, the Codex CLI docs answer the command and feature questions; the repo still needs AGENTS.md rules, MCP limits, and a verification loop so the agent works inside your codebase instead of around it.

That is how I frame Codex CLI training with engineering teams: product docs for product behavior, repository instructions for local judgment. Keep the shared operating model close to your CLI workflows, then make each repo carry its own rules.

Treat the official docs as the baseline

The Codex CLI official documentation should be the source of truth for CLI behavior, flags, and supported features. Do not copy a teammate's old shell alias into onboarding docs and call that the standard.

Use the official docs to decide what Codex can do. Use AGENTS.md to decide what Codex may do in this repo.

For example, if a service has generated files, migration rules, or a slow integration suite, that belongs in AGENTS.md. The CLI docs cannot know that your team never edits generated OpenAPI clients by hand.

If the team is still setting up the tool, I would pair this article with Install Codex CLI for Team Workflows and keep this page focused on the working loop after installation.

Put repo judgment in AGENTS.md

AGENTS.md should carry durable rules that apply across tasks. Keep prompts for a specific bug out of it.

I like nested AGENTS.md files because local scope matters. A frontend package can require component tests and accessibility checks, while a backend package can require migration review and contract tests.

Write instructions that are easy to obey. If the agent has to infer the test command from six paragraphs, the file is too vague.

Make MCP read-only first

Use MCP when Codex needs a live system, not when a file in the repo is enough. With MCP, the agent reaches another system through a declared server rather than through pasted credentials or ad hoc browser work.

Start with read-only access. A GitHub or issue-tracker MCP server can help Codex inspect context before editing code, while write access should wait until the team has logging, approval, and rollback habits.

This limit keeps the workflow understandable. A coding agent that can read tickets and docs is easier to review than one that can also change labels, close issues, update project boards, and push branches in the same pass.

Require a verification receipt

Do not accept agent work because the diff looks plausible. Ask for the command it ran, the result, and the reason that command covers the change.

This is the Review step in our methodology: the human does not replay every token, but they do require evidence before they trust the result. For a small backend change, that might be one focused unit test plus a typecheck; for a UI change, it might be a component test plus a screenshot review in the team's normal tooling.

A concrete workflow I use in repos is simple: ask Codex to inspect the scripts, choose the smallest relevant test, run it, then summarize the diff and command output in the PR note. If it cannot run the check, it must say why and name the next human action.

Use this team loop

Use this procedure when you turn the docs into a repeatable Codex workflow for one repository.

1. Link the official Codex CLI docs from your internal onboarding page.
2. Add or update AGENTS.md with repo-specific rules, test commands, and forbidden edits.
3. Connect only the MCP servers needed for the first workflow, preferably read-only.
4. Ask Codex to make one small change and produce a verification receipt.
5. Review the diff, the command output, and any files the agent chose not to touch.
6. Promote the workflow only after two or three ordinary tasks succeed without special coaching.

The limit is important. A workflow that only works when the most experienced engineer stands over it is not a team workflow yet.

Paste this AGENTS.md starter

# AGENTS.md

## Scope
These instructions apply to this repository unless a nested AGENTS.md file gives a more specific rule.

## Working rules
- Read the relevant package scripts before changing code.
- Prefer the smallest safe diff that solves the task.
- Do not edit generated files by hand.
- Do not introduce a new dependency without explaining why existing code is not enough.
- When an MCP server is available, use read-only lookup before taking action in external systems.

## Verification
Before calling the task complete, run the narrowest command that proves the change.

Use these commands when they apply:
- Typecheck: npm run typecheck
- Unit tests: npm test -- --runInBand
- Lint: npm run lint

If a command cannot run, report:
- The exact command attempted
- The failure or missing prerequisite
- The safest next human step

## Final response
Summarize:
- Files changed
- Verification commands and results
- Any risk or follow-up work

Change the commands before you commit this file. The point is not the exact npm scripts; the point is that Codex knows what evidence your team expects.

Further reading

• Codex CLI docs
• Codex CLI features
• Codex on GitHub

Put one repo on rails

For a guided version, bring one service repo to our hands-on training on Codex CLI workflows and leave with a scoped AGENTS.md, an MCP boundary, and a verification loop.