AI Agent 总是丢失上下文？一个 FLOCK.md 文件给出知识地图

AI agent 改变了我的代码库里谁来写文档。但它们没有改变谁在后来去找这些文档。

在过去一年里，agent 写掉了我的项目中大多数的计划、规格说明和工作日志。它们写得很快，写得足够好——而且写到哪里取决于当天被指向哪里。docs/、notes/、planning/、仓库根目录、有人粘贴到工单里的 gist。每个文件在创建那天都是有意义的。

然后你六周后回来，试图回答一个简单的问题：我们为什么这样决定？决定是存在的。它被写在了某个地方。你找不到它，写下它的那个 agent 也找不到它——而一个找不到决定的 agent 不会停下来。它会自信地重新辩论它，或者把它重构掉。

这就是我反复碰到的失败。不是文档缺失——而是文档找不到，写得比任何人整理的速度都快。

FLOCK.md 是一个位于仓库根目录的 markdown 文件，只回答一个问题：这个仓库的知识在哪里？没有 schema，没有工具，没有构建步骤。最小可用版本是一张表：

# FLOCK.md

## Docs Map

| Type | Where | Answers |
|---|---|---|
| readme | README.md | What is this project and how do I run it? |
| design note | docs/ | Why is a piece of the system built the way it is? |
| decision | docs/decisions/ | What did we decide, when, and what was rejected? |

这是一种合规的采用方式。不在表中的位置，按照定义，就不是仓库知识契约的一部分——这听起来很官僚，直到你亲眼看到一个 agent 真正遵守它。指向一个带有 Docs Map 的仓库，agent 就会停止发明目录结构。它读取表格，然后把文档放到表格指定的位置。

四个问题，四份文档

对于跑满设计到交付完整周期的项目，标准定义了一个叫做问题链的生命周期。一项工作在四个问题都有书面答案且按顺序完成后才算结束：

一份索引回答第五个问题——一切在哪里、处于什么状态——对每个工作单元都各用一行文字汇总。

一个特性的三份文档相互链接，所以只要落到其中任何一份上，就能跳转到另外两份。如果你曾经打开过一份规格说明却不知道它有没有被实现——或者打开代码却不知道它有没有对应的规格说明——三向链接正是为了堵上这个缺口。

实践中最重要的分割是蓝图 vs 工作日志：我们计划了什么 vs 实际发生了什么。Agent 极其擅长写计划，极其不擅长记住现实偏离了计划。把两者作为独立文档保存，意味着分歧被记录下来而不是被掩盖。

为 agent 时代而建的部分

标准的历史规则是我最想捍卫的部分，因为它们是为一种在 agent 出现之前几乎不存在的失败模式而生的：

决定携带日期。（decided 2026-08-22）以内联方式写在决定旁边。

原地替代。推翻一个决定不得删除它。旧文本保留（删除线即可），标记 SUPERSEDED 和日期，新决定写在旁边。

记录未被选中的路。当一个替代方案被认真考虑过但被拒绝时，写下那个替代方案和拒绝的原因。

这就是第三条规则值得存在的理由：读取你代码库的 agent 对你们已经讨论过的辩论毫无记忆。如果被拒绝的选项没有被写下来，agent 会在你花了一整天否决它的三周后，再次把它提出来——措辞漂亮、理由充分、信心十足。记录下来的拒绝才是阻止同一场辩论被以谋生为由的东西重新打开的东西。

AGENTS.md 不是已经做了这件事吗？

没有——它们是互补的，边界很清晰：

如果你有 AGENTS.md——或者 CLAUDE.md，或者你的工具读取的任何指令文件——一行字连接它们：Docs and project conventions: see FLOCK.md.

这一行字比它看起来更重要，有一个今年特有的原因：没有任何一个模型的训练数据里有过这个新标准。Agent 从没听说过 FLOCK.md——但它已经在每个 session 开始时读取你的指令文件了，所以它通过一个从第一天就信任的文件找到了地图。

采用是一种声明，不是迁移。规范的典型位置是默认值；你的 Docs Map 声明你真正的路径——所以什么都不用动。在一个全新的仓库里，按照发货状态复制最小模板，它的默认值就是采用。在已经有文档的仓库里，写下指向文档现有位置的 Docs Map 行，不要回溯：历史惯例从采用日起适用。无论哪种方式，规范都明确说明采用不得移动、重命名或重写现有文件。

如果你更愿意把采用本身交给 agent，仓库的 Quick start 根据仓库状态路由——全新、已有文档、迁移已有文档系统、升级旧采用——并为每条需要它的路径提供一条护栏 prompt。当你想验证结果时，规范仓库自带了合规检查器——node tools/check.mjs <repo>，零依赖——只会在 MUST 违规时失败：所有未标记 MUST 的都是指导性内容，检查器与规范保持着同一条界线。

完整规范只有一页：github.com/repoflock/flock.md。

它是 CC BY 4.0，且刻意与工具无关——它零工具运行，在任何编辑器里可用，配合任何 agent。它从 RepoFlock 背后的工作惯例中提取出来，更早的版本已在该项目自己的仓库中投入生产使用，但它没有任何部分需要任何特定工具。它是一个 markdown 文件。这就是它的设计初衷。

我真的很想听听它在什么地方会坏掉。如果你的仓库有一种文档布局不符合 Docs Map 的形状，或者你的 agent 工作流有一种历史规则没覆盖到的失败模式——issues 是开放的。