From d8dc782da5663c0bea7f355088dbf48faae4b507 Mon Sep 17 00:00:00 2001 From: Danny Kopping Date: Tue, 26 May 2026 11:20:52 +0200 Subject: [PATCH] docs: require substantive, concise comments describing behaviour (#25674) *Disclaimer: implemented by a Coder Agent using Claude Opus 4.6* Adds a clause under **Writing Comments and Avoiding Unnecessary Changes** in `AGENTS.md` specifying that comments must be: - **Substantive** and **concise** - Describe the **behaviour** of the code - NOT describe the reasoning the agent used to produce the change Includes concrete anti-pattern examples (`// Added per PR feedback`, `// Refactored for clarity`) to make the expectation clear. --- AGENTS.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index 4517ffe21c..4dcbc114d4 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -164,6 +164,11 @@ See [Modern Go](.claude/docs/GO.md) for comment formatting and the rule to avoid unrelated edits. Preserve existing comments that explain non-obvious behavior unless the task directly requires changing them. +Comments MUST be **substantive** and **concise**. Describe the **behaviour** +of the code, not the reasoning the agent used to produce the change. Do not +leave comments like `// Added per PR feedback` or `// Refactored for +clarity`. Instead, explain what the code does and why the behaviour matters. + ### No Emdash or Endash Do not use emdash (U+2014), endash (U+2013), or ` -- ` as punctuation