Agent Coding Governance：上下文地图、运行时护栏与自进化 Loop 如何重塑 AI 编程交付

把 AI 接进研发流程以后最容易被误判的一件事是只要模型足够强编码交付就会自然变快。真实落地时会发现模型生成代码的速度并不是瓶颈瓶颈常常出现在它周围的工程环境里。一个编码智能体可以快速读文件、改代码、跑命令但它也会忘记上下文、误判团队约束、绕过分层边界甚至在验证没有完成时给出“已完成”的结论。工程师被迫反复补充提示词、贴报错、纠偏、复查最后形成一种很别扭的状态表面上是在用 AI实际是在给 AI 当流程调度器。本文讨论的不是“怎么写更好的 Prompt”而是另一个更工程化的问题如果要让 AI 真正参与服务端交付需要在大模型和 Code IDE 之间补上一层什么样的治理系统。答案可以概括为两层层核心职责Harness把知识、权限、状态、证据、失败处置和自进化机制组织成一套可执行的研发治理框架Loop驱动 Harness 自动推进把人从重复的过程干预里拿出来只在关键判断点介入这套体系的目标不是让人退出研发而是让工程师不再被迫一拍一拍地驱动 AI把注意力重新放回架构判断、风险取舍和最终交付质量上。从“模型能力问题”转向“工程治理问题”一次普通 AI Coding 任务里模型真正写代码可能很快慢的是它不知道该怎么安全地完成这件事。它可能不知道仓库分层约束把infra反向 import 到biz/strategy它可能改了一个调用点却漏掉另一个入口它可能跑通了局部测试却顺手改了不该碰的函数它也可能在失败后不知道该回滚、重试还是停下来问人。这些问题看起来像模型不够聪明但根因并不全在模型。更准确地说是模型被放进了一个过于裸露的工程现场没有稳定的项目地图它只能临时猜仓库结构。没有硬边界它可以在规划阶段直接动业务代码。没有​证据闭环​它会把“我认为完成了”当成交付结果。没有跨会话记忆上一次纠正过的问题下一次还会重犯。这类问题很难靠“提示词写详细一点”解决。提示词是软约束工程交付需要的是硬机制。图人工驱动的 AI Coding 循环问题集中在人反复补上下文与纠偏。真正需要补齐的不是另一个更长的提示词而是一层能把 AI 行为纳入工程秩序的运行环境。四层分工智力、工具、治理和驱动图AI Coding 体系中智力、工具、治理和驱动需要分层协作。在AI Coding体系里至少要区分四件事谁负责思考谁负责执行谁负责治理谁负责推动流程。层级负责什么类比不负责什么大模型理解需求、生成代码、做语义判断一颗强但健忘的 CPU不记住组织约束不保证每次正确Code IDE / CLI读写文件、跑命令、调用工具、连接 MCP操作系统或容器运行时不判断这一步该不该做Harness知识、权限、状态、证据、失败处置、自进化框架、网关、流水线、配置中心的组合不产生智力不替代 IDE 工具Loop自动推进流程在卡点找人CI/CD 流水线不亲自写代码不绕过确认大模型提供智力Code IDE 提供工具这两层都会持续变强。但它们叠加起来仍然缺一层东西谁来规定当前阶段允许做什么、产出是否可信、失败后往哪里退、经验如何沉淀。Harness 解决的就是这层治理。Loop 则负责把 Harness 驱动起来让流程不再依赖人每一步手动敲“继续”。图大模型、Code IDE、Harness 与 Loop 的四层职责边界。开发前把仓库变成 AI 能安全进入的工作区智能体每次会话都近似从空白开始。它不会天然知道这个仓库的模块边界、接口入口、构建命令、分层约束也不会知道哪些行为是团队长期禁止的。所以在真正交给 AI 写业务代码前Harness先做一件看似“不产出需求代码”、但非常关键的事把普通仓库整理成 AI 能读懂、有接口资料、有提交护栏的工作区。这一步可以拆成三层。准备层产物解决的问题知识层AGENTS.md、ARCHITECTURE.md、docs/AGENTS.md给模型一张稳定地图而不是让它临时 grep接口层docs/reference/接口.md把调用链、入参出参、PSM、IDL 映射前置成资产护栏层.harness/、pre-commit、pre-push、分层校验脚本在提交点拦住违反工程约束的变更知识层地图比百科全书更有用知识层不是把所有代码解释一遍而是给模型一张足够稳定的项目地图。AGENTS.md负责导航告诉模型不同任务该看哪里ARCHITECTURE.md承载架构约束、依赖方向和不变量docs/AGENTS.md按任务场景把文档组织起来。这里的关键取舍是知识不是越多越好。过时或低质量的知识会主动误导模型比没有知识更危险。高层结构、模块边界、构建测试命令、分层约束这些稳定信息适合沉淀具体实现细节则不适合每次代码合入后机械同步。接口层把一次次检索变成可复用资产服务端需求经常围绕接口展开。模型需要知道接口入口、调用链、入参出参、IDL 映射、PSM 以及相关目录。如果每次都让模型自己 grep它会把大量上下文窗口消耗在原始代码扫描上。以AskQuestion接口为例读现成接口文档只需要约 5431 字符约 1.6k tokens如果让模型自行 grep 并拼出上下文会命中 10 个业务文件约 73872 字符约 22k tokens。后者大约是前者的 13 倍而且还建立在“模型知道该搜什么、不会重复读”的理想前提上。接口层的价值在于把检索成本从“每次需求都付一遍”变成“建一次、反复用”。护栏层提交点必须有硬门禁知识层让模型看得懂护栏层让错误不容易进入仓库。Harness 会把分层依赖校验、增量 gofmt、go mod tidy干净性检查、OpenSpec 门禁等能力挂到 Git hooks 上。比如从ARCHITECTURE.md中读取依赖方向生成check_layer_dependency.sh拦住infra反向 importbiz/strategy这类违反架构不变量的代码。这一步的边界也要讲清楚hooks 只在提交或 push 时生效不能管理开发过程本身知识和门禁也会过期需要被检测和刷新。也就是说开发前准备只是把工地建好还没有解决“施工过程如何受控”的问题。开发中用运行时把 AI 行为管起来图运行时护栏把模型行为纳入可控、可观、可恢复的边界。开发中阶段Harness 要回答的问题是一次需求从规划到实现、验证、推送、归档如何做到可控、可观、可恢复、可扩展。这四个性质对应四套机制。​Guard Runtime​正确性不能靠模型自觉可控是 Harness 的核心。一个会忘、会编、会抄近路的执行者不能只靠提醒它“请遵守规则”。Harness 用四道防线把不确定性关进确定边界里。防线机制解决的问题硬执法pre_tool_useGuard 按control.yaml裁决工具调用让越界写操作在执行前被阻断验令牌每代framework_token控制运行态修改防止模型或脚本伪造框架状态变更证据 权限前置verifier 派生 emit派单前钉死工具和写路径结果不靠模型自报权限不靠临场判断失败处置heal 由内核引擎裁定失败后往哪退不交给刚失败的执行者决定Guard 的关键在于它不读 Prompt也不相信模型自述。它只看运行时投影当前节点是谁、允许写哪些路径、处于执行还是暂停状态、generation 是否匹配。同一个.go文件在不同节点下会有完全不同的裁决结果图同一写操作在不同流程节点下会得到不同的 Guard 裁决。这不是提示词能提供的硬度。提示词最多告诉模型“不要这样做”Guard 则让“这样做”根本执行不了。​Evidence Runtime​过程必须可回放AI Coding最让人不安的不是它会出错而是它出错以后不知道错在哪。Harness把关键过程都落成结构化记录文件内容用途current.yaml当前节点、状态、恢复点单一事实源audit.jsonl谁通过什么机制改了状态依据什么证据回放推进与回退observations.jsonlGuard 拦截了什么工具、目标路径、原因追踪越界行为也是后续自进化原料这些记录不是普通日志噪声而是带证据的运行时账本。写入方只能是框架内核所有写入走统一接口并凭令牌不接受byuser这类自报也不允许 Prompt 或普通脚本直接改文件。这样才能保证并发安全、状态一致也保证可观测性不会因为有人绕开接口偷偷改盘而失真。​Recovery Runtime​断点续跑不能带病运行一次需求可能跨多次会话也可能被上下文压缩中断甚至换人接手。Harness 的恢复机制分两层。第一层是流程能续。状态和产物都落盘续跑时读取current.yaml知道上一次跑到哪个节点、当前变更是什么、下一步该从哪里继续。第二层是环境能自检。续跑不是无条件信任旧状态而是重新跑一遍就绪校验包括工具是否存在、环境变量是否齐全、能力注册表是否完整以及开发前装好的门禁是否过期。门禁新鲜度不靠感觉而靠.harness/.gate-stamp.json里的版本号和各脚本 sha256 指纹比对结果含义处理ok版本和指纹一致放行stale版本或指纹不一致触发刷新uninitialized从未初始化阻断并要求初始化这解决了开发前准备的一个老问题知识和门禁会过期但不能指望人每次都想起来检查。把新鲜度检测嵌入每条流程的起点才是真正可持续的做法。​Flow Runtime​新增流程不应该改内核如果每增加一个流程、接入一个能力都要修改框架内核系统很快会变成一堆特例。Harness 的设计是把流程顺序从代码里挪到模板里把能力职责收进自包含契约里内核只认三种结构