Cursor .mdc vs CLAUDE.md vs AGENTS.md

Repository instructions help a coding agent discover conventions before changing files. Cursor rules, Claude Code memory and Codex instructions have different loading and scoping behavior. A team using several clients should verify which files each client actually reads instead of assuming that every Markdown file is automatically active.

Put durable guidance in the instruction file

Useful guidance names the important entry points, verification commands and constraints that apply across tasks. Avoid filling these files with completed task transcripts. A future change should inherit repository knowledge, not another task’s temporary assumptions.

Use the current Cursor rules, Claude Code memory and Codex instructions documentation for exact behavior. An instruction describing a permission boundary does not enforce it. Configure and test the actual tool permissions and hooks separately.

Keep the task contract beside the task

For a documentation-only change, the task record might say:

Goal: correct installation examples.
Allowed paths: docs/**
Exclude: application code, infrastructure and credentials.
Verification: the repository’s docs lint and link checks.
Handoff: changed paths, commands, observed results and unresolved failures.

This is a proposed task brief, not a completed run. Fill in the real commands before starting, then save their actual outcomes with the pull request. The repository instruction file can require that handoff format without accumulating every historical result itself.

Check the rule in an ordinary change

Pick one recent agent-assisted PR and ask whether its reviewer can identify the intended scope and the evidence for the change. Add the smallest missing instruction, then repeat a similar task. Check whether the client loaded the relevant rule, whether the diff stayed within the brief, and whether the handoff names a real verification result.

For a repository with multiple clients, repeat that small task in each client before treating the instruction files as equivalent. Correct a loading or scope mismatch in the appropriate file. Do not write a fictional precedence clause that promises to override the client’s runtime behavior.

Updated 21 September 2026: corrected instruction-file versus task-log responsibilities and removed assumptions about universal policy precedence.