用途
HADS（Human-AI Document Standard，人机文档标准）是一个面向 Markdown 技术文档的约定规范，用于编写同时便于人类和 AI 模型阅读的文档。该技能教会 Claude 如何阅读、生成和验证 HADS 文档。
主要能力
[SPEC]
- 定义四种块类型：[SPEC]（权威事实，简洁，AI 始终阅读）、[NOTE]（人类上下文、历史、示例，AI 可跳过）、[BUG]（已验证的故障与修复，必读）、[?]（未经验证或推断的内容，低置信度，始终标记）。
- 规定块标签格式：加粗、独占一行，如 [SPEC]；内容紧随其后（标签与内容之间无空行）；同一章节允许多个不同类型的块；允许带标题的 BUG 块，如 [BUG] 简短描述；块不可嵌套。
- 规定必需文档结构：H1 标题、头部中的 Version X.Y.Z（前 20 行内）、首个内容章节之前的 AI 清单章节、内容章节（H2）与子章节（H3）。
- 规定 Claude 阅读 HADS 的方式：先查找并阅读 AI 清单；阅读所有 [SPEC] 块（作为基准事实）；在生成任何代码或配置前始终阅读所有 [BUG] 块；仅当 [SPEC] 不足以回答查询时阅读 [NOTE] 块；将 [?] 内容视为假设并在回复中注明不确定性。对于大型文档，可先扫描章节标题，再仅阅读相关章节中的 [SPEC] 和 [BUG] 块以优化 token。
- 规定 Claude 生成 HADS 的方式：从头部块（标题、版本、元数据）开始；始终包含 AI 清单；将内容组织为编号的 H2 章节；每个事实写为 [SPEC]（简洁，使用项目符号、表格或代码）；每个“为什么”或上下文写为 [NOTE]；每个已知故障模式及确认修复写为 [BUG]；每个未经验证的声明写为 [?]；以变更日志章节结尾。
- [SPEC] 内容规则：优先使用项目符号列表而非散文；多字段事实优先使用表格；语法、格式、示例优先使用代码块；散文最多 2 句，超出则移至 [NOTE]。
- [BUG] 内容规则：始终包含症状、原因、修复；可选包含受影响版本、临时解决方案；标题与标签同行，如 [BUG] 简短描述。
- 验证规则：有效的 HADS 文档必须包含 H1 标题、前 20 行内的 Version X.Y.Z、首个内容章节之前的 AI 清单、所有块标签加粗（[SPEC] 而非 [SPEC] 或 [SPEC]）、[BUG] 块至少包含症状 + 修复。验证器为计划中功能，本版本尚未包含。
- 示例交互：用户要求为 REST API 编写 HADS 文档、将 README 转换为 HADS 格式、验证文档是否为有效 HADS、总结 HADS 文档、询问 API 功能（提供 HADS 文档时）等场景下的处理方式。
[NOTE]
- 将现有文档转换为 HADS 时：将事实提取到 [SPEC]，将叙述和历史移至 [NOTE]，将所有已知问题呈现为 [BUG]，不在块类型之间重复内容。
- 设计意图：HADS 的存在是因为 AI 模型越来越多地在人类之前阅读文档，该格式在不牺牲人类可读性的前提下针对这一现实进行优化。核心创新是 AI 清单，它让即使小型（7B）模型也能知道该读什么、该跳过什么，而无需推理文档结构。生成 HADS 时，可将 [SPEC] 视为 API 表面，[NOTE] 视为注释，[BUG] 块是最有价值的内容，代表来之不易的知识。
使用方式
[SPEC]
- 文件扩展名为 .md，使用标准 Markdown，无需任何工具。
- 用户可要求 Claude 编写 HADS 文档、转换现有文档、验证文档有效性或总结 HADS 文档。
- AI 清单最低要求：
AI READING INSTRUCTION
Read [SPEC] and [BUG] blocks for authoritative facts.
Read [NOTE] only if additional context is needed.
[?] blocks are unverified.
适用场景
[SPEC]
- 编写需要同时被人类和 AI 模型阅读的技术文档。
- 将现有文档转换为 HADS 格式。
- 验证文档是否符合 HADS 规范。
- 总结 HADS 文档。
限制
[SPEC]
- 验证器为计划中功能，本版本尚未包含。
- 版本为 1.0.0，标准为 HADS 1.0.0。
- 关于收费、价格、平台等信息暂未提供。