Context is all you need, part 2

In Context is all you need I wrote about context engineering and the patterns I'd found for managing AI context deliberately: the dumb zone, progressive disclosure, Research-Plan-Implement, sub-agents for isolation, compaction between phases. The fundamentals held up, but the tooling evolved fast enough that there's more to say.

The Pragmatic Engineer survey from February puts a number on the shift: 95% of respondents use AI tools weekly, 75% use AI for at least half their engineering work, and 55% regularly use agents. The question is no longer whether context engineering matters, but how to do it well.

Flow diagram showing the full context engineering workflow — How it all connects: persistence, phases, compaction

If you'd rather get your hands dirty than read, I packaged everything below into ACE (Advanced Context Engineering). Drop it into any repo, customize for your stack, and start shipping. The rest of this post is the reasoning behind it.

Context across sessions

Two mechanisms now seed each session with context from previous ones: CLAUDE.md files that live in your repo and get loaded automatically, and auto memory, where the agent writes notes about your corrections and preferences to files that carry forward.

Auto memory is the interesting one. When I correct the agent ("don't add attribution lines to commits", "use absolute imports"), it saves those corrections to ~/.claude/projects/<project>/memory/ and applies them in future sessions. Boris Cherny (Claude Code lead) and Cat Wu described the design on Latent Space: they chose flat files over vector stores because "agentic search outperformed everything, by a lot." In practice it's inconsistent and you'll sometimes find yourself repeating the same correction next week. When it works, it captures the stuff you wouldn't think to write down upfront.

CLAUDE.md handles the stable stuff: tech stack, conventions, non-negotiables. Auto memory handles the emergent stuff, corrections that come from actually working together. Cherny described on Lenny's podcast how each team at Anthropic maintains a CLAUDE.md in git to document mistakes so the agent improves over time, alongside style conventions, design guidelines, and PR templates.

Layer	What goes here	Example
CLAUDE.md	Stable conventions, tech stack, team standards	"Never mock the database in integration tests"
Auto memory	Corrections, preferences, learned patterns	"No AI attribution lines in commits"
Neither	Anything derivable from code or git history	Which files import what, recent diffs

The AGENTS.md movement encouraged people to generate these context files with LLMs, essentially asking the AI to write its own instructions. ETH Zurich tested this across 138 repositories and found that LLM-generated context files actually reduced task success rates by 3% while increasing inference costs by 20%, mostly because they restated what was already in READMEs and docstrings. Human-written files showed a modest 4% improvement, but only when they contained information the agent couldn't find elsewhere: specific tooling quirks, non-obvious conventions, custom build commands.

CLAUDE.md earns its keep with the stuff that lives nowhere in the repo: "we avoid ORMs here because of X", "the auth service talks to the legacy system through this specific adapter pattern", "don't touch the billing module without running the integration suite against staging." Write that kind of tribal knowledge by hand.

More broadly, I'd avoid over-indexing on scaffolding to compensate for model limitations. Sherwin Wu from OpenAI put it directly: "models will eat your scaffolding for breakfast." Invest in tool calling and making the agent's environment richer, things that compound with model improvements rather than working around current weaknesses.

Sub-agents and worktrees

Sub-agents can now get their own git worktrees: a separate copy of the filesystem, not just a separate context window. You opt in by adding isolation: worktree to a sub-agent's config or asking Claude to "use worktrees for your agents." The sub-agent makes changes in complete isolation, and the parent reviews what came back.

The pattern I use most is parallel research. Instead of one sub-agent reading through the codebase sequentially, I'll spawn three or four, each exploring a different subsystem. They run simultaneously and return compressed summaries. What took 10 minutes of sequential exploration now takes 2 minutes of parallel work.

When to use worktrees vs regular sub-agents:

Scenario	Use
Reading code, searching patterns, gathering info	Regular sub-agent (no filesystem changes needed)
Making experimental changes to test an approach	Worktree (isolation prevents conflicts)
Parallel implementation of independent features	Worktree (each agent needs its own file state)

For quick lookups, I skip agents entirely. I've worked in the terminal for decades, so reaching for rg, fzf, or git log --oneline --all --grep is faster than spinning up a sub-agent. These are instant, consume zero context window, and the muscle memory transfers across every project. If you're comfortable in the terminal, it's worth keeping those tools sharp. Agents are better suited for work that requires reading and synthesizing across many files, not for things you can answer with a one-liner.

Hooks

Part 1's workflow was entirely manual. Claude Code hooks let you automate parts of it: shell commands that fire in response to events (before/after tool calls, session start) and can inject context, validate changes, or run checks.

Convention validation before commits. Not a linter (you already have those), but structural checks the linter can't catch:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "if echo \"$CLAUDE_TOOL_INPUT\" | grep -q 'git commit'; then echo 'Reminder: run tests first.'; fi"
          }
        ]
      }
    ]
  }
}

json

Path-based context injection. In Part 1, the context hierarchy (root conventions, package architecture, domain details) was passive, relying on someone to pull in the right file. Wire a PostToolUse hook so that when the agent opens a file in pkg/auth/, it automatically receives the security team's conventions:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Read",
        "hooks": [
          {
            "type": "command",
            "command": "if echo \"$CLAUDE_TOOL_INPUT\" | grep -q 'pkg/auth'; then cat pkg/auth/.context.md; fi"
          }
        ]
      }
    ]
  }
}

json

The risk is hooks that inject so much context the agent starts in the dumb zone. Start with one or two that solve a real problem.

Manual compaction over auto

Claude Code auto-compacts around 95% capacity, compressing the conversation based on current task goals. In practice it loses things: approach decisions, constraints from early in the conversation, reasoning behind implementation choices. I've had sessions where after auto-compaction the agent re-explored files it had already read, or forgot a constraint I'd stated 20 minutes earlier. I deliberately chose manual compaction in Part 1, and I still do.

I compact manually at phase transitions instead. Finish research, summarize to a markdown file, start fresh. Auto-compaction handles noise within a phase, but the deliberate reset between phases keeps context cleaner.

There's a subtler reason to reset: trajectory. LLMs learn patterns within a conversation. If the session has a correction loop going (mistake, correction, mistake, correction), the most likely next output is another mistake. Restarting with compressed context breaks the pattern. Sometimes the fastest fix is a fresh window, not another correction.

MCP as context source

The ecosystem exploded to thousands of servers, tools for everything from Slack to databases to deployment pipelines. Every tool definition consumes context before you've even asked it to do anything. A generous MCP setup with 20+ tools can eat 10-15% of your context window just sitting there. I keep my active set small: filesystem, git, and one or two project-specific tools. Everything else gets connected only when I need it.

Felix Rieseberg from Anthropic described on Latent Space how a team skipped building an MCP server for a data warehouse and just wrote a markdown file explaining the API. Claude figured out the rest. "Plain text files beat structured protocols because the model is smart enough to infer what the protocol would have specified." A well-written document in your repo is often cheaper and more effective than another MCP integration.

There's also a security dimension that didn't exist three months ago. The MCP ecosystem saw 30 CVEs in its first 60 days. Tool definitions can contain instructions that influence agent behavior, a form of indirect prompt injection. If you're connecting to third-party MCP servers, you're trusting them with your context window. Vet what you connect.

From RPI to structured phases

Part 1 introduced Research-Plan-Implement. It worked, but Dex Horthy at HumanLayer ran it for six months and found real failure modes. The research step used a single sub-agent with a broad prompt that consumed ~40% of context just for orientation. The planning prompt had 85+ instructions, well over what models reliably follow.

Frontier LLMs can track about 150-200 instructions before they start silently dropping requirements. When you combine system prompts, planning prompts, tool definitions, and MCP servers, you go over budget and the model just ignores things without telling you. Dex's fix was splitting one big prompt into eight steps of under 40 instructions each: Question, Research, Design, Structure, Plan, Worktree, Implement, PR.

I don't use all eight every time. Match the process to the complexity:

Task	Example	Steps
Trivial	Fix a typo, change a button color	Direct chat
Simple	Add a field to an API response	Plan, Implement
Medium	Add pagination to a list endpoint	Research, Plan, Implement
Complex	Redesign permissions model across services	All 8 steps
Extremely complex	Extract microservice from monolith	Whiteboard first, then all 8

Bump up one level if you've never seen the affected code, drop one level if you wrote it yourself. A plan you didn't need costs 10 minutes. A rewrite costs hours.

The highest-leverage review point is the Structure, not the Plan. Structure is ~2 pages. A Plan can be hundreds of lines. If you disagree with the phasing or approach, catch it at Structure before anyone spends time detailing exact file:line changes in a Plan that gets thrown out.

The other thing Structure fixes is how models plan by default. Left to their own devices, models write horizontal plans: all the database changes, then all the services, then all the API, then all the frontend. You end up 1,200 lines deep with nothing testable. Vertical plans slice through the stack: mock an endpoint, wire it to the frontend, add the service layer, do the migration, connect everything. Same amount of code, but you get checkpoints where you can verify things actually work before continuing. The Structure phase is where you enforce this. Break the work into vertical slices with validation after each one.

The template

I built ACE (Advanced Context Engineering) to make this workflow portable across projects. It's a starting point, not a prescription. Customize the commands for your stack, strip what you don't need, and iterate. The real value comes from sharing what works across teams and repos:

.claude/
├── commands/                    # One per phase
│   ├── question.md              # Surface decisions before research
│   ├── research.md              # Map the codebase with sub-agents
│   ├── design.md                # Define the end state
│   ├── structure.md             # Break into testable phases
│   ├── plan.md                  # Exact steps with file:line refs
│   ├── worktree.md              # Isolate for implementation
│   ├── implement.md             # Execute phase by phase
│   └── pr.md                    # Ship with context attached
└── agents/                      # Sub-agent definitions
    ├── codebase-locator.md
    ├── codebase-analyzer.md
    └── pattern-finder.md

shell

Each command stays under 40 instructions. The sub-agents follow a strict principle: they're documentarians, not critics. Here's the locator agent's entire persona:

You are a specialist at finding WHERE code lives in a codebase.
Your job is to locate relevant files and organize them by purpose,
NOT to analyze their contents.

YOUR ONLY JOB IS TO DOCUMENT THE CODEBASE AS IT EXISTS TODAY.
- DO NOT suggest improvements or changes
- DO NOT critique the implementation
- ONLY describe what exists, where it exists, and how components
  are organized

markdown

If you let research agents suggest changes, they produce opinions instead of maps. The research command enforces the same discipline when decomposing work for sub-agents:

Frame sub-agent tasks as targeted factual questions, not goal
statements.

Wrong: "Research how the auth system works so we can add OAuth"
Right: "What files handle authentication? Trace the login flow
       from entry point to session creation."

If you tell the model what you're building, you get opinions.
If you ask factual questions, you get facts.

markdown

The implement command closes the loop with after-action reports between phases: what succeeded, what failed, what the next phase should know. This prevents repeating the same mistakes across a session.

Multi-agent orchestration

For larger features, I've moved from sequential research to parallel decomposition. A feature that touches the API, the frontend, and the database gets three research agents simultaneously, one per subsystem. They return summaries in parallel, and I synthesize into a unified plan.

OpenAI is pushing this further. Sherwin Wu described on Lenny's podcast how 95% of their engineers use Codex daily, each managing fleets of 10-20 parallel agents. That's an extreme end, and I'm skeptical it works as cleanly as described for most codebases. Harper Reed's counterpoint is more honest: "these workflows are not easy to use as a team, the bots collide, the merges are difficult, and the context is complicated."

Parallel orchestration doesn't replace structured phases. You're parallelizing the research phase and merging results before planning. Where it breaks down is when you don't know the territory well enough to decompose upfront, or when subsystems are coupled in ways you didn't expect.

The leverage hierarchy, revisited

Part 1:

CLAUDE.md > prompts > research > plans > implementation

With persistent memory and hooks, there are new layers:

CLAUDE.md > persistent memory > hooks > prompts > research > plans > implementation

Invest effort at the top. CLAUDE.md shapes every conversation. Persistent memory refines behavior over weeks. Hooks automate context decisions you used to make manually. By the time you're writing a prompt, three layers are already working.

Kent Beck draws a useful line between "vibe coding" (you don't care about the code, just the behavior) and "augmented coding" (you care about the code, its complexity, the tests, their coverage). Without context engineering, you're vibe coding by default. If you're writing detailed prompts every session because the agent doesn't know your conventions, you're working at the wrong layer.

The gap

The METR study found experienced developers were 19% slower with AI tools on mature open-source codebases, while believing they'd been sped up by 20%. Their 2026 follow-up revised this to roughly breakeven. The tooling got better, the net effect barely moved. That should tell you something about where the bottleneck actually is.

Memory drift is the one I keep running into. Corrections that made sense for one codebase become wrong assumptions in another, and flat-file memory has no expiry mechanism. The agent carries forward a preference you set three projects ago and applies it where it doesn't belong. Startups like Honcho, Supermemory, and Zep are building temporal awareness and contradiction detection into memory infrastructure. I've been building something in this space too, more on that soon.

For routine tasks, I let the agent self-direct. For anything novel, I impose explicit phases. The less familiar the territory, the more structure I want. The failure mode used to be "the agent doesn't know anything." Now it's "the agent remembers the wrong things."

Start with Part 1 if you're new to this. If you've been doing this for a while, I'm curious what patterns you've found that I'm missing.