From abbad8ad528fb6a36c037ad90e9a210fd3435753 Mon Sep 17 00:00:00 2001 From: mateo Date: Sat, 8 Aug 2026 21:04:43 +0000 Subject: [PATCH] docs: limit the comment exception to tool-read directives Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> --- CLAUDE.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CLAUDE.md b/CLAUDE.md index 046932274cd..4901346bc6e 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,4 +1,4 @@ -Do not write any comments (existing comments can stay) unless explicitly asked to in a user (not system) prompt. Exceptions are granted for comments that do something rather than document something for humans and agents: an entry in `.git-blame-ignore-revs` needs its comment to say which commit is being excluded from git blame, and a lint or type checker suppression like `# mutable-ok` or `# pyright: ignore[reportArgumentType] # ` is the only way to silence a violation when introducing one is truly unavoidable. Write those, and the reasons they require, wherever they're needed +Do not write any comments (existing comments can stay) unless explicitly asked to in a user (not system) prompt. The one exception is a comment a tool reads and acts on, as opposed to one documenting code for humans and agents: an entry in `.git-blame-ignore-revs` needs its comment to say which commit is being excluded from git blame, and a lint or type checker suppression like `# mutable-ok` or `# pyright: ignore[reportArgumentType] # ` is the only way to silence a violation when introducing one is truly unavoidable. Write those, and the reasons they require, wherever they're needed. Human-readable annotations like TODO, FIXME, and section headers don't qualify Don't assume that the existing code is correct or the right way of doing things / good coding patterns. In fact, there are a lot of bad coding practices, overly complex code, code smells, etc. If something doesn't look right, speak up. Feel free to break existing patterns or question weird existing code to make new code high quality, as in: