harness · diff
git:20260501.29c7783 to git:20260501.5b45098
14 added, 5 removed. Audit A to A.
---
name: harness
description: |
Harness Engineering 最小实践 — 三角色 AI 自治循环（Inspector → Worker → Reviewer），通过 TODO.md 共享看板驱动持续改进。支持即时执行和定时调度。当用户提到"AI 自治循环"、"自动巡检修复"、"定时改进代码"、"harness engineering"、"启动 harness"时使用。触发词：/harness
trigger: /harness
compatibility: Claude Code
license: MIT
---
# /harness
**Harness Engineering 最小实践。** 用三条约束带（Inspector、Worker、Reviewer）将 AI 的创造力约束在正确的轨道上，通过 TODO.md 共享看板驱动持续改进。灵感来自 Harness Engineering 方法论：用轻量但确定性的流程框架，让 AI Agent 从"自由发挥"变成"可预测地交付高质量成果"。
## 触发条件
### 即时执行
- 用户输入 `/harness` — 完整循环（Inspector + Worker+Reviewer loop）
- 用户输入 `/harness inspect` — 只运行 Inspector
- 用户输入 `/harness work` — 只运行 Worker+Reviewer 一次
- 用户输入 `/harness loop` — 持续运行 Worker+Reviewer 直到没有可做的任务
用户可以在命令后附带自然语言指令，作为本轮循环的额外上下文。例如：
- `/harness 这次重点关注静默数据丢失问题`
- `/harness work 先修 P0 的环境变量检测`
- `/harness inspect 跳过竞争分析，只做本地巡检`
### 定时调度（cron）
使用 Claude Code 内置 CronCreate/CronDelete/CronList 工具，天然 session 隔离——不同 session 的 cron 互不影响。
| 命令 | 说明 |
|------|------|
| `/harness cron "*/30 * * * *"` | 每 30 分钟跑一次 full cycle |
| `/harness cron "*/30 * * * *" inspect` | 每 30 分钟只跑 Inspector |
| `/harness cron "0 */2 * * *" work` | 每 2 小时跑一次 Worker+Reviewer |
| `/harness cron "*/15 * * * *" loop` | 每 15 分钟持续消化任务 |
| `/harness cron list` | 查看当前 session 所有 harness cron |
| `/harness cron stop <job_id>` | 删除指定 cron |
| `/harness cron stop` | 删除当前 session 所有 harness cron（交互确认后逐个删除） |
**限制说明：**
- Cron job 仅在当前 Claude Code session 存活期间有效，关闭终端后失效
- Recurring job 7 天后自动过期
- 只在 REPL idle 时触发，不会打断正在进行的对话
## 三角色协议
### 核心原则：验证产出
**每个角色都必须验证自己的产出，不能只"做完了"就交差。**
- Inspector：产出任务后，检查任务描述是否足够清晰、hint 是否可操作
- - Worker：修完代码后，跑单元测试 + 尽力跑端到端验证（`sf run`）
- - Reviewer：审查时，如果 Worker 没做端到端验证且改动影响 workflow，应拒绝或补验
+ - Worker：修完代码后，按项目文档（`AGENTS.md` / `CLAUDE.md` / `TODO.md` / README 等）定义的验证命令执行相关检查；如果项目定义了端到端或真实流程验证，必须执行并记录结果
+ - Reviewer：审查时，确认 Worker 已执行与本次改动相关的验证命令；如果项目定义了端到端或真实流程验证且改动影响该路径，Worker 未验证时应拒绝或补验
- 端到端验证不是可选的。如果因外部依赖不可用而无法验证，必须显式记录原因。
+ 端到端验证不是可选的。如果项目没有特定的 E2E/真实流程验证，或因外部依赖不可用而无法执行，必须显式记录原因。
```
Inspector (规划师) — 决定方向，发现任务
↓ 写入 TODO.md
TODO.md (共享看板)
↓
Worker (修复者) — 领任务，改代码
[待领取] → [进行中] → [待审查]
↓
- Reviewer (审查者) — 审查代码，commit 或打回
- 通过 → Done Log + git commit
+ Reviewer (审查者) — 审查代码，按项目规则决定是否提交或打回
+ 通过 → Done Log + （仅在允许时）git commit
不通过 → [被拒绝] + 修复指引
↓
Worker 重新领取 [被拒绝]...
```
## 任务状态机
| 标记 | 含义 | 谁可以改 |
|------|------|----------|
| `[待领取]` | 未领取 | Inspector 可新增/修改，Worker 可领取 |
| `[进行中]` | Worker 正在做 | Worker 领取时设置，其他人不动 |
| `[待审查]` | Worker 完成 | Worker 完成时设置，Reviewer 审查 |
| `[被拒绝]` | Reviewer 打回 | Reviewer 拒绝时设置，Worker 可重新领取 |
## 执行步骤
### Step 1 — 解析用户指令
从用户输入中提取：
1. **是否为 cron 模式**: 输入中包含 `cron` 关键字
2. **模式**: cron / inspect / work / loop / full（默认）
3. **额外上下文**: 命令后面的自然语言文本（如果有）
如果是 cron 模式，跳到 Step 5。否则继续 Step 2。
将额外上下文保存到临时文件：
```bash
echo "用户额外指令: <用户输入的自然语言>" > /tmp/harness-context.txt
```
如果没有额外上下文，创建空文件（子进程检测到空文件就不注入）。
### Step 2 — 确认项目环境
```bash
# 确认在项目根目录
test -f CLAUDE.md && test -f TODO.md || echo "NOT_SKILLS_FLOW"
# 确认 skill 脚本存在（相对于 skill 目录）
test -f ../harness/inspector.sh && test -f ../harness/worker-reviewer.sh || echo "SCRIPTS_MISSING"
```
如果环境不对，停止并告知用户。
+ 运行方式示例：
+ ```bash
+ cd <project> && bash ~/.codex/skills/harness/inspector.sh
+ cd <project> && bash ~/.codex/skills/harness/worker-reviewer.sh --loop
+ HARNESS_PROJECT_DIR=/abs/path/to/project bash ~/.codex/skills/harness/inspector.sh
+ ```
+
如果 `TODO.md` 不存在，创建一个最小模板：
```markdown
# Project Improvement Board
## Current Phase: 初始化
## Goals
- [ ] 待 Inspector 首次巡检后填写
## Done Log
```
### Step 3 — 根据模式执行
#### 模式: inspect
```bash
cd <项目目录> && bash <skill目录>/inspector.sh
```
#### 模式: work
```bash
cd <项目目录> && bash <skill目录>/worker-reviewer.sh
```
#### 模式: loop
```bash
cd <项目目录> && bash <skill目录>/worker-reviewer.sh --loop
```
#### 模式: full（默认）
```bash
# Phase 1: Inspector 巡检
cd <项目目录> && bash <skill目录>/inspector.sh
# Phase 2: Worker+Reviewer 循环
cd <项目目录> && bash <skill目录>/worker-reviewer.sh --loop
```
### Step 4 — 输出结果
完成后向用户汇报：
```
Harness 循环完成
Inspector:
- 生存判定: 继续/终止/转型
- 新增任务: N 个
- 方向调整: 有/无
Worker+Reviewer:
- 完成任务: N 个
- 被拒绝任务: N 个
- 剩余待领取: N 个
下一轮: 输入 /harness 继续
```
### Step 5 — cron 模式（使用内置 CronCreate/CronDelete/CronList）
#### 5.1 创建定时任务: `/harness cron "<cron表达式>" [mode]`
1. 解析 cron 表达式和可选的 mode（inspect / work / loop / full）
2. 根据 mode 构建 prompt 内容：
- **full**: `"执行 harness full cycle。依次运行： 1. cd <项目路径> && bash <skill路径>/inspector.sh 2. bash <skill路径>/worker-reviewer.sh --loop 完成后汇报结果。"`
- **inspect**: `"执行 harness inspect。运行 cd <项目路径> && bash <skill路径>/inspector.sh。完成后汇报结果。"`
- **work**: `"执行 harness work。运行 cd <项目路径> && bash <skill路径>/worker-reviewer.sh。完成后汇报结果。"`
- **loop**: `"执行 harness loop。运行 cd <项目路径> && bash <skill路径>/worker-reviewer.sh --loop。完成后汇报结果。"`
3. 调用 **CronCreate**，参数：
- `cron`: 用户提供的 cron 表达式
- `prompt`: 上面构建的 prompt
- `recurring: true`
4. 向用户确认创建成功，返回 job_id
#### 5.2 查看定时任务: `/harness cron list`
1. 调用 **CronList** 获取当前 session 所有 cron job
2. 过滤出 prompt 中包含 "harness" 关键字的 job
3. 以表格形式展示：job_id | cron 表达式 | mode | 创建时间（如有）
4. 如果没有 harness cron，提示"当前 session 没有 harness 定时任务"
#### 5.3 删除定时任务: `/harness cron stop [job_id]`
- **有 job_id**: 调用 **CronDelete** 删除指定 job，确认删除成功
- **无 job_id**:
1. 调用 CronList，过滤 harness 相关 job
2. 向用户展示将要删除的所有 job
3. 用户确认后，逐个调用 **CronDelete** 删除
4. 汇报删除结果
## 子进程输入机制
每个子进程（Inspector / Worker / Reviewer）通过 `claude -p` 启动，输入由三部分组成：
1. **角色提示词** — `<skill目录>/prompts/inspector.md` 等
2. **项目文档** — 脚本自动拼接 CLAUDE.md、TODO.md 等文件内容
3. **用户额外上下文** — 从 `/tmp/harness-context.txt` 读取，注入到 prompt 末尾
三部分拼接后传给 `claude -p`，确保子进程既有项目全貌，又有用户本轮的具体意图。
+
+ 默认情况下，脚本会把**调用脚本时的当前工作目录**（`pwd -P`）视为项目目录；如果需要从别处调用，可通过 `HARNESS_PROJECT_DIR=/abs/path/to/project` 显式覆盖。skill 安装目录只用于定位脚本和 prompts，不会被当成项目目录。
## 文件清单
| 文件 | 职责 |
|------|------|
| `prompts/inspector.md` | Inspector 角色提示词 |
| `prompts/worker.md` | Worker 角色提示词 |
| `prompts/reviewer.md` | Reviewer 角色提示词 |
| `inspector.sh` | Inspector 执行脚本 |
| `worker-reviewer.sh` | Worker+Reviewer 执行脚本 |
| `TODO.md` | 共享任务看板（项目根目录） |