Capture Decisions and Session Notes in Claude

Preserving the “why” across sessions

What this step is

The fourth habit (after CLAUDE.md, spec.md, and the plan-first workflow) when working with Claude: write down what you decided and what happened, as you go, so future-you and future-Claude don’t lose the context.

This is the habit that makes Claude actually remember across sessions. Everything else (CLAUDE.md, specs, plans) sets up the work. Notes preserve what you learn from the work.

Why this matters

You’ll come back to this project in two weeks, two months, or two years. By then you will have forgotten:

• Why you chose Library A over Library B
• That you tried approach X and abandoned it because of edge case Y
• What the “obvious” assumption was that made the code structure make sense
• Which TODOs are real vs. leftover from earlier brainstorming

Without notes, you and Claude will re-debate the same decisions, re-discover the same dead ends, and slowly drift away from the original intent.

Code shows what. Notes show why. Claude can read the code perfectly fine — it cannot reconstruct your reasoning.

The two kinds of notes

1. Decisions — long-lived, one per choice

Lives in docs/features/<name>/decisions.md (or a project-wide docs/decisions/ folder for cross-cutting choices). Each entry is short and structured.

Template:

## YYYY-MM-DD — Short title of the decision

**Context:** What problem or situation triggered this decision.
**Decision:** What we chose to do.
**Alternatives considered:** What we rejected, and why.
**Trade-offs:** What this costs us, that we accept.

Example:

## 2026-05-15 — Use JWT instead of session cookies for auth

**Context:** Mobile app needs to share auth with web frontend.
**Decision:** JWT with refresh tokens, 15-min access token lifetime.
**Alternatives considered:** Session cookies (rejected: cross-domain pain),
OAuth-only (rejected: overkill for our scale).
**Trade-offs:** Slightly more complex token refresh logic; accepted
for the cross-platform benefit.

Five lines. Date, decision, why, what you rejected, what it costs. That’s it.

2. Session notes — short-lived, one per work session

Lives in docs/sessions/YYYY-MM-DD-topic.md. Written at the end of meaningful sessions — not every chat, only the ones where real work happened.

Template:

# YYYY-MM-DD — Topic

## Done
- What got completed
- Tests passing / not passing

## In progress
- What's half-done and where it stopped

## Open questions
- Things to resolve before continuing
- Assumptions made that need confirming

## Next session
- The first thing to do when you come back
- Where the plan picks up

When you return next week, you read this file and you’re back in flow in 60 seconds.

How to get it done — practical workflow

Have Claude write them for you

You don’t write these by hand. Claude does. Two prompts that work reliably:

At the end of a session:

“Write a session note to docs/sessions/2026-05-15-login.md covering what we did, what’s in progress, open questions, and what to do next session.”

After any non-obvious choice:

“Add an entry to docs/features/login/decisions.md documenting why we chose JWT over session cookies. Keep it to ~5 lines: context, decision, alternatives, trade-offs.”

Claude is genuinely good at these — it has the full session context fresh. You just need to remember to ask before closing the session.

Make it automatic in CLAUDE.md

To avoid relying on memory, add this to your root CLAUDE.md:

## Notes and Decisions

- When a non-trivial choice is made (library, pattern, architectural
  trade-off), add an entry to `docs/features/<name>/decisions.md`
  without being asked.
- At the end of a working session where substantive work was done,
  offer to write a session note to `docs/sessions/YYYY-MM-DD-<topic>.md`.
- Session notes must include: what was done, what's in progress,
  open questions, suggested starting point for next session.
- Use the 5-line decision template: context, decision, alternatives,
  trade-offs. No essays.

Now Claude proactively offers to capture notes. You don’t have to remember.

Folder structure to set up once

docs/
├── features/
│   ├── login/
│   │   ├── spec.md             ← from Step 2
│   │   ├── design.md           ← optional, implementation plan
│   │   └── decisions.md        ← Step 4: feature-level decisions
│   └── payments/
│       ├── spec.md
│       └── decisions.md
├── decisions/                  ← cross-cutting decisions (auth, infra, etc.)
│   └── 0001-use-jwt-auth.md
└── sessions/                   ← Step 4: per-session notes
    ├── 2026-05-15-login.md
    └── 2026-05-16-payments.md

The structure earns its value through consistency. Pick this once, document it in CLAUDE.md, never relitigate it.

Do’s and Don’ts

Do

• Keep entries short. A decision is 5 lines. A session note is half a page. If it’s getting long, you’re writing for the wrong audience.
• Write decisions when the choice is made, not later. Reasoning fades fast — even by the next morning.
• Commit notes to git in the same PR as the code they describe. This is the strongest possible link between what and why.
• Include alternatives you rejected. Often more valuable than what you chose — future-you will re-propose the rejected option otherwise.
• Date everything. ISO format: 2026-05-15. Sorts correctly, parses universally.
• Let Claude draft, you review. Claude writes faster and more completely; you edit for accuracy and brevity.
• Review old notes occasionally. Once a month, skim docs/decisions/ and prune anything that’s no longer true.

Don’t

• Don’t write a note for every trivial choice. If the decision is “used map instead of a for-loop,” skip it. Reserve notes for choices that have trade-offs or that someone might second-guess later.
• Don’t write essays. Long notes don’t get read — by you or by Claude. Brevity is the whole point.
• Don’t keep decisions in chat history alone. Chat sessions die. The note is the durable artifact. If it’s only in chat, it doesn’t exist.
• Don’t put session notes in CLAUDE.md directly. CLAUDE.md is curated context; sessions are journal. Mixing them bloats your context file fast.
• Don’t backfill weeks later. A note written today about a decision made three weeks ago is mostly fiction. Write it within 24 hours or skip it.
• Don’t duplicate the spec. Decisions explain choices, not requirements. If it belongs in the spec, put it there.
• Don’t worry about format perfection. Consistency beats elegance. Pick a template, stick with it, move on.

How Claude uses these later

When you start a new session and say “continue work on the login feature,” Claude (with the right CLAUDE.md instruction) will:

1. Read docs/features/login/spec.md for what you’re building
2. Read docs/features/login/decisions.md for why it looks the way it does
3. Read the most recent docs/sessions/*-login.md for where you left off
4. Resume from the “Next session” pointer

You go from cold start to full context in one prompt. That’s the payoff of this habit.

To make it explicit, add this to CLAUDE.md:

## Resuming work

When asked to continue or resume work on a feature, before doing
anything else:
1. Read `docs/features/<feature>/spec.md`
2. Read `docs/features/<feature>/decisions.md`
3. Read the most recent `docs/sessions/*-<feature>.md`
Then summarize where things stand and confirm before proceeding.

The compounding effect

After a few months, your docs/ folder becomes a living history of the project:

• docs/features/*/spec.md → what you set out to build
• docs/features/*/decisions.md → why it looks the way it does
• docs/sessions/*.md → the journey, including dead ends and lessons

You’ll notice Claude’s answers get better over time on the same project — there’s more genuine history to draw on. New teammates can onboard by reading the docs folder. Your future self thanks you every time you come back.

This is the unglamorous step. It doesn’t feel as productive as writing code. But it’s the difference between a project that stays coherent for a year and one that turns into archaeology after three months.

Quick start checklist

1. Create the folder structure: mkdir -p docs/features docs/sessions docs/decisions
2. Add the Notes and Decisions section to your root CLAUDE.md
3. Add the Resuming work section to your root CLAUDE.md
4. After the next non-obvious decision: ask Claude to write the decision note
5. At the end of the next real session: ask Claude to write the session note
6. After two weeks, skim what’s accumulated — refine the templates if needed

The full rhythm so far

1. CLAUDE.md — persistent project context
2. spec.md — what to build
3. Plan → Code — how to build it, with review
4. Decisions + session notes — preserve why and what was learned

Step 5 (codebase knowledge graphs) and Step 6 (automated AI memory tools) build on top of this foundation. But this is the habit that makes everything else worth doing — without notes, the rest is just code with no story.