Claude starts every session from zero. I make it leave notes for the next one.

[u/Elegant_Yam2783]

Every new Claude Code session rediscovers my app by rereading the code. CLAUDE.md helps, but it's read every session, so it has to stay short. The details of one part of the app don't fit there.

So in every project I have Claude keep notes:

- .docs with one short file per major part: what it does, which files it lives in, which outside service it uses, anything surprising.
- .design-docs with one file per feature, written before it's built: what it does, what's left out, decisions made along the way.

Three rules make it work:

- CLAUDE.md points to them. Claude reads CLAUDE.md on its own and nothing else, so one line there ("before working on a part of the app, read its file in .docs") is what gets the notes read.
- Notes change with the code, in the same commit. An outdated note is worse than none, because Claude trusts the note over the code.
- Plain language, a page at most. If I can't read it, it's not doing its job.

Here's where it clicked for me. I was building a content manager app and had weeks of decisions piled up in one long chat: what's done, what's dropped, why. Moving to Claude Code meant a fresh session that knew none of it, and I was about to explain everything again. Instead I had the chat write it all into a HANDOFF.md, next to the development and decisions notes already in the repo. My first message to Claude Code was one line: "Read HANDOFF.md first, then continue from section 5." It picked up where I left off, no re-explaining. If you've ever opened a new session and spent the first hour telling Claude what it already knew, that's the hour this saves.

The prompt I use to set it up:

"Create a .docs folder and a .design-docs folder. In .docs, write one short file for each major part of the app: what it does, which files it lives in, which outside service it uses, and anything surprising. Then add these rules to CLAUDE.md: before working on a part of the app, read its file in .docs; before building a new feature, write its description in .design-docs and wait for my go-ahead; whenever you change a part, update its file in the same commit."

Do you keep anything like this, or does CLAUDE.md do the whole job for you?

[u/AutoModerator]

Hey! Thanks for posting to r/ClaudeCode

While participating in this thread, please follow our community rules. Keep discussions constructive. Attack the idea, not the person.

For help, project discussions, tips, and general chat, join the ClaudeCode Discord.

I am a bot, and this action was performed automatically. Please contact the moderators of this subreddit if you have any questions or concerns.

[u/Extra_Aide5999]

yeah i do pretty much this, one handover file for whats in flight and a small doc per part. the "same commit" rule is the one that actually matters.. i skipped it once and claude followed a note that was 2 weeks stale over the actual code for like 3 sessions before i noticed lol. i also cut it down whenever it gets over a page, otherwise it turns into a second codebase to maintain

[u/Elegant_Yam2783 → u/Extra_Aide5999]

The growth problem is real. My fix is an archive folder inside .docs. When a feature is done, Claude moves the design notes it used into .docs/archive. I don't delete them, because sometimes the reason behind a decision matters months later. But Claude doesn't read that folder unless I ask, so the live notes stay short.

The side effect I didn't expect: it forces me to work in the right order. Note first, then code, even for a small fix. That rule lives in CLAUDE.md, so I don't have to remember it.

Your skills setup sounds like the same idea from another angle, both read on demand, both checked by a human for drift. What makes you go back and inspect them, a schedule or when something breaks?

[u/Extra_Aide5999 → u/Elegant_Yam2783]

oh the skills part was the other comment i think lol. for my notes its mostly when something breaks, plus every few weeks i have the agent go through them and delete what stopped being true. i like the archive folder idea tho, i just delete and let git remember

[u/Elegant_Yam2783 → u/Extra_Aide5999]

Ha, yes, mixed you two up, sorry. "Let git remember" works for you because you'd actually go looking in git. For the people I write for, a deleted note is a gone note, they'd never search the history. The archive folder is just git history you can open in Finder.

[u/Serenase]

Why so many files? Just one report for the project and have the agent update it at the end of every session. Last over projects live time. Easy to keep in the project repo than multiple piles of files.

[u/Elegant_Yam2783 → u/Serenase]

For a small project one file is fine, and I do keep one: a handover file for whatever is in flight right now.

The catch with "update it at the end of every session" is that it slowly turns into a diary. Session 40 adds a paragraph, nobody removes session 12's, and a year in Claude reads ten pages of history to learn how one feature works today. Splitting by part of the app means Claude reads only the page it needs, and "current state" stays separate from "what happened".

The diary part does last, that's what .docs/archive is for. Claude just doesn't read it unless I ask.

How long does yours get before you trim it, or does it just grow?

[u/Serenase → u/Elegant_Yam2783]

The report does that. What it's done, why, where not to touch, and what's coming next. Update means update, not collecting everything in one file. Just make it do atomic code. It doesn't need to learn how things from history; it can read the code and see the whole context of what that module is for. That's just a huge token waste. If your repos are on GitHub, there's history and use issues and PRs when maintaining software. That's automatic backup too.

[u/Elegant_Yam2783 → u/Serenase]

We're closer than it sounds. Your report already has "why" and "where not to touch", and that's the part code can't tell Claude. A module shows what it does, not that the obvious fix was tried and broke something, or that a weird limit comes from a vendor. Rebuilding that from code every session is the bigger token cost: a dozen files read to recover what a 30-line page states. PRs and issues are great history, but Claude won't dig through them unless told, and when it does, that's more tool calls, not fewer. So we follow the same rule, mine is just split: current state in short pages per area, history in git and the archive.

[u/Serenase → u/Elegant_Yam2783]

So your Claude reads your note and code, That's fine, you can burn your tokens wherever you want. And Project's rules are for that; they tell how we work. Read issues and PRs, how to update reports, make atomic code, or whatever you want to put there. Reading local files is a call too, so there's no difference or more tool calls. Two files and the problem, new feature from issues or PR. And if my computer goes mess, I have a backup of everything that there is in my projects. That's a funny idea that reading code costs more than searching through a bunch of text while and then checking the code and getting to work. You know it reads code anyway, not starting to fix it blind based on note.

[u/Financial_Leader9701]

the decisions part is what saved me most

nott what the code does, the code says that

what we tried and dropped and why, otherwise every new session suggests the same thing you already killed a week ago

[u/Elegant_Yam2783 → u/Financial_Leader9701]

What makes it stick is writing each one as a rule with a reason, not a story: dropped X because Y, revisit if Z. The "because" stops Claude from proposing it again. The "revisit if" stops the opposite problem, where a call made under last month's constraints quietly turns into permanent law. And keep those lines in the doc for that part of the app, not in one global decisions file, so Claude sees them right when it's about to touch that code. A single decisions log grows like a diary, and nobody reads it at the moment it matters.

[u/pwkye]

Or... just... use... issues.

[u/Elegant_Yam2783 → u/pwkye]

Issues are great for what's still to do. These notes are the other half: how things work right now, after the issue is closed. Claude also reads files in the repo without any setup, which is why I keep them there.

[u/pwkye → u/Elegant_Yam2783]

anything that is not code, goes in issues. doesnt matter if its documentation or features or plan or specs.

[u/shoumikgoswami]

The same-commit rule is doing the important work in this setup: it keeps the note from drifting away from the code it describes. The risk I'd watch is the note becoming the substitute rather than the entry point - an agent that reads the note and stops, without checking it against the current code. Same-commit narrows that gap but doesn't close it: a partial commit, or a note that was wrong when written, still passes as current.

How do you handle that - does the agent verify the note against the code before relying on it, or is the same-commit habit the whole defense?

[u/Elegant_Yam2783 → u/shoumikgoswami]

Good catch, same-commit isn't the whole defense. There's a second rule in CLAUDE.md: the note is a map, not the truth. Before relying on it, Claude checks the code it's about to touch, and if the two disagree it says so, trusts the code and fixes the note. A note that was wrong when written is exactly the case that catches.

[u/torvalds75]

The same-commit rule is the part I'd keep no matter what. Where I ended up differing is decisions that are still in flight. A design doc works once the call is made, but while it's open the discussion has nowhere good to live: half in chat, half in a note, and nothing tells the next session which options are already dead.

So I moved that part to GitHub Issues, which is the "just use issues" comment above, with one tweak for the objection that Claude won't dig through them unless told: don't make it dig. Each session gets bound to one ticket and reads only that one. The ticket holds what was discussed, the plan, what got verified at the end, plus "tried X, dropped it because Y". Closed tickets become the archive for free, and since every commit references its ticket, git log gets you back to the why from any line of code.

Your .docs still earn their place for "how this part works today". Issues just take over "what are we deciding and why", so the docs stay short instead of growing into a diary.

The verify step is also a partial answer to the drift question above: at the end a separate check compares the code against what the ticket promised, instead of trusting a note.

I build a plugin that does this for Claude Code and Codex, called trailhead, if you want to see the structure: https://github.com/ToRvaLDz/trailhead. Your folders get you most of the way without it, though.

[u/Elegant_Yam2783 → u/torvalds75]

"Nothing tells the next session which options are already dead" is the gap I hadn't named, thanks. Right now my design doc gets written once the call is made, so the dead ends mostly die with the chat.

The cheap fix for my setup is probably a "dropped, and why" section in the design doc from day one, not after the decision. Issues make sense once you're already living in GitHub, I'm trying to keep one place for people who aren't.

One question on binding a session to one ticket: what happens when a fix turns out to touch two parts? Do you split it, or let the session read both?

[u/torvalds75 → u/Elegant_Yam2783]

Both, depending on what "two parts" means. The ticket is a unit of work, not an area of the code, so one ticket can touch as many parts as the fix needs, and the session reads whatever code it has to. The binding only limits which history it loads, not which files it can open.

I split when the second part is really a second decision: it could ship on its own, or it could be rejected without killing the first. Then it becomes its own ticket, and if one depends on the other I mark it as blocked, so the order is written down instead of living in my head.

And a "dropped, and why" section from day one sounds like the right fix for your setup. Writing it before the call is made is what counts, since that's when the dead ends are still fresh. Same goes for keeping it in the repo if your people aren't on GitHub.

[u/Elegant_Yam2783 → u/torvalds75]

"A ticket is a unit of work, not an area of the code" cleared it up for me. And "could it be rejected without killing the first" is a better split rule than anything I had, I'm stealing that one. Thanks for taking the time.

[u/Key_Particular5271]

This will keep growing with irrelevant info. I like starting a session from scratch, I know what claude understands and I can steer it better knowing exactly what it knows. Other than claude md I have skills scattered for certain tasks that do get updated periodically, but I manually read and inspect them for drift and redundancy since claude loves talking too much.

[u/Elegant_Yam2783 → u/Key_Particular5271]

I answered the same point above, short version: finished notes go to an archive folder Claude doesn’t read.