Your AI Instructions File Should Be a Router, Not a Novel

Every AI coding tool has some version of an instructions file. Claude has CLAUDE.md. Copilot has copilot-instructions.md. Cursor has .cursorrules. The idea is the same: give the AI context about your project so it produces better code.

Most teams treat this file like a junk drawer. They start with a few lines, then add coding conventions, database naming rules, architecture guidelines, and error-handling patterns. Before long, they have a 3,000-line file that no human reads and no AI fully processes. Treat the instructions file for what it actually is: a router.

The Problem With One Big File

AI agents have large but finite context windows, and not all context is relevant to every task. A monolithic file forces an agent to load database conventions while it writes a CSS component and security standards while it fixes a README typo. Every session pays for the entire standards library whether it needs it or not.

As the file grows, important rules are also more likely to be lost among guidelines irrelevant to the task. That is why an agent can keep ignoring a convention you know is present in the instructions.

The Router Pattern

Your root instructions file should be an index, not an encyclopedia. In my teams, the root file (CLAUDE.md or its equivalent) states the non-negotiable principles, points to modular standards files organized by topic, and tells the AI when to load each module.

The root file stays small enough to load and process reliably. Detailed standards live in separate files that the AI pulls in only when they matter to the current task. Think of it like an API: the root file is the entry point, the standards modules are endpoints, and each request calls only what it needs.

The File Structure

ai/
├── agentic_standards.md          # The router (always loaded)
├── standards/
│   ├── golden-rules.md           # Core behavioral rules (always loaded)
│   ├── agentic-workflow.md       # How agents should work (always loaded)
│   ├── architecture.md           # Load when: architectural decisions
│   ├── api-controllers.md        # Load when: building API endpoints
│   ├── csharp-conventions.md     # Load when: writing C# code
│   ├── database-conventions.md   # Load when: database work
│   ├── testing-standards.md      # Load when: writing tests
│   ├── security-standards.md     # Load when: auth, data handling
│   ├── error-logging-handling.md # Load when: error handling, logging
│   ├── git-commits.md            # Load when: committing code
│   ├── pr-checklist.md           # Load when: creating PRs
│   └── examples/
│       └── reference-impl.cs     # Load when: building new features

Three Loading Tiers

1. Always loaded: the router, golden rules, and workflow expectations. Not everything needs to be loaded all the time; these few hundred lines apply to every task and form the floor for every session.
2. Contextually loaded: topic-specific standards that match the work. API endpoints load API and architecture standards; tests load testing standards. The router maps each module to its trigger condition.
3. On demand: code examples and reference implementations. These consume thousands of tokens for a meaningful sample, so load them only when the agent is building something that must follow a pattern.

Why This Matters for Token Budgets

A typical router-pattern session uses roughly 4,800 tokens for a quick bug fix, 5,600 for a new API endpoint, and 9,000 for a new feature with examples. Loading everything uses about 10,000 tokens.

The one-big-file approach can spend 10,000+ tokens on every session whether the work needs that context or not. More important than the token savings, the router pattern keeps relevant standards prominent instead of burying them on page 47 of a monolithic instructions file.

The Golden Rules File

One file gets special treatment: the golden rules. This is your behavioral constitution. It’s always loaded because it defines how the AI should operate regardless of what it’s working on.

• Read existing code before modifying anything. Don’t assume. Look.
• State your plan before acting. No surprises.
• Never say “you’re absolutely right.” If you disagree, say so. Sycophancy is a bug.
• One logical change at a time. If 200 lines could be 50, rewrite it.
• Never take irreversible actions without explicit permission.
• Surface confusion immediately. Don’t guess and hope.

These rules shape every interaction, so they do not need to be contextual. They earn a permanent place in every session because every task depends on the agent behaving predictably before it begins implementation.

The Workflow File

• Enter plan mode for any task requiring 3+ steps
• Use sub-agents liberally (one task per sub-agent)
• Maintain a session-level task list (not committed to the repo)
• Never mark a task complete without demonstrating it works
• Update a lessons file after every correction so the same mistake doesn’t repeat

This is operational infrastructure. It’s how the agent behaves, separate from what the code should look like. Keeping it in its own file means you can update workflow practices independently of coding standards.

The Tool-Agnostic Layer

The pattern scales across teams because tool-specific files are thin pointers, not copies. For example, CLAUDE.md can contain:

This project follows the Agentic Coding Standards.
Load and comply with ai/agentic_standards.md

copilot-instructions.md can contain the same pointer:

This project follows the Agentic Coding Standards.
Load and comply with ai/agentic_standards.md

The tool-specific files do not contain the standards. They point to them. One developer can use Claude, another Copilot, and a third Cursor while all three route to the same source of truth. That structure prevents a Copilot file from saying one thing while a Claude file says another.

Contextual Citations

I enforce one rule: the AI must cite the specific standard it is applying when it makes a non-obvious decision. Instead of silently choosing a pattern, the AI says, “Per coding standards: using controller-based API with [ApiController], not Minimal API,” or, “Per architecture standards: parallelizing independent repo calls with Task.WhenAll.”

The citation proves the standard was applied and speeds code review because the reviewer can see the reasoning without having to infer it. It also creates a useful record when an implementation decision needs to be revisited later.

Getting Started

To implement the pattern, audit the current instructions file for universal and task-specific content, extract contextual material into topic-specific files, write a router that maps each module to its loading condition, define the golden rules, replace tool-specific files with thin pointers, and version the system in Git so standards changes receive PR review.

I’ve published a reference implementation on GitHub that shows the full structure with example content. Fork it, replace the examples with your actual standards, and you’ve got a working system in an afternoon.

The Principle

Your AI instructions file is infrastructure. It needs modular design, separation of concerns, clear interfaces, and version control. The same principles that make code maintainable make AI configurations maintainable. The operating model is a router, not a novel.

Receipts

• Reference implementation: The public agentic coding standards example shows the router, modular standards files, and tool-specific pointers discussed here.
• Token figures: The token counts in this essay are first-party examples from the author’s standards layout, not a benchmark of every coding harness or model.