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

# 文档审计

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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