Claude Code as a Self-Maintaining KB
Every second-brain pattern on this site so far is about notes you read. This one turns the idea inward: applying the same capture-organise-retrieve discipline to the coding agent's own knowledge of your project, so it doesn't start from zero every session. This builds directly on Memory & CLAUDE.md - that page covers the mechanism; this page covers the practice of using it as a deliberate second brain rather than an occasional convenience.
The Problem It Solves
A coding agent session ends, and with it goes everything the agent figured out that session - which approach you rejected and why, what's mid-flight, which command actually works on your machine. Re-explaining this every session is the single biggest tax on long-running project work with an AI coding agent. The fix is the same one that works for a human second brain: write it down somewhere the agent reliably reads next time, in a form dense enough to be useful and short enough to actually get read.
Three Layers, Three Purposes
Each layer answers a different question: what are the rules, where do things stand, and what happened before
Why Three Separate Files, Not One
CLAUDE.md
Rules that should survive indefinitely - how to build, deploy, and what conventions to follow. If this file needs a change every session, it's the wrong place for what you're writing.
Living plan file
The single source of truth for where the project actually stands right now - task statuses, open questions, what to pick up next. Read first, every session, before any work starts.
Session log
A durable append-only record - what happened, when. Session transcripts get cleaned up automatically after a retention window; a log file in your own repo does not.
The Discipline That Makes This Work
- Update as you go, not at the end. A plan file only updated in a final wrap-up step gets skipped the moment a session runs out of room to finish gracefully.
- Put the most important thing first. An agent weighs earlier content in a file more heavily - current status and open decisions belong at the top, historical detail further down.
- Prune stale entries. A plan file that only ever grows becomes exactly the unstructured pile this pattern is meant to avoid - see Karpathy's LLM Wiki Pattern for the same failure mode in a different setting.
- Separate durable facts from session-scoped chatter. Not everything that happens in a session is worth remembering - save the decision and its reason, not the back-and-forth that led to it.
Scaling to Multiple Projects
The same three-layer pattern extends cleanly across several projects: each project keeps its own CLAUDE.md, its own plan file, and its own session log, so an agent working on one project never carries irrelevant context from another. See Routines for automating the recurring parts of this - a scheduled check-in that reads the plan file and reports status without you having to ask.
Checklist: Do You Understand This?
- Can you explain why standing instructions, current state, and history are kept in three separate files rather than one?
- Do you understand why updating the plan file continuously beats updating it only at the end of a session?
- Can you explain why a session log file matters even though CLAUDE.md and memory both persist?