docs: add claude-faq.md, starting with memory-vs-docs Q&A

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KefnwbGDM8CGrhb4sFhVq9
2026-07-04 12:57:21 +02:00
parent de11b849d8
commit da832b961e
1 changed files with 35 additions and 0 deletions
@@ -0,0 +1,35 @@
 # Claude FAQ
 Notes on how Claude Code works with this repo, for later reference.
 ## Does Claude store a separate memory/context for planning work like the overshoot investigation, or is the TODO enough?
 **Q:** After a long session diagnosing the HOLD-state overshoot and writing
 up the fix plan in `docs/overshoot_hold_windup.md` / `components/pid/TODO.md`,
 I asked: did you also store a context and/or memory for easier retrieval
 later, or is the TODO enough?
 **A:** No separate memory was created for the plan's *content* — that lives
 in the committed docs (`docs/overshoot_hold_windup.md` +
 `components/pid/TODO.md`), which is strictly better than Claude's own memory
 system for this: it's version-controlled, visible to anyone with repo
 access, and gets updated in place as the real work happens. Claude's memory
 system explicitly excludes storing "architecture/file paths/design content
 already derivable by reading the project" — duplicating a plan into memory
 would just be a second, decaying copy of the same facts.
 What Claude *does* keep in memory is a **pointer**, not the content: an
 existing `pid_design_backlog.md` memory says (in effect) "check
 `components/pid/TODO.md` before starting PID work." That pointer was 15
 days stale at the time and had a couple of now-wrong claims (e.g. it said
 the three Kalman filters sharing one tuning was "still open", but
 `temp_controller_smith.py` had since dropped Kalman filtering entirely) —
 so it was refreshed in the same turn, with one line added noting this
 session's windup investigation exists and where to find it, without
 copying the investigation's content into memory.
 **Takeaway:** for durable project knowledge that belongs in the repo
 (design decisions, investigation writeups, TODOs), the repo docs *are* the
 memory — Claude's own memory system is reserved for cross-session pointers,
 preferences, and facts that aren't otherwise written down anywhere in the
 project.