docs: add code comment guidelines to AGENTS.md and update rule (#27729)

* docs: add code comment guidelines to AGENTS.md

Co-Authored-By: eunjae@cal.com <hey@eunjae.dev>

* docs: extract comment guidelines into agents/rules and reference from AGENTS.md

Co-Authored-By: eunjae@cal.com <hey@eunjae.dev>

---------

Co-authored-by: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

AGENTS.md

@@ -17,6 +17,7 @@ You are a senior Cal.com engineer working in a Yarn/Turbo monorepo. You prioriti
 - Put permission checks in `page.tsx`, never in `layout.tsx`
 - Use `ast-grep` for searching if available; otherwise use `rg` (ripgrep), then fall back to `grep`
 - Use Biome for formatting and linting
+- Only add code comments that explain **why**, not **what** — see [code comment guidelines](agents/rules/quality-code-comments.md)
 
 
 ## Don't
@@ -29,6 +30,7 @@ You are a senior Cal.com engineer working in a Yarn/Turbo monorepo. You prioriti
 - Never use barrel imports from index.ts files
 - Never skip running type checks before pushing
 - Never create large PRs (>500 lines or >10 files) - split them instead
+- Never add comments that simply restate what the code does (e.g., `// Get the user` above a `getUser()` call)
 
 ## PR Size Guidelines
 

agents/rules/quality-code-comments.md

@@ -13,10 +13,13 @@ Keep comments limited and avoid obvious ones. Comments should explain "why" not
 
 ## When to Comment
 
-- Complex business logic that isn't obvious from the code
+- Business decisions or domain logic that isn't obvious from the code
 - Workarounds or hacks with explanation of why they're needed
 - Non-obvious performance optimizations
 - Important security considerations
+- Troubleshooting context (e.g., why a particular approach was chosen after hitting issues)
+
+If none of these apply, skip the comment entirely. The function name, parameters, and return type should speak for themselves.
 
 ## When NOT to Comment