自包含文档
给 Agent 写的规格说明必须自包含——不能有隐含知识，不能说"参考现有实现"。文档本身就是完整的上下文。
什么是自包含文档？
当我们把任务交给 AI Agent 时，Agent 没有”团队记忆”，不知道上次站会讨论了什么，也不记得代码库里某个模块的设计初衷。自包含文档就是要解决这个问题：把所有必要的上下文、约束、验收标准打包进一份文档里，让 Agent 拿到文档后就能独立完成工作，不需要反复追问。
核心原则：
- 不依赖隐含知识——不能写”参照现有实现”，要把具体接口、数据结构写明
- 不依赖对话上下文——文档单独拿出来也能被理解
- 文档内自分段——每个部分有明确边界，Agent 可以分段处理
社区声音
“我要求 /architect 输出的 design 一定要去 self contained 的，就是避免 /coder 分不清信息的层级乱引用其它文档。” — 马工，2026-02-18
“human loop 结束了，自包含文档准备好了，然后就是全自动。” — Violet，2026-03-20
“自包含还是咱们群里因为我们个别人提到的概念。” — 胥克谦，2026-03-19
“所以才有胥老师的，文档自包含，文档内自分段——这两点是让 Agent 真正能用起来的关键。” — leo，2026-03-20
为什么重要？
传统的需求文档假设读者是人——人可以追问、可以查 Slack 历史、可以找同事确认。但 Agent 不会。如果文档不自包含，Agent 要么猜测（导致错误），要么停下来问你（打断自动化流程）。
自包含文档是 AI 原生工程的基础设施：文档质量直接决定 Agent 的输出质量。