ln-610-code-comments-auditor

**路径：**文件路径（shared/、references/、../ln-*）均相对于技能仓库根目录。如果当前工作目录（CWD）中找不到，请定位此 SKILL.md 目录，并向上一级找到仓库根目录。

代码注释审查器

审查代码注释和文档字符串的质量。适用于任何技术栈。

目的

• 验证注释是否解释原因（WHY），而非显而易见的内容（WHAT）
• 检查注释密度（15-20% 的比例）
• 检测禁止内容（日期、作者姓名、历史记录）
• 验证文档字符串是否与函数签名一致
• 确保注释符合当前代码状态
• 识别遗留注释和注释掉的代码

调用方式

• **直接调用：**用户调用此工具进行代码注释质量审查
• **管线调用：**由 ln-100-documents-pipeline 调用（Phase 5，条件是 auditComments=true）

工作流

1. **扫描：**查找所有源文件（自动检测技术栈）
2. **提取：**解析行内注释和文档字符串/JSDoc
3. **审查：**执行 6 类检查（见下文“审查类别”）
4. **评分：**按每个类别计算 X/10 分
5. **上下文验证：**对检查结果进行后置过滤（见下文）
6. **报告：**输出检查结果和建议措施

审查类别

#	类别	检查内容
1	解释 WHY，而非 WHAT	注释说明理由，而非显而易见的代码行为；不重复描述代码
2	密度（15-20%）	注释与代码的比例在目标范围内；不过度或注释不足
3	无禁止内容	不含日期/作者；无历史记录；注释中无代码示例
4	文档字符串质量	与函数签名一致；记录参数；返回类型准确
5	时效性	注释与代码行为一致；无过时引用；示例可运行
6	清理遗留内容	TODO 均包含上下文；无注释掉的代码；无已弃用说明

上下文验证（后置过滤）

**必须阅读：**加载 shared/references/context_validation.md

应用规则 1 和注释专用的行内过滤器：

FOR EACH finding WHERE severity IN (HIGH, MEDIUM):
  # Rule 1: ADR/Planned Override
  IF finding matches ADR → advisory "[Planned: ADR-XXX]"

  # Comment-specific: Per-category density targets
  IF Cat 2 (Density) finding:
    Classify file by path:
    - test/ or tests/           → target density 2-10%
    - infra/ or config/ or ci/  → target density 5-15%
    - business/domain/services  → target density 15-25%
    Recalculate with per-category target instead of fixed 15-20%.
    If >50% comments are docstrings → calculate inline density separately.

  # Comment-specific: Complexity context for WHY-not-WHAT
  IF Cat 1 (WHY not WHAT) finding:
    - If file McCabe complexity > 15 → WHAT comments acceptable (complex logic)
    - If file in domain/ or business/ → explanatory comments OK (domain knowledge)

Downgraded findings → separate "Advisory" note in report.

输出格式

## Code Comments Audit Report - [DATE]

### Compliance Score

| Category | Score | Issues |
|----------|-------|--------|
| WHY not WHAT | X/10 | N obvious comments |
| Density (15-20%) | X/10 | X% actual (target: 15-20%) |
| No Forbidden Content | X/10 | N forbidden items |
| Docstrings Quality | X/10 | N mismatches |
| Actuality | X/10 | N stale comments |
| Legacy Cleanup | X/10 | N legacy items |
| **Overall** | **X/10** | |

### Critical Findings

- [ ] **[Category]** `path/file:line` - Issue description. **Action:** Fix suggestion.

### Recommended Actions

| Priority | Action | Location | Category |
|----------|--------|----------|----------|
| High | Remove author name | src/X:45 | Forbidden |
| Medium | Update stale docstring | lib/Y:120 | Actuality |

评分算法

**必须阅读：**加载 shared/references/audit_scoring.md，了解统一评分公式。

严重程度映射：

问题类型	严重程度
注释中的作者姓名、日期	CRITICAL
注释掉的代码块	HIGH
过时或陈旧的注释	HIGH
说明显而易见的 WHAT 的注释	MEDIUM
密度偏差 >5%	MEDIUM
轻微密度偏差	LOW

参考文件

• 注释规则和模式：references/comments_rules.md

完成定义

• 已扫描所有源文件（自动检测技术栈）
• 已提取并解析行内注释和文档字符串/JSDoc
• 已审查全部 6 个类别，并分别给出 X/10 分（WHY-not-WHAT、密度、禁止内容、文档字符串、时效性、遗留内容）
• 已计算注释与代码的密度比例，并与 15-20% 的目标范围进行比较
• 已列出关键发现，包含文件:行号、类别和修复建议
• 已生成建议措施表，包含优先级、措施、位置和类别

重要说明

• **修复代码，而非规则：**切勿修改规则文件（_rules.md、_standards.md）来规避问题。始终修复代码。
• **代码为准：**注释与代码矛盾时，标记注释以便更新
• **WHY > WHAT：**应删除解释显而易见行为的注释
• **任务 ID 可以保留：**注释中的任务/Story ID 有助于追踪代码
• **通用：**适用于任何语言；自动检测注释语法
• **依据：**Claude Code comment-analyzer Agent 模式

---

**版本：**3.0.0 **最后更新：**2025-12-23