Curious how others handle this — do you keep everything in one place, or does it not matter as long as you write it down somewhere?
0) Work journals. One repo for all projects at once. Each project or feature has its folder with dated entries, one entry per significant move, and a small index: a row per entry with date, link and a few lines of what happened. The project folder points to its journal and the journal points back, so when two projects touch, both sides reference each other.
1) Docs. Always maintained starting from day one of the project, not scattered in the code but usually in repo/<proj|subproj>/docs in the code repos.
2) Knowledge base with the index on top which consolidates the knowledge across projects. The index is sqlite + faiss, built from what is in git and rebuilt as it changes, and there is MCP over it. So I can ask "where did I talk about X" and get a quick recap with the links to primary notes (can be docs, journals, other knowledge base articles, sometimes source code files).
3) Issues tracker (e.g. github issues). Journal entries reference the issues (no retelling, but the linkage is preserved). Optional and for smaller projects can be solved with journals.
4) Procedures. Notes that teach how to maintain all of this while working. This is the "onboarding procedure" for a maintainer, and it is a "must read". All these piles of knowledge and sources stay sane and survive months only because the maintainers always keep the network updated as they work. My coding agents follow these same procedures and journal.
Getting back to a project after a long break or onboarding a new agent starts from reading its journal index. I describe the feature, the agent finds relevant journals and onboards itself. This just works
-- start of extract
# Documentation — mandatory
- `docs/` holds the project's living documentation; every module/subsystem gets its own md file. If `docs/` is missing, create it plus `docs/README.md` before any other doc work. - `docs/README.md` is the index: one line per doc with a short description. Update it whenever a doc is added, removed or renamed. - Any change touching documented behaviour updates its doc *in the same change* — a change isn't done until its docs are. - New feature/module → new doc file → add to the index. - One-home rule: each topic lives in exactly one doc; everywhere else links to it, never copies it. - *Code is ground truth.* A doc line contradicted by code gets fixed the moment it's found, not noted for later. - Prune stale lines; don't only append. - Keep this file current too, and keep the docs-index link above wired.
# Index and wiring One line per doc file with a short description. Link docs/README.md from the root CLAUDE.md so the index is reachable from the project's agent instructions.
-- end of extract
If you want to map an existing project, you might add this:
- Document this existing web project into docs/, working bottom-up from the actual code. Never document a feature you haven't seen in source. - If the repo is large, go module by module rather than in one pass — finish and index each doc before starting the next.
Optionally you can specify the structure (also as a rule), here is an example one, adapt to your needs: 1. Environment — docs/ENVIRONMENT.md 2. Architecture — docs/ARCHITECTURE.md 3. Module inventory — docs/MODULES.md 4. API surface — docs/API.md 5. Data model — docs/DATA-MODEL.md 6. Domain glossary — docs/CONCEPTS.md 7. Open questions — docs/QUESTIONS-FOR-OWNER.md 8. Tests — docs/TEST-COVERAGE.md
This is a simple setup, but forces the agent to write your comments to docs, keep them current, remove stale data, etc. I frequently state during session - "wire in docs" for important facts or instructions. The fact that the index of the mds is wired in agents/claude.md gives instant access to every session.
Even better - when you have it all documented - you can instruct the agent for the information to be restructured, killing duplicates, establishing priority - notes seem to pile up unevenly, a regular restructure solves it.
Also you can ask it to fill in weak information from source/comments, etc. or ask you to provide it. As a side effect that boosts precision of the sessions themselves, and buys you the luxury to say things like "do whatever necessary..." and expect to actually understand you.
For day-to-day task it is of benefit to add a Plans.md and track progress there instead in the durable docs.
On session end (ok, there is hook for automatically do this, but in realty only you know when you are really finished) - take extra care - ask the agent to persist valuable session data, write durable the scripts it generated - you won't believe how much precise information stays in the session and gets discarded. You can even repeat this several times (I would say a must for big fat sessions), until it starts looking at you with empty eyes (figuratively :) ).
Possibly you can ask agent to do a handoff md document and a prompt to initiate a session continuation, that points to the md.