Do you split your AGENTS.md into scoped rule files?

One large AGENTS.md creates problems as a project grows. Agents use space in the context window for instructions that don't apply to the current work. Scoped rule files address this — they load only when an agent works on files in specific locations.

The problem with one big AGENTS.md

If a single AGENTS.md includes instructions for backend, frontend, database, testing, and security, the system pulls in all of it on every use — even when the work is limited to one area. Large files get truncated, slow context loading, and hide the specific instructions that matter for the immediate task.

Multiple AGENTS.md let you limit rules to specific directories. But there are times when rules must apply to file patterns instead of locations — e.g. "all .razor files" or "all *Effects.cs files across the codebase".

The solution: path-scoped rule files

Claude Code allows rule files in .claude/rules/ with a paths: frontmatter that tells the agent when to load them.

---
paths:
  - "src/Northwind.Web/**/*"
  - "**/*.razor"
---

# UI — Blazor

## Components

- One component per feature folder
- Use `@bind-Value` for form inputs
- Validation via `EditForm` + `DataAnnotationsValidator`
...

✅ Figure: Good example - Path-scoped rule file — only loaded when the agent touches matching files

At the root, the AGENTS.md file then serves as a small index that refers to the scoped files:

## Rules

Detailed conventions are in `.claude/rules/` (auto-loaded by Claude Code):

* `architecture.md` — Clean Architecture layers, MediatR
* `coding-standards.md` — naming, async, enums, records
* `database.md` — EF Core migrations
* `testing.md` — xUnit, FluentAssertions
* `ui-blazor.md` — components, validation, accessibility

✅ Figure: Good example - Root AGENTS.md as an index pointing to scoped rule files

Example: a Northwind app

Consider a Northwind sample app that uses Clean Architecture. Instead of placing every convention into one giant AGENTS.md, divide the detail across .claude/rules/ by topic. Each file declares the paths where its rules apply, so the agent only loads what relates to the file currently being edited.

├── 🤖 AGENTS.md                       ← Index + project overview
└── .claude/
    └── rules/
        ├── architecture.md            ← paths: src/Northwind.Application/**, src/Northwind.Domain/**
        ├── coding-standards.md        ← paths: **/*.cs
        ├── database.md                ← paths: **/Migrations/**, **/*DbContext.cs
        ├── ddd-patterns.md            ← paths: src/Northwind.Domain/**
        ├── security.md                ← paths: **/*Authorization*.cs
        ├── testing.md                 ← paths: **/*.Tests/**
        └── ui-blazor.md               ← paths: **/*.razor

✅ Figure: Good example - Scoped rule files keep each concern targeted, the agent's context lean, and the root AGENTS.md skimmable

When to use scoped rules vs. multiple AGENTS.md

• Multiple AGENTS.md — when rules align with directory structure (e.g. one AGENTS.md per package in a monorepo). See Do you write an AGENTS.md?.
• Scoped rule files — when rules apply to file patterns that cross directories (e.g. "all migration files", "all .razor files"), or when you want one short index at the root.

The two methods can also exist together — an AGENTS.md for each package, with files in .claude/rules/ managing patterns that appear across many areas.

Further reading

• Claude Code — Project rules
• Do you write an AGENTS.md?
• Do you symlink your AGENTS.md to other tool-specific files?