Started with an ARCHITECTURE.md I wrote once and then intermittently updated. In most cases for a new session, Claude re-derived everything from the code and git log. Wanted sessions to get up to speed faster. The obvious fix is to actually keep that doc current. My instinct pointed me in a different direction, but hard to know if this is right, since it’s only been a month. Instead of docs need to be up to date , I went for minimal docs that don’t reproduce what’s already in the code. I.e. glossary of concepts, invariants, decisions, etc. The code and the data model stay the source of truth. The decisions are static: an entry records what was decided on a date, not what’s true now. append-only decision log — dated, never edited, never deleted namespace docstrings instead of external prose; they rot visibly, inside the diff that changed the code ARCHITECTURE.md cut down to glossary, data flow, invariants — only the things code can’t express 1.5 MB of older design specs frozen and explicitly labeled unmaintained a Stop hook that fires on six structural changes only (new subsystem dir, a namespace with no docstring, an edit to the frozen specs, etc). Ordinary feature work never trips it — if it did it’d be noise and I’d start bypassing it The thinking: I’m not writing for a skeptical human who’d notice a doc looks out of date. I’m writing for something that trusts everything it reads and is bad at telling stale from current. So aim for staleness being impossible or loud, rather than aiming for accurate. One month, let’s see how well this works… Anyone keeping a genuinely current architecture doc? How do you avoid drift and keep it up to date? Who else has tried this approach? What artifacts do you maintain – manually or via agent? submitted by /u/RestlessMotion
Originally posted by u/RestlessMotion on r/ClaudeCode