From 8ea1f2ee338e3fb2737b9e812d0e8077bbcaf710 Mon Sep 17 00:00:00 2001
From: Jinjing <6427696+AmethystLiang@users.noreply.github.com>
Date: Mon, 20 Apr 2026 19:39:25 -0700
Subject: [PATCH] docs(agents): tighten code-comment rule to short, why-only
 (#883)

---
 AGENTS.md | 8 +++++---
 1 file changed, 5 insertions(+), 3 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index 8be143be..f69c354d 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,8 +1,10 @@
 # AGENTS.md
 
-## Code Comments: Document the "Why"
+## Code Comments: Document the "Why", Briefly
 
-When writing or modifying code driven by a design doc or non-obvious constraint, you **must** add a comment explaining **why** the code behaves the way it does.
+When writing or modifying code driven by a design doc or non-obvious constraint, add a comment explaining **why** the code behaves the way it does.
+
+Keep comments short — one or two lines. Capture only the non-obvious reason (safety constraint, compatibility shim, design-doc rule). Don't restate what the code does, narrate the mechanism, cite design-doc sections verbatim, or explain adjacent API choices unless they're the point.
 
 ## File and Module Naming
 
@@ -22,4 +24,4 @@ Orca targets macOS, Linux, and Windows. Keep all platform-dependent behavior beh
 
 ## GitHub CLI Usage
 
-Be mindful of the user's `gh` CLI API rate limit — batch requests where possible and avoid unnecessary calls. All code, commands, and scripts must be compatible with macOS, Linux, and Windows.
+Be mindful of the user's `gh` CLI API rate limit — batch requests where possible and avoid unnecessary calls. All code, commands, and scripts must be compatible with macOS, Linux, and Windows.
\ No newline at end of file