---
name: docs-audit
description: >-
  只读审计现有项目文档，检查资料散乱、入口难找、断链、内容过时、重复主源及当前与历史混用。用于用户要求“审计文档”“检查文档是否过时”“看看文档哪里乱”，或阶段交接前检查文档体系时。
---

# 文档审计

检查现有资料是否找得到、可信、职责清楚。默认只读，不移动、改写或删除文件；修复获准后交给相应维护流程。

## 1. 扫描文档，了解现有组织

确认项目根、受检版本与用户限定范围。默认盘点整个项目的自有文档，不只看 docs；排除依赖和构建产物，生成文档单独识别。先看路径、标题和现有索引，再按主题读正文，不一次加载全部资料。

识别项目入口、主题目录、当前说明、草稿与历史记录，以及它们之间的引用。列明未能读取或未覆盖的部分；不能把未读内容当作已检查。

## 2. 检查入口与引用，能否找到正确资料

从项目实际的 AGENTS／CLAUDE、README 或 MAP 出发，选“查接口”“改数据库”等适用任务，沿指针找到正文。检查失效路径、断链、无入口的重要文档，以及能打开却指向旧版的链接；有意不放在总导航的内部资料不直接判错。

复用项目已有只读检查；本插件的路径与链接检查可运行 `python3 <插件目录>/scripts/audit-docs.py --root <项目根> --scope artifacts`。记录命令、范围与结果；检查失败后，继续独立且可安全核实的部分，依赖失败环节或缺失证据的部分标为未完成，说明影响范围。脚本通过仍需判断导航是否有用；失败提示不授权修改文件。

## 3. 核对内容，是否仍适用于当前项目

### 核心模块的知识入口覆盖

在受检范围内，从已有架构、导航、业务职责和代码证据识别核心业务模块，不按目录大小或文件数推定。逐个检查并列明未覆盖模块：

- 必要职责、状态边界、接口和验证约定能否从现有主记录明确定位并覆盖该模块，且遵守项目级规则。局部 AGENTS、根入口中的明确模块章节或既有架构主记录都可作为落点；根入口已充分覆盖且无新增局部规则时标“复用／有效”，如实说明没有独立局部文件。只有必要约定确实未覆盖，或项目明确要求局部入口而未满足时才报缺口；不为补文件数量创建空壳。
- 是否有对应 CONTEXT，或明确链接到共享业务词汇表；前后端共用一份是有效覆盖，不强迫复制。没有领域专属词时可列“不适用”并给依据；有待澄清术语却没有主记录时列“缺失”。
- 是否只是空模板、链接是否有效、职责与术语是否混写或重复；入口质量按 `agent-entrypoints`、术语质量按 `context-and-decisions`、文档与代码边界按 `architecture-docs` 核对，不在此复制其方法。

输出“核心模块及识别依据｜规则主记录／局部入口或复用路径｜CONTEXT 主记录／复用路径｜有效、缺失、不适用或未验证｜建议”。模块归属不明或资料不可读时标未验证，不臆造缺失结论。存在文件不等于覆盖有效；静态审计脚本也不自动完成此语义核对。

本流程只读；发现缺口后建议补齐，不凭审计发现自动生成文件。若当前用户已同时授权补齐模块文档，可将明确缺口交给 `module-governance`，无须用户点名 Skill；保持审计发现与实际修复分开记录。非核心目录和普通 UI 组件不要求各有两份文件。


结合相关代码、配置、机器契约、已确认需求和变更记录核对关键说明；优先检查入口、操作指南、接口示例及近期变化涉及的文档，报告抽查范围。具体变更的候选检索复用 `change-impact`，示例验证复用 `docs-maintenance` 的验证方法，仅运行获准且不改变目标项目的检查。

按证据区分仍有效、已过时和待复核，不能仅凭修改日期判断。需求与实现冲突时分别记录，不默认代码正确。历史方案保留当时含义；检查它是否标明状态、是否被当前入口误当生效说明。

## 4. 检查职责与主源，是否集中且清楚

读取并按 [docs-structure](../docs-structure/SKILL.md) 的只读模式判断归类、主题入口与细节组织，传入本次盘点及项目已有约定；复用它的规则，不另定目录模板。该 Skill 不可用时说明结构检查未完成，不假称已调用。

重点核对同类知识是否散落、一篇文档是否混杂无关职责、同一事实是否在多处独立维护。区分必要摘要／引用与重复主源；主源不明时列出候选和冲突，不擅自裁决。

例如，表结构同时写在 README 和两份设计说明中，应核对当前主源及其余内容的用途；历史设计不要求改成现状，当前入口应明确指向生效说明。

完成后按影响列出“位置 → 证据 → 问题与影响 → 建议动作”，建议明确到具体文件或章节，说明应更新哪份主记录、修正哪个入口，或归档哪份已被替代的资料；依据不足时指出需确认什么。说明检查范围、通过项和未验证项。每项发现应能复核，扫描全项目不等于全文核实；缺少依赖、证据或检查失败时明确剩余缺口。默认在回复交付，不另建报告，也不为凑数量制造问题。