doc-claim-validator

文档声明验证器

通过提取可测试的声明并对照代码库进行检查，验证文档所说的是否确实属实。与处理结构健康状况的 doc-maintenance 互为补充，负责处理语义准确性。

适用场景

• 重大代码变更后（重构、重命名、API 变更）
• 发布前——发现描述已移除或已变更行为的文档
• 新成员反馈“文档有误”时
• 定期审计项目文档的可信度
• 运行 doc-maintenance 后，深入检查结构之外的问题

快速参考

资源	用途	何时加载
scripts/extract_claims.py	从 Markdown 中确定性地提取声明	始终加载（阶段 1）
scripts/verify_claims.py	对照代码库自动验证	始终加载（阶段 2）
references/claim-taxonomy.md	带示例的完整声明类型分类	梳理不明确的声明时

---

工作流概览

Phase 1: Extract    → Pull verifiable claims from docs (deterministic script)
Phase 2: Verify     → Check claims against codebase (automated + AI)
Phase 3: Report     → Classify failures by severity and type
Phase 4: Remediate  → Fix or flag broken claims

---

阶段 1：提取声明

运行提取脚本，解析所有 Markdown 文件并提取可验证的断言：

python3 skills/doc-claim-validator/scripts/extract_claims.py [--json] [--root PATH] [--scope docs|manual|all]

脚本会从 Markdown 中提取以下声明类型：

类型	提取内容	文档示例
file_path	符合文件路径模式的行内代码	`src/auth/login.ts`
command	代码块或包含 Shell 命令的行内代码	`npm run build`
code_ref	行内代码中的函数、类、方法引用	`authenticate()`
import	代码块中的导入/require 语句	import { Router } from 'express'
config	配置键、环境变量、设置	`MAX_RETRIES=3`
url	外部链接（http/https）	[docs](https://example.com)
architectural	关于技术、集成或架构模式的动词锚定型散文声明	“使用 Redis 进行缓存”“遵循 Actor 模型”“委托给 Auth0”
dependency	软件包/库名称声明	“使用 Redis 进行缓存”
behavioral	关于代码行为的断言	“系统会重试 3 次”

前 7 种类型采用确定性方式提取。脚本通过动词锚定的正则表达式匹配 architectural（规则如 uses X、built with X、follows the X pattern、delegated to X、via X、depends on X），从而捕获此前遗漏的、没有锚点的散文声明。

最后 2 种类型（dependency、behavioral）需要 AI 分析，会在阶段 2 处理。尤其是 behavioral，不会通过正则表达式提取，因为行为声明属于自由格式散文（例如“用户登出时缓存会失效”），难以通过模式匹配可靠识别——行为验证器会在一次处理中发现并验证这些声明。

**输出：**包含声明来源文件、行号、声明类型和声明原文的结构化列表。

---

阶段 2：验证声明

步骤 2a——自动验证

对提取的声明运行验证脚本：

python3 skills/doc-claim-validator/scripts/verify_claims.py [--json] [--root PATH] [--claims-file PATH] [--check-staleness]

传入 --check-staleness，以启用基于 Git 的偏移分析（见下文）。

脚本会根据声明类型采用不同的检查方式：

声明类型	验证方式	通过条件
file_path	os.path.exists()	引用路径下的文件存在
command	shutil.which() + 脚本检查	二进制文件或脚本文件存在
code_ref	使用 grep -r 搜索函数/类名称	在代码库中找到符号
import	检查模块是否存在于项目或依赖项中	模块可解析
config	在源代码中搜索配置键	在配置文件或代码中找到该键
url	HTTP HEAD 请求（可选，默认关闭）	返回 2xx/3xx

传入 --check-urls，以启用 URL 验证（速度较慢，需要网络）。

第 2b 步 — AI 辅助验证

自动检查完成后，派遣 Agent 验证脚本无法核实的声明。 四个验证器中，有三个使用 general-purpose + sonnet 运行——行为、架构和代码示例验证都需要跨多个文件进行推理，而 haiku 的摘录读取模式难以胜任。依赖项验证器则继续使用 Explore + haiku，因为它只需对清单文件进行模式匹配。

派遣策略：按文档文件批处理

对于行为和架构验证器，每个包含此类声明的 Markdown 文件派遣 一次 sonnet 调用，并在单个提示词中批量处理该文件中的所有声明。这样既能将每次调用的上下文预算控制在少量相关声明上（在文档内交叉引用有助于验证），又能让总调用次数取决于文档集的规模，而不是声明的数量。对于约有 50 份文档和约 150 条架构声明的项目，预计需要约 10–20 次 sonnet 调用（只有包含声明的文档才会触发调用），而不是 150 次。

对于精确度比成本更重要的发布审计，请采用 按声明派遣——每条声明派遣一次 sonnet 调用，并将完整文档作为上下文。成本更高，精确度也更高。

验证器

验证器 1 — 依赖项声明验证器（subagent_type: "Explore"， model: "haiku"）： 读取 package.json、requirements.txt、go.mod、Cargo.toml 或等效的 依赖项清单。交叉核对有关所用库、框架或服务的文档声明。报告提及项目中 不存在的依赖项的声明。使用 haiku 是因为对清单进行模式匹配无需 sonnet 的推理能力。

验证器 2 — 行为声明验证器（subagent_type: "general-purpose"， model: "sonnet"，每个文档文件单独运行）： 对范围内的每个 Markdown 文件，分派一个 sonnet Agent，并提供该文件内容。 该 Agent 将（a）找出文件中的行为声明（“重试 3 次”“缓存 5 分钟”“处理前 验证输入”“用户注销时缓存失效”），（b）通过 grep / codanna / Read 查找相关代码，（c）验证声明是否与实现一致。 逐条报告声明，并标注已确认／已否定／无法验证／有条件状态。需要 sonnet， 因为行为验证通常需要跨多个文件追踪（处理程序 → 中间件 → 配置），并区分 正常路径与错误路径的行为。

验证器 3 — 架构声明验证器（subagent_type: "general-purpose"，model: "sonnet"，每个文档文件单独运行）： 对于提取出 architectural 声明的每个 Markdown 文件，分派一个 sonnet Agent， 并提供该文件内容和预先提取的声明列表。Agent 通过以下方式验证每项声明：

• 对于 uses/built/depends/via 框架：在依赖项清单、配置文件和源代码导入中检查所提及的技术。
• 对于 delegated 框架：检查与所提及服务相匹配的 SDK 导入或 HTTP 集成。
• 对于 follows/uses_pattern 框架：检查目录结构、类名和代码组织是否符合所提及的架构模式（例如，CQRS：分离的命令／查询处理程序 + 事件存储；六边形架构：adapters/ports 目录；saga：包含指定转换的协调器类）。

逐条报告声明，并标注已确认／已否定／无法验证／有条件状态。需要 sonnet， 因为架构模式并非与任何单个文件一一对应——验证需要阅读足够多的代码库内容， 才能识别出该模式。

验证器 4 — 代码示例验证器（subagent_type: "general-purpose"， model: "sonnet"，每个文档文件单独运行）： 对于文档中展示用法示例的代码块，验证函数签名、参数名、返回类型和导入路径 是否与当前代码库一致。报告复制粘贴后会运行失败的示例。需要 sonnet，因为 签名检查需要读取当前实现并进行比对；haiku 对摘录的读取不足以完成这项工作。

并行启动验证器 1、2、3、4。在验证器 2/3/4 内部，每个文档文件的任务按顺序 分派（或者在成本允许的情况下，以小批次并行分派）。

步骤 2c — Git 过时度评分

对于通过存在性检查的声明，计算漂移分数，以找出可能已过时的声明：

python3 skills/doc-claim-validator/scripts/verify_claims.py --check-staleness

对于每条通过检查的声明，脚本将：

1. 获取文档文件最近一次 Git 修改的时间戳
2. 获取目标文件最近一次 Git 修改的时间戳
3. 统计文档最近一次编辑之后修改目标文件的提交次数
4. 分配漂移分数：低（1-3 次提交）、中（4-9 次）、高（10 次以上）

高漂移声明是最适合 AI 审查的候选项——目标文件有大量变更，但文档没有， 因此文档描述的行为很可能已经过时。

过时度报告将作为按分数降序排列的表格追加。

---

阶段 3：报告

将自动化结果与 AI 发现合并为一份报告。对每条未通过检查的声明进行分类：

严重级别

级别	含义	示例
P0	面向用户的文档声称了某项内容，但照此操作会导致问题	教程展示了已删除的 API 端点
P1	开发文档引用了不存在的代码结构	README 引用了已重命名的 auth.validate()
P2	行为说明不再准确	声称“重试 3 次”，但重试逻辑已移除
P3	依赖项／导入说明已过时	声称“使用 Express”，但项目已迁移到 Fastify
P4	轻微的不准确，仅影响外观	配置键已重命名，但行为未变

失败类别

类别	描述
missing_target	引用的文件、函数或符号不存在
wrong_signature	函数存在，但签名与文档不符
stale_behavior	行为说明与实现不符
dead_dependency	文档引用了项目中不存在的依赖项
phantom_pattern	代码库中没有证据支持的架构说明（“使用 CQRS”“遵循 Actor 模型”）
wrong_integration	文档提到的服务／SDK（“委托给 Auth0”）实际上并未集成
broken_example	代码示例执行时会失败
dead_url	外部链接返回 4xx/5xx
phantom_config	文档中引用的配置选项在代码中不存在

---

阶段 4：修正

对于每项未通过验证的声明，决定采取以下操作：

操作	适用情况	方法
更新文档	代码正确，文档已过时	编辑文档，使其与代码一致
标记待审核	无法确定是代码还是文档有误	创建问题，交由人工审核
删除声明	所引用的功能已删除	删除或重写相关章节
更新示例	代码示例已过时	根据当前代码重写示例

按照 doc-maintenance 约定，将修正工作分派给相应的 Agent：

• API／CLI 参考文档交给 reference-builder
• 架构和开发者文档交给 technical-writer
• 面向用户的教程和指南交给 learning-guide

---

与 doc-maintenance 集成

此技能设计为在 doc-maintenance 之后运行：

doc-maintenance  →  Structural health (links, orphans, folders, staleness)
doc-claim-validator  →  Semantic accuracy (do claims match reality?)

这两项技能使用相同的严重级别和修正 Agent 分派规则。两者的结果可以合并为一份文档健康报告。

---

反模式

• 不要自动修正行为说明——判断意图需要人工参与
• 不要将每个行内代码引用都视为文件路径（`true` 不是文件）
• 不要验证已归档文档（docs/archive/）中的声明——它们属于历史记录
• 不要因可选／条件性功能而判定失败——应标记为“条件性”
• 默认不要检查 URL——这很慢且不稳定；仅在明确选择时检查
• 不要验证标记为 `` comment 的代码块

---

附带资源

脚本

• scripts/extract_claims.py — 从 Markdown 文件中确定性地提取声明
• scripts/verify_claims.py — 根据代码库自动验证提取出的声明

参考资料

• references/claim-taxonomy.md — 声明类型的完整分类法，包含提取模式和示例