ln-600-docs-auditor

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

文档审计器

审计项目文档质量。适用于任何技术栈。

目的

• 主动压缩 - 找出所有可以缩减篇幅且不损失价值的地方
• 消除无意义、重复和冗长的内容
• 将散文转换为结构化格式（表格、列表）
• 验证文档层级，以 CLAUDE.md 为根
• 检测重复内容并贯彻单一事实来源原则
• 确保文档与当前代码状态一致
• 语义验证 - 委派给 ln-601，验证内容是否符合 SCOPE 和代码库实际情况

调用方式

• **直接调用：**用户发起文档质量审查
• **流水线调用：**由 ln-100-documents-pipeline 调用（第 5 阶段，条件为 auditDocs=true）

工作流

1. **扫描：查找项目中的所有 .md 文件（CLAUDE.md、README.md、docs/）
2. **构建树：**根据 CLAUDE.md 的外链构建层级结构
3. **审计类别 1-7：**运行结构检查（见下方“审计类别”）
4. **语义审计（类别 8）：**将每份项目文档委派给 ln-601-semantic-content-auditor 审查
5. **评分：**计算各类别的 X/10 分（包括 ln-601 提供的语义分数）
6. **上下文验证：**对审查结果进行后置筛选（见下文）
7. **报告：**输出审查结果和建议操作

第 4 阶段：委派语义审计

对每份项目文档（不包括 tasks/、reference/、presentation/）：

FOR doc IN [CLAUDE.md, docs/README.md, docs/project/*.md]:
    result = DELEGATE ln-601-semantic-content-auditor {
        doc_path: doc,
        project_root: project_root,
        tech_stack: detected_stack
    }
    semantic_findings.append(result.findings)
    semantic_scores[doc] = result.scores

**目标文档：**CLAUDE.md、docs/README.md、docs/documentation_standards.md、docs/principles.md、docs/project/*.md

**排除项：**docs/tasks/、docs/reference/、docs/presentation/、tests/

审计类别

#	类别	检查内容
1	层级与链接	CLAUDE.md 是根文档；所有文档均可通过链接访问；没有孤立文件；没有失效链接
2	单一事实来源	没有内容重复；重复内容已替换为指向来源的链接；归属清晰
3	主动压缩	消除冗长或重复内容；散文→表格；移除无意义信息；即使未超限也压缩文件；参见 size_limits.md
4	要求合规性	章节正确；符合篇幅限制；不含代码块（仅限表格/ASCII 图示/文本）；文档链接适用于相应技术栈
5	准确性（关键）	**根据代码验证事实：**路径存在、函数匹配、API 可用、配置有效；过时文档比没有文档更糟
6	清理旧内容	不含历史章节；没有“曾被更改”之类的说明；没有已弃用信息；仅描述当前状态
7	技术栈适配	链接/引用符合项目技术栈；.NET 项目中没有 Python 示例；官方文档对应正确平台
8	语义内容	**委派给 ln-601：**内容符合 SCOPE；服务于项目目标；描述与实际代码行为一致；架构/API 文档反映实际情况

上下文验证（后置筛选）

**必须阅读：**加载 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]"

  # Doc-specific: Compression context
  IF Cat 3 (Compression) finding:
    - Skip if path in references/ or templates/ (reference docs = naturally large)
    - Skip if filename contains architecture/design/api_spec
    - Skip if tables+lists > 50% of content (already structured, not verbose prose)

  # Doc-specific: Actuality severity calibration
  IF Cat 5 (Actuality) finding:
    - Path/function COMPLETELY missing → CRITICAL (broken docs)
    - Path exists but deprecated/renamed → HIGH (not CRITICAL)
    - Example code outdated but concept valid → MEDIUM

Downgraded findings → "Advisory Findings" section in report.

输出格式

## Documentation Audit Report - [DATE]

### Compliance Score

| Category | Score | Issues |
|----------|-------|--------|
| Hierarchy & Links | X/10 | N issues found |
| Single Source of Truth | X/10 | N duplications |
| Proactive Compression | X/10 | N compression opportunities |
| Requirements Compliance | X/10 | N violations |
| Actuality | X/10 | N mismatches with code |
| Legacy Cleanup | X/10 | N legacy items |
| Stack Adaptation | X/10 | N stack mismatches |
| Semantic Content | X/10 | N semantic issues (via ln-601) |
| **Overall** | **X/10** | |

### Critical Findings

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

### Recommended Actions

| Priority | Action | Location | Category |
|----------|--------|----------|----------|
| High | Remove duplicate section | docs/X.md | SSOT |
| Medium | Add link to CLAUDE.md | docs/Y.md | Hierarchy |

评分算法

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

严重性映射：

问题类型	严重性
内容过时（与代码不符）	严重
失效链接、孤立文档	高
语义不匹配（由 ln-601 发现）	高
内容重复	中
存在压缩空间	低

参考文件

• 篇幅限制和目标：references/size_limits.md
• 详细检查清单：references/audit_checklist.md

完成定义

• 扫描项目中的所有 .md 文件，并根据 CLAUDE.md 构建层级树
• 审核类别 1-7（结构），并分别给出 X/10 的评分
• 将类别 8（语义）委派给 ln-601，对每个目标文档进行审核；收集评分
• 计算总体合规评分（8 个类别的平均分）
• 列出关键发现，注明文件:行号、类别和修复建议
• 生成建议操作表，列出优先级、操作、位置和类别

关键注意事项

• 修复内容，而非规则： 切勿修改标准/规则文件（_standards.md、_rules.md、*_limits.md）来让违规内容通过。始终修复违规文件。
• 依据代码核实事实： 主动检查文档中提及的每个路径、函数名、API 和配置。运行命令。过时的文档会误导读者，比没有文档更糟。
• 始终精简： 大小限制是上限，不是目标。100 行的文件优于 300 行的文件。始终寻找精简机会。
• 无意义内容： 删除填充词、显而易见的陈述和过度解释。没有价值的内容就删掉。
• 文档中不写代码： 使用表格或 ASCII 图描述算法。代码应放在代码库中。
  • 禁止： 代码块、实现片段
  • 允许： 表格、ASCII 图、Mermaid、方法签名（1 行）
  • 不要贴代码，改为：“参见 官方文档”或“参见 src/file.cs:42”
• 格式优先级： 表格/ASCII 图 > 列表（仅用于枚举）> 文本（最后选择）
• 适配技术栈： 核实所有文档引用都与项目技术栈匹配。.NET 项目不得包含 Python 示例。检查官方文档链接是否指向正确平台（C# 应链接 Microsoft 文档，JS 应链接 MDN 等）。
• 代码才是真相： 文档与代码冲突时，始终更新文档。切勿为了符合文档而“修复”代码。
• 修复后重新核实 SSOT： 每次修改任何文档后，都要重新检查修复是否符合单一事实来源原则。如果内容存在于多个文件中，只保留在规范来源中，并将其他位置的内容替换为指向该来源的链接（例如，See [section](path#anchor)）。切勿内联重复内容，始终使用链接。规范来源层级：CLAUDE.md → docs/README.md → docs/project/.md → docs/reference/.md。
• 删除，不归档： 应移除旧内容，而非移入“archive”
• 不记录历史： 文档只描述当前状态；历史由 git 跟踪

---

版本： 4.0.0 最后更新： 2026-01-28