AI Coding Harness工程实践：8个Skill构建可控可追溯的智能体开发链路

今年大家聊 AI Coding热度已经明显从“一次对话能生成多少行代码”转移到“这个项目到底能不能让人省心”上了。我观察到一个特别明显的变化现在社区里高频出现的已经不是 prompt 技巧而是一个听起来很有运维感的词——Harness。有人问 DeepSeek Harness 怎么装有人问 Codex Harness 的 Skill 脚本怎么写也有人自己搭了框架之后再回过头来琢磨“Harness 和 Agent 到底什么关系”。归根结底大家都在做同一件事给 AI Agent 套上一套可控的工程缰绳让它能在真实仓库里按流程干活而不是漫无目的地改代码。这篇文章要分享的就是我在企业级 AI Coding 落地中摸索出来的一套 Harness 工程实践用 8 个 Skill 把需求理解、架构设计、编码执行、代码审查、测试生成、文档同步、发布联动、反馈复盘串成一条完整链路。适合正在做 AI Coding 平台建设或者想把 Agent 写码真正接到团队工作流里的同学如果你只是拿 AI 写点脚本也能从这套设计里理解 Harness 的底层思路。1. 先把概念对齐Harness 工程到底是什么1.1 Harness 与 Agent 的边界Harness 英文原意是马具、挽具放到工程语境里很形象。我们常说 Agent 是“大模型 记忆 工具调用循环”负责思考、行动、观察也就是“想做什么、怎么做”而 Harness 是这个循环外面的那套控制系统负责启动、暂停、回滚、记录也就是“能不能做、做到哪一步停、出事怎么兜底”。很多人第一次接触 Harness 会误以为它是又一个 Agent 框架或者只是 IDE 插件的替身。实际上它更像一层“中间管理层”。Agent 本身可以很聪明但聪明不意味着可靠Harness 的作用恰恰是用工程手段去约束这种聪明。比如Agent 在修改代码时可能觉得自己“已经理解了项目结构”但 Harness 可以通过预置的文件访问白名单、命令执行沙箱、diff 行数上限把风险提前卡住。我对团队说的最多的一句话是Agent 是驾驶员Harness 是道路、红绿灯和刹车系统。没有 Harness 的 Agent 也能开车但没人敢让它上企业级项目的路。1.2 Skill可复用的“业务能力单元”有了 Harness 之后还要解决另一个问题Agent 得具备“干某一类具体活”的能力。这个能力包就是 Skill。Skill 不是普通的提示词模板它通常打包了四样东西触发器Trigger什么时候被调用比如新建 issue、PR 变更、定时任务。使用说明Instruction给模型的行为指引包括步骤和约束。工具声明Tools这个 Skill 可以调用哪些外部工具比如代码搜索、依赖分析、测试命令、Git 操作。校验与输出Validation Output模型产出必须满足的格式和校验规则一般用 JSON Schema 约束。举个例子团队里经常要写技术方案。如果每次都用一句“帮我设计一下”让模型临场发挥输出格式五花八门很难复用。但封装成“架构方案 Skill”后模型必须按 ADR架构决策记录模板输出必须调用依赖分析工具必须返回结构化的 JSON。这样 Harness 才能把这个结果交给下一个 Skill 继续加工。我一直跟研发强调Skill 的颗粒度决定了 AI 流程的稳定度。颗粒度太粗Skill 就退化成“带格式的 prompt”颗粒度太细编排成本又会失控。1.3 企业级落地的三个硬约束个人用 AI Coding 工具跑飞了再重来也没事企业级落地有三个绕不开的硬约束。第一个是安全边界。AI 生成代码时可能会无意间读取敏感配置、执行危险命令、修改锁定文件。Harness 必须给每个 Skill 分配最小权限比如“只能读 src 目录”“只能写 tests 目录”“不能执行 package 发布命令”。第二个是可追溯性。整个过程要能审计谁在什么时候触发了哪个 Skill模型生成了什么谁做了人工审批哪一步失败了。没有审计AI Coding 就没办法在合规要求严格的团队中推广。第三个是降级和人工接管。AI 链路不能是“单点赌命”。某个 Skill 连错三次Harness 必须能自动降级把任务转给人工处理或者回滚到上一个稳定检查点。我在项目里给这三个约束分别对应了三个机制RBAC 权限模型、全量操作日志、任务状态机。这样即使某个 Skill 跑坏了损失也是可控的。2. 8 个 Skill 串起的全链路从需求到复盘的闭环2.1 为什么是 8 个而不是 3 个或 20 个企业软件研发流程如果高度概括是“想清楚、写出来、验明白、发出去”四个阶段。但真正落地每个阶段还要再拆出关键动作。我把 AI Coding 全链路裁剪成了 8 个 Skill需求解析 Skill架构方案 Skill编码执行 Skill代码审查 Skill测试资产 Skill文档同步 Skill发布联动 Skill反馈复盘 Skill这 8 个不是拍脑袋定的而是按“端到端闭环 每段可人工介入”的原则裁剪出来的。少于 8 个意味着某些环节只能靠人肉补位多于 8 个编排成本和触发冲突会明显上升。比如需求解析和架构方案看似可以合并但如果你让一个 Skill 同时干“理解需求”和“设计技术方案”它很容易在需求还没确认时就开始写代码这是大忌。每个 Skill 对应一个“门禁”环节。前一个 Skill 的输出没有通过校验后一个 Skill 就不会启动。这种门禁式设计让 AI 流程具备解释性——任何一步出问题你能立刻定位到是哪个环节。2.2 全链路状态流每个 Skill 输入输出怎么衔接下面这张表是我们在 Harness 编排层定义的核心流转关系也直接映射到任务状态机里Skill 名称输入输出关键工具失败处理需求解析原始需求、Issue、PRD需求任务书目标、范围、验收标准仓库搜索、文档检索、Issue 读取置信度过低时转人工澄清架构方案需求任务书技术方案、影响面清单、ADR依赖分析、架构图生成、代码地图影响面超过阈值暂停审批编码执行技术方案、任务书代码 diff、提交信息、变更说明代码搜索、编辑器、Git 操作触碰敏感文件自动回滚代码审查代码 diff、技术方案审查意见、问题列表、质量评分Linter、静态检查、API 对比发现 Block 级问题打回重写测试资产代码 diff、测试计划测试用例、测试报告、覆盖率测试框架、Mock 服务、覆盖率工具用例失败时自动补充并重跑文档同步代码 diff、变更说明README 更新、接口文档、CHANGELOG文档生成器、文档站点 API越权修改时拒绝变更发布联动测试报告、审批记录MR/PR、流水线状态、部署通知CI/CD API、Git 平台、监控系统流水线失败时通知相关人反馈复盘线上问题、失败用例、评审记录复盘报告、共性原因、知识沉淀日志检索、错误追踪、知识库形成待办并更新经验库实际运行中Harness 会在每个输出节点做两件事格式校验和语义校验。格式校验用的是 JSON Schema语义校验会调用一次轻量模型枚举输出中的风险点。例如需求任务书里必须有可验证的验收标准不能只写“优化性能”这种不可测的话技术方案里如果涉及数据库变更必须包含回滚方案。这一层校验极大地减少了下游 Skill 被脏数据污染的概率。2.3 关键设计取舍为什么不做“一把梭大 Agent”现在很多产品宣传是“你把任务丢给 AI它自己搞定一切”。这种“一把梭大 Agent”在企业级场景里并不好用原因很现实。第一是上下文爆炸。一个 Agent 如果把需求、代码库、测试结果、历史决策全部塞进上下文很快会超过模型窗口然后开始“失忆”。拆成 8 个 Skill 后每个 Skill 只接收上一个环节的结构化输出上下文可控得多。第二是失败定位困难。大 Agent 跑偏时你很难判断是需求理解错了、方案设计有问题、还是工具调用出了岔子。拆开后哪个 Skill 失败一目了然可以单独重试或降级。第三是权限没法精细控制。一个全知全能的 Agent 要么给太多权限有安全风险要么给太少权限干什么都要打断你。拆成 Skill 后可以给“编码执行 Skill”开放写权限给“架构方案 Skill”只开放读权限权限被最小化。这个取舍的本质是“复杂任务拆成简单流水线”。它牺牲了一点端到端的“智能感”换来了稳定性和可维护性。在企业里稳定性永远排在炫技前面。3. 逐个拆解8 个 Skill 的落地方式与调试要点3.1 Skill 1 需求解析把模糊想法变成任务书几乎所有 AI Coding 翻车根源都在“需求没有说清楚”。需求解析 Skill 的目标是逼着模型在动手前先输出一份结构化的需求任务书。我用一个简化版的 Skill 配置来说明name: requirement-parser version: 1.3.0 description: 将原始需求转换为结构化任务书 triggers: - event: issue.state_changed condition: new_status triage - event: command.manual command: /parse-requirement tools: - repo.code_search - docs.read - issue.read_comments steps: - extract: fields: - goal - scope - users - acceptance_criteria - constraints - risks - verify: required: - acceptance_criteria - scope - estimate: method: llm_analysis input: repo.code_search_result - output: format: json schema: task_schema_v3.json checkpoints: - 缺失验收标准时必须列出澄清问题并转人工 - 影响模块清单来自代码搜索不得凭空填写这里的关键设计是checkpoints。第一项要求“缺失验收标准时必须列出澄清问题并转人工”是为了禁止模型自行脑补需求。第二项要求“影响模块清单来自代码搜索”是为了防止模型编造项目结构。实测下来这个 Skill 是整套链路里回报率最高的因为它把后续所有 Skill 的地基打牢了。调试这个 Skill 时最常踩的坑是模型把“输出 JSON”理解成“只有 JSON”导致给用户的解释性内容全丢了。后来我在校验器里加了summary字段要求同时输出给用户看的自然语言摘要和给下游用的结构化数据两边都不耽误。3.2 Skill 2 架构方案先写设计再碰代码架构方案 Skill 存在的价值是“延迟编码”。很多 AI 写代码翻车就是因为拿到需求立刻开写跳过设计。这个 Skill 的输出是一份技术方案包含技术选型说明变更涉及的前后端模块清单依赖与数据模型的影响面风险与回滚策略测试策略建议我给这个 Skill 配置了一个“影响面阈值”机制。如果模型估算的变更文件超过 15 个或者涉及数据库表结构变更方案会自动进入“待人工审批”状态不会继续往编码环节走。这个机制帮我们挡住了好几次“AI 迷之自信的大重构”。架构方案 Skill 还可以调用绘图工具生成架构图。我们试过让模型输出 Mermaid 然后转成图片但效果一般后来直接接了一个内部架构图渲染服务模型只输出节点和连线关系由服务端出图。企业环境里更容易落地因为图片资源是可控的。3.3 Skill 3 编码执行安全写码与“主动停下来”编码执行 Skill 是核心也是风险最高的一环。它的任务不是“尽可能多地写代码”而是“在约束下正确完成变更”。我给它定义了四条铁律不碰白名单之外的文件不执行危险命令强制数据库迁移、发布、删除分支等不在没有测试的情况下提交大段代码遇到三类情况必须停下现有逻辑与任务书冲突、需要新增外部依赖、涉及跨模块大规模重构为什么强调“主动停下来”因为 AI 并不知道企业内部系统的隐藏约束。有一次模型为了实现某个功能想直接改一个公共库的内部方法影响面波及六个业务模块。如果没有停下来机制这种改动进到 MR 里Review 成本极高。在 Harness 层我给这个 Skill 挂了文件锁和 diff 量监控。多个 Skill 并行时文件锁防止同时写同一个文件diff 量超过阈值时系统自动拆分成多个变更批次。实际操作中一个 500 行以内的变更模型完成度最高超过 1000 行错误率显著上升所以宁可拆成多个小批次。3.4 Skill 4 代码审查让 AI 黑起自己来审查 Skill 最容易做成摆设因为模型给自己写的代码做 Review容易“自我感觉良好”。我的解决方法是给这个 Skill 加“对抗性角色”。审查时必须同时扮演三类人安全评审、性能工程师、维护者。它要回答三个问题这段代码有没有安全漏洞有没有明显的性能瓶颈三个月后其他人来维护能看懂这段代码吗关键实现是审查 Skill 不能只看 diff还要结合上下文。只看 diff 的审查往往漏掉跨函数影响所以我会把涉及的核心函数调用链一起喂给模型并让它输出“建议阻塞”和“建议优化”两类问题。如果出现“建议阻塞”级别问题Harness 会跳过提交直接把 diff 打回“编码执行 Skill”重做。这里要提一个细节审查 Skill 的 temperature 必须调低我一般设在 0.1 以下。Review 是确定性任务不需要创意发散。温度高了模型会给出很多似是而非的风格建议反而淹没了真正的问题。3.5 Skill 5 测试资产跑通比生成更多重要测试资产 Skill 很容易被误解为“生成单测用例”但真正难的是让测试跑起来。我们遇到过模型生成了 80% 代码行数的测试结果有一半因为环境依赖问题执行不了。所以这个 Skill 我设计了三个步骤读取变更代码分析测试计划生成单测和必要集成测试在容器中真实执行测试收集报告为了稳定执行所有测试统一跑在预置 Docker 容器里避免“在我电脑上是好的”这种问题。容器里预装了依赖、Mock 服务和 SQLite 数据库不给测试访问生产数据库的机会。这个约束同时保证了安全性和复现性。覆盖率阈值我通常设在 60% 到 70%对核心函数还可以单独提高。如果测试后覆盖率不达标Skill 会继续生成测试直到达标或达到最大尝试次数。实测这个机制让流水线中的 AI 代码评审问题数下降不少因为很多逻辑错误都是写测试时才暴露出来的。3.6 Skill 6 文档同步AI 写代码的“售后”几乎每个 AI Coding 项目都会忽略文档。代码合进去了文档还是旧的这在企业里是很重的技术债。文档同步 Skill 做的事是在代码变更通过测试后自动更新 README、接口文档和 CHANGELOG。这个 Skill 要控制“动什么文档”。我给模型配了一份文档白名单只允许改与当前变更直接相关的文件。比如一个 API 的入参变了就更新对应的接口文档但不允许它顺手重写整个 README。乱改文档比不更新更糟Review 的人会崩溃。还有个实际细节文档同步 Skill 的 prompt 里要明确“使用与代码变更一致的词汇风格”否则模型容易把文档改成它自己的表述习惯和团队风格冲突。文档生成后又通过脚本比对只保留 diff 中实际变化的段落防止大段无意义重写。3.7 Skill 7 发布联动接到流水线才叫闭环编码、测试、文档都完成之后发布联动 Skill 负责把成果推向工程化流水线。它的核心动作是创建 MR/PR、触发 CI、跟踪流水线、反馈部署状态。这个 Skill 的难点不在模型而在外部系统的对接。我先调用 Git 平台 API 创建 MR提交信息由编码执行 Skill 生成但会经过模板化处理。接着触发 CI 流水线并轮询状态。如果流水线失败Skill 会把失败日志摘录下来读取关键错误信息然后决定是转给人处理还是自动回到编码执行环节做一次修复。对外部系统调用要做三个防御处理幂等、超时、人工接管。比如“创建 MR”重复调用时不能创建多个“轮询流水线”不能无限等连续失败三次必须发通知给人。这些逻辑对输出内容的“智能性”没要求但对系统稳定性帮助巨大。3.8 Skill 8 反馈复盘让每个失败都变成经验反馈复盘 Skill 是 8 个里最容易被砍掉但长期价值最大的一个。它定期收集三类信息线上问题、失败测试用例、代码评审意见。然后进行两个动作第一聚类分析找出问题发生的共性原因。比如“接口超时”反复出现可能指向某个架构决策有问题“测试失败”集中在一个模块可能说明那个模块需要补重构。第二更新知识库和 Skill 的 few-shot 示例。如果发现模型在新增类型时反复犯同样的错误就把这个 case 提炼成经验示例注入到后续编码 Skill 的上下文中。这就形成了链路自学习的闭环。让我印象最深的一个案例反馈复盘 Skill 发现新代码中 70% 的问题集中在“异步处理没做好”上。于是我们把这个 case 沉淀为反模式示例并在编码执行 Skill 里增加了一条强制检查“凡是涉及异步调用必须在代码中显式说明错误处理和超时策略”。一个月后相关问题数量明显下降。这个 Skill 让整套链路不是“一次性消耗品”而是可以越用越懂业务、越用越稳的基础设施。4. 实战避坑Skill 编排里的那些坑4.1 两种最容易翻车的 Skill 编排反模式第一种反模式是把 Skill 做成“超级提示词”。有同事为了省事把需求解析、架构方案、编码执行全塞进一个 Skill以为模型自己会拆。实际结果就是上下文膨胀模型经常遗忘最初的需求约束而且出问题时完全无法定位。第二种反模式是“有 Skill 无状态流”。Skill 虽然定义了但 Harness 没有做严格的输入输出校验每个 Skill 跑完就完事下一个 Skill 拿到的数据可能已经是脏的。这样链条越长错误越积越深。我建议强制校验节点必须有并且每个 Skill 的输出格式要版本化避免上游改动悄悄破坏下游。4.2 上下文预算与状态管理一个很现实的问题模型上下文窗口有限但项目信息无限。Harness 的核心工作之一就是上下文预算管理。我通常给单次 Skill 执行设置上下文上限比如 32k tokens超出部分要分层压缩最优先保留当前任务相关的代码和结构化数据中间层用摘要替代最底层的历史信息直接丢弃。状态管理也很重要。任务状态机至少要包含created、running、awaiting_review、succeeded、failed、manual_handoff六种状态。这样 Skill 之间的依赖关系才能在 Harness 中被正确追踪。常见错误是状态只有成功和失败两种导致“需要人工确认”的中间态只能靠人肉记录非常容易被漏。4.3 Skill 全生命周期的版本、权限与审计Skill 本身是代码也需要做好版本管理。我见过一个团队某个 Skill 改了 prompt 后没人通知结果下游解析直接崩了。所以 Skill 的 manifest 必须带版本号并且每次调整都要走 MR 评审。权限方面遵循最小化。需求解析和架构方案 Skill 只给读权限编码执行 Skill 给受限写权限发布联动 Skill 只能调用 CI 接口。权限配置在 Harness 的 RBAC 层统一管理不要在 Skill 内部零散设置否则很容易漏。审计日志记录三件关键信息谁触发了什么 Skill、模型产出的核心关键字、是否有异常路径。这些日志不仅是问题排查的依据也是后续优化 Skill 的数据来源。4.4 高频问题速查表现象可能原因解决方案同一个 Skill 被反复触发触发器条件重叠在 Harness 编排层加互斥锁和优先级AI 调用不存在的工具工具注册边界不清晰在 Skill 的 tools 白名单明确列出可调用项输出 JSON 频繁解析失败校验器过于宽松引入强 JSON Schema 校验并给 fail 示例测试 Skill 总是不稳定环境差异导致依赖缺失统一用容器执行锁定依赖版本多个 Skill 同时改一个文件缺少文件级并发控制在 Harness 加文件锁冲突时串行化AI 代码风格与团队差异大缺少风格约束上下文编码 Skill 加入团队规范摘录和正反例Skill 升级后下游解析失败输出结构变更未同步输出格式版本化升级时做兼容测试如果只让我留一个建议那就是别急着把 8 个 Skill 一次全上。先投入产出比最高的三件套——需求解析、编码执行、代码审查——跑通一条最窄的链路。这条链路稳定运行一两周后你会发现模型在真实项目里的行为模式已经比较可预测了再逐步叠加测试、文档、发布和复盘。我见过太多团队一上来就想要“全家桶”结果被编排复杂度劝退。AI Coding 的落地本质不是模型更聪明而是工程外壳足够结实。Harness 工程的价值恰恰是让聪明变得可用、可控、可追溯。