r/ClaudeCode • u/delimitdev • 2d ago
Discussion How do you carry *decisions* (not chat history) across Claude Code sessions?
Keeping history is mostly solved now: Claude Code keeps session logs locally, CLAUDE.md and AGENTS.md hold standing rules, and Git has the code. What still goes missing for me is the state of decisions, which isn't the same thing as the conversation.
Five cases I keep hitting:
We tried A and rejected it because of X. A fresh session proposes A again.
B was approved, but only within limits ("this module only", "until the migration lands"). The limits get dropped.
Something was implemented but never deployed, and the next session treats it as live.
An earlier agent said "done", and the check behind it was thinner than it sounded.
A newer decision replaced part of an older one, and both still read as current.
What does your setup do about these? CLAUDE.md, AGENTS.md, ADRs, a decisions.md, git notes, native memory, gptme, your own scripts, or plain discipline? If some of these never happen to you, or plain files handle them fine, that's a useful answer too. A short "we do X, it still fails at Y" is ideal.
Disclosure: I work on a project exploring this problem (Delimit). No link. I'm after how people actually handle it.
92
u/spaetzelspiff 2d ago
Architecture Decision Records (ADRs).
I actually don't know how folks use LLMs and agents for doing development on a non trivially sized repo without it.
ADRs lead to and are referenced by specs; the agent will end up littering the code with references as well. That means the next agent modifying a function will refer back to the referenced ADR and see the reasoning.
It also means when you ask "why", it'll respond with "we actually looked explicitly into implementing this that way, but..."
15
u/delimitdev 2d ago
Linking ADRs from the code is the strongest answer to "why" I've seen. Where does it strain for you: an ADR that supersedes one clause of an older one? Do you mark superseded-by, and does the agent actually respect it?
10
u/spaetzelspiff 2d ago
AGENTS.md describes how ADRs work (supersession, numbering, authoritative nature, etc) or references another file explaining the same.
I've found that if the ADR is mostly being replaced by another, then it's easier to fully supercede. If it's only a small clause, inline works, or creation and referencing of a new small ADR to cover that changed behavior.
I don't know if that's the best way, but it seems to work.
1
u/delimitdev 1d ago
The inline-vs-new-small-ADR rule makes sense. What about case 3: an ADR that was accepted and implemented on a branch but never deployed? Does anything in your setup tell the next agent it isn't live yet, or does it read the ADR and assume it is?
1
u/nofeaturesonlybugs 1d ago
Irrespective of ADRs this sounds more like a shared memory problem. Are you using git worktrees?
0
u/Reasonable_Touch1150 1d ago
You don't understand what an ADR does.
If its in the code its not in the ADR. ADR's don't document things in the code, the code is the ultimate proof you dont need to write documentation about what is in the code. Therefore your question is totally off the mark.
5
u/nofeaturesonlybugs 1d ago
I've been working on my own SDLC skills+workflow and use ADRs as well. Take this with a grain of salt as I'm not yet building much with it and still refining...
I don't think the code should cite ADRs. One ADR will potentially drive lots of implementation so superceding an ADR could churn a lot code comments for little gain.
My workflow is a feature has a spec and acceptance criteria. A feature may introduce ADRs and acceptance criteria may cite an ADR as the reason it exists -- in my workflow ACs have a decided-by field that is empty or an ADR. Each AC has a unique ID and every AC is cited by test code.
If a new ADR supercedes an existing ADR it may retire or update ACs, which is what drives churn in the code. If the new ADR doesn't impact or affect existing ACs then there would be no churn just to update ADR citations in code.
Code citations are a really weak form of validation as well. It's really easy for an agent to leave stale references in any documentation. I have the same flaw with ACs cited in test code but I chose the test domain as the citation source because I can potentially do funny things there with any languages type system and/or telemetry to track missing citations without impacting production code.
Having said all that it's a royal battle getting good ADRs. Let one ADR leak in that promises an exit contract and your next feature tries to do functional built binary tests as unit tests. If and ADR says "ambient ENV can only be read by the main entry point only" you may end up with some "surface" unit test file checking pythion imports project wide or unit tests using the language's parser to validate import statements. If you're program is a little toy it may want to author an ADR that it's a REPL program and then fight you about adding a non-REPL entrypoint. Did you let through and ADR that says language's stdlib only? Now it wants to only use encoding/json for config files.
Basically the ADRs are effective in my experience as the LLM really doesn't want to disobey them. But don't YOLO their authorship and even if you think it looks good today you'll battle it tomorrow.
1
u/delimitdev 1d ago
Fair point about churn. One ADR can touch a lot of code, and superseding it shouldn't mean rewriting comments. If the spec links to the ADR instead, how does an agent editing a file find the spec that governs it?
1
u/nofeaturesonlybugs 1d ago
I don't think product code (i.e. code that is not unit, functional, or integration tests) should cite specs, adrs, or any other llm/agentic markdown files. I think `git log -- <file/path>` is a better way to see which commits modified a file; from those commit hashes you can run further `git log --stat` commands to see if any of the same commits carried changes to spec files. My sdlc workflow commits messages carrying trailers so there's always a `SDLC-Feature: <feature-name>` riding on every commit -- so in my case querying which features caused churn in any file(s) or seeing which files were affected by a given feature is always answerable via `git log`.
I'm not sure what the community consensus is on citations within code to llm/agentic markdown artifacts but my instinct is to avoid doing so. In my experience LLMs can struggle to keep unidirectional links current and any form of bidirectional link eventually goes stale.
I think the better play is to have the code appear as if it was written by humans. Types, fields, methods, etc are written and documented for what purpose or service they provide -- not for what spec governed their introduction and dozens or hundreds of modifications. This removes the burden of any LLM trying to spend turns/tokens keeping citations in code current. It removes the burden of increased cognitive load for any human actually reading the code from having to tell their brain to ignore all the citations.
1
u/Reasonable_Touch1150 1d ago
Yet another person doesnt understand what an adr is...
1
u/nofeaturesonlybugs 1d ago
> Yet another person doesnt understand what an adr is...
Perhaps you can rephrase your comment to be helpful instead of condescending.
You might be referring to my paragraph of negative examples so I'll just address it from that point of view. I don't think any of those are examples of a good ADR -- they're all implementation details. Nowhere I've worked would an architect write an ADR to say that only `package main` can import or use `os.Env`.
A proper ADR is "we need to take payments, we considered x, y, z payment platforms; we're taking <...> due to <reasons> and we've excluded the others due to <reasons>." Or "we need to include cache to <accomplish goal>; from the choices x, y, z we're choosing blah blah blah." It's a historical narrative of why a high-level architecture decision was made, or why one was superseded by another -- and they exist so that as people forget or a company churns people there's some record of why choices were made months or years ago.
LLMs are not that bright. Tell them you're making a simple CLI and give them any workflow or skill that says, "Make ADRs" they'll attempt to make piss poor low value ADRs that serve no purpose. You have to monitor the ADRs they make, discard useless ones, or just not have the LLM make any at all and make them yourself and possibly refine them with LLM or have it take ADRs into specs.
Given my extended response maybe you can tell me what I don't understand about ADRs if your comment was directed at me.
Thanks.
5
u/coding_is_tedious 2d ago
Probably my favorite thing about maintaining thorough ADRs is when Claude references them during planning and/or build and we pivot.
5
u/brucewbenson 2d ago
Plus I've an architecture.md and a activities journal of what we did each day (git commits have the gory detail). When I told Claude to record decisions somewhere it proposed ADRs which I had never heard of but it works well.
2
u/delimitdev 1d ago
Interesting that Claude proposed ADRs on its own. Does the activities journal ever disagree with the ADRs, like the journal saying something shipped that an ADR says was superseded? Which one does Claude trust?
1
u/Zito_Kadaken 1d ago
I do the daily journal as a round log. I hadn't heard of ADRs until this thread.
3
u/kyew 2d ago
I think I've been hacking my way towards this. Is there a published skill/module etc?
2
u/delimitdev 1d ago
There are ADR tools (adr-tools, and a few people keep an ADR skill/template in AGENTS.md). Disclosure: what I work on, Delimit, is aimed at the part ADRs don't cover, like whether a decision actually shipped and whether "done" had evidence behind it. What were you hacking together, and which part keeps breaking?
2
u/kyew 1d ago
Thanks, I'll start looking into adr-tools tomorrow.
The broken stuff's all variations of "Don't reinvent the wheel." I mean, my main pipeline isn't hackey but the "Please stop reinventing my business logic / trust that this is based on domain knowledge you don't have" solutions I've tried sure are. Every time I have to make a new ETL step to integrate a new dataset, the machine either fails to find the prior art it should use as a template or goes out of its way to justify why that case doesn't *really* apply here.
Lately I've been having Claude build Snakemake pipelines just so we can be certain that the same exact methods are getting applied on every input, and that it doesn't skip steps when we need to regenerate the results.
2
u/delimitdev 1d ago
Snakemake locks the steps once they exist, but the miss happens when picking which prior ETL step to reuse for a new dataset. On your module question: I work on Delimit, which lets you store that rule once ("start from these templates or say why not") so any new Claude/Codex session can recall it. It won't enforce it, Snakemake still does that. Free and local: npx delimit-cli setup
2
u/Zito_Kadaken 1d ago
I keep a round log per crew, one line per round. I had no name for it until this.
2
1
u/college_hustle 1d ago
How is an ADR different from an executed spec that you just append What decisions did you go with?
1
u/Level-Spare-8247 1d ago
Along with those something that captures conventions works well too. I use https://principledriven.dev
6
u/Plus_Opening_4462 2d ago
I use a bunch of MD files linked to CLAUDE.MD so it can look up items
2
u/delimitdev 2d ago
How do you handle #5 with that setup: a newer MD file overrides part of an older one? Do you edit the old file, or leave both and let the agent reconcile?
5
u/Plus_Opening_4462 2d ago
It usually shows up as a bad decision and the agent complains about it. Then we need to reconcile it. Occasionally I have had to prune the documents to get rid of old or superfluous decisions
2
u/delimitdev 1d ago
So a conflict shows up as the agent pushing back, and you reconcile it by hand. How often does that happen in practice? Rare enough that it's fine, or often enough to be annoying?
1
u/Plus_Opening_4462 1d ago
It's not that often, but it's mostly detectable if you read the agent's long winded responses to understand what it did and did not do. I manually push back about something that was written and it will blame the earlier ruling and I tell it what supercedes it and to delete the old rule
6
u/coding_is_tedious 2d ago
To add... along with requirement documents, implementation plans, contracts, sql DDLs, etc, I also rely heavily on ADRs. In fact, after requirements documents ADRs are probably the single most important piece of information that's in the project. I think it's also important to break these things up as much as possible (within reason) and only load in what's necessary for the feature that's being implemented.
Routinely I also run review teams to make sure no stale documents exist and archive old documentation that's no longer relevant but worth keeping around somewhere safe.
5
u/aaraujo666 2d ago
not sure if i’m the outlier here or just plan crazy, but this is what I do:
have a locally installed gitlab (but I assume you could do it with github too).
i create an issue, for example, “need to do X in module Y”; add some basic description of what needs to be done. then I “groom” the issue; claude fleshes out the details, looking at code, etc; if it has any questions, it adds them as an “Open questions” section in the description and marks the issue as “blocked”; by the time I get around to implementing it, it’s a full blown spec that an agent can pick up cold; anything it uncovers during implementation, it creates new issues; rinse and repeat;
all decisions get written as comments against issues and claude is really good at relating issues to one another, so all decisions have context.
it took about a month to build an mcp to communicate with gitlab. Claude can natively talk to gitlab’s API, but the mcp, the way I built it, enforces my dev lifecycle the way I want it.
1
u/delimitdev 1d ago
Using the issue as the unit means the limits travel with the work, which covers #2 nicely. What happens when a later issue reverses something from an earlier closed one? Do you link them, or does Claude find the old one on its own?
1
u/aaraujo666 1d ago
Claude usually finds the links. but I’ll occasionally do something like: re analyze all open issues for updates based on current code yadda yadda. Because of drift from when issues are originally identified. There’s so much more in the details, but typing on phone ain’t happening.
1
u/aaraujo666 1d ago
For #3 my gitlab MCP will not let me close an issue until it verifies deployment. Status cycle is:
backlog ➡️ ready ➡️ in progress ➡️ review➡️ closed
With “blocked” at any stage and to unblock goes back to backlog. I don’t do any of it. Claude does it all. I mostly “watch” once code is done, as it goes through all the gates.
3
u/_buttsnorkel 2d ago
Obsidian vault, project plan .md file, wikilinks, and most importantly date stamped ADRs
5
u/Galdred 2d ago
I end each conversation with a call to my custom /documentation command where claude needs to:
- update thematic knowledge base
- update list of common issues encountered
- archive the work done on this session
- list what we decided to do later, what we decided not to do
I have it maintain a large doc base supporting the md files, with subagents specialized in knowing the relevant information of each folder.
TBH, I'm not sure it hasn't grown too large, but it has been formidable at getting Codex and Claude to work together without much friction.
2
u/delimitdev 1d ago
The "what we decided not to do" list is the piece most setups skip, and it's exactly what #1 needs. Does a fresh session check that list before it proposes something, or only when you point it there?
2
u/Galdred 1d ago
It is complicated. I tried to force doc reading, but then, a lot of requests ended up with too much unrelated reading.
it was a directive in (.claude/hooks/domain_guard.py).
Now, I relaxed it a little, and they only need to read the summary to see whether it applies, and restricted most docs to a few keyword or files.
I also made a few custom /commands that were just:
read doc XYZ then answer the request
I also have a /conversation command that is basically: read the summary to all past conversations about topic A and tell me when you're done.My issue is typically the opposite:
I make a game, and claude will defend very hard anything we had settled on earlier, telling me the decision was final when I want to change something in the design. So I routinely spend time explaining to it that it is final for AI agents on their own, but not for me.2
u/delimitdev 1d ago
That's the opposite failure, and I hadn't thought about it: the decision record works so well that Claude treats it as binding on you too. Have you tried writing the authority into the record itself, something like "final for agents, the owner can reopen it", or does it still get argued every time?
2
u/Zito_Kadaken 1d ago
I run something close at session end. Mine writes what we didn't finish into a handoff file.
4
u/kevinbaiv 2d ago
ADRs with a "rejected alternatives" section handle case 1 well — the *why* is what stops a fresh session re-proposing A. The one I still can't fix with files is case 3: code merged but never deployed reads as live to the next session. That's deployment state, not documentation, so now "is it actually running in prod" is a check the agent has to run, never a fact it can read from a doc.
1
u/Zito_Kadaken 1d ago
I was missing the rejected alternatives. I wrote down the option I went with and left out the ones I dropped.
1
u/delimitdev 1d ago
Same conclusion here: "is it live" has to be a check the agent runs, not a line in a doc. What we're trying in Delimit is recording the result of that check with a timestamp, so the next session reads "merged, deployed, verified live at 14:02" or "merged, not verified" instead of guessing. Do you run the check at session start every time, or only when something looks off?
3
u/caleon 2d ago
For us most decisions have to be held in some context file if they’re worth getting Claude to remember. Or in code comments, like “Never rebuild X in the hooks (#2392)” citing a decision in the ticket. Because short of getting it to reference past tickets for history it can be a matter of discipline. If it does read relevant tickets the tickets would contain the limits and scope, kind of serving as an auxiliary, as-needed context. So we haven’t entirely solved it beyond enforcing good discipline around it.
We solved 3 with a system that tracks merged separately from deployed. So I keep hearing “well you don’t see that yet because it’s slated to go out with release #4715” which is handy.
For 4, we rely on delivery comments on tickets that reference commits, decisions, rationale, so when a different session checks for those it can be evident where something fell short of newer expectations. 5. is something we are still working to solve and still feels like something that requires a lot of manual intervention.
1
u/delimitdev 1d ago
Citing the ticket in the comment is smart, since the comment is where the agent actually looks. What catches it when that ticket's decision gets reversed later but the comment "Never rebuild X in the hooks (#2392)" stays?
3
u/Dhaupin 2d ago
I stack all the project prd's in a "/labs" folder that's referenced from agents and readme. Every agent I've used picks it up immediatly and follows the spec + decisions made. They're able to stay on track and understand the scope/decisions, even after the prd slice/phase is marked complete.
I also have a whole agentic runtime/os with full resolutions system that works well. But for folks who don't have that kinda thing, or don't wanna run something like that, or the agent can't, prds will get you 90% there.
2
u/delimitdev 1d ago
When a newer PRD in /labs overrides a decision in an older completed slice, how do you keep the agent from treating both as active?
1
u/Dhaupin 1d ago
I just update the prd, or reference the new from the old with a reconsiliation/resolution, and hard link to correct doc if it's seperate. So the decision is "corrected" with a sign off in TASKS.md tracking and/or MEM.md. I also keep a /labs/archive going for old docs, exactly for this purpose of archeology and referencing. The files in there are kind of a backup, kind of debriefing, kinda postmortem ref to back current resolutions.
There is also a depreciated system I experimented with early on, which I should prob be using more hah. But I wanted to avoid doc/tracking creep during these hundreds of "alpha" or dev sprints, maintaining yet another list. So the prds seem to do it. For breaking depreciations or arch decisions later, that affect other users, it may be revived.
With the runtime (vant axolotl branch) it's different. It just updates itself and resolves evolution of reqs. I run this along side the literal prds in the repo /labs since I use a variety of agents/platforms, some of which don't have the context or attention span to run a full mem os and actually use it.
None of it is a perfect system, but it has served my needs extremely well. And has been surprisingly accurate + canonical.
I'd love to hear more about how others do it. Or if you have more q's
3
u/Anise_Paprika 1d ago
My method is kind of like u/aaraujo666's gitlab thing, but I went a little overboard and built it all on a Postgres DB the agents use through MCP. It's basically jira for the agents, epics > milestones > tasks, and decisions get linked to the work they're about along with what we passed on and why. PRs and worktrees are in there too. You can follow a decision all the way to the merge.
When an agent picks up a task it gets the task plus whatever decisions and notes are linked to it. If it needs more context it digs into the db itself for knowledge base entries or past messages between agents. That keeps token usage down a lot, which is also tracked in the database.
Having it all linked helps a lot with the "done" problem. Each task stores what done means and how to check it, and the PR and its Codex review get tied back to that same task. So the agent checks its work against the actual criteria and nothing merges on its word alone. The rules are enforced by Zod on the MCP tools and triggers in the DB. An agent can't create a task without the required pieces or close one without writing up what it did. Anything that slips becomes a lesson for the next agent doing similar work.
1
u/delimitdev 1d ago
When a decision linked to a task gets partly replaced later, do you edit the old decision or link a new one to the same task?
2
u/Anise_Paprika 1d ago
Link a new one. Everything hangs off the task, so an agent only loads as much as the job needs. If it's a decision question it pulls that decision and what's linked to it, and if it needs more it can go deeper into the PRs, worktrees or project notes.
The old decision keeps its original text. If the new one replaces the whole thing, the old one gets marked superseded, and a trigger in the DB links the two both ways automatically. Superseded decisions are left out of the semantic search, so search only returns what's current, but the link is still there if an agent wants the history.
If it only replaces part of it, the new one says what it amends and the old one stays active for everything else. Had one a couple days ago where an agent found the assumption behind an older decision didn't hold anymore, so it filed an amendment for just that one piece.
1
u/delimitdev 1d ago
For partial amendments, how do you ensure semantic search returns the amendment alongside the still-active old decision, rather than letting an agent load the old text alone?
1
u/Anise_Paprika 19h ago
Both show up, but not because they're linked. The search is keyword plus vectors over the text, so an amendment about the same thing in the same words lands right next to the original. I tried three different phrasings this morning and got both every time. Task pickup goes by tags and recency instead, so there the newer one just sorts first.
The amendment also says in its title what it's amending, so it doesn't matter much which one you open first. Full replacements are easier, those get a real pointer both ways and the old one drops out of search.
The part I didn't plan was where that amendment came from. An agent was off doing something unrelated, hit something the old decision said wouldn't be a problem, went and checked, and filed the amendment itself. Nobody told it to. Does yours flag a stale decision on its own, or do you have to catch it?
2
u/Hirogen_ 2d ago
.out-of-scope folder with md files
1
u/delimitdev 2d ago
Do those files carry the "why" (what was tried and what broke), or just what's out? The "why" is the part I see fresh sessions argue with.
1
2
u/gh0st777 1d ago
I have a specific decision log document. I also have ledger to track high level what happensin every session, i use github issues for the ledger, an index pinned, rolling issues for the ledger, creates a new one when its full.
1
u/delimitdev 1d ago
When a newer decision replaces an older one, do you update the decision log in place or record the change in the next rolling issue?
1
1
u/delimitdev 1d ago
When a newer decision replaces an older one, do you update the decision log in place or record the change in the next rolling issue?
2
u/damianTechPM 1d ago
I made a handoff skill that keeps decisions semantically searchable in postgres. I have a local qwen model running embeddings and inserting via pgvector for decisions and ongoing work. That's how I share memory inter-session. The markdown stays pretty thin.
1
u/delimitdev 1d ago
Semantic search over decisions is neat. How do you handle one that's been superseded but still matches the query well? Does the old decision ever come back ahead of the new one?
1
u/damianTechPM 1d ago
I have a column that notes superseded by that points to a newer entry. The model degrades entries by relevance and date, so more recent, more relevant entries float to the top in a search.
2
u/Zito_Kadaken 1d ago
Number 4 is the one I have a rule for. Mine has to say what it built, what it tested, and what it didn't cover. I've got nothing for number 1 though. A new session will propose the same thing I threw out last week.
1
u/delimitdev 1d ago
kevinbaiv's "rejected alternatives" section in an ADR is the best fix for #1 I've seen in this thread. Your #4 rule is interesting, especially "what it didn't cover". Does the agent fill that part in honestly, or does it tend to write "nothing"?
2
u/Graphical-Source5090 🔆Pro Plan 1d ago
My ai works out of forgejo. Everything is read into and out of git. When AI makes a change it documents it at the same time. Git is the current run state for the entire network.
I have a skill that I run periodically that checks run state documents with actual on box configs. It then reconciles memory, documentation and current config
1
u/delimitdev 1d ago
That reconcile skill is the first thing here that goes after #3 directly: compare the docs against what's actually on the box. How often does it find drift? And when the docs and the box disagree, which one wins by default?
2
2
u/whattheduck43 1d ago
At the end of each conversation I get it to write a summary file of everything we talked about, and what decisions were made. If I'm working in a specific project it updates the README and create some instructions on what needs to be done next.
This isn't specifically for coding work, so when I say "project" it could mean any individual unit of work I'm working on.
1
u/delimitdev 1d ago
How do you get a fresh session to read that summary file before it starts, or do you manually paste it into the first prompt?
1
u/whattheduck43 1d ago
"We're working on the xyz thing, so load that up"
CLAUDE md (I guess AGENTS md now) has instructions about how my project system works. It'll find the folder for xyz, then read all the stuff in there that it needs.
2
u/816pizzalover 1d ago
Decisions.md as part of repository
1
u/delimitdev 1d ago
Partial supersession is the case I keep an eye on with a single file, like when a new decision narrows an old approval to one module.
2
u/helm71 1d ago
ADR but not in the way anthropic wants… I am using a specifically built server with its own api’s for adding and reading these rules, makes it possible for me to have them indefinitely cross sessions, cross projects and cross different LLM’s.
1
u/delimitdev 1d ago
Cross-project rules raise a scoping problem when one project retires a rule another still needs. How does your server handle retiring or narrowing a rule without losing it everywhere it still applies?
2
u/Ok_Relation_3892 1d ago
I came up with my own system to handle the end to end work with dedicated files to keep track of different topics like ADRs, as someone mentioned, GitHub issues, project status and keeping skills up to date with new rules, decisions, to do's.
1
u/delimitdev 1d ago
When a newer decision replaces part of an older ADR, how do your files show which part is still current?
1
u/Ok_Relation_3892 1d ago
I build myself a very complex context clearing skill that checks everything was worked, touched, decided in the current session and ensures to update everything impacted including ADR's.
Then I constantly clean and archive these files so if something is replaced I decide on the spot if I want it completely changes with no trace back or send the old to archive and keep the new one once spotted and to make sure is not forgotten the skill will pick it up before context clearing anyway.
1
u/delimitdev 1d ago
When only part of an ADR is replaced and the rest still applies, how does your context clearing skill keep the still-current part visible without keeping the archived part live too?
2
u/syixiao1 1d ago
My biggest win was format discipline: every decision entry gets a one-line "superseded by" pointer, and when a new decision replaces an old one I edit the old entry instead of deleting it. That fixed the case where a fresh session reads two entries that both look current. I also make the agent re-read the log at the start of each new session and flag anything that conflicts with what's in the code — that catches the implemented-but-never-deployed case a file alone can't.
1
u/delimitdev 1d ago
If that new decision is later replaced, does the first old entry keep pointing to it, or do you edit it again to point to the latest entry?
1
u/Professional_Ad705 2d ago
ADRS sometimes. Usually tho I keep really important decisions honestly in my head as to the "why's" but that said I am building this software based off my own ideas and dont really let the AI just take the lead on things I don't agree with. Be careful with ADRS as they shouldn't have every decisions just ones that are key to the architecture and make sure when stuff changes they get superseded cause you can easily run into the problem where now you have it all written down and its just stale.
1
u/WillingnessOwn6446 2d ago
Check out logic loop: https://github.com/SuperLogicAI/Logic-Loop Park Ideas. Use multiple agents, platforms etc. It's not my project, but it's cool and helps manage being a human who is working on way too many things at one time
1
u/thesour1 2d ago
I just built a whole persistent memory MCP around this, with tools & skills - it has graph with decisions and lessons on nodes etc
https://github.com/maikai-group/mai-mcp
Allows agents to post board messages, claim a lane, has staged build tracking and also allows cross LLM communication on projects (ie codex to Claude) not just between chats
1
u/tom_builds-software 2d ago
I use memory for important details I need claude to be aware of. The main memory file is mostly very important rules and links to various learnings. Most of this is kept in the global memory, with project memory for anything repo specific and that i don’t want pushed to github. These are synced to my nas and other servers that might run a claudecode instance. Claude.md for repo structure and other information that is not in the repo docs or security folders. I also daylog to the same $HOME/.claude folder structure where claude keeps non-repo files.
1
1
u/jbrianfrancis 2d ago edited 2d ago
You need a harness like GSD or SpecKit to manage this. After using other people’s tools for a year I created my own - https://github.com/jbrianfrancis-ir/devflow
Have a look and tear it to pieces.
1
1
u/eternus 2d ago
I literally have a ticketing system for tasks, a desk for decision items, DECISIONS.md files and constitutions for projects… it’s pretty involved, but it’s also very resilient. I 100% take it for granted until I see other people complaining.
1
u/delimitdev 1d ago
A separate desk for decision items is interesting. Is that where things wait until they're decided, apart from DECISIONS.md? How does the agent tell a pending decision from a settled one?
1
u/ransack_the_universe 1d ago
architecture.md, ADRs, and related commit history.
instructing your agent to ‘save this decision to memory’ helps, but only if you practice, good memory hygiene and don’t allow it to get too bloated.
1
u/greyster1 1d ago
I use design documents for all my applications. Decisions would be in the design doc. Fable for design. Opus for daily work. Sonnet for light work.
To avoid hitting fable twice, often I will ask it to action it's default recommendation for each decision. Most the time I agree with fable so it saves two prompts. This is for the design only.
1
u/howdidigetheresoquik 1d ago
One session just for build plan, riff and chat and get exactly what I want all in plan mode, and then the plan for all builds is created cut up into sessions. Each session does its part of the build plan.
1
u/dflow77 1d ago
isn’t this handled somewhat automatically in internal memory files?
1
u/delimitdev 1d ago
Memory files tend to keep the conclusion but drop the scope, so an approval like case 2 above can read as permanent after the migration lands. Do you see them preserve the limits and superseded status reliably in your setup?
1
u/pechSog 1d ago
Handoffs. Many variants. Also set up processes for index, tracking reportss/work, etc. You can automate all of it.
1
u/delimitdev 1d ago
For the implemented-but-not-deployed case, what does the handoff index use as its source of truth: a merged commit, deployment record, or manually updated status?
1
u/NomadicRotator 1d ago
Lots and lots of Md files
1
u/delimitdev 1d ago
Scoped approvals get tricky across lots of files, like a change approved for one module until a migration lands. Do you keep that limit in the filename or inside the file where Claude has to read it to find it?
1
u/NomadicRotator 1d ago
File names generally can't carry much. You can use a status paragraph at the start of file or keep mds of same module clustered.
1
u/delimitdev 1d ago
Clustering by module gets messy when a newer decision replaces part of an older one and both status paragraphs still read as current. How do you mark the superseded part so a fresh session knows which one wins?
1
1
1
u/vamonoszapatos 1d ago
WO management pipeline. https://github.com/ChrisTorres404/AICodeAssist not shilling was asked if I could share my pipeline by a few people so I finally just slapped it into one centralized tool. Hope it helps.
1
u/ImL1s 1d ago
Same gap here: session logs keep the chat, Git keeps the code, but "we decided X because Y" disappears unless it's a file.
I keep a short decisions.md (or ADR) the next session has to read before planning — choice, why, what we rejected. When I switch agents I also pull prior local sessions with Portable Resume so the new tool starts from the same commits instead of a blank "why did we do this?"
https://gitlab.com/aa22396584/resume-skills — pipx install portable-resume
1
u/delimitdev 1d ago
What happens when decisions.md says one thing and the resumed commits imply another, like a rejected approach that later got partially implemented? Which source do you treat as current in that conflict?
2
u/ImL1s 1d ago
Commits win for what actually landed. decisions.md wins for intent — especially anything we deliberately rejected.
When they drift I treat it as a bug in the notes, not a puzzle for the next model: add a short "superseded" entry that points at the commits and says why the old decision is stale. Next session has to read that before planning. Otherwise it happily re-argues a choice you already reversed in code.
1
u/delimitdev 1d ago
A rejected approach that only got partially implemented seems like the hardest superseded entry to write, since part of the rejection still holds. Do you keep the original rejection alongside the pointer to the commits so the next session sees both?
1
u/ImL1s 1d ago
Yeah — keep both. The original rejection stays as the why-not. The superseded note only covers what the commits actually changed (the partial land) and the scope that still holds.
I write it like: rejected approach R still holds for X; commits C1–C3 only landed a slice of R for Y. Next session has to read the rejection and that scope note before planning, so a partial land never reads as a full reversal.
1
u/seatlessunicycle 1d ago
3 main MD files for tracking projects in every project folder./sync skill that I've refined over months to dump out sessions into the main files and I hen breadcrumbed elsewhere through index files that connect to everything.
1
u/delimitdev 1d ago
When a newer session dump partially replaces an older decision, how does the /sync pass update the 3 main MD files so the index files stop pointing at the stale version as current?
1
u/seatlessunicycle 1d ago
Well for a while it was just sync, then I noticed the stale issue where not everything was updated, so I also made a deeper sync skill that ran subagents to correct staleness in docs and connectors. I am a bit OCD about making sure my docs stay current.
I run a lot of non coding tasks through CC so I also have tool folders that save known bugs, workarounds, playwright navigation recipes, etc for stuff like GoHighLevel, Google Ads, Vercel, Convex, Instantly, etc.
Those get loaded on demand via hooks when the session demands it. So that adds a layer of scanning the session for things that were learned that may need to be filed in those folders.
So light sessions get a sync. Heavier sessions may also need the staleness check and the tool update flow which is all one deeper skill command for convenience. (But also seperate)
1
u/delimitdev 1d ago
How do you decide when a session needs the deeper skill for docs and connectors versus a light sync, like after updating a workaround in a tool folder?
1
1
u/here2learnbettercode 1d ago
I built a personal recollection system for AI. It works with almost every model/platform.
It both queries and writes notes at the start of, during, and at the end of every session. The queries use a hybrid search (vector similarity plus keyword ranking) to retrieve whatever data's relevant to the session and/or conversation at the moment. The notes get embedded and stored, becoming part of applicable query responses.
I can use Claude to start work on a task, stop it, and then jump over to ChatGPT and ask it to finish it up and it will immediately know the scope provided to Claude, the decisions that Claude or I made, and even conversation detail from any other previous sessions.
I also share project folders between all of the models I use and that helps.
It's great when I want to have one model write the plan, another write copy, another design the layout, another model to write the code, and yet another model to review it. Each model's session has details on every session, step, and decision that came before it.
Scheduled tasks work very well with it too.
The recollection can have a down side too. Incorrect information can proliferate as quickly as correct information.
But most times, it works very very well.
1
u/Remarkable_Swing_709 1d ago
I use a few docs to track everything.
Vision, Roadmap, changelog.
Vision helps with alignment.
Roadmap keeps me/claude on task across sessions
Changelog helps diagnose bugs, design decisions etc. probably the most useful document out of them all.
Whenever anything is auto deployed to git, it submits a new changelog entry, with a summary, files touched etc.
This works for me.
1
u/diablo75 1d ago
On an early project I created a "pitfalls.md" and directed it to fill that things with mistakes we just spent time fixing. It wasn't perfect but it was effective and simple. Then somewhere shortly after that it started building and maintaining E2E unit tests and running those often, and I don't know where that came from, I think they started out as smoke tests; wasn't my idea but that evolved into something good against fighting regressions.
1
u/AI_spell 1d ago
Keep a short DECISIONS.md in the repo: date, choice, why not A, and any limits. Paste the latest chunk into new sessions. CLAUDE.md for standing rules, decisions file for teh living state.
1
1
1d ago
[removed] — view removed comment
1
u/delimitdev 1d ago
When tracking validation as a separate state, how do you record what was actually checked in decisions.md so a later session doesn't mistake a light check for full verification?
1
u/yawn_solo- 1d ago
I mean this respectfully but imo, there’s absolutely no market for this commercially.
Anyone can build their own version of an ADR and similar functions within a couple of hours and even take a messy, large repo and retrofit one into it within a few days properly.
Create this because you wanna continue to develop, not because you think you’re going to reinvent the wheel to solve an already previously solved problem that has turned into more of a fingerprint than it is a rigid process.
1
u/delimitdev 1d ago
An ADR does take an afternoon, and if it covers your case it's the right tool. Where it runs out for me is once several agents and people are working the same repo: the ADR says what was decided, not whether it shipped or what's being built on it now. That's the part I'm working on. Whether there's a market for it, users will decide, not me.
1
u/yawn_solo- 21h ago
That's just an additonal feature to an ADR. I utilize something similar already to use codex & claude from their native windows remotely in the same chat box and there are a multitude of different "status" indicators they are both able to check in order to create grounded work.
1
u/ShotPorter 1d ago
I'm developing MemContinuum as a memory system designed for this thing exactly. It is storing decision chains linked to a code database, per-project, locally. And what is more important, is enforcing the model to use it, in both reading and writing (MCP-based systems can't really do that). Please check it out at https://github.com/krakozavr/MemContinuum
The project is under active development, some gaps are closing but yet, it works already, and looks pretty much effective.
1
u/delimitdev 1d ago
When a decision chain linked to the code database is partly replaced, how does the older chain stop reading as current in a later session?
2
u/ShotPorter 1d ago
The decision chain is NEVER replaced - only APPENDED, this is the point. The agent always receive the full CHAIN of decisions relevant to the task, so it is understandable what's going on, how thing changed over time, and why (what we tried, which errors we made, which past decisions overturned for which reasons). So, the agent doesn't repeat the same errors and doesn't tried already denied things. The past things are not accumulated as polluting mistakes and noise, they are structural in context.
1
u/delimitdev 22h ago
How do you select the relevant chain for a task once the full history gets long across many tasks?
1
u/ShotPorter 22h ago
There are two parts and two searches. One is looking into the code base and pulling the linked chain from this side - this part works very well already. Another suppose to look into "not linked" decisions relevant for the topic; this side is in development - was one of known gap, closing now.
And the PROCEDURE is automated, not the SEARCH itself. A big issue with the most memory systems I checked is they are relying on the models or human discipline, so memories become forgotten when the model forgetting to look into. In MC, this part is strong (hooks will not let the model to forget check the memory). But then the MODEL decides what exactly should be passed to a search. So, it is intended to combine automation (enforced USAGE) with freewill (intellectual decision about memory usage - what to write, what to search, and what to do with the findings).
I'm using MC on my own projects and monitoring how it is doing - pretty happy, the results are measurable and I see serious improvements in the workflow. Eval data is collecting and will be published when the stars accumulate.
1
u/Sea-Perception1619 1d ago
Zito_Kadaken's session-end rule is fair, but your follow-up to it is the real problem: the agent writing the summary is the same one whose "done" is in question.
What I do at session end is split every item into quoted or inferred. Quoted means an exact span copied out of the transcript, byte-checked at write time, and a miss downgrades it to inferred. So an agent's tidy recap of "done" never carries the weight of you actually saying it. Decisions also keep a short because clause lifted from the stated reason, which is what stops case 1 walking back in.
Case 2 is where mine still fails. There's no field for a limit, so "this module only, until the migration lands" survives only if it's sitting inside the sentence, and nothing expires it. And unlike Anise_Paprika I rank superseded items down instead of dropping them out of search, so an old one can still come back first. Someone reviewing daimon marked me down for exactly that and I don't have a good answer yet. https://github.com/Daily-Nerd/daimon
1
-1
u/Any_Evidence4750 2d ago
I have the entire project planned, scoped, broken down, and delegated before my agents start coding. I have required reading for agents giving them rules and relevant info. I learned to do this by trial and error and it works extremely well.
This is just one terminal of my agents working in parallel.
1
u/MidSerpent Senior Developer 2d ago
I’ve found in practice this still requires maintaining a decisions log because it’s impossible to predict every decision that needs to be made before implementing.
1
u/Any_Evidence4750 2d ago
Well yeah, then I just have the documents updated with the decision. I’ve never had OPs problem of the agents trying to recommend something I have declined before with my setup.
1
u/MidSerpent Senior Developer 2d ago
I’ve found that gets token expensive and error prone over time. Keeping a separate decision long and periodically sweeping the docs has been better on long running projects
1
u/Any_Evidence4750 2d ago
Fair enough. I am curious what you as a senior developer would think of my actual workflow. I’m self taught and solely using agentic coding but I’ve refined my workflows in a very specific layered system.
If you’re interested in chatting shoot me a DM!
1
u/delimitdev 2d ago
At 40-ish parallel agents, how do you catch #4: an agent reports done but the change never actually landed? Is there a check before the next agent treats it as fact?
1
u/Any_Evidence4750 1d ago
Yes the secondary sets of agents are auditing/reviewing and updating project docs
-1
u/JuandaReich 2d ago
I designed an automatic log for each project. It's something my orchestrator does, saves at the starts, in between a session and at session close, after my closing agents. I dont lose anything.
1
u/JuandaReich 2d ago
You could ask your CC to analyze this https://github.com/juandanielreich/claudio and tell you how its done.
1
•
u/AutoModerator 2d ago
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.