5.4 Building a Second Brain

CLAUDE.md holds the rules; it deliberately stays short. But projects accumulate knowledge — research, decisions and their reasons, style references, meeting notes, dead ends you don't want to re-explore. A second brain is that knowledge kept as plain files your agent can read on demand. This lesson builds yours and wires it into every session.

What you will learn

• Structure a docs/ knowledge base agents can actually navigate.
• Write decision records — the single highest-value document type in agentic work.
• Make the agent both consult and maintain the second brain.

Builder principle

Knowledge in your head helps you. Knowledge in plain files helps you, your agent, your collaborators, and the you of next year — same effort, four beneficiaries.

Why files beat brains

The insight is almost embarrassingly simple: agents read files. Every piece of project knowledge sitting in a readable, findable file is knowledge your agent can gather (loop phase 1) exactly when a task needs it — without you spending your session context or your patience re-explaining.

CLAUDE.md is the index and rulebook — loaded always, kept lean. The second brain is the library — loaded when relevant, allowed to grow. The two work as a system: CLAUDE.md says where the library is and when to check it.

Data gate — complete before creating the library

1. Classify: Is each source public, internal, confidential, personal, or regulated?
2. Authorize: Do you have permission to provide it to this agent and its tools?
3. Check handling: Do the provider, account, retention, and organizational controls permit this use?
4. Minimize: Store only what the project needs; remove secrets, names, identifiers, and unnecessary raw notes.
5. Substitute: When any answer is unclear, use synthetic notes and decisions for this exercise. Do not add the real material.

An agent-readable file is data shared with the agent, even when the file is local or excluded from Git. Repository privacy and .gitignore do not determine what the model or connected tools can access.

The structure

Boring and predictable on purpose — agents (and humans) navigate boring well:

my-project/
├── CLAUDE.md
├── docs/
│   ├── decisions.md      ← why things are the way they are
│   ├── style.md          ← voice, design references, examples of "good"
│   ├── research.md       ← what we learned: competitors, users, options weighed
│   └── log.md            ← running build journal (newest on top)

Four files. Not seventeen folders, not a wiki, not an app — four markdown files. Add a fifth only when one of these overflows.

Then wire it into CLAUDE.md:

## Knowledge base
- docs/decisions.md — check before proposing architectural or design changes
- docs/style.md — consult for any user-facing copy or visual work
- docs/research.md — background; check before re-researching anything
- docs/log.md — read the top entry at session start for current state

Those aren't links — they're behavioral instructions. "Check before proposing" tells the agent when to reach for what. That's the wiring that makes the library alive.

Decision records: the crown jewel

The most valuable page is decisions.md, and each entry is four lines:

## 2026-07-02 — Single page, no framework
DECIDED: entire site stays one index.html; no React/build tools.
BECAUSE: client edits it herself; simplicity is the feature.
REJECTED: Astro (overkill), Wix (client had bad experience).

Reasons can help a person or agent apply a decision in a new situation. A rule ("no frameworks") states the boundary; a reason ("client edits it herself") supplies context for reviewing edge cases. REJECTED: also records alternatives that should not be proposed again without new evidence.

The agent as librarian

The second brain would die if you maintained it by hand. You won't — the agent will:

End of any significant session:

Before we close out: update docs/log.md with a dated entry — what we
did, what's unfinished, what to pick up next. And if we made any
decision today that future sessions should honor, add it to
docs/decisions.md in the standard format.

Start of the next session (this line can live in CLAUDE.md so it's automatic): read the top of the log. The result is continuity that feels like sorcery — a fresh session, empty whiteboard, that opens with "I see we shipped the testimonials section last time and the favicon is still pending — start there?"

That's the payoff of the whole layer stack: session memory dies, project memory persists, and the second brain carries the narrative.

🌱 No-code lane⚙️ Engineer lane

Your builder's journal from Chapter 1? It just found its destiny — its project-relevant entries become docs/log.md. You've been building a second brain since Lesson 1.5 without knowing it. Now the agent reads it too.

This is ADRs (architecture decision records) generalized to all project knowledge — and if your team already keeps ADRs, point CLAUDE.md at them and you're done. The step most teams miss: feeding the brain from agent sessions (the librarian prompt), so knowledge captured during AI-assisted work doesn't evaporate when the terminal closes. In Chapter 7 you'll package the librarian routine as a Skill; in Chapter 9, a hook can make the log update automatic.

Try it now

1. Complete the data gate above. Create docs/ with the four files in your quick-win project, using synthetic content if the real project is not approved. Seed decisions.md with two safe-to-share decisions you've already made (you have — think: no frameworks? single page? color scheme?). Use the four-line format, REJECTED: included.
2. Add the Knowledge base section to CLAUDE.md with behavioral wiring.
3. End today's session with the librarian prompt. Commit everything.
4. Tomorrow (actually tomorrow): start a session with What's the current state of this project and what's next? — and watch the narrative continuity land.

Check your understanding

• What's the division of labor between CLAUDE.md and the second brain?
• Why do agents honor reasons better than rules, and which line of the decision format carries the reason?
• What prevents the "re-proposing rejected ideas" loop?
• How does the second brain get maintained without your discipline being the bottleneck?