用Claude自动完成开发循环：Plan-Work-Review实战教程

痛点：你的时间都花在哪儿了？

先做个简单的计算。假设你一天写6小时代码，实际敲键盘的纯编码时间有多少？

我自己的历史数据（用RescueTime跟踪了3个月）显示：真正写功能代码只占35%，剩下65%花在——

  • 阅读旧代码理解上下文（20%）
  • 对照需求文档修修改改（15%）
  • 手动写单元测试、补注释（12%）
  • 来回切换分支、跑CI、审查同事的PR（18%）

更扎心的是：这些重复性工作并没有消失，只是从一个开发者转移到另一个开发者。比如你写了单元测试，但测试覆盖率的边际收益越来越低；你写了详细的注释，但下一个人接手时还是得通读一遍代码。

Claude Code Harness（以下简称CCH）试图解决的根本问题是：把开发流程中可标准化、可自动化的部分剥离出来，交给AI自动驾驶，人类只做决策和异常处理。 这不是一个新想法，GitHub Copilot、Cursor、Codeium都在做，但CCH的独特之处在于：它强制了一个 Plan→Work→Review 的闭环，而不是让AI随机生成代码片段。

核心设计：为什么“自主学习-执行-审查”能提升质量？

plan work review cycle programmer AI

先看看CCH的工作流（基于其README简化）：

  1. Plan：AI根据任务描述，生成一份详细的执行计划（含文件列表、修改点、预期影响）。
  2. Work：AI按照计划逐项执行，每完成一项自动提交一个commit。
  3. Review：AI执行完所有任务后，生成一份审查报告（diff统计、潜在风险、测试建议）。
  4. Human Approval：开发者审查计划+代码+报告，决定合并或回滚。

对比传统AI编程助手（如Copilot Chat）：

  • Copilot：开发者提问→AI回答→开发者手动应用。适合“写个函数”、“解释这段代码”的微观场景。
  • Cursor：在IDE内直接让AI编辑文件，但缺乏全局计划。适合“把这段代码的循环改成列表推导式”的中观修改。
  • CCH：先计划，再执行，最后审查。适合 “添加一个日志记录中间件”、“为所有API端点增加速率限制” 这类需要跨越多个文件、涉及多个步骤的宏观任务。

CCH的聪明之处在于：它不是用一次提示就生成最终代码，而是把问题分解成多个子任务，让AI在每个子任务上都“停下来想一想”。这类似人类的“小步快跑”模式——你写代码时也会先想好改哪些文件，再动手，改完看diff。

但这里有个关键问题：AI能做好计划吗？ 我测试了3个场景（详情见下文），结论是：计划的质量取决于任务描述的清晰度。如果你只说“优化性能”，AI会给出笼统的计划；如果你说“把用户列表页的数据库查询从N+1改成批量查询，并添加缓存”，AI计划的可执行性很高。

搭建你的Claude Code Harness：从零到跑通

前置准备

  • 一个Claude API Key（pro账号也行，但建议使用API，因为CCH需要多次调用）
  • 一个Git仓库（推荐新项目或功能分支，避免污染主分支）
  • Node.js 18+（CCH基于Node运行）

安装与配置

CCH本质是一个Shell脚本集合。从GitHub克隆（我当前使用的版本是v0.1.0）：

bash
1 2 3 
git clone https://github.com/Chachamaru127/claude-code-harness.git
cd claude-code-harness
cp .env.example .env

在 .env 中设置：

text
1 2 3 4 5 
ANTHROPIC_API_KEY=sk-ant-your-key
WORK_DIR=../test-project   # 目标项目路径
BRANCH_NAME=feat/auto-rate-limit  # AI工作的分支
MAX_RETRIES=3
REVIEW_MODE=strict           # 或 balanced

然后安装依赖：

bash
1 
npm install

第一个任务：为Express API添加速率限制

假设你的 test-project 是一个Node.js+Express项目。创建一个任务描述文件 tasks/rate-limit.json：

json
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 
{
  "version": "1.0",
  "description": "为所有API路由添加express-rate-limit中间件",
  "constraints": [
    "使用express-rate-limit包（版本^7.0）",
    "限制：每IP每分钟100次请求",
    "超出限制时返回429状态码和JSON消息",
    "仅在非开发环境启用（NODE_ENV !== 'development'）"
  ],
  "outputs": [
    "修改app.js/app.ts引入中间件",
    "创建config/rateLimit.js配置文件",
    "添加环境变量示例",
    "编写单元测试验证（可选）"
  ]
}

运行：

bash
1 
./run.sh tasks/rate-limit.json

脚本会依次执行：

  1. 读取任务 → 调用Claude生成计划
  2. 将计划保存到 .harness/plans/
  3. 逐步骤执行：对每个步骤调用Claude生成代码，并写入文件
  4. 每完成一个步骤自动 git commit -m "[CCH] <步骤描述>"
  5. 所有步骤完成后，生成审查报告（diff、风险项、测试建议）
  6. 输出最终报告，等待人工确认

实际效果数据

我在一个中型Express项目（23个路由文件，约8000行代码）上测试了这个任务。对比手动完成（由另一名同事执行）和CCH自动完成：

指标 手动 CCH 差异
总耗时 45分钟 3分12秒（AI计算时间） 节省93%
代码修改文件数 4个 4个（app.js, config/rateLimit.js, .env.example, test/rateLimit.js） 一致
代码错误 0（但有1处lint警告） 0（lint通过，但测试覆盖率未达100%） 接近
需人工修正数 0 1（配置文件路径与项目约定不符） 需复审

注意：这里“3分12秒”是纯AI执行时间，不包括生成计划和审查报告的时间（约30秒）。但对比手动45分钟，节省非常明显。

缺陷也很明显：AI生成的代码风格不完全符合项目现有约定。比如项目使用 module.exports = {}，AI生成的是 export default（因为我们未在约束中指定模块系统）。所以约束写详细一点很重要。

落地注意事项：别让自动驾驶变成无人驾驶

1. 任务粒度：微任务最好

CCH最适合的是一小时内能手动完成的任务。如果任务跨越多个领域（比如“同时重构数据库和前端”），AI计划会变得冗长，且容易出错。我建议把大任务拆分成多个小任务，每个任务只改一个关注点。

2. 约束条件越多，结果越可控

从上面的例子可见，任务描述里必须明确：

  • 代码风格（CommonJS vs ESM、缩进、命名规范）
  • 第三方库版本（不然AI可能选最新但未稳定版本）
  • 测试要求（是否必须覆盖边界情况）
  • 非功能需求（性能、安全、日志）

3. 成本与延迟

CCH每次调用Claude API，生成计划+执行每个步骤+审查，对于上述任务消耗了约 80K 输入Token + 20K 输出Token（按Claude 3.5 Sonnet计费约0.4美元）。不算贵，但如果你每天跑几十个任务，月费可能到几百美元。性价比取决于你团队人工时薪。

4. 安全：不要在生产分支直接跑

必须让CCH在独立功能分支工作，且默认禁止推送。我建议在 .env 中设置 DRY_RUN=true 先试跑一次，看计划是否符合预期。

git branch isolated feature harness

5. 审查报告不是免检金牌

CCH生成的审查报告会列出每个修改点的风险和测试建议，但它不会说“这里我写错了”。我看到一次审查报告说“数据库索引已添加”，但实际上AI没添加，只是添加了注释。永远要做人工diff检查。

改造思路：如何让Harness适配你的工作流

CCH原本是通用框架，但你完全可以定制它。这里分享两个我改造的地方：

改造1：添加多语言lint检查

原始脚本只检查diff，但我想在review阶段自动运行 npm run lint 和 npm test。修改 scripts/review.sh，在生成报告后加入：

bash
1 2 3 4 5 6 
# 在review脚本末尾
echo "Running lint..."
npm run lint -- --max-warnings=0 2>&1 | tee -a $REVIEW_FILE
if [ $? -ne 0 ]; then
    echo "Lint检查未通过，请在合并前修复" >> $REVIEW_FILE
fi

改造2：让计划包含影响分析

我把任务描述格式扩展为包含impactAnalysis字段，让AI在计划中预测对现有功能的影响。例如：

json
1 2 3 4 5 
"impactAnalysis": [
    "检查已有速率限制中间件是否冲突",
    "确认不会影响健康检查端点（/health）",
    "确认不会影响静态文件路由"
]

AI会在计划中逐条回应，这样你就不用猜。

我的判断：该不该用Claude Code Harness？

如果你满足这三个条件，值得一试：

  • 团队有代码审查文化（不信任AI完全自治）
  • 经常需要实现重复性的跨文件修改（添加鉴权中间件、切换日志库、统一错误处理）
  • 愿意花半天时间完善任务模板库

如果你们项目变化剧烈、代码规范极其混乱、或者API成本敏感，建议再等等。CCH当前还是早期项目（0.1.0），存在不少小bug（比如路径处理、大项目token超限），但方向是对的。

最后说一句：不要指望AI替你写整个feature，而是用它帮你处理那些“写起来很烦但必须做”的部分。 正是那些琐碎但重要的任务加在一起，消耗了团队40%以上的产出。把代码审查、测试生成、跨文件同步交给AI，人类专注架构和业务逻辑——这才是真正的提效。

（完）