Why I Keep a Per-Project Investigation Log Outside Claude Code

After about six months of running Claude Code across multiple repos, I have stopped pretending that conversation history is enough.

I still use Claude Code for almost everything. The in-conversation layer is excellent for "what should I do next" and "explain this error". The problem is what happens after the conversation ends: I close the session, switch projects, come back two days later, and I cannot find the investigation I am sure I did.

I tried three fixes, and the one that stuck is a per-project investigation log that lives outside the chat.

The first attempt: rely on /resume and session IDs.

The problem was remembering the session ID. By the time I needed the old conversation, I had forgotten the project name, the date, the symptom, and the keyword that would distinguish it from the eleven other sessions I ran that week. /resume works perfectly when you know what you are looking for. It does not help when the whole point of the search is "what was the keyword".

The second attempt: dump important findings into CLAUDE.md.

The problem was that CLAUDE.md is for behavior the model should follow every run. A "we tried plan B, plan A was faster because of X" note does not belong in a file the model reads on every session start. The signal-to-noise ratio collapses within a month, and the file becomes a graveyard of one-off decisions. I had to admit that CLAUDE.md is a constitution, not a journal.

The third attempt: a per-project investigation log, written by hand, indexed by project.

The format is a single markdown file per project, with one short entry per "investigation": a problem, the path I took, the conclusion, and any links or commit hashes. I append to it from a tiny shell command, so writing an entry takes five seconds. I read it whenever I am about to start work on the project, the way I would read a colleague's handover note.

The crucial detail is the indexing. Entries are filed by project, not by tool. If I had used the "Claude Code session browser" route, the same investigation under Cursor or Codex would have been filed under a different tool, and the cross-tool lookups would still break. The project is the unit of search.

What goes in:

• A one-line summary of the question.
• The decision I made and why.
• A link to the commit, the PR, or the conversation (if I remember it).
• Anything I want future-me to know — "don't redo this analysis, the bottleneck is in module X".

What stays out:

• Anything that belongs in CLAUDE.md (rules the model must follow every run).
• Long code excerpts. Paste a path and a line range instead.
• Anything private to one session. If it is not useful next month, it is not useful.

The cheapest version of this is one markdown file per project, kept next to the code, with a short shell alias for appending. The richer version is a tool with a search box and a per-project filter. Both work. The richer one is what I am building as Shelf, because the manual approach broke down around eight projects.

If you only have two or three projects, the manual approach is fine. The shell alias is two lines. The discipline is "write the entry the moment you decide", not "I will remember to do it later". You will not.

Tags: claudecode, codex, devtools, productivity, workflow

Shelf, the open-source desktop workspace we are building around Claude Code and Codex, is the project-level retrieval layer we use to find old investigations by project. The link is at
https://github.com/Harukaon/shelf if you want to compare it to your current workflow.