Keeping Your Claude Code Subagents Aligned

You've built five Claude Code subagents and they're all inventing their own rules. Your task creator uses MM/DD/YYYY dates. Your validator expects YYYY-MM-DD. Your reviewer just guesses at the schema. Sound familiar?

A few months ago, when subagents became available in Claude Code, I went all-in. Since every subagent instance receives its own context, they are indispensable in managing context bloat and subsequently getting better, higher-quality results from Claude Code. Over time, I defined subagents for planning, coding, reviewing, documentation - you name it.

Quickly though, I had a maintenance issue on my hands. Sometimes agents share instructions and standards. For example, a coding agent may need to know about specific coding standards during implementation, while a reviewer also needs access to the same standards for code reviews. Duplication and inconsistencies started to mount.

I added shared instructions to CLAUDE.md, but now every subagent carried 650 lines of implicit context (~2,600 tokens) it didn't need. Duplicating language and instructions across subagent files created update headaches. Adding explicit referencing to other docs didn't always work as expected.

Here's what I built to solve this: a way for subagents to fetch exactly the additional information they need, with cross-references resolved automatically. No token waste, no duplication, no drift. Let's dive into why the usual approaches often fail, then we'll set this up in five minutes.

The Alignment Problem

You've got your guardrails neatly documented: coding guidelines, architecture patterns, deployment procedures. And now you want your subagents to actually follow these standards instead of inventing their own interpretations.

There are four ways teams typically try to solve this. I've tried them all. Here's why each one falls short.

Let's look at a simple example. Say you're building subagents for task management and you've got standards documented in docs/task-schema.md (just a regular markdown file with numbered sections):

# Task Schema Documentation

## 1. Required Fields
- id (UUID format)
- title (string, 1-200 characters)
- status (enum: todo, in_progress, done)
- created (ISO 8601: YYYY-MM-DD)

## 2. Optional Fields
- due_date (ISO 8601: YYYY-MM-DD)
- priority (enum: low, medium, high)
- depends_on (array of task IDs)
- tags (array of strings)

## 3. Validation Rules
1. Status must be lowercase with underscore
2. Dates must be ISO 8601 format (not MM/DD/YYYY)
3. Priority defaults to "medium" if omitted
4. Depends_on must reference existing task IDs

## 4. Status Workflow
[... transition rules ...]

## 5. Error Handling
[... validation error formats ...]

[... 50 more lines covering sections 6-12 ...]

That's 150 lines total, and your subagents need to follow it.

Option 1: Hope for the Best

Create tasks with the documented schema for fields and validation.

You put a reference to the task schema doc in CLAUDE.md and rely on the subagent to find relevant files with the information. This might work if you recently discussed the schema in the conversation, or if the subagent happens to use its Read tool to discover the standards file. But that's unpredictable.

Often, subagents ignore these implicit references and invent their own schema based on what seems reasonable. Each invocation makes different choices.

Subagent 1 creates tasks like this:

{
  "id": "task-001",
  "name": "Write article",
  "state": "In Progress",
  "created": "10/27/2025"
}

Subagent 2 creates tasks like this:

{
  "task_id": "550e8400-e29b-41d4-a716-446655440000",
  "title": "Write article",
  "status": "in_progress",
  "created_date": "2025-10-27"
}

Different field names, different date formats, different status values. You can't predict which schema any given subagent will choose, so you can't build consistent tooling around the output.

You're probably thinking: there's got to be a better way.

Option 2: CLAUDE.md

You add all relevant standards to your project's CLAUDE.md file. This beats the first approach because the instructions are now present as implicit context for every conversation. The subagent doesn't need to guess - the schema is already there.

The tradeoff: you carry all this context for every prompt and every subagent, whether they need it or not. Your task creation subagent sees the entire 150-line schema. So does your planning subagent, your code review subagent, your reporting subagent, and any other subagent in your system.

Add more standards and the problem compounds. Task schema (150 lines), coding guidelines (200 lines), API documentation (300 lines). Now every subagent in your system carries 650 lines of context, but each one only needs 10-20 lines for its specific job.

Context is precious. As your CLAUDE.md grows, relevant information gets hidden in noise. Critical validation rules in Section 3 get overlooked when they're surrounded by low-signal content. Models often miss details embedded in the middle of long contexts.

At 650 lines, your CLAUDE.md now carries more noise than signal for any given subagent. You're not only paying the token cost for all that context, but you're also not getting consistent compliance.

Option 3: Explicit instructions

You could paste the entire schema into every subagent:

Create tasks with these rules:
- id (UUID format)
- title (string, 1-200 characters)
- status (enum: todo, in_progress, done)
[... paste all 150 lines ...]

Now you're duplicating those 150 lines across 5 subagent files. That's 750 total lines of duplicated content (150 lines × 5 subagents), roughly 3,000 tokens at a conservative estimate.

When you need to update the schema, you're editing 5 files. Miss one? Subagent 2 still uses the old date format. Subagent 4 accepts status values you deprecated last week.

Option 4: "Read the docs"

On to the next option. You could try this:

Create tasks following the standards in @docs/task-schema.md.

This is better, because you're no longer duplicating content, but unless you keep file sizes small and granular to maintain focus, the subagent might read all 150 lines and waste tokens on sections it doesn't need. Worse it may guess which parts matter and get inconsistent results, or ignore the reference entirely and produce invalid output.

So, let's be more specific:

You are a task creation subagent.

Before creating tasks, read these sections from @docs/task-schema.md:
- Section 1 (Required Fields)
- Section 3 (Validation Rules)

Use the Read tool to fetch the file, then locate the sections.

Now the agent has specific instructions for what to look for. It reads the file (150 lines), scans for ## 1. Required Fields and ## 3. Validation Rules, extracts content between section markers, uses that for task creation.

But now, there's another problem: what if your schema file references other files? Say Section 3 includes "See validation-rules.md for detailed error handling" or Section 5 says "Workflow transitions defined in state-machine.md."

The subagent might read docs/task-schema.md but ignore those cross-references. Or it might chase one reference but not another. Or it might read all of them, burning tokens on content it doesn't need.

You have no control over which references the subagent follows. It may or may not follow these references. The behavior is unpredictable, which makes your output unpredictable.

Seeing the pattern? You've probably tried at least two of these approaches.

Why This Gets Expensive Fast

Finally, you will still have to battle context waste. As you add content and more shared standards to your files, token cost will increase while subagents will only use a fraction of what they read.

What you need is a tool that fetches specific sections directly and resolves cross-references automatically. That's the mechanical work that shouldn't require subagent judgment.

This is why I built MCP Policy Server. It automates section fetching and cross-reference chasing, so you can feed subagents exactly what they need, nothing more.

How MCP Policy Server Fixes This

The policy server sits between Claude Code and your standards ("policy") files. You mark sections with § references (like {§TASKS.1} or {§TYPES.2}), and subagents request them directly.

The server handles the mechanical work. Subagent asks for §TASKS.1, server returns that section. If §TASKS.1 mentions §TASKS.3, server automatically fetches both. No manual file reading, no section marker parsing, no unpredictable cross-reference chasing.

It's the same pattern as explicit section references, just automated and more reliable.

Manual approach vs automated approach

Manual approach: Subagent reads 150 lines to extract 2 sections.
Automated approach: Server returns exactly those 2 sections.

Manual:

Before creating tasks:
1. Read @docs/task-schema.md (150 lines)
2. Extract Section 1 (Required Fields)
3. Extract Section 3 (Validation Rules)

Automated:

Before creating tasks, fetch:
- §TASKS.1 (Required Fields)
- §TASKS.3 (Validation Rules)

Subagent calls mcp__policy-server__fetch_policies({"sections": ["§TASKS.1", "§TASKS.3"]}). Server returns exact section content.

How it works

Mark sections in your policy files with § markers (replacing plain section numbers).

Syntax note: When you mark sections in policy files, you use braces: {§TASKS.1}. When you reference sections in prompts or tool calls, you drop the braces: §TASKS.1. The braces identify section boundaries in source files; the bare § notation references those sections.

policies/type-policies.md:

## {§TYPES.1} ID Format

All IDs use UUID v4 format...

policies/task-policies.md:

## {§TASKS.1} Required Fields

- id (see §TYPES.1 for format)
- title (string, 1-200 characters)
- status (enum: todo, in_progress, done)
- created (see §TYPES.2 for format)

Subagent prompts include § references:

Before creating tasks, fetch §TASKS.1

Your code calls the tool:

{
  "sections": ["§TASKS.1"]
}

The server reads policies/task-policies.md, extracts §TASKS.1, sees it references §TYPES.1 and §TYPES.2, automatically fetches those too. The response includes all three sections from one request. No manual cross-reference chasing.

What you get back: §TASKS.1 plus any sections it references (§TYPES.1 and §TYPES.2 in this case) - all from one tool call.

Here's why this beats manual section references: manual approach needs six steps (read file, scan for section markers, extract content, notice cross-references, read referenced files, extract those sections). Automated approach: one tool call. The server handles all the mechanical work deterministically - same input always gives the same output, no parsing errors, no unpredictable reference chasing.

The lookups are hard references, not semantic search. Request §TASKS.1, get §TASKS.1. No "finding relevant content," no RAG pipelines, no vector embeddings. Direct section retrieval.

Set This Up in Five Minutes

Let's get this running. We'll create the actual policy files with § markers, configure the server, and verify it works with the task schema example we've been using.

Create policy directory

mkdir policies
cd policies

Note: In our earlier examples, we used docs/task-schema.md as a conceptual single file. For actual implementation, we'll split this into focused policy files in a policies/ directory - one for shared type definitions (type-policies.md) and one for task-specific rules (task-policies.md). This separation makes policies more maintainable and reusable.

Create your policy files

First, create base type definitions in policies/type-policies.md:

## {§TYPES.1} ID Format

All IDs use UUID v4 format:
- 36 characters (32 hex + 4 hyphens)
- Example: `550e8400-e29b-41d4-a716-446655440000`
- Generation: Use standard UUID library

## {§TYPES.2} Date Format

All dates use ISO 8601 format:
- Format: YYYY-MM-DD
- Example: `2025-10-28`
- Invalid: MM/DD/YYYY, DD/MM/YYYY, timestamps

Then create task-specific policies in policies/task-policies.md:

## {§TASKS.1} Required Fields

- id (see §TYPES.1 for format)
- title (string, 1-200 characters)
- status (enum: todo, in_progress, done)
- created (see §TYPES.2 for format)

## {§TASKS.2} Optional Fields

- due_date (see §TYPES.2 for format)
- priority (enum: low, medium, high)
- depends_on (array of task IDs, each follows §TYPES.1)
- tags (array of strings)

## {§TASKS.3} Validation Rules

1. Status must be lowercase with underscore
2. Dates must follow §TYPES.2 format
3. Priority defaults to "medium" if omitted
4. All IDs must follow §TYPES.1 format

The {§TASKS.1} markers tell the policy where sections start, without mistaking them for references themselves. Notice §TASKS.1 references §TYPES.1 and §TYPES.2 - the server fetches those automatically.

The server automatically extracts prefixes (TYPES, TASKS) from section IDs in all configured files. No manual mapping needed.

Add the MCP server configuration

In your project root (the directory containing your policies folder) run:

Linux/macOS:

claude mcp add --transport stdio policy-server \
  npx -y @andrebremer/mcp-policy-server \
  --env MCP_POLICY_CONFIG="./policies/*.md" \
  --scope project

Windows:

claude mcp add-json policy-server ('{' `
  '"type": "stdio", "command": "cmd",' + `
  '"args": ["/c", "npx", "-y", "@andrebremer/mcp-policy-server"], ' + `
  '"env": {"MCP_POLICY_CONFIG": "./policies/*.md"}}') `
  --scope project

The npx -y command automatically downloads and runs the package on first use. Restart Claude Code after creating .mcp.json.

Test it

Ask Claude:

Use list_sources tool to show available policies

If everything's working:

Available policy sources:
- TYPES → type-policies.md
- TASKS → task-policies.md

Now test cascading references: Fetch §TASKS.1

You should see three sections returned:

• §TASKS.1 (Required Fields): the section you requested
• §TYPES.1 (ID Format): automatically fetched because §TASKS.1 references it
• §TYPES.2 (Date Format): automatically fetched because §TASKS.1 references it

The server chased the cross-references for you. No manual file reading, no guessing which references to follow.

Makes sense? You've got working section references. The task schema example generalizes to any scenario where subagents need to follow documented standards. Code reviews, API documentation, data validation, deployment procedures - any place where you need consistent subagent behavior based on written policies.

Per-Project Policies

Each project gets its own policies/ directory with its own .mcp.json configuration.

Your task management project uses policies/task-policies.md with §TASKS sections. Your API project uses policies/api-standards.md with §API sections. Your documentation project uses policies/doc-templates.md with §DOC sections.

Same server, different policy sets. Switch projects, get different policies. No conflicts, no shared state. Each project's subagents fetch sections from that project's policy files.

Where This Makes the Biggest Difference

Code Review Standards

Your team has a 50-page coding standards document covering naming conventions, error handling patterns, testing requirements, and security guidelines. Different review subagents need different sections:

• Import validation subagent → §CODE.3 (Import Conventions), §CODE.12 (Dependency Rules)
• Error handling subagent → §CODE.7 (Error Patterns), §SEC.5 (Security Exceptions)
• Test coverage subagent → §TEST.1 (Coverage Requirements), §TEST.4 (Mock Standards)

Each subagent fetches exactly what it needs. Update §CODE.7 with a new error pattern, every subagent that references it enforces the new rule immediately.

API Documentation Compliance

You're building a REST API with strict conventions documented across multiple files. Your documentation generation subagent needs:

• §API.1 (Endpoint Naming) from api-standards.md
• §API.5 (Error Responses) from api-standards.md
• §TYPES.2 (Date Formats) from type-policies.md
• §AUTH.3 (Token Headers) from security-policies.md

Four sections from three files, one tool call. The subagent generates documentation that matches your actual standards, not its best guess.

What's your use case? Any place you've got documented standards that multiple subagents need to follow consistently, this pattern applies.

Summary

You need subagents that follow your standards consistently. Vague instructions fail. CLAUDE.md buries important details in noise. Copy-paste creates maintenance burden. Manual section references work but burn tokens reading entire files.

Section references with MCP Policy Server give you precision: subagents fetch exactly the sections they need, cross-references resolve automatically, and updates propagate instantly. Same sections every time means predictable behavior. Single source of truth means no drift.

Your subagents now follow the same standards you do. Reliably.

Get MCP Policy Server here: https://github.com/AndreBremer/mcp-policy-server