How returning Markdown from docs shapes agentic coding

The workshop review found it in one pass: the team had policy in three places, and the agent only ever saw one at a time, so every merge depended on which file happened to load. Returning markdown from docs means the documentation layer answers an agent in structured Markdown fields, scope, constraints, verification, owner, instead of freeform prose. When docs return markdown, Cursor, Claude Code, and Codex inherit the same review shape instead of improvising three.

Three files, one agent, zero overlap

Counter-thesis: the problem is not that agents ignore your policy; it is that your policy never arrives in a shape they all read.

The wrong path: We split the control plane the obvious way, .mdc for Cursor, CLAUDE.md for Claude Code, AGENTS.md for Codex CLI, and believed that was the system. It worked until precedence got fuzzy and each tool followed a different local interpretation of scope, verification, and exceptions.

Diagnosis: Conway's law, applied to docs. The three files mirror the seams of how the team communicates, so the agent inherits the org chart's gaps instead of one contract.

Thesis: make returned markdown the contract between documentation and execution.

Instead of asking an agent to explain policy in prose, ask it to emit the same reviewable fields every time: scope, constraints, verification, owner. Three fixes get each tool there.

Three fixes, one shared shape

Named fix: the scope rule. Cursor's rules system is strongest when the repo declares boundaries before the session starts. A .mdc file names allowed paths, forbidden paths, and the verification command a reviewer can rerun from the diff. Keep MCP domains explicit, and make the verification command part of the rule, not a side note in chat.

Named fix: the precedence file. Claude Code works better when the repo states which instruction wins on conflict. The docs and hooks model turns noisy when precedence stays implicit, so CLAUDE.md names the override order, the folders that require human review, and the place where temporary exceptions are recorded.

Named fix: the replayable run. Codex CLI is easiest to trust when output can be replayed without the operator's terminal. The quickstart supports a workflow where task output includes intent, command transcript, and diff summary, which makes the run auditable instead of merely successful.

The shared snapshot is small:

---
description: Delegation boundary snapshot
alwaysApply: false
---

- Cursor: keep scopes explicit in `.mdc`; forbid undeclared MCP domains.
- Claude Code: cite `CLAUDE.md` precedence before expanding shell scope.
- Codex: require replay-friendly verification notes in `AGENTS.md` before merge.

Rolling it out without a committee

This pattern does not replace threat modeling, customer approvals, or blast-radius decisions. If the repo cannot name owners for MCP domains, human review still gates the change even when the output is neatly formatted. In our methodology this is the Document step paying for the Review step, and it is the same trade agentic coding governance makes at the merge gate. The standing practice lives on the AI coding governance topic page.

One image: a docs layer that returns markdown is a customs form, the same fields at every border. Review becomes stamping, not interrogating.

Best ways to use this research

• Best for: Cursor teams whose policy lives in three files and whose reviewers see three different run shapes.
• Best first artifact: one .mdc rule that carries allowed paths, forbidden paths, and the verification command in the rule itself.
• Best comparison angle: compare a week of freeform agent summaries against a week of fielded markdown returns; count which merges needed a follow-up question.

Common questions

• What does returning markdown from docs mean for agentic coding?

  It means the docs layer answers agent queries with structured Markdown fields, scope, constraints, verification, owner, instead of prose. Every run then emits the same reviewable shape, so Cursor, Claude Code, and Codex inherit one contract rather than three local interpretations.

• Why do agents need structured returns instead of prose answers?

  Prose varies per run, and reviewers cannot scan what varies. Fielded markdown gives every task the same checkable surface: what was in scope, what was forbidden, which command proves the change, who owns exceptions. The review question shrinks to whether fields match the diff.

• Does this replace human review for risky changes?

  No. The pattern does not replace threat modeling, customer approvals, or blast-radius decisions. If the repo cannot name owners for MCP domains, human review still gates the change, even when the agent output arrives in perfectly formatted fields. Red-folder work keeps its human approval path.

Further reading

• Cursor documentation
• Claude Code getting started
• OpenAI Codex documentation
• Model Context Protocol introduction
• NIST AI Risk Management Framework
• OWASP Top 10 for LLM Applications
• OpenAI Skills repository

Next step

The full contract pattern, fields, rollout order, and exception paths, is in our white paper; read it before standardizing your three files.