ln-21-documentation-auditor

文档审计

目标： 将文档作为只读证据系统进行审计：新的贡献者、运维人员、用户或编码 Agent 能否找到正确的信息来源、信任其中的说法，并在没有隐藏上下文的情况下采取行动？审查独立文档和承载公共或运维知识的代码注释。

执行约定： 按顺序排列的复选框即为完成定义。内部将每项标记为 PENDING、以具体证据证明的 PROVEN、有证据表明其条件不存在的 CLEARED，或存在缺口的 UNPROVEN；阅读、委派或工具故障都不构成证据。每完成一节后都要核对各项。返回前，解决所有 PENDING 项，并且只统计 PROVEN 和 CLEARED 项；对每个缺口，按照此技能的判定和批准规则处理。 保留用户意图、范围和现有授权。继续已获授权的工作；仅在存在尚未解决且影响重大的选择，或需要外部批准时才提出询问。根据材料风险调整审查深度，不得悄然跳过检查。保留依赖关系和安全顺序；其他情况下，为每项义务选择合适的验证方式。

工具路由

需求	首选工具	适用场景	备选方案
文档清单和层级结构	使用精确模式的原生文件列表工具	确认文档范围、生成内容区域和导航结构	仓库目录树和已知入口文档
链接、重复术语、说法和矛盾	先用原生文本搜索，再针对性阅读	查找引用、过时名称、重复指南、路径、命令和配置键	手动跨文档比对
代码和配置事实	原生代码搜索、清单、架构定义和直接读取文件	文档声称某个路径、选项、端点、行为或默认值存在时	文本不足以验证时，执行安全的检查命令
新旧状态和归属	Git 日志、blame 和 diff	确定说法何时变更、文档是否对应当前代码，或谁负责维护某项约定	当前代码和明确的归属文件
命令和示例	以非变更模式或试运行模式使用 Shell	验证帮助文本、命令是否存在、配置解析、生成的输出或示例语法	检查命令注册和测试；将运行时证明标记为不可用
外部事实	官方文档、规范和发行说明	当前外部 API、版本、标准或平台行为会影响正确性时	查询一手来源；否则标记为 UNVERIFIED

不要运行会发布、迁移、部署、写入生产状态或重写文档的命令。只有在获准且明确披露的情况下，才可使用生成的缓存。

证据规则

说法类型	所需证据
仓库路径、符号、命令、配置、端点或默认值	当前仓库或安全命令的输出
外部 API、版本、标准或兼容性说明	与相关版本匹配的官方来源
数量或覆盖率说明	范围和排除项明确且可复现的查询
历史缘由	仍与当前实现相符的决策记录或历史记录
建议	已证实的读者受阻情况、矛盾、维护成本或运维风险

只有当确有受众需要缺失信息时，文档缺失才算问题。评估过时或缺失的指南时，应依据其造成的读者受阻情况或损害。

检查清单

1. 明确范围和受众

• 确定纳入范围的文档入口、公开文档、维护者文档、运维手册、生成的参考资料、示例和代码注释。
• 确定目标受众及其具体任务：理解、安装、配置、运行、排查问题、扩展或验证系统。
• 阅读适用的仓库说明，并确认文档归属、生成命令、语言政策和事实来源约定。
• 在评估缺陷前，将编写的文档与生成内容、第三方内容、归档内容、临时内容和示例区分开。
• 将每个目标归类为入口/索引、参考资料、操作指南、说明文档、决策记录、生成内容或示例；优先检查规范性文档和内容密集的文档，再检查仅用于导航的文件。
• 明确哪些代码、配置、架构、测试和外部契约可用于验证文档中的说法。
• 保持审计只读，并将任何不可用的来源、命令或环境记录为限制。

2. 检查结构和可发现性

• 确认根入口文档说明了适合其受众的用途、支持的使用方式、先决条件、安装路径和导航。
• 检查层级、标题、目录、本地导航、交叉链接、锚点，以及相关内容是否位于可预期的位置。
• 验证本地路径和锚点（包括大小写敏感性），并检查外部重定向是否指向错误或不可用的目标；有意设置且正常工作的重定向不属于缺陷。
• 找出孤立文档、重复入口、循环导航、过深的导航链，以及只能通过搜索仓库才能找到的重要内容。
• 确认每个概念都有唯一的规范归属文档，次要文档通过链接引用，而不是另行维护规则、阈值或流程。
• 确认生成的文档注明了生成工具，且不会引导用户手动编辑后又被覆盖。
• 检查大型文档能否拆分或精简，同时不丢失安全执行操作所需的顺序或上下文。

3. 检查相关性、覆盖范围和一致性

• 将每份文档的标题、范围说明和目标读者与其实际内容进行对比。
• 根据文档类型评估内容：索引应负责导航，避免重复细节；参考文档应便于精准查找；操作指南应按安全顺序编排；说明文档应帮助读者建立正确的心智模型；决策记录应保留背景、决策、备选方案和后果。
• 标记填充内容、重复摘要、推测性叙述、泛泛的生成式文本，以及无助于目标读者做出决策或采取行动的形式化章节。
• 优先记录持久的意图、约定、约束和操作方式，而非照搬实现或业务逻辑；仅保留安全执行操作所必需的、经过验证的最少代码或命令示例。
• 找出偏离主题的内容、范围蔓延、未说明的前提条件、隐藏假设，以及不再支持当前任务的章节。
• 在适用的情况下，检查是否覆盖公开行为、配置、部署、迁移、故障恢复、安全敏感操作和扩展点。
• 跨文档追踪需求和架构说明；报告矛盾和归属不明确之处，不要默默自行取舍。
• 找出过时的将来时计划、已完成的 TODO、已移除的功能、旧版兼容性指南、过时的目录结构，以及陈旧的截图或示例。
• 检查术语、实体名称、标识符、大小写和生命周期状态是否与代码一致，并在各文档间保持一致。
• 确认警告、前提条件、破坏性操作、回滚步骤和故障结果都出现在读者需要了解的位置。
• 在始终加载的 Agent 指令中，找出工具已强制执行的冗余格式说明，以及可移至受支持的作用域文件中的特定路径细节。保留发现机制、非显而易见的要求和宿主兼容性。

4. 核实事实和示例

• 提取有关路径、文件、符号、版本、数量、命令、标志、环境变量、配置键、端口、端点、架构和默认值的重要声明。
• 核实前先建立规范化的声明台账，并按主题归类重复声明，以便通过一次仓库检查同时发现过时副本和跨文档矛盾。
• 根据当前仓库证据或安全命令核实每项声明；记录检查所用的确切来源和范围。
• 查阅外部文档或声称当前支持情况之前，先从清单文件和锁定文件确认已安装的版本。
• 对外部 API、弃用信息、安全标准、平台限制和兼容性声明，使用官方来源。
• 仅在安全的本地环境或一次性环境中执行示例；否则检查其解析结果、测试和预期输出，并标记为静态核实。
• 检查示例是否缺少导入项、将占位符当作真实值、路径无效、包含不安全的机密、语法过时，或输出与当前行为不符。
• 按照声明的上下文解读示例、模板、未来计划和外部引用。即使当前未启用，也要核实条件式指南所需的受支持前提条件；不要将假设性示例视为已部署行为。
• 使用可复现的查询和有记录的排除项核实数值；避免保留会随时间变化且没有自动化维护的汇总数量。
• 在可行的情况下，建议将易变的版本、路径、默认值、清单、生成内容和状态快照迁移到权威代码、配置或生成源；否则，指出防止其在不知情的情况下过时所需的来源、范围、负责人或生成／更新触发条件。
• 遵循从研究到行动的门槛：只有当外部指南能够证明仓库中存在具体缺陷或风险时，才将其列为发现项。

5. 审查注释并生成报告

• 检查注释和文档字符串，确认其中是否包含有用的设计依据、不变量、契约、副作用、失败行为和不明显的限制。
• 将公共或不明显接口的文档字符串与当前签名、参数、返回值、抛出的错误、副作用、可空性和生命周期义务进行核对。
• 标记语法说明、过时的历史信息、死代码、错误承诺，以及更适合通过名称或类型表达的信息；保留仍能解释限制或防止已知回归的历史设计依据。
• 检查公共接口是否包含语言或生态系统要求的文档，以及与实际契约相符的示例。
• 在报告前，筛除有意面向受众简化的内容、框架惯例、生成内容和已接受的遗留限制。
• 将每个范围内的文档或注释部分分类为 KEEP、ADD、UPDATE、DELETE 或 MERGE；只有在规范内容能覆盖所有必需的受众任务和契约时，才建议删除或合并。
• 应用实质性门槛：必须存在具体的读者错误、任务受阻、不安全操作、矛盾或有证据表明会反复发生的维护成本。排除品味偏好、理论上的纯粹性、泛泛的最佳实践、假设性规模问题和合理的替代方案；要求指出结果或限制，而非偏好的实现方式。
• 对外部更正，依据与版本相符的官方契约；对于尚未解决的权衡，使用一手工程资料。对于本地缺陷，本地证据即可。
• 根据错误操作造成的危害、无法运行、维护偏差或轻微阻碍，将发现的问题分为 P0 至 P3。
• 如果无法在没有可信替代依据的情况下核实安全关键声明、必需的受众操作路径或权威来源，则使用 BLOCKED；如果证据证实存在不安全指南、必需操作路径无法运行或尚未解决的 P0/P1，则使用 FAIL；仅在存在实质性但不阻塞的信任缺口时使用 CONCERNS；只有在必需声明和操作路径均已核实且不存在实质性发现时，才使用 PASS。

自检

• 返回前完成核对。 检查逐项证据、要求覆盖情况、矛盾、范围、判定结果和适用的清理工作。更正报告或获授权的产物。复用有效证据；不要自动重新扫描代码仓库或重新运行已成功的命令。仅针对相关更改、失败或尚未解决的证据重复检查。披露剩余缺口。

输出契约

使用用户的语言，并按以下顺序报告；保留全部五个字段，每项事实仅陈述一次。结果较少时，每个字段可占一行；省略空表格，不要复制链接的产物：

1. 结果： 技能专属判定结果和有依据的结论。
2. 范围： 已审查/更改的范围、排除项、基线和重要假设。
3. 证据： 以下技能专属字段；区分事实、推断和未经核实的声明。链接产物；适用时使用表格。
4. 验证： 检查及结果、无法获取的证据，以及适用的清理工作/外部状态。
5. 完成情况： Checklist: X/Y complete；Incomplete: None，或列出每项 UNPROVEN 的原因、对结果的影响和确切的下一步操作；剩余风险和所需决策。

技能专属证据： 文档受众和操作路径；结构、覆盖范围、准确性、持久性/SSOT 以及注释可信度。记录范围内每个部分的 KEEP / ADD / UPDATE / DELETE / MERGE。发现的问题须说明优先级、文档位置、核实依据、受影响受众、实质影响、不可接受的权衡，以及最小修正方案或规范内容的归属方；允许采用等效结构。区分未经核实的声明与已证实的缺陷。