Ask Knox

Introduction

The 200-line discipline for CLAUDE.md is not about arbitrary limits — it is about a failure mode that Knox has observed repeatedly: when CLAUDE.md grows unchecked, critical Tier 1 rules get buried under Tier 2 and Tier 3 content. Claude reads the file, but the high-priority rules are lost in the noise.

The three-tier system is the engineering discipline that prevents this. It asks a single question about every piece of content: "Does this need to load every single turn, or only sometimes?"

The Three Tiers

Tier 1: Always Load (≤80 lines, first in the file)

Tier 1 is the non-negotiable, always-on block. These are rules that, if violated, cause immediate and potentially serious damage. They apply regardless of task type, project, or session context.

From Knox's global CLAUDE.md, examples of genuine Tier 1 rules:

NEVER commit directly to main — violation causes direct damage: PR history lost, CI bypassed, other agents blocked
Run git branch --show-current before any Write, Edit, commit, or push — violation causes silent file modification on the wrong branch
Post-PR retro is mandatory — violation breaks the compound learning loop
90% coverage floor — violation allows technical debt accumulation that CI would catch
Supabase is the only auth stack — violation creates a security architecture inconsistency that may not be obvious until production

The test for Tier 1: "If Claude ignores this rule even once, is there immediate damage?" If yes, it is Tier 1. If the damage is delayed or recoverable, it may be Tier 2.

Tier 2: Load on Access

Tier 2 is the middle layer — content that is important and contextually relevant but not needed on every turn. The correct storage mechanism is separate sub-doc files — scoped via sub-directory CLAUDE.md files or read on demand by the agent.

Examples from Knox's stack:

design-system/MASTER.md — critical for UI work, irrelevant for backend API tasks. The agent reads it when the task type is frontend.
design-intelligence.md — detailed design anti-patterns and typography rules. Load for any visual work, not for trading bot fixes.
Per-page design overrides in design-system/pages/ — load only when working on that specific page.
lessons.md for the current project — load at session start for that project, not globally.

Tier 2 has two delivery mechanisms, and the distinction matters: @imports (@AGENTS.md) resolve eagerly at load time — right for sub-docs every session in the repo needs — while lazy-read instructions ("Read design-system/MASTER.md before any UI work") load a file only when the agent executes the read for a matching task. There is no conditional @import; task-conditional Tier 2 content uses the lazy read.

Tier 3: On Demand Only

Tier 3 is content you need rarely — only for specific, targeted retrieval. The correct home is Semantic Memory Layer, not CLAUDE.md.

Examples:

Daily logs (~/.config/agent/workspace/memory/2026-05-31.md) — fetched only by the morning-brief or RCA skill
Incident RCAs — queried when diagnosing a recurring failure class, not on every session start
API specs for external services — fetched by verify-deps skill when checking signature compatibility
Historical decision logs — queried from Semantic Memory Layer when understanding "why was this built this way?"

The query-first habit (memory_query("project") at session start) provides targeted Tier 3 retrieval without pre-loading everything. You get the relevant subset of your 2,968-chunk knowledge base, not the full corpus.

The Anatomy of a Well-Structured CLAUDE.md

A healthy 180-line CLAUDE.md for a complex project looks like this:

Lines 1–80:    Tier 1 block
               - Non-negotiable rules (git workflow, test gates, security)
               - @-imports for sub-documents (AGENTS.md, lessons reference)
               - HOST CHECK if machine-specific (for Knox's dual-machine setup)

Lines 81–150:  Architecture quick-ref
               - Key files table (what each file does)
               - Commands reference (npm run test, npx tsc --noEmit)
               - Tech stack choices (Supabase, Vitest, Next.js App Router)
               - API routes inventory

Lines 151–180: Behavioral reminders
               - Agent discipline notes
               - Stop-and-replan rule
               - Known footguns for this specific project

What is NOT in this file: design tokens, full API documentation, historical context, step-by-step setup guides, code examples, or anything that is better as a linked sub-doc.

The Bloat Failure Mode

When Tier 2 and Tier 3 content flows into CLAUDE.md, three things happen:

Critical rules get buried — Claude reads the file top to bottom, and if "never commit to main" is on line 187 of a 280-line file, it competes with design token tables and setup guides for Claude's attention.
Token cost increases — every extra line is paid for on every turn, compounding across hundreds of sessions.
File becomes a maintenance nightmare — when rules, reference docs, examples, and history are all mixed together, outdated content is hard to identify and remove.

The /context-budget skill is the auditing tool for this failure mode. It surfaces: how many tokens is CLAUDE.md consuming, how does that compare to the total window, and which sections are Tier 2/3 candidates for extraction.

Practical Application: Running the Tier Audit

For each entry in your CLAUDE.md, ask three questions in sequence:

"If Claude ignores this once, is there immediate damage?" → Yes: Tier 1 (keep). No: continue.
"Is this needed for UI/frontend tasks but not backend tasks?" → Yes: Tier 2 (@import pattern). No: continue.
"Is this reference content I look up occasionally?" → Yes: Tier 3 (Semantic Memory Layer). No: consider whether it should be in the file at all.

Run this audit every 30 days or whenever CLAUDE.md exceeds 200 lines. The 200-line breach is a forcing function — it forces the audit rather than letting bloat accumulate indefinitely.

Summary

Three tiers: always-load (Tier 1, ≤80 lines, first in file) → load on access (Tier 2, sub-docs read when the task fires) → on demand (Tier 3, Semantic Memory Layer)
Tier 1 test: "If Claude ignores this once, is there immediate damage?" — only these rules earn the always-on slot
Tier 2 is for important-but-conditional content — design system, per-project lessons, domain specs
Tier 3 is for reference material, historical context, and rarely-needed specifics
The 200-line cap is a forcing function that triggers the tier audit before bloat becomes architectural debt

What's Next

The next lesson introduces progressive disclosure — the mechanism that lets you load Tier 2 and Tier 3 content exactly when it is needed, including deferred tools, @-imports, and skill-triggered context loading.

Tiered Importance — What Belongs Where