Sim 的注释治理方法you-might-not-need-a-comment 技能与 TSDoc 注释体系【免费下载链接】simSim is the collaborative workspace to build, deploy, and monitor AI agents and workflows. Used by 100,000 builders.项目地址: https://gitcode.com/GitHub_Trending/sim16/sim在大型 TypeScript 代码库中注释腐化是比代码腐化更隐蔽的技术债复述代码的行内注释、区块分隔横幅、注释掉的死代码会持续消耗读者的注意力。Sim 仓库在.agents/skills/目录下内置了一组面向 AI Agent 的反模式清理技能其中you-might-not-need-a-comment专门负责分析并清除冗余或自我解释的行内注释把真正的文档提升为 TSDoc。本文基于该技能的 SKILL.md结合 AGENTS.md 中的全局注释规范与scripts/下多个 CI 检查脚本的源码实现完整拆解这套注释即信息量的治理体系读完后你将掌握一条可落地的注释判定规则、七类反模式的识别清单以及为什么某些看似普通的//注释在 Sim 中是承重结构、绝不能触碰。技能定位与调用方式you-might-not-need-a-comment是 Sim 仓库.agents/skills/目录下的一个 Agent 技能采用标准的技能文件结构YAML frontmatter 声明name、description与argument-hint正文则是可直接执行的作业指令。其 SKILL.md 的关键元数据如下--- name: you-might-not-need-a-comment description: Analyze and fix redundant or self-explanatory inline comments — remove noise, promote genuine documentation to TSDoc argument-hint: [scope] [fixtrue|false] ---技能接受两个参数通过正文中的$ARGUMENTS占位符注入调用时传入的用户实参scope分析范围默认为你当前的改动。可选示例包括diff to main、PR #123、src/components/、whole codebase——即从单次 PR 到整个代码库都可以作为审计单位fix是否应用修复默认true置为false时技能只提出修改建议而不落地。这一命名与参数模式并非孤例。同一目录下存在一组结构完全一致的姊妹技能——you-might-not-need-a-memo、you-might-not-need-a-callback、you-might-not-need-an-effect、you-might-not-need-state、you-might-not-need-url-state——全部使用[scope] [fixtrue|false]的参数约定。从源码结构看Sim 把反模式清理沉淀为了一族可复用的 Agent 工作流每个技能聚焦一类具体反模式用统一的分析范围 是否修复接口驱动。核心规则注释必须增加代码无法自表达的信息技能的第一条、也是唯一真正重要的规则原文用 The one rule that matters 强调可以概括为代码表达what做什么和how怎么做注释只有在解释why——非显而易见的约束、绕行方案、决策背景、陷阱——时才配拥有自己的位置。如果删掉一条注释后一个有能力的读者无法从代码中在几秒内恢复这条信息才值得保留。这条规则把注释的价值判定从是否有信息收紧为是否有代码表达不出的信息。据此以下注释一律不合格复述标识符语义的命名已经说清楚了复述语句动作的counter上方写// increment counter用散文重复类型签名的// takes a string and returns a number。与之配套的是 Sim 仓库的全局约定AGENTS.md 的 Global Standards 一節明确写着原文第 10 行Comments: Use TSDoc for documentation. Noseparators. No non-TSDoc comments即文档性内容一律使用 TSDoc/** ... */块挂在声明上禁止这类分隔横幅除此之外不应存在任何非 TSDoc 注释。技能文档把这条约定表述为真正的文档应该以/** ... */块的形式挂在声明上任何存活的行内//注释必须是真正的why且保持简短。七类要检测的注释反模式技能把检测目标枚举为七类反模式每一类都给出了可操作的判别标准复述代码Restates the code如counter上方的// increment counter、return result上方的// return the result、// loop over items。判定删除后信息量为零。用标识符叙述显而易见之事函数叫fetchUserById注释写// fetches a user by id——标识符已经把话说完了。区块分隔/横幅注释Section-divider / banner comments// Helpers 、// --- state ---、// #region之类。这与仓库 Noseparators 的约定直接冲突技能的立场是代码的结构就是结构本身分隔注释应当删除。注释掉的死代码历史遗留的 commented-out code。原则是git 就是历史——需要旧代码时从版本历史找回而不是留在源文件里腐烂。散文式重复类型/参数签名签名已经写明类型契约时再用// takes a string and returns a number复述一遍属于冗余。这类信息应通过类型系统或 TSDoc 的param/returns表达。变更历史/署名噪音Changelog / attribution noise// added by X、长期陈旧的// TODO(2021): ...、// fix for bug等。默认删除除非它编码了仍然有效、可操作的约束。以松散//块书写的真正文档这是对导出函数/类型/常量的真实用途说明但被写成一堆堆叠的//行而不是 TSDoc。处理方式是转换而非删除——把它提升为声明上的/** ... */TSDoc 块。第 7 类值得注意它说明该技能的目标不是无注释化而是注释归位。噪声被删除真文档被规范化为 TSDoc最终仓库里存活的自由注释只剩why。不能动的模式承重注释与工具指令技能明确列出了看起来像反模式、实际上是正确代码的白名单要求不得标记解释非显而易见 why 的//注释上游 bug 的绕行方案、执行顺序约束、性能原因、代码无法自文档化的规格边界原文示例// first-match wins — matches the old find() semantics声明上已有的 TSDoc/** ... */块保留不动仅在冗长时收紧措辞脚本 grep 的kebab-tag: 原因注解// boundary-raw-fetch:、// double-cast-allowed:、// boundary-raw-json:、// untyped-response:、// migration-safe:、// rq-lint-allow:、// client-boundary-allow:等以及块注释形式的变体例如图标路径上的/** svg-path-precision-exception: ... */指令——原文用 load-bearing, never touch them承重结构绝不触碰来强调工具指令// biome-ignore、// eslint-disable、// ts-expect-error等指向真实未完成工作的// TODO/// FIXME。其中一类在 Sim 中尤为关键边界注解并非文档习惯而是CI 契约的一部分。scripts/下的多个检查脚本会逐行 grep 这些前缀缺失即报错check-api-validation-contracts.ts 定义了RAW_FETCH_ANNOTATION_PREFIX // boundary-raw-fetch:、DOUBLE_CAST_ANNOTATION_PREFIX // double-cast-allowed:、RAW_JSON_ANNOTATION_PREFIX // boundary-raw-json:、UNTYPED_RESPONSE_ANNOTATION_PREFIX // untyped-response:等前缀常量并检查相应位置是否携带// tag: reason注解、原因是否为空check-client-boundary-imports.ts 把// client-boundary-allow: reason声明为客户端边界导入检查的逃逸口escape hatch要求写在违规行的正上方check-migrations-safety.ts 要求对危险迁移操作在上一行写-- migration-safe: reasonSQL 文件里的行注释形态且原因不能为空否则输出 -- migration-safe:annotation has no reason. Give it a real justification. 的报错check-react-query-patterns.ts 以// rq-lint-allow: reason作为 React Query 模式检查的豁免注解并限定了注解必须出现在目标行上方三行内。仓库代码中这类注解的使用方式可以印证其原因必填的设计例如 resume-execution.ts 中的两处// double-cast-allowed: contract models pause points as z.record; the resume UI uses the richer PausedExecutionDetail interface注解格式是严格的tag: reason两段式tag 标识豁免的检查项冒号后的 reason 记录为什么必须这样写。这也正是该技能把白名单注释标注为绝不触碰的原因——删掉它们bun run check:api-validation之类的 CI 检查会立刻失败而不是仅仅丢失一段可读性信息。Bias这是一次减法 pass技能用一节 Bias 明确了修复时的取舍倾向值得逐条引用优先删除其次改写deletion over rewriting代码已经清晰时无注释优于有注释no comment over a comment注释确属真文档时优先提升为简短的 TSDoc而不是保留松散//块本次 pass 绝不新增注释——this is a reduction pass这是一次缩减 pass新增文档应走别的流程对某条注释是否编码了真实why拿不准时保留它。最后一条是工程上的重要护栏误删一条承载隐性知识的注释例如某个顺序约束造成的事故远比多留一条冗余注释的成本高。技能的默认方向是激进删除但在不确定处偏保守两者结合把误伤风险压到最低。执行步骤与实战用法技能正文的 Steps 部分只有两步逻辑上对应一个分析 → 处置的两段式流程在指定 scope 内分析上述反模式清单若fixtrue默认应用修复若fixfalse只提出修复建议而不改动。结合参数约定典型的调用形态是you-might-not-need-a-comment—— 分析当前改动默认 scope直接应用清理you-might-not-need-a-comment diff to main fixfalse—— 只读审计分支相对 main 的全部改动输出建议清单适合在 PR 评审前人工复核you-might-not-need-a-comment src/components/—— 对某个目录做一次历史注释债清偿。由于其白名单显式覆盖了scripts/各检查脚本 grep 的全部注解前缀这套流程可以安全地用于whole codebase级别的存量清理噪声注释被删除、真文档被提升为 TSDoc、承重注解与工具指令原样保留最终收敛到 AGENTS.md 所规定的稳态——TSDoc 承载文档行内注释只承载 why。小结注释治理作为仓库级契约you-might-not-need-a-comment表面上是一条注释清理规则实际上它是 Sim 仓库三层体系的交汇点规范层AGENTS.md 的 TSDoc only, no, no non-TSDoc comments 给出稳态定义执行层技能文件定义了 Agent 可重复执行的检测清单七类反模式、白名单承重注解与工具指令与取舍 bias减法 pass、拿不准就保留校验层check-api-validation-contracts.ts、check-client-boundary-imports.ts、check-migrations-safety.ts、check-react-query-patterns.ts 等脚本在 CI 中 grep 注解前缀使注释本身成为可机器验证的契约。对维护者的实践启示是清理注释时先区分信息冗余与信息载体——前者按七类反模式删除或提升为 TSDoc后者脚本 grep 的kebab-tag: reason注解、lint 指令、指向未完成工作的 TODO一律保留并且把注释清理严格限定为减法操作不在同一 pass 中新增注释。【免费下载链接】simSim is the collaborative workspace to build, deploy, and monitor AI agents and workflows. Used by 100,000 builders.项目地址: https://gitcode.com/GitHub_Trending/sim16/sim创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考