L6Lesson 4

Session Log vs Rules File

After this, you'll maintain two separate artifacts from every session: an append-only session log of what you tried and decided, and a CLAUDE.md that contains only durable rules.

Before you start

Complete Prune the Rules File first; this lesson builds on having pruned so you understand from experience what should stay in the rules file versus flow into the log.

The idea

Here is the before and after: You added a note to your CLAUDE.md three months ago: 'tried migrating to Vite, hit ESM issues with legacy plugin X, reverted to Webpack for now.' Now every session, the model reads that note and either gets confused by the historical context or starts trying to re-attempt the migration unprompted. The note is not a rule. It is a log entry in the wrong place.

The rules file and the session log serve completely different purposes and should never be the same document. Your CLAUDE.md is a set of standing instructions the model reads at the start of every session. It should contain only rules that are true today and will be true next week. Your session log is an append-only audit trail of what happened: what you tried, what broke, what you decided and why.

What belongs in CLAUDE.md from the Vite incident is one rule: 'Do not migrate the build system to Vite until plugin X publishes ESM support.' The experiment narrative belongs in the log.

The session log structure is simple: date, task, what you tried, what broke, what you decided. Append only. Never edit old entries. The value is the audit trail: three months from now, you can trace exactly why a rule exists and whether the conditions that created it still apply.

After 30 sessions, your rules file should be under 80 lines. Your session log should be measured in weeks of entries. The rules file compresses. The log grows. They never merge.

Try it (20 min)

Watch out for

Editing old session log entries. The log is append-only. If you got something wrong, add a new entry that corrects it. Old entries are evidence, not drafts.
Putting the session log inside CLAUDE.md as a section. They must be separate files. The model loads CLAUDE.md every session. It should not load your experiment history every session.
Making the log template so detailed that filling it in takes 15 minutes. Five fields, 3 minutes maximum. If it is a burden, you will stop doing it.
Treating the session log as a substitute for the codify step. The log is where you record what happened. The codify step is where you extract the rule. Both are required.
Letting the session log grow indefinitely without ever referencing it. Once a month, scan the last 30 days of entries and check whether any logged decisions should become new CLAUDE.md rules or trigger a rules audit.

Paste this into Claude:

I want to set up a session log separate from my CLAUDE.md. Help me: (1) design a simple append-only format for logging what I tried, what broke, and what I decided each session (give me a template with 4-5 fields that takes under 3 minutes to fill in), (2) look at my current CLAUDE.md and identify any entries that are actually session notes, experiment histories, or 'remember when' annotations rather than standing rules, and (3) move those entries out of CLAUDE.md into the session log format, replacing each with a tighter rule if one is warranted. Show me the before and after for CLAUDE.md and the first entries in my new session log.

What good looks like:

You have a session log file with a consistent format you can fill in under 3 minutes
You removed at least one historical note or experiment narrative from CLAUDE.md
Each removed note became either a clean rule in CLAUDE.md or an entry in the session log, not both
You understand the test for which artifact an observation belongs in
You can describe the difference between 'what I tried' (log) and 'what the rule is' (CLAUDE.md) in one sentence

What a good response looks like:

Session log template (fill in under 3 minutes):

```
## [DATE] — [TASK TYPE]
Tried: [1-2 sentences on what you attempted]
Broke: [what failed or surprised you, or 'nothing']
Decided: [what you will do or not do going forward]
Rule extracted: [the CLAUDE.md rule if one applies, or 'none']
```

Entries from your existing CLAUDE.md that belong in the log instead:

Entry removed: 'Tried using Prisma for the DB layer, too much overhead for this project size, went back to raw SQL queries (2025-11)'
Why it is a log entry, not a rule: it describes an experiment and its outcome. The model does not need this history. It creates noise on every session load.
Moved to session log:
```
## 2025-11-12 — Database Layer
Tried: Prisma ORM for database access layer
Broke: Migration overhead too high for project size, generated migrations conflicted with existing schema
Decided: Raw SQL with parameterized queries only
Rule extracted: Do not introduce Prisma or any ORM. Use raw SQL with parameterized queries.
```
New CLAUDE.md rule: `Do not introduce Prisma or any ORM. Use raw SQL with parameterized queries.`

Entry removed: 'Note: the staging environment uses a different JWT secret than prod, caused auth failures in Oct'
Why it is a log entry: historical incident note. Not a standing rule.
Moved to session log as an incident entry, rule extracted: `Always check JWT_SECRET env var is set correctly in staging before testing auth flows.`

CLAUDE.md before: 24 lines. After: 18 lines. Session log: 2 entries, ready to grow.

When this breaks

Breaks when historical context lives in CLAUDE.md, because the model treats every line as active instruction and either gets confused by stale narrative or attempts to re-litigate decisions you already made and moved past.
Breaks when the log and the rules file collapse into one document over time, because no one prunes a file that is doing two jobs (the standing rules drown in narrative), and the model loads experiment history into context every session.

Claude can do it for you

Tell Claude: 'Design a session log template for me. 4-5 fields, takes 3 minutes to fill in after each session. Then look at my CLAUDE.md and identify any entries that are session notes rather than standing rules, and show me what to move where.' It will build the template and do the sort for you.

You can now

Produce two separate artifacts from your last session: a single-line CLAUDE.md rule and a 4-5 field session log entry, where the rule contains no narrative and the log contains no standing instruction.

Key takeaways

CLAUDE.md holds what is true now. The session log holds what happened and why. They serve different readers: one feeds the model, one feeds future you.

Two artifacts, two purposes: rules feed the model every session, the log feeds future-you when you need provenance
Append-only logs are evidence, not drafts. Never edit old entries. Add a correction entry instead
If the log template takes more than 3 minutes per session, you will stop using it. Five fields, ruthlessly simple
A monthly scan of the log catches rules that should exist but do not, and rules that should be retired

Go deeper

I want to set up a session log separate from my CLAUDE.md. Help me: (1) design a simple append-only format for logging what I tried, what broke, and what I decided each session (give me a template with 4-5 fields that takes under 3 minutes to fill in), (2) look at my current CLAUDE.md and identify any entries that are actually session notes, experiment histories, or 'remember when' annotations rather than standing rules, and (3) move those entries out of CLAUDE.md into the session log format, replacing each with a tighter rule if one is warranted. Show me the before and after for CLAUDE.md and the first entries in my new session log.

Session log template (fill in under 3 minutes): ``` ## [DATE] — [TASK TYPE] Tried: [1-2 sentences on what you attempted] Broke: [what failed or surprised you, or 'nothing'] Decided: [what you will do or not do going forward] Rule extracted: [the CLAUDE.md rule if one applies, or 'none'] ``` Entries from your existing CLAUDE.md that belong in the log instead: Entry removed: 'Tried using Prisma for the DB layer, too much overhead for this project size, went back to raw SQL queries (2025-11)' Why it is a log entry, not a rule: it describes an experiment and its outcome. The model does not need this history. It creates noise on every session load. Moved to session log: ``` ## 2025-11-12 — Database Layer Tried: Prisma ORM for database access layer Broke: Migration overhead too high for project size, generated migrations conflicted with existing schema Decided: Raw SQL with parameterized queries only Rule extracted: Do not introduce Prisma or any ORM. Use raw SQL with parameterized queries. ``` New CLAUDE.md rule: `Do not introduce Prisma or any ORM. Use raw SQL with parameterized queries.` Entry removed: 'Note: the staging environment uses a different JWT secret than prod, caused auth failures in Oct' Why it is a log entry: historical incident note. Not a standing rule. Moved to session log as an incident entry, rule extracted: `Always check JWT_SECRET env var is set correctly in staging before testing auth flows.` CLAUDE.md before: 24 lines. After: 18 lines. Session log: 2 entries, ready to grow.

Tell Claude: 'Design a session log template for me. 4-5 fields, takes 3 minutes to fill in after each session. Then look at my CLAUDE.md and identify any entries that are session notes rather than standing rules, and show me what to move where.' It will build the template and do the sort for you.