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

The diff was clean, the tests were green, and nobody could explain the change from the repo alone. That review-queue moment is where agent-readable media assets earn their name. Agent-readable docs are plain Markdown contracts that a coding agent loads before it edits: .mdc rules for Cursor, CLAUDE.md for Claude Code, and AGENTS.md for Codex. Markdown files, not dashboards or wikis, are the media assets that decide how delegated work gets reviewed.

The change nobody could explain

Counter-thesis: the fix for unexplainable agent changes is not more chat discipline; it is a contract that lives where the work lands.

The wrong path: We kept policy in the wiki and the chat thread and believed careful prompting would carry it. The first clean-looking change nobody could explain from the repo alone ended that belief.

Diagnosis: this is the bus factor, applied to delegation. When the operating contract exists only in one operator's session history, every agent-assisted change has a bus factor of one, and the bus arrives at review time.

Thesis: if the repo cannot show what the agent was allowed to touch, which policy won, and how the change was verified, review is a guess.

Cursor, Claude Code, and Codex leave different traces, and those traces only help if reviewers can read them as one operating system. Nobody needs a special agentic markdown editor for this; the files are source files.

Three contracts that hold up in review

Named fix: the scope ledger. Cursor works best when the rule file names the boundary instead of implying it:

- Goal: update docs only; no code-path changes.
- Allowed paths: docs/**, .cursor/rules/**
- Forbidden paths: src/**, infra/**
- Verification: run docs lint and link check
- Merge owner: platform reviewer

A reviewer compares this against the diff and the path list. No archaeology required.

Named fix: the precedence block. Claude Code needs a visible order of operations where the session starts, per the docs and hooks model:

## Policy precedence
1. Repository hooks override local session preferences.
2. Files under `security/` require human review.
3. Temporary overrides must be written in `notes/overrides.md` and removed before merge.

Named fix: the run record. Most searches for Codex AGENTS.md docs are really asking one thing: what makes a run reviewable later. Treat AGENTS.md as Codex documentation that ships with the repo, holding intent, command, and result in one place:

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

The Codex Markdown contract keeps review from depending on a terminal screenshot or memory; the quickstart covers the tool half.

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 the proving command, and reject merges that cannot be replayed from Markdown alone. In our methodology, this is the Document step doing the Review step's prep work, the same trade described in returning Markdown from docs. Markdown does not replace access control, test coverage, or human judgment. It makes delegation inspectable, which is the part most teams lose first; the wider practice lives under AI coding governance.

One image: these files are the flight recorder, not the autopilot. They fly nothing, and they are the only reason anyone can say what happened.

Best ways to use this research

• Best for: Cursor teams deciding which rule, subagent, skill, or MCP boundary to write down before the next delegated run.
• Best first artifact: one scope ledger in .mdc with allowed paths, forbidden paths, verification command, and merge owner.
• Best comparison angle: compare your current review path against these three contracts; keep the one that leaves the shortest auditable trail.

Common questions

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

  AGENTS.md is the Codex file that preserves intent and run history so a reviewer can replay CLI work from the repo alone. A useful run record holds four lines: intent, the command that ran, the result, and a diff summary. Review stops depending on memory.

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

  Yes, because Cursor, Claude Code, and Codex all read them natively as .mdc rules, CLAUDE.md, and AGENTS.md. Markdown does not replace access control, test coverage, or human judgment; it makes delegation inspectable, which is the part teams lose first as agent use spreads.

• Does Codex use Markdown for documentation?

  Yes. Codex reads AGENTS.md, a plain Markdown file in the repository, as its operating contract for CLI work. The same review standard applies as for Cursor's .mdc rules and Claude Code's CLAUDE.md: a reviewer should be able to replay the run from intent, command, and result.

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

  Scope, precedence, and verification, not style. A scope ledger naming allowed paths, forbidden paths, the verification command, and the merge owner gives reviewers something to compare against the diff. Reject merges where the agent output cannot be replayed from the Markdown alone.

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

  No. The files are plain Markdown that lives in the repository and gets edited like any other source file. What matters is the content: a .mdc scope ledger, a CLAUDE.md precedence block, and an AGENTS.md run record a new teammate can read without the chat log.

Further reading

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

Next step

If you want these three files reviewed against a real repo, get in touch and bring one .mdc, one CLAUDE.md, and one AGENTS.md.