需要让技术文档同时被人和 AI 高效读取时，用…

当你写技术文档、把已有 README/文档转成 HADS 格式、校验 HADS 文档，或想让文档对 AI 更省 token 时，用这套纯 Markdown 约定（SPEC/NOTE/BUG/? + AI manifest）。

适用场景

解决思路

1. 以标准 Markdown（`.md`）编写，不需要任何工具链；只用四种块类型：`**[SPEC]**`、`**[NOTE]**`、`**[BUG]**`、`**[?]**`。
2. 块标签必须加粗且独占一行（写 `**[SPEC]**`，不能写 `[SPEC]` 或 `*[SPEC]*`）；内容紧跟在标签之后，标签与内容之间不留空行。
3. 同一小节内允许出现多个不同类型的块；允许给 BUG 块加标题写成 `**[BUG] 简短描述**`；禁止在块内嵌套块。
4. 按固定顺序放置必需元素：H1 标题 → 前 20 行内的 `**Version X.Y.Z**` → 首个内容小节之前的 AI manifest → H2 内容小节（必要时 H3 子小节）。
5. 在 `## AI READING INSTRUCTION` 小节写 AI manifest，明确告知 AI：读 `[SPEC]` 与 `[BUG]` 获取权威事实，仅在需要补充上下文时才读 `[NOTE]`，`[?]` 为未验证内容需按更低置信度对待。
6. `[SPEC]` 用于写权威事实、写法简洁：优先用无序列表而非段落，多字段事实用表格，语法/格式/示例用代码块；正文最多 2 句话，超出部分移到 `[NOTE]`。
7. `[NOTE]` 用于写人类可读的上下文、历史沿革和示例（AI 可以跳过）。
8. `[BUG]` 用于写已验证的失败及其修复，必填字段 symptom、cause、fix；可选字段 affected versions、workaround。
9. `[?]` 用于写未验证或推断出来的内容，必须显式标注其低置信度。
10. 生成 HADS 文档时：先写头部块（标题、版本、元数据），紧接着写 AI manifest（必须写，任何情况下都不能省略）。
11. 把内容组织成带编号的 H2 小节。
12. 逐条归类落块：每条事实写成 `[SPEC]`，每处“为什么”或背景写成 `[NOTE]`，每个已确认修复的已知失败模式写成 `[BUG]`，每个未证实的说法写成 `[?]`。
13. 文档末尾加 changelog 小节。
14. 把已有文档转换为 HADS 时：把事实抽取到 `[SPEC]`，把叙述与历史移到 `[NOTE]`，把所有已知问题暴露为 `[BUG]`；不要在不同块类型之间重复内容。
15. 读取 HADS 文档时按此顺序：先找到并读 AI manifest；再读所有 `[SPEC]` 块（视为 ground truth）；所有 `[BUG]` 块都要读，尤其在生成任何代码或配置之前；只有当 `[SPEC]` 不足以回答时才读 `[NOTE]`；把 `[?]` 内容当作假设，并在回答中说明不确定性。
16. 对大型文档做 token 优化：先扫一遍小节标题，然后只读相关小节内的 `[SPEC]` 与 `[BUG]` 块。
17. 校验文档时逐项检查：有 H1 标题；前 20 行内有 `**Version X.Y.Z**`；首个内容小节之前有 AI manifest；所有块标签都是加粗格式；每个 `[BUG]` 块至少包含 symptom + fix。
18. 被要求总结一份 HADS 文档时：只读 `[SPEC]` 与 `[BUG]` 块，返回结构化摘要。
19. 被问某个 API 在做什么（已提供 HADS 文档）时：先读 manifest，再读相关小节里的 `[SPEC]` 块，然后直接作答。
20. 被要求为某接口/系统写 HADS 文档时，产出完整文档：头部、manifest、各小节及 `[SPEC]`/`[NOTE]`/`[BUG]` 块。
21. 被要求判断“这份文档是否是合法 HADS”时，按第 18 条那套检查项逐条核对并给出结论。

适用边界 · 注意事项

• 文档纯属叙事、教程或营销文案，没有可抽取的事实清单，也不需要被 AI 消费时。
• 期望用自动校验器验证格式时——本版本的 validator 仍是 planned 状态、尚未提供，只能人工按检查项核对。
• 需要非 Markdown 的输出格式，或文档必须内联在无 Markdown 渲染能力的环境中时。