写这篇东西之前我先说个背景。我们团队在企业里推 AI Coding 已经两年多了刚开始大家都很兴奋觉得拿个大模型接上仓库就能自动写代码。结果真正落到项目里发现完全不是那么回事模型确实是强今天能一口气生成几百行代码明天换了个需求就给你编出根本不存在的 API后天修了个 bug 又引入两个新问题。折腾了两个月我们把 Cursor、Claude Code、DeepSeek 这一类专业 Agent 工具换着用了一圈最后得出一个结论企业级 AI Coding 缺的不是模型不是工具是 harness控制器/脚手架和 skill技能包这套工程化体系。这篇文章就把我们这半年最核心的一套打法完全拆开讲8 个 skill 怎么设计、怎么开发、怎么串成全链路以及我在这个过程中踩过的坑和沉淀下来的排查方法。内容不挑具体模型你现在用的是 DeepSeek、Codex 还是 Claude Code 都适用因为整套思路是挂在 harness 层上的。1. 为什么企业级 AI Coding 必须先上 Harness而不是直接上 Agent1.1 裸 Agent 在企业落地为什么翻车先讲个真实的失败案例。我们早期试点的时候给一个核心后端组的同学配了带 Agent 能力的 IDE期望他能在半天内把十几个接口的 CRUD 写完。结果那天一下午组长的 200 行核心逻辑被 Agent 静默改坏了它自己还觉得改得挺好没有跑测试没有看 CI直接就把文件覆盖了。从那天起我意识到一个很基础的问题大模型不是不聪明而是不稳定。这种不可靠体现在好几个方面模型对着一个模糊需求会自己脑补业务规则没人告诉它这个项目里什么叫订单状态机它也能编一套改代码的时候没有边界感你让它加一个字段它能顺手把无关的配置也改了更麻烦的是每个开发者喂给模型的上下文完全不一样同样的任务今天做和明天做产出可能差一个量级。这些问题的根源不是模型本省而是缺少一层约束和编排的中间层也就是 harness。打个比方裸 Agent 就像一个刚入职但能力很强的外包开发你给他一个需求文档他可能写得很漂亮也可能把事情搞砸因为他没有你们团队的规范、没看过历史代码、没有测试习惯。而 Harness 就是给这个外包配上的一整套工作环境给他工位、规矩、工具清单还要有一个项目负责人帮他拆任务、做验收。一个没有 harness 约束的 agent在企业代码库里就是风险敞口。1.2 Harness 到底给模型加上了什么Harness 这个词在 AI Agent 工程里指的是 agent 运行时的控制器外壳它负责几个核心职责第一是上下文管理。模型一次能读的 token 有限harness 要决定哪些文件该读、哪些历史对话该保留、哪些信息该压缩。第二是工具调度。模型不能想调什么就调什么harness 负责把可用的工具封装成白名单比如只允许读特定目录、只允许执行特定的测试命令。第三是流程控制。模型输出代码之后harness 可以强制接上 lint、测试、类型检查这些环节不通过就不算完成。第四是记忆与标准化。把团队的编码规范、项目背景、历史决策沉淀下来让每次对话都能继承。你会发现这四个职责里没有一个依赖具体模型的智力。也就是说你换 GPT-5 还是 DeepSeek-V3harness 这套骨架都能工作它稳定的不是模型是流程。1.3 为什么偏偏是 Skill 这个抽象层有了 harness 还不够因为每个企业的业务千差万别。一个做电商的公司要 AI 写退款逻辑一个做芯片的公司要 AI 写驱动代码通用的 harness 也不知道该怎么做。这时候就需要 skill 这个抽象层。Skill 本质上是一组可复用的任务能力包它把某个特定任务的完成方法固化成声明文件加脚本。比如代码审查可以是一个 skill里面写清楚审查要关注哪些点、要调用哪些工具、输出什么格式的报告。下次任何项目需要代码审查时harness 就知道去加载这个 skill并严格按照里面的流程执行。我们最终决定走harness 8 skills这套路线就是因为它的可沉淀性极强。代码写得烂可以重构模型变强可以升级但这些 skill 积累的是团队的方法论是越用越值钱的资产。这一节看到这里你对为什么要 harness应该有个基本感觉了下面我们进入核心8 个 skill 到底怎么设计怎么串成全链路。2. 8 个 Skill 如何串起需求到交付的全链路2.1 链路总览从需求到交付的八道工序如果你的 AI Coding 只在写代码这一个环节发力那本质上你还是在用自动补全。真正的企业级 AI Coding 应该覆盖一个需求从萌芽到上线的全部环节这也是我们设计这 8 个 skill 的逻辑起点。我们按照软件交付的自然流水线把全链路切成八个工序序号Skill 名称定位典型输入典型输出1spec-writer需求规格化一句话需求/会议纪要可验收的 PRD 规格2arch-designer架构方案设计规格文档模块拆分与接口定义3task-planner任务分解编排架构方案可执行的任务清单4code-crafter代码生成实现任务清单主体业务代码5code-reviewer代码质量审查源码与上下文问题清单与修改建议6test-master测试生成执行代码与需求规格测试用例与执行结果7doc-scribe文档同步更新代码 diff 与规格README/接口文档更新8release-checker交付验收把关全量代码与测试结果发布结论与风险报告请注意这里每次工序之间传递的不是自然的对话文本而是结构化的产出物。也就是说spec-writer 输出的不是一段描述需求的散文而是一个包含了验收标准、边界条件、数据字段定义的结构化文档arch-designer 输出的不是一段建议使用微服务架构的话而是一个包含模块列表、依赖关系、接口签名的方案文件。2.2 工序间的契约用结构化产出做交接为什么一定要强调结构化产出我见过很多团队做 Agent 编排上一个 Agent 的对话历史直接拼给下一个 Agent结果下一个 Agent 读完前一段根本分不清哪些是需求、哪些是已经完成的决策、哪些是废案。你让 AI 写代码它先把前 200 行对话当成上下文学习一遍再开始生成不仅浪费 token还容易学歪。我们的做法非常朴素每个 skill 只读上一个 skill 落盘的文件不读对方的对话历史。spec-writer 把 PRD 写到artifacts/spec.mdarch-designer 只读那个文件读完输出artifacts/architecture.md以此类推。这条链路上所有信息都通过文件系统传递路径就是它们之间的接口契约。这个设计的好处非常明显可追溯性极强。任何一步出问题你只需要打开对应文件看内容不需要翻整段对话。上下文开销低。每个 skill 启动时只要加载相关文件不会被无关对话稀释注意力。方便断点续跑。task-planner 跑挂了修复 skill 后直接从第 3 步重新执行前两步的产物还在。2.3 契约的代码实现Skill 之间的 I/O 规范为了让这套契约不至于靠自觉我们把 I/O 规范直接固化在 harness 的配置里。每个 skill 的声明文件里头都有明确的inputs和outputs字段harness 在调度时会自动校验文件是否存在。如果一个 skill 的输出文件不存在下一个 skill 就会启动失败错误信息直接提示缺少 xxx.md。听起来有点死板但正是这种死板护栏保证了全链路的可靠性。实际工程里我们会在工作目录下建一个artifacts/和logs/目录前者放每道工序的结构化产出后者放每次执行的日志。时间久了这套产物本身就是一份项目知识库甚至可以用来训练更懂公司业务的私有模型这个后面讲压测的时候我还会提。3. Skill 开发的完整实操3.1 SKILL.md 格式与灵魂三问Skill 的载体通常是一个目录里面包含一个SKILL.md描述文件和若干执行脚本可以是 Python、Shell 或直接把指令写在 markdown 里。这个SKILL.md是我们所有 skill 的灵魂写得好不好直接决定模型听不听你的。我的经验是写每个 skill 的声明之前先回答三个问题这个 skill 什么时候触发不要在 description 里写一套很泛的话比如用于代码审查而是写清楚触发条件和上下文标志比如当检测到工作区存在未审查的 diff 且当前阶段为 code-review 时。你给模型讲得越具体它越容易在正确时机激活这个技能。这个 skill 的边界是什么哪些事它绝对不做这一点至关重要。比如 spec-writer 的 SKILL.md 里我们就明确写了不要输出任何具体技术术语、不要指定数据库选型、不要讨论接口性能优化因为它只负责需求规格化把技术决策留给 arch-designer。防止 skill 越权是 AI Coding 工程里最常见的治理难题。这个 skill 的成功标准是什么输出格式、质量门槛、必含字段全部量化。比如 code-reviewer 的输出必须是问题清单 严重级别 涉及文件行号 修改建议并且严重级别为 P0/P1 的问题数必须为零才算审查通过。看一个我们实际在用的SKILL.md骨架--- name: code-reviewer description: 对工作区中的代码变更进行静态审查和逻辑校验。当检测到 code-crafter 产出代码且未通过质量门禁时自动触发。 when_to_use: 执行完代码生成后、进入测试前 inputs: - artifacts/source-code-summary.md - src/**/*.{py,ts,java} outputs: - artifacts/review-report.md --- # 职责范围 - 只做审查不修改源代码 - 不讨论业务需求合理性只关注代码质量与正确性 - 严禁自行执行修改操作 # 审查维度 1. 逻辑正确性条件分支、循环边界、异常捕获是否完备 2. 安全风险SQL 注入、路径穿越、敏感信息硬编码 3. 性能隐患明显的 N1 查询、大对象持有、死锁风险 4. 规范一致性是否遵循项目 .editorconfig / lint 配置 # 输出格式 输出 artifacts/review-report.md格式如下 ## 问题列表 | 严重级别 | 文件 | 行号 | 问题描述 | 修改建议 |这里有个细节值得多说一句description字段的写法直接影响 skill 的触发概率。你把只做审查写在职责范围里但模型仍然有可能手滑去改代码所以我建议在 SKILL.md 里多用严禁必须不讨论这类强约束词模型对这些词的遵循度明显高于中性描述。3.2 一个可复用的 Skill 骨架大多数 skill 不只是扔给模型一段提示词还要配合实际执行脚本调用工具。我这边推荐一个足够简单的骨架用 Python 写30 行以内搞定绝大部分需求from pathlib import Path from harness import skill, ctx skill(code-reviewer) def run(): # 1. 读取上下文产物 summary ctx.read_artifact(source-code-summary.md) changed_files ctx.changed_files() # 2. 调用 lint / 类型检查等工具 lint_report ctx.run_tool(linter, fileschanged_files) # 3. 把工具结果注入 prompt 上下文 prompt ctx.build_prompt( skill_namecode-reviewer, templatereview_template.j2, data{summary: summary, lint: lint_report, files: changed_files}, ) # 4. 调用模型生成审查报告 report ctx.llm.generate(prompt) # 5. 校验输出格式并落盘 ctx.validate_with_schema(report, schemareview-report.schema.json) ctx.write_artifact(review-report.md, report)这个骨架体现的是代码负责拿事实、模型负责做判断的分工。你不会让模型自己去跑 git diff它容易漏文件也不会让模型自己解析 JSON 输出它可能格式错乱。正确的姿势是所有确定性操作交给脚本和工具模型只处理真正的智力活动。3.3 给 Skill 配置工具权限与执行环境Skill 能不能安全地在企业仓库里运行一大半取决于工具权限设计。我们踩过最大的坑是给了 skill 太宽的 Shell 执行权限结果有一次 test-master 在跑测试的时候把整个临时目录给rm -rf了。从此之后我们强制每个 skill 声明自己需要的工具列表harness 层面做一层白名单映射。比如spec-writer只读文件读取、文档解析code-crafter读 写限定在工作区src/和tests/目录test-master读 执行只允许运行 pytest、go test、npm test 等白名单命令release-checker读 查询可查 git status、CI 状态但不能执行构建脚本之外的命令另外特别注意环境隔离问题。如果你的 skill 要安装依赖不要直接装在开发机全局环境。我们用了一个很轻量的办法每个 skill 执行时通过 Docker 容器挂载工作区容器内只预装该 skill 需要的运行时。比如 code-crafter 需要 Node 18test-master 需要 Python 3.11互不干扰。如果我图省事让两个 skill 公用一个环境后面会出现各种依赖地狱排查起来能让人崩溃。4. 8 个 Skill 的实际落地与编排细节4.1 前置 Skillspec-writer 与 arch-designer 的实现要点链路的第一环 spec-writer 最容易被人轻视但它恰恰决定了整条链路的最终质量上限。如果需求是模糊的后面所有环节都会放大这种模糊。企业里最常见的场景是一句消息丢过来订单列表加个筛选功能这句话的信息量根本不足以让 AI 完成后续任何工作。spec-writer 要做的就是逼出需求。它的工作流通常长这样读取用户原始输入识别哪些是事实、哪些是假设、哪些是缺失项。对缺失项逐条发起追问。注意这里不是让模型一次性列出 50 个问题那是偷懒的做法。我们的 skill 会让模型按业务优先级分批提问每轮最多 5 个用户答完后继续深化最多三轮。把确认后的信息整理成结构化 PRD包含用户故事、功能列表、验收标准、边界条件、数据字典、非功能需求。特别写出本阶段明确不包含的内容用来防止后续环节过度设计。arch-designer 接着读 PRD输出技术方案。这里我强烈建议在 skill 里内嵌一套架构约束规则比如新功能不允许引入额外中间件除非在方案中明确论证必要性、接口必须兼容现有版本如需破坏兼容必须标注迁移方案。没有这类约束的架构设计会非常飘模型动不动就给你上个消息队列或者推荐重构整个服务。4.2 中段 Skilltask-planner、code-crafter、code-reviewer 的协作机制task-planner 是整条链路里最容易被低估的 skill。核心难点在于粒度控制。任务拆得太粗code-crafter 要一次生成几百行代码质量必然崩拆得太细又会有大量上下文切换开销而且任务之间可能产生依赖冲突。我们的经验法则是每个任务能够在一个小时内完成验证闭环包含改代码、跑相关测试、更新最小文档。按这个标准一个 2000 行的新模块通常会拆成 20 到 30 个任务。code-crafter 处理单个任务时的策略也很关键。我建议让它遵循 TDD 方式执行先写一个暴露需求的最小测试再写实现最后跑通测试。但这里有个现实问题现网项目基本没有留好测试接口code-crafter 写测试时经常发现代码耦合严重无法 mock。所以我们在 code-crafter 里内置了对现有代码可测试性最小改动的指导原则允许它先做小范围重构但必须在任务描述里注明。code-reviewer 在链路中的作用是拉高底线。它不需要像资深工程师那样做高深的架构评审但必须能够识别出明显问题。实战中我们对 code-reviewer 有一个 KPI 导向的期望P0 级别问题数据丢失、崩溃、安全漏洞发现率必须高于 90%。为了实现这个目标我们给 code-reviewer 配了几个特殊的工具包括一个维护着历史 bug 模式清单的配置文件模型审查时会逐一比对。这比让它自由发挥可靠得多。4.3 后置 Skilltest-master、doc-scribe、release-checker 的收尾逻辑test-master 表面上只是跑一遍测试实际上它承担的是闭环验证职责。我们定义它的工作是三层单元测试、集成测试、回归测试。每一层都有明确的进入条件和退出条件。单元测试没跑过不允许进入集成。有一段时间我们把三步全让模型在一个 prompt 里完成结果它经常跳过回归测试因为它觉得刚才不是已经跑过了这就是缺乏阶段约束的后果。后来我们强制拆成三个子步骤并且每步都要落产物问题立刻消失。doc-scribe 是个争议很大的 skill很多人觉得让 AI 写文档就是在添乱。我们的处理办法很务实doc-scribe 不负责创造文档只负责同步文档。它读取 code-crafter 产生的代码 diff对比既有文档找出失真的地方并更新。凡是新增内容必须能在代码里找到依据找不到依据的内容一律不写。这种保守策略让文档准确率保持在一个可用水平。最后一道 release-checker 是质量闸门。它会综合所有前序产出来做最终裁决检查粒度包括所有任务是否完成、测试是否全绿、review 报告中的问题是否关闭、文档是否同步、目标分支是否干净、构建是否成功。我们的实现是让 release-checker 生成一个结构化清单每项标绿/标红只要有一项标红就拒绝进入发布流程。这个 skill 让 AI Coding 的产出在合并到主干之前有了一个客观的质量关卡而不是靠人肉碰运气。4.4 编排器的选择链式调度还是 Handler 分发8 个 skill 都开发好了接下来要解决编排问题。市面上不同 harness 框架的编排方式不太一样但归纳起来无非两种形态链式调度sequential pipeline和事件分发event-driven。链式调度特别适合我们这套全链路流程因为每个 skill 的输入输出关系是固定的。我们的 orchestrator 逻辑就是一张有序表PIPELINE [ (spec-writer, {}), (arch-designer, {require: spec.md}), (task-planner, {require: architecture.md}), (code-crafter, {require: tasks.json, batch: True}), (code-reviewer, {require: src/**}), (test-master, {require: review-report.md}), (doc-scribe, {require: test-report.md}), (release-checker, {require: doc-update.md}), ]链式调度的好处是心智负担小出问题好排查。但它的缺点是不够灵活一旦某个环节要跳过或回退就要在 orchestrator 里写一堆条件逻辑。所以我们在链式主路之外也给每个 skill 暴露了独立调用的入口。比如开发者只写了代码想单独跑 code-reviewer 和 test-master不需要强制走完整链路。事件分发则适合更复杂的动态场景但对企业内大部分标准交付流水线来说链式调度已经够用也更可控。5. 常见问题与排查技巧实录5.1 Skill 明明写了却不触发这是我们在推行 harness 过程中被问得最多的问题。表现是模型明明看到了 SKILL.md但就是不用或者偶尔用偶尔不用。排查思路要从两个层面入手。第一层是描述文档。检查description里有没有明确触发条件。很多人写的是你是一个代码审查专家请审查代码这其实是 role prompt 而不是触发条件。模型很难判断什么时候该用这个技能。我们改成执行完 code-crafter 生成代码后、进入测试阶段前必须调用本 skill 对工作区代码进行审查触发率立刻提升。第二层是 harness 侧的逻辑有些 harness 框架并不扫描所有 SKILL.md只扫描当前目录或者指定 index。如果发现 skill 从未被加载先去查框架的配置文件看技能发现skill discovery机制是怎么实现的。还有一个容易忽略的点SKILL.md 的 frontmatter 格式必须严格符合规范字段拼错一个字母都可能被静默忽略。5.2 上下文被拉爆全链路压测是怎么做的全链路跑起来之后最常遇到的问题是上下文爆炸。尤其到了 code-reviewer 和 test-master 这两个环节它们需要同时读取需求文档、架构文档、源码、diff、测试结果一旦项目大了上下文瞬间超限。我们的解题思路是把压测前置。每周我们会从线上真实任务里抽 30 个样本跑一遍完整的 8 skill 流水线专门记录每个环节的 token 消耗峰值。用这些数据给每道工序设定 token 预算。比如 spec-writer 预算 20K tokencode-crafter 单任务预算 15K token超出预算就强制进入总结-压缩状态把当前进展压缩成摘要后继续。这套压测机制已经跑了一个多月让我们的流水线稳定性提高了非常多至少没有出现过跑一半系统崩溃的情况。有个具体技巧分享一下在给模型注入代码时不要整文件塞。我们的 code-crafter 会先读取文件的结构化摘要函数列表、关键类名、对外接口让模型先规划改动点再用需要精确修改的函数体触发精确读取。这相当于给模型加了一层按需加载能把 token 消耗降低 40% 到 60%。5.3 工具权限、环境隔离、模型幻觉的坑工具权限问题我在第 3 节提到过环境隔离这里再补充两个实战教训。第一个是白名单命令的转义问题。我们曾允许 test-master 运行pytest {file}看着很安全但模型还是可能拼出一个带 shell 特殊字符的文件名从而造成命令注入。解决方式是在 harness 层禁用 Shell 解析所有参数必须通过数组传递并且对参数做严格校验。第二个是网络权限。默认情况下我们禁止所有 skill 在未经批准的情况下访问外部网络。原因是模型会产生幻觉以为自己调用了某个包的最新版本 API实际上根本没有安装。禁止网络访问后它就必须依赖本地环境中真实存在的东西幻觉比例明显下降。关于模型幻觉还有一个很隐蔽的场景code-reviewer 在审查时经常看出来一个根本不存在的 bug。后来我们分析这是因为它对代码理解不够深却要硬凑审查结论。解法是让 code-reviewer 在报告里对每个问题提供证据必须引用具体的代码行和调用链。如果模型给不出证据我们宁可相信它没发现问题。5.4 避坑速查表把这些年趟过的坑列成一张速查表方便你直接抄作业现象根因解决方案skill 不触发SKILL.md 描述缺少触发时机在 description 里写明XX 阶段完成后必须调用skill 不触发frontmatter 格式错误严格校验 yaml 字段别拼错 name/descriptiontoken 超限整文件导入上下文改用结构化摘要 按需读取代码越权修改工具权限过宽工具白名单 目录限定 禁用远程执行测试跳过回归缺乏阶段约束拆成独立子步骤每步必须落产物报告失真模型瞎编强制要求每条结论附带证据引用依赖不一致skill 共享环境Docker 容器隔离每 skill 独立运行时链路中断上游产物缺失I/O 校验 清晰报错信息写到这里其实这套 8 个 skill 的全链路方案本质上做的是把 AI Coding 从会写代码变成能交付可靠的代码。我个人的经验是Harness 工程这个方向的投入产出比极高它不需要你去调教模型也不需要你有算法功底它需要的只是把软件工程的常识翻译成模型能理解、能执行、能约束的语言。如果你也在企业里推 AI Coding不妨从复制这条链路开始哪怕一开始只有三四个 skill也比裸奔的 Agent 强得多先把骨架搭起来再慢慢往里面填属于你们组织的特殊技能这条路走得通。