2.4 机器契约：JSON 让机器可读，Markdown 让人可读

AI Context Workspace 里所有的文件只有两种格式：Markdown 和 JSON。

Markdown 写给人看，也写给 AI 看。 背景文档、约定规范、任务说明，都用 Markdown。Markdown 是人类可读的纯文本，也是 AI 理解效率最高的格式之一。没有专有格式，没有二进制，没有需要渲染才能理解的富文本。

JSON 写给脚本看。 生命周期状态、检查结论、索引记录，都用 JSON。JSON 有固定字段，可以被脚本解析和校验，可以作为机器之间的契约。

为什么分开？

因为状态和说明是两回事。

"这个任务完成了"是一个状态，应该用 JSON 记录，因为它可以被脚本读取、校验、转换。"这个任务是怎么完成的"是一个说明，应该用 Markdown 记录，因为它需要人（和 AI）阅读和理解。

如果把状态混在 Markdown 里，脚本就得解析 Markdown 才能拿到状态，容易出错，也不稳定。如果把说明塞进 JSON，JSON 的可读性会急剧下降，不适合长篇叙述。

分开的核心原则：机器状态写入 JSON 契约，说明和证据写入 Markdown。

具体来说：

• 任务的 artifact.json 用 JSON 记录：ID、流程等级、生命周期状态、创建时间、更新时间、交付物列表。这些字段是固定的，脚本可以读、可以写、可以校验。
• 任务的执行记录用 Markdown 记录：做了什么、怎么做的、遇到了什么问题、有什么结论。这些内容不需要固定字段，需要灵活叙述。
• Review 结论用 JSON 记录检查项和结果，确保"是否通过"这个判断可以被脚本自动处理。
• 背景和约定用 Markdown，因为它们是给人（和 AI）阅读的，不是给脚本处理的。

这套设计的实际效果是什么？

你可以在脚本中批量检查所有活跃任务的状态，而不需要解析任何 Markdown。你可以在 CI 中配置一个检查：归档时必须有 Review 结论，且 Review 结论必须是 PASS 或被接受的 REVIEW。

同时，AI 在理解任务时，读的是 Markdown——自然的、可读的、有上下文的叙述。它不需要从 JSON 键值对中脑补故事。

机器契约保证了自动化可靠，Markdown 保证了人机可读。两者各司其职，不互相替代。