Add “why” comments to non-obvious code, not “what” comments
Category: Docs · Updated 2026-09-22 · Tools: Claude Code
Use this on a module you or a teammate had to puzzle over recently — code that works but where the reasoning behind a specific choice (a magic number, an odd ordering, a workaround) isn't written down anywhere. Small usage, scoped to one module or file at a time works best.
Full prompt
Read through <file/module path> and identify spots where the code's behavior is correct but the reasoning behind it isn't obvious from the code alone — a magic number, a specific ordering of operations, a workaround for something external, an edge case being deliberately ignored. For each one, add a short comment explaining *why* it's written that way, not what it does line by line. Explicitly skip anything that's already self-explanatory — do not add a comment that just restates the code in English. Show me the diff before considering it done, and don't change any actual logic, only comments.
Tips
- The "why not what" instruction needs to be explicit and repeated — left alone, agents default to narrating every line, which adds noise instead of value
- Scope it to one file or module at a time so the diff stays reviewable
- If you know of a specific tricky spot already, point the agent at it directly rather than asking it to find everything on its own
Still waiting on a reset? See what to do when you hit the limit, or check Codex / Claude time since last reset.
Back to the prompt library · Subscribe: all-products feed