编码智能体适合干一个下午的活，但撑不过一个季度。下面是一小组文件和规则——附带实际配置——无论你在同一个仓库上运行一个智能体还是一群智能体，它们都能防止质量在数月和数千次编辑中衰减。

与编码智能体的第一次会话是清爽的：它读取代码，做出干净的修改，编写测试。到第三十次时，某些东西已经腐化了——它重新发现相同的文件，与三周前自己做出的决定相矛盾，猜测测试命令，并悄悄停止编写测试，因为没人要求它这么做。解决办法不是更好的模型。而是围绕模型的操作系统：一部宪法、一条自主边界、分层上下文、持久记忆、一个审查小组，以及一个编辑后钩子。

为什么是套具，而不是模型

一个有用的说法是：智能体是模型加上它的套具——围绕原始模型的提示词、工具、上下文策略、钩子、沙箱、子智能体、可观测性。模型可能只占决定你是否能在一个季度内获得可用软件的十分之一；套具占其余部分。证据很直白。在公开的 Terminal-Bench 2.0 基准测试中，LangChain 将一个编码智能体从 30 名开外提升到前 5 名——从 52.8% 跃升至 66.5%，即 13.7 个百分点——仅通过改变套具（系统提示词、工具，以及自验证和循环检测等中间件），保持模型不变。

诚实地审视，大多数智能体失败不仅仅是模型失败——它们是配置失败：缺少工具、规则模糊、缺少护栏、上下文窗口塞满噪声。因此，当质量在一个长期项目中衰减时，杠杆几乎从来不是“等待一个更聪明的模型”。而是套具——与模型不同，套具是你自己构建的。本文的其余部分就是具体的做法。

会衰减的四样东西（以及修复每一样的产物）

• 纪律——跳过测试、扩大范围 → 每次会话都读取的一部宪法
• 上下文——重新学习仓库 → 分层的 CONTEXT.md，由钩子维护
• 记忆——重复已纠正的错误 → 持久的逐事实记忆文件
• 审查——一个盲点被统一应用 → 一个多视角智能体小组

1. 一部宪法（CLAUDE.md / AGENTS.md）

一个精简的、始终加载的文件，陈述不可协商的事项：工作流循环（Plan → Document → Implement → Test → Review → Commit）、自主边界、质量标准（测试在同一 diff 中、无死代码、约定式提交），以及适配器纪律（领域代码中不使用供应商 SDK）。保持简短——它每一轮都会被读取，所以每一行都消耗上下文预算。

2. 一条自主边界，而不是一个终止开关

最高杠杆的单一决策：让智能体在所有可逆的事情上自由运行，只在两件不可逆的事情上暂停——推送到远程和部署。作为权限配置：

{
  "permissions": {
    "allow": ["Read","Edit","Write","Grep","Glob",
              "Bash(git add:*)","Bash(git commit:*)",
              "Bash(npm test:*)","Bash(npm run:*)","Bash(npm ci:*)","Bash(pytest:*)"],
    "ask":   ["Bash(git push:*)","Bash(npm publish:*)","Bash(aws:*)","Bash(terraform apply:*)","Bash(kubectl apply:*)"],
    "deny":  ["Bash(git push --force:*)","Bash(git push -f:*)","Bash(*--no-verify*)"]
  }
}

现在它可以工作一个小时并提交十几次；你在推送时审查，而不是在每次按键时审查。“自主”的爆炸半径保持有界，因为不可逆操作是唯一被门控的。（验证你的运行器的匹配语义——前缀与子串不同——以便 --no-verify / --force 拒绝和 npm publish 真正触发；像 npm:* 这样的宽泛通配符会悄悄允许 npm publish。）

3. 智能体维护的分层上下文

一个巨大的上下文文件会逐渐腐化并耗尽预算。将其分层：

• 根 CONTEXT.md —— 地图：这是什么、如何运行/测试、一行模块索引、不变量、状态存放位置。上限约 200 行；会话启动时读取。
• 每个模块的 CONTEXT.md —— 职责、关键文件、依赖、注意事项、如何仅测试该模块。编辑该模块前阅读。
• DECISIONS.md —— 仅追加：日期、决策、原因、被拒绝的替代方案。（当多个智能体共享仓库时，这一项值得单独深入处理——在第二部分中展开。）

规则：过时的上下文是一个 bug，应在使其失效的同一次变更中修复——而不是“以后”。

4. 持久记忆 + 一个小型知识图谱

上下文描述代码；记忆保存代码无法跨会话告诉你的内容——每个文件一条事实，并建立索引：

memory/
  MEMORY.md                  # index: one line per fact
  user-prefers-X.md          # type: user | feedback | project | reference
  graph.jsonl                # {from, rel, to} — modules/decisions as nodes; depends-on/adapts/supersedes

图谱回答了智能体最不擅长的问题：“如果我改这个，什么会坏？”

5. 一个评审小组，而不是一个评审者

与其进行一次自我评审，不如并行运行专注的子智能体，每个只用一个视角，严格输出：

product   — solves the stated problem? scope creep?   (plan stage)
architect — correctness, data model, failure modes, coupling
infra     — resource limits, deploy/rollback, resilience
security  — authz, input validation, secrets, audit trail
test-eng  — is the suite real, or happy-path theater?  (per change)
→ each returns: [BLOCKER|MAJOR|MINOR] (confidence%) — file:line — issue — fix ; VERDICT

只有高置信度的 BLOCKER/MAJOR 才作为门禁。多样化的视角能捕捉单次检查遗漏的问题；置信度阈值可避免你被琐碎问题淹没。（注意：这些是评审同一变更的并行智能体——不同于进行变更的并行智能体，后者是第二部分的核心问题。）

6. 一个编辑后钩子，让任何东西都不会悄悄漂移

将所有内容串联起来的部分——在每次编辑后触发并输出一份检查清单（一个 PostToolUse 钩子）：

在 settings.json 中接入它，指向一个小脚本：

{ "hooks": { "PostToolUse": [
  { "matcher": "Edit|Write|MultiEdit",
    "hooks": [ { "type": "command", "command": "python3 .claude/hooks/post-edit.py" } ] } ] } }

# .claude/hooks/post-edit.py — reads the tool event on stdin, emits a checklist as context
import json, sys
ev = json.load(sys.stdin)
path = ev.get("tool_input", {}).get("file_path", "the edited file")
checklist = (f"Post-edit refresh for {path}: (1) update the nearest CONTEXT.md if responsibility/"
             "key-files/gotchas changed; (2) append a memory/graph edge on a dep/API change; "
             "(3) log a DECISIONS.md line on a precedent; (4) update memory on a durable fact. "
             "Make these edits in THIS change — stale context is a bug.")
print(json.dumps({"hookSpecificOutput": {"hookEventName": "PostToolUse", "additionalContext": checklist}}))

它会输出一份检查清单；智能体在同一 diff 中进行编辑——可审查，而非静默重写。它是一个提醒，而不是静默重写器——你始终能看到它改了什么。

循环，一行概括

session start: read root CONTEXT.md + MEMORY.md
per task:      plan → panel reviews plan → you approve →
               implement subtask (tests in same diff) → panel reviews diff →
               full test+lint → commit → hook refreshes context/memory/graph → next
only stops:    push and deploy

这就是一个智能体的完整约束框架：六个工件加一个循环。每个都只是几行配置或一个 markdown 文件；合在一起，它们决定了一个智能体是只能辉煌一个下午，还是能在第一千次编辑时依然值得信赖。

第二部分——从一个智能体到一群智能体

一个智能体，以这种方式被约束，可以保持数月的高效。现在让多个智能体同时运行在同一个仓库上——一种上述工件都无法应对的新故障模式出现了：智能体之间发生冲突。它们编辑相同的文件，互相撤销对方的工作，并重新争论某个智能体已经做出的决定。直觉是让它们“沟通”。这既不可扩展也不可靠。真正有效的方法恰恰是让人类团队实现并行化的方式：通过共享的、书面化的状态来协调，而非对话——并把来之不易的决策记录下来，这样任何人，无论碳基还是硅基，都无法静默地推翻它们。

7. 通过状态协调，而非聊天（共识主动性）

智能体之间不应互相发消息。它们读写一小组共享文件，这些文件编码了工作的状态——谁拥有什么、已决定了什么、什么已被认领、什么已完成。每个智能体作用于世界（仓库加上这些文件）；下一个智能体读取世界来决定做什么。协调成为共享状态的一种属性，而非对话的属性——这意味着它能在重启后存活，并且可审计。昆虫正是通过这种方式协调大规模建造的，通过改变和读取共享环境而非交谈。同样的技巧在这里也适用。

所有权映射——谁拥有哪些路径。默认按目录划分所有权；编辑自己区域之外的内容需要认领。

| path                  | owner    | notes                       |
| core/**               | agent-B  | agent-A reads, doesn't edit |
| services/service-a/** | agent-A  |                             |
| shared/contracts/**   | shared   | claim required to change    |

认领/释放——低成本的互斥，无需锁服务器：

## CLAIM 2026-06-10T14:20Z · agent-A · task-114 · services/service-a/**
working: add retry to the fetch step    est: 40m
## RELEASE 2026-06-10T14:58Z · agent-A · task-114 · commit a1b2c3d

规则：在认领之前，扫描最近几小时内是否存在针对重叠路径的未关闭 CLAIM；如果发现，就选择不同的工作。要诚实地说明这是建议性/乐观的，而非锁——两个智能体可能都扫描了，都没看到任何东西，然后都认领了同一条路径（TOCTOU 竞态）。如果你需要真正的互斥，请使用具有原子检查并设置的原语：一个唯一命名的 git 分支（如果已存在则推送失败），或对协调存储的条件写入。当冲突很少且由人工合并时，文件追加式认领已经足够；不要把它当作锁来推销。

进度日志——仅追加，带时间戳。智能体启动时读取最近一天的内容来定位自己：完成了什么，谁在哪里工作。

决策日志——仅追加；它是阻止智能体 B 推翻智能体 A 经过推理的选择的脊柱。它足够关键，值得在下一节单独讨论。

防止这一切瓦解的规则：

• 每个任务一个分支；由人类合并——防止未经审查的更改进入 main；合并就是人类的检查点。
• 禁止智能体之间的调用——防止隐藏的旁路通道；所有协调都保留在可审计的文件中。
• 稳定的公共接口（每个模块声明接口）——防止并行重构互相破坏。
• 决策仅追加且具有约束力——防止关键选择被悄悄推翻。
• 在触碰共享或其他方拥有的路径之前先声明——防止两个智能体编辑同一个文件。

8. 决策日志：为 AI 构建编写 ADR

每个非平凡系统都会积累决策：我们使用这个数据存储，智能体只提出建议，所有模型流量都经过一个网关，这个组件可以循环而其他组件不可以。六周后没人记得为什么，有人“修复”了其中一个，于是一个关键选择被悄悄推翻。经典的补救方法是架构决策记录（Architecture Decision Record）。在 AI 辅助的构建中——智能体也会做出更改——决策日志不仅仅是卫生习惯，它是防止人类和智能体互相矛盾的机制。人类团队有走廊记忆；智能体没有。智能体接到任务时会阅读日志，了解它必须遵守的约束——并且不会推翻一个它看不到原因的选择。（这就是 §3 中的 DECISIONS.md 成长后的样子：一旦智能体——而不仅仅是你——做出更改，它就不再是笔记本，而成为强制执行的契约。）

一个仅追加的单一文件（或目录），每个条目简短且结构化：

DEC-017 · 2026-06-10 · We route ALL model traffic through one gateway.
why: one place for rate-limits, cost tracking, the kill switch, and provider swaps.
alternatives rejected: per-service SDK calls (scatters cost + coupling everywhere).
status: accepted

原因和被拒绝的替代方案是最有价值的部分——它们能阻止决策每季度被重新争论。如果你希望它机器可读，就保留为 YAML，这样工具可以对其进行 lint：

- id: DEC-017
  date: 2026-06-10
  decision: All model traffic goes through one gateway.
  why: single chokepoint for rate-limit, cost, kill switch, provider swap.
  rejected: [per-service SDK calls]
  governs: ["src/**"]        # which paths this decision constrains — makes the gate runnable
  forbids_imports: ["sdk-a", "sdk-b"]   # one machine-checkable rule (optional)
  supersedes: null           # status is DERIVED: an entry is "superseded" iff a LATER entry's `supersedes` points at it

取代，绝不编辑

你永远不编辑或删除过去的决策；你通过新条目来改变主意：

DEC-031 · 2026-07-02 · Supersedes DEC-017: the gateway also handles embeddings, not just chat.

历史——包括反转——本身就是有价值的：它讲述了系统思维如何演变的故事，而一个记忆模糊的旧条目永远不会悄悄出错，它会被明确标记为已被取代。注意，状态不是你翻转的存储字段——它派生自 supersedes 指针（一个条目被取代当且仅当后续条目指向它），因此过去的条目根本不会被编辑。

让它具有约束力，而不是被动文档

没人执行的日志会腐烂。把它接入审查流程，这样违反已接受决策的 diff 会被拒绝：

governs 是使其可运行的关键——没有它，门禁就无法知道哪些决策适用于某个 diff。forbids_imports 是一条廉价、完全可机器检查的 violates() 规则；更丰富的检查需要人工或智能体审查者。现在日志不再是会腐化的文档——它是构建所维护的活跃约束。要更改某项决策，智能体需写入一条取代条目并标记人工；它绝不会悄悄绕过决策进行编码。

什么该放进去

放入日志：非显而易见、难以逆转的选择；架构、数据存储、安全态势；智能体自主权的边界；任何你被悄悄撤销会感到恼火的内容。

排除在外：代码已明确表达的内容；临时实现细节；任何可自由更改且无后果的内容；琐碎内容（填充会掩盖重要条目）。

它与其他仅追加日志配对使用

有纪律的构建最终会产生几条相互呼应的记录——全部仅追加、带日期、从不重写：决策日志（系统为何如此构建）、进度/协调日志（完成了什么、谁在哪里工作——即上文并行智能体共享的文件），以及如果你正在构建一个在运行时做决策的系统，还有审计账本（它在生产环境中为何如此决策）。这种共享纪律使快速构建在事后可读——对新队友、审计员、智能体，或三个月后的你自己。

反模式

• 归咎于模型——当质量下滑时，本能反应是“等下一个模型”。更常见的是 harness 缺口：缺少工具、规则模糊、上下文窗口嘈杂。修复 harness。
• 没有自主权边界——要么你盯着每一次击键，要么它未经审查就推送/部署。
• 一个巨型上下文文件——会腐化，且每轮都耗尽预算。
• 上下文“稍后”更新——永远没有稍后；让过期成为同一 diff 中的 bug。
• 一次自我审查——一个盲点，统一应用；使用多视角审查小组。
• 一个悄悄重写文档的钩子——你会失去可审查的痕迹；发出检查清单，在 diff 中编辑。
• 智能体互相发消息——隐藏的侧信道，重启后无法存活；改为通过共享文件协调。
• 没有所有权映射——两个智能体编辑同一文件并互相撤销；默认按目录划分所有权，跨目录需声明。
• 编辑过去的决策而非取代它——你会丢失历史，并使旧副本悄悄出错；追加一条取代条目。

要点

我们已经从“AI 写一个函数”跨越到“AI 运行一个项目数周”——然后到“一群智能体并行运行它”。瓶颈已从模型能否编码转移到其周围的 harness 能否长期保持其诚实、有方向且经过审查。对于一个智能体，该 harness 是一部宪法、一条自主权边界、分层上下文、持久记忆、一个审查小组和一个编辑后钩子。对于多个智能体，增加一个共享的书面世界来行动——所有权映射、声明/释放协议、每任务分支加人工合并，以及一个接入审查因而具有约束力的仅追加决策日志。

这些都不是构建 AI 系统特有的——这是你在任何代码库上运行编码智能体的方式。你无法让模型可靠；你做不到。你约束模型并在其周围构建有纪律的系统。设置成本低，且每次会话都会累积——这是“聪明一下午的实习生”与“每周都更擅长你代码库的工程团队”之间的区别。

我稍后会将其打包为一个即插即用工具包。

这是构建层——应用于构建系统的智能体的纪律。其下的五个运行时层（确定性、评估、置信度、安全性、可运维性）是本系列的其余部分。

系列：在生产环境中运行 LLM 系统——第 6 级（共 6 级）：有纪律的构建。

这些文章采用 Creative Commons Attribution-ShareAlike 4.0 International 许可协议授权。

creativecommons.org/licenses/by-sa/4.0/deed.en

转载声明：本文为转载整理，原文版权归原作者及原站点所有。

原文来源：Stack Overflow Blog

原创地址：https://stackoverflow.blog/2026/10/07/part-6-an-operating-system-for-coding-agents-the-disciplined-build/