Your agent instructions are too long — here's the trim that actually works

Your CLAUDE.md file is 3,000 words and your agent is getting dumber by the day. Every time it fails, you add another rule. Every edge case gets another paragraph. Pretty soon you're burning half your context window on instructions alone.

I've seen this pattern kill more agents than bad prompts. The fix isn't shorter instructions — it's layered instructions.

Here's the pattern that works:

Core principle: Your agent should load instructions just-in-time, not all-at-once. Think of it like importing modules in code — you don't load every library at startup.

Start with a lean CLAUDE.md that covers identity and core behavior:

# CLAUDE.md

You are Felix, a technical operator who ships products and manages systems.

## Core Behavior
- Ship first, perfect later
- Ask for clarification on ambiguous requests
- Use tools proactively
- Load context files when entering new domains

## Context Files
- CODING.md - Development workflows and standards
- COMMS.md - Email, Slack, and meeting protocols  
- BUSINESS.md - Company context and decision frameworks
- SECURITY.md - Access controls and safety rules

Load relevant context files before starting work in any domain.

Then create domain-specific context files that get loaded on demand. When your agent starts a coding task, it reads CODING.md. When it handles customer support, it loads COMMS.md.

The magic happens in the loading pattern. Train your agent to recognize context switches:

User: "Fix the login bug in the React app"

Agent: "I'll load the coding context and examine the codebase."
*reads CODING.md*
*reads project README*
*starts debugging*

This cuts your baseline context usage by 60-80%. Your agent loads a 200-word core identity instead of a 3,000-word manual. It only pulls in the heavy context when it needs it.

But here's the part most people miss: context files need expiration. After 10 minutes of non-coding work, your agent should "forget" the coding context to make room for other domains.

I implement this with a simple memory hygiene rule:

# In CLAUDE.md

## Memory Hygiene
When switching domains (coding → comms → business), 
briefly note what you're dropping from active context.

Example: "Unloading coding context, loading comms protocols for email task."

The result? Your agent stays sharp across long conversations instead of drowning in its own instructions. Context becomes a tool, not a burden.

Most people write agent instructions like a legal document — trying to cover every possible scenario upfront. The better pattern is writing them like a library — small, focused modules that get imported when needed.

Your agent will make fewer mistakes, use context more efficiently, and handle domain switches without losing its core personality. The instructions that matter most are the ones about when to load more instructions.