From 8adafe51db4125ea261775d2da2328e61f526377 Mon Sep 17 00:00:00 2001 From: cyfung1031 <44498510+cyfung1031@users.noreply.github.com> Date: Fri, 17 Jul 2026 21:42:51 +0900 Subject: [PATCH 1/3] =?UTF-8?q?=F0=9F=93=84=20=E8=A1=A5=E5=85=85=E6=B3=A8?= =?UTF-8?q?=E9=87=8A=E8=A7=84=E8=8C=83=EF=BC=9A=E6=8B=92=E7=BB=9D=E5=AE=A1?= =?UTF-8?q?=E8=AE=A1=E8=BF=BD=E6=BA=AF=E6=A0=87=E7=AD=BE=E3=80=81=E5=A4=8D?= =?UTF-8?q?=E8=BF=B0=E6=80=A7=E4=B8=8E=E5=A4=B1=E6=95=88=E6=B3=A8=E9=87=8A?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Codex/Claude 等 agent 在近期一次多轮代码审计中，把内部审计编号 （如 "finding 5"）写进了正式代码注释与测试用例名称，审计对话结束后 这些编号对读者毫无意义；同一批改动里还出现了纯复述下一行代码的注释、 与所在函数/类 JSDoc 重复的说明，以及代码搬走后未同步更新、继续描述 错误位置逻辑的过时注释。 在 docs/develop.md 的 Language Conventions 之后新增 Comment Discipline 小节，给出可执行的规则与反例；AGENTS.md 的 Engineering Principles 增补一条对应的非协商条款并链接过去，避免同一事实在两份 文档里重复维护。 Co-Authored-By: Claude Sonnet 5 --- AGENTS.md | 1 + docs/develop.md | 23 +++++++++++++++++++++++ 2 files changed, 24 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index 63d90e238..6541b128c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -45,6 +45,7 @@ These are non-negotiable and apply to every change, regardless of what `docs/dev - **Direct replacement over adapter sandwiches.** When swapping a backend/library, replace in place — no `interface Foo + LegacyImpl + NewImpl` unless both must coexist at runtime. - **Scope discipline — stay in your lane.** Bug fix ≠ cleanup PR. Touch only the files the task requires; leave unrelated files untouched (不要动和任务不相干的文件). Don't add helpers, abstractions, validation, or backwards-compat shims you don't need today. Three similar lines beats a premature abstraction. - **No dead code or `// removed` markers** — git remembers. Delete unused code outright. +- **Comments explain "why", not "what" — and never carry review/audit labels.** No `finding N`, issue numbers, or round labels in comments or test names; that traceability belongs in the commit message/PR description. Don't restate the next line, don't duplicate an existing JSDoc, and don't leave a comment behind describing code that moved or was replaced. See `docs/develop.md`'s Comment Discipline section. ## Architecture diff --git a/docs/develop.md b/docs/develop.md index 0ce0ab4bd..08a2deafc 100644 --- a/docs/develop.md +++ b/docs/develop.md @@ -51,6 +51,29 @@ Use strict TypeScript, React JSX runtime, 2-space indentation, semicolons, doubl - UI default English (global users). - Template literals: `${i}`, not `${i.toString()}`. +### Comment Discipline + +A comment earns its place by telling the reader something the code cannot: an invariant, a race condition, a +workaround for a specific constraint, or a reason something looks wrong but isn't. Before adding or keeping a +comment, ask whether deleting it would cost a future reader anything — if not, delete it. + +- **No internal tracking labels.** Never write review-round or audit identifiers into comments or test names — + e.g. `finding 5`, `issue #123`, `round 2 fix`, `【finding N 回归】`. These numbers are meaningless outside the + conversation that produced them and read as noise once that context is gone. If a fix needs traceability, + that belongs in the commit message or PR description, not in source code; the comment itself should just + state the invariant being protected (e.g. `确认读失败不代表写入未落盘，只是无法证实` rather than `见 finding 2`). +- **Don't restate the next line.** A comment placed right above code must add information the code doesn't + already convey — never narrate what a reader can already see, like `// 继续循环` above `continue;` or + `// send done event` above `sendEvent({ type: "done" })`. If the comment would read the same after deleting + the code below it, it isn't explaining anything. +- **Don't duplicate the enclosing doc comment.** If a function or class already has a JSDoc explaining a + behavior, don't repeat the same explanation as an inline comment inside its body — state each fact once, in + the place that owns it, and let the rest of the code speak for itself. +- **Keep comments attached to what they describe.** When you move, replace, or reorder code, move or delete the + comments that described it. A comment that still describes logic that used to be there, but no longer sits + next to what actually runs now, is more misleading than no comment at all — verify this explicitly when a + diff moves code around, not just when it adds new code. + ## UI React 19 + shadcn/ui (Radix UI primitives, "new-york" style) + Tailwind CSS v4 + React Router. Pages in From c2748a24d55824e69a70678bee25573f911877eb Mon Sep 17 00:00:00 2001 From: cyfung1031 <44498510+cyfung1031@users.noreply.github.com> Date: Fri, 17 Jul 2026 21:46:01 +0900 Subject: [PATCH 2/3] =?UTF-8?q?=F0=9F=93=84=20=E4=BF=AE=E6=AD=A3=E6=B3=A8?= =?UTF-8?q?=E9=87=8A=E8=A7=84=E8=8C=83=EF=BC=9A=E7=9C=9F=E5=AE=9E=E3=80=81?= =?UTF-8?q?=E5=8F=AF=E8=BF=BD=E6=BA=AF=E7=9A=84=20issue/PR=20=E7=BC=96?= =?UTF-8?q?=E5=8F=B7=E4=B8=8D=E5=B1=9E=E4=BA=8E=E7=A6=81=E6=AD=A2=E4=B9=8B?= =?UTF-8?q?=E5=88=97?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 上一版把 "issue #123" 和 "finding 5" 这类一次性审计编号混为一谈， 一并禁止了。两者性质不同：审计编号脱离当次审计对话后无处可查， 而真实的、外部可解析的 issue/PR 编号（例如"这条回归测试是因为 #1234 这个真实 bug 而加"）恰恰是注释该有的内容——它让未来的维护者 能打开 issue 追溯完整背景，这是对理解/审查/维护有真实价值的信息， 不是噪音。 改用同一个判定标准："这条引用脱离当次对话后，对读者是否还有意义"： 外部 issue/PR 编号通常能通过，只在对话内部有意义的审计轮次编号 永远不能。无论哪种情况，注释本身仍必须先用文字说明要保护的不变量， 编号只是补充，不能替代这句说明。 Co-Authored-By: Claude Sonnet 5 --- AGENTS.md | 2 +- docs/develop.md | 17 ++++++++++++----- 2 files changed, 13 insertions(+), 6 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 6541b128c..1bf7fe94e 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -45,7 +45,7 @@ These are non-negotiable and apply to every change, regardless of what `docs/dev - **Direct replacement over adapter sandwiches.** When swapping a backend/library, replace in place — no `interface Foo + LegacyImpl + NewImpl` unless both must coexist at runtime. - **Scope discipline — stay in your lane.** Bug fix ≠ cleanup PR. Touch only the files the task requires; leave unrelated files untouched (不要动和任务不相干的文件). Don't add helpers, abstractions, validation, or backwards-compat shims you don't need today. Three similar lines beats a premature abstraction. - **No dead code or `// removed` markers** — git remembers. Delete unused code outright. -- **Comments explain "why", not "what" — and never carry review/audit labels.** No `finding N`, issue numbers, or round labels in comments or test names; that traceability belongs in the commit message/PR description. Don't restate the next line, don't duplicate an existing JSDoc, and don't leave a comment behind describing code that moved or was replaced. See `docs/develop.md`'s Comment Discipline section. +- **Comments explain "why", not "what" — never ephemeral review labels, but real issue/PR references are welcome.** No `finding N` / round labels in comments or test names (nobody outside that conversation can resolve them); a permanent, externally-resolvable issue or PR number is fine and often useful (e.g. a regression test's "why" is genuinely a tracked bug). Don't restate the next line, don't duplicate an existing JSDoc, and don't leave a comment behind describing code that moved or was replaced. See `docs/develop.md`'s Comment Discipline section. ## Architecture diff --git a/docs/develop.md b/docs/develop.md index 08a2deafc..d6acd4f0e 100644 --- a/docs/develop.md +++ b/docs/develop.md @@ -57,11 +57,18 @@ A comment earns its place by telling the reader something the code cannot: an in workaround for a specific constraint, or a reason something looks wrong but isn't. Before adding or keeping a comment, ask whether deleting it would cost a future reader anything — if not, delete it. -- **No internal tracking labels.** Never write review-round or audit identifiers into comments or test names — - e.g. `finding 5`, `issue #123`, `round 2 fix`, `【finding N 回归】`. These numbers are meaningless outside the - conversation that produced them and read as noise once that context is gone. If a fix needs traceability, - that belongs in the commit message or PR description, not in source code; the comment itself should just - state the invariant being protected (e.g. `确认读失败不代表写入未落盘，只是无法证实` rather than `见 finding 2`). +- **Ephemeral review labels never; permanent issue/PR references when they aid understanding.** Never write + review-round or audit identifiers that only made sense inside one throwaway conversation — e.g. `finding 5`, + `round 2 fix`, `【finding N 回归】`. A future reader has no way to look these up once that conversation is gone, + so they read as pure noise (see the invariant example below: state the "why" directly instead of pointing at + a number nobody can resolve). A reference to a real, permanent, externally-resolvable **issue or PR number** + is different and often exactly what a comment should do — e.g. `// regression test for #1234: 附件在会话删除 + 重建后被误删` on a test added because of a real tracked bug. That reference lets a future maintainer open the + tracker and read the full history, which is real value for understanding/review/maintenance, not noise. The + test is the same either way: would this reference still mean something, and help the reader, with no memory + of the conversation that added it? An issue number usually passes that test; a private review-round label + never does. Either way, still state the invariant/behavior itself in words + (e.g. `确认读失败不代表写入未落盘，只是无法证实`) — the reference supplements that sentence, it doesn't replace it. - **Don't restate the next line.** A comment placed right above code must add information the code doesn't already convey — never narrate what a reader can already see, like `// 继续循环` above `continue;` or `// send done event` above `sendEvent({ type: "done" })`. If the comment would read the same after deleting From 071c3373beb62111a98056846d90a0759fca28ee Mon Sep 17 00:00:00 2001 From: cyfung1031 <44498510+cyfung1031@users.noreply.github.com> Date: Sat, 18 Jul 2026 01:33:06 +0900 Subject: [PATCH 3/3] =?UTF-8?q?=F0=9F=93=84=20=E7=B2=BE=E7=AE=80=E6=B3=A8?= =?UTF-8?q?=E9=87=8A=E8=A7=84=E8=8C=83=E6=96=87=E6=A1=88=EF=BC=8C=E9=99=8D?= =?UTF-8?q?=E4=BD=8E=E5=B8=B8=E9=A9=BB=E6=96=87=E6=A1=A3=20token=20?= =?UTF-8?q?=E5=8D=A0=E7=94=A8?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit AGENTS.md 的规则条目内容不变但压缩表达，减少每次加载 AGENTS.md 都要 承担的固定 token 成本；docs/develop.md 对应小节同步精简，并统一列表 标点与项目符号风格（原有 * 与空行分隔与文件其余列表风格不一致）。 Co-Authored-By: Claude Sonnet 5 --- AGENTS.md | 2 +- docs/develop.md | 33 ++++++--------------------------- 2 files changed, 7 insertions(+), 28 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 1bf7fe94e..718cca9bd 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -45,7 +45,7 @@ These are non-negotiable and apply to every change, regardless of what `docs/dev - **Direct replacement over adapter sandwiches.** When swapping a backend/library, replace in place — no `interface Foo + LegacyImpl + NewImpl` unless both must coexist at runtime. - **Scope discipline — stay in your lane.** Bug fix ≠ cleanup PR. Touch only the files the task requires; leave unrelated files untouched (不要动和任务不相干的文件). Don't add helpers, abstractions, validation, or backwards-compat shims you don't need today. Three similar lines beats a premature abstraction. - **No dead code or `// removed` markers** — git remembers. Delete unused code outright. -- **Comments explain "why", not "what" — never ephemeral review labels, but real issue/PR references are welcome.** No `finding N` / round labels in comments or test names (nobody outside that conversation can resolve them); a permanent, externally-resolvable issue or PR number is fine and often useful (e.g. a regression test's "why" is genuinely a tracked bug). Don't restate the next line, don't duplicate an existing JSDoc, and don't leave a comment behind describing code that moved or was replaced. See `docs/develop.md`'s Comment Discipline section. +- **Comments explain "why", not "what".** Do not use ephemeral review labels such as `finding N` or review-round identifiers in comments or test names. Permanent issue or PR references are allowed when useful, but must supplement—not replace—the explanation. Do not restate code, duplicate enclosing documentation, or leave stale comments after code changes. See [`docs/develop.md`](docs/develop.md#comment-discipline) for the full policy. ## Architecture diff --git a/docs/develop.md b/docs/develop.md index d6acd4f0e..6892bb82d 100644 --- a/docs/develop.md +++ b/docs/develop.md @@ -53,33 +53,12 @@ Use strict TypeScript, React JSX runtime, 2-space indentation, semicolons, doubl ### Comment Discipline -A comment earns its place by telling the reader something the code cannot: an invariant, a race condition, a -workaround for a specific constraint, or a reason something looks wrong but isn't. Before adding or keeping a -comment, ask whether deleting it would cost a future reader anything — if not, delete it. - -- **Ephemeral review labels never; permanent issue/PR references when they aid understanding.** Never write - review-round or audit identifiers that only made sense inside one throwaway conversation — e.g. `finding 5`, - `round 2 fix`, `【finding N 回归】`. A future reader has no way to look these up once that conversation is gone, - so they read as pure noise (see the invariant example below: state the "why" directly instead of pointing at - a number nobody can resolve). A reference to a real, permanent, externally-resolvable **issue or PR number** - is different and often exactly what a comment should do — e.g. `// regression test for #1234: 附件在会话删除 - 重建后被误删` on a test added because of a real tracked bug. That reference lets a future maintainer open the - tracker and read the full history, which is real value for understanding/review/maintenance, not noise. The - test is the same either way: would this reference still mean something, and help the reader, with no memory - of the conversation that added it? An issue number usually passes that test; a private review-round label - never does. Either way, still state the invariant/behavior itself in words - (e.g. `确认读失败不代表写入未落盘，只是无法证实`) — the reference supplements that sentence, it doesn't replace it. -- **Don't restate the next line.** A comment placed right above code must add information the code doesn't - already convey — never narrate what a reader can already see, like `// 继续循环` above `continue;` or - `// send done event` above `sendEvent({ type: "done" })`. If the comment would read the same after deleting - the code below it, it isn't explaining anything. -- **Don't duplicate the enclosing doc comment.** If a function or class already has a JSDoc explaining a - behavior, don't repeat the same explanation as an inline comment inside its body — state each fact once, in - the place that owns it, and let the rest of the code speak for itself. -- **Keep comments attached to what they describe.** When you move, replace, or reorder code, move or delete the - comments that described it. A comment that still describes logic that used to be there, but no longer sits - next to what actually runs now, is more misleading than no comment at all — verify this explicitly when a - diff moves code around, not just when it adds new code. +A comment must tell the reader something the code cannot: an invariant, a race condition, a workaround for a specific constraint, or why something looks wrong but is correct. If deleting it would cost a future reader nothing, delete it. + +- **No ephemeral review labels; permanent issue/PR references are allowed when useful.** Never write review-round or audit identifiers that only made sense inside a now-gone conversation, such as `finding 5`, `round 2 fix`, or `【finding N 回归】`. A permanent issue or PR reference that is accessible to the intended maintainers can be useful, for example: `// regression test for #1234: 附件在会话删除重建后被误删`. Apply the same test to every reference: will it still help a future reader who has no memory of the conversation that added it? A relevant, accessible issue or PR usually passes; a private review label never does. In all cases, state the invariant or behavior in words first, such as `确认读失败不代表写入未落盘，只是无法证实`. The reference supplements the explanation; it does not replace it. +- **Do not restate the next line.** A comment above code must add information the code does not already convey. Do not write `// 继续循环` above `continue;` or `// send done event` above `sendEvent({ type: "done" })`. If the comment adds no meaning beyond the code below it, delete it. +- **Do not duplicate enclosing documentation.** If a function, class, or module doc comment already explains a behavior, do not repeat the same fact inside the implementation. State each fact once, in the place that owns it. +- **Keep comments attached to the code they describe.** When code is moved, replaced, reordered, or deleted, move, update, or delete its comments as well. A comment that no longer describes what actually runs is worse than no comment. Check this explicitly whenever a diff changes existing code, not only when it adds new code. ## UI