AGENTS.md vs CLAUDE.md vs Cursor Rules for Teams

Treat AGENTS.md as your canonical, tool-agnostic rule file, and make CLAUDE.md and Cursor rules thin adapters that point at it. AGENTS.md is an open markdown format read by 20+ coding tools — Cursor, OpenAI’s Codex, GitHub Copilot, Devin, and others — with over 60,000 open-source projects using it, per the agents.md site. CLAUDE.md is Claude Code’s own memory file (it does not read AGENTS.md natively), and Cursor’s .cursor/rules adds glob-scoped .mdc rules on top of its AGENTS.md support. For a team, the winning setup is one source of truth plus small tool-specific shims — not three files drifting apart.

What does each file actually do?

All three inject instructions into the model’s context at the start of a session — none of them is enforcement, and an agent can still ignore a rule. The differences are in who reads the file, where it can live, and how precisely you can scope it.

	AGENTS.md	CLAUDE.md	Cursor rules
Read by	20+ tools (Codex, Cursor, Copilot, Devin, Jules…)	Claude Code only	Cursor only
Format	Plain markdown, no required fields	Markdown + @path imports	.mdc files with frontmatter, or AGENTS.md
Scoping	Nested files, closest wins	Nested files + path-scoped .claude/rules/ globs	Four modes: always, glob-attached, agent-decided, manual
Personal layer	No	~/.claude/CLAUDE.md, CLAUDE.local.md	User rules in settings

Two verified specifics worth knowing. First, Claude Code’s docs are explicit that it reads CLAUDE.md, not AGENTS.md — the recommended bridge is a one-line @AGENTS.md import (or a symlink), with any Claude-specific instructions added below it. Second, Cursor’s docs describe rules as instructions bundled into the model’s initial context, and its glob mode (modules/**/*.tf-style patterns) attaches a rule only when matching files are in play — the most precise scoping mechanism of the three. Claude Code has an equivalent in .claude/rules/*.md files with paths: frontmatter.

Which assistant your team standardizes on is a separate question — we compared them for infra work in our AI tools for Terraform and Kubernetes roundup.

How do these files layer in a monorepo?

Nested files override the root, and the closest file to the code being edited wins. That is the documented behavior for AGENTS.md across supporting tools, and Cursor states that nested instructions combine with parents, with more specific files taking precedence. Claude Code loads root CLAUDE.md files at launch and pulls subdirectory CLAUDE.md files into context on demand, when the agent reads files in those directories.

For a typical funded-startup monorepo, a sensible layout looks like:

• /AGENTS.md — repo-wide: build commands, PR conventions, “never commit secrets”, test gates
• /CLAUDE.md — one line: @AGENTS.md, plus Claude-specific notes (plan mode for risky paths)
• /infra/terraform/AGENTS.md — Terraform module conventions (below)
• /k8s/AGENTS.md — manifest standards
• /.cursor/rules/terraform.mdc — glob infra/**/*.tf, only if you need Cursor-only behavior

Keep the root file short. Claude Code’s docs recommend targeting under 200 lines per memory file because longer files consume context and reduce adherence — a rule of thumb that holds for every tool, since these files ride along in every session.

What IaC rules belong in an agent config file?

The highest-value rules are the ones that encode decisions an agent cannot infer from the code — your conventions, not Terraform’s syntax. Generic advice (“write clean HCL”) wastes context; concrete, checkable rules change output.

For a Terraform directory, rules worth writing look like:

• New modules follow modules/<provider>/<name> with variables.tf, outputs.tf, README.md; every variable has a description and explicit type
• Pin provider versions with ~>; never edit .terraform.lock.hcl by hand
• Run terraform fmt and terraform validate before proposing a diff; never run apply — plans go through CI
• Tag every resource with team, env, and cost-center; no inline IAM policies, use the shared iam-role module

For Kubernetes manifests:

• Every Deployment sets resource requests and limits, liveness and readiness probes, and a non-root securityContext
• No latest image tags; images come from our registry only
• Never modify anything under k8s/argocd/ — cluster state is GitOps-managed
• Secrets are referenced, never inlined — see keeping secrets out of AI coding tools

The “never run apply” line matters: instruction files are suggestions, so anything destructive needs a real guardrail (CI-gated pipelines, sandboxes, deny rules). We covered the enforcement side in can AI agents safely run Terraform.

How do you keep three files in sync?

Don’t sync — alias. Maintain AGENTS.md as the only file humans edit, and generate or reference the rest. The @AGENTS.md import handles Claude Code; Cursor reads AGENTS.md natively, so .mdc files are only needed for glob-scoped extras. If you’re stuck with genuinely divergent copies, a CI check that diffs them (or a symlink, where your platform allows it) prevents silent drift.

Two more habits keep this healthy. Review the files in normal code review — they are repo governance, and a wrong rule misleads every agent session until someone notices. And prune quarterly: contradictory instructions are worse than none, because the model picks one arbitrarily.

Who should own these files?

Someone has to — agent config files are now part of your platform layer, alongside CI and IaC. On teams of 5-25 engineers there’s rarely a dedicated owner, which is exactly the gap a monthly DevOps retainer fills: we set up the AGENTS.md hierarchy, the IaC rules, and the CI guardrails behind them in the first weeks of an engagement, then keep them current as the stack evolves. If you want a second opinion on your current setup, that’s covered in our infrastructure audit.