{"id":3516,"date":"2026-05-15T02:42:59","date_gmt":"2026-05-15T02:42:59","guid":{"rendered":"https:\/\/aiopsschool.com\/blog\/?p=3516"},"modified":"2026-05-15T02:43:01","modified_gmt":"2026-05-15T02:43:01","slug":"capture-decisions-and-session-notes-in-claude","status":"publish","type":"post","link":"https:\/\/aiopsschool.com\/blog\/capture-decisions-and-session-notes-in-claude\/","title":{"rendered":"Capture Decisions and Session Notes in Claude"},"content":{"rendered":"\n

Preserving the “why” across sessions<\/h2>\n\n\n\n

What this step is<\/h2>\n\n\n\n

The fourth habit (after CLAUDE.md<\/code>, spec.md<\/code>, 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.<\/strong><\/p>\n\n\n\n

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

Why this matters<\/h2>\n\n\n\n

You’ll come back to this project in two weeks, two months, or two years. By then you will have forgotten:<\/p>\n\n\n\n

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

    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.<\/p>\n\n\n\n

    Code shows what<\/em>. Notes show why<\/em>.<\/strong> Claude can read the code perfectly fine \u2014 it cannot reconstruct your reasoning.<\/p>\n\n\n\n

    The two kinds of notes<\/h2>\n\n\n\n

    1. Decisions \u2014 long-lived, one per choice<\/h3>\n\n\n\n

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

    Template:<\/strong><\/p>\n\n\n\n

    ## YYYY-MM-DD \u2014 Short title of the decision\n\n**Context:** What problem or situation triggered this decision.\n**Decision:** What we chose to do.\n**Alternatives considered:** What we rejected, and why.\n**Trade-offs:** What this costs us, that we accept.\n<\/code><\/pre>\n\n\n\n
    Example:<\/strong><\/p>\n\n\n\n
    ## 2026-05-15 \u2014 Use JWT instead of session cookies for auth\n\n**Context:** Mobile app needs to share auth with web frontend.\n**Decision:** JWT with refresh tokens, 15-min access token lifetime.\n**Alternatives considered:** Session cookies (rejected: cross-domain pain),\nOAuth-only (rejected: overkill for our scale).\n**Trade-offs:** Slightly more complex token refresh logic; accepted\nfor the cross-platform benefit.\n<\/code><\/pre>\n\n\n\n
    Five lines. Date, decision, why, what you rejected, what it costs. That’s it.<\/p>\n\n\n\n
    2. Session notes \u2014 short-lived, one per work session<\/h3>\n\n\n\n
    Lives in docs\/sessions\/YYYY-MM-DD-topic.md<\/code>. Written at the end of meaningful sessions \u2014 not every chat, only the ones where real work happened.<\/p>\n\n\n\n
    Template:<\/strong><\/p>\n\n\n\n
    # YYYY-MM-DD \u2014 Topic\n\n## Done\n- What got completed\n- Tests passing \/ not passing\n\n## In progress\n- What's half-done and where it stopped\n\n## Open questions\n- Things to resolve before continuing\n- Assumptions made that need confirming\n\n## Next session\n- The first thing to do when you come back\n- Where the plan picks up\n<\/code><\/pre>\n\n\n\n
    When you return next week, you read this file and you’re back in flow in 60 seconds.<\/p>\n\n\n\n
    How to get it done \u2014 practical workflow<\/h2>\n\n\n\n
    Have Claude write them for you<\/h3>\n\n\n\n
    You don’t write these by hand. Claude does. Two prompts that work reliably:<\/p>\n\n\n\n
    At the end of a session:<\/strong><\/p>\n\n\n\n
    \n
    “Write a session note to docs\/sessions\/2026-05-15-login.md<\/code> covering what we did, what’s in progress, open questions, and what to do next session.”<\/em><\/p>\n<\/blockquote>\n\n\n\n
    After any non-obvious choice:<\/strong><\/p>\n\n\n\n
    \n
    “Add an entry to docs\/features\/login\/decisions.md<\/code> documenting why we chose JWT over session cookies. Keep it to ~5 lines: context, decision, alternatives, trade-offs.”<\/em><\/p>\n<\/blockquote>\n\n\n\n
    Claude is genuinely good at these \u2014 it has the full session context fresh. You just need to remember to ask<\/strong> before closing the session.<\/p>\n\n\n\n
    Make it automatic in CLAUDE.md<\/code><\/h3>\n\n\n\n
    To avoid relying on memory, add this to your root CLAUDE.md<\/code>:<\/p>\n\n\n\n
    ## Notes and Decisions\n\n- When a non-trivial choice is made (library, pattern, architectural\n  trade-off), add an entry to `docs\/features\/<name>\/decisions.md`\n  without being asked.\n- At the end of a working session where substantive work was done,\n  offer to write a session note to `docs\/sessions\/YYYY-MM-DD-<topic>.md`.\n- Session notes must include: what was done, what's in progress,\n  open questions, suggested starting point for next session.\n- Use the 5-line decision template: context, decision, alternatives,\n  trade-offs. No essays.\n<\/code><\/pre>\n\n\n\n
    Now Claude proactively offers<\/em> to capture notes. You don’t have to remember.<\/p>\n\n\n\n
    Folder structure to set up once<\/h3>\n\n\n\n
    docs\/\n\u251c\u2500\u2500 features\/\n\u2502   \u251c\u2500\u2500 login\/\n\u2502   \u2502   \u251c\u2500\u2500 spec.md             \u2190 from Step 2\n\u2502   \u2502   \u251c\u2500\u2500 design.md           \u2190 optional, implementation plan\n\u2502   \u2502   \u2514\u2500\u2500 decisions.md        \u2190 Step 4: feature-level decisions\n\u2502   \u2514\u2500\u2500 payments\/\n\u2502       \u251c\u2500\u2500 spec.md\n\u2502       \u2514\u2500\u2500 decisions.md\n\u251c\u2500\u2500 decisions\/                  \u2190 cross-cutting decisions (auth, infra, etc.)\n\u2502   \u2514\u2500\u2500 0001-use-jwt-auth.md\n\u2514\u2500\u2500 sessions\/                   \u2190 Step 4: per-session notes\n    \u251c\u2500\u2500 2026-05-15-login.md\n    \u2514\u2500\u2500 2026-05-16-payments.md\n<\/code><\/pre>\n\n\n\n
    The structure earns its value through consistency. Pick this once, document it in CLAUDE.md<\/code>, never relitigate it.<\/p>\n\n\n\n
    Do’s and Don’ts<\/h2>\n\n\n\n
    Do<\/h3>\n\n\n\n
      \n
    • Keep entries short.<\/strong> A decision is 5 lines. A session note is half a page. If it’s getting long, you’re writing for the wrong audience.<\/li>\n\n\n\n
    • Write decisions when the choice is made<\/strong>, not later. Reasoning fades fast \u2014 even by the next morning.<\/li>\n\n\n\n
    • Commit notes to git in the same PR as the code they describe.<\/strong> This is the strongest possible link between what<\/em> and why<\/em>.<\/li>\n\n\n\n
    • Include alternatives you rejected.<\/strong> Often more valuable than what you chose \u2014 future-you will re-propose the rejected option otherwise.<\/li>\n\n\n\n
    • Date everything.<\/strong> ISO format: 2026-05-15<\/code>. Sorts correctly, parses universally.<\/li>\n\n\n\n
    • Let Claude draft, you review.<\/strong> Claude writes faster and more completely; you edit for accuracy and brevity.<\/li>\n\n\n\n
    • Review old notes occasionally.<\/strong> Once a month, skim docs\/decisions\/<\/code> and prune anything that’s no longer true.<\/li>\n<\/ul>\n\n\n\n
      Don’t<\/h3>\n\n\n\n
        \n
      • Don’t write a note for every trivial choice.<\/strong> If the decision is “used map<\/code> instead of a for-loop,”<\/em> skip it. Reserve notes for choices that have trade-offs or that someone might second-guess later.<\/li>\n\n\n\n
      • Don’t write essays.<\/strong> Long notes don’t get read \u2014 by you or by Claude. Brevity is the whole point.<\/li>\n\n\n\n
      • Don’t keep decisions in chat history alone.<\/strong> Chat sessions die. The note is the durable artifact. If it’s only in chat, it doesn’t exist.<\/li>\n\n\n\n
      • Don’t put session notes in CLAUDE.md<\/code> directly.<\/strong> CLAUDE.md<\/code> is curated context; sessions are journal. Mixing them bloats your context file fast.<\/li>\n\n\n\n
      • Don’t backfill weeks later.<\/strong> A note written today about a decision made three weeks ago is mostly fiction. Write it within 24 hours or skip it.<\/li>\n\n\n\n
      • Don’t duplicate the spec.<\/strong> Decisions explain choices<\/em>, not requirements<\/em>. If it belongs in the spec, put it there.<\/li>\n\n\n\n
      • Don’t worry about format perfection.<\/strong> Consistency beats elegance. Pick a template, stick with it, move on.<\/li>\n<\/ul>\n\n\n\n
        How Claude uses these later<\/h2>\n\n\n\n
        When you start a new session and say “continue work on the login feature,”<\/em> Claude (with the right CLAUDE.md<\/code> instruction) will:<\/p>\n\n\n\n
          \n
        1. Read docs\/features\/login\/spec.md<\/code> for what you’re building<\/li>\n\n\n\n
        2. Read docs\/features\/login\/decisions.md<\/code> for why it looks the way it does<\/li>\n\n\n\n
        3. Read the most recent docs\/sessions\/*-login.md<\/code> for where you left off<\/li>\n\n\n\n
        4. Resume from the “Next session” pointer<\/li>\n<\/ol>\n\n\n\n
          You go from cold start to full context in one prompt. That’s<\/strong> the payoff of this habit.<\/p>\n\n\n\n
          To make it explicit, add this to CLAUDE.md<\/code>:<\/p>\n\n\n\n
          ## Resuming work\n\nWhen asked to continue or resume work on a feature, before doing\nanything else:\n1. Read `docs\/features\/<feature>\/spec.md`\n2. Read `docs\/features\/<feature>\/decisions.md`\n3. Read the most recent `docs\/sessions\/*-<feature>.md`\nThen summarize where things stand and confirm before proceeding.\n<\/code><\/pre>\n\n\n\n
          The compounding effect<\/h2>\n\n\n\n
          After a few months, your docs\/<\/code> folder becomes a living history of the project<\/strong>:<\/p>\n\n\n\n
            \n
          • docs\/features\/*\/spec.md<\/code> \u2192 what you set out to build<\/li>\n\n\n\n
          • docs\/features\/*\/decisions.md<\/code> \u2192 why it looks the way it does<\/li>\n\n\n\n
          • docs\/sessions\/*.md<\/code> \u2192 the journey, including dead ends and lessons<\/li>\n<\/ul>\n\n\n\n
            You’ll notice Claude’s answers get better over time<\/em> on the same project \u2014 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.<\/p>\n\n\n\n
            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.<\/p>\n\n\n\n
            Quick start checklist<\/h2>\n\n\n\n
              \n
            1. Create the folder structure: mkdir -p docs\/features docs\/sessions docs\/decisions<\/code><\/li>\n\n\n\n
            2. Add the Notes and Decisions<\/strong> section to your root CLAUDE.md<\/code><\/li>\n\n\n\n
            3. Add the Resuming work<\/strong> section to your root CLAUDE.md<\/code><\/li>\n\n\n\n
            4. After the next non-obvious decision: ask Claude to write the decision note<\/li>\n\n\n\n
            5. At the end of the next real session: ask Claude to write the session note<\/li>\n\n\n\n
            6. After two weeks, skim what’s accumulated \u2014 refine the templates if needed<\/li>\n<\/ol>\n\n\n\n
              The full rhythm so far<\/h2>\n\n\n\n
                \n
              1. CLAUDE.md<\/code><\/strong> \u2014 persistent project context<\/li>\n\n\n\n
              2. spec.md<\/code><\/strong> \u2014 what to build<\/li>\n\n\n\n
              3. Plan \u2192 Code<\/strong> \u2014 how to build it, with review<\/li>\n\n\n\n
              4. Decisions + session notes<\/strong> \u2014 preserve why and what was learned<\/li>\n<\/ol>\n\n\n\n
                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 \u2014 without notes, the rest is just code with no story.<\/p>\n\n\n\n
                <\/p>\n","protected":false},"excerpt":{"rendered":"
                Preserving the “why” across sessions What this step is The fourth habit (after CLAUDE.md, spec.md, and the plan-first workflow) when […]<\/p>\n","protected":false},"author":4,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[1],"tags":[],"class_list":["post-3516","post","type-post","status-publish","format-standard","hentry","category-uncategorized"],"_links":{"self":[{"href":"https:\/\/aiopsschool.com\/blog\/wp-json\/wp\/v2\/posts\/3516","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/aiopsschool.com\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/aiopsschool.com\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/aiopsschool.com\/blog\/wp-json\/wp\/v2\/users\/4"}],"replies":[{"embeddable":true,"href":"https:\/\/aiopsschool.com\/blog\/wp-json\/wp\/v2\/comments?post=3516"}],"version-history":[{"count":1,"href":"https:\/\/aiopsschool.com\/blog\/wp-json\/wp\/v2\/posts\/3516\/revisions"}],"predecessor-version":[{"id":3517,"href":"https:\/\/aiopsschool.com\/blog\/wp-json\/wp\/v2\/posts\/3516\/revisions\/3517"}],"wp:attachment":[{"href":"https:\/\/aiopsschool.com\/blog\/wp-json\/wp\/v2\/media?parent=3516"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/aiopsschool.com\/blog\/wp-json\/wp\/v2\/categories?post=3516"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/aiopsschool.com\/blog\/wp-json\/wp\/v2\/tags?post=3516"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}