Harness Engineering Workflow — 完整工作流文档

版本: v1.0
创建日期: 2026-05-14
理论基础: Mitchell Hashimoto (2026.2.5) / OpenAI 百万行代码实践 / Anthropic 长时间运行 Agent 实践
适用范围: OpenClaw 主 Agent + 37 子 Agent 工作区

📋 目录

核心定义与哲学
工作流全景图
第 1 层：上下文工程
第 2 层：结构化执行
第 3 层：持久化记忆
第 4 层：架构约束
第 5 层：反馈循环
第 6 层：债务管理
落地工具清单
附录：审计检查表

一、核心定义与哲学

定义

Harness Engineering（驾驭工程）
围绕 AI Agent 构建约束机制、反馈回路、工作流控制和持续改进循环的系统工程实践。

核心哲学

人类掌舵，Agent 执行（Human Steer, Agent Execute）

Hashimoto 金句

"Agent 的每一次失败，都是环境设计不完善的信号。正确的回应不是换一个更强的模型，而是不断优化它的运行环境。"

关键区分

Harness 不优化模型本身——模型还是那匹马
Harness 优化的是模型运行的环境——缰绳、马鞍、辔头
瓶颈不在模型智能，而在基础设施（五个独立团队共识）

二、工作流全景图

                         ┌──────────────────────────┐
                         │    Harness Engineering     │
                         │      驾驭工程体系          │
                         └──────────┬───────────────┘
                                    │
        ┌───────────────┬───────────┼───────────┬───────────────┬───────────────┐
        │               │           │           │               │               │
        ▼               ▼           ▼           ▼               ▼               ▼
   ┌─────────┐   ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌──────────┐  ┌──────────┐
   │Layer 1  │   │Layer 2  │  │Layer 3  │  │Layer 4  │  │Layer 5   │  │Layer 6   │
   │上下文工程│   │结构化执行│  │持久记忆 │  │架构约束 │  │反馈循环  │  │债务管理  │
   └────┬────┘   └────┬────┘  └────┬────┘  └────┬────┘  └────┬─────┘  └────┬─────┘
        │              │            │            │              │             │
        ▼              ▼            ▼            ▼              ▼             ▼
   让Agent看懂    思考≠执行    进度落盘    规则机械化   Agent审Agent  自动清理

六层职责

层级	回答什么问题	实现方式
L1 上下文工程	Agent 能"看懂"项目吗？	AGENTS.md + Tier 2/3 文档体系
L2 结构化执行	Agent 按正确流程做事吗？	思→规→执→验 + update_plan
L3 持久化记忆	下次会话还能接上吗？	PROGRESS.md + git log
L4 架构约束	规则能机械化执行吗？	Linter 规则 + CI 检查 + 错误格式
L5 反馈循环	出错能自我发现吗？	Agent 自审 + 跨 Agent 审查
L6 债务管理	技术债务会累积吗？	后台定期扫描 + 自动 PR

三、第 1 层：上下文工程

原则：让 Agent "看得懂"项目。上下文是稀缺资源，按需分配。

3.1 三层上下文体系

┌──────────────────────────────────────────────────┐
│ Tier 1 — 热记忆 (Hot)                              │
│ ├─ 每次会话自动加载                                  │
│ ├─ AGENTS.md（工作区规则+反模式）                     │
│ ├─ SOUL.md（人格+执行准则）                          │
│ ├─ TOOLS.md（环境笔记+进度约定）                      │
├──────────────────────────────────────────────────┤
│ Tier 2 — 领域专家 (Warm)                            │
│ ├─ 按任务类型触发时加载                               │
│ ├─ 嵌入式 C 铁律（仅处理 C 代码时注入）                │
│ ├─ Skill 文件（akshare-finance、embedded-dev 等）    │
│ └─ 项目专属知识库（PROJECT_KNOWLEDGE.md）            │
├──────────────────────────────────────────────────┤
│ Tier 3 — 冷记忆 (Cold)                              │
│ ├─ Agent 主动查询时加载                               │
│ ├─ 芯片 datasheet / 数据手册                        │
│ ├─ 历史会话记录 / 研究文档                           │
│ └─ 外部 API 文档 / 规格说明                          │
└──────────────────────────────────────────────────┘

3.2 Tier 1 文件加载顺序

每次新会话启动：

bash

# 步骤 1：建立人格
cat SOUL.md

# 步骤 2：加载工作区规则
cat AGENTS.md

# 步骤 3：了解环境
cat TOOLS.md

# 步骤 4：检查进行中任务（如有）
cat PROGRESS.md 2>/dev/null || echo "无进行中任务"

3.3 Tier 2 触发规则

触发条件	注入内容	来源文件
用户提到嵌入式 C / MCU / 固件	嵌入式 C 开发铁律（10 条）	SOUL.md §嵌入式 C 开发铁律
用户提到股票/基金/行情	AKShare 财经数据技能	skills/akshare-finance/SKILL.md
用户提到 BT896X / bluetrum	Bluetrum 项目知识库	.agents/bluetrum/PROJECT_KNOWLEDGE.md
用户要求代码审查	代码审查规范	skills/code-review/SKILL.md
用户说"发消息给..."	企业微信消息技能	skills/wecom-msg/SKILL.md

3.4 上下文填充原则

✅ 按需分片加载，不全量加载大文件（>500行的文件用 offset/limit）
✅ 信息密度优先——给关键信息，不给噪音
✅ 代码注释精简——不写显而易见的注释
❌ 不要把项目全貌塞进一个上下文窗口
❌ 不要从上下文窗口读历史——用文件系统

四、第 2 层：结构化执行

原则：思考与执行分离。审查计划远比审查代码快。

4.1 执行序列

┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐
│ 1. 思考  │───▶│ 2. 规划  │───▶│ 3. 执行  │───▶│ 4. 验证  │
│ Think    │    │ Plan     │    │ Execute  │    │ Verify   │
└──────────┘    └──────────┘    └──────────┘    └──────────┘
  理解需求        拆分步骤        逐步完成        编译/测试
  明确边界        update_plan     代码可编译      端到端验证
  评估约束        人工审查点      每步有产出      可能风险

4.2 各阶段具体要求

思考（Think）：

理解用户真实需求，识别隐含约束
明确："这属于哪个领域？需要 Tier 2 上下文吗？"
评估复杂度：简单（单步）/ 中等（3-5步）/ 复杂（需多会话）

规划（Plan）：

使用 update_plan 创建结构化步骤
每个步骤必须可验证（有明确产出物）
复杂任务插入人工检查点（checkpoint）
规划完成后，等待确认再执行（关键步骤）

执行（Execute）：

按 plan 步骤逐步推进
每步完成后立即验证（编译/运行/检查）
遇到问题不跳过，更新 plan 解决
进度实时写入 PROGRESS.md

验证（Verify）：

代码：必须编译通过 + 运行/测试通过
配置：必须检查语法 + 逻辑正确性
分析：必须多数据源交叉验证
验证失败 → 回到执行阶段，不标记完成

4.3 四类任务的执行模板

代码开发类

1. [思考] 理解需求 → 读现有代码 → 确认边界
2. [规划] update_plan → 拆分实现步骤
3. [执行] 逐个文件修改 → 每步编译检查
4. [验证] 全量编译 + 运行测试 + 边界测试

数据分析类

1. [思考] 明确数据源 → 评估可靠性
2. [规划] 确定查询路径 → 备选方案
3. [执行] 获取数据 → 交叉验证
4. [验证] 数据一致性检查 → 异常值审计

文档编写类

1. [思考] 明确受众 → 确定结构
2. [规划] 列出章节大纲 → 确认信息源
3. [执行] 逐章节编写 → 每章检查准确性
4. [验证] 全文通读 → 链接和引用检查

运维操作类

1. [思考] 明确操作范围 → 评估风险
2. [规划] 写出 rollback 方案 → 确认备份
3. [执行] 逐步执行 → 每步检查状态
4. [验证] 服务正常性检查 → 日志审计

4.4 人工检查点规则

以下场景必须等待用户确认再继续：

删除文件/数据
对外发送消息/通知
修改生产配置
超过 3 个文件的批量修改
涉及安全/权限的操作

五、第 3 层：持久化记忆

原则：进度在文件系统上，不在上下文窗口里。每次会话都可以从零接手。

5.1 进度文件规范

文件位置： {项目根目录}/PROGRESS.md

模板： harness/PROGRESS_TEMPLATE.md

必填字段： 任务背景、子任务 ([ ]/[x])、当前状态、阻塞项、关键决策记录、文件变更清单、验证记录

新建任务时：cp harness/PROGRESS_TEMPLATE.md PROGRESS.md

5.2 进度更新时机

时机	操作
新任务开始	创建 PROGRESS.md，填入任务背景和子任务列表
每完成一个子任务	将 `[ ]` 改为 `[x]`，更新"当前状态"
遇到阻塞	更新"阻塞项"，记录原因
会话结束前	更新"下一步"，确保下个会话能接上
任务完成	更新整体状态为"已完成"，总结产出

5.3 Agent 角色分工

角色	职责	权限	调用时机
主 Agent	总控协调、任务拆解、进度管理	全部（受约束）	默认
研究 Agent	探索代码库、分析实现细节	只读	需要理解现有代码时
规划 Agent	将需求分解为结构化任务	只读	复杂任务开始时
执行 Agent	实现单个具体任务	限定范围读写	编码/配置修改
审查 Agent	审计完成的工作，标记问题	只读 + 标记	执行完成后
调试 Agent	修复审查发现的问题	限定范围修复	审查发现问题后

5.4 Git 集成规范

每个子任务完成后：git commit -m "[task-id] 子任务描述"
会话结束时：确保所有变更已提交或至少 staged
Commit message 格式：[模块] 简短描述（如 [uart] fix fifo watermark overflow）
无意义的 WIP commit 在每个任务完成时 squash（不跨任务合并）

六、第 4 层：架构约束

原则：约束必须机械化执行。文档写了不等于 Agent 会遵守。

6.1 全局反模式（硬性禁令）

#	反模式	检测方式
1	一个会话企图做完整个大项目	人工 + plan 步数 >5 触发警告
2	没验证就说完成	必须提供编译/测试输出证据
3	完全不读项目文件就开始写代码	必须先 read 至少一个相关文件
4	保留不正确的代码模式	发现坏模式必须指出并修正
5	用上下文窗口代替文件系统	进度必须写入 PROGRESS.md

6.2 嵌入式 C 领域约束

#	规则	违反检测
1	只用 C，不用 C++	输出 .cpp 文件即违规
2	默认不用 malloc/free	代码含 malloc 需显式说明理由
3	volatile + 临界区处理	中断共享变量无 volatile 即违规
4	整数优先于浮点	无理由使用浮点即违规
5	静态分配优先于动态	需说明分配策略

6.3 错误格式规范

所有错误/警告遵循统一格式，便于 Agent 自动解析：

ERROR: {类别} — {简短描述}
  原因: {为什么会发生}
  修复: {具体修复步骤}
  文件: {path}:{line}
  参考: {相关文档链接}

示例：

ERROR: 中断安全 — ISR 中使用的全局变量未声明 volatile
  原因: isr_flag 在 UART ISR 和主循环中共享，编译器可能优化掉主循环中的读取
  修复: 将 uint8_t isr_flag 改为 volatile uint8_t isr_flag
  文件: app/driver/uart.c:47
  参考: SOUL.md §嵌入式 C 开发铁律 第4条

6.4 提交前自检清单

每次提交代码前，必须完成：

[ ] 代码已编译通过（提供编译输出摘要）
[ ] 相关测试已运行（提供结果）
[ ] 边界条件已考虑（缓冲区/超时/溢出）
[ ] 中断安全已审查（如有 ISR）
[ ] 代码风格符合项目规范
[ ] PROGRESS.md 已更新

七、第 5 层：反馈循环

原则：Agent 自我审查 + 跨 Agent 交叉审查，形成闭环。

7.1 自审协议

每完成一个执行步骤，执行自审：

1. [自审] 对照需求逐条检查产出
2. [自审] 检查是否满足 SOUL.md 约束
3. [自审] 检查是否触发任何反模式
4. [修复] 发现的问题立即修复
5. [记录] 自审结果写入 PROGRESS.md

7.2 跨 Agent 审查流水线

执行 Agent            审查 Agent            调试 Agent
     │                     │                     │
     ├── 提交代码 ────────▶│                     │
     │                     ├── 审查通过？         │
     │                     │   ├─ 是 → 合并       │
     │                     │   └─ 否 → 标记问题 ─▶│
     │                     │                     ├── 修复问题
     │   ◀─────────────────┴─────────────────────┘
     │                     
     └── 进入下一轮

调用方式：

bash

# 使用专用审查 Agent 审查当前变更
openclaw agent run --agent code-reviewer "审查 app/driver/ 下的最新变更，检查中断安全和缓冲区边界"

# 使用 bug-hunter 扫描潜在缺陷
openclaw agent run --agent bug-hunter "扫描 app/ 目录，查找资源泄漏和竞态条件"

7.3 自愈循环

当测试或审查发现问题时：

发现问题 → 记录错误（ERROR: 格式） → 自动修复 → 重新验证 → 通过/升级

同一问题修复 3 次仍失败 → 升级为阻塞项 → 记录到 PROGRESS.md 并请求人工介入
修复过程中发现新问题 → 不在同一循环修复 → 记录新 issue，继续当前修复

7.4 验证通过标准

产出类型	通过条件
C 代码	编译成功 + 全部相关测试通过 + 无新增 warning
Python 脚本	执行无报错 + 输出格式正确
文档	链接可访问 + 代码示例可运行
配置	语法检查通过 + 服务正常启动
数据分析	多数据源交叉验证 + 异常值已标注

八、第 6 层：债务管理

原则：持续小额偿还。技术债不能等项目结束再清理。

8.1 定期清理策略

频率	任务	工具
每次提交	不引入明显坏模式	自审检查
每周	扫描新增的代码风格偏差	bug-hunter Agent
每月	文档与代码一致性检查	docs-writer Agent
季度	全量架构合规审查	code-reviewer Agent

8.2 垃圾回收规则

在以下场景主动清理：

发现过时注释/文档 → 立即更新或删除
发现死代码（未使用的函数/变量） → 标注 // TODO: remove if unused by YYYY-MM-DD
发现重复代码块 → 在 PROGRESS.md 阻塞项中记录，标注 TODO-REFACTOR，不立即修改（避免范围蔓延）
发现不符合项目风格的新代码 → 立即修正

8.3 文档同步

每次修改公开接口/API → 同步更新对应文档
每次修改配置项 → 同步更新配置说明
发现文档与代码不一致 → 以代码为准更新文档，记录到 commit message

九、落地工具清单

9.1 文件体系

/mnt/d/openclaw/
├── SOUL.md                  ← Tier 1: 人格 + 执行准则 + 领域铁律
├── AGENTS.md                ← Tier 1: 工作区规则 + 反模式 + 角色矩阵
├── TOOLS.md                 ← Tier 1: 环境笔记 + 进度约定
├── PROGRESS.md              ← Tier 1: 当前进行中任务（有任务时存在）
├── HEARTBEAT.md             ← 心跳检查配置
├── harness/
│   ├── HARNESS.md           ← 本文档：完整工作流说明
│   ├── PROGRESS_TEMPLATE.md ← 进度文件模板
│   └── session-init.sh      ← 会话启动脚本
└── .agents/                 ← 37 个专用 Agent 工作区

9.2 会话启动脚本 (harness/session-init.sh)

bash

bash harness/session-init.sh [项目路径]

包含四个阶段：

Tier 1 上下文文件存在性校验
Git 仓库状态检查
PROGRESS.md 进行中任务检查
环境工具链检查

完整脚本见 harness/session-init.sh

9.3 错误格式宏（嵌入 C 项目用）

// 编译期错误标注宏 — 仅 GCC/Clang 可用（IAR/Keil/MSVC 用 #pragma message 替代）
// 格式: ERROR: 类别 - 描述\n  修复: 具体步骤\n  文件: path:line

#define HARNESS_ERROR(category, desc, fix) \
    _Pragma("message \"ERROR: " category " - " desc "\"") \
    _Pragma("message \"  修复: " fix "\"")

9.4 OpenClaw 集成

通过 OpenClaw 的 Project Context 机制，Tier 1 文件会自动注入到每次会话：

yaml

# gateway config 中的项目上下文配置
project_context:
  files:
    - SOUL.md
    - AGENTS.md
    - TOOLS.md
  auto_inject: true

十、附录：审计检查表

A. 每次会话启动时检查

[ ] SOUL.md / AGENTS.md / TOOLS.md 已加载
[ ] PROGRESS.md 已检查（如有）
[ ] 上次会话的 git log 已了解

B. 每个任务开始时检查

[ ] 已调用 update_plan 拆分步骤
[ ] 复杂度已评估（简单/中等/复杂）
[ ] Tier 2 上下文已判断是否需要
[ ] 人工检查点已标注（如需要）

C. 每个子任务完成时检查

[ ] 产出物已创建/修改
[ ] 编译/测试/运行验证已通过
[ ] PROGRESS.md 已更新 [x]
[ ] 自审已执行
[ ] 无新引入的反模式

D. 每次会话结束时检查

[ ] PROGRESS.md "当前状态"和"下一步"已更新
[ ] 所有代码变更已提交或 staged
[ ] 无未解决的阻塞项（如有，已记录原因）

E. 每周审计检查

[ ] 是否有 PROGRESS.md 遗留超过 7 天？
[ ] 是否有未关闭的长期 issue？
[ ] 文档与代码一致性扫描
[ ] 代码风格偏差统计

📊 版本历史

版本	日期	变更
v1.0	2026-05-14	初始版本，基于 Hashimoto/OpenAI/Anthropic 实践整理

这个文档本身也是活的——每次发现新的失败模式，就更新对应的层级。
参考 Hashimoto 的 Ghostty 实践：文档中每一条规则背后，都对应着至少一个过去的坑。

Harness Engineering Workflow — 完整工作流文档 ​

📋 目录 ​

一、核心定义与哲学 ​

定义 ​

核心哲学 ​

Hashimoto 金句 ​

关键区分 ​

二、工作流全景图 ​

六层职责 ​

三、第 1 层：上下文工程 ​

3.1 三层上下文体系 ​

3.2 Tier 1 文件加载顺序 ​

3.3 Tier 2 触发规则 ​

3.4 上下文填充原则 ​

四、第 2 层：结构化执行 ​

4.1 执行序列 ​

4.2 各阶段具体要求 ​

4.3 四类任务的执行模板 ​

代码开发类 ​

数据分析类 ​

文档编写类 ​

运维操作类 ​

4.4 人工检查点规则 ​

五、第 3 层：持久化记忆 ​

5.1 进度文件规范 ​

5.2 进度更新时机 ​

5.3 Agent 角色分工 ​

5.4 Git 集成规范 ​

六、第 4 层：架构约束 ​

6.1 全局反模式（硬性禁令） ​

6.2 嵌入式 C 领域约束 ​

6.3 错误格式规范 ​

6.4 提交前自检清单 ​

七、第 5 层：反馈循环 ​

7.1 自审协议 ​

7.2 跨 Agent 审查流水线 ​

7.3 自愈循环 ​

7.4 验证通过标准 ​

八、第 6 层：债务管理 ​

8.1 定期清理策略 ​

8.2 垃圾回收规则 ​

8.3 文档同步 ​

九、落地工具清单 ​

9.1 文件体系 ​

9.2 会话启动脚本 (harness/session-init.sh) ​

9.3 错误格式宏（嵌入 C 项目用） ​

9.4 OpenClaw 集成 ​

十、附录：审计检查表 ​

A. 每次会话启动时检查 ​

B. 每个任务开始时检查 ​

C. 每个子任务完成时检查 ​

D. 每次会话结束时检查 ​

E. 每周审计检查 ​

📊 版本历史 ​

Harness Engineering Workflow — 完整工作流文档

📋 目录

一、核心定义与哲学

定义

核心哲学

Hashimoto 金句

关键区分

二、工作流全景图

六层职责

三、第 1 层：上下文工程

3.1 三层上下文体系

3.2 Tier 1 文件加载顺序

3.3 Tier 2 触发规则

3.4 上下文填充原则

四、第 2 层：结构化执行

4.1 执行序列

4.2 各阶段具体要求

4.3 四类任务的执行模板

代码开发类

数据分析类

文档编写类

运维操作类

4.4 人工检查点规则

五、第 3 层：持久化记忆

5.1 进度文件规范

5.2 进度更新时机

5.3 Agent 角色分工

5.4 Git 集成规范

六、第 4 层：架构约束

6.1 全局反模式（硬性禁令）

6.2 嵌入式 C 领域约束

6.3 错误格式规范

6.4 提交前自检清单

七、第 5 层：反馈循环

7.1 自审协议

7.2 跨 Agent 审查流水线

7.3 自愈循环

7.4 验证通过标准

八、第 6 层：债务管理

8.1 定期清理策略

8.2 垃圾回收规则

8.3 文档同步

九、落地工具清单

9.1 文件体系

9.2 会话启动脚本 (harness/session-init.sh)

9.3 错误格式宏（嵌入 C 项目用）

9.4 OpenClaw 集成

十、附录：审计检查表

A. 每次会话启动时检查

B. 每个任务开始时检查

C. 每个子任务完成时检查

D. 每次会话结束时检查

E. 每周审计检查

📊 版本历史