Back to Details

hads

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

HADS Claude Skill

HADS Claude 技能

Version 1.0.0 · Human-AI Document Standard · 2026 · HADS 1.0.0
版本 1.0.0 · 人机文档标准 · 2026 · HADS 1.0.0

AI READING INSTRUCTION

AI 阅读说明

This skill teaches Claude how to read, generate, and validate HADS documents. Read all 
[SPEC]
blocks before responding to any HADS-related request. Read 
[NOTE]
blocks if you need context on intent or edge cases.
本技能教Claude如何读取、生成和验证HADS文档。 在响应任何HADS相关请求前，请先阅读所有
[SPEC]
块。 如果你需要了解意图或边界场景的上下文，请阅读
[NOTE]
块。

1. WHAT IS HADS

1. 什么是HADS

[SPEC]
  • HADS = Human-AI Document Standard
  • Convention for Markdown technical documentation
  • Four block types: 
    **[SPEC]**
    , 
    **[NOTE]**
    , 
    **[BUG]**
    , 
    **[?]**
  • Every HADS document requires: H1 title, version declaration, AI manifest
  • AI manifest appears before first content section, tells AI what to read/skip
  • File extension: 
    .md
    — standard Markdown, no tooling required
[SPEC]
  • HADS = Human-AI Document Standard（人机文档标准）
  • Markdown技术文档编写约定
  • 四种块类型：
    **[SPEC]**
    、
    **[NOTE]**
    、
    **[BUG]**
    、
    **[?]**
  • 所有HADS文档都必须包含：H1标题、版本声明、AI说明清单
  • AI说明清单放在第一个内容章节之前，告知AI需要读取/跳过的内容
  • 文件扩展名：
    .md
    — 标准Markdown格式，无需额外工具支持

2. BLOCK TYPES

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.
Block tag rules:
  • Bold, on its own line: 
    **[SPEC]**
  • Content follows immediately (no blank line between tag and content)
  • Multiple blocks of different types allowed per section
  • Titled BUG blocks allowed: 
    **[BUG] Short description**
  • No nesting of blocks inside blocks
[SPEC]
**[SPEC]**   权威事实，简洁表述，可用无序列表、表格、代码，AI必须始终读取
**[NOTE]**   面向人类的上下文、历史、示例，AI可跳过
**[BUG]**    已确认的故障 + 修复方案，必填字段：症状、原因、修复方案，必须始终读取
**[?]**      未验证/推断内容，可信度较低，必须标记风险
块标签规则：
  • 加粗，单独占一行：
    **[SPEC]**
  • 内容紧跟标签（标签和内容之间不要有空行）
  • 每个章节允许存在多个不同类型的块
  • 允许带标题的BUG块：
    **[BUG] 简短描述**
  • 不允许块之间嵌套

3. REQUIRED DOCUMENT STRUCTURE

3. 必备文档结构

[SPEC]
markdown
undefined
[SPEC]
markdown
undefined

Document Title

文档标题

Version X.Y.Z · Author · Date · [metadata]
版本 X.Y.Z · 作者 · 日期 · [元数据]

AI READING INSTRUCTION

AI 阅读说明

Read 
[SPEC]
and 
[BUG]
blocks for authoritative facts. Read 
[NOTE]
only if additional context is needed. 
[?]
blocks are unverified — treat with lower confidence.
读取
[SPEC]
和
[BUG]
块获取权威事实 仅当需要额外上下文时读取
[NOTE]
块 
[?]
块内容未验证 — 可信度较低

1. First Section

1. 第一个章节

[SPEC] ...

Required elements in order:
1. H1 title
2. `**Version X.Y.Z**` in header (first 20 lines)
3. AI manifest section before first content section
4. Content sections (H2), subsections (H3)

---
[SPEC] ...

必备元素按顺序排列：
1. H1标题
2. 头部包含`**版本 X.Y.Z**`（前20行内）
3. AI说明清单放在第一个内容章节之前
4. 内容章节（H2）、子章节（H3）

---

4. HOW CLAUDE READS HADS

4. Claude 如何读取HADS

[SPEC] When encountering a HADS document:
  1. Find and read the AI manifest first
  2. Read all 
    [SPEC]
    blocks — these are ground truth
  3. Read all 
    [BUG]
    blocks — always, before generating any code or config
  4. Read 
    [NOTE]
    blocks only if 
    [SPEC]
    is insufficient to answer the query
  5. Treat 
    [?]
    content as hypothesis — note uncertainty in response
Token optimization: for large documents, scan section headings first, then read only 
[SPEC]
and 
[BUG]
blocks in relevant sections.
[SPEC] 遇到HADS文档时：
  1. 首先找到并阅读AI说明清单
  2. 读取所有
    [SPEC]
    块 — 这些是事实基准
  3. 读取所有
    [BUG]
    块 — 必须在生成任何代码或配置前读取
  4. 仅当
    [SPEC]
    不足以回答查询时才读取
    [NOTE]
    块
  5. 将
    [?]
    内容视为假设 — 回复中需标注不确定性
Token优化：针对大型文档，先扫描章节标题，仅读取相关章节的
[SPEC]
和
[BUG]
块。

5. HOW CLAUDE GENERATES HADS

5. Claude 如何生成HADS

[SPEC] When asked to write documentation in HADS format:
  1. Start with header block (title, version, metadata)
  2. Add AI manifest — always include, never skip
  3. Organize content into numbered H2 sections
  4. For each fact: write as 
    [SPEC]
    — terse, bullet or table or code
  5. For each "why" or context: write as 
    [NOTE]
  6. For each known failure mode with confirmed fix: write as 
    [BUG]
  7. For each unverified claim: write as 
    [?]
  8. End with changelog section
Content rules for 
[SPEC]
:
  • Prefer bullet lists over prose
  • Prefer tables for multi-field facts
  • Prefer code blocks for syntax, formats, examples
  • Maximum 2 sentences of prose — if more needed, move to 
    [NOTE]
Content rules for 
[BUG]
:
  • Always include: symptom, cause, fix
  • Optional: affected versions, workaround
  • Title on same line: 
    **[BUG] Short description**
[NOTE] When converting existing documentation to HADS: extract facts into 
[SPEC]
, move narrative and history to 
[NOTE]
, surface all known issues as 
[BUG]
. Do not duplicate content between block types.
[SPEC] 当被要求编写HADS格式的文档时：
  1. 从头部块开始（标题、版本、元数据）
  2. 添加AI说明清单 — 必须包含，不得省略
  3. 将内容组织为编号的H2章节
  4. 所有事实写入
    [SPEC]
    块 — 简洁表述，可用列表、表格或代码
  5. 所有「原因说明」或上下文写入
    [NOTE]
    块
  6. 所有已知故障模式及确认的修复方案写入
    [BUG]
    块
  7. 所有未验证的声明写入
    [?]
    块
  8. 末尾添加更新日志章节
[SPEC]
内容规则：
  • 优先使用无序列表而非段落文字
  • 多字段事实优先使用表格
  • 语法、格式、示例优先使用代码块
  • 最多包含2句段落文字 — 更多内容请移至
    [NOTE]
    块
[BUG]
内容规则：
  • 必须包含：症状、原因、修复方案
  • 可选：受影响版本、临时解决方案
  • 标题和标签在同一行：
    **[BUG] 简短描述**
[NOTE] 将现有文档转换为HADS格式时：将事实提取到
[SPEC]
块，将叙述性内容和历史记录移至
[NOTE]
块，将所有已知问题整理为
[BUG]
块。不要在不同块类型之间重复内容。

6. VALIDATION RULES

6. 验证规则

[SPEC] A valid HADS document must have:
  • H1 title
  • **Version X.Y.Z**
    in first 20 lines
  • AI manifest before first content section
  • All block tags bold: 
    **[SPEC]**
    not 
    [SPEC]
    not [SPEC]
  • [BUG]
    blocks contain at minimum symptom + fix
Validator: (planned — not yet included in this release)
[SPEC] 合法的HADS文档必须包含：
  • H1标题
  • 前20行内存在
    **版本 X.Y.Z**
  • AI说明清单位于第一个内容章节之前
  • 所有块标签已加粗：是
    **[SPEC]**
    而非
    [SPEC]
    或*[SPEC]*
  • [BUG]
    块至少包含症状+修复方案
验证工具：(规划中 — 本次版本暂未包含)

7. EXAMPLE INTERACTIONS

7. 交互示例

[SPEC]
User: "Write HADS documentation for this REST API" → Generate full HADS document: header, manifest, sections with [SPEC]/[NOTE]/[BUG] blocks
User: "Convert this README to HADS format" → Restructure existing content into HADS blocks, preserve all facts, add manifest
User: "Is this document valid HADS?" → Check: H1 title, version, manifest, block tag formatting, BUG block completeness
User: "Summarize this HADS document" → Read only [SPEC] and [BUG] blocks, return structured summary
User: "What does this API do?" (HADS doc provided) → Read manifest, read [SPEC] blocks in relevant sections, answer directly
[SPEC]
用户："为这个REST API编写HADS文档" → 生成完整HADS文档：头部、说明清单、带[SPEC]/[NOTE]/[BUG]块的章节
用户："将这个README转换为HADS格式" → 将现有内容重构为HADS块，保留所有事实，添加说明清单
用户："这个文档是合法的HADS吗？" → 检查项：H1标题、版本、说明清单、块标签格式、BUG块完整性
用户："总结这份HADS文档" → 仅读取[SPEC]和[BUG]块，返回结构化摘要
用户："这个API有什么功能？"（已提供HADS文档） → 读取说明清单，读取相关章节的[SPEC]块，直接作答

8. DESIGN INTENT

8. 设计意图

[NOTE] HADS exists because AI models increasingly read documentation before humans do. The format optimizes for this reality without sacrificing human readability.
Key insight: the AI manifest is the core innovation. It lets even small (7B) models know what to read and what to skip — without requiring them to reason about document structure. Explicit is better than implicit for model consumption.
When generating HADS, think of 
[SPEC]
as the API surface and 
[NOTE]
as the comments. 
[BUG]
blocks are the most valuable content — they represent hard-won knowledge that saves others from hitting the same wall.
[NOTE] HADS的诞生背景是现在AI模型读取文档的频率已经高于人类。该格式在不牺牲人类可读性的前提下，针对这一现状做了优化。 核心设计思路：AI说明清单是核心创新点。哪怕是小参数（7B）模型也能明确知道该读什么、跳过什么 — 不需要它们自行推理文档结构。对AI消费来说，显式规则优于隐式规则。 生成HADS时，可以把
[SPEC]
看作API接口，
[NOTE]
看作注释。
[BUG]
块是最有价值的内容 — 它们代表了来之不易的经验，能避免其他人踩同样的坑。

9. QUICK REFERENCE

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
Manifest minimum:
markdown
undefined
[SPEC]
标签       | 加粗格式        | 读取方  | 必备内容
----------|----------------|---------|------------------
[SPEC]    | **[SPEC]**     | AI      | 事实内容，简洁表述
[NOTE]    | **[NOTE]**     | 人类    | 上下文、叙述内容
[BUG]     | **[BUG] ...**  | 双方    | 症状 + 修复方案
[?]       | **[?]**        | 双方    | 未验证声明
最少必填说明清单：
markdown
undefined

AI READING INSTRUCTION

AI 阅读说明

Read 
[SPEC]
and 
[BUG]
blocks for authoritative facts. Read 
[NOTE]
only if additional context is needed. 
[?]
blocks are unverified.
undefined
读取
[SPEC]
和
[BUG]
块获取权威事实 仅当需要额外上下文时读取
[NOTE]
块 
[?]
块内容未验证
undefined