Back to Details

ln-600-docs-auditor

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Documentation Auditor

文档审计工具

Audit project documentation quality. Universal for any tech stack.
审计项目文档质量。适用于任何技术栈。

Purpose

目标

  • Proactively compress - find all opportunities to reduce size while preserving value
  • Eliminate meaningless, redundant, and verbose content
  • Convert prose to structured formats (tables, lists)
  • Verify documentation hierarchy with CLAUDE.md as root
  • Detect duplication and enforce Single Source of Truth
  • Ensure docs match current code state
  • Semantic verification - delegate to ln-601 to verify content matches SCOPE and codebase reality
  • 主动精简 - 寻找所有在保留价值的前提下缩减文档篇幅的机会
  • 移除无意义、重复和冗长的内容
  • 将散文式内容转换为结构化格式（表格、列表）
  • 验证以CLAUDE.md为根的文档层级结构
  • 检测重复内容并落实单一信息源（SSOT）原则
  • 确保文档与当前代码状态一致
  • 语义验证 - 委托ln-601验证内容是否符合SCOPE和代码库实际情况

Invocation

调用方式

  • Direct: User invokes for documentation quality review
  • Pipeline: Called by ln-100-documents-pipeline (Phase 5, if auditDocs=true)
  • 直接调用： 用户发起文档质量审查请求
  • 流水线调用： 由ln-100-documents-pipeline调用（第5阶段，当auditDocs=true时）

Workflow

工作流程

  1. Scan: Find all .md files in project (CLAUDE.md, README.md, docs/**)
  2. Build Tree: Construct hierarchy from CLAUDE.md outward links
  3. Audit Categories 1-7: Run structural checks (see Audit Categories below)
  4. Semantic Audit (Category 8): For each project document, delegate to ln-601-semantic-content-auditor
  5. Score: Calculate X/10 per category (including semantic scores from ln-601)
  6. Report: Output findings and recommended actions
  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. 生成报告： 输出问题发现和建议措施

Phase 4: Semantic Audit Delegation

第4阶段：语义审计委托

For each project document (excluding 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
Target documents: CLAUDE.md, docs/README.md, docs/documentation_standards.md, docs/principles.md, docs/project/*.md
Excluded: docs/tasks/, docs/reference/, docs/presentation/, tests/
对于每个项目文档（排除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/

Audit Categories

审计类别

#CategoryWhat to Check
1Hierarchy & LinksCLAUDE.md is root; all docs reachable via links; no orphaned files; no broken links
2Single Source of TruthNo content duplication; duplicates replaced with links to source; clear ownership
3Proactive CompressionEliminate verbose/redundant content; prose→tables; remove meaningless info; compress even under-limit files; see size_limits.md
4Requirements ComplianceCorrect sections; within size limits; no code blocks (tables/ASCII diagrams/text only); stack-appropriate doc links
5Actuality (CRITICAL)Verify facts against code: paths exist, functions match, APIs work, configs valid; outdated docs are worse than none
6Legacy CleanupNo history sections; no "was changed" notes; no deprecated info; current state only
7Stack AdaptationLinks/refs match project stack; no Python examples in .NET project; official docs for correct platform
8Semantic ContentDelegated to ln-601: Content matches SCOPE; serves project goals; descriptions match actual code behavior; architecture/API docs reflect reality
序号类别检查内容
1层级结构与链接CLAUDE.md为根文档；所有文档可通过链接访问；无孤立文件；无失效链接
2单一信息源（SSOT）无内容重复；重复内容替换为指向源的链接；明确内容归属
3主动精简移除冗长/重复内容；散文转表格；删除无意义信息；即使文件未超限制也要精简；详见size_limits.md
4合规性要求章节结构正确；符合篇幅限制；无代码块（仅允许表格/ASCII图/文本）；链接适配项目技术栈
5时效性（关键）对照代码验证事实： 路径存在、函数匹配、API可用、配置有效；过时文档不如没有文档
6遗留内容清理无历史章节；无“已修改”注释；无废弃信息；仅保留当前状态内容
7技术栈适配链接/参考内容匹配项目技术栈；.NET项目中无Python示例；官方文档指向对应平台
8语义内容委托给ln-601处理： 内容符合SCOPE；满足项目目标；描述与实际代码行为一致；架构/API文档反映真实情况

Output Format

输出格式

markdown
undefined
markdown
undefined

Documentation Audit Report - [DATE]

文档审计报告 - [日期]

Compliance Score

合规分数

CategoryScoreIssues
Hierarchy & LinksX/10N issues found
Single Source of TruthX/10N duplications
Proactive CompressionX/10N compression opportunities
Requirements ComplianceX/10N violations
ActualityX/10N mismatches with code
Legacy CleanupX/10N legacy items
Stack AdaptationX/10N stack mismatches
Semantic ContentX/10N semantic issues (via ln-601)
OverallX/10
类别分数问题数量
层级结构与链接X/10发现N个问题
单一信息源X/10发现N处重复
主动精简X/10发现N个精简机会
合规性要求X/10发现N处违规
时效性X/10发现N处与代码不符
遗留内容清理X/10发现N项遗留内容
技术栈适配X/10发现N处技术栈不匹配
语义内容X/10发现N处语义问题（由ln-601检测）
整体评分X/10

Critical Findings

关键问题

  • [Category] 
    path/file.md:line
    - Issue description. Action: Fix suggestion.
  • [类别] 
    path/file.md:line
    - 问题描述。措施： 修复建议。

Recommended Actions

建议措施

PriorityActionLocationCategory
HighRemove duplicate sectiondocs/X.mdSSOT
MediumAdd link to CLAUDE.mddocs/Y.mdHierarchy
undefined
优先级措施位置类别
高移除重复章节docs/X.mdSSOT
中添加指向CLAUDE.md的链接docs/Y.md层级结构
undefined

Scoring Algorithm

评分算法

See 
shared/references/audit_scoring.md
for unified formula and score interpretation.
Severity mapping:
Issue TypeSeverity
Outdated content (code mismatch)CRITICAL
Broken links, orphaned docsHIGH
Semantic mismatch (via ln-601)HIGH
Content duplicationMEDIUM
Missing compression opportunityLOW
统一公式和分数说明详见
shared/references/audit_scoring.md
严重程度映射：
问题类型严重程度
过时内容（与代码不符）关键
失效链接、孤立文档高
语义不符（由ln-601检测）高
内容重复中
未抓住精简机会低

Reference Files

参考文件

  • Size limits and targets: references/size_limits.md
  • Detailed checklist: references/audit_checklist.md
  • 篇幅限制与目标：references/size_limits.md
  • 详细检查清单：references/audit_checklist.md

Critical Notes

重要注意事项

  • Fix content, not rules: NEVER modify standards/rules files (*_standards.md, *_rules.md, *_limits.md) to make violations pass. Always fix the violating files instead.
  • Verify facts against code: Actively check every path, function name, API, config mentioned in docs. Run commands. Outdated docs mislead - they're worse than no docs.
  • Compress always: Size limits are upper bounds, not targets. A 100-line file instead of 300 is a win. Always look for compression opportunities.
  • Meaningless content: Remove filler words, obvious statements, over-explanations. If it doesn't add value, delete it.
  • No code in docs: Documents describe algorithms in tables or ASCII diagrams. Code belongs in codebase.
    • Forbidden: Code blocks, implementation snippets
    • Allowed: Tables, ASCII diagrams, Mermaid, method signatures (1 line)
    • Instead of code: "See Official docs" or "See src/file.cs:42"
  • Format Priority: Tables/ASCII > Lists (enumerations only) > Text (last resort)
  • Stack adaptation: Verify all documentation references match project stack. .NET project must not have Python examples. Check official doc links point to correct platform (Microsoft docs for C#, MDN for JS, etc.)
  • Code is truth: When docs contradict code, always update docs. Never "fix" code to match documentation.
  • Delete, don't archive: Legacy content should be removed, not moved to "archive"
  • No history: Documents describe current state only; git tracks history
Version: 4.0.0 Last Updated: 2026-01-28
  • 修正内容，而非规则： 绝不要修改标准/规则文件（_standards.md、_rules.md、*_limits.md）来掩盖违规问题。始终修改违规的文档文件。
  • 对照代码验证事实： 主动检查文档中提到的每个路径、函数名、API、配置。执行相关命令验证。过时文档会误导他人——比没有文档更糟。
  • 始终精简： 篇幅限制是上限，而非目标。300行的文件精简到100行就是进步。始终寻找精简机会。
  • 无意义内容： 移除填充词、显而易见的陈述、过度解释。如果内容没有价值，就删除它。
  • 文档中禁止出现代码： 文档需用表格或ASCII图描述算法。代码应放在代码库中。
    • 禁止： 代码块、实现片段
    • 允许： 表格、ASCII图、Mermaid、方法签名（单行）
    • 替代方案： “详见官方文档”或“详见src/file.cs:42”
  • 格式优先级： 表格/ASCII图 > 列表（仅枚举） > 文本（最后选择）
  • 技术栈适配： 验证所有文档参考内容匹配项目技术栈。.NET项目中不得出现Python示例。检查官方文档链接指向正确平台（C#用微软文档，JS用MDN等）
  • 代码即事实： 当文档与代码矛盾时，始终更新文档。绝不要“修改”代码来匹配文档。
  • 直接删除，而非归档： 遗留内容应直接删除，而非移至“归档”文件夹
  • 无历史记录： 文档仅描述当前状态；历史记录由git追踪
Version: 4.0.0 Last Updated: 2026-01-28