Imported from lane2077/claude-code-harness-zh (
skills-v3/harness-work/SKILL.md). Install upstream withnpx skills add lane2077/claude-code-harness-zh --skill harness-work. Copyright stays with the author.
Harness Work (v3)
Harness v3 的统一执行技能。 整合了以下旧技能:
work— 实现 Plans.md 中的任务(自动判断范围)impl— 功能实现(按任务执行)breezing— 团队全自动执行parallel-workflows— 并行工作流优化ci— CI 失败后的恢复
Quick Reference
| 用户输入 | 模式 | 动作 |
|---|---|---|
harness-work |
auto | 按任务数量自动判定(见下文) |
harness-work all |
auto | 以自动模式执行所有未完成任务 |
harness-work 3 |
solo | 只立即执行任务 3 |
harness-work --parallel 5 |
parallel | 强制使用 5 个 worker 并行执行 |
harness-work --codex |
codex | 委托给 Codex CLI(仅在显式指定时) |
harness-work --breezing |
breezing | 强制使用团队执行 |
Execution Mode Auto Selection(无标志时自动判定)
如果没有显式模式标志(--parallel、--breezing、--codex),
会根据目标任务数量自动选择最合适的模式:
| 目标任务数 | 自动选择模式 | 原因 |
|---|---|---|
| 1 个 | Solo | 开销最小,直接实现最快 |
| 2 到 3 个 | Parallel(Task tool) | 到了 worker 拆分开始明显收益的阈值 |
| 4 个及以上 | Breezing | Lead 协调 + Worker 并行 + Reviewer 独立的三方分工更有效 |
规则
- 显式标志始终覆盖自动模式
--parallel N→ Parallel 模式(与任务数量无关)--breezing→ Breezing 模式(与任务数量无关)--codex→ Codex 模式(与任务数量无关)
--codex只在显式指定时启用- 因为有些环境没有安装 Codex CLI,所以不会自动选它
--codex可以与其他模式组合使用- 例如:
--codex --breezing→ Codex + Breezing
- 例如:
选项
| 选项 | 说明 | 默认值 |
|---|---|---|
all |
作用于所有未完成任务 | - |
N or N-M |
指定任务编号/范围 | - |
--parallel N |
并行 worker 数量 | auto |
--sequential |
强制串行执行 | - |
--codex |
委托 Codex CLI 实现(仅显式指定时,不自动选择) | false |
--no-commit |
禁止自动提交 | false |
--resume <id|latest> |
恢复上一次会话 | - |
--breezing |
以 Lead/Worker/Reviewer 团队模式执行 | false |
--no-tdd |
跳过 TDD 阶段 | false |
--no-simplify |
跳过 Auto-Refinement | false |
--auto-mode |
显式启用 Auto Mode rollout。仅在父会话 permission mode 兼容时考虑采用 | false |
Token Optimization (v2.1.69+):对于不涉及 git 操作的轻量任务, 可以在 plugin settings 中启用
includeGitInstructions: false, 以减少 prompt token 消耗。
范围对话框(无参数时)
harness-work
要执行到什么范围?
1) 下一个任务:执行 Plans.md 中下一个未完成任务 → Solo
2) 全部(推荐):完成剩余全部任务 → 按任务数量自动选模式
3) 指定编号:输入任务编号(如 3、5-7)→ 按数量自动选模式
带参数时立即执行(跳过对话):
harness-work all→ 全部任务,自动选模式harness-work 3-6→ 共 4 个任务,因此自动选择 Breezing
Effort 级别控制(v2.1.68+,v2.1.72 简化)
在 Claude Code v2.1.68 中,Opus 4.6 默认使用 medium effort (◐)。
到了 v2.1.72,max 级别被废止,简化为三档:low(○) / medium(◐) / high(●)。
可以通过 /effort auto 恢复默认值。
遇到复杂任务时,可使用 ultrathink 关键字启用 high effort (●)。
多因素评分
开始任务时会合并以下分数,当总分达到 3 及以上时自动注入 ultrathink:
| 因素 | 条件 | 分数 |
|---|---|---|
| 文件数 | 涉及 4 个及以上文件 | +1 |
| 目录 | 包含 core/、guardrails/、security/ |
+1 |
| 关键词 | 包含 architecture、security、design、migration |
+1 |
| 失败记录 | agent memory 中存在同任务失败记录 | +2 |
| 显式指定 | PM 模板中明确写了 ultrathink | +3(直接采用) |
注入方法
当分数 ≥ 3 时,会在 Worker spawn prompt 的开头加入 ultrathink。
在 breezing 模式中也适用同样逻辑,由 harness-work 统一管理。
执行模式详情
Solo 模式(1 个任务时自动选择)
- 读取 Plans.md,识别目标任务
- 若 Plans.md 不存在:自动调用
harness-plan create --ci→ 先生成 Plans.md 再继续 - 如果表头里缺少 DoD / Depends 列:提示
Plans.md 是旧格式,请用 harness-plan create 重新生成。→ 停止 - 如果会话中存在未记录任务:从最近对话上下文提取需求,并自动以
cc:TODO追加到 Plans.md- 提取逻辑:从用户发言中识别动作动词(如“新增”“修复”“实现”)
- 追加时遵循 v2 格式(Task / 内容 / DoD / Depends / Status)
- 追加后提示用户“已向 Plans.md 追加以下内容”(带 5 秒超时提示,默认继续) 1.5. 确认任务背景(30 秒):
- 从任务的“内容”和“DoD”中推断 目标(该任务要解决的问题),并用 1 行显示
- 通过
git grep/Glob推断 影响范围(会被修改的文件/模块) - 如果推断把握较高:直接进入实现(不拖慢流程)
- 如果推断把握不足:只向用户确认 1 个问题(“我的理解对吗?”)
- 若 Plans.md 不存在:自动调用
- 将任务更新为
cc:WIP - TDD 阶段(没有
[skip:tdd]且存在测试框架时): a. 先创建测试文件(Red) b. 确认测试失败 - 通过
scripts/generate-sprint-contract.sh <task-id>生成sprint-contract.json - 用
scripts/enrich-sprint-contract.sh补充 Reviewer 视角,并通过scripts/ensure-sprint-contract-ready.sh确认已 approved - 实现代码(Green)(Read/Write/Edit/Bash)
- 用
/simplify执行 Auto-Refinement(可通过--no-simplify跳过) - 自动评审阶段(见“评审循环”):
- 优先使用 Codex exec 执行评审,失败时回退到内部 Reviewer agent
- 若
sprint-contract.json中的reviewer_profile为runtime,则运行scripts/run-contract-review-checks.sh - 若 verdict 为
REQUEST_CHANGES:基于意见修复后重新评审(最多 3 次) - 若 verdict 为
APPROVE:进入下一步。仅靠 self-check 不算真正完成
- 用
scripts/write-review-result.sh规范化并保存 review artifact - 自动执行
git commit(可通过--no-commit跳过) - 将任务更新为
cc:完了(附 commit hash)
- 用
git log --oneline -1获取最近提交的短 hash(7 位) - 将 Plans.md 的 Status 更新为
cc:完了 [a1b2c3d] - 如果没有 commit(如使用了
--no-commit),则只写cc:完了
- 输出增强版完成汇报(见“完成汇报格式”)
- 失败时的自动重规划(仅限测试 / CI 失败):
- 检查测试执行结果
- 如果失败:把修复任务建议保存到 state,并通过批准命令追加到 Plans.md(见“失败任务自动补票”)
- 如果成功:继续处理下一个任务
Parallel 模式(2 到 3 个任务时自动选择 / 用 --parallel N 强制)
带 [P] 标记的任务会用 N 个 worker 并行执行。
如果显式指定 --parallel N,则无论任务数量多少都使用该模式。
若多个任务会竞争写入同一文件,则通过 git worktree 隔离。
Codex 模式(仅在显式指定 --codex 时)
通过官方插件 codex-plugin-cc 的 companion,把任务委托给 Codex CLI。
# 委托任务(允许写入)
bash scripts/codex-companion.sh task --write "任务内容"
# 通过 stdin(适合较大的 prompt)
CODEX_PROMPT=$(mktemp /tmp/codex-prompt-XXXXXX.md)
# 写入任务内容
cat "$CODEX_PROMPT" | bash scripts/codex-companion.sh task --write
rm -f "$CODEX_PROMPT"
# 继续上一个线程
bash scripts/codex-companion.sh task --resume-last --write "继续做"
companion 会通过 App Server Protocol 与 Codex 通信, 提供 Job 管理、thread resume 和结构化输出。 若结果未达到质量标准,需要自行修正。
Breezing 模式(4 个及以上任务时自动选择 / 用 --breezing 强制)
通过 Lead / Worker / Reviewer 的角色分离来团队执行。
在 Codex 中,默认采用基于 spawn_agent、wait、send_input、resume_agent、close_agent
的原生子 agent 协调方式,
不再采用旧的 TeamCreate / TaskCreate 风格说明。
权限策略:
- 当前已发布默认值是
bypassPermissions --auto-mode只作为面向兼容父会话的 opt-in rollout 标志- 不要在
permissions.defaultMode或 agent frontmatter 的permissionMode中写入未文档化的autoMode值
CC v2.1.69+:平台层面已经禁止 nested teammates, 所以不要在 Worker / Reviewer prompt 中再追加冗长的“禁止嵌套”说明。
Lead (this agent)
├── Worker (task-worker agent) — 负责实现
└── Reviewer (code-reviewer agent) — 负责评审
Phase A: Pre-delegate(准备):
- 读取 Plans.md,识别目标任务
- 解析依赖图,决定执行顺序(Depends 列)
- 为每个任务计算 effort 分数(判断是否注入 ultrathink)
- 用
scripts/generate-sprint-contract.sh生成sprint-contract.json - 用
scripts/enrich-sprint-contract.sh注入 Reviewer 视角,若scripts/ensure-sprint-contract-ready.sh判定未批准则停止
Phase B: Delegate(Worker spawn → 评审 → cherry-pick):
对每个任务按顺序执行以下步骤(遵循依赖顺序):
API 注记:以下示例使用 Claude Code 的 API 语法。 在 Codex 环境中,请将
Agent(...)理解为spawn_agent(...),将SendMessage(...)理解为send_input(...)。 详情见team-composition.md中的 API 映射表。
for task in execution_order:
# B-1. 生成 sprint-contract
contract_path = bash("scripts/generate-sprint-contract.sh {task.number}")
contract_path = bash("scripts/enrich-sprint-contract.sh {contract_path} --check \"从 reviewer 视角确认 DoD\" --approve")
bash("scripts/ensure-sprint-contract-ready.sh {contract_path}")
# B-2. Worker spawn(前台执行,worktree 隔离)
# Agent tool 的返回值里包含 agentId,后续修复循环要用 SendMessage
Plans.md: task.status = "cc:WIP" # 开始时更新(未开始任务仍保持 cc:TODO)
worker_result = Agent(
subagent_type="claude-code-harness:worker",
prompt="任务: {task.内容}\nDoD: {task.DoD}\ncontract_path: {contract_path}\nmode: breezing",
isolation="worktree",
run_in_background=false # 前台执行 → 等待 Worker 完成
)
worker_id = worker_result.agentId # 保存起来供 SendMessage 使用
# worker_result 包含 {commit, worktreePath, files_changed, summary}
# B-3. Lead 执行评审(优先使用 Codex exec)
diff_text = git("-C", worker_result.worktreePath, "show", worker_result.commit)
verdict = codex_exec_review(diff_text) or reviewer_agent_review(diff_text)
profile = jq(contract_path, ".review.reviewer_profile")
review_input = "review-output.json"
if profile == "runtime":
review_input = bash("cd {worker_result.worktreePath} && scripts/run-contract-review-checks.sh {contract_path}")
runtime_verdict = jq(review_input, ".verdict")
if runtime_verdict == "REQUEST_CHANGES":
verdict = "REQUEST_CHANGES"
elif runtime_verdict == "DOWNGRADE_TO_STATIC":
pass # 没有 runtime 校验命令 → 直接沿用 static verdict
if profile == "browser":
# browser artifact 会生成 PENDING_BROWSER scaffold。
# 实际的 browser 执行由后续 reviewer agent 负责。
# review-result 里写入的仍是 static review 的 verdict,而不是 PENDING_BROWSER。
browser_artifact = bash("scripts/generate-browser-review-artifact.sh {contract_path}")
# browser artifact 仅保存为参考资料,review-result 的 verdict 保持 static
# 如果 review_input 是 DOWNGRADE_TO_STATIC,则回退使用 static review 结果
if review_input != "review-output.json" and jq(review_input, ".verdict") == "DOWNGRADE_TO_STATIC":
review_input = "review-output.json" # 回退到 static review 结果
bash("scripts/write-review-result.sh {review_input} {latest_commit}")
# B-4. 修复循环(REQUEST_CHANGES 时,最多 3 次)
# Worker 虽然已在前台执行完毕,但仍可通过 SendMessage 重新唤起
# (CC: SendMessage(to: agentId) / Codex: resume_agent(agent_id) + send_input)
review_count = 0
latest_commit = worker_result.commit
while verdict == "REQUEST_CHANGES" and review_count < 3:
SendMessage(to=worker_id, message="问题如下: {issues}\n请修复并 amend")
# Worker 修复 → amend → 返回新的 commit hash
updated_result = wait_for_response(worker_id)
latest_commit = updated_result.commit
diff_text = git("-C", worker_result.worktreePath, "show", latest_commit)
verdict = codex_exec_review(diff_text) or reviewer_agent_review(diff_text)
review_count++
# B-5. APPROVE → cherry-pick 到 main
if verdict == "APPROVE":
git cherry-pick --no-commit {latest_commit} # worktree → main
git commit -m "{task.内容}"
Plans.md: task.status = "cc:完了 [{hash}]"
else:
→ 升级给用户处理
# B-6. 进度播报
print("📊 Progress: 已完成任务 {completed}/{total} — {task.内容}")
Sprint Contract
sprint-contract 是一个小型契约文件,用来把“这项任务怎样才算通过”描述成机器和人都能一致理解的形式。
默认保存位置是 .claude/state/contracts/<task-id>.sprint-contract.json。
scripts/generate-sprint-contract.sh 32.1.1
生成结果包含以下内容:
checks: 对 DoD 拆解后的确认项non_goals: 本次明确不做的内容runtime_validation: 如 test、lint、typecheck 等校验命令browser_validation: browser reviewer 需要保留的 UI 流程验证项browser_mode:scripted或exploratoryroute: browser reviewer 采用playwright/agent-browser/chrome-devtools中的哪一种risk_flags: 如needs-spike、security-sensitive、ux-regressionreviewer_profile:static,runtime,browser
Phase C: Post-delegate(整合与汇报):
- 汇总所有任务的 commit log
- 输出增强版完成汇报(使用“完成汇报格式”中的 Breezing 模板)
- 最终检查 Plans.md(确认所有任务都已变为
cc:完了)
CI 失败时的处理
当 CI 失败时:
- 查看日志并定位错误
- 执行修复
- 如果因同一原因连续失败 3 次,则停止自动修复循环
- 整理失败日志、已尝试的修复、以及仍然未解决的问题后升级处理
失败任务自动补票
当任务完成后测试 / CI 失败时,会自动生成修复任务建议,并在获得批准后写回 Plans.md:
触发条件
| 条件 | 动作 |
|---|---|
cc:完了 后测试失败 |
将修复任务建议保存到 state,并等待批准 |
| CI 失败(少于 3 次) | 直接尝试修复,并增加失败计数 |
| CI 第 3 次失败 | 提示修复任务建议并升级处理 |
自动生成修复任务
- 对失败原因进行分类(syntax_error / import_error / type_error / assertion_error / timeout / runtime_error)
- 将修复任务建议写入
.claude/state/pending-fix-proposals.jsonl:- 编号:原任务编号 +
.fix后缀(例如26.1.fix) - 内容:
fix: [原任务名] - [失败原因分类] - DoD:测试 / CI 通过
- Depends:原任务编号
- 编号:原任务编号 +
- 当用户发送
approve fix <task_id>时,就以cc:TODO追加到 Plans.md - 发送
reject fix <task_id>可丢弃建议。若当前只有 1 条 pending,也可直接用yes/no回应
评审循环
这是在实现完成后(Step 5 之后)自动执行的质量验证阶段。 它会统一应用在所有模式(Solo / Parallel / Breezing)中。 在 Parallel 模式下,每个 Worker 都会把这一循环作为 step 10(接受外部评审)来执行。
评审执行优先级
1. Codex exec(优先)
↓ 若不存在 codex 命令或超时(120s)
2. 内部 Reviewer agent(回退)
APPROVE / REQUEST_CHANGES 判定标准
会把以下阈值标准传给 reviewer,并要求只能依据这些标准来判定 verdict。
不属于这些阈值范围的改进建议,应作为 recommendations 返回,不影响 verdict。
| 重要度 | 定义 | 对 verdict 的影响 |
|---|---|---|
| critical | 安全漏洞、数据丢失风险、可能引发生产故障 | 只要 1 条 → REQUEST_CHANGES |
| major | 破坏现有功能、与规格明显矛盾、测试不通过 | 只要 1 条 → REQUEST_CHANGES |
| minor | 命名改进、注释不足、风格不统一 | 不影响 verdict |
| recommendation | 最佳实践建议、未来改进方向 | 不影响 verdict |
重要:如果只有 minor / recommendation,必须返回 APPROVE。 “有会更好”的改进点,不能成为
REQUEST_CHANGES的理由。
Codex exec 评审(通过官方插件)
会在任务开始时把当前 HEAD 保存为 BASE_REF,并以它与当前状态的 diff 作为评审对象。
这里使用官方插件 codex-plugin-cc 的 companion review。
# 在任务开始时记录 base ref(在 Step 2 更新 cc:WIP 之前执行)
BASE_REF=$(git rev-parse HEAD)
# ... 实现完成后 ...
# 执行官方插件的结构化评审
bash scripts/codex-companion.sh review --base "${BASE_REF}"
REVIEW_EXIT=$?
verdict 映射(官方插件 → Harness 形式):
官方插件会返回符合 review-output.schema.json 的结构化输出。
转换为 Harness verdict 的规则如下:
| 公式 plugin | Harness | verdict 影響 |
|---|---|---|
approve |
APPROVE |
- |
needs-attention |
REQUEST_CHANGES |
- |
findings[].severity: critical |
critical_issues[] |
只要 1 条 → REQUEST_CHANGES |
findings[].severity: high |
major_issues[] |
只要 1 条 → REQUEST_CHANGES |
findings[].severity: medium/low |
recommendations[] |
不影响 verdict |
AI Residuals 扫描仍由 scripts/review-ai-residuals.sh 执行,
并与 companion review 的结果一起决定最终 verdict。
# AI Residuals 扫描(可与 companion review 并行执行)
AI_RESIDUALS_JSON="$(bash scripts/review-ai-residuals.sh --base-ref "${BASE_REF}" 2>/dev/null || echo '{"tool":"review-ai-residuals","scan_mode":"diff","base_ref":null,"files_scanned":[],"summary":{"verdict":"APPROVE","major":0,"minor":0,"recommendation":0,"total":0},"observations":[]}')"
回退到内部 Reviewer agent
当 Codex exec 不可用时(command -v codex 失败,或 exit code ≠ 0):
Agent tool: subagent_type="reviewer"
prompt: "请评审以下变更。判定标准:critical/major → REQUEST_CHANGES,只有 minor/recommendation → APPROVE。diff: {git diff ${BASE_REF}}"
Reviewer agent 会在只读模式下执行评审(禁用 Write / Edit / Bash),以保证安全。
修复循环(REQUEST_CHANGES 时)
review_count = 0
MAX_REVIEWS = 3
while verdict == "REQUEST_CHANGES" and review_count < MAX_REVIEWS:
1. 解析评审意见(只处理 critical / major)
2. 针对每条意见执行修复
3. 再次执行评审(沿用相同判定标准和优先级)
review_count++
if review_count >= MAX_REVIEWS and verdict != "APPROVE":
→ 升级给用户处理
→ 显示“已经修复了 3 次,但以下 critical/major 问题仍然存在”以及问题列表
→ 等待用户决定(继续 / 中断)
在 Breezing 模式中的应用
在 Breezing 模式下,由 Lead 负责执行评审循环(见上文 Phase B):
- Worker 在 worktree 中实现并提交 → 把结果返回给 Lead
- Lead 用 Codex exec 评审(优先)或 Reviewer agent(回退)
- 若为
REQUEST_CHANGES→ Lead 通过 SendMessage 指示 Worker 修复 → Worker 执行 amend - 修复后再次评审(最多 3 次)
- 若为
APPROVE→ Lead cherry-pick 到 main → 将 Plans.md 更新为cc:完了 [{hash}]
完成汇报格式
当任务完成时(cc:完了 + commit 之后),会自动输出一份视觉化摘要。
目标是让非技术人员也能理解这次改了什么、影响是什么。
模板
┌─────────────────────────────────────────────┐
│ ✓ Task {N} 完成: {任务名} │
├─────────────────────────────────────────────┤
│ │
│ ■ 做了什么 │
│ • {变更内容 1} │
│ • {变更内容 2} │
│ │
│ ■ 发生了什么变化 │
│ Before: {旧行为} │
│ After: {新行为} │
│ │
│ ■ 变更文件 ({N} files) │
│ {文件路径 1} │
│ {文件路径 2} │
│ │
│ ■ 剩余任务 │
│ • Task {X} ({status}): {内容} ← Plans.md │
│ • Task {Y} ({status}): {内容} ← Plans.md │
│ (Plans.md 中还有 {M} 个未完成任务) │
│ │
│ commit: {hash} | review: {APPROVE} │
└─────────────────────────────────────────────┘
生成规则
- 做了什么:从
git diff --stat HEAD~1和 commit message 中自动提取,尽量少用技术术语,并以动词开头 - 发生了什么变化:从任务“内容”和“DoD”推断 Before / After,优先体现用户体验变化
- 变更文件:从
git diff --name-only HEAD~1获取。若超过 5 个文件,则省略明细只显示数量 - 剩余任务:列出 Plans.md 中的
cc:TODO/cc:WIP任务,并明确说明是否已记入 Plans.md - review:显示评审结果(APPROVE / REQUEST_CHANGES → APPROVE)
Parallel 模式下的汇报
- 1 个任务(强制
--parallel时):使用 Solo 模板 - 多个任务:使用 Breezing 汇总模板(见下文)
Breezing 模式下的汇报
所有任务完成后统一输出。每个任务只展示简版信息(做了什么 + commit hash), 最后再输出总体摘要(总变更文件数 + 剩余任务):
┌─────────────────────────────────────────────┐
│ ✓ Breezing 完成: {N}/{M} 个任务 │
├─────────────────────────────────────────────┤
│ │
│ 1. ✓ {任务名 1} [{hash1}] │
│ 2. ✓ {任务名 2} [{hash2}] │
│ 3. ✓ {任务名 3} [{hash3}] │
│ │
│ ■ 整体变更 │
│ {N} files changed, {A} insertions(+), │
│ {D} deletions(-) │
│ │
│ ■ 剩余任务 │
│ Plans.md 中还有 {K} 个未完成任务 │
│ • Task {X}: {内容} │
│ │
└─────────────────────────────────────────────┘
相关技能
harness-plan— 规划要执行的任务harness-sync— 同步实现结果与 Plans.mdharness-review— 评审实现结果harness-release— 做版本提升与发布