人机协作文档标准

文档先被模型读，而不是人读

现在的技术文档越来越常被 AI 模型直接消费：写 API 文档、迁移指南、内部规范时，读者的第一程往往是模型而非人类。但通用 Markdown 没有区分事实与推测、已知坑与背景叙事。模型要么把过期注释当规范，要么漏掉关键的 [BUG] 警告，在错误前提下生成代码或配置。

HADS（Human-AI Document Standard）就是为此设计的一套 Markdown 约定。它不引入新文件格式，产物仍是标准 .md，不需要额外工具链。核心变化在于：文档结构显式暴露给模型，让模型知道该读什么、该跳过什么。

核心机制：四类块 + AI manifest

HADS 定义四种块类型：

• [SPEC] — 事实性内容，模型的 ground truth。要求简短，优先用列表、表格、代码块；正文最多两句。
• [NOTE] — 背景、设计意图、历史脉络。仅当 [SPEC] 不足以回答用户问题时才读。
• [BUG] — 已知失败模式，必须包含症状、原因、修复。标题可写在 tag 后：**[BUG] Short description**。
• [?] — 未验证的假设，模型回答时应说明不确定性。

文档还必须包含：H1 标题、前 20 行内的 **Version X.Y.Z** 声明、以及首个内容小节之前的 AI manifest。manifest 是这套规范的关键设计：它显式告诉模型读取顺序与跳过策略，而不是让模型自行推断文档结构。对 7B 级别的小模型来说，这比隐式约定更可靠。

读取优先级明确：先 manifest → 全部 [SPEC] → 全部 [BUG]（生成代码前必读）→ 按需 [NOTE] → [?] 仅作假设。生成文档时，事实进 [SPEC]，原因进 [NOTE]，已知问题进 [BUG]，不跨块重复内容。

适用边界

这套规范目前是格式约定，不是自动工具。校验器（Validator）仍在计划中，尚未包含在当前版本。有效性依赖生成方和阅读方都遵守约定；如果读者模型不识别 manifest 与块优先级，收益会打折扣。它也不替代版本控制、评审流程或文档托管系统，只负责把文档组织成对人和模型都友好的形式。