I maintain 7 AI context files. Here’s what actually goes in them.#

I added one feature to PitchDocs last week. A new skill. That meant updating “15 skills” to “16 skills” in CLAUDE.md. And AGENTS.md. And .cursorrules. And copilot-instructions.md. And .windsurfrules, .clinerules, and GEMINI.md. Seven files, same number change, across the same repo.

I missed two of them. Of course I did.

TL;DR:

• Every AI coding tool wants its own instruction file. Maintaining them all is a losing game unless you centralise.
• An ETH Zurich study found that overstuffed context files actually make AI agents worse - reducing task success and increasing inference costs by over 20%.
• What works: one canonical AGENTS.md with short bridge files per tool, containing only what the AI can’t figure out from your code.

Two 2025-2026 studies, same finding. A February 2026 ETH Zurich paper (Gloaguen et al.) evaluated AGENTS.md across four coding agents and found that LLM-generated context files reduced task success on AGENTbench while increasing inference cost by over 20%. A separate November 2025 study of 2,303 context files across 1,925 repos found developers over-weight implementation details (69.9% of content) and architecture (67.7%) at the expense of constraints the agent actually needs. A March 2026 MSR paper analysing 401 repos of Cursor Rules went further: 28.7% of all lines were duplicates of what the code already tells the agent. The evidence is consistent - shorter, developer-written, constraint-focused files beat longer auto-generated ones.

The irony is not subtle. I build a documentation tool. My own docs went stale because I couldn’t keep 7 files in sync. Most developers won’t hit 7 - you’ll probably have 2-3 if you use more than one AI coding tool. Even 2 files that say the same thing will drift, and everything I learned about keeping them honest applies at any scale.

Why do I have 7 context files?#

Each AI coding tool reads its own instruction file from your project root. That’s how this happened - not through any grand design. Each tool shipped its own convention independently.

If you only use one tool, you have one file. Easy. Most of my repos have 2-3. PitchDocs is different, though - it’s a documentation tool that generates context files for other people’s repos, so it needs to work with every editor. I use Claude Code daily (including from my phone while walking the dog) and test PitchDocs with Cursor, Codex CLI, and Gemini CLI for cross-tool compatibility. That repo alone has all 7 files.

The problem isn’t writing them. Writing a context file takes 20 minutes. How many of your context files say the same thing right now? Are you sure? The problem is that they drift within days. I added a PitchDocs feature, updated the skill count in CLAUDE.md, and forgot .cursorrules and GEMINI.md. Three days later, Cursor was telling a contributor there were 15 skills when there were 16. Small thing. That’s how trust erodes, though - not through dramatic failures. Through quiet inaccuracies that pile up.

A study analysing 2,303 context files across Claude Code, Codex, and GitHub Copilot found the median update interval for Claude Code files is 24.1 hours. People are touching these files constantly. And every update that doesn’t propagate to the other 6 files creates drift.

What actually goes in a context file?#

Most context files I’ve seen are too long. They contain directory trees, architecture overviews, file listings, and detailed explanations of how the codebase works. The instinct makes sense - give the AI more context, get better results. Right?

Wrong.

An ETH Zurich study from February 2026 tested context files against four coding agents (Claude Code with Sonnet-4.5, Codex with GPT-5.2, Codex with GPT-5.1 mini, and Qwen Code with Qwen3-30B). Their finding: LLM-generated context files - the kind that dump everything about a project into one file - reduced task success rates by 2% on AGENTbench. Inference costs went up over 20%. The agents took more steps, consumed more reasoning tokens, and solved fewer problems.

The developer-written context files performed better - they actually improved success rates by 4% on the same benchmark. The difference? The developer-written files were shorter and focused on what the developer knew was unusual about the project. Not architecture overviews. Not file trees. Just the gotchas.

A March 2026 MSR paper by Jiang and Nam found the same pattern from a different angle. They analysed Cursor Rules across 401 repositories and found 28.7% of all lines were duplicates of code or documentation the agent could already see. Every one of those duplicated lines is tokens paid for a second time, and the ETH Zurich data shows what you get for them: slower agents, higher bills, fewer solved problems.

I call this the Signal Gate principle: only include what the AI cannot discover by reading your code.

What to include#

Think of it like a tourist phrase book. You don’t hand someone a dictionary when they land in a new country. You give them the five phrases locals actually use and a warning about the taxi scam. Context files work the same way - the agent already speaks the language, it just doesn’t know your local customs.

Your AI coding agent is going to read your source files, your tests, your config. It’ll figure out your framework, your language, your project structure. You don’t need to tell it any of that. What you need to tell it is the stuff that isn’t in the code:

• Naming conventions that break expectations. If your Python project uses camelCase because it wraps a JavaScript API, say so. The agent will default to snake_case otherwise
• Build quirks and environment setup. direnv exec . wrangler deploy instead of just wrangler deploy. The agent won’t guess that your shell doesn’t inherit direnv
• Architectural decisions that aren’t obvious from the code. “We use D1 for transactional data and KV for config. Don’t mix them.” The agent can see both bindings. It doesn’t know why you split them that way
• Testing conventions. “Integration tests hit the real database. Don’t mock D1.” The agent would default to mocking
• Things that have gone wrong before. “The content filter blocks CODE_OF_CONDUCT generation. Use the content-filter-guard hook.” Also the $4,868 bill I got from an infinite loop - context files are where those lessons live so the next AI session doesn’t repeat them

What to leave out#

Anything the agent can figure out by reading files. Here’s the split at a glance:

Every line of redundant context wastes tokens. The ETH Zurich data shows it actively degrades performance too. The agents spend reasoning tokens processing information they would have discovered anyway. Sometimes they contradict themselves because the context file describes something slightly differently than the code does.

For perspective: React’s CLAUDE.md is 8 lines. The most popular JavaScript library on GitHub, 244,000 stars, and their context file says “React is a JavaScript library for building user interfaces” and points to one subdirectory. That’s it. An Anthropic engineer on Hacker News recommended keeping context files under 1,000 tokens - roughly 60 lines. “We remove from it with every model release,” they said, “since smarter models need less hand-holding.”

Line budgets that work#

After three months of iteration across multiple repos, I’ve landed on these limits:

• AGENTS.md: Under 120 lines. This is the shared canonical source
• CLAUDE.md: Under 80 lines. Starts with @AGENTS.md to import the shared context, then adds Claude-specific instructions
• Bridge files (.cursorrules, copilot-instructions.md, etc.): Under 60 lines. Just tool-specific additions

Before I enforced these limits, my auto-loaded context was consuming about 2,613 tokens per session. After trimming to only undiscoverable signals, it dropped to about 1,554 tokens - a 41% reduction. The AI didn’t get worse. If anything, it got more focused because it wasn’t wading through architectural details it already knew.

AUTO-LOADED CONTEXT TOKENS PER SESSION

# CLAUDE.md

@AGENTS.md

## Claude Code specific

- Use `direnv exec .` for all wrangler and gh commands
- MCP servers: brave-search, github, trello, jina, pal, context7
- Hook: content-filter-guard.sh handles CODE_OF_CONDUCT generation

Read AGENTS.md for project conventions.

Cursor-specific: use the built-in terminal for build commands,
not the chat interface. TypeScript strict mode is enforced.