17 AGENTS.md 当同一个目录里跑着好几个 agent，git 纪律必须写死

先记住这一句

这是本书里最容易被低估的一章。多数项目的 agent 规则文件写的是「用 2 空格缩进」「别加 emoji」这类偏好；pi 的这份里有相当篇幅在解决一个真实的分布式问题——多个写者共享一个工作区。

推论只有一条，但很硬：任何「作用于整个工作区」的 git 操作都是禁止的，因为它必然踩到别人的未提交改动。

前提写在开头

Multiple pi sessions may be running in this cwd at the same time, each modifying
different files. Git operations that touch unstaged, staged, or untracked files
outside your own changes will stomp on other sessions' work. Follow these rules:

禁令清单：七条，无例外

Never run (destroys other agents' work or bypasses checks):

- `git reset --hard`, `git checkout .`, `git clean -fd`, `git stash`,
  `git add -A`, `git add .`, `git commit --no-verify`.

与之配套的是正向要求：只提交你这个会话改过的文件；用显式路径 git add <path>；提交前先 git status 确认只暂存了自己的文件。AGENTS.md:55

rebase 冲突的处理也顺着同一逻辑：只解决自己改过的文件里的冲突；冲突出现在你没改过的文件里，就中止并问用户；永不 force push。AGENTS.md:67

其余规则的共同形状：给出理由，或给出替代动作

连「怎么跑测试」都规定得极细

「永远不要直接跑完整 vitest 套件」——因为里面含 e2e 测试，一旦环境里存在 endpoint/auth 环境变量就会激活，产生真实的 provider 调用和费用。替代方案给到了具体命令行。AGENTS.md:30

对 packages/coding-agent/test/suite/，规则是用 harness + faux provider，不许用真 provider API、密钥或付费 token。AGENTS.md:34 甚至规定了 issue 回归测试的存放路径与文件命名格式 <issue-number>-<short-slug>.test.ts。AGENTS.md:35

最后一条：冲突时怎么办

If the user's instructions conflict with any rule in this document, ask for explicit
confirmation before overriding. Only then execute their instructions.

为什么「多会话共享工作区」这个前提值得整段规则

常规做法是给每个 agent 会话开一个 git worktree，物理隔离。pi 团队显然选择了不隔离——同一个 cwd 跑多个会话。

好处推得出来：共享工作区意味着共享构建产物、共享 node_modules、共享正在运行的 dev server；一个会话改了类型，另一个会话立刻能看到。对一个 25 万行的 monorepo，重建成本很高，隔离的代价是实打实的。

代价则是必须靠纪律替代隔离——而纪律的执行者是 LLM。所以规则写成了命令级黑名单而不是原则：模型可以误判「这个 git checkout . 应该没事」，但很难误判「这条命令在禁用清单里」。禁令的具体程度，是对执行者可靠性的一种补偿。

这份文件的写法比内容更值得学

通读下来，有效规则都符合同一个模式：不要 X + 因为 Y + 改为做 Z。三段齐全的规则（比如 models.generated.ts 那条）几乎不会被误读；只有「不要 X」的规则容易被模型在边缘情况下自行放宽。

另一个细节是预先消除犹豫。「带上重新生成的 diff 总是 OK 的，即使包含无关的上游模型元数据变化」——这句话存在的原因是：一个谨慎的 agent 看到自己的改动里混进了无关 diff，会停下来问。文档提前回答了这个问题，省掉一次往返。

与 CONTRIBUTING.md 的分工

AGENTS.md 的开头就写明它是给人和 agent 共用的项目规则，而贡献者门槛在 CONTRIBUTING.md（第 18 章）。README.md:50

这个分工是清晰的：AGENTS.md 管「在这个仓库里怎么干活」，CONTRIBUTING.md 管「你有没有资格进来干活」。而 CONTRIBUTING.md 里那句「如果你用 agent，请从 pi 根目录运行，让它自动读到 AGENTS.md」，把两者接了起来。CONTRIBUTING.md:19

• 全部靠模型遵守，没有任何强制。禁用清单是文本，不是 hook。一个不读 AGENTS.md 的 agent（或读了但被长上下文冲淡的 agent）照样能跑 git add -A。唯一有真正强制力的是 pre-commit hook，而它只管 lockfile。
• 165 行的规则文件会占据上下文，并随压缩而衰减。在一个长会话里，这份规则是最早被压缩掉的内容之一（第 06 章：没有「pin 住某条消息」的机制）。会话越长，纪律越松——这个失效模式是结构性的。
• 「同一 cwd 多会话」这个前提对外部贡献者通常不成立。大部分人只跑一个会话，于是那段最重要的规则对他们是纯粹的开销，也更容易被判断为「不适用于我」。
• 规则与代码可能不同步。它引用了具体的常量名（DEFAULT_EDITOR_KEYBINDINGS）、路径、命令。这些一旦重构，规则就指向不存在的东西——而没有任何校验器检查这件事。

检查过并确认：AGENTS.md 中引用的 DEFAULT_EDITOR_KEYBINDINGS 与 DEFAULT_APP_KEYBINDINGS 在锚定 SHA 上确实存在于 packages/coding-agent/src，未构成漂移。

• 规则写成「不要 X + 因为 Y + 改为做 Z」三段式。只有「不要 X」的规则会在边缘情况被模型自行放宽；给了替代动作的不会。 适用条件：所有 agent 规则文件。这是全章最普适的一条。
• 把危险操作写成具体命令的黑名单，而不是抽象原则。「不要做破坏性 git 操作」需要判断；「不要跑 git add -A」不需要。执行者越不可靠，规则就该越具体。 适用条件：执行者是 LLM。对人类同事，抽象原则反而更好——具体清单显得不信任。
• 预先回答「agent 会在哪里停下来问」。比如「带上无关的重新生成 diff 是 OK 的」——一句话省掉一次往返。 适用条件：你观察到 agent 反复在同一处犹豫。这条只能靠积累，写不出来第一版。
• 如果你选择「共享工作区 + 纪律」而不是「worktree 隔离」，要清楚你把可靠性押在了模型的服从上。并且知道这个服从会随上下文长度衰减。 代价：长会话末期的纪律最松，而那恰恰是改动最多、最累的时候。