doc-consistency-audit

文档一致性审计 & 上下文优化

本 Skill 分两个阶段执行：一致性审计（代码 vs 文档）和上下文优化（裁剪冗余 / 超长内容）。

代码永远是 Source of Truth。文档描述与代码不符时，以代码为准更新文档。

---

阶段一：一致性审计

1.1 执行方式

为每个需要审计的模块并发启动独立 subagent：

subagent_type: generalPurpose
readonly: false    ← 需要写入文档
model: fast

每个 subagent 的任务 Prompt 模板：

你是 <模块名> 模块的文档一致性审查员，以代码为最终权威。

请完成以下任务：

**第一步 — 读取源码接口**
读取 <源码路径> 下的 .h 文件，提取：
- 所有 public 函数签名（UFUNCTION 和普通 public）
- 所有 UPROPERTY（EditAnywhere/BlueprintReadWrite/SaveGame 等）
- 关键枚举和结构体定义

**第二步 — 与 spec.md 对比**
读取 AI_Docs/<模块>/spec.md，逐项检查：
- 接口速查表中的函数/属性是否与源码一致（名称、参数、类型）
- 已删除的类/函数是否还在文档里
- 新增的接口是否遗漏

**第三步 — 检查 design.md 描述的流程**
读取 AI_Docs/<模块>/design.md，检查：
- "核心流程走读"中的类名、函数名是否与源码一致
- 数据流图中的组件关系是否准确

**第四步 — 修复**
以代码为准，更新 spec.md 和 design.md 中所有不一致之处。
- spec.md：更新接口表格、参数类型、函数名
- design.md：更新类名引用、流程步骤（保持叙述风格，只改不准确的部分）
- 保留 design.md 第一行的 <!-- AI NOTE --> 注释

**输出格式：**
发现的不一致：<逐条列出>
已修复：<逐条列出>
无需修改：<哪些部分已准确>

1.2 重点检查项

检查类型	具体验证
函数签名	参数名/类型/返回值是否与 .h 文件一致
资产路径	/Game/Content/... 路径是否实际存在（用 MCP 或 Glob 验证）
已删除内容	文档里提到但代码中已不存在的类/函数
枚举值	enum 的枚举项名称和数量
委托签名	DECLARE_DYNAMIC_MULTICAST_DELEGATE 参数是否准确

---

阶段二：上下文优化审计

2.1 执行方式

启动一个 readonly subagent 扫描所有文档，生成优化报告：

subagent_type: explore
readonly: true
model: fast

Prompt：

你是项目文档的上下文优化审查员，目标是减少 AI 不必要的 Token 消耗。

请扫描 AI_Docs/ 和 .cursor/rules/ 下的所有文件，报告以下问题：

**检查项 A：spec.md 超长（>200 行）**
对每个超过 200 行的 spec.md，分析：
- 哪些章节内容在 design.md 中已重复描述？（可以从 spec.md 中移除或缩减）
- 接口速查表是否有大量已弃用/未实现的接口（标注 ⬜ 的）占用空间？
- 是否有大段代码示例可以移到 design.md？

**检查项 B：主文档索引冗余**
读取主文档（CLAUDE.md 或等效文件），检查：
- "文档索引"中是否有条目 AI 从未需要查询（低频、仅人类关心）
- "快速问答索引"是否有重复问题指向同一文档

**检查项C：alwaysApply Rules 负担**
读取所有 alwaysApply: true 的 Rule 文件，评估：
- 每次对话都加载是否真的必要？
- 哪些可以改为 trigger-based（alwaysApply: false）？
- 每个 always-apply Rule 的大致行数

**检查项 D：changelog.md 需要归档**
对每个 changelog.md，检查是否超过 300 行（需要归档）

报告格式：
## A. 超长 spec.md
[文件] [行数] [建议操作]

## B. 主文档冗余
[具体条目] [建议]

## C. alwaysApply 负担
[Rule 文件] [行数] [是否可改为触发式] [理由]

## D. 需归档 changelog
[文件] [行数]