I’m a UX designer doing prototypes of complicated, experimental UX designs. These are things that LLMs often really do poorly on as they have so little previous designs to fall back on. Instead of relying on it figuring things out from the code, which I found to be error prone, I started asking to to remember and log stuff, e.g. why I did something, when changes were made, a running list of open questions and CLAUDE.md just turned into a huge bloated document. I’ve setting on the following structure. CLAUDE.md — pure orientation: workflow rules, stack, file map. Nothing specific to the working of the code. SPEC.md — The documented behavior of the current state of the project. Rules stated as facts, no backstory. A decisions/ directory — the why : evidence, rejected alternatives, dated reasoning behind each rule. This is where the deeper story lives so SPEC.md doesn’t have to carry it. I have just a few files here (indexed in SPEC.md) that cover the main sections of the project. WATCHLIST.md — open doubts about current rules that aren’t bugs, just unresolved trade-offs I’m holding pending more data. HISTORY.md — a terse chronological changelog that only ever points at the other files, never duplicates their content. The rule I keep coming back to: never write the same fact in two places. Every file has exactly one job, and if content doesn’t clearly pass that file’s test, it doesn’t go there. HISTORY.md is the one the LLM naturally reaches for after finishing a task, so it’s also the easiest place to lazily dump reasoning that should really go in the decisions log. I added an explicit checklist at the top of that file forcing a "does this belong in decisions/ " check before you’re allowed to just log-and-go. The structure allows me to /new agressively as the agent can pick up context fairly quickly. SPEC.md is basic context it needs before diving into any code changes. If we go into /plan mode, reviewing the decisions/ directory gives even more backstore. I’m sure there are MUCH more sophisticated solutions out there. I’ve basically stumbled into this and if there is a better approach, I’m all ears. submitted by /u/scottjenson
Originally posted by u/scottjenson on r/ClaudeCode