再次聊聊AI Coding对应的 Harness Engineering 的6 大支柱及其在 Coding 中的映射与部分实践
Harness Engineering 的 6 大支柱
无论是agent自身的Harness Engineering ，还是AI coding对应的Harness Engineering都有这几个方面：
- 方面一：上下文管理（Context Architecture）
- 方面二：工具系统（Tool System）
- 方面三：执行编排与多 Agent 协作（Execution Orchestration）
- 方面四：状态与记忆（State & Memory）
- 方面五：评估与观测（Evaluation & Observability）
- 方面六：约束与恢复（Guardrails & Recovery）
这次只聊聊AI coding对应的Harness Engineering这几方面的映射实践。
方面一：上下文管理
对agent上下文管理来说更多指的是在llm有限的上下文窗口中更好的留下有用有价值的信息。
在AI coding中这方面指的更多的是，如何提供给AI更好的工程信息，需求信息等信息。
在实践中更多是这样的：
AGENTS.md 当作项目入口信息，基本只承载目录，通过目录渐进式披露所有细分文档。
- 通过AGENTS指向设计文档、架构图、执行计划、质量评级等。比如ARCHITECTURE.md、Rules.md、doc/、wiki/等等
- 与之反面做法是AGENTS.md写了成百上千行，将信息一股脑塞入AGENTS.md
- 看自身项目情况，可以将业务侧信息与技术侧信息分开，doc目录一般更多放的是业务侧需求相关的信息，wiki更多放的是自身项目代码技术侧信息。
结构化规范需求文档
- 如果使用sdd流程开发需求，以Spec .md的形式承载把需求和设计决策。
- 这些文件也同时存进 Git 仓库，变成 AI 随时能调取的”长期记忆”。
变更隔离？
持久化知识库
- 前面说的doc 、 wiki目录下存放团队 Wiki、代码仓库、业务文档挂载为知识库。
- 同样需要通过渐进式披露的方式，通过一个目录让ai知道相关信息从哪里获取。具体来说 wiki目录下有一个 wiki.md 活着 wiki.json的形式文件作为目录，再指向具体组件库、通用业务库等。
- 可以在AGENTS.md要求必须先阅读这个目录，让AI之后可以自己通过目录在后续工作中自主获取信息。
专业化上下文、领域知识
- 在知识库建立的基础上，可以将固定开发流程、领域知识做成skill的形式。
- skill信息也需要渐进式披露，skill信息分三层（描述 → 指令 → 详细步骤），按需逐步加载，省 Context。
- 当前简单的固定的流程能用简单脚本来执行 还是脚本好一点，减少AI上下文的占用。
简单来说整个上下文工程也就是：
- 沉淀/建立 项目工程信息对应的md文档，便于AI查看
- 渐进式披露这些信息
- 固化流程&信息为skill/脚本等
方面二：工具系统（Tool System）
对agent来说工具系统更多指的是提供给llm给外界交互的途径，比如如何阅读代码文件，如何上网搜索信息等。
在AI coding中这方面指的更多的是，怎么在获取当前目录下，当前代码仓库之外的业务信息，怎么获取特定领域的专业能力。
脱离不了agent概念，这方面也需要skill、mcp等形式承载。
MCP形式，一般作用是连接外部数据源，有：
- 比如获取公司内部文档的特定 文档mcp
- 比如获取外部信息，figma url对应的信息的 figma mcp
- 比如接入 CI/CD、监控系统的 运维mcp
Skills形式，一般作用是封装领域专家经验，有：
- 固化特定模式的代码生成逻辑skill
- 需求文档转换为开发者视角的skill
- 持续迭代优化的skill
未来或许各部门都可以有一个主agent对外提供信息，通过A2A协议，跳过mcp 从agent开始对接信息等形式。
方面三： agent专业化与执行编排
如果是sdd开发流程，遵循 SDD 工作流：requirements.md → 人工审核 → task.md → 执行 → 归档。
可以根据自身项目的情况，可以简单划分为四个agent：
- plan agent：输入需求描述，输出结构化文档，包含任务清单、单元测试信息的那个。
- code agent： 输入结构化文档，根据其中的任务清单输出代码。
- test agent：根据代码，做规范合规检查和代码逻辑审查。
- ci agent：自动把 Spec 归档，更新相关项目知识库。
方面四：状态与记忆
对agent来说这方面更多指的是短期记忆长期记忆等。比如当前对话记忆，历史对话记忆。历史对话记忆又可称为持久化记忆。根据不同的类型划分 ，又可以划分为场景记忆、设定记忆等
在AI coding中这方面指的更多的是上下文管理中工程相关的信息。比如：
- 各级导航目录信息，或者说渐进式披露的信息。
- 结构化规范需求文档
- 持久化知识库
- 变更信息，比如change文件下需求变更信息等
方面五：评估与观测
对agent来说这方面更多指agent自身效果指标、体验指标、成本指标、可靠性指标等。比如任务完成率、输出准确性、幻觉率、首字延迟、响应时间、token消耗、工具调用次数等等。
在AI coding中这方面指的更多当前需求AI 生成的代码是不是靠谱的。
对应的验证检测方式就是：
- 语法检测：编译通过、Lint 检查、lsp验证等等
- 逻辑检测：单元测试、测试用例验证
- 规范检测：合规 安全性检测等等
- 人工介入：必要的权限等人工交叉验证等等
方面六：约束与恢复
对agent来说这方面偏向执行中断后如何恢复。
在AI coding中这方面指的更多当前需求AI 生成的代码是否按照项目工程的内部约定、有没有使用项目已有的工具类、有没有进行危险操作等。
对应的处理方式就是：
- rule红线硬性要求
- skill封装工具类、标准操作以供agent调用
- 声明特定操作必须备份、高危操作必须经过准备好的检查列表才允许。
- 所有变更通过 Git 管理，随时可以回滚。允许回退到上一个状态。workspace隔离操作等
实践一 知识沉淀之错例沉淀
正向的，从已有代码文档转换为wiki下的知识一般而言比较简单，但是团队遇到的踩坑经验、遇到的错误修复等经验 难以转换为文档沉淀下来。
往往会造成什么问题？
- 重复踩坑：一次 session 反复纠偏踩出来的路径，session 结束就清零。下一个同事碰同样问题，AI 又是零基础起步。
- 知识碎片化：老同事脑子里有一套”这么做才对”的 pattern，但没人有动力写下来。文档永远跟不上代码变更的速度。到了 AI 时代，靠的不是知识管理，是靠运气——这次 session 的上下文恰好覆盖了上次的历史，就对了；没覆盖，就错了。
这里就说一下如何沉淀ai coding中遇到的经验。
- 源信息从哪里来？ 很简单 agent对话信息都会保存下来，在一个个session信息中。
- 这些session信息如何使用？
如果仅仅是让agent从session中“提取你认为有价值的内容” 会导致什么样的后果？
- 对话信息量太大，llm可能会提取大量无关内容
- 对话信息上下文不全，llm提取的可能只在特定上下文环境才会生效的经验。不符合通用场景。
所以这个沉淀过程中我们也需要对llm进行特定的约束和引导。
- 分类归因处理，沉淀不同的类别的经验，让llm先分类。比如分类为：
- 新API，新工具使用错误
- 项目特定语言、代码映射、使用偏好
- 团队通用常识
- 颗粒度使用错误
- 然后判断当前信息是否是可沉淀的经验。比如要求经验必须：
- 解决了什么可复用问题、
- 是否是项目特有
- 源码探索做事实性校验
- 入库处理，往往有以下场景
- 库中不存在同类目标经验
- 与历史经验同向，但带有实质新信息，合并更新
- 与新经验在核心结论上可互相替代，跳过
- 与历史经验结论直接冲突，标记为冲突并提人工裁决
最终再将上述经验转换为agent可渐进式阅读的上下文知识。
实践二 需求文档转换为 ai/开发者 可理解操作的文档
出现这一问题的原因有团队不同角色对同同一事物的术语不同，或者描述不够清晰。比如提醒，有红点提醒、弹窗提醒、无干扰提醒、强制提醒等等形式。
作为开发，将需求文档、设计文档转换为sdd流程中的规格文档，也可以新增一些流程去完善、规范这个过程。
比如：
- 意图消歧 - 「这个目标可能对应 4 种技术解读」
- 模块定位 - 目录树 + 解读结果
- 关键词搜索 - 函数声明 + 位置
- 调用链追踪 - 完整调用链
- 验证确认 - 最终改动点 + 理由
这样一个流程将需求点，转换为具体的开发文档。其中需要说明一下的是，意图消歧这一步往往需要沉淀一个 领域语义桥 来抹平”设计 / 协议”和”代码”的鸿沟。
这一层是最容易被低估、却最能体现工程价值的部分。
举个例子，设计侧转换为开发侧：
- 设计稿上写着 Mobile/callout，AI 该怎么写代码？目测字号？硬编码 [UIFont systemFontOfSize:15]？——都不对。Skill 把这种翻译规则全部沉淀到 figma_token_mapping.md
同理 产品侧转换为开发侧 也需要这样的一个领域语义桥来进行转换。在skill中建立一个强信号关键词表来进行语义的转换，便于ai来查看理解。