Govern Codex Agents With Workflows

AI coding agents write code autonomously by reading repo context, planning edits, changing files, running tools, and looping on feedback until they hit a stop condition. Govern that loop with AGENTS.md rules, MCP boundaries, and review gates, not heroic prompting.

Agentic coding governance is the set of team rules that decides what coding agents may do, which tools they may use, and what evidence humans need before approving their work. For AI coding training and engineering team training, teach that operating model first; the AI IDE or CLI comes second.

Start with the agent loop

OpenAI Codex, OpenAI’s coding agent, is useful because it can move through a whole engineering task: inspect files, propose a plan, edit code, run checks, and revise. The same broad loop shows up across coding agents, including Claude Code, Anthropic’s coding agent, and Codex, Anysphere’s AI code editor.

Treat that loop like a workflow you own. A simple state machine is enough: intake -> plan -> edit -> verify -> review -> merge, with allowed transitions and required evidence at each step.

The trap is letting autonomy mean “skip the boring parts.” Autonomous does not mean unreviewed. It means the agent can perform more steps before a human intervenes, as long as the next checkpoint is clear.

As of June 2026, projects like Aharness point at a healthy coding agents news pattern: teams are trying to enforce agent workflows instead of trusting chat transcripts. You do not need a special framework to start. You need one convention that every agent and reviewer can see.

Put the convention in AGENTS.md

Put the shared rules where Codex can read them. In a Codex repo, that usually means an AGENTS.md file near the code it governs, with narrower nested files for subprojects that need different rules.

Keep it short enough to obey. The file should tell the agent how to plan, what it may change, how to verify, and when to stop.

The trap is turning AGENTS.md into a policy landfill. If a rule does not affect daily edits or review, move it to docs and link it only when needed.

Paste this into a repo and adapt it:

# AGENTS.md — Codex workflow convention

## Scope
This file applies to this repository unless a nested AGENTS.md gives a narrower rule.

## Workflow states
- Intake: restate the task, identify the touched area, and read nearby tests before editing.
- Plan: propose the smallest safe change. Do not edit more than one subsystem without asking.
- Edit: make focused changes. Preserve public APIs unless the task explicitly asks for an API change.
- Verify: run the narrowest meaningful checks first, then the broader suite if the change touches shared code.
- Review: summarize changed files, behavior changes, verification results, and known risks.

## Tool boundaries
- Do not use write-capable external tools unless the task explicitly permits them.
- Use MCP servers only for the named system and purpose in the task.
- Never copy secrets, customer data, or private credentials into prompts, logs, commits, or review notes.

## Verification loop
Before asking for review, run:
- formatter or linter for touched files
- unit tests for touched package
- one integration or smoke check when behavior crosses a service boundary

If a check cannot run, record:
- command attempted
- reason it failed
- what a human should run next

## Review checklist
A reviewer should approve only when:
- the task and plan match the final diff
- the diff is smaller than the stated scope
- verification evidence is present
- risky tool use is disclosed
- follow-up work is tracked outside the PR

This is the convention. The important part is not the exact words; it is that the agent, author, and reviewer share the same states.

Adopt it as a team rule, not a prompt trick

Have one engineer propose the first AGENTS.md in a normal pull request. Ask the code owners for the touched areas to review it, because they know which shortcuts are dangerous.

Keep the root file for repo-wide rules. Add nested AGENTS.md files only where local constraints differ, such as mobile/AGENTS.md, api/AGENTS.md, or infra/AGENTS.md.

The review rule is simple: no agent-authored PR gets approved unless it includes a review note with the workflow state, verification commands, and known risks. This is a code review guardrail, not a vibe check.

The trap is centralizing everything in one platform owner’s document. AI coding governance works better when the rule lives next to the code and changes through the same review process as the code.

If you are building a broader program, connect this convention to the related training topic so workshops, onboarding, and review practice teach the same habits.

Keep tools behind explicit MCP boundaries

Model Context Protocol, or MCP, is a standard way for agents to connect to external tools and data sources. In agentic coding, it is where a local coding task can accidentally become a production-impacting workflow.

Write down which MCP servers are read-only, which are write-capable, and which require human approval. A GitHub MCP server used to read issues is very different from one allowed to open PRs, change labels, or touch releases.

The trap is treating MCP as “just context.” It is also capability. Give Codex the smallest tool surface that lets it finish the task, and make write access explicit in the task or ticket.

A useful boundary note in a task might be: “Use the docs MCP server for read-only product docs lookup. Do not use Jira, Slack, database, or deployment tools for this change.” That one sentence can prevent a surprising amount of wandering.

Review the run, not just the diff

Review the final code, then review the run that produced it. A clean diff is not enough if the agent skipped tests, widened scope, or used a tool it should not have touched.

Ask for the short evidence bundle: planned scope, files changed, commands run, failures, and unresolved risks. This gives reviewers something concrete to check and gives newer engineers a repeatable model for AI coding for engineering teams.

The trap is asking the agent for a beautiful summary after the fact. Summaries are helpful, but they are not proof. Prefer command output, CI links, test names, and small diffs.

For a deeper companion pattern, see How Autonomous Coding Agents Ship Safely. The shared idea is simple: autonomy is safest when verification is part of the workflow, not a separate cleanup step.

Common questions

• How do AI coding agents write code on their own?

  AI coding agents work by turning a task into repeated tool use: read files, plan a change, edit code, run checks, and revise from errors. The useful governance number is not “fully autonomous”; it is how many steps the agent may take before a required checkpoint such as plan review, test evidence, or PR approval.

• Should we use a state machine for Codex work?

  Yes, use a lightweight state machine when your team needs repeatable behavior across agents and reviewers. Five or six states are usually enough: intake, plan, edit, verify, review, and merge. More states can help regulated work, but they also create ceremony that engineers may route around.

• Where should agent rules live: AGENTS.md, CLAUDE.md, or somewhere else?

  Put Codex-facing repo rules in AGENTS.md, and put tool-specific memory in that tool’s expected file when your team uses it. For example, a team using Claude Code may keep durable Claude instructions in CLAUDE.md, while still keeping cross-tool architecture and review rules in AGENTS.md near the code.

• How strict should MCP access be for coding agents?

  MCP access should be least-privilege by default. Start with read-only tools for docs, issues, and code search, then grant write-capable tools only for named workflows. The caveat is developer productivity: too little access creates copy-paste work, so review the boundary after a few real PRs.

• Is this overkill for a small team?

  No, as long as the convention stays small. A single AGENTS.md plus a review checklist is enough for many teams. The moment it feels like a compliance program, cut it back to the rules that actually prevent bad diffs, unsafe tool use, or unverifiable changes.

Further reading

• OpenAI Developers — Codex quickstart
• GitHub — openai/codex
• Claude Code — getting started
• GitHub — anthropics/skills
• Codex — Agent
• Model Context Protocol — specification
• OWASP — Top 10 for Large Language Model Applications
• NIST — AI Risk Management Framework
• Google Search Central — helpful, people-first content
• Google Search Central — generative AI content guidance
• GitHub — Alfredvc/aharness

Make the next PR the pilot

Pick one repo, add the AGENTS.md convention, and require the review checklist on the next Codex-assisted PR. Keep what helps, delete what nobody uses, and let the workflow earn its place.

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.