yy-comment

name	yy-comment
description	为代码添加注释。当用户要求"加注释"、"添加文档注释"、"补充注释"、 "写 docstring"、"加 Javadoc"、"给模板加注释"、"给样式加注释"时触发。 不适用于：实现新功能、修改代码逻辑、删除代码，或为每行代码强制加注释。

yy-comment

描述

为代码添加注释的通用技能，支持多种编程语言和标记语言。遵循跨语言通用规则，并按语言加载特定注释规范；语言特定规则与通用规则冲突时，以语言特定规则优先。

使用场景

当用户表达以下意图时触发：

• 为代码文件或指定函数/类/方法添加注释
• 补充文档注释（docstring、Javadoc、KDoc、PHPDoc 等）
• 为代码逻辑添加解释性注释
• 为 HTML/Vue 模板添加结构注释
• 为 CSS/SCSS/LESS 添加样式注释

不应触发：

• 用户要求实现新功能、修改代码逻辑或删除代码
• 文件已有完整注释且用户未明确要求补充
• 用户要求为每行代码都加注释（过度注释）

规则层级

通用规则定义在 resources/common.md，语言特定规则定义在 resources/{语言}.md。

当特定语言的规则与通用规则冲突时，以特定语言的规则优先。

支持的语言

• Python → resources/python.md
• Java → resources/java.md
• C/C++ → resources/c-cpp.md
• C# → resources/csharp.md
• Go → resources/go.md
• Rust → resources/rust.md
• Swift → resources/swift.md
• Kotlin → resources/kotlin.md
• Ruby → resources/ruby.md
• PHP → resources/php.md
• Shell/Bash → resources/shell.md
• SQL → resources/sql.md
• JavaScript/TypeScript → resources/js-ts.md
• HTML/CSS → resources/html-css.md

遇到未列出语言的文件时，使用通用规则和该语言的注释语法常识处理。

指令

步骤 1. 确定范围

决策分支：

• 用户指定文件：读取目标文件
• 用户指定函数/类/方法：定位目标
• 用户未指定：通过 git diff 查找变更文件，过滤为支持类型的文件

对于超过 500 行的文件，先告知用户文件规模，确认后再执行。

步骤 2. 识别语言并加载规则

• 根据文件扩展名识别语言
• 加载 resources/common.md 中的通用规则
• 加载 resources/{语言}.md 中的语言特定规则（如存在）
• 当特定语言的规则与通用规则冲突时，以语言特定规则优先

步骤 3. 添加注释

按通用规则和语言特定规则执行：

• 为函数/类/方法/接口添加文档注释
• 为重要模块级常量和类型定义添加注释
• 在关键逻辑步骤前添加内部注释（解释"为什么"）
• 跳过自解释代码和显而易见的逻辑
• 已有注释内容正确则保留，仅在缺失处补充；内容过时则修正

步骤 4. 输出结果

修改目标文件后，报告：

• 添加了注释的函数/类/接口/模块列表
• 各类注释数量：文档注释 N 处、内部逻辑注释 N 处

安全边界

• 不修改代码逻辑、不删除已有代码
• 不删除已有的正确注释
• 不为自解释代码强制添加注释
• 不修改自动生成的代码文件（如构建产物、编译输出）

---

相关资源

• resources/common.md - 跨语言通用注释规则（判断标准、避免模式、标注约定）
• resources/{语言}.md - 各语言特有的注释语法和规范