第六部分：编码代理的操作系统：纪律化构建
内容提要
文章认为编码代理的长期质量取决于框架而非模型。框架包含六项：宪法文件、自主边界（仅推送和部署需批准）、分层上下文、持久记忆、多视角审查小组、编辑后钩子。多代理并行时需靠共享文件协调：所有权图、认领协议、每任务分支、追加式决策日志，以避免冲突和决策被悄然推翻。
延伸解读
框架比模型更重要：来自基准测试的证据
文章引用Terminal-Bench 2.0的公开结果：LangChain仅通过改变框架（系统提示、工具、中间件如自验证和循环检测），在模型不变的情况下，将编码代理的得分从52.8%提升到66.5%，排名从30名外跃升至前5。这13.7个百分点的差距说明，长期项目中的质量衰减往往源于配置缺失——缺少工具、规则模糊、上下文噪声——而非模型能力不足。因此，当代理表现下滑时，优先检查框架而非等待更强模型。
自主边界：只对不可逆操作设卡
文章建议将代理的自主权与操作的可逆性挂钩：允许读取、编辑、运行测试和提交等可逆操作自由执行，仅在推送和部署这两个不可逆操作上要求人工批准。示例权限配置中，git push、npm publish、terraform apply等被设为“询问”，而强制推送和跳过验证被明确拒绝。这样做既让代理能连续工作一小时并多次提交，又将“自主”的风险限制在可控范围内。注意不同运行器的匹配语义可能不同，需验证拒绝规则是否真正生效。
多代理协作：通过共享状态而非对话
当多个代理在同一仓库并行工作时，文章指出它们不应互相发送消息，而应通过共享文件协调：所有权图明确每个路径的负责代理，认领/释放协议提供乐观的互斥，每个任务独立分支并由人类合并，追加式决策日志防止已做出的选择被悄然推翻。这些文件编码了工作状态，使协调可审计、可跨重启。文章也提醒，文件追加式认领并非真正的锁，存在竞态条件，若需强互斥应使用原子操作如唯一分支名。
决策日志：从笔记到可执行的约束
文章将决策日志（DECISIONS.md）视为防止人类和代理互相矛盾的核心机制。每条记录包含日期、决策、原因和被拒绝的替代方案，且只追加、不编辑，变更通过新条目声明取代旧条目。通过YAML格式中的governs字段指定受约束的路径，并可选forbids_imports等机器可检查规则，日志可接入审查流程，使违反已接受决策的差异被拒绝。这样，日志不再是会腐烂的文档，而是构建过程中主动维护的约束。
Q&A
为什么编码代理的长期质量取决于框架而不是模型？
文章指出，模型可能只占决定长期软件质量因素的十分之一，框架（harness）才是其余部分。证据是：在Terminal-Bench 2.0基准上，仅改变框架（系统提示、工具、中间件如自验证和循环检测），保持同一模型，LangChain将编码代理从30名开外提升到前5名，分数从52.8%升至66.5%。大多数代理失败是配置失败，如缺少工具、规则模糊、缺少护栏、上下文窗口充满噪音。
编码代理的自主边界应该如何设置？
最高杠杆的决策是：让代理在所有可逆操作上自由运行，仅在两个不可逆操作上暂停——推送到远程和部署。通过权限配置实现：允许读、编辑、写、grep、glob以及git add/commit、npm test/run/ci、pytest等；询问git push、npm publish、aws、terraform apply、kubectl apply等；拒绝git push --force、--no-verify等。这样代理可以自主工作一小时并提交多次，你只需在推送时审查。
如何为编码代理设计分层上下文？
分层上下文包括：根CONTEXT.md（约200行，包含项目是什么、如何运行/测试、模块索引、不变量、状态位置，会话开始时读取）；每个模块的CONTEXT.md（职责、关键文件、依赖、陷阱、如何测试该模块，编辑前读取）；DECISIONS.md（追加式，记录日期、决策、原因、被拒绝的替代方案）。规则：过时的上下文是bug，必须在使其失效的同一变更中修复。
多代理并行时如何协调以避免冲突？
通过共享的书面状态协调，而非对话。具体包括：所有权图（默认按目录分配所有权，跨区域编辑需认领）；认领/释放协议（追加式，认领前扫描最近几小时是否有重叠路径的开放认领，但这是乐观的，非锁）；每任务分支，人类合并；进度日志（追加式，带时间戳）；决策日志（追加式，防止代理B撤销代理A的决策）。规则：无代理间调用，稳定公共接口，决策追加且具有约束力，触碰共享或他人拥有的路径前先认领。
决策日志（ADR）在AI构建中有什么作用？
决策日志是防止人类和代理相互矛盾的机制。代理没有走廊记忆，通过阅读日志了解必须遵守的约束，不会撤销看不到原因的选择。每个条目简短结构化，包含id、日期、决策、原因、被拒绝的替代方案、状态。关键规则：永远不编辑或删除过去的决策，而是用新条目取代（supersede）。通过governs和forbids_imports等字段使日志可执行，在审查中拒绝违反已接受决策的差异。
编码代理的编辑后钩子（post-edit hook）是做什么的？
编辑后钩子在每次编辑后触发，发出一个检查清单作为上下文，提醒代理：更新最近的CONTEXT.md（如果职责/关键文件/陷阱变化）；在依赖/API变化时追加记忆/图边；在出现先例时记录DECISIONS.md；更新持久事实的记忆。代理在同一差异中进行这些编辑，可审查，而非静默重写。钩子通过settings.json配置，指向一个脚本，读取工具事件并输出检查清单。
