Series: Weekend at Claude's — misadventures in building a production app with an AI anyone could mistake for the person who's going to make the whole thing happen
More than once, I scrolled back through a chat looking for "the file with the consent screen changes," found one, downloaded it, committed it — and it was the earlier draft. Not the final one. The one Claude had already superseded three messages later with a better version that fixed something the first one missed.
This wasn't a one-time mistake. It happened more than once, on more than one file, across a session that had stretched across several days and dozens of design decisions. By the time I was trying to commit everything, I had four or five versions of TASKS.md floating around in the chat, two different DECISIONS.md append files with overlapping but not identical content, and no reliable way to tell at a glance which one was actually current without re-reading the conversation.
That's not a Claude problem. That's a "this project has gotten big enough that scrolling doesn't scale" problem.
Why it kept happening
The pattern was always the same. I'd ask for something mid-session — design a feature, fix a gap, make a decision — and Claude would (reasonably) update TASKS.md or DECISIONS.md right then, because that felt like the responsible thing to do in the moment. Then later in the same session, something else would come up that touched the same file, and it'd get regenerated again. By the end of a long session, the chat had three or four versions of the same document, each one a little more complete than the last, with no label distinguishing "this is final" from "this was final twenty minutes ago."
Multiply that by a session that runs across multiple days, and the problem compounds. I'm not holding the whole conversation in my head. I'm scrolling, pattern-matching on filenames, and trusting that the one I land on is the right one. Sometimes it wasn't.
The fix wasn't "be more careful"
The instinct is to just be more disciplined — track versions better, double-check before downloading, keep a personal log. That's a real fix, but it's the kind of fix that depends on me never having a distracted moment, which isn't a plan, it's a hope.
The actual fix was structural: stop producing multiple versions of the same document in the first place. Instead of regenerating TASKS.md every time something new comes up mid-session, hold all of that in one place that gets edited in place — never duplicated, never re-dated, never superseded by a sibling file three messages later. Then only touch the real project files — TASKS.md, CONTEXT.md, DECISIONS.md, HISTORY.md — at an actual session close, once, when there's something to consolidate.
That single place is the new SESSION_MANIFEST.md.
What it actually does
It's a living index, not an archive. For every feature or fix that comes up in a session, it gets one row: what was designed, what file has the spec, what file has the Claude Code prompt, and whether it's been implemented yet. When the next piece of work touches something already in the manifest, the existing row gets updated — not a new file, not a new section, the same row.
At the real end of a session — not every time something gets decided, but when I'm actually closing out — everything sitting in the manifest gets folded into the four core project files exactly once. Then the manifest gets cleared back down to just the reference index, ready for the next session to add to.
The rule that makes this work is almost embarrassingly simple: regenerate the core files only at true session close, never mid-session. Every superseded file I almost committed by mistake existed because that rule wasn't being followed yet. Once it is, there's structurally only one version of each file to ever exist at a time — there's nothing to confuse it with, because the earlier draft was never written to a separate file to begin with.
Why this matters more as the project grows
A two-day project doesn't need this. You can hold the whole thing in your head, and scrolling back is fast enough. Aphilaty stopped being that kind of project a while ago — sessions that span days, a dozen-plus features designed and queued for Claude Code, a blog series, legal docs, an API layer, all happening in the same place. The cost of losing track of "which file is current" doesn't grow linearly with project size. It grows faster than that, because every new feature is one more thing that could have a stale duplicate floating around.
The manifest is a small thing to maintain. It's a much smaller thing than re-deriving "what's actually current" by scrolling through a week of conversation, hoping I land on the right message.
Bernie's friends never had a manifest. They just kept dragging the same guy around and hoping nobody asked too many questions. We'd rather know exactly which version of everything is real.
Aphilaty is a privacy-first community coordination app. aphilaty.com