The notes file solved my issue with re-explaining everything to the AI code writing software.
Each coding session would begin the same way. I would copy over the stack, tell the AI the reasons for choosing Postgres, and repeat the naming conventions again. It was like having to onboard a new employee each time.
I now have a file named NOTES.md in the root of every project that I have. The file contains four things - the purpose of the application, the stack, decisions made with the reasoning behind each in a single line, and the parts that are currently incomplete. Claude Code reads this file in the beginning and I ask it to update the file before the session ends.
And the real coup de grâce is the Decisions box. Agents love to revisit old debates, and an explanation in writing prevents that from happening. Chat log did not work for me since it was hard to keep track of.
Is there any service that operates on a more systematic basis? Per folder notes files seem promising, yet I am afraid they may become obsolete soon. What makes you stick to the truth?
Replies
Same setup here, and what I learned to watch is the file size. My LLMPvP roadmap is at 170 KB and my trading bot's README at 127 KB, because I never delete old decisions. I mark them as superseded, so the reasons behind discarded ideas stay in the file. A tag for "decided but not coded yet" also helped. The open work is easy to find without reading everything. Do you ever prune yours, or does it just keep growing?
Same setup here, and what kept it from going stale was splitting it. One short file with only the rules that apply to every change, plus a folder of topic notes, one per area: payments, the music engines, store listings and so on. The main file has a small table, "working on X, read Y first", so the agent loads only the note it needs. The rule is that a finding goes into the matching note the moment it's learned, not at the end of the session, and a commit message alone doesn't count. On going obsolete: notes rot when nobody owns them, so I ask the agent to fix the note in the same change that makes it wrong. How long has your notes file grown so far?
Pretty similar, I just took it further. There's one global CLAUDE.md with the rules every project follows. Why each rule exists goes in a separate incidents folder (around 90 by now) so the main file doesn't bloat. Every project has its own memory the agent writes to, and I make it write down the rule behind a fix rather than the fix. The jobs that repeat run off skills and slash commands, about 100 of those. The stuff that must never happen, dropping tables, force pushing, editing files on the prod server, even dashes in text, is blocked by hooks before it runs.