Agents: Tighten doc-comment rules for compact code comments #4966

.claude/rules/frontend-rules.md

@@ -1,7 +1,9 @@
 ## Frontend Code Style & Test Coverage
 
-- **Doc comments are required**, even when a test isn't practical. Every new JS function and every Vue component `methods:` / `computed:` entry needs a brief doc comment above it — including module-internal helpers, not just `export`-ed functions. The house style is a single `// Name does X.` line (see `src/options/themes.js`, `src/common/util.js`); use a `/* … */` block for multi-line notes.
-- Vue Single-File Components: add a one-line doc comment above the default export and a one-liner above each non-trivial method, computed property, or watcher. Trivial getters (`isOpen: () => this.open`) can skip the comment.
+- **Doc comments are required, but compact.** Every new JS function and every non-trivial Vue `methods:` / `computed:` / watcher entry needs a doc comment — but the default is ONE `// Name does X.` line (see `src/options/themes.js`, `src/common/util.js`). Skip trivial getters (`isOpen: () => this.open`).
+- **Length cap.** One line for WHAT. Add 1–2 short lines (`// …`) only when the WHY is non-obvious: a hidden invariant, a workaround that would otherwise be undone by a future cleanup, a contract a reader can't infer from the code. If the next reader can derive it from the function body or a nearby line, leave it out. Multi-paragraph comments belong in specs or PR descriptions, never in source.
+- **Don't include in code comments:** issue / PR numbers, "previously…" history, alternatives considered, what the function used to do, references to old commits, names of subsequent reviewers, or any narrative that names the change rather than the steady-state behavior. Those belong in commit messages, specs, or handover notes.
+- Vue Single-File Components: one-line doc comment above the default export and a one-liner above each non-trivial method, computed property, or watcher. Same length cap as above.
 - Test new JS functions (including helpers) and new Vue components whenever practical; update existing tests when behavior changes. When a unit test is impractical (DOM-heavy flows, third-party widget integration), the doc comment is still mandatory — it's the minimum bar.
 - **JavaScript only — do not introduce TypeScript.** The frontend is a pure JS + Vue SFC codebase: no `.ts` files, no `tsconfig.json`, no `<script lang="ts">` blocks. JSDoc type annotations in comments are fine; full TS migrations are out of scope.
 - Use the Options API in Vue components (consistent with the rest of the codebase); do not introduce Composition API or `<script setup>`.

.claude/rules/go-code-style.md

@@ -2,7 +2,8 @@
 
 - Run `make lint-go` (golangci-lint) after Go changes; prefer `golangci-lint run ./internal/<pkg>/...` for focused edits.
 - Doc comments for packages and exported identifiers must be complete sentences that begin with the name of the thing being described and end with a period.
-- Every new function, including unexported helpers, needs a concise doc comment that explains its purpose.
+- Every new function (including unexported helpers) needs a doc comment — but keep it compact. Default to ONE line: `// Name does X.` Add a short follow-up line only when the WHY is non-obvious (hidden invariant, subtle workaround, contract a reader can't infer from the body). If the next reader can derive it from the code, leave it out.
+- **Don't include in code comments:** issue / PR numbers, "previously…" history, alternatives considered, what the function used to do, references to old commits, names of subsequent reviewers, or any narrative that names the change rather than the steady-state behavior. That context belongs in commit messages, specs, or handover notes.
 - For short examples inside comments, indent code rather than using backticks; godoc treats indented blocks as preformatted.
 - Every Go package must contain a `<package>.go` file in its root (e.g. `internal/auth/jwt/jwt.go`) with the standard license header and a short package description comment.
 - Go is formatted by `gofmt` with tabs. Do not hand-format indentation. After edits run `make fmt-go` (gofmt + goimports).

AGENTS.md

@@ -99,13 +99,16 @@ Title Case rules (Chicago-style, with code- and path-aware normalization):
 - Shared Go style rules:
   - After Go edits, run `make fmt-go` and keep `gofmt` tab indentation.
   - Doc comments for packages and exported identifiers must be complete sentences that begin with the described name and end with a period.
-  - Every new function, including unexported helpers, needs a concise doc comment that explains its purpose.
+  - Every new function (including unexported helpers) needs a doc comment — but keep it compact: default to ONE `// Name does X.` line. Add 1–2 short follow-up lines only when the WHY is non-obvious (hidden invariant, subtle workaround, contract a reader can't infer from the body).
   - Every new Go function, including unexported helpers, must have focused test coverage in the corresponding `*_test.go` files; update existing tests or add new ones as needed.
   - For short examples in comments, indent code instead of using backticks.
   - Every Go package must contain a root `<package>.go` file with the standard license header and a short package description comment.
+- Shared JS/Vue style rules:
+  - Every new JS function and every non-trivial Vue `methods:` / `computed:` / watcher entry needs a doc comment. Same compact default as Go: ONE `// Name does X.` line; 1–2 short follow-up lines only for non-obvious WHY. Trivial getters (e.g. `isOpen: () => this.open`) can skip the comment.
 - Shared JS/Vue testing rules:
   - New JavaScript functions, including helpers, should be tested whenever practical; update existing tests or add new ones as needed.
   - New Vue components should have component-test coverage, and existing component tests should be updated as needed when behavior changes.
+- Do not include in any code comment (Go or JS): issue / PR numbers, "previously…" history, alternatives considered, what the function used to do, references to old commits or reviewers, or any narrative that names the change instead of the steady-state behavior. That context belongs in the commit message, the spec, or a handover note — never in source.
 - When adding a metadata source such as `SrcOllama` or `SrcOpenAI`, update both `internal/entity/src.go` and `frontend/src/common/util.js` so backend and UI stay aligned.
 
 ## Agent Runtime