mcpField
H
hads

hads

github.com/wshobson文档处理41.9k6.7k 次安装2 周前更新
代码仓库

关于 hads

HADS Claude Skill 教授 Claude 读取、生成和检查 HADS 格式的 Markdown 技术文档。它定义四类内容块、必需文档结构及阅读规则；文档验证器尚未包含。

主要功能

  1. 01介绍四种 HADS 内容块
  2. 02规定文档必需结构
  3. 03指导按块读取文档
  4. 04指导生成 HADS 文档
  5. 05列出格式验证规则

适用场景

  1. 01将现有文档改写为 HADS 格式
  2. 02按规范编写技术文档
  3. 03检查文档结构与内容标记
  4. 04从 HADS 文档提取事实摘要

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/wshobson/agents --skill hads

安装后在 Claude Code 中输入/hads确认已加载。

详细介绍

HADS Claude Skill

Version 1.0.0 · Human-AI Document Standard · 2026 · HADS 1.0.0

AI 阅读说明

本 Skill 教 Claude 如何阅读、生成和校验 HADS 文档。 在回应任何与 HADS 相关的请求之前，先阅读所有 [SPEC] 块。 如果需要了解意图或边缘情况的背景信息，阅读 [NOTE] 块。

1. 什么是 HADS

[SPEC]

  • HADS = Human-AI Document Standard
  • Markdown 技术文档的约定
  • 四种块类型：**[SPEC]**、**[NOTE]**、**[BUG]**、**[?]**
  • 每个 HADS 文档都需要：H1 标题、版本声明、AI manifest
  • AI manifest 出现在第一个内容章节之前，告诉 AI 要阅读/跳过哪些内容
  • 文件扩展名：.md —— 标准 Markdown，无需任何工具

2. 块类型

[SPEC]

**[SPEC]**   Authoritative fact. Terse. Bullet lists, tables, code. AI reads always.
**[NOTE]**   Human context, history, examples. AI may skip.
**[BUG]**    Verified failure + fix. Required fields: symptom, cause, fix. Always read.
**[?]**      Unverified / inferred. Lower confidence. Always flagged.

块标签规则：

  • 加粗，独占一行：**[SPEC]**
  • 内容紧随其后（标签与内容之间不留空行）
  • 每个章节允许多个不同类型的块
  • 允许带标题的 BUG 块：**[BUG] Short description**
  • 块内不允许嵌套块

3. 必需的文档结构

[SPEC]

# Document Title
**Version X.Y.Z** · Author · Date · [metadata]

---

## AI READING INSTRUCTION

Read `[SPEC]` and `[BUG]` blocks for authoritative facts.
Read `[NOTE]` only if additional context is needed.
`[?]` blocks are unverified — treat with lower confidence.

---

## 1. First Section

**[SPEC]**
...

按顺序的必需元素：

  1. H1 标题
  2. 头部中的 **Version X.Y.Z**（前 20 行内）
  3. 第一个内容章节之前的 AI manifest 章节
  4. 内容章节（H2）、子章节（H3）

4. Claude 如何阅读 HADS

[SPEC] 遇到 HADS 文档时：

  1. 首先找到并阅读 AI manifest
  2. 阅读所有 [SPEC] 块 —— 这些是基准事实
  3. 阅读所有 [BUG] 块 —— 始终阅读，在生成任何代码或配置之前
  4. 仅当 [SPEC] 不足以回答查询时，才阅读 [NOTE] 块
  5. 将 [?] 内容视为假设 —— 在回复中注明不确定性

Token 优化：对于大型文档，先扫描章节标题，然后只阅读相关章节中的 [SPEC] 和 [BUG] 块。

5. Claude 如何生成 HADS

[SPEC] 当被要求以 HADS 格式撰写文档时：

  1. 从头部块开始（标题、版本、元数据）
  2. 添加 AI manifest —— 始终包含，绝不跳过
  3. 将内容组织为带编号的 H2 章节
  4. 对于每个事实：写成 [SPEC] —— 简洁，用项目符号、表格或代码
  5. 对于每个“为什么”或背景：写成 [NOTE]
  6. 对于每个已知且有已确认修复方案的失败模式：写成 [BUG]
  7. 对于每个未经证实的说法：写成 [?]
  8. 以 changelog 章节结尾

[SPEC] 的内容规则：

  • 优先使用项目符号列表，而非散文
  • 多字段事实优先使用表格
  • 语法、格式、示例优先使用代码块
  • 散文最多 2 句话 —— 如需更多，移到 [NOTE]

[BUG] 的内容规则：

  • 始终包含：症状、原因、修复方案
  • 可选：受影响的版本、临时解决方案
  • 标题在同一行：**[BUG] Short description**

[NOTE] 将现有文档转换为 HADS 时：将事实提取到 [SPEC]，将叙述和历史移到 [NOTE]，将所有已知问题呈现为 [BUG]。不要在块类型之间重复内容。

6. 校验规则

[SPEC] 有效的 HADS 文档必须具有：

  • H1 标题
  • 前 20 行内的 **Version X.Y.Z**
  • 第一个内容章节之前的 AI manifest
  • 所有块标签都加粗：**[SPEC]**，而非 [SPEC]，也非 [SPEC]
  • [BUG] 块至少包含症状 + 修复方案

校验器：(计划中 —— 本版本尚未包含)

7. 示例交互

[SPEC]

用户：“为这个 REST API 写 HADS 文档” → 生成完整的 HADS 文档：头部、manifest、包含 [SPEC]/[NOTE]/[BUG] 块的章节

用户：“把这个 README 转换为 HADS 格式” → 将现有内容重组为 HADS 块，保留所有事实，添加 manifest

用户：“这个文档是有效的 HADS 吗？” → 检查：H1 标题、版本、manifest、块标签格式、BUG 块完整性

用户：“总结这个 HADS 文档” → 只阅读 [SPEC] 和 [BUG] 块，返回结构化摘要

用户：“这个 API 是做什么的？”（提供了 HADS 文档） → 阅读 manifest，阅读相关章节中的 [SPEC] 块，直接回答

8. 设计意图

[NOTE] HADS 之所以存在，是因为 AI 模型越来越多地在人类之前阅读文档。该格式在不为人类可读性妥协的前提下，针对这一现实进行了优化。

关键洞察：AI 清单是核心创新。它让即使小规模（7B）的模型也能知道该读什么、该跳过什么——而无需它们对文档结构进行推理。对于模型消费而言，显式优于隐式。

生成 HADS 时，把 [SPEC] 视为 API 表面，把 [NOTE] 视为注释。[BUG] 块是最有价值的内容——它们代表着来之不易的知识，能让其他人免于撞上同一堵墙。

9. 快速参考

[SPEC]

Tag       | Bold format    | Reader  | Required content
----------|----------------|---------|------------------
[SPEC]    | **[SPEC]**     | AI      | Facts, terse
[NOTE]    | **[NOTE]**     | Human   | Context, narrative
[BUG]     | **[BUG] ...**  | Both    | Symptom + fix
[?]       | **[?]**        | Both    | Unverified claims

清单最小要求：

## AI READING INSTRUCTION
Read `[SPEC]` and `[BUG]` blocks for authoritative facts.
Read `[NOTE]` only if additional context is needed.
`[?]` blocks are unverified.

评论

支持 Markdown