ASK KNOX
beta
Learn/Context Engineering & CLAUDE.md Architecture/Lesson 378
LESSON 378

The Context Engineering Playbook

The complete system: how all five context layers combine into a production-grade setup, and the hands-on audit checklist to verify your own CLAUDE.md and memory setup against the playbook standard.

9 min read·Context Engineering & CLAUDE.md Architecture

Introduction

This is the capstone lesson for the Context Engineering track. Everything this track has covered — the four-lever frame, token accounting, CLAUDE.md hierarchy, tiered importance, progressive disclosure, memory files, knowledge OS, rot detection, pruning, and domain scoping — assembles into a coherent system.

The goal of this lesson is not to add new concepts. It is to show how the full stack works together in practice, and to give you the audit checklist that verifies your own setup against the playbook standard.

The Complete System Assembly

A fully-engineered context session uses five components, each with a specific role and token budget:

Component 1: CLAUDE.md (Tier 1 block, ~800 tokens) Always-on. The ~40-line Tier 1 block specifically — the non-negotiable rules, git workflow, safety gates, and @-import directives. (The full CLAUDE.md, up to the 200-line discipline, runs ~3,600 tokens; this component budgets only the Tier 1 core that must lead the file.) Covers all four hierarchy levels: enterprise → project → sub-directory → session.

Component 2: Progressive sub-docs (~0–4,000 tokens, triggered) Conditionally loaded: design-system/MASTER.md read by the agent when UI work begins, AGENTS.md @imported (eagerly, with CLAUDE.md) in the academy repo, lessons.md read for active project sessions. Never inlined in CLAUDE.md — always separate files: @imported when they should load with every session, read on demand when they are task-conditional (@imports resolve eagerly and cannot be conditional).

Component 3: Semantic Memory Layer (~1,200 tokens per query result) Query-first habit: memory_query("project-name") before any file read. Surfaces architecture notes, known failure modes, behavioral feedback, and prior session decisions from 2,968 indexed chunks across 43 repos. Namespace-filtered to prevent cross-domain contamination.

Component 4: Deferred Tools (~400 tokens per loaded schema) ToolSearch fetches MCP schemas only when a skill fires. 50+ tool schemas are available (at ~300–400 tokens each, ~18,000 tokens if all loaded) but only 2–5 are typically loaded per session. From ~18,000 tokens of speculative overhead to ~2,000–4,000 tokens of precision-loaded tooling.

Component 5: lessons.md (~600 tokens) Session-start read for the active project. The anti-pattern register: what went wrong, root causes, rules. Escalation path: 3+ recurrences in same category → move rule to CLAUDE.md Tier 1.

Total budget: ~3,400 tokens baseline (no @-imports), ~8,200 tokens full session (all components loaded), leaving 190K+ tokens available for actual work in a 200K window.

The Playbook Audit Checklist

Run this audit every 30 days against your own CLAUDE.md and memory setup.

CLAUDE.md Structural Audit

The HARD gates that cause immediate damage if violated:

  • Total lines ≤ 200 (use wc -l CLAUDE.md to check)
  • Tier 1 block in first 80 lines, delineated clearly
  • No Tier 2/3 content mixed into Tier 1 block
  • Skill files in ~/.claude/skills/, not inlined in CLAUDE.md

The SOFT gates that create drift over time:

  • Every rule has a date stamp or explicit "timeless" annotation
  • @-imports used for sub-docs instead of inline paste

Memory & Semantic Memory Layer Audit

HARD gates:

  • memory_query runs at session start for every project (query-first habit)
  • Every correction ends with memory_remember + lessons.md entry

SOFT gates:

  • MEMORY.md index links all resolvable (no orphaned topic file references)
  • One topic file per fact — no monolith MEMORY.md with inline blocks
  • memory_status run to verify chunk count matches what MEMORY.md documents

Progressive Disclosure Audit

HARD gates:

  • design-system/MASTER.md is a separate file read on demand, not inlined
  • Sub-agent prompts contain only domain-relevant context
  • Skill files in ~/.claude/skills/, never in source code

SOFT gates:

  • Deferred MCP tools fetched via ToolSearch, not pre-loaded
  • Session compaction before turn 20 when verbose output detected

Freshness & Pruning Audit

HARD gates:

  • No contradictory rules active simultaneously (one supersedes, one is removed)

SOFT gates:

  • /context-budget run to surface any bloat > 200 tokens per section
  • Deprecated tools/services marked with date in CLAUDE.md
  • lessons.md entries follow ## [Date] — [Category] format

Building Your Own Stack: The Minimal Viable Setup

You do not need the full Semantic Memory Layer deployment to implement this playbook. The minimum viable context engineering stack:

  1. Project CLAUDE.md (80 lines or under): five rules that, if violated, cause immediate damage + the key files table + the tech stack choices
  2. lessons.md with three fields (mistake → root cause → rule) added after every correction
  3. memory_remember after every session retro, even a one-sentence summary
  4. memory_query at the start of every session (even if you only have 10 memories — it surfaces the ones you have)
  5. /compact at turn 15–20 with verbose tool output

This five-point minimum establishes the habit infrastructure. The system grows with every session: more lessons, more memories, richer Semantic Memory Layer context. At 50 memories, cross-session pattern detection begins. At 200 memories, the knowledge OS becomes the most valuable context layer.

The Context Engineer's Edge

The operators who compound fastest are not the ones who use the best model. They are the ones who build context layers that teach the model what it cannot learn from training data:

  • The specific failure mode their team has hit 3 times
  • The exact API quirk that caused a production incident
  • The design decisions that were made and why they can't be undone
  • The conventions that were discovered over months of session work

This knowledge does not exist in Claude's training data. It exists only in CLAUDE.md, lessons.md, and Semantic Memory Layer — built and maintained by an operator who treats context as the product.

The Compounding Mechanism

The compound learning loop (the “Memory Files & Persistent State” lesson) is what separates a static CLAUDE.md from a living context engineering system. Every correction, every discovered pattern, every pruning pass makes the next session better:

Month 1: Basic CLAUDE.md, empty lessons.md, 10 Semantic Memory Layer memories. Sessions are good but agents repeat known mistakes.

Month 3: 30 lessons.md entries, 150 Semantic Memory Layer memories, CLAUDE.md Tier 1 refined from 3 escalations. Sessions reliably avoid common failure modes.

Month 6: 70 lessons.md entries, 400 Semantic Memory Layer memories, cross-project pattern detection active. The knowledge OS surfaces connections between problems that the agent wouldn't have made without the accumulated context.

Month 12: The knowledge OS is the most valuable asset in the system. No model upgrade can replicate it. No competitor with a generic context can match it. This is the moat.

Summary: The Context Engineering Playbook

The complete playbook, in one paragraph: Build CLAUDE.md Tier 1 first (≤80 lines of non-negotiables, 200-line total limit). Use progressive disclosure for everything else (sub-docs read on demand for Tier 2, Semantic Memory Layer for Tier 3). Establish the query-first habit (memory_query before every session). Maintain lessons.md with the three-field format after every correction. Compact sessions before turn 20 with verbose output. Prune monthly using the four-question decision tree. Scope each agent's context to its domain only. Run the audit checklist every 30 days. The system compounds with every cycle — context is the product, and the product gets better every session.

Track Complete

You have completed the Context Engineering & CLAUDE.md Architecture track. The key takeaways across all 11 lessons:

  1. Context is the dominant lever (60%) — build it first, optimize it constantly
  2. The context window is a budget — account for the reread tax on every session
  3. CLAUDE.md is a hierarchy — four levels, inner overrides outer on conflict
  4. Three tiers of importance — always-load, load on access, on demand only
  5. Progressive disclosure reduces speculative token cost by 70%+
  6. Memory files are the persistence layer — one-fact-per-file rule prevents contradiction
  7. Semantic Memory Layer is the knowledge OS — query-first habit, 10 tools, 6 namespaces
  8. Context rot is active misleading — freshness signals and pruning are engineering requirements
  9. Pruning is precision — the four-question decision tree keeps context sharp
  10. Domain scoping improves agent quality — focused 80-line context beats noisy 400-line omnibus
  11. Context engineering is an ongoing practice — the compound learning loop never stops

The leverage compounds with every session. Start the practice today.