So I have an instruction in my CLAUDE.md that tells Claude Code to flag any noteworthy stuff it finds in the codebase after every task, even if its unrelated to whatever we were working on. Unfinished TODOs, possible bugs, dead code, smells, that kind of thing. It does this great. The problem was just that it ends up in the chat and i have to go offtrack and wrap my head around issues I currently don’t want to take care. When I have a calm afternoon I pick a section and chip away. So I started having it dump them into a markdown file code-observations.md instead. Below the Instructions I have in CLAUDE.md
Code Observations After completing each task, log noteworthy findings you encountered while reading or working with the codebase into todo/code-observations.md. The file persists across sessions so the team can triage during dedicated cleanup passes — see the file’s header for entry format, severity tags, and the verify/resolve lifecycle. What to look for(only things you actually encountered; don’t go hunting): - Unfinished implementations: TODOs, stubs, placeholder logic, partially implemented features - Dead code: Unused functions, unreachable branches, commented-out blocks - Possible bugs: Unchecked errors, race conditions, off-by-ones, logic errors - Unusual patterns: Inconsistent conventions, surprising workarounds, anti-patterns How to log: 1. Append a row to the matching section’s table in todo/code-observations.md (Renderer / Main / FastAPI / DB / Directus / Build / Other). The header at the top of that file documents the exact column format, severity tags, and the ☐/☑ status glyphs. 2. Get the introducing commit’s short hash via git blame -L <line>,<line> <file> and put it in the Hash column (backtick-wrapped). For non-code observations (e.g. Directus content) write n/a. 3. Append-only — never reorder or delete rows. Use the V/R status columns and strikethrough rules defined in the file for state changes. In your end-of-turn response, mention findings only if directly relevant to the current task. Otherwise say “N new observations logged” so the user knows the log moved without re-listing everything. If there’s nothing to log this turn, skip the section entirely.
Claude appends new findings to that file instead of dumping them in chat. So mainly why I love that workflow is that, it does it just passively. I could have created a Skill, or prompt to find these kind of issues, but why wasting tokens when we can find and take note of such while just vibing on something? Only thing is, you should verify the issues first before you actually instruct Claude to fix them, because sometimes its not actually an issue and it just flagged it with limited context of the related code he flagged. Anyone else doing stuff like this? I can really recommend you to try out! Add whatever you like and fits your codebase. Possibly i build a Skill next to tackle those items (like first do verify the issue, then fix, then move do a seperate file with done tasks). submitted by /u/snarfi
Originally posted by u/snarfi on r/ClaudeCode
You must log in or # to comment.