Markdown files for coding agents: the real interface

The markdown files in your repo are the real interface a coding agent obeys, not the prompt you typed and forgot. A markdown file for a coding agent is a plain-text contract that says what the agent may touch and what it must report back. Cursor, Anysphere's AI code editor, reads .mdc rules; Claude Code reads CLAUDE.md; Codex CLI reads AGENTS.md. If a boundary lives only in chat, the agent cannot follow it and your reviewer cannot check it.

This matters most at review time. A one-word "LGTM" on an agent diff is a signature on a contract nobody wrote down. The fix is to move the contract into a file, so the boundary survives the session, gets diffed, and shows up in the PR.

Why the file beats the prompt

A prompt improves one session. A file improves every session that follows, including the ones run by teammates you have not hired yet.

Tool vendors ship fast, and connectors tend to multiply faster than anyone updates the ownership map. The written contract is the slower, more boring thing that keeps pace with how your team actually reviews. When ownership is fuzzy in the org, it shows up as fuzzy language in the rules file, and the agent runs that fuzz at machine speed.

So the goal is plain: write the boundary once, let every tool read it, and keep the wording honest about who owns what.

Set up the four files that do the governing

Most agent review pain traces back to four gaps. Each one has a small markdown artifact that closes it.

Claude permission creep. Run Claude Code on a shared laptop and bash approvals turn into muscle memory. Hooks help, but precedence needs to be written down. The Claude Code getting started guide wires up hooks and leaves the precedence question open. Put a supremacy clause at the top of CLAUDE.md: which hooks win, which folders need human eyes, where temporary overrides live. Sessions stop inventing policy mid-run because the rules are on the page.

Codex replay gaps. Lean on Codex CLI, OpenAI's coding agent, and you can merge a green build the reviewer never actually saw. The Codex quickstart starts the session but produces no record a reviewer can replay. Make AGENTS.md mandate a replay sandwich: an intent line, then the command transcript, then a diff summary, before any PR. Now review works without standing behind someone's terminal.

MCP blast radius. Wire up MCP quickly and you will eventually find a connector touching data nobody put on the diagram. The Model Context Protocol specification defines capabilities; drawing the least-privilege boundary is on you, and the OWASP Top 10 for LLM applications is blunt about what happens when nobody draws it. Write one connector card per MCP server: allowed actions, forbidden actions, owner, rollback. Incidents shrink because operators know what "off" looks like.

Recursive handoff blur. Chain agents together and the summaries start dropping child-owned paths, the old telephone game. Require a child receipt block: every child returns the paths it touched, the commands it ran, and the tests proving its regression guards. Parents stop green-lighting mystery diffs on confidence alone.

Here is the portable version that fits in one boundary file:

---
description: Delegation boundary snapshot (adapt globs to your repo)
globs:
  - "**/*"
alwaysApply: false
---

- Cursor: keep scopes explicit in `.mdc`; forbid undeclared MCP domains.
- Claude Code: cite `CLAUDE.md` precedence before expanding bash scope.
- Codex: ensure `AGENTS.md` carries replay-friendly verification notes for CLI runs.

Cursor reads its .mdc rules the same way: the Cursor agent docs describe the machinery, and your rules supply the boundaries. The public OpenAI Skills repository makes the same point from the other side, where a skill is just a markdown file with one job. This is the file layer that agentic coding governance keeps circling back to.

Give reviewers a gate they can answer from files

Reviewers need four answers, and every one should come from a file instead of a hallway conversation.

Paste this into your PR template so the reviewer has a checklist instead of a vibe:

• MCP connectors mentioned (if any) list owners.
• Verification command output is pasted or linked.
• Forked agent work lists parent + child responsibilities.
• Red-folder paths received explicit human acknowledgement.

Know where the pattern runs out

A repo that cannot state its boundaries plainly will watch agents guess, and guessing scales poorly. The NIST AI Risk Management Framework frames this as governance work, which is accurate and a little flattering. Mostly it is writing things down before an incident does it for you.

The files do not make a vague repo clear. They make a clear repo legible to a machine, and that is a real difference. Start with the contract that answers the question your incident channel asks first: who owns this, and how do we turn it off?

Common questions

• Which markdown files do coding agents actually read? Cursor reads .mdc rules files, Claude Code reads CLAUDE.md and follows its hook precedence, and Codex CLI reads AGENTS.md. Skills are markdown too. The overlap is the useful part: one delegation boundary snapshot can state scopes, forbidden paths, and verification expectations once, and each tool consumes the same contract its own way.

• What goes on a connector card for an MCP server? Four lines: allowed actions, forbidden actions, owner, rollback. The card exists so that least privilege is a written decision instead of a default, and so an operator under pressure knows what "off" looks like. If a connector cannot fill the four lines, it is not ready for your repo yet.

• Why do markdown files for coding agents beat prompt templates? Prompts vanish with the session; files persist, get diffed, and get reviewed. A markdown file carries precedence, scope, and verification expectations across every run and every operator. A better prompt improves one session. A better file improves every session that follows, including the ones run by people you have not hired yet.

• Where should I start if I only write one file this week? Write the connector card. It is one page per MCP server, and it answers the question your incident channel asks first: who owns this, and how do we turn it off? Open your last three agent PRs, check which gate questions a file could have answered, and write the one that would have saved the most chat.

Next step

If you want a second pair of eyes on your contract layer, bring your CLAUDE.md, your rules, and your last awkward merge to a team training session. We will help you write the first file that sticks.