Rules
What rules are
Section titled “What rules are”Rules are the persistent, human-authored context each CLI reads automatically at session start and injects into the model’s context — before you’ve typed anything. They live in a file (or set of files) you write and check into the repo: build commands, naming conventions, “we use pnpm not npm,” “the API lives in services/api,” “never edit migrations after they’ve been merged.”
There’s a cross-tool convention here. Codex, opencode, Cursor, and Copilot all read AGENTS.md natively (Copilot also reads CLAUDE.md and GEMINI.md from the repo root). Claude Code reads CLAUDE.md but can import @AGENTS.md for interop. The clean pattern is one AGENTS.md at your repo root, imported into CLAUDE.md — a single source of truth that every major tool will load.
Rules are declarative — you write them, the agent reads them. That’s the distinction from agent-managed memory (where the agent decides what to remember about a session or a user); memory is a separate primitive, not covered here. This chapter is about the static, version-controlled context you author.
Why you’d want them
Section titled “Why you’d want them”You’ve started a fresh session on the same repo for the fifth time this week. The first three messages of every session are always the same: “we use pnpm, not npm. Tests are in __tests__/, not next to source. Don’t auto-run the dev server, it conflicts with the one I already have open. Use the dev-stack branch as base, not main.”
You’re not telling the agent anything new. You’re telling this session something you already told last session, because sessions don’t remember each other. The agent reads files, runs greps, can find anything in the codebase — but it still doesn’t know the unwritten conventions of the team that owns it. So every session starts at zero on the same five facts.
That’s the gap rules close. Write the facts down once, in a file the CLI reads on every start, and they’re loaded before your first message. The agent walks in already knowing.
Real-world examples of what teams put in CLAUDE.md / AGENTS.md:
- Stack and tooling — package manager, test runner, linter, build commands. The first thing the agent gets wrong without this.
- Project layout — where things live (“API code is in
services/api, web is inapps/web”). Saves it from grepping the whole tree to find a file you could’ve named. - Conventions the linter can’t catch — “use the
Loggerclass, notconsole.log,” “all DB calls go throughdb/repo/,” “feature flags read fromflags.ts, never inline.” - Workflow rules — “never push to
main,” “runpnpm validatebefore declaring done,” “write tests in the same PR as the feature.” - Domain context — what your product is, who uses it, what the core nouns mean. Especially useful for non-obvious domains (insurance, logistics, ad-tech).
- Pointers to deeper docs — “for the auth flow, read
docs/auth.md,” so the file stays small but the breadcrumbs are there.
The test: if you’ve corrected the agent on the same thing twice across sessions, it belongs in your rules.
Why this and not…
Section titled “Why this and not…”| You want to… | Reach for | Not |
|---|---|---|
| State a fact the agent should know on every turn of every session | Rules | Skill |
| Encode a multi-step procedure the agent activates only when relevant | Skill | Rules |
| Hard-enforce a rule (block, gate, redirect) deterministically | Hook | Rules |
| Apply guidance only when working in a specific path/subdir | Path-scoped rules (see below) | Bloating root CLAUDE.md |
| Share knowledge across multiple repos | User-global rules file | Per-repo rules |
Rules are always loaded, every turn. That makes them powerful — and expensive on context. Anything that doesn’t need to be present every single turn belongs in a skill instead. Anything that needs to enforce (not just inform) belongs in a hook.
How it works in each tool
Section titled “How it works in each tool”Files Claude Code reads on every session:
./CLAUDE.md— project root- Nested
CLAUDE.mdfiles in subdirectories — load when Claude works in that subdir ~/.claude/CLAUDE.md— your user-wide file (applies to every project)- Managed-policy
CLAUDE.md— org-controlled, takes precedence .claude/rules/*.md— optional path-scoped rules (new in 2026)
Layering: all levels are additive. Claude reads every applicable file and uses judgment when they conflict; more specific takes precedence.
Path-scoped rules keep CLAUDE.md small. A rule file in .claude/rules/ with paths: frontmatter only loads when Claude touches matching files:
---paths: ["src/api/**"]---Use Zod for all request validation.Imports: @path/to/file anywhere in CLAUDE.md inlines that file’s content. Use @AGENTS.md to share rules with Codex and opencode from a single file.
Sizing: keep CLAUDE.md under ~200 lines. Move reference material to skills, and path-specific guidance to .claude/rules/.
Files Codex reads:
./AGENTS.md— project root- Closest
AGENTS.mdwalking up from the working directory ~/.codex/AGENTS.md— user-wide
Standard: Codex implements the open agents.md spec. Any tool that follows the spec reads the same file.
Layering — nested files: Codex concatenates AGENTS.md files from the root downward into one combined prompt, joined by blank lines. Files closer to the working directory appear later and therefore override earlier guidance positionally — additive with positional override, not replacement.
@path imports: Not supported. AGENTS.md is read as-is; there is no file-inclusion directive.
Files opencode reads:
./AGENTS.md— project root~/.config/opencode/AGENTS.md— user-wide
Standard: opencode is the other implementation of the agents.md spec. A project’s AGENTS.md is portable between opencode and Codex with no changes.
Behavioral rules: opencode does not have a separate “Rules” file — AGENTS.md is the rules layer. For additional rule sources, point at extra files via the instructions field in opencode.json (accepts file paths or glob patterns).
Nested files: opencode walks up from the current working directory and the first matching file wins per category — a subdirectory’s AGENTS.md replaces (does not merge with) a parent’s.
@path imports: Not parsed. opencode does not auto-resolve @path references inside AGENTS.md. Workarounds: list the files in opencode.json’s instructions field, or instruct the agent in prose to read specific files on demand.
Files Cursor reads:
./AGENTS.md— repo root; nestedAGENTS.mdfiles in subdirectories auto-apply when working in that subtree.cursor/rules/*.mdc— Cursor-native rule files (Markdown + YAML frontmatter).cursorrules— legacy single-file format at repo root; still honored for back-compat, no longer recommended- User Rules — global, edited from Cursor Settings → Rules; no local file
- Team Rules — dashboard-managed on Team and Enterprise plans; pushed to all members
Standard: Cursor reads AGENTS.md natively — portable with Codex and opencode from a single file.
.mdc frontmatter controls when a rule attaches:
---description: Use Zod for request validationglobs: ["src/api/**"]alwaysApply: false---All API handlers validate input with Zod schemas.Four rule types map to those fields: Always (alwaysApply: true), Apply Intelligently (agent picks via description), Apply to Specific Files (globs:), and Apply Manually (invoked with @RuleName).
Layering: Project, User, and Team rules are additive. .cursor/rules/ and AGENTS.md coexist — Anysphere recommends AGENTS.md for cross-tool portability and .cursor/rules/ for Cursor-specific guidance.
@path imports: No bare @path syntax inside rule files. @RuleName invokes a specific manual rule; @File and @Folder attach context inline in chat. Not the same primitive as Claude Code’s static import.
Files Copilot reads (VS Code, JetBrains):
.github/copilot-instructions.md— single-file, repo-wide.github/instructions/*.instructions.md— path-scoped withapplyTo:glob./AGENTS.md,./CLAUDE.md,./GEMINI.md— read natively at repo root; nearest file in the directory tree takes precedence- Personal custom instructions — set at
github.com/settings/copilot; apply to your sessions across all repos - Org instructions — Business/Enterprise; set by org admins
Standard: Copilot natively reads AGENTS.md (and CLAUDE.md, GEMINI.md) at the repo root — clean interop with Codex, opencode, Cursor, and Claude Code from a single file.
Path-scoped instructions use frontmatter:
---applyTo: "app/models/**/*.rb"---Use Active Record validations; never raw SQL in models.applyTo: accepts comma-separated globs. Optional excludeAgent: opts the file out of specific surfaces (e.g., ["code-review", "cloud-agent"]).
Layering precedence (highest → lowest): personal > repository > organization. All applicable sets are concatenated, not overridden.
VS Code knob: github.copilot.chat.codeGeneration.useInstructionFiles must be true for copilot-instructions.md to auto-apply (default on in current builds). JetBrains lags VS Code on path-scoped .instructions.md support.
@path imports: No file-inclusion directive. #file:path references a file as live context inside a chat turn, but doesn’t statically import rules at session start.
Comparison
Section titled “Comparison”| Aspect | Claude Code | Codex | opencode | Cursor | Copilot |
|---|---|---|---|---|---|
| Default project file | CLAUDE.md | AGENTS.md | AGENTS.md | .cursor/rules/*.mdc or AGENTS.md | .github/copilot-instructions.md or AGENTS.md |
| Cross-tool standard | Via @AGENTS.md import | Native (agents.md) | Native (agents.md) | Native (AGENTS.md) | Native (AGENTS.md / CLAUDE.md / GEMINI.md) |
| User-global file | ~/.claude/CLAUDE.md | ~/.codex/AGENTS.md | ~/.config/opencode/AGENTS.md | User Rules (UI; no local file) | Personal instructions (github.com) |
| Path-scoped rules | .claude/rules/ with paths: | — | instructions: in opencode.json | globs: in .mdc frontmatter | .instructions.md with applyTo: |
| Nested files per subdir | Concatenated (additive) | Concatenated; deeper files override by appearing later | First match wins (no merging) | Nested AGENTS.md auto-applied in subtree | Nearest AGENTS.md takes precedence |
@path imports | Yes (bare @path) | No | No | @RuleName only (manual invocation) | No |
| Managed/org override | Yes | Yes | Yes | Yes (Team Rules) | Yes (Business / Enterprise) |
Name collisions
Section titled “Name collisions”- “Rules” means different things across tools. In Claude Code it’s path-scoped Markdown files in
.claude/rules/(a subset of the rules layer). In opencode there is no separate “Rules” file —AGENTS.mdcarries that role, supplemented by theinstructionsfield inopencode.json. In Cursor, “Rules” is the umbrella name for the whole layer (.cursor/rules/*.mdc, User Rules, Team Rules, plusAGENTS.md). Copilot calls the same concept “instructions” (copilot-instructions.md,.instructions.md, personal and org instructions). In this chapter, “rules” is the cross-tool umbrella term. AGENTS.mdvsCLAUDE.md— same purpose, different filenames. Don’t write conflicting copies of both in one repo; have one import the other.- “Memory” is not the same as rules. Rules are human-authored, declarative, version-controlled. Memory (in the strict sense) is agent-managed — the agent itself decides what facts to remember about a user or project across sessions, often without you seeing the write. They solve different problems and live in different places. This chapter covers rules only.