📄 补充注释规范：拒绝审计追溯标签、复述性与失效注释 - #1602
Merged
CodFrm merged 4 commits intoJul 20, 2026
Merged
Conversation
Codex/Claude 等 agent 在近期一次多轮代码审计中，把内部审计编号 （如 "finding 5"）写进了正式代码注释与测试用例名称，审计对话结束后 这些编号对读者毫无意义；同一批改动里还出现了纯复述下一行代码的注释、 与所在函数/类 JSDoc 重复的说明，以及代码搬走后未同步更新、继续描述 错误位置逻辑的过时注释。 在 docs/develop.md 的 Language Conventions 之后新增 Comment Discipline 小节，给出可执行的规则与反例；AGENTS.md 的 Engineering Principles 增补一条对应的非协商条款并链接过去，避免同一事实在两份 文档里重复维护。 Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
上一版把 "issue scriptscat#123" 和 "finding 5" 这类一次性审计编号混为一谈， 一并禁止了。两者性质不同：审计编号脱离当次审计对话后无处可查， 而真实的、外部可解析的 issue/PR 编号（例如"这条回归测试是因为 scriptscat#1234 这个真实 bug 而加"）恰恰是注释该有的内容——它让未来的维护者 能打开 issue 追溯完整背景，这是对理解/审查/维护有真实价值的信息， 不是噪音。 改用同一个判定标准："这条引用脱离当次对话后，对读者是否还有意义"： 外部 issue/PR 编号通常能通过，只在对话内部有意义的审计轮次编号 永远不能。无论哪种情况，注释本身仍必须先用文字说明要保护的不变量， 编号只是补充，不能替代这句说明。 Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Member
|
这个感觉属于develop的？agents.md 里面尽量只放高优先级的 |
Collaborator
Author
詳細放了在develop.md 這應該沒什麼問題吧 如同字面所言，agent 的comments 很喜歡寫what, 但我們需要它寫的是why |
Collaborator
Author
|
我看看能不能簡化一下agents 裡的寫法 |
Member
哦哦 我看岔了 没问题 |
AGENTS.md 的规则条目内容不变但压缩表达，减少每次加载 AGENTS.md 都要 承担的固定 token 成本；docs/develop.md 对应小节同步精简，并统一列表 标点与项目符号风格（原有 * 与空行分隔与文件其余列表风格不一致）。 Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Collaborator
Author
done: 071c337 |
cyfung1031
marked this pull request as draft
July 18, 2026 02:57
Collaborator
Author
cyfung1031
marked this pull request as ready for review
July 19, 2026 14:04
cyfung1031
added
documentation
1 of 3 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Checklist / 检查清单
背景
在 #1549 的一次多轮 AI 代码审计过程中，agent 把内部审计编号（如
finding 5）直接写进了正式代码注释与测试用例名称——审计对话结束后，这些编号脱离上下文，对未来读者毫无意义。同一批改动里还发现了另外三类相关问题：// 继续循环后面跟着continue;）。这些都已在 #1549 里手动清理，但
AGENTS.md/docs/develop.md里此前没有任何规则能提醒 agent（或人类贡献者）在源头上避免它们。本次改动
docs/develop.md：在Language Conventions之后新增Comment Discipline小节，给出四条可执行规则（拒绝审计追溯标签、不复述下一行、不重复 JSDoc、注释要跟代码一起搬家）及反例。AGENTS.md：在Engineering Principles里增补一条对应的非协商条款，并链接到docs/develop.md的新小节，避免同一事实在两份文档里重复维护（遵循docs/DOC-MAINTENANCE.md的"不要重复，交叉引用"约定）。纯文档改动，不涉及代码逻辑。
验证
pnpm exec prettier --check AGENTS.md docs/develop.md— 通过。docs/develop.md拥有实质规则，AGENTS.md仅做简述+链接。🤖 Generated with Claude Code