关于 doc-validator
doc-validator 是用于检查 SDD 文档集关系与一致性的技能。它报告交叉引用、孤立文档、ID、可追溯性、图表、术语和文字问题，并可选择修复安全可修的问题。
主要功能
- 01检查文档间链接和交叉引用
- 02查找孤立文档及可追溯性断链
- 03验证 ID 与累积上游标签
- 04检查图表、术语和内容计数
- 05备份后选择性修复特定问题
适用场景
- 01发布前执行项目级文档检查
- 02检查双向可追溯性与孤立文档
- 03发布前审查文档文字
安装
复制下面的命令，在终端中运行。
npx skills add https:/安装后在 Claude Code 中输入/doc-validator确认已加载。
详细介绍
doc-validator
用途
验证 SDD 语料库中各文档之间的关系与一致性：损坏的交叉引用、孤立的制品、单向链接、累积标签缺失、重复或格式错误的 ID，以及跨 8 个层级的可追溯矩阵完整性。此技能就是验证器——框架不提供运行时代码；它会针对 ${CLAUDE_PLUGIN_ROOT}/framework/governance/ 和各层的 README.md 文件执行声明式检查。
层级：跨领域实用工具（读取全部 8 个层级；不生成制品）。
使用时机
适用于项目范围的检查：文档间关系、累积标签、孤立项检测、双向链接一致性、重复 ID、深度可追溯性（可选修复链接）、文案/术语审查，以及重大版本发布前的检查。它是唯一的语料库级验证器——也涵盖了此前由独立技能负责的可追溯深度与修复，以及文案审查。
不适用于：
- 单个文档的结构/元数据/内容——请使用该层的
../doc-<layer>-audit/SKILL.md； - ID 格式规则的定义——该规则由
../doc-naming/SKILL.md负责。（此技能会强制执行 ID 格式并报告XDOC-E007；可用它来检查 ID——规则定义在doc-naming中。）
输入：docs_path（必填）、scope（默认为 cross-document /
traceability / prose / full）、strictness（strict / permissive）、
auto_fix（安全时修复损坏的链接/重新生成计数）、report_format。
行为
跨文档检查
| 类别 | 检查项 | 错误代码 |
|---|---|---|
| LINKS | 每个 Markdown/文档链接和锚点均可解析 | XDOC-E001, XDOC-E004 |
| CROSS-REF | 每个引用的文档/元素 ID 均存在于语料库中 | XDOC-E001, XDOC-E003 |
| ORPHAN | 每个制品都具有上游关联 | XDOC-E005 |
| TAGS | 累积上游标签符合 8 层级结构要求 | XDOC-E002 |
| IDS | 元素 ID 格式为 TYPE.NN.SS.xxxx；文档引用为 SPEC-NN/ADR-NN/IPLAN-NN；不得重复；不得使用旧式/3 段式/已停用格式 | XDOC-E006, XDOC-E007 |
| MATRIX | 跨 8 个层级的可追溯矩阵完整性 | XDOC-W001 |
| SECTION | 章节文件数量与元数据一致 | SEC-E001…E003, SEC-W001 |
| DIAGRAM | Mermaid 实体与文案一致 | DIAG-E001/E002, DIAG-W001/W002 |
| TERM | 术语/缩略语一致性 | TERM-E001/E002, TERM-W001/W002 |
| COUNT | 声明的计数与逐项合计一致 | COUNT-E001, COUNT-W001 |
| FWDREF | 不得存在上游→下游引用；不得有循环 | FWDREF-E001/E002, FWDREF-W001 |
SECTION / TERM / COUNT 类问题通常可自动修复（重新生成计数/章节、规范术语）；其余问题会报告出来，需手动修复。
可追溯深度 + 修复
除跨文档检查外，还会运行完整的双向可追溯性检查：
- 双向对称性——对每条 A→B 链接，确认 B→A 链接存在；得分为
(匹配的链接对数 / 总数) × 100（目标 ≥ 95%）。 - 覆盖率 + 孤立项——除 BRD 外，每个制品都必须有上游关联；下游关联为可选项；标记没有下游关联的链中制品和意外的孤立项；按类型报告覆盖率。
- 修复（
auto_fix）——启用后，仅修复可安全修复的问题：添加缺失的双向链接、重新生成章节/COUNT 元数据、规范术语。先写入带时间戳的备份并打印回滚命令；绝不为满足检查而编造占位 ID。结构/内容缺失问题仍会报告给相关的-fixer。
文案审查（scope: prose）
审查单个文件或文件夹的文案质量，不涉及可追溯性，涵盖以下四类：
- DATA — 陈述的数量／状态／日期逻辑与内容不符（例如，声称有“5 项功能”但只列出 4 项；
last_updated早于created）。 - REF — 行内链接／锚点／标签格式解析。
- TYPO — 拼写错误、重复词、Markdown 格式损坏。
- TERM — 未定义的缩写、术语不一致或带有主观色彩的术语。
严重级别遵循 strictness：在 strict 模式下，任何 DATA/REF/TYPO/TERM 问题都是错误（会阻止操作）；在 permissive 模式下则为警告。遵循项目的 glossary（.aidoc/profile.yaml；参见 Adaptation），以抑制领域术语相关的 TERM 误报。可在发布或提交文档前使用。
累积标签层级
| 层级 | 工件 | 必需的上游标签 |
|---|---|---|
| 1 | BRD | 无 |
| 2 | PRD | @brd |
| 3 | EARS | @brd, @prd |
| 4 | BDD | @brd, @prd, @ears |
| 5 | ADR | @brd, @prd, @ears, @bdd |
| 6 | SPEC | + @adr (5) |
| 7 | TDD | + @spec (6) |
| 8 | IPLAN | + @tdd (7) |
权威依据：${CLAUDE_PLUGIN_ROOT}/framework/registry/LAYER_REGISTRY.yaml（required_tags）和
${CLAUDE_PLUGIN_ROOT}/framework/governance/TRACEABILITY.md。
ID 格式强制检查（IDS）
要求元素 ID 使用 4 段格式 TYPE.NN.SS.xxxx
（TYPE ∈ {BRD, PRD, EARS, BDD, ADR, TDD}），文档级引用使用连字符格式 SPEC-NN/ADR-NN/IPLAN-NN。拒绝旧版 3 段元素 ID、数字类型代码方案，以及任何对已退役的 12 层工件的引用——对每项都标记 XDOC-E007。参见 ../doc-naming/SKILL.md。
质量门禁
ERROR 会阻止操作（退出码 2）；WARNING 仅在使用 --strict 时阻止操作（退出码 1）；INFO 仅供参考。项目级门禁：跨引用错误为零、孤立项为零、双向合规率和累积标签合规率均为 100%、重复 ID 为零。输出为合并报告（markdown/json/text），列出每项问题、其代码和修复提示。
适配
验证前读取项目适配配置（.aidoc/profile.yaml）。
遵循此技能声明的可配置项：
active_layers— 禁用可跳过层（BDD / ADR）时，将其视为按设计缺失：应用级联规则（从下游的required_tags/can_reference中移除该层），以免累积标签、孤立项和双向检查将这一有意的缺失标记为错误。glossary— 使用项目首选术语，在文案检查阶段规范化领域术语并抑制TERM问题（对已接受的词汇不产生误报）。
忽略未知或不在适用范围内的键；若没有配置文件，则使用框架默认值。
权威依据：${CLAUDE_PLUGIN_ROOT}/framework/governance/ADAPTATION.md。
相关资源
- 治理：
${CLAUDE_PLUGIN_ROOT}/framework/governance/DOC_GOVERNANCE_CORE.md·${CLAUDE_PLUGIN_ROOT}/framework/governance/TRACEABILITY.md·${CLAUDE_PLUGIN_ROOT}/framework/governance/ID_NAMING_STANDARDS.md - 层注册表：
${CLAUDE_PLUGIN_ROOT}/framework/registry/LAYER_REGISTRY.yaml - 各层权威依据：
${CLAUDE_PLUGIN_ROOT}/framework/layers/NN_<X>/README.md - ID 格式权威依据：
../doc-naming/SKILL.md - 单文档门禁：
../doc-brd-audit/SKILL.md…../doc-iplan-audit/SKILL.md - 工作流路由：
../doc-flow/SKILL.md· 图表：../charts-flow/SKILL.md