Skip to content
agents.cli

Rules

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 what you already told last session, because sessions don’t remember each other. It can read any file and grep anything; what it can’t do is know the unwritten conventions of the team that owns the repo. So every session starts at zero on the same five facts.

Rules are how you stop re-teaching. They are persistent, human-authored context that many tools read when a session starts and attach to the model’s context: a file (or set of files) you write and check into the repo, holding the facts you would otherwise repeat - “we use pnpm not npm,” “never edit migrations after they’ve been merged.” Discovery, path scoping, and load timing vary by tool, so the per-tool tabs matter.

The file format has partly converged. Several tools read AGENTS.md natively, while Claude Code’s primary file is CLAUDE.md. Since v2.1.277 it also reads AGENTS.md directly, but only when no CLAUDE.md exists; with one present, it can pull the other in with an @AGENTS.md import. So the clean pattern is one AGENTS.md at your repo root, imported into CLAUDE.md where one exists - a single source of truth for the tools that support it. The Comparison table has the per-tool filenames.

Rules are declarative: you write them, the agent reads them. That is the whole line between rules and agent-managed memory, a separate primitive this chapter doesn’t cover - see Name collisions.

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 in apps/web”). Saves it grepping the tree for a file you could have named.
  • Conventions the linter can’t catch - “use the Logger class, not console.log,” “all DB calls go through db/repo/,” “feature flags read from flags.ts, never inline.”
  • Workflow rules - “never push to main,” “run pnpm validate before 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 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.

Watch the 2-minute version

Rules. Watch on YouTube

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 that a tool attaches to a session are typically present on every turn, which makes them powerful - and expensive on context. Path-scoped and intelligently attached instructions may load only when relevant. Anything that doesn’t need durable context belongs in a skill; anything that needs to enforce (not just inform) belongs in a hook.

The tabs won’t tell you which files win when several apply at once. That needs the per-tool paths first, so it waits until after the tabs.

How it works in each tool

Section titled “How it works in each tool”

Showing: Claude Code pick a tab to change

Files Claude Code may load into a session:

  • ./CLAUDE.md - project root
  • Nested CLAUDE.md files 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; later or more-specific instructions often receive more attention, but contradictory files are not a reliable override mechanism.

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.

Path-scoped rules load when Claude reads matching files. Verify that a rule is present with /memory or /context before relying on it for anything critical.

Imports: @path/to/file anywhere in CLAUDE.md inlines that file’s content. @AGENTS.md imports that file into Claude Code; whether other tools read it is tool-specific.

AGENTS.md support: from v2.1.277 Claude Code reads AGENTS.md itself, but by default only when there is no CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md in the working directory or above it. If any of those exists, only the CLAUDE.md files load. A CLAUDE.md that imports @AGENTS.md works on every version. The Project instructions option in /config (claude-md-or-agents-md by default, or claude-md-and-agents-md, claude-md, managed-only) changes this.

Sizing: keep CLAUDE.md under ~200 lines. Move reference material to skills, and path-specific guidance to .claude/rules/.

Which files load, and in what order

Section titled “Which files load, and in what order”

Tools agree on where rules files live but not on how they combine - and the differences bite in monorepos. Same repo, same files, a different answer per tool: pick where the agent is working and see exactly which files each one loads. In OpenCode, nested rule selection and configured instructions are separate mechanisms: the former uses precedence, while the latter can be combined with AGENTS.md.

The resolver currently models Claude Code, Codex, OpenCode, and Pi. Cursor and Copilot remain covered by the tabs and comparison table, but their resolution data is not modeled in this widget yet.

The agent is working on:

Additive - every applicable file loads; more specific guidance sits later and tends to draw more attention, but a flat contradiction is not a reliable override - Claude may pick either.

  1. #1 loaded~/.claude/CLAUDE.mdUser-wide; applies to every project.
  2. #2 loadedCLAUDE.mdProject root; always loaded.
  3. skippedpackages/api/CLAUDE.mdNested files load only when the agent touches files in that subtree.
  4. skipped.claude/rules/api-validation.mdpaths: ["packages/api/**"] - no match for this file.
Two files load, additively. The project file sits later in context and tends to draw more attention - but where the two flatly contradict, Claude may simply pick one. Keep the layers consistent.

Comparison

Section titled “Comparison”
Aspect Claude Code Codex OpenCode Cursor Copilot Pi
Default project file CLAUDE.md AGENTS.md AGENTS.md, or CLAUDE.md as fallback .cursor/rules/*.mdc or AGENTS.md .github/copilot-instructions.md or AGENTS.md AGENTS.md / CLAUDE.md (+ APPEND_SYSTEM.md / SYSTEM.md)
Cross-tool standard Native fallback when no CLAUDE.md exists (v2.1.277+); otherwise @AGENTS.md import Native (agents.md) Native (agents.md / CLAUDE.md) Native (AGENTS.md) Native (AGENTS.md / CLAUDE.md / GEMINI.md) Native (agents.md)
User-global file ~/.claude/CLAUDE.md ~/.codex/AGENTS.md ~/.config/opencode/AGENTS.md, then ~/.claude/CLAUDE.md User Rules (UI; no local file) Personal instructions (github.com) ~/.pi/agent/
Path-scoped rules .claude/rules/ with paths:¹ - instructions: in opencode.json globs: in .mdc frontmatter .instructions.md with applyTo: - (nested walk only, no glob targeting)
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 Nested walk, concatenated; closer files appended later, no formal override
@path imports Yes (bare @path) No No @RuleName only (manual invocation) No No
Managed/org override Yes Yes Yes Yes (Team Rules) Yes (Business / Enterprise) - (project resources are trust-gated, not org-policy-gated)

¹ paths: is the documented, current key - not globs: (that’s Cursor’s). Unverified: community reports describe user-level (~/.claude/rules/) scoping being ignored and rules loading on read but not on write. Reproduce the behavior on the installed version before treating it as a product guarantee.

Name collisions

Section titled “Name collisions”

“Rules” is the least portable word in this chapter. It names a different slice of the layer in every tool:

Tool What the word points at there
Claude Code The path-scoped Markdown files in .claude/rules/ only - a subset. The main file is CLAUDE.md.
Codex No separate “Rules” concept; AGENTS.md is the entire layer.
OpenCode No separate “Rules” file; AGENTS.md carries the role (with CLAUDE.md read as a fallback), supplemented by the instructions field in opencode.json.
Cursor The umbrella name for the whole layer: .cursor/rules/*.mdc, User Rules, Team Rules, plus AGENTS.md.
Copilot Called “instructions” throughout: copilot-instructions.md, .instructions.md, personal and org instructions.
Pi No “Rules” concept; AGENTS.md / CLAUDE.md is the context layer, with APPEND_SYSTEM.md / SYSTEM.md as a stronger layer above it.

In this chapter, “rules” is the cross-tool umbrella term. Two more collisions worth knowing:

  • AGENTS.md vs CLAUDE.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.

Start with one AGENTS.md at the repo root and let corrections fill it: the second time you tell the agent the same thing, that line goes in the file. When it stops fitting - the Claude Code tab suggests holding it under ~200 lines - the overflow has somewhere to go. Procedures move to skills, path-specific guidance to path-scoped rule files, and anything that has to be enforced rather than remembered to hooks.