The 200-Line Rule

CLAUDE.md has a job description: give an agent the cognitive map it needs to operate in your codebase without reading every file from scratch. A system diagram. The file hierarchy that matters. The rules that prevent catastrophic mistakes. The commands that get things done.

That is the job. The file that accumulates in practice is something different.

It is the v4-to-v5 migration narrative that was urgent in November and irrelevant by January. It is the full .env.example block because someone thought the agent might need it — even though the actual .env.example file is right there. It is the verbatim output of ls -R from six months ago when the directory structure was different. It is the 15-row factor scoring table for the trading strategy, which has been updated three times but not in CLAUDE.md.

This is not negligence. It is — individually reasonable additions that nobody reviewed as a whole.

The 200-line rule is the enforcement mechanism.

The Three-Category System

Every line in CLAUDE.md falls into one of three categories. Applying this classification is the entire pruning process.

Category 1: Always Remove

These items have no place in CLAUDE.md. They are either stale by design, redundant with existing files, or retrievable in one tool call.

Verbatim file trees. An agent can run ls or use Glob in under a second. A file tree in CLAUDE.md was accurate on the day it was added. Every subsequent file rename, addition, or deletion makes it less accurate. It burns tokens on every load while delivering information that is both retrievable and stale.

Version-transition narratives. "We migrated from v4.2 to v5.0 in November. The old approach did X. The new approach does Y. If you see Z, it's a legacy artifact." This was useful during the migration. After the migration, it is archaeology. The agent only needs to understand the current system.

Full .env.example blocks. The file exists. It is at the path the agent can find. Duplicating it in CLAUDE.md adds 20–40 lines that go stale when variables change. A one-line pointer to the file serves the same purpose.

Live statistics with dates. "As of January 2026, we have 1,970 tests." Statistics with embedded dates go stale in weeks. An agent that reads a stale statistic makes decisions based on wrong information. The actual test count is available by running pytest --collect-only | wc -l.

SQL query examples. If query patterns matter, they belong in a runbook or docstring — not in CLAUDE.md where they consume tokens on every session that has nothing to do with database queries.

Category 2: Condense to One Line

These items have real value but are wildly over-expressed. The information should be preserved as a pointer or prose summary.

Factor scoring tables. The Foresight bot's CLAUDE.md included a 15-row table mapping each signal factor to its weight range, status, and description. That is 40 lines. The condensed version:

# Before: 40 lines
| Factor | Weight | Range | Status | Description |
|--------|--------|-------|--------|-------------|
| price_momentum | 35 | 0-35 | active | 1h/4h/24h price delta... |
| technical_analysis | 30 | 0-30 | active | RSI + Bollinger Band... |
...13 more rows...

# After: 1 line
11 factors in src/strategy.py. Primary: price_momentum (0-35), technical_analysis (0-30). Thresholds: STRONG ≥80, MODERATE ≥70.

The one-line version points the agent to the authoritative source. The 40-line version is a stale copy that diverges from truth every time a threshold is tuned.

Environment variable tables. A table of 25 env vars with descriptions, types, and required/optional flags is 30 lines. The condensed version: "Key vars: POLYMARKET_API_KEY, STRATEGY_MODE, STOP_LOSS_THRESHOLD. Full list with defaults in config.py." That is one line. The agent reads config.py when it needs details — and gets the current state, not a snapshot.

Setup blocks. Multi-step installation instructions belong in RUNBOOK.md. In CLAUDE.md: "Setup: see RUNBOOK.md. TL;DR: make install && cp .env.example .env." Two lines.

Category 3: Always Keep

These items earn their line count. An agent cannot retrieve this information from any single source file, and the cost of not having it is measured in bad decisions.

Architecture overview. Not a file tree — a system diagram in prose or ASCII. Module boundaries, data flow, the relationship between components. A 30-line architecture overview prevents an agent from misunderstanding how the system fits together.

Tiered file guide. This is the highest-value section in any CLAUDE.md. It classifies files into tiers: T1 (always read), T2 (read when working on feature X), T3 (ignore). A pointer costs one line. Without it, the agent explores blindly, reading files that are irrelevant to its task.

Do NOT rules. These are the safety rails. "Do NOT commit directly to main." "Do NOT modify shared Foresight modules for Leverage fixes." "Do NOT run destructive commands without confirmation." These rules prevent the class of mistakes that cost hours to reverse. They are non-negotiable.

Common tasks cookbook. Ten to fifteen lines covering the operations the agent needs most: how to run the test suite, how to deploy, how to trigger a specific cron, what command to use for debugging. These save the agent from reading setup docs to find a single command.

The Before and After

The Foresight bot's CLAUDE.md was 465 lines. After applying the three-category system, it landed at 151 lines.

What was removed:

• A 121-line verbatim file tree (stale, retrievable via Glob)
• A full .env.example block (32 lines, replaced with a one-line pointer)
• SQL query examples from the reporting module (18 lines, moved to inline docstrings)
• Three version-transition narratives from the v4-v5 migration (41 lines, deleted entirely)
• A factor scoring table (40 lines, condensed to 2 lines)

What was kept:

• Architecture overview with module boundaries (28 lines)
• Tiered file guide with T1/T2/T3 classification (38 lines)
• Do NOT rules (12 lines)
• Common tasks cookbook (15 lines)
• Configuration prose with key var list (8 lines)

The 151-line result covers everything an agent needs and nothing it does not. Sessions load 1,900 tokens of context instead of 6,000. The information is more accurate because the stale sections are gone.

The Line Budget

A practical allocation that fits in 200 lines with 38 lines of buffer:

Section	Budget
Header + pointer to docs	5 lines
Architecture overview	35 lines
Config prose (not tables)	8 lines
Tiered file guide	35 lines
Do NOT rules	10 lines
Common tasks cookbook	20 lines
Separators + section headers	15 lines
Total	128 lines

The 72-line buffer accommodates project-specific sections. When the buffer is exhausted, the pruning cycle restarts.

The Fundamental Question

Every line that survives a pruning cycle must answer yes to:

A tiered file guide pointer saves five file-read round trips. Yes. A one-line env var list saves a config.py scan. Yes. A verbatim file tree from six months ago describes files that may not exist. No. A scoring table tuned three times since it was written tells the agent wrong thresholds. No.

The question is not "is this information true?" It is "does including it here produce better outcomes than removing it and letting the agent find it at the source?"