开启 Harness Engineering 探索之旅

过去两年AI Coding 从能写出能跑的代码走到能放手让它写一整段功能。但把这个能力放进真实业务、放进多人协作、放进存量系统里跑时我们发现一件怪事——AI 写得越快整体节奏并没有同步加快。盘点下来单看AI 写出来的代码占比这个数字一路走高可真正落到版本节奏上提效却远没有这个数字好看。出码率和提效之间裂开了一道缝。从 OpenAI Codex 团队那篇 Harness 工程博客里反复强调的一个观察——早期进展比预期慢并不是因为 Codex 不具备相应的能力而是因为环境的规范不够明确——开始整个行业都在补同一件事给模型搭一套能稳定干活的工作环境。这一层最近被业界命名为 Harness Engineering——它不是教模型怎么回答而是设计模型怎么工作。 在这里也分享下我们的探索之旅是踩过的坑、做过的取舍、和到现在还没解决的问题。序章Harness Engineering 是怎么结晶出来的1. 先把话说清楚Harness 到底是什么Harness Engineering 一句话能讲完不是教模型怎么回答而是设计模型怎么工作。用一个正在被广泛引用的等式表达就是Agent Model模型 Harness模型外的运行框架命名者 Mitchell Hashimoto 给出的定义更朴素也更直指核心It is the idea that anytime you find an agent makes a mistake, you take the time to engineer a solution such that the agent never makes that mistake again.—— 每当你发现 Agent 犯了一个错你就花时间在它外面工程化一个方案让它永远不再犯同样的错。它把工程关注点从模型这一句说得对不对挪到了模型这一整段活干得稳不稳。换个视角看这其实是 AI 工程关注点连续迁移的第三站——图 1 · AI 工程关注点的三次迁移Prompt → Context → HarnessPrompt Engineering2022–2024关心单次调用——这一句话怎么说模型这一次输出得更好。Context Engineering2025关心每一步——该把什么信息、以什么形式喂给模型。Harness Engineering2026关心整个任务——当 Agent 要跑长链条、多步骤的活可靠性已经不取决于模型本身而取决于模型外面那一整套工程化框架执行环境、工具协调、状态管理、反馈注入、约束施加、进展验证。一句话概括三者关系Prompt 教模型怎么说话Context 保证它上班有足够信息Harness 给它搭一套能持续干活的工作环境。 三层不是替代关系而是层层叠加——Harness 时代到来意味着前两层已经基本成熟短板被挤到了模型外面。2. 概念结晶时间线仍在结晶中有意思的是Harness Engineering这个词不是某个人一拍脑袋造出来的而是先有实践、后有命名、再被推广、最近才开始被学术界系统梳理——一个典型的概念结晶过程还在过程中2025 年8月起OpenAI Codex 团队在 agent-first 内部实验中验证模型能力之外环境设计、上下文组织、工具抽象、反馈回路和控制系统同样决定 Agent 能否稳定工作。2026 年2月Mitchell Hashimoto 将这类“发现 Agent 犯错后用工程手段让它不再犯同类错误”的实践称为 harness engineering。随后 LangChain 用 “Agent Model Harness” 明确边界 Böckeler / Thoughtworks将其拆解为 guides 与 sensors学界也开始用 ETCLOVG 七层分类做系统化梳理。 Harness Engineering 没有标准定义但它有一条清晰的实践路径 为Agent搭建可执行、可约束、 可验证、可反馈的工程环境。Harness Engineering 没有标准定义但它有一条清晰的实践路径 为Agent搭建可执行、可约束、 可验证、可反馈的工程环境。3. 回到我们自己——AI 写得快了研发整体没快多少回到我们自己团队很多人都已经离不开 AI Coding 了——一个独立小模块从想法到能跑一杯咖啡的时间。但盘点产出时我们发现一件怪事单看AI 写出来的代码占比这个数字一路走高可真正落到版本节奏上提效却远没有这个数字好看。 出码率和提效之间裂开了一道缝。分析根因是三件事:根因一研发从来不是写代码这一个环节。 早在《人月神话》和《没有银弹》里Brooks 就把软件难题拆成两层附属复杂度accidental语法、工具、平台带来的翻译成本和本质复杂度essential概念结构的构造、对外部世界的顺应、需求的可变性。AI 砍掉的恰好是附属那一层本质复杂度一分没少——甚至因为代码产出更多下游的对齐、review、维护反而更重了。没有银弹从来不是因为银弹造得不够好而是因为狼根本不在编码这一层。根因二局部加速只会让瓶颈转移不会让它消失。 把写这一环踩到十倍速理解、对齐、验证、沉淀这些环节一步没动——整条链的总时长由没被加速的部分决定。于是写得越快下游的 review、测试、维护越被动瓶颈只是从写挪到了收整体没动几分。根因三AI 看不见我们工程体系里的隐性约束。 团队规范、领域知识、历史依赖这些没被显式喂进去的东西AI 一概看不见。换个说法当 AI 把写代码这一格的成本压到接近零研发的瓶颈就显形了——真正的瓶颈本来就不在写在于理解、对齐、追溯、沉淀、验证这一连串非编码工作。真正限制研发节奏的是理解、对齐、追溯、沉淀、验证——这些恰恰是当前 AI 工具做得最差的部分。换成上一节的术语我们撞上的正是 Harness 这一层。我们不是在解决 Prompt模型已经够聪明也不是在解决 Context检索、长上下文这些工具已经成熟我们撞上的、想解决的是怎么让 AI 在我们自己的工程体系里能验证、能反馈、能修复、能循环、能持续地跑下去。一、我们的探索1. 先定目标是什么我们的目标用一句话说就是「AI 驱动研发全链路 · 人提需求 → AI 理解 → AI 执行 → 人确认」。从 P1 需求澄清 → P2 方案 → P3 实现 → P4 测试 → P5 部署 → P6 归档前端 / 后端并行覆盖 DEV / TEST / OPS 三段及线上运营告警闭环。2. 整套体系 2条轨道1个长期记忆要让它真正跑起来 把整套体系拆成2个轨道1个长期记忆轨道1研发端到端交付轨道2线上运营长期记忆(知识库)它让 AI 真正懂我们的业务、系统、线上质量。(1) 轨道 1研发端到端交付--项目工程落地在SpecWorker上研发端到端交付要考虑的是 换任何人来用、用在任何项目上AI 的产出质量是稳定的、可预期的。考虑的是3个层面的事① 协议层AI 每一步的输入输出契约协议层--管的是一件事AI 每一步的输入和输出必须是什么样的为什么需要协议层因为你和 AI 之间没有契约。你以为说清楚了它以为理解了做出来才发现对不上。人和人协作可以靠默契人和 AI 协作必须靠契约。协议层就是这份契约。它规定了四件事每一步必须产出什么格式的文档、文档必须用标准模板写、写完机器自动校验是否达标、每次变更只记增量保留完整历史。预期的效果就是AI 不再自由发挥而是在明确的框架内输出。 格式是确定的内容是可校验的历史是可追溯的。出了问题能查到是哪一步导致的。② 管线层标准化需求 → 上线61 阶段管线层——标准化整条链路工序 让AI 在跑需求 → 上线这条长链如何跑在跑的过程中不要丢了上下文、丢了证据、丢了纪律。从需求→上线历经 6 个核心阶段 1 个可选前置P0 brainstorming可选→ P1 requirements → P2 design → P3 implementation → P4 e2e-test → P5 deploy → P6 archive。6 张阶段能力深化卡片P1/P2/P3/P4/P5/P6P2/P3/P4/P5 标注前端/后端双流程❶ P1 需求TAPD 拉取 AC 可测 test-cases 同源问题研发的理解、对齐环节在 AI Coding 里是最容易塌方的——AI 把功能写出来了但为什么这样写没人能复述同一个需求A 同学昨天理解的和 B 同学今天理解的不一样。核心痛点是需求口径在 P1 阶段就要钉死否则下游全部跑偏。做法TAPD 拉取做需求底稿P1 阶段第一步是从 TAPD 拉取本次需求的官方描述作为 requirements.md 的原始口径段落——不允许 AI 自己复述用户的话只允许它从 TAPD 引用。ACAcceptance Criteria必须可测每条需求拆成 WHEN前置条件→ THEN系统 SHALL ... 形式含 AND 连接子句禁止性能要好这种不可测描述不可测的 AC 必须改写或拆细。test-cases.md与requirements.md同源P1 阶段同时产出 requirements.md给 P2 用 test-cases.md给 P4 用两份文档共用同一份 AC 列表——下游 P4 不再理解一遍需求自己写测试而是直接拿 test-cases 跑。双 SubAgent 串联P1 阶段不是 AI 一气呵成出稿而是 specworker-requirement-analyzer生成澄清问题 → 主流程让用户回答 specworker-integration-testcase-generator基于澄清后的需求生成 test-cases.md两个 SubAgent 串联。澄清 → 用户确认 → 测试用例同步生成三步走完才算 P1 通过。权衡 / 边界P1 不解决用户真正想要什么——这件事必须人来做我们只解决AI 怎么不歪曲已经表达出来的需求。❷ P2 设计契约先行 sandbox_mode D-x 改动点问题传统 design.md 是给人读的——讲背景、讲思路、讲架构图。但 AI 读不懂这种文档它需要的是机器可读的契约接口签名、错误码、状态机、字段必填项。如果 P2 不把这些钉死P3 实现时 AI 会自己发明一套——下游 code-reviewer 也就无从比对。做法契约先行design.md 不是设计文档是契约接口签名 / 数据模型 / 字段必填项一律写死成 Markdown 表格 Mermaid 时序图 / 数据流图下游 P3 实现 / code-reviewer 都拿同一份契约比对——design.md 是契约不是说明。sandbox_mode 字段标记写入模式前端前端 P2 design.md 顶部强制有 sandbox_mode: true / false 字段——true 时 P3 把改动先写入沙箱目录不影响主链路false 时直写项目目标文件。这个字段会贯穿到 P3让 AI 在改代码时知道该不该先隔离。D-x 改动点拆解design.md 里有一个 D-1 / D-2 / D-3 … 改动点列表逐项标注 「文件:行号 函数名」「目的」「实现」「关键代码片段」。P3 实现时按 D-x 列表逐项勾掉code-reviewer 也按 D-x 列表逐项 review——改动点不是流水账是 P3 的工单池。specworker-clarify-design 单 SubAgent 两道 STOPP2 不是一次出稿——specworker-clarify-design SubAgent 先做一轮代码分析、按 P0阻断/ P1高优先/ P2中优先 三档抛出技术澄清问题如这个接口的并发场景考虑了吗这个状态转移的边界条件呢写入澄清草稿主流程让用户回答 → 用户确认摘要方案 → 才生成 design.md。两道 STOP 卡点强制把代码分析的疑问和用户的业务约束对齐后再落地。权衡 / 边界design.md 不强求完美只强求机器可读——任何等实现时再说的字段必须显式标注待澄清或待确认不允许暗藏。❸ P3 实现D2C UI 95% 五轮 code-reviewer 三档问题实施阶段是最容易翻车的一格——AI 写得快但写得对不对、像不像、改得稳不稳全靠下游兜底。我们在这一格里做了三套兜底D2C 把从 Figma 还原 UI代码、UI 双 95% 五轮校准把像不像做成可量化的闭环、code-reviewer 三档分级把对不对做成可机读的契约比对。做法前端 D2CUI较准把从 Figma 还原 UI拆成 3 个 Skill 串行外加一个 fixer subagentspecworker-d2c-get-figma拉设计稿资源本地化生成 pages.config.jsonspecworker-d2c-refactor按 slug 分流支持全量/增量、沙箱/直写、Hippy/通用 Web 多模板、multi-slug 并行specworker-ui-calibration做法UI 校准自愈UI 校准修正循环像素SSIM 的可自愈闭环specworker-ui-calibration 在 d2c-refactor 完成后自动启动截图 → 像素差异 SSIM 双指标 → 任一 95% 触发自修循环最多 5 轮→ 每轮调起 specworker-ui-calibration-fixer-fe subagent 拿差异 diff 当前 DOM 做局部修改 → 再截图比对 → 直到双 95% 或耗尽 5 轮。5 轮未过自动 fallback输出最终汇总含每轮指标变化交由用户决策——继续追加修复轮次、回退到设计稿调整或跳过本次校准。做法后端 code-reviewer 三档契约 review每次 P3 实现一个分组含若干接口/改动点都自动调用 specworker-code-reviewer SubAgent对照 design.md 检查实现与方案的一致性 已规划功能的覆盖度输出三档Critical必修契约违反 / 接口签名不一致 / 错误码缺失。不允许 AI 自己改了就过必须人审 签字 留痕。Important必标可绕过但必须显式标记已知偏差 原因写入 evaluation 日志。Suggestion自由处置风格、命名、注释等。code-reviewer 不读全文件优先读 git diff。code-reviewer 也不解决代码风格——这部分交给 lintcode-reviewer 只看契约。❹ P4 集成测试端测 后端 API 测试双流程 · 失败自愈问题测试是 AI Coding 最容易假完成的一格——AI 一句已通过敷衍过去尤其AI Native方式下测试要左移尽量将问题在前面环节暴露并解决掉在功能开发阶段会去做功能测试在前、后端发布后再做集成测试。前端和后端的测试形态完全不同前端要在浏览器/小程序里跑 UI 交互、做截图比对后端要发 HTTP 请求、查日志、看数据库。两条流程都要做但能力栈完全独立。做法前端多场景支持P4 主 Skill 不直接执行测试而是按项目类型分发到子 SkillWeb 自动化specworker-web-automator-test基于 Playwright跑端到端用例并截图。小程序自动化specworker-miniprogram-automator-test specworker-miniprogram-cloudtest走小程序专属真机云测。 通用 Automatorspecworker-e2e-minitest-testcase-generator 把 test-cases.md 转成可执行脚本。做法后端specworker-api-test specworker-api-test-debugger 双 SubAgent 自愈后端测试是这一节最值得展开的部分——它的难点不在跑用例而在失败之后能不能不靠人查根因。整条链路是specworker-api-test Skill 生成脚本从 P2 阶段产出的 uat/api_test_cases.md 自动生成 Node.js原生 fetch测试脚本按场景 SC-N 步骤拆成独立 case收集环境变量 执行自动从 deploy.md / .env.test 抓 host / token / 测试账号跑 pytest失败时 specworker-api-test-debugger SubAgent 接管把失败请求的 trace-id 提取出来 → 自动去 CLS 拉相关日志 → 去 MySQL 查相关数据行 → 去 Redis 看相关 key 状态 → 产出失败根因 建议修法的诊断报告诊断报告附给 implementation Agent 修代码修完自动重跑这一条 case 验证销案 / 介入重跑通过则销案同一用例 3 轮诊断仍未修通则 STOP 并标注需人工介入——交给开发同学拉起 specworker-debugging Skill 走人工根因分析这是用户主动调用的兜底 Skill不是自动升级。权衡 / 边界api-test-debugger 也不解决日志根本没打的情况——遇到这类必须回退到specworker-debugging 让人介入。❺ P5 部署前端 git 规范 / 后端deploy.md动态解析双流程问题部署阶段是质量最难兜底的一格——一旦上线错误代价从整改返工变成线上事故。前端和后端的部署形态也完全不同前端是构建产物推到 CDN / 测试环境后端是镜像发布到 K8s 数据库变更。两条都要做纪律层评分门槛 total_score ≥ 95最多 3 轮整改与 P1~P6 全流程统一。部署阶段评分卡≥ 95 才允许进 P6 归档缺失字段 → 60% 上限做法前端 P5git 提交规范commit message 必须符合 type(scope): subject 格式type 限定为 feat / fix / refactor / style / test / chore。测试环境部署 状态轮询推送后按知识库的 CI/CD 规范触发部署若有部署状态查询命令或 CI 链接轮询等待最多 10 分钟、每 30 秒查询一次超时则输出警告并询问用户是否继续——不会自动判定为失败也不会自动拉取 CI 日志由用户根据警告决定下一步。无 CI/CD 规范文件时退化为提示用户按项目规范手动部署。部署产物落盘产出 {change_dir}/frontend/deploy.md不是 deploy-report.md按 templates/output/deploy.md 模板填写——含 change-id / 分支 / 提交 hash / 部署时间 / 测试环境 URL / 部署状态、提交信息、变更文件、部署步骤等字段。归档由 P6 阶段统一处理P5 只负责落盘 deploy.md。做法后端 P5deploy.md 任务化解析P2 阶段已经写好部署计划P5 阶段 specworker-p5-deploy-be 把 deploy.md 解析成三类任务列表- [ ] 复选框数据库变更类 / 流水线发布类 / 其他类按类分发处理流水线参数pipeline_id / start_params从 references/pipeline.md 提取。SQL 变更强制用户确认任何数据库 DDL / DML 变更不允许 AI 自动执行——必须把生成的 SQL 拼成可读 diff由用户显式 yes/no 才能跑。这条规则即使是 Critical 修复也不例外。流水线发布 轮询调发布接口后轮询发布状态直到成功 / 失败失败时自动拉取 K8s pod 日志附在 deploy-report 里。评分卡 ≥ 95 兜底P5 评分门槛 ≥ 95最多 3 轮整改——其实全流程 P1~P6 评分门槛统一是 ≥ 95这是 specworker 的硬规矩P5 之所以特别强调是因为它是上线前最后一道闸没部署成功的 change 不允许先归档下次再说。权衡 / 边界P5 不解决灰度策略和回滚决策——这两件事必须 SRE 拍板AI 只负责按计划执行和失败时报错。SQL 强制确认看似拖慢节奏但这是我们踩过线上事故后立的硬规矩——部署阶段宁可慢不可错。❻ P6 归档changes-sync knowledge-sync specs-generator问题归档是最容易被跳过的一格——代码合进去了测试过了部署上线了谁还有耐心写归档文档但跳过归档的代价是下次同类需求来时AI 找不到上次的解法从零开始线上踩过的坑下次照样会踩。归档不是留资料是复利。状态管理跨阶段状态全部落盘成 markdown——文件即协议、即状态、即复利做法三件套强制跑changes-sync把 git 实际改动跟 design / planning 描述对齐确保代码做了什么和文档说要做什么完全一致——不一致就强制更新文档或回炉 P3。knowledge-sync把当前 change 里被反复用到的设计、踩过的坑、约定的契约沉淀进项目级知识库 specs/下一次相似需求来时 P1 阶段就能 grep 到。specs-generator根据本次 change 的 delta-spec.mdADDED / MODIFIED / REMOVED / RENAMED 四类标记增量合并到 specs/[module]/spec.md 对应章节避免 全量复制 → 知识库膨胀。Delta Spec 是 P6 的灵魂它不直接复制本次 change 的全部文档进 specs而是只标记哪些是新增的、哪些是修改的、哪些是删除的、哪些只是重命名——specs-generator 按这四类标记做增量合并避免知识库膨胀。❼ 管线上的可监测性 三个维度可追踪 → 可回溯 → 可度量管线之上还要叠一层「可监测性」。在 AI 驱动的研发管线里可监测性不是「运维锦上添花」——它是信任 AI 的工程前提。AI 驱动研发和传统研发最大的差别是执行主体从人变成了 AI——这带来一个根本性的信任问题传统研发人写代码、人提测、人发布每一步出了问题追责到人就够了AI 研发AI 分析需求、AI写方案、AI 写代码、AI 跑测试、AI 部署每一步出了问题追责到谁如果没有可监测性AI 跑完一段告诉你「我做完了」你既无法验证它真的做完了、也无法回放它是怎么做的、更无法度量它消耗了什么资源——整条管线就退化成一个黑盒能跑通是运气跑不通是玄学。只有 AI 的每一步都被记录、被验证、被度量我们才敢把「需求到上线」的长链交给它。我们把可监测性拆成三个维度对应「信任 AI」的三个不同问题。●维度 1 · 可追踪让每一步都留下机器可读的证据价值把 AI 自述的「我做完了」变成机器能读的证据。这是「证据先于断言」纪律的物理形态。实现手段——三件强制落盘的产物 一个不靠 AI 自觉的触发机制.phase-metrics.jsonl每个 change 目录下每个阶段一行 JSON记录 phase / action / timestamp / duration_ms / total_input_tokens / total_output_tokens / response_count / lines_added / lines_deleted / files_changed以及按模型费率自动折算的estimated_cost_usd。这是阶段级运行明细的「流水账」。evaluation.md每个阶段结束由独立的 specworker-evaluation skill 跑一份评分维度 / 分数 / 结论total_score ≥ 95 才允许进下一阶段最多 3 轮整改。Report API payload把固定字段组装成 event_typepost:phase:end 的 payload 上报到后端服务spawn 后台进程发送、fire-and-forget主流程不等上报结果——上报失败本地仍有完整 jsonl可以离线补传。●维度 2 · 可回溯失败时能从结果反推根因价值AI 跑挂的时候能从「结果异常」自动收敛到「根因是什么、该怎么修」而不是丢一句「测试失败」让人手工排查。实现手段——按「失败类型」配套不同的反馈回路失败类型回溯路径收敛终点UI 还原偏差D2C 完成 → 截图 → 像素差异 SSIM 双指标 → 任一 95% 触发 ui-calibration-fixer-fe 局部修改 → 再截图比对最多 5 轮95% 或耗尽 5 轮升级人工API 测试挂了失败 trace-id → CLS 拉日志 → MySQL 查数据行 → Redis 看 key 状态按 specworker-api-test-debugger 中写死的 SOP 检索失败根因 建议修法 诊断报告附给 implementation Agent 修跨阶段重试浪费specworker-summarize-report 把调用了哪些 skill / agent各自吃了多少 token哪些步骤失败重试过组装成结构化报告回写知识库重试 3 次成功也标红关键纪律SOP 写死不让 Agent 自由发挥——这条 SOP 是把「人工排查的隐性经验」显式化为 Agent 的检索路径。●维度 3 · 可度量让效果和成本能被量化价值让「这套 AI 体系到底好不好用、贵不贵」从感觉变成数字能做横向对比、能给老板讲清 ROI。实现手段——双层 Hook 把单点数据汇聚到全局业务级 CLI按场景定制「落什么字段」平台级 Hook Engine全局统一「什么时候触发」两层都进 hook_events 表中央聚合token / 用量 / 阶段耗时 / 失败重试都可追溯。可量化的四类指标Token / 成本total_input_tokens total_output_tokens 按模型费率自动折算 estimated_cost_usd耗时每个阶段开始到结束的 duration_ms重试 / 失败率哪些阶段反复挂、挂在哪一步来自 summarize-report 沉淀代码改动量lines_added / lines_deleted / files_changed配合 token 成本能算出「每行代码的 AI 成本」。③ 纪律层每道工序硬编码门禁AI 不可绕过纪律层——规定过程中不许偷工减料做完了还有独立质检。 比如写代码前必须先写测试、声称完成前必须跑验证拿到证据、每批代码有独立审查。最后还有一道评估门禁独立模型打分95 分以下打回重做。AI 能力这么强为什么还需要这么严的纪律管控因为 AI 有一个坏毛病——它会偷懒。 它会跳过测试直接写代码、遇到 bug 猜一个修复方案碰运气、没验证就说已完成、自己给自己打高分。这些不是偶尔发生是 AI 的天然倾向。所以我们针对 AI 的每一种偷懒模式设了对应的纪律防线。写代码想跳过测试TDD 纪律强制你先写测试再写代码。遇到 bug 想猜着改Debug 纪律强制你先做根因分析。想说应该做完了Verify 纪律要求你必须拿出运行证据。代码偏离了设计方案Review 纪律逐项比对。最后交付时自己打分可能偏高Evaluate 纪律用SubAgent来评。五道防线每一道拦截 AI 的一种偷懒模式缺一道就有漏洞。而且这些纪律不是建议遵守是硬编码到管线里的——底部三条原则强制嵌入、每道都是门禁、触发否决直接阻断。(2) 轨道 2线上运营研发管线管上线前线上运营轨道管上线后——研发态与运营态共用同一份知识库、同一套 trace-id 检索 SOP、同一套评分门槛是 Harness 在不同输入入口上的对偶设计。它要回答的是另一个问题代码上线后告警了AI 怎么稳定修回去这条轨道整条链路是 7 步告警触发 / 自动巡检监控告警错误率突增 / 延迟飙升 / 业务指标异常 周期性巡检关键链路、核心 SLI双源进入。清洗合并去重、按调用链关联同源告警避免同一根因爆出几十条。采集证据按预定 SOP 自动拉 trace-id 链路、CLS 日志、MySQL 该数据行、Redis 该 key 状态、相关变更记录。根因分析AI 给出假设 证据 影响面三件套不允许只给猜测——每个假设必须有证据指向。AI / 人工修复低风险的文案、空指针、漏字段AI 直接出 PR高风险的数据库变更、灰度策略必须人工签字才能落盘。回归验证对原失败 case 重跑一次通过则销案、未通过则升级。归档把这次告警怎么挂的、怎么修的、什么场景会重现回写知识库——下次同类告警进来时根因分析直接命中。为什么把它单独一条而不是塞进管线 因为研发管线是主动驱动人提需求 → AI 执行运营轨道是被动驱动系统报警 → AI 响应两条轨道的输入入口、节奏、纪律点都不一样。但只要共享知识库它们就是同一套 Harness 的两面。(3) 知识库AI 的长期记忆知识库是 AI 的长期记忆——它让 AI 真正懂我们的业务、系统、线上质量。 没有它每次新需求来 AI 都要从零理解一遍上下文所谓复利也就无从谈起。我们的做法是把知识库做成两件事——一套规范 一套运作逻辑规范层面明确知识库由哪些部分构成、需要包含哪些内容、这些内容如何组织、目录结构是怎么样的同时对内容质量提出要求每一类知识库都配套示例。运作逻辑分三个阶段第一阶段存量初始化、第二阶段迭代演进、第三阶段持续治理待实现。运行时怎么用知识库切好了形状、立好了规范运行时还得有一套机制把切好的片段精准送到模型面前。① 知识库规范构成 / 组织 / 内容要求上下文工程的转变从一次性塞满整个仓库到按阶段分包、按需读取索引→相关 spec→片段、token 双层结算两套知识库并存各管一段项目级 specs/沉淀产品长期资产——业务规则、技术架构、接口契约、术语表。粒度按产品/服务切。变更级 knowledge-spec/即 change 目录每次需求迭代独立一个目录沉淀本次变更的 requirements.md / design.md / planning.md / test-cases.md / delta-spec.md / archive/。粒度按change切。两者通过 index.md 索引互通——P1 阶段做需求分析时可以从 change 目录跳到 specs 找历史相似 change也可以从 specs 跳到当前 change 看本次改动。5 类目录分层设计自上而下越来越具体、越来越易变知识库的 5 类目录设计business/业务规范 / 不依赖任何端→ frontend/ backend/端侧技术规范 / 依赖 business→ common/接口契约 / 由 trpcgo-protocol 派生→ changes/需求演进 / 引用上面所有层加 archives/ 与 issues/ 两个辅助目录。依赖严格单向向下。依赖严格单向向下business/ 不依赖任何端frontend/、backend/ 依赖 business/common/ 由 trpcgo-protocol 派生、绝不反向依赖实现changes/ 可引用上面所有层但不被它们依赖。好处很直接——改一个接口只动 common/改一条业务规则只动 business/不会牵动全库模型检索时也能先定位到目录再定位到篇。知识库目录结构business / frontend / backend / common / changes archives / issuesspec 质量与粒度设计让按需检索真正可命中粒度三级递进顶层概述粗一页讲清产品是什么→ 模块/服务 spec中一页讲清一个模块的边界、数据模型、接口列表→ 子页面/接口详情细字段级 Request/Response。读者与模型都能在需要的那一级停下不必每次下钻到底。两级查找禁止全局通配任何检索必须 index.md → 相关 spec 两跳命中明令禁止 **/*.md。粒度切得对两跳就能精确定位。单一事实来源SSOT术语只在 glossary.md 定义一次别处引用不得重定义接口只认 trpcgo-protocol 的 .protocommon/ 全部由其派生。杜绝同一个概念三处定义、三处过期。章节结构统一同类文档如各服务的 spec.md章节骨架完全一致概述/目录/数据模型/缓存/接口/时序/依赖/规则让模型按固定位置取信息而不是每篇都重新理解排版。原位增量更新所有更新在原文件上改、以 Git diff 审查不复制时间戳目录文档与代码冲突时以代码为准并回写。② 知识库三阶段运作初始化 → 演进→ 治理知识库不是一次写完就放那的死文档它要跟着项目一起活。我们把它的运作逻辑分成三个阶段每个阶段解决的事不一样、用的工具也不一样❶阶段一存量初始化——把家底盘清楚老项目接入 AI Native 开发最大的痛点是有历史包袱——代码、文档、线上产品三者各自漂移、互相对不上号。这一阶段要做的是从历史文档、代码、线上产品同时取证做信息采集、分析、生成、内容验证四步把家底盘清楚。但这个环节不能完全靠 AI——存量里有大量过时但还能跑的代码、已经废弃但没删的接口、以前有但现在不要了的字段。这些 AI 没法判断必须由熟悉业务的人去确认、剔除掉。我们的实测经验是用 AI 跑出初稿、人工剔过时、人工补关键约束三步下来才能形成可用的初版。❷阶段二迭代演进——每次归档都强制更新家底盘清楚之后每次迭代结束都要把这次的资产沉回知识库——不是代码合了就完事而是 P6 阶段强制跑三件套changes-sync 把 git 实际改动跟 design / planning 描述对齐、knowledge-sync 把被反复用到的设计、踩过的坑、约定的契约提炼进 specs、specs-generator 按 delta-spec.mdADDED / MODIFIED / REMOVED / RENAMED 四类标记增量更新 specs 索引。没跑完三件套下一个 change 的 P1 起不来——这是纪律层硬卡的不允许先归档下次再说。阶段三持续治理待实现。③ 上下文注入session-start 钩子 两级查找 token 双层结算知识库切好了形状、立好了规范、跑通了运作运行时还得有一套机制把切好的片段精准送到模型面前。我们落成四个工程动作index.md两级查找禁止全局通配每个 Skill 的前置检查里都有一条禁止使用 **/*.md 全局通配。token 双层结算父 Skill / SubAgent 独立计费我们最初把 code-reviewer 设计为读全文件做契约 review看似合理。直到核对 token 消耗才发现SubAgent 的上下文是独立计费的——它每读一遍全文件主 Agent 端毫无感知但成本照样产生。解法重写为优先读 git diff 关键片段仅在 diff 过大或上下文不足时才读全文件。反直觉洞察SubAgent 并非节省上下文的银弹而是另一份独立计费的开销——看似把负担甩了出去实际是另起了一份账。SubAgent 优先 git diff避免读全文件把优先读 diff作为所有 SubAgent 的统一约定——P3 的 code-reviewer、P4 的 api-test-debugger、P6 的 changes-sync 全部遵循。两条加起来一句话上下文注入不是塞得越多越好而是每一步只送它该看见的那一片。 这一层做扎实之后两条运营轨道才能稳定跑——否则一切都会被 token 爆炸拖死。回头看协议层定契约、管线层定阶段、纪律层堵漏、再加一份长期记忆——四件事看似分散但都在做同一件事把AI 看不见的东西挪到它一定看得见的地方。 契约让我以为说清楚了变成机器可读阶段让做到哪一步了变成文件就能查纪律让AI 偷没偷懒变成可机读的证据知识库让上次怎么解的不再依赖某个人的记忆。二、实践心得4 条工程原则 4 个典型问题走完这一遭最大的判断只有一句AI Coding 的工程化本质是对不确定性的系统治理。 模型本身是概率的、注意力是衰减的、上下文是会被压缩的、输出是会自我合理化的——这些都不是 bug是 LLM 的物理常数。Harness Engineering 之所以成立恰恰是因为我们承认这些常数无法消除只能在它周围搭一套确定性的骨架兜住它。过程中也有一些心得1. 【A 组4 条工程原则】(1) 原则 1AI 工作流编排追求确定性而非自由发挥采用 Fixed Flow 结合对抗式、程序化质量门禁以保障过程的确定性与结果的质量。具体落到四件事状态持久化设计每个步骤的输入、输出、状态都写到一个共享的持久化文件而非在 Agent 间直接传递上下文避免上下文丢失或失真程序化门禁检查对关键步骤及产出物进行程序化硬检查一旦不通过需要退至上一环节再跑不依赖 AI 的自我判断输入质量要求通过标准化模板如需求模板、方案设计模板等约束输入质量为 Fixed Flow 奠定基础对抗式纪律行为铁律TDD / Debugging / Verification 等 评估独立防止自己给自己打高分 自我合理化警报工程判断让 AI自由发挥听起来很美但工程上的代价是把整条流水线的不确定性叠加给下游。Fixed Flow 不是限制 AI 的能力是把它的能力锚定在可验证的轨道上。(2) 原则 2上下文控制当上下文过长时CodeBuddy 会对上下文进行压缩影响 SKILL 效果。 这条是上下文工程里最朴素也最关键的事实。落地动作将重要的规则固化到 rules 中避免在长会话里被压缩掉无关联的任务使用新的 session 执行SKILL 按需读取文件避免全量扫描控制文件长度避免出现超长文件工程判断上下文不是窗口——是稀缺资源。窗口越大越容易被错觉成无限但真正决定 AI 表现的不是窗口大小是窗口里关键信息的密度。控制上下文本质是控制信噪比。(3) 原则 3Token 成本优化合理选择模型按任务要求选择匹配的模型不是越强越好控制上下文长度如无必要不要在一个 Session 一直对话开新的窗口工程判断成本优化的反面是把贵不贵和对不对混为一谈。便宜的模型 紧凑的上下文 干净的会话常常比最强模型 一锅炖效果更好——任务匹配度才是第一性问题模型规模只是手段。(4) 原则 4将确定性过程用脚本实现大语言模型具有随机性——虽然经多次迭代通常也可以实现效果但浪费 Token 和时间。对于确定性强、可重复执行的流程沉淀为脚本skill.mdscripts/ - run_test.js配套使用 SKILL 而不是 MCP。MCP 的主要问题会固定占用上下文长度、工具不可灵活选配、数量过多会影响模型效果且需要手动配置到 IDE使用较繁琐。我们的中转方案是 CodeBuddy IDE → SKILL Script → MCP Server按渐进式披露完成鉴权与调用兼顾 SKILL 的优势与 MCP 的生态。工程判断AI 是好工具但不是所有事都该用 AI 做。确定的事用脚本、不确定的事用 AI——这条边界划清楚了AI 的价值才能被放大划不清楚反而会被随机性吞掉。本质在做一件事把 AI 的发挥空间收敛到它真正擅长的那一片。2. 【B 组4 个典型问题】下面 4 个问题是反复踩到、并已经形成问题 → 原因 → 解决方案标准应对的——它们之间不是孤立的而是同一个底层事实LLM 是概率模型在不同环节的不同表现。(1) 问题一AI 指令遵循问题AI 易跳过关键步骤导致流程偏离质量门控未严格执行原因上下文压缩上下文过长时会被压缩导致信息丢失注意力机制LLM 注意力衰减远距离信息关注度下降解决方案TODO 文件驱动核心步骤写入 TODO 文件AI 逐条执行并更新进度拆解 SubAgent降低单次上下文提高模型指令遵循表现渐进式披露按需加载上下文工程判断AI 不听话很多时候不是它不想听是它真的没看见——上下文压缩 注意力衰减让原本写明的指令在长会话后期等于失声。所以治理指令遵循不是反复强调AI 你要听话是把指令搬到 AI 一定看得见的地方TODO、SubAgent 起点、渐进披露的当前帧。(2) 问题二需求歧义问题由于自然语言的模糊性需求文档天然存在歧义AI 易误解需求解决方案多轮澄清机制执行前强制 AI 提问确认后再动手结构化需求规范需求统一转为 GIVEN-WHEN-THEN 格式工程判断需求歧义不是 AI 的问题是自然语言的物理属性——人和人之间也会误解只是人会用常识兜底AI 不会。与其指望 AI理解力更强不如把需求写成它没法误解的格式——结构化GIVEN-WHEN-THEN 显式澄清把理解这个动作变成匹配。(3) 问题三设计稿还原问题AI 对 Figma 设计稿 UI 还原效果一般布局 / 切图 / 样式易失真解决方案引入中间产物html css 切图AI 更擅长基于结构化中间产物渲染多轮 UI 校准迭代截图对比逐步逼近设计稿工程判断AI 不擅长从图像直接生成代码但很擅长从中间结构html/css/切图生成代码。这个事实暗示了一个普适方法论当 AI 在 A → B 一步到位很差时在中间插一层 A → C → B——让每一段都是 AI 真正擅长的转换。(4) 问题 4如何保证产物的可靠性问题LLM 是概率模型且存在幻觉每次生成的代码会有差异解决方案自验证循环编写 → 运行 → 测试 → 修复 → 再验证单元测试驱动开发UTDD先生成测试用例再生成实现代码用测试用例约束代码质量审查 Agent 门控关键产物经交叉评审达标后再交付工程判断可靠性不是让 AI 一次写对是承认它写不对但用机制兜住。自验证循环、UTDD、审查 Agent——这三件事的共同点是没有一个相信 AI 单点输出全都靠输出 验证双轨。这也正是 Harness 的核心模型给定的情况下工程能做的不是改造模型是改造它周围的环境。三、结束语我们刚走到地图刚画出来的地方走到这里我们越来越清楚一件事Harness Engineering 不是一套先有理论再去实现的工程方法——它是先在 Anthropic、Codex、我们这种一线团队的踩坑里冒出来再被回头命名、回头总结的。 所以这一套的边界、纪律点、评分门槛——全部是 AI 在真实工程里翻车一次、留下来一道防线。某种意义上这套 Harness 是 AI 自己逼我们写出来的——它把传统研发里靠默契、靠经验、靠 review 兜住的东西挑明成了文档、契约、评分卡、SubAgent。这套体系的价值不在于我们做对了多少而在于我们承认还有哪些没做对。 具体来说至少有六件事还在路上——评分机制和下游真实消耗的耦合还没打通P2 得 90 分但 P3 翻车的反馈回路目前只在 docs 里写了规则scorer 仍按只看本阶段产物打分下游反哺还没真正落到分数上知识库的自动治理还在演进changes-sync / knowledge-sync / specs-generator 三件套解决了如何归档但归档进去的东西如何老化、如何淘汰还没有机制运营轨道的告警闭环还在补全这条轨道在兄弟项目里跑通了主链路但跨项目的 SOP 复用、跨项目的知识库共享还在试多模型评估、跨项目知识迁移、Agent 自我进化业界 AHE 那条线这些更前沿的方向我们也只是站在了门口。业务复杂度高的历史项目如何适配进来这套体系在新项目里启动顺利但老项目的历史积淀往往是水下的冰山——隐性约束散落在老同学脑袋里、过期文档与现网行为对不上、废弃接口和特殊例外没人敢动AI 一上手就要面对这些代码里看不见的规矩。目前还得靠熟悉业务的同学陪跑做大量初始化。如何把这部分陪跑成本压下来让老项目也能像新项目一样快速进入 AI Native 节奏是我们现在最头疼、也最值得继续投入的一格。AI 测试的可靠性挑战还在持续探索当前测试左移、E2E、API 测试和失败自愈已经能拦住一部分问题但 AI 生成测试用例仍可能覆盖不足、断言偏弱、只验证“能跑通”而没有验证“业务真的正确”UI 自动化也容易受到环境、数据、截图差异、业务复杂度的影响。下一步需要补齐测试用例质量评估、反例生成、覆盖率与业务风险映射以及“测试本身是否可信”的二次评审机制。这一路走下来我们没有发明任何新概念——把头部公司在 Harness 这一层踩出来的工程语言一层一层落到我们自己的体系里每一块都有真踩过的坑、真解过的题、真留下的产物。但这恰恰是 Harness Engineering 这件事最有意思的地方它不是一套终极框架而是一张被现实不断逼着补全的地图——每跑一次真实业务地图就被推进一格。我们刚走到地图刚画出来的地方前面还有很大一片空白。如果你也正在自己的团队里做类似的事欢迎拍砖、欢迎讨论、欢迎一起往前走一步。