From bd896693dad8d8ba2472bb56668560d20f2ce63a Mon Sep 17 00:00:00 2001 From: Francesco Novy Date: Wed, 17 Jun 2026 09:52:50 +0200 Subject: [PATCH] docs: Clarify comment and PR-body guidelines for agents Document two conventions in AGENTS.md (CLAUDE.md): comments must explain why not what, and PR bodies should omit the "Summary" heading. Co-Authored-By: Claude Opus 4.8 (1M context) --- AGENTS.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index baa0ca7f2174..b27c79f3c04b 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -73,7 +73,8 @@ Uses **Git Flow** (see `docs/gitflow.md`). ## Pull Requests -- **Do NOT add a "Test plan" / "Testing" checklist to PR bodies.** CI runs the full test suite on every PR — a hand-rolled checklist duplicates that signal and rots fast. Use the PR body for _Summary_ and _Root cause_ (if relevant) only. +- **Do NOT add a "Test plan" / "Testing" checklist to PR bodies.** CI runs the full test suite on every PR — a hand-rolled checklist duplicates that signal and rots fast. Write the summary content directly and add a _Root cause_ section only if relevant. +- **Omit the "Summary" heading** in PR bodies — lead with the summary text itself, no `## Summary` header. - Include `Fixes #` somewhere in the PR body so the merge auto-closes the linked issue. ## Architecture @@ -130,6 +131,7 @@ Uses **Git Flow** (see `docs/gitflow.md`). - Only use libraries already in the codebase - Never expose secrets or keys - When modifying files, cover all occurrences (including `src/` and `test/`) +- Comments explain **why**, never **what** — never add a comment that restates what the code does or describes the change being made; only comment when the reasoning isn't obvious from the code itself ## Reference Documentation