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 someone adds coding conventions. Then someone pastes in the database naming rules. Then the architecture guidelines. Then the error handling patterns. Before long, you’ve got a 3,000-line file that no human reads and no AI fully processes.

There’s a better way. And it starts with treating your AI instructions file like what it actually is: a router.

The Problem With One Big File

AI agents have context windows. They’re large, but they’re not infinite. And more importantly, not all context is equally relevant to every task.

When you dump everything into one file, you’re forcing the AI to load your database conventions when it’s writing a CSS component. You’re burning tokens on security standards when it’s fixing a typo in a README. Every session pays the cost of your entire standards library whether it needs it or not.

Worse, when the file gets long enough, the AI starts deprioritizing content in the middle. Important rules get lost in a sea of guidelines that aren’t relevant to the current task. You’ve seen this if you’ve ever wondered why the AI keeps ignoring that one convention you know you put in the instructions file.

The Router Pattern

The fix is simple: your root instructions file should be an index, not an encyclopedia.

Here’s how I set this up for my teams. The root file (your CLAUDE.md or equivalent) does three things:

States the non-negotiable principles (a handful of lines, not pages)
Points to modular standards files organized by topic
Tells the AI when to load each module

The root file stays small. Always loaded, always processed, never ignored. The detailed standards live in separate files that the AI pulls in only when they’re relevant to the current task.

Think of it like an API. The root file is the entry point. The standards modules are the endpoints. You don’t call every endpoint on every request. You call the ones you need.

The File Structure

Here’s what this looks like in practice:

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

The key insight is that not everything needs to be loaded all the time. I use three tiers:

Tier 1: Always Loaded. The router itself, your golden rules, and your workflow expectations. These are small (a few hundred lines total) and apply to every single task. This is your floor. Every AI session starts with this context.

Tier 2: Contextually Loaded. The topic-specific standards that the AI pulls in based on what it’s working on. Building an API endpoint? Load the API and architecture standards. Writing tests? Load the testing standards. The router file includes a table that maps each module to its trigger condition.

Tier 3: On Demand. Code examples and reference implementations. These are expensive (thousands of tokens for a meaningful code sample) and only relevant when the AI is building something new that needs to follow a pattern. Don’t load your 200-line reference implementation for a bug fix.

Why This Matters for Token Budgets

A typical session with the router pattern:

Quick bug fix: ~4,800 tokens (router + golden rules + workflow)
New API endpoint: ~5,600 tokens (add architecture + API standards)
New feature with examples: ~9,000 tokens (add reference implementation)
Everything loaded: ~10,000 tokens

Compare that to the “one big file” approach where every session burns 10,000+ tokens whether you need it or not. The router pattern gives you the right context for the right task, every time.

But the token savings aren’t even the main benefit. The main benefit is that the AI actually follows the standards because the relevant ones are prominent in context, not buried 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.

Mine includes things like:

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. They don’t need to be contextual because they’re always relevant. They earn their permanent spot in every session.

The Workflow File

The second always-loaded file defines how the agent should work:

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

Here’s the part that makes this scale across teams: the tool-specific files are thin pointers, not copies.

Your CLAUDE.md:

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

Your copilot-instructions.md:

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

That’s it. The tool-specific files don’t contain standards. They point to the standards. One developer uses Claude, another uses Copilot, a third uses Cursor. They all get routed to the same source of truth.

No drift. No “well, the Copilot file says X but the Claude file says Y.” One set of standards, multiple entry points.

Contextual Citations

One rule I enforce: the AI must cite the specific standard it’s 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.”

This does two things. First, it proves the standards were actually applied, not just loaded and ignored. Second, it makes code review faster because the reviewer can see the reasoning without having to infer it.

Getting Started

If you want to implement this pattern, here’s the path:

Audit your current instructions file. Identify what’s universal (always needed) versus contextual (task-specific).
Extract the contextual content into topic-specific files.
Write the router. A table mapping each module to its loading condition.
Define your golden rules. The behavioral standards that apply to every session.
Replace your tool-specific files with thin pointers to the router.
Version it all in Git. Standards changes go through PR review, just like code.

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. Treat it like infrastructure.

That means modular design, separation of concerns, clear interfaces, and version control. The same principles that make code maintainable make AI configurations maintainable.

A router, not a novel.