AI Coding Project Rules: AGENTS.md, CLAUDE.md, Cursor Rules, and Specs
Learn how AGENTS.md, CLAUDE.md, Cursor Rules, MCP, specs, and verification gates divide responsibilities—so agents stay helpful without owning your release.
AI coding tools behave better when the repository explains how work should be done. That guidance shows up as AGENTS.md, CLAUDE.md, Cursor Rules, MCP configs, specs, and verification gates.
These files are instructions and contracts. They are not a substitute for human review or a green build.
Direct answer
| Artifact | Primary job |
|---|---|
AGENTS.md / CLAUDE.md / Cursor Rules | Tell agents project conventions, boundaries, and preferred commands |
| Specs / task briefs | Define what “done” means for a change |
| MCP / tool configs | Control which external tools an agent may call |
| Verification gates | Prove the change with tests, builds, lint, and review checklists |
Use short, enforceable rules. Long essays that nobody updates become ignored noise.
For non-technical builders, start with vibe coding without losing control. For release checks, use the workflow checklist.
When this guide helps
- Your agents keep editing the wrong folders or inventing new patterns.
- The team disagrees about which instruction file is authoritative.
- You want MCP enabled without granting unbounded network or repo power.
- You need a clear line between “agent guidance” and “merge requirements.”
Browse related plugins and skills on the AI Coding plugins directory.
Instruction files: boundaries, not magic
AGENTS.md
Commonly used as a repo-level agent brief: stack, structure, must-run commands, forbidden actions, and links to deeper docs.
Good content:
- Package manager and required Node/Java/Python version
- How to run tests and lint
- Folders agents should avoid
- How to name PRs or commits
Bad content:
- Copy-pasted marketing about the product
- Secrets and production URLs
- Contradictory rules no one maintains
CLAUDE.md
Often used for Claude-oriented project guidance. Treat it like AGENTS.md: keep it current, specific, and short. If both exist, state which file wins for shared rules, or keep them in sync deliberately.
Cursor Rules
Cursor Rules are typically editor/agent scoped instructions (project or user rules). Use them for:
- Coding style and framework conventions
- “Always run X before claiming done”
- Paths that need extra caution (auth, billing, migrations)
Do not hide critical security policy only in a personal user rule if teammates cannot see it.
Specs and task slices
Specs answer what to build and how to accept it. Rules answer how agents should behave while building.
A useful mini-spec includes:
- User-visible outcome
- Out of scope
- Files or areas likely touched
- Test or manual check steps
- Rollback note if risky
Agents without a spec invent scope. Humans without a spec argue after the fact.
MCP and tool access
MCP (and similar tool bridges) let agents call external systems. That is powerful and dangerous.
Before enabling tools:
- Prefer read-only access first
- Allowlist hosts and commands where possible
- Never paste production secrets into MCP configs committed to git
- Log which tools ran for non-trivial changes
MCP configuration is capability control, not product documentation.
Verification gates
Rules can say “run tests.” Gates require evidence:
npm test/npm run build(or your stack equivalents)- Lint and typecheck where applicable
- Diff review for secrets and unexpected file churn
- Checklists such as AI code review and ship checklist
Also see verification gates for AI coding agents.
No green gate → no “done.”
A practical setup order
- Write a one-page
AGENTS.md(or equivalent) with commands and forbidden zones. - Add Cursor Rules /
CLAUDE.mdonly for tool-specific extras; avoid duplication wars. - Require a short spec for any non-trivial task.
- Enable MCP tools narrowly.
- Make merge depend on verification gates, not on agent confidence.
Limits
- File names and product features evolve; verify current docs for Cursor, Claude Code, Codex, and others.
- Rules cannot fix ambiguous product ownership.
- Overlong rule sets get skipped—prefer links to living docs over pasting everything.
FAQ
Do I need every file type?
No. Start with one authoritative brief plus specs for real tasks. Add tool-specific files when a product needs them.
Where should secrets live?
In environment configuration and secret managers—not in rules files, prompts, or committed MCP configs.