用 Claude Code Harness 驱动多智能体自动协同编程：工作时间5小时，全程不要人参与，一直干到任务结束！！！

大家好，我是讯享网，很高兴认识大家。这里提供最前沿的Ai技术和互联网信息。

 本文分享一套基于 Claude Code CLI 的多智能体自动协同编程脚手架，通过 Harness 调度 4 个 Claude 实例（Designer → Reviewer → Coder → Validator），以文件为唯一状态载体，完成从 PRD 到可运行代码的完整交付。文末附带真实案例：AI 狼人杀项目（9 个 Story、4 个 Agent、零人工干预完成核心开发）。

用过 Claude Code 的同学都知道，单会话的上下文是有限的。当你想做一个完整项目时，往往面临几个问题：

上下文爆炸：一个复杂项目的需求、设计、代码、测试全部塞在一个会话里，很快就触顶了。
角色混杂：你一会儿让 Claude 做架构设计，一会儿写代码，一会儿又跑测试，它容易"精神分裂"。
无法并行：一个会话只能串行处理，没法让多个 Claude 实例同时工作。
状态易失：会话一断，之前的推理过程、设计决策就丢了，恢复成本很高。

解决思路：把"一个超级 Agent"拆成"多个专业 Agent"，通过文件和状态机协同。

这和人类团队的分工是一样的：

Designer：做技术方案设计
Reviewer：审核设计，查漏补缺
Coder：写代码、跑测试、提交
Validator：验收、跑回归、出测试报告

整个系统最关键的设计是：Agent 之间不直接通信，只通过读写文件来传递信息。

这意味着：

每个 Agent 启动时，先读 worker_state.json 知道自己该干嘛；
然后读上一个 Agent 留下的输出文件（如 design-v1.md、design-v2.md）；
完成工作后，写入自己的输出文件，并更新 status.json；
主控程序 worker.py 轮询 status.json，决定启动下一个 Agent。

2.1 文件结构

 worker/ ├── stories/ # Story 文件夹 │ └── {story-id}/ │ ├── story.md # 需求描述（由 story-splitter 从 PRD 拆分） │ ├── design-v1.md # Designer 输出 │ ├── design-v2.md # Reviewer 修改后的设计 │ ├── implementation.md # Coder 输出（实现报告） │ ├── test-report.md # Validator 输出（测试报告） │ └── status.json # 状态管理（核心） ├── agents/ │ ├── designer.md # Designer Agent 系统提示词 │ ├── reviewer.md # Reviewer Agent 系统提示词 │ ├── coder.md # Coder Agent 系统提示词 │ └── validator.md # Validator Agent 系统提示词 ├── shared/ │ ├── PRD.md # 产品需求文档 │ ├── AGENTS.md # 项目架构规范 │ └── mvp/ # MVP 参考实现 ├── logs/ # 日志目录 ├── ui/ # Web UI 监控面板 ├── worker.py # 主控循环脚本 └── config.json # 配置文件

2.2 状态文件：status.json

每个 Story 都有一个 status.json，它是整个工作流的"红绿灯"：

 { "storyId": "US-001-websocket-server", "phase": "coding_complete", "phases": { "design": {"status": "completed", "version": 1}, "design_review": {"status": "completed", "version": 2}, "coding": {"status": "completed", "iteration": 1}, "validation": {"status": "pending", "iteration": 0} }, "retryCount": 0, "maxRetries": 20 }

phase 字段决定了当前 Story 处于哪个阶段，worker.py 根据它调度对应的 Agent。

2.3 全局状态：worker_state.json

 { "currentStoryId": "US-001-websocket-server", "currentPhase": "design", "currentAgent": "designer", "startedAt": "2024-01-15T10:00:00Z", "iteration": 5 }

每个 Agent 启动后的第一件事就是读这个文件，确认 currentAgent 是不是自己。如果不是，立即停止。这个机制防止了 Agent "越权"操作。

worker.py 是整个系统的"导演"，它不负责具体业务，只负责：

轮询所有 Story，找到下一个待处理的；
更新 worker_state.json；
调用 claude --print --dangerously-skip-permissions 启动对应 Agent；
捕获 Agent 的输出日志；
检查返回码，决定是继续下一个还是重试。

3.1 核心调度逻辑

 def process_story(story_dir: Path) -> bool: status = read_status(story_dir) phase = get_current_phase(status) if phase == "pending": return run_designer(story_dir) elif phase == "designed": return run_reviewer(story_dir) elif phase in ["design_reviewed", "coding"]: return run_coder(story_dir) elif phase == "coding_complete": return run_validator(story_dir) elif phase == "done": return True

3.2 Agent 启动方式

 def build_agent_command(agent_type: str, story_dir: Path) -> List[str]: agent_file = AGENTS_DIR / f"{agent_type}.md" prompt = agent_file.read_text(encoding="utf-8") prompt = prompt.replace("{story-id}", story_dir.name) return [ "claude", "--print", "--dangerously-skip-permissions", prompt, ]

这里的关键是 claude --print：它会让 Claude Code CLI 以非交互方式执行一段 prompt，执行完自动退出。这样 worker.py 就可以像调用子进程一样调用 Claude。

Agent 的"智商"很大程度上取决于提示词。我们的设计原则是：给每个 Agent 明确的身份、严格的输入输出规范、强制的前置检查。

4.1 Designer Agent

核心职责：读 story.md + PRD + MVP + AGENTS.md，输出 design-v1.md。其中PRD跟MVP文档，都是在项目开始前已经准备好的，使用

强制前置检查：

读 worker_state.json，确认 currentAgent == "designer"；
读 status.json，确认 phase == "pending"；
读 story.md、prd.md、mvp/、AGENTS.md，缺任何一个都停止工作。

输出规范：design-v1.md 必须包含 8 个章节：需求理解、技术方案、文件结构、接口定义、依赖分析、实现步骤、风险点、测试策略。

4.2 Reviewer Agent

核心职责：读 design-v1.md，审核并直接修改，输出 design-v2.md + design-review-report.md。

关键设计：Reviewer 不是只提意见，而是要直接修改设计文档。这避免了"意见很多但没人改"的情况。修改后通过 mv design-v1.md design-v2.md 完成版本升级。

4.3 Coder Agent

核心职责：读 design-v2.md，实现代码，跑本地测试，提交代码，输出 implementation.md。

强制要求：

必须运行真实的本地测试（typecheck / lint / test / build）；
不允许使用 mock 数据；
必须 git commit；
如果是修复迭代（phase == "coding"），必须读 test-report.md 针对性修复。

4.4 Validator Agent

核心职责：读 implementation.md + design-v2.md，做代码审查、运行测试、浏览器测试（如有 UI），输出 test-report.md。

关键设计：Validator 是"守门员"。

通过 → phase 设为 done；
失败 → phase 回退到 coding，retryCount + 1，Coder 重新修复。

严格规则：发现任何跟当前 Story 相关的错误，都必须打回，不允许跳过。

除了后台自动跑，我们还提供了一个简单的 Web 监控面板，方便观察进度：

 http://localhost:7332

面板功能：

总进度圆环：显示完成百分比
Story 列表：每个 Story 的当前阶段、文件产出情况
工作日志：实时滚动显示 worker 和 agent 的日志
详情弹窗：点击 Story 可查看 design-v1/v2、implementation、test-report 的完整内容

UI 由 ui/server.py（一个轻量 HTTP 服务器）提供 API，ui/app.js 每 5 秒轮询刷新。

下面是我们用这套系统真实跑出来的项目案例。

6.1 项目背景

做一个 AI 驱动的狼人杀游戏：

9 个 AI 玩家（3 狼人、1 预言家、1 女巫、1 猎人、3 平民）
使用 PI-Agent 框架 + DeepSeek API 驱动 AI 决策
WebSocket 实时推送游戏状态
Web 前端可视化展示游戏进程和 AI 思考过程

6.2 从 PRD 到 Stories

PRD 写好后，用 story-splitter 技能自动拆分为 9 个独立 Story：

Story ID 标题优先级依赖 US-001 WebSocket Server 实现 P0 无 US-002 游戏引擎核心 P0 US-001 US-003 夜晚阶段逻辑 P0 US-002 US-004 白天阶段逻辑 P0 US-002 US-005 AI 玩家集成 P1 US-003, US-004 US-006 前端基础界面 P1 US-001 US-007 游戏视图界面 P1 US-002, US-006 US-008 角色详情面板 P2 US-005, US-007 US-009 整体功能回归测试 P2 全部

6.3 自动化执行结果

启动 python3 worker.py 后，系统开始自动按顺序处理每个 Story。以下是部分真实运行记录：

US-001：WebSocket 服务器（一次通过）

Designer 输出 design-v1.md：设计了 ConnectionManager、RoomManager、MessageHandler 三层架构。
Reviewer 审核后输出 design-v2.md：补充了非法消息防护、心跳超时清理、移除 uuid 依赖改用原生 crypto.randomUUID()。
Coder 实现并提交：创建了 9 个文件，包含 6 个集成测试，全部通过。
Validator 验证通过：测试覆盖连接、创建房间、加入房间、广播、心跳、异常消息等场景。

US-008：角色详情面板（迭代 2 次通过）

第 1 轮：Coder 实现了角色详情面板，但 Validator 在浏览器测试中发现：前端日志区的 vote_result 消息显示成了 [object Object]。
状态回退：Validator 将 status.json 的 phase 从 coding_complete 改回 coding，retryCount 设为 1。
第 2 轮：Coder 读取 test-report.md，定位到 app.js 中 vote_result 处理逻辑，用 JSON.stringify 修复对象显示问题，重新提交。
Validator 再次验证：通过，截图留存 8 张，包含预言家面板、狼人面板、遗言样式、狼人频道标记等。

这是整个系统最有价值的地方：错误可以被自动发现、自动记录、自动修复，不需要人盯着。

US-009：整体回归测试

Designer 设计了三层测试架构：服务端日志监控 + WebSocket E2E + Puppeteer 前端 E2E。
Reviewer 补充了 [object Object] 的 DOM 层扫描、内存监控方案、端口冲突预防措施。
Coder 编写了完整的端到端测试套件。
Validator 运行完整一局游戏（约 14 秒），验证 9 个角色功能、WebSocket 通信、前端 UI、PRD 符合性，最终结论：通过，系统功能完整，可以发布。

6.4 真实状态文件示例

US-008 的 status.json：

 { "storyId": "US-008", "phase": "done", "phases": { "design": {"status": "completed", "version": 1}, "design_review": {"status": "completed", "version": 2}, "coding": {"status": "completed", "iteration": 2}, "validation": {"status": "completed", "iteration": 2} }, "retryCount": 1, "history": [ {"action": "design_completed", "version": 1}, {"action": "design_review_completed", "version": 2}, {"action": "coding_completed", "iteration": 1}, {"action": "validation_failed", "retryCount": 1, "reason": "vote_result 显示 [object Object]"}, {"action": "coding_completed", "iteration": 2}, {"action": "validation_passed", "iteration": 2} ] }

7.1 文件状态机是核心

不要试图让 Agent 之间直接对话或共享内存。文件是最稳定、最可追溯、最容错的通信方式。 即使某个 Agent 崩溃了，你也能从文件中恢复上下文。

7.2 前置检查必须严格

每个 Agent 的提示词里都要写死：

先读 worker_state.json 确认身份；
再读 status.json 确认阶段；
最后读必要的输入文件，缺一个就停止。

这能有效防止 Agent "幻觉"或越权操作。

7.3 Reviewer 必须直接修改，不能只评论

如果 Reviewer 只输出评论，Coder 很可能不看或者理解偏差。让 Reviewer 直接产出 design-v2.md，把设计缺陷在编码前就消灭掉。

7.4 Validator 是质量守门员，必须能打回

Validator 不能只做"老好人"。它的核心职责就是发现问题、详细记录、把状态打回给 Coder。只有严格的 Validator，才能让整个系统自动收敛到正确结果。

7.5 日志和截图是调试利器

每个 Agent 的运行日志都保存到 logs/YYYYMMDD-HHMMSS-{agent}-{story-id}.log。对于前端 Story，Validator 还会截图到 screenshots/。这些产物对于定位问题非常关键。

8.1 快速开始

 # 1. 拆分 PRD 为 Stories claude skill:story-splitter # 输入 PRD 文件路径，如 worker/shared/PRD.md # 2. 启动 Worker cd worker python3 worker.py # 3. 打开监控面板 open http://localhost:7332

8.2 worker.py 核心代码

 #!/usr/bin/env python3 """ Worker - 自主 AI Agent 循环执行器 严格顺序：Designer → Reviewer → Coder → Validator """ import json, sys, subprocess, time, os, signal from pathlib import Path from datetime import datetime MAX_ITERATIONS = 100 AGENT_TIMEOUT = 30 * 60 POLL_INTERVAL = 5 WORKER_DIR = Path(__file__).parent.resolve() STORIES_DIR = WORKER_DIR / "stories" AGENTS_DIR = WORKER_DIR / "agents" LOGS_DIR = WORKER_DIR / "logs" WORKER_STATE_FILE = WORKER_DIR / "worker_state.json" def read_worker_state(): if not WORKER_STATE_FILE.exists(): return {"currentStoryId": None, "currentPhase": None, "currentAgent": None} return json.loads(WORKER_STATE_FILE.read_text(encoding="utf-8")) def write_worker_state(state): state["lastUpdate"] = datetime.now().isoformat() WORKER_STATE_FILE.write_text(json.dumps(state, indent=2, ensure_ascii=False), encoding="utf-8") def read_status(story_dir: Path): status_file = story_dir / "status.json" if not status_file.exists(): return None return json.loads(status_file.read_text(encoding="utf-8")) def find_next_story(): for story_dir in sorted(STORIES_DIR.iterdir()): if not story_dir.is_dir(): continue status = read_status(story_dir) if not status: continue phase = status.get("phase", "pending") retry_count = status.get("retryCount", 0) max_retries = status.get("maxRetries", 20) if phase == "done" or retry_count >= max_retries: continue # 检查依赖是否满足 deps_satisfied = True for dep_id in status.get("dependencies", []): dep_status = read_status(STORIES_DIR / dep_id) if not dep_status or dep_status.get("phase") != "done": deps_satisfied = False break if deps_satisfied: return story_dir return None def run_agent(agent_type: str, story_dir: Path) -> bool: story_id = story_dir.name agent_file = AGENTS_DIR / f"{agent_type}.md" prompt = agent_file.read_text(encoding="utf-8").replace("{story-id}", story_id) # 更新全局状态 status = read_status(story_dir) phase = status.get("phase", "unknown") if status else "unknown" write_worker_state({ "currentStoryId": story_id, "currentPhase": phase, "currentAgent": agent_type, }) cmd = ["claude", "--print", "--dangerously-skip-permissions", prompt] log_file = LOGS_DIR / f"{datetime.now().strftime('%Y%m%d-%H%M%S')}-{agent_type}-{story_id}.log" with open(log_file, "w", encoding="utf-8") as f: f.write(f"=== {agent_type.upper()} Agent - {story_id} === ") process = subprocess.Popen( ["script", "-q", "/dev/null"] + cmd, cwd=str(WORKER_DIR.parent), stdout=subprocess.PIPE, stderr=subprocess.STDOUT, text=True, encoding="utf-8", ) start_time = time.time() with open(log_file, "a", encoding="utf-8") as f: while True: if time.time() - start_time > AGENT_TIMEOUT: process.terminate() return False ret_code = process.poll() if ret_code is not None: remaining = process.stdout.read() if remaining: f.write(remaining) return ret_code == 0 import select ready, _, _ = select.select([process.stdout], [], [], 1.0) if ready: line = process.stdout.readline() if line: f.write(line) f.flush() def process_story(story_dir: Path) -> bool: status = read_status(story_dir) phase = status.get("phase", "pending") if status else "pending" if phase == "pending": return run_agent("designer", story_dir) elif phase == "designed": return run_agent("reviewer", story_dir) elif phase in ["design_reviewed", "coding"]: return run_agent("coder", story_dir) elif phase == "coding_complete": return run_agent("validator", story_dir) return True def main(): # 启动 UI 服务器 try: from ui import server as ui_server ui_server.start(port=7332, open_browser=True) except Exception as e: print(f"UI 启动失败: {e}") for iteration in range(1, MAX_ITERATIONS + 1): story_dir = find_next_story() if not story_dir: print("所有 Story 已完成！") break process_story(story_dir) time.sleep(2) if __name__ == "__main__": main()

8.3 四个 Agent 提示词节选

Designer Agent

 # Designer Agent 指令 你是 Story 设计 Agent，负责为每个 Story 创建详细的技术设计方案。 强制前置检查 执行任何工作前，必须按顺序完成以下检查： 1. 获取当前任务 首先读取 `worker/worker_state.json` 获取当前任务： - 如果 `currentAgent` 不是 `"designer"`，立即停止并报告错误 - 如果 `currentStoryId` 为空，立即停止并报告错误 2. 验证 Story 状态 读取 `worker/stories/{currentStoryId}/status.json`，确认： - `phase` 为 `"pending"` - 如果 phase 不是 "pending"，立即停止并报告错误 3. 必须读取以下文件（缺少任何一个都停止工作）： - `worker/stories/{currentStoryId}/story.md` - Story 需求 - `worker/shared/prd.md` - 产品需求文档 - `worker/shared/mvp/` - MVP 实现参考 - `worker/shared/AGENTS.md` - 项目架构规范 输出要求 必须输出文件 `worker/stories/{currentStoryId}/design-v1.md` design-v1.md 必须包含以下章节 1. 需求理解 2. 技术方案 3. 文件结构 4. 接口定义 5. 依赖分析 6. 实现步骤 7. 风险点 8. 测试策略 状态更新 完成设计后，必须更新 `worker/stories/{currentStoryId}/status.json`： 将 `phase` 设置为 `"designed"`，并记录 `design.completed` 状态。

Reviewer Agent

 # Reviewer Agent 指令 你是设计审核 Agent，负责审核 Designer 的设计方案，并直接修改完善。 核心职责 - 读取当前任务和设计文档 - 检查设计是否符合架构和需求 - 直接修改 design.md，输出 design-v2.md - 生成审核报告 强制前置检查 1. 获取当前任务 首先读取 `worker/worker_state.json`： - 如果 `currentAgent` 不是 `"reviewer"`，立即停止并报告错误 - 记录 `currentStoryId` 2. 验证 Story 状态 读取 `worker/stories/{currentStoryId}/status.json`，确认： - `phase` 为 `"designed"` 3. 必须读取以下文件： - `worker/stories/{currentStoryId}/design-v1.md` - `worker/stories/{currentStoryId}/story.md` - `worker/shared/prd.md` - `worker/shared/mvp/` - `worker/shared/AGENTS.md` 输出要求 1. 修改后的设计文档 必须直接修改 `worker/stories/{currentStoryId}/design-v1.md` 修改后重命名为 `design-v2.md`： bash mv worker/stories/{story-id}/design-v1.md worker/stories/{story-id}/design-v2.md

2. 审核报告

创建 worker/stories/{currentStoryId}/design-review-report.md

完成审核后，必须更新 status.json：将 phase 设置为 "design_reviewed"。

  # Coder Agent markdown # Coder Agent 指令 你是开发 Agent，负责根据设计文档实现代码，并进行本地测试。 核心职责 - 读取当前任务和设计文档 - 实现代码功能 - 运行本地测试（typecheck, lint, test） - 提交代码并生成实现报告 强制前置检查 1. 获取当前任务 首先读取 `worker/worker_state.json`： - 如果 `currentAgent` 不是 `"coder"`，立即停止并报告错误 2. 验证 Story 状态 读取 `status.json`，确认 `phase` 为以下之一： - `"design_reviewed"` - 首次开发 - `"coding"` - 修复迭代（Validator 发现问题后） 3. 必须读取以下文件： - `worker/stories/{currentStoryId}/design-v2.md` - `worker/stories/{currentStoryId}/story.md` - `worker/stories/{currentStoryId}/design-review-report.md` - `worker/stories/{currentStoryId}/test-report.md`（如果有，说明是修复迭代） - `worker/shared/prd.md` - `worker/shared/mvp/` - `worker/shared/AGENTS.md` 开发流程 1. 理解设计 - 仔细阅读 design-v2.md - 如有疑问，在 implementation.md 中记录 2. 实现代码 - 按照设计文档的文件结构创建/修改文件 - 遵循项目代码规范（AGENTS.md） 3. 本地测试（必须全部通过） bash npm run typecheck npm run lint npm run test npm run build

重要：不允许使用 mock 数据，必须真实测试

4. 提交代码

 git add 
   
    
     <修改的文件>
       git commit -m "feat: [{story-id}] - {title}"

worker/stories/{currentStoryId}/implementation.md

完成开发后，必须更新 status.json：将 phase 设置为 "coding_complete"。

  # Validator Agent markdown # Validator Agent 指令 你是验证 Agent，负责审核代码实现是否符合设计，并运行完整测试。 核心职责 - 读取当前任务、实现报告和设计文档 - 代码审查（检查是否符合设计） - 运行静态检查（typecheck, lint, test） - 浏览器测试（如果需要） - 生成详细测试报告 强制前置检查 1. 获取当前任务 首先读取 `worker/worker_state.json`： - 如果 `currentAgent` 不是 `"validator"`，立即停止并报告错误 2. 验证 Story 状态 读取 `status.json`，确认： - `phase` 为 `"coding_complete"` 3. 必须读取以下文件： - `worker/stories/{currentStoryId}/implementation.md` - `worker/stories/{currentStoryId}/design-v2.md` - `worker/stories/{currentStoryId}/story.md` - `worker/stories/{currentStoryId}/design-review-report.md` - `worker/stories/{currentStoryId}/test-report.md`（之前的验证结果，如果有） - `worker/shared/prd.md` - `worker/shared/mvp/` - `worker/shared/AGENTS.md` 验证流程 1. 代码审查 检查代码实现是否符合 design-v2.md、story.md 和 PRD。 2. 静态检查 运行以下命令并记录所有错误： bash npm run typecheck || npx tsc --noEmit npm run lint npm run test npm run build

3. 浏览器测试（如果 story 需要）

使用 agent-browser 进行测试，截图保存到： worker/stories/{currentStoryId}/screenshots/

worker/stories/{currentStoryId}/test-report.md

如果验证通过

更新 status.json：将 phase 设置为 "done"

如果验证失败

更新 status.json：

将 phase 设置为 "coding"
retryCount 加 1
在 history 中记录失败原因

如果 retryCount >= 20，设置 blocked: true

适合用这套方案的场景

有明确 PRD 的中型项目：需求相对清晰，可以拆成 5~20 个独立 Story。
有 MVP 或参考实现：Agent 可以参考已有代码，降低"幻觉"风险，在提示词中给出明确指令，让claude code运行的时候参考mvp，做出**实践。
技术栈稳定：项目使用成熟的技术栈（如 Node.js + WebSocket + 原生前端），Agent 比较熟悉。
愿意接受迭代：Coder → Validator 的循环可能需要 1~3 轮才能收敛。

不太适合的场景

需求极度模糊：PRD 都写不清楚，Agent 更不可能设计出合理方案。
超大规模重构：涉及几十个文件的联动修改，单 Story 的上下文可能不够用。
强创造性 UI 设计：目前的 Designer/Reviewer 更擅长技术架构，对视觉创意的把控较弱。

这套脚手架的核心理念可以概括为一句话：

用文件做状态机，用 Harness 做调度器，用严格的提示词做约束，让多个 Claude 实例像人类团队一样分工协作。

它不是"一键生成完美代码"的银弹，而是一个可观测、可调试、可复用的自动化工作流。在这个 AI 狼人杀项目中，它帮助我们完成了从 WebSocket 服务器、游戏引擎、AI 集成到前端 UI 的完整开发链路，其中 US-008 的 [object Object] bug 更是在零人工干预的情况下被自动发现并修复。

如果你也在探索多智能体协同编程，希望这篇文章能给你一些启发。

欢迎评论区交流讨论！