Govern Autonomous Codex Workflows

AI coding agents write code autonomously by turning a goal into a loop: inspect the repo, plan a change, edit files, run checks, read failures, and try again until the task is ready for review. For OpenAI Codex, OpenAI's coding agent, the safest move is to make that loop explicit in AGENTS.md and code review, not hope each prompt remembers it.

Agentic coding governance is the team practice of defining what an agent may do, which tools it may call, and what evidence it must produce before humans merge its work. This is where ai coding governance, agentic coding training, and normal engineering discipline meet.

Start with states, not vibes

Treat the agent workflow as a small state machine. A state machine is a workflow where work moves through named states with allowed transitions and exit criteria.

A Show HN project called Aharness is a useful signal here: it explores enforcing Codex workflows as state machines. The important idea is tool-agnostic. A team can get most of the value by naming the states in plain markdown before buying or building enforcement software.

A good first pass is Intake, Plan, Edit, Verify, Summarize. The agent should not jump from Intake to Edit on risky work, and it should not claim completion before Verify produces evidence.

The trap is making the state machine too clever. If engineers cannot remember it during review, Codex will not reliably follow it during a messy task.

For teams building an ai coding workshop or engineering team training path, keep the first version boring. The practical answer to how AI coding agents write code autonomously is operational rather than magical: they follow a bounded loop, and your job is to make the loop inspectable.

Put the workflow where Codex can read it

Put durable rules in AGENTS.md, close to the code they govern. Use a root AGENTS.md for repo-wide rules, then nested files for local constraints such as services/billing/AGENTS.md or packages/mobile/AGENTS.md.

The rule should say what Codex must do, not what the team hopes it will infer. For example: before editing a database migration, inspect the existing migration pattern, propose the rollback path, and run the migration test command listed in this directory.

This matters because coding agents are context machines. They perform better when repo conventions are written in the same place they are doing the work.

The trap is turning AGENTS.md into a junk drawer. Keep architectural rules, verification commands, and safety boundaries there. Put task-specific notes in the prompt or issue instead.

For broader patterns across agentic coding and code review guardrails, see the related training topic and this companion guide on Make Coding Agents Follow a Workflow.

Bound MCP and tools before granting autonomy

MCP, the Model Context Protocol, is the integration layer agents use to reach tools such as GitHub, issue trackers, docs, databases, and internal systems. Treat every mcp server like a capability grant, not a convenience toggle.

Start with read-only access. Let Codex inspect GitHub issues, documentation, and build logs before you let it write labels, open tickets, mutate data, or trigger deployment actions.

The same convention can travel to Codex, Anysphere's AI code editor, or Claude Code, Anthropic's coding agent, but Codex users should start with the Codex CLI verification loop they already trust. Whether the agent runs in a CLI or an AI IDE, the governance question is the same: what can it touch, and what proof must it bring back?

The trap is giving broad tool access because the demo feels smooth. Developer productivity improves when the agent has the right tools. It falls apart when the agent can take actions the reviewer cannot reconstruct.

Copy this AGENTS.md convention

Paste this into a root AGENTS.md, then trim it for your repo. The convention is intentionally small. It gives Codex a workflow, gives reviewers a checklist, and gives engineering leaders a repeatable training artifact.

# Coding agent workflow convention

Applies to: OpenAI Codex, Codex CLI, and any agent editing this repository
Owner: Engineering Productivity
Reviewers: tech lead for the changed area plus one maintainer

## State machine

Every agent task must move through these states.

- Intake
  - Restate the task in repo terms.
  - Identify touched packages, services, and tests.
  - Stop if the task requires secrets, production access, or unclear product judgment.

- Plan
  - List the intended files or directories.
  - Name the verification commands before editing.
  - Ask for human confirmation when the change affects auth, billing, data deletion, permissions, or deployments.

- Edit
  - Make the smallest coherent change.
  - Preserve local style and existing abstractions.
  - Do not perform drive-by refactors unless the plan explicitly includes them.

- Verify
  - Run the narrowest relevant checks first.
  - Run broader checks when shared code, generated code, schema, or build config changes.
  - Record command, result, and any remaining risk.

- Summarize
  - Explain what changed.
  - Include verification evidence.
  - Call out skipped checks, assumptions, and follow-up work.

## Allowed transitions

- Intake may move to Plan or Stop.
- Plan may move to Edit or Stop.
- Edit may move to Verify.
- Verify may move back to Edit only to fix a failed check.
- Verify may move to Summarize only after evidence is recorded.
- Summarize may move to human review.

## MCP and tool boundaries

- Read-only MCP access is allowed for repo docs, issues, and build logs.
- Write access through MCP requires the task prompt to name the system, action, and rollback path.
- Production data, customer data, secrets, deploy actions, and billing systems require human approval outside the agent session.
- The agent must not paste secrets into prompts, logs, commits, or summaries.

## Codex CLI verification loop

Before marking work complete, run the verification commands named in Plan.
If a command fails, inspect the failure, make a targeted fix, and rerun the command.
If a command cannot run, record why and name the human follow-up.

## Skills handoff

Use team skills for repeatable procedures such as release checks, migration reviews, incident debugging, or generated-code updates.
Repository rules live here. Reusable playbooks live in skills.

## Review checklist

- [ ] The PR summary includes the final state and verification evidence.
- [ ] The touched directory has an AGENTS.md rule or the root rule is sufficient.
- [ ] MCP use stayed within the stated boundary.
- [ ] Risky areas such as auth, permissions, billing, data deletion, and deployment were reviewed by a human owner.
- [ ] Failed or skipped checks are explained, not hidden.
- [ ] The change is small enough for a reviewer to reason about.

Adoption path: one engineer proposes the convention in a normal PR, two service owners review it, and the team agrees where it lives. Then add one nested AGENTS.md in the riskiest service first, not in every directory at once.

The enforcement rule is simple: no agent-authored PR merges unless the summary includes the state path, verification evidence, and any MCP actions taken. Reviewers should reject missing evidence the same way they reject missing tests.

Train the team on the review habit

Use one small internal exercise before rolling this out widely. Give three engineers the same low-risk Codex task, ask each to use the convention, then compare the summaries and verification logs.

This is better ai coding training than a slide deck because the team sees where the workflow bends under real repo pressure. It also turns coding agents news into a practical question: what should our team change on Monday?

The trap is measuring only speed. Autonomous work that saves ten minutes but creates a vague review can cost the team an afternoon later.

A good workshop exercise is a dependency update, a failing test fix, or a small API rename. Avoid auth, migrations, and production systems until the habit is boring.

Common questions

• How do AI coding agents write code autonomously?

  AI coding agents write code autonomously by repeating a tool-using loop: read files, form a plan, edit, run checks, and revise from errors. The citable artifact is the verification log: command, result, and remaining risk for each change. Without that log, autonomy becomes a hidden process rather than an engineering workflow.

• Is a state machine overkill for small teams?

  No, a lightweight state machine is often enough for small teams because it names the moments where mistakes happen. Five states, Intake, Plan, Edit, Verify, and Summarize, fit in one AGENTS.md file. The caveat is to avoid building a process engine before the review habit exists.

• Should MCP servers be available to every coding agent?

  No, MCP servers should be granted by task and risk, not enabled by default for every agent. Start with read-only systems, then add write access only when the workflow has a named state, owner, and rollback plan. Treat production data and customer systems as separate approvals.

• Where should team skills live: AGENTS.md or SKILL.md?

  Put durable repository rules in AGENTS.md and reusable procedures in a skill file when the procedure needs templates, scripts, or examples. A migration checklist, incident debugging routine, or release playbook fits better as a team skill. The caveat is activation: the description must make clear when to use it.

Further reading

• OpenAI Developers — Codex quickstart
• GitHub — openai/codex
• Codex — Agent
• Claude Code — getting started
• Model Context Protocol — specification
• GitHub — anthropics/skills
• 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

Start with one bounded workflow

Pick one repo, one service, and one safe Codex task. Add the AGENTS.md convention, require verification evidence in review, and let the team improve the workflow after three real PRs.

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.