Agent-readable media assets: AGENTS.md, CLAUDE.md, .mdc rules

Agent-readable Markdown files make delegated coding work reviewable from the repository, not from a chat transcript. Agent-readable docs are plain Markdown contracts that a coding agent loads before it edits. In practice, that means .mdc rules for Cursor, Anysphere's AI code editor, CLAUDE.md for Claude Code, Anthropic's coding agent, and AGENTS.md for Codex, OpenAI's coding agent.

Put the contract where the diff lands

The fix for unexplainable agent changes is not better chat discipline. It is a contract that lives beside the work.

A wiki page can describe policy, but it does not travel with the patch. A chat prompt can steer one run, but it disappears from normal review. When the operating contract exists only in one operator's session history, every agent-assisted change has a bus factor of one.

A reviewer needs three facts from the repo: what the agent was allowed to touch, which policy won when instructions conflicted, and how the change was verified. If those facts are missing, green tests only prove that one command passed.

Write the file each tool will actually read

Cursor rules should name scope. A .mdc file should say which paths are allowed, which paths are forbidden, which Model Context Protocol (MCP) servers or tools are in bounds, and who owns the merge decision. Cursor's rule docs are the place to check how rules are loaded and scoped.

Claude Code needs visible precedence. Put the order of operations in CLAUDE.md, especially where repository hooks override local preferences and where human approval is required. The Claude Code docs and hooks model are the right references when you define that boundary.

Codex needs a run record. Treat AGENTS.md as the file that preserves intent, command, result, and diff summary for CLI work. The tool flow belongs in the Codex quickstart; the review trail belongs in the repo.

Use one scope ledger before the next delegated run

Start with a small artifact that a reviewer can compare against the diff. Do not begin with tone rules or style preferences. Scope, precedence, and verification do more work.

Paste this into the relevant repo file, then adjust the paths and commands before the agent runs:

# Agent run contract

Goal: update documentation examples only.

Allowed paths:
- docs/**
- .cursor/rules/**

Forbidden paths:
- src/**
- infra/**
- security/**

Policy precedence:
- Repository rules override local session preferences.
- Files under security/ require human review before merge.
- Temporary overrides must be written in notes/overrides.md and removed before merge.

Verification:
- Run docs lint.
- Run link check.

Run record:
- Intent: refresh docs examples.
- Command: npm test -- docs
- Result: passed; link check clean.
- Diff summary: updated examples and one reference link.

Merge owner: platform reviewer.

For Cursor, put the scope portion in the appropriate .mdc rule. For Claude Code, put precedence and approval zones in CLAUDE.md. For Codex, keep the run record in AGENTS.md so the next reviewer does not need a terminal screenshot.

Roll it out as a review rule, not a documentation project

Rollout is four moves. Add one policy file per tool. Lead with scope and precedence rather than style. Require the PR body to quote the relevant file and proving command. Reject merges that cannot be replayed from Markdown alone.

This is also a team-conventions problem. If the same repo uses Cursor, Claude Code, and Codex, the convention should say how the files relate to each other and which one wins when instructions conflict. Keep that convention with the code, and point new operators to your team conventions before they delegate work.

In our methodology, this is the documentation work that makes review cheaper later. Markdown does not replace access control, test coverage, or human judgment. It makes delegation inspectable, which is the part most teams lose first.

These files are the flight recorder, not the autopilot. They do not make the change safe by themselves, but they let a reviewer say what happened.

Common questions

• What is the purpose of AGENTS.md in Codex?

  AGENTS.md preserves the operating contract and run history for Codex work so a reviewer can replay the change from the repository. A useful entry records intent, the command that ran, the result, and a short diff summary. Without it, review depends on memory, screenshots, or a chat transcript outside the repo.

• Are Markdown files the right agent-readable media assets for a repository?

  Yes. Markdown is the right default because Cursor, Claude Code, and Codex can all use repo-local Markdown files as operating context. The value is not the file format by itself. The value is that scope, precedence, and verification become reviewable source artifacts instead of private instructions.

• Does Codex use Markdown for documentation?

  Yes. Codex uses AGENTS.md, a plain Markdown file in the repository, to guide CLI work and preserve instructions. Treat it with the same review standard as Cursor .mdc rules and Claude Code CLAUDE.md: a new teammate should understand the run from intent, command, result, and diff summary.

• What should the first lines of an agent rule file cover?

  Start with scope, precedence, and verification. Name allowed paths, forbidden paths, approval zones, the proving command, and the merge owner. Style guidance can come later. A reviewer should be able to compare the rule against the diff before reading any generated code or prose.

• Do we need a special agentic Markdown editor to maintain these files?

  No. These are plain repository files, edited and reviewed like any other source file. The hard part is not tooling. The hard part is writing a clear contract that survives handoff: what the agent may touch, what it may not touch, and how the result is proved.

Further reading

• Cursor rules documentation
• Cursor docs
• Claude Code docs
• Claude Code hooks
• OpenAI Codex quickstart
• OpenAI Codex docs
• Model Context Protocol specification
• NIST AI Risk Management Framework
• OWASP Top 10 for LLM Applications

Review one delegated change this way

Pick one recent agent-assisted PR and ask whether the repo shows scope, precedence, and verification. If it does not, add the smallest .mdc, CLAUDE.md, or AGENTS.md contract that would have made the review replayable.