通用代码注释规范

在定义附近主动补充准确、简明的注释，让读者直接理解职责、参数、结果和必要约束。先从类型、调用点、测试和已确认契约取得事实；用足以说清作用的最短文字表达，不复述语法或猜测业务。

工作范围与协作边界

• 适用于所有编程语言，沿用项目和语言原生的文档注释、docstring 或实现注释格式。
• 默认处理本轮新增或实质修改的声明，以及保持注释准确所必需的直接关联代码。用户明确要求补齐指定文件或整个仓库时，再按该范围执行。
• 无论独立使用还是由其他 Skill 调用，都只新增、修改或删除注释及文档字符串；不改签名、类型声明、逻辑、命名或代码结构，不提取函数或调整依赖与配置。
• 可由 $writing-vue-components、$organizing-frontend-components、$integrating-frontend-apis 等实现类 Skill 在代码生成后、验证前调用。发现实现或结构问题时反馈调用方处理；注释完成后交还控制权。

1. 建立注释契约

读取仓库指令、目标文件、相邻代码及已有文档、格式化和 lint 配置，确定：

• 目标语言、框架、现有注释语言、文档语法、标签顺序与工具约束；
• 本轮涉及哪些声明、参数、变量、数据契约和复杂流程；
• 用途、结果、单位、范围、缺省值、可空性、副作用和异常分别有什么证据。

证据优先级为：已确认契约或类型定义、可执行测试、真实调用点、同模块稳定约定。不得从名称或相似页面猜测字段含义、单位、接口行为或异常条件。若事实仍未知，只能在代码本身已经是显式 Mock/TODO 时标注“契约待确认”；否则先报告缺失事实，不写伪精确注释。

完成标准：目标范围、注释格式与必须覆盖的声明已确定；说明有可定位的事实依据，缺失事实已列出。

2. 主动覆盖定义处的注释

在本轮范围内按下表主动生成、补齐或同步注释。必须项即使名称清楚，也用简短说明交代职责或业务含义；按需项在存在非显然语义、约束或维护风险时注释。

函数参数集中写在函数文档块、docstring 或语言对应的文档位置，不为加注释拆改参数列表。变量、字段和类型优先在声明上方注释；流程注释放在所解释代码块之前。

完成标准：必须项已逐个覆盖；按需项保留了必要说明；注释可在所属定义或流程附近直接定位。

3. 简明表达并同步旧注释

• 默认用一句话说明职责；存在前置条件、单位、范围、边界、副作用或异常时，再补充必要信息，不设固定字数。
• 每个参数和泛型参数都说明含义；有业务约束的解构字段逐项可定位，已有模型字段文档可直接引用。
• 说明实际返回结果、异步完成后的值或生成器产出。无实际返回结果时，省略单纯的“无返回值”；构造函数不虚构返回值。异步完成时机影响调用方时，说明完成条件。
• 类型声明是类型的单一事实来源。TypeScript 等已有明确声明的代码不在注释中重复类型；JavaScript 等需要文档承载类型时，用项目支持的语法记录已确认类型。
• 本轮行为、签名、字段语义、默认值、来源、副作用或流程约束变化时，同步相关旧注释。原注释仍准确时保持不变；删除失真说明、被注释掉的旧实现及已失效的 TODO。

目标涉及 JavaScript、TypeScript、Vue 或 React 时，读取 注释写法与前端细则 的对应部分；其他语言或特殊文件存在格式疑问时，读取其中的“通用写法与格式边界”。

完成标准：文字简短且足以解释作用；参数与结果准确；没有重复声明类型、猜测事实或遗留过时说明。

4. 就地解释复杂流程

按有意义的阶段说明难读逻辑，解释每步目的、顺序依赖及必要原因：

• 有顺序依赖的多阶段流程，可使用 1. …、2. … 等编号；编号对应实际阶段。
• 独立分支、兼容限制、竞态规避、回滚条件、不变量和性能取舍，用简短块前说明。
• 不按代码行数判断复杂度，不把每次赋值、判断或循环翻译成一个步骤。
• 即使逻辑难读，也在现有结构的合法注释位置说明；结构改进交给其他 Skill，不以补注释为由重构。

完成标准：复杂点有必要解释；步骤与实际执行顺序一致；代码结构和行为保持原样。

5. 验证注释与变更边界

使用项目已有的注释或文档校验、formatter 检查、lint、typecheck 与相关测试，按项目能力执行。已有的 JSDoc、TSDoc 或文档生成检查必须纳入。自动格式化或修复可能改动非注释内容时，使用检查模式；只修复注释内的问题，代码或配置问题反馈调用方，不添加依赖。

最后逐项复查：

1. 覆盖表中的必须项是否完整，普通临时变量与简单回调是否避免了噪声；
2. 参数、泛型、返回结果和字段含义是否与当前代码或契约一致；
3. 是否仅在需要文档承载类型时写类型，且没有重复声明已有类型；
4. 复杂流程说明是否准确，旧注释是否已同步；
5. diff 是否只有注释或文档字符串变更，没有修改实现、签名、结构、依赖或配置；
6. 适用检查是否通过，未运行项及范围外问题是否说明原因。

完成标准：注释覆盖与准确性检查通过，变更边界经过 diff 复核；可在注释内解决的问题已修复并重新验证。

需要追溯前端规则依据时，再读取 前端标准调研记录。