前言

Harness Engineering这一概念在技术圈内已引起广泛讨论。较为通用的定义将其描述为Harness = Agent - Model——即除去模型本身之外的所有附加能力，例如MCP、Skill、提示词等，均可归为Harness的范畴。然而，本文聚焦于一个更具体的应用场景：在Claude Plugins中的Harness实践探索。这一定义虽与广义解读略有差异，但其核心理念一致——都是为确保模型能够稳定、可靠地输出结果。

关于Harness Engineering的具体概念，此处不再详述。以下简要梳理Prompt、Context与Harness三种范式的核心区别：

为什么需要这次实践

先从背景说起。团队正在开发一款针对服务端代码改造的影响面分析工具Claude Plugins。该工具的诞生源于Q2以来团队逐步向AI全栈转型的规划，核心挑战在于如何利用AI交付Java项目。当前，许多主流模型在新项目中编写代码已游刃有余，但对于那些历史包袱较重的存量项目，模型在编码过程中仍可能出现Bug——即便已引入Sdd/SuperPowers等增强开发范式来辅助。

目前已上线交付的两个服务端项目中，有一个在线上出现了问题。经过根因分析发现，是AI误改了一个本不应变动的业务入口。因此，为了最大程度保障交付质量，团队急需一套能够精准分析改动影响面的工具。

分析代码影响面对AI而言是一项复杂任务。它需要全面检索代码引用（已有GodeGraph/GitNexus等工具进行了深度优化）、梳理业务链路、评估风险、整理输出等。相信不少开发者都有类似体验：直接通过提示词将复杂任务丢给模型，执行过程中模型可能出现偷懒、偏离预定路径等情况。无论怎样调整提示词，最终结果往往与预期存在偏差——这通常源于模型自身的认知局限以及上下文窗口的限制。而Harness的作用之一，正是为了有效缓解这类问题。

架构拆解

关于这个分析代码改动影响面的Plugin，我们在工程手段上进行了大量设计。下面分享具体做法以及背后的设计思路。

1. 整体工作流 —— 用确定性的工程流程，管控非确定性的模型输出

从流程图可见，Plugin主要通过暴露Skill作为用户交互入口，Skill内部使用脚本驱动流程逐步推进（Step1 → Step2 → ...）。每个Step下的创造性任务仍然交由模型处理，模型执行完毕后，脚本负责将结果记录到yaml文件（状态机）中，对成果进行校验，然后继续执行下一个Step，直至整个流程结束。

这一设计带来了三点显著优势：

1. 流程可控：“执行哪一步”、“是否能继续推进下一步”完全由脚本掌控，可有效避免模型“提前收工”或“跳跃步骤”的问题。如果仅依靠提示词告诉模型执行步骤，即便清晰地列出了Step1/2/3，模型仍可能因注意力稀释、追踪能力不足、位置偏差等导致执行效果不理想。

2. 状态可追溯：关键步骤的执行结果会被记录到指定文件中（此处使用yaml格式）。以分析改动影响面的Skill为例，我们让模型直接调用Python脚本，脚本先生成所有待处理的任务，并为每个任务标记status: WAITING/DONE/FAILED状态。脚本将这些任务分派给模型执行并记录状态变化，这样在执行过程中就能清晰了解哪些任务已完成、哪些尚未处理。最终流程结束时，脚本会校验这个.yaml文件，针对未完成的任务，要求模型返回继续执行，确保所有任务均得到妥善处理。

3. 上下文可控：针对所调用的脚本，模型在脚本执行完成后能够获取哪些上下文，完全由脚本决定。举个具体例子：

   ---name: xxdescription: xx---
   
   ## 作用
   xx...
   
   ## 执行步骤
   
   ### Step1 - 生成改动任务
   执行
   ```bash
   python3 ${PLUGIN_ROOT}/script/generate.py" --create 
   ```
   
   ### Step2 - xxxxxx
   ...
   

   def main():
       # ...
       print(f"脚本输出的内容会被模型读到，可以输出你想让模型知道的上下文")
   if __name__ == "__main__":
       main()
   

   模型能获取哪些上下文，完全由脚本中print输出的内容决定。利用这一特性，可以在脚本中做文章——比如告知模型当前执行结果、下一步该做什么、下一步任务所需的参数等信息。

2. 状态机 —— 全/跨流程状态管理

状态机主要解决两个关键问题。

问题一：记录任务状态，兜底模型提前收工

面对复杂且任务量大的需求时，模型可能因上下文窗口限制、追踪能力不足等问题而提前收工。具体表现是：模型在对话框里宣布所有任务均已完成，但人工审查时却发现有些地方并未修改到位。反问“这块是不是没有改到”之后，模型才意识到还有任务尚未完成。

src/main/java/com/example/OrderService.java:
analysis_steps:
  - step1_分析影响面: WAITING/PROCESSING/DONE/FAILED
  - step2_分析风险点: WAITING/PROCESSING/DONE/FAILED

解决方法是为每个任务添加状态标记，任务执行完成后通过验证门对状态进行校验，校验通过才放行，否则打回重新执行。工作流程如下：

（图片占位）

问题二：跨Agent（mainAgent、subAgent）协作时的任务状态追溯 / 跨Skill工作流时的任务状态追溯

将关键步骤的执行结果记录到.yaml文件中，其他Agent/Skill执行时也能读取该记录，从而实现跨Agent/Skill的协作。设想一个全流程需求交付的Plugin，从PRD → 系分 → 开发 → 测试每个阶段都对应不同的Skill，下一步必然依赖前一步的执行结果，因此状态记录显得尤为重要。

3. Diff切割 —— 减少模型不确定性

这一层的核心思路是：将模型容易产生幻觉的任务拆分出来，使用脚本辅助完成，或者直接全部由脚本完成，从而降低模型的不确定性。

例如，在本次Plugin中，获取“当前分支相比origin/master改动了哪些文件、哪些代码块”这类任务对模型来说是容易产生幻觉的。因此，我们直接选择用脚本梳理好后再喂给模型。当每一个模型有概率出错的小任务都得到一层保障时，整个工作流的稳定性自然会显著提升。

4. SubAgent并发 —— 避免上下文窗口限制

执行复杂任务时，将全部任务都交给一个Agent处理，容易触发上下文窗口限制以及注意力分散的问题。Anthropic也曾遇到过类似情况：当上下文达到一定比例（约40%）时，模型会变得犹豫不决，甚至倾向于提前收工，即便任务尚未完成。

部分AI IDE支持开启subAgent，例如Claude Code、Cursor等。因此，可以换一种思路：用一个mainAgent控制主流程，复杂任务则由mainAgent派发subAgent来执行。这样subAgent在执行任务时拥有干净的上下文，不易出现提前收工的问题，整个工作流也不会发生上下文溢出。

这里可能有人疑惑mainAgent如何获取subAgent的运行结果。实际上，IDE会自动将subAgent的结果返回给mainAgent，这一点无需担心。但从稳定性和状态管理统一性的角度出发，通过回写状态机的方式会更加合适。工作流程如下：

（图片占位）

5. 验证门 —— 把控模型交付质量

验证机制是Harness理念中至关重要的一环。在一般的Prompt工程中，如果想验证结果，可能会写类似这样的提示词：“Review你的成果，识别有没有问题”。但仔细想想，让本身带有不确定性的模型来Review自己的输出，这就像让人用同一双眼睛检查自己的作业，难以发现根本性问题。此前我们也做过一些尝试——让模型生成一份方案文档，然后新建一个会话保持干净上下文，继续让模型Review这份方案是否存在问题，并重复这一动作。最终结论是，每次Review模型都会提出新的问题。让模型自己Review自己，显然不是一个能够趋于稳定的方案。

在这次实践中，关于验证部分的做法是将一个大任务进行拆解。例如，在一次代码改动分析任务中，diff里的每一个文件都可以拆分为一个小任务，而每一个文件中的改动又有不同维度需要分析（如调用链、影响面、逻辑错误、性能风险等），每个维度同样可以拆分为一个小任务，以此类推。任务类型也各不相同，有的任务只需执行通过即可，有的任务则涉及多个方面，需要模型执行得全面。最终，验证门需要完成两件事：

1. 结合状态机里任务的status，校验任务是否已执行完
2. 结合状态机里任务执行结果.yaml文件，校验模型是否执行到位

校验不通过则不允许放行，让模型重新执行该任务。具体实现同样通过脚本来控制，只需在脚本执行完后print结论，模型就会获取这个结论并做后续处理。不过，建议针对整个工程设计一套结构化的输出范式，以加强模型关注脚本执行结果的心智。工作流程与状态机类似，只是校验粒度更细，此处不再贴图。

6. Skill Prompt设计

尽管已采用多种工程化手段，但Prompt设计依然不可忽视。在这方面我们也踩过一些坑，总结出了一些实践经验。

简单Prompt vs 复杂Prompt

我们尝试了两种风格的Prompt。一种写得比较复杂，将各个场景下的正确案例、错误案例都列出来，用全面的自然语言举例说明什么是对的、什么是错的，并附加一些边界情况。另一种则写得比较简单，整个Prompt仅包含需要执行的Step。最终发现，Prompt越精简，模型的执行过程越稳定——过多的Prompt会导致模型注意力分散。不过，这一点可能因模型而异，各家观点也不尽相同，比如OpenAI倾向于使用详细的Prompt，而Anthropic则倾向于定期精简Prompt。

直接上代码 > 文字描述

这一点很好理解。某些模型在内部编码、预训练数据、分词逻辑方面天然偏向英文，因此在解析中文时可能存在偏差。测试发现，即使是很短的描述也有概率产生幻觉，而代码是通用的，不存在歧义问题。

维度不要太分散，否则模型每次执行的重点都不一样

起初，我们在代码中放置了一份包含34个风险点的风险点列表md文件，让模型逐一分析。经过多次测试后发现，有时模型最终输出的风险点不一致，甚至偏差较大。排查下来，根源在于风险点太过分散。后来，我们将34个具体的风险点整合为10个，并且从具体的点转变为给模型提供方向引导。

以下是几个主要Skill的最终提示词设计：

（Skill Prompt模板占位）

7. 整体目录设计

Plugin与单个Skill不同，Plugin可以视为一个Skill集合，因此目录设计需要兼顾通用性。

├── .claude-plugin/plugin.json          # 插件元信息
├── .cc-version                         # 版本号 (1.0.0)
├── README.md                           # 项目文档
├── constants/
│   ├── analysis_diff_risk/
│   │   └── filter-rules.yaml           # 文件过滤规则
│   └── common/
│       ├── runtime-constants.yaml      # 公用运行时配置
│       └── output-messages.yaml        # 输出消息模板
├── docs/
│   └── analysis_diff_risk_point.md     # 风险检查文档
│   └── analysis-diff-risk-step2.md     # 风险检查文档
├── script/analysis_diff_risk/
│   ├── analyze_diff.py                 # Git diff 解析 + YAML 生成
│   ├── execute_analysis.py             # 状态机引擎（列表/收集/汇总）
│   └── cleanup_state.py                # 清理临时状态
├── state/analysis_diff_risk/           # 运行时状态机
│   └── impact-analysis-${hash_id}.yaml # 待执行的任务列表
│   └── results_${hash_id}_batch.yaml   # subAgent执行任务的结果
├── skills/fe-analysis-diff-risk/
│   └── SKILL.md                        # Skill 入口定义
└── template/
    └── analysis_diff_risk_result.md    # 输出报告模板
    └── subagent_analyze_prompt.md      # subagent提示词

踩过的坑

1. 使用脚本输出执行结果时，需注意print中的文字描述要足够精确，否则也可能导致模型偏移。最好的做法是附带下一步需要做什么的信息。

2. 性能一般的模型在统计diff行数时容易出现偏差。我们选择直接用脚本算好每一段diff的start_line和end_line，再统一喂给模型，以确保准确性。

3. 当改动量较大时，模型的检索时间会明显变长。这是因为模型常用的检索方式是grep或ripgrep（rg）命令，其本质是通过正则模糊匹配项目中的代码字符，匹配完成后还需依赖模型来判断是否属于正确的场景。

举例来说：告诉模型“把项目中所有的start换成star”，模型会开始执行grep命令。由于只是正则模糊匹配，它无法区分语境，可能会匹配出各种不相关的结果。然后模型需要逐一分析上下文，判断哪些才是预期的场景，这样一来循环往复，检索速度自然被拖慢。

好消息是，目前社区已有开源库能够有效解决这些问题，例如codegraph。它会先将代码解析成结构图（AST + 符号关系图），记录“谁是什么角色”。开始检索时，它可以直接查索引，清晰知道哪些是变量定义、哪些是函数引用，甚至能精确得知代码在哪些地方被实际使用。实测下来，这种方式能减少约30%的耗时，而且比模型更加稳定，后续我们也计划将其集成到Plugin中。

效果与局限

1. 我们测试了Sonnet 4.6、Opus 4.8、deepseek-v4-pro、Qwen3.6 Plus等模型，均能按预期执行任务。
2. 服务端场景下可能存在跨上下游的情况。此时，上游或下游代码位于其他项目中，Skill无法读取到，会导致上下文不够完整。一个简单的解决办法是将上下游项目放在同一个文件目录下。

总结：Harness的核心启示

1. 我们当然期待能力更强大的模型能够一键帮我们完成所有事情，但模型的稳定性与边界同样不可忽视。
2. 除了学会使用模型，还应当深入探索模型相关的更深层次能力，以提升在未来竞争中的优势。
3. 在前端/服务端领域积累的那些工程化能力，在AI时代依然大有用武之地。平时也需重视基础能力的持续积累。