Agentic Workflow System

Claude代理工作流系统

一个可重用、功能强大的编排框架，用于使用AI编码助手构建任何软件项目

版本：2.2 许可证：麻省理工学院 兼容：Claude Code CLI、Gemini 2.5（反重力IDE） 最后更新日期：2024年12月

______________________________________________________________________

🎯 这是什么？

这是一个 通用的、可重用的多智能体系统 这将改变您使用AI编码助手构建软件项目的方式。它使用专门的子代理从始至终管理复杂的项目，并强制进行人工监督和视觉测试。

适用于Claude Code和Gemini -使用您喜欢的任何AI助手！

将此系统用于任何项目： web应用程序、API、移动应用程序、脚本、自动化工具或任何软件开发任务。

______________________________________________________________________

⚡ 主要特点

• 🧠 编排器 -管理全局和待办事项的大型上下文窗口（Claude 200K/Gemini 1M+）
• ✍️ 编码器子代理 -在隔离的上下文中一次执行一个任务
• 👁️ 测试员分代理 -使用Playwright MCP浏览器自动化进行视觉验证
• 🆘 卡住的子代理 -人为升级点（无自动回退）
• 📋 待办事项跟踪 -始终准确了解您的项目进展情况
• 🔄 迭代工作流 -创建待办事项→ 委派给程序员→ test → 重复
• 🔀 多供应商 -适用于Claude Code CLI和Gemini 2.5（反重力IDE）
• 📏 智能任务拆分 -通过将大型任务拆分为可管理的部分来自动处理它们

______________________________________________________________________

🚀 快速启动（任何项目）

先决条件

1. 克劳德代码CLI 已安装(文档)
2. Node.js （用于剧作家MCP视觉测试）
3. Git （可选，用于版本控制）

第一步：将此系统复制到您的项目中

# Option A: Copy the entire system
cp -r /c/Users/travi/claude-agent-system /path/to/your-project/.

# Option B: Clone and copy
git clone  /path/to/your-project/claude-agent-system

步骤2：导航并启动Claude代码

cd /path/to/your-project/claude-agent-system
claude

代理从自动加载 .claude/ 目录。

第三步：告诉克劳德要做什么

自然地描述你的项目：

"Build a React todo app with TypeScript and Tailwind CSS"

或

"Create a REST API with Express, PostgreSQL, and JWT authentication"

或

"Build a Python script that scrapes website data and exports to CSV"

克劳德将：

1. 创建详细的待办事项列表
2. 将任务委托给编码子代理
3. 使用测试器子代理测试实现
4. 需要时通过卡住的代理向您提问
5. 迭代完成项目

______________________________________________________________________

🏗️ 系统架构

┌─────────────────────────────────────────────────┐
│  YOU (User)                                     │
│  - Provides project requirements                │
│  - Makes decisions when agents ask              │
└────────────┬────────────────────────────────────┘
             │
             ↓
┌─────────────────────────────────────────────────┐
│  ORCHESTRATOR (Main Claude - 200K context)      │
│  - Creates comprehensive TodoWrite lists        │
│  - Maintains big picture and project state      │
│  - Delegates one task at a time to subagents    │
│  - Tracks overall progress                      │
└──┬────────┬────────┬─────────────────────────────┘
   │        │        │
   ↓        ↓        ↓
┌──────┐ ┌──────┐ ┌──────┐
│CODER │ │TESTER│ │STUCK │
│      │ │      │ │      │
│Fresh │ │Fresh │ │Asks  │
│context│ │context│ │you   │
│      │ │      │ │      │
│Builds│ │Visual│ │Human │
│code  │ │tests │ │input │
└──────┘ └──────┘ └──────┘

______________________________________________________________________

📋 工作流程

USER: "Build X"
    ↓
ORCHESTRATOR: Creates detailed TodoWrite list
    ↓
ORCHESTRATOR: Invokes coder(todo #1)
    ↓
CODER (fresh context): Implements feature
    ↓
    ├─→ Problem? → Invokes STUCK → You decide → Continue
    ↓
CODER: Reports completion
    ↓
ORCHESTRATOR: Invokes tester(verify todo #1)
    ↓
TESTER (fresh context): Playwright screenshots & verification
    ↓
    ├─→ Test fails? → Invokes STUCK → You decide → Continue
    ↓
TESTER: Reports success
    ↓
ORCHESTRATOR: Marks todo #1 complete ✓
    ↓
ORCHESTRATOR: Invokes coder(todo #2)
    ↓
... Repeat until all todos done ...
    ↓
ORCHESTRATOR: Reports final results to YOU

______________________________________________________________________

🤖 代理人

编曲（主克劳德）

地点： .claude/CLAUDE.md 背景： 20万代币（维护整个项目）

责任：

• 使用TodoWrite创建和维护全面的待办事项列表
• 保持大局和项目愿景
• 将个人任务委托给专门的子代理
• 跟踪所有任务的总体进度
• 在关键里程碑向用户报告

它没有做什么：

• 直接执行代码（委托给编码器）
• 测试实施（委托给测试人员）
• 做出假设（使用粘合剂进行澄清）

编码器子代理

地点： .claude/agents/coder.md 背景： 每个任务的新上下文

责任：

• 接收一个特定待办事项
• 实现干净、实用的代码
• 遵循语言/框架的最佳实践
• 切勿使用回退或变通方法
• 出现问题时立即调用卡住的代理

可用工具：

• 读取、写入、编辑（文件操作）
• 全球，Grep（搜索）
• Bash（终端命令）
• 任务（生成其他代理）

测试员分代理

地点： .claude/agents/tester.md 背景： 每次测试的新上下文

责任：

• 通过实际引用和查看来验证实现
• 使用Playwright MCP进行视觉测试
• 截图作为证据
• 测试交互（点击、表单、导航）
• 切勿将未通过的测试标记为通过
• 发现视觉问题时调用卡住的代理

可用工具：

• 任务（编剧MCP）
• 阅读（了解构建的内容）
• Bash（运行测试）

卡住的子代理

地点： .claude/agents/stuck.md 背景： 每个问题都有新的上下文

责任：

• 任何问题的人为升级点
• 提供清晰的选项供您选择
• 阻止进度，直到您做出响应
• 将您的决定返回给呼叫代理
• 确保没有盲目的回退或变通方法

这是关键的区别： 没有无声的失败！

______________________________________________________________________

🎯 “无退路”规则

传统AI： 点击错误→ 尝试解决方法→ 可能会默默地失败

该系统： 点击错误→ 问你→ 你决定→ 正确进行

每个代理都会调用卡住的代理，而不是猜测或使用回退。 你保持控制。

______________________________________________________________________

💡 示例会话

示例1：反应todo应用程序

YOU: "Build a React todo app with TypeScript and Tailwind CSS"

ORCHESTRATOR creates todos:
  [ ] Initialize Next.js with TypeScript
  [ ] Set up Tailwind CSS
  [ ] Create TodoList component
  [ ] Create TodoItem component
  [ ] Add state management (useState)
  [ ] Style with Tailwind
  [ ] Test all functionality

ORCHESTRATOR invokes coder(todo #1)
CODER: Creates Next.js project with TypeScript
CODER: Reports completion

ORCHESTRATOR invokes tester("Verify Next.js app runs")
TESTER: Uses Playwright, takes screenshot
TESTER: Reports success

ORCHESTRATOR: Marks todo #1 complete ✓
ORCHESTRATOR invokes coder(todo #2)
... continues until all todos done

示例2:Python数据抓取器

YOU: "Build a Python script that scrapes product data from a website and exports to CSV"

ORCHESTRATOR creates todos:
  [ ] Set up Python project with dependencies (requests, beautifulsoup4, pandas)
  [ ] Create scraper function to fetch HTML
  [ ] Parse HTML to extract product data
  [ ] Store data in pandas DataFrame
  [ ] Export to CSV with proper formatting
  [ ] Add error handling
  [ ] Test with sample URL

ORCHESTRATOR invokes coder(todo #1)
CODER: Creates requirements.txt, installs packages
CODER: Reports completion

ORCHESTRATOR invokes coder(todo #2)
CODER: Implements scraper function
CODER: ERROR - Website requires authentication
CODER: Invokes STUCK agent

STUCK: Asks YOU:
  "Target website requires authentication. How to proceed?"
  Options:
  - Add authentication (provide credentials)
  - Use a different test website
  - Skip authentication for MVP

YOU choose: "Use a different test website (https://example.com)"

STUCK: Returns your decision to coder
CODER: Proceeds with example.com
... continues until done

示例3：Express REST API

YOU: "Create a REST API with Express, PostgreSQL, and JWT authentication"

ORCHESTRATOR creates todos:
  [ ] Initialize Node.js project with TypeScript
  [ ] Set up Express server
  [ ] Configure PostgreSQL connection
  [ ] Create database schema (users table)
  [ ] Implement user registration endpoint
  [ ] Implement login endpoint with JWT
  [ ] Add protected route with JWT middleware
  [ ] Add error handling middleware
  [ ] Test all endpoints

ORCHESTRATOR invokes coder(todo #1)
... delegates systematically ...
CODER builds each feature
TESTER verifies endpoints with test requests
... completes entire API

______________________________________________________________________

📂 目录结构

claude-agent-system/
├── .claude/                   # Claude Code configuration
│   ├── CLAUDE.md              # Orchestrator instructions
│   ├── settings.local.json    # Claude settings
│   └── agents/
│       ├── coder.md          # Coder subagent definition
│       ├── tester.md         # Tester subagent definition
│       └── stuck.md          # Stuck subagent definition
├── .gemini/                   # Gemini configuration
│   ├── GEMINI.md              # Orchestrator instructions
│   ├── settings.json          # Gemini settings
│   └── agents/
│       ├── coder.md          # Coder subagent definition
│       ├── tester.md         # Tester subagent definition
│       └── stuck.md          # Stuck subagent definition
├── .mcp.json                  # Playwright MCP configuration
├── .gitignore
├── README.md                  # This file
└── HOW-TO-USE.md             # Detailed usage guide

# Your project files will be created here:
├── (generated project structure)
│   ├── src/
│   ├── package.json
│   └── ...

______________________________________________________________________

🎓 如何用于不同的项目类型

Web应用程序（Next.js、React、Vue）

"Build a [app type] with [features] using [tech stack]"

Example:
"Build a blog with user authentication using Next.js 14, TypeScript, and Supabase"

API（Express、FastAPI、Django）

"Create a REST API with [endpoints] using [framework] and [database]"

Example:
"Create a REST API with CRUD operations for a task manager using Express and MongoDB"

脚本和自动化

"Build a Python/Node script that [does something]"

Example:
"Build a Node.js script that monitors a folder and automatically backs up new files to S3"

移动应用程序（React Native）

"Build a [mobile app type] with [features] using React Native"

Example:
"Build a weather app with location-based forecasts using React Native and OpenWeather API"

桌面应用程序（Electron）

"Create an Electron app that [functionality]"

Example:
"Create an Electron app that manages local markdown notes with search and tags"

______________________________________________________________________

⚙️ 定制

添加自定义代理

在中创建新的代理文件 .claude/agents/your-agent.md:

---
name: your-agent
description: What this agent does
tools: Read, Write, Bash, etc.
model: sonnet
---

# Your Custom Agent

You are [agent role and purpose]

## Your Mission
[Describe what this agent should do]

## Workflow
1. [Step 1]
2. [Step 2]
...

## When to Invoke Stuck Agent
[Conditions that require human input]

然后从编排器调用：

Invoke the your-agent subagent for [specific task]

修改代理行为

在中编辑代理文件 .claude/agents/ 自定义：

• 可用工具
• 工作流程步骤
• 升级触发
• 成功标准

更改MCP配置

编辑 .mcp.json 要添加更多MCP服务器：

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest"],
      "env": {}
    },
    "your-mcp-server": {
      "command": "your-command",
      "args": ["args"],
      "env": {}
    }
  }
}

______________________________________________________________________

🚨 成功的关键规则

对于您（用户）：

1. ✅ 提供明确的项目要求
2. ✅ 当被卡住的客服提出问题时，及时回应
3. ✅ 信任流程-让代理完成任务
4. ✅ 查看测试员代理的屏幕截图
5. ✅ 检查TodoWrite列表以跟踪进度

对于编排者：

1. ✅ 立即创建详细的待办事项列表
2. ✅ 一次委派一项任务
3. ✅ 使用测试器测试每个实现
4. ✅ 每次完成后更新待办事项
5. ✅ 在不创建页面的情况下，切勿创建页眉/页脚链接（防止404）

对于所有代理：

1. ✅ 检查任何问题、不确定性或错误
2. ✅ 切勿使用回退或变通方法
3. ✅ 切勿跳过测试
4. ✅ 永远不要对需求做出假设

______________________________________________________________________

📊 成功指标

当满足以下条件时，项目即告完成：

• ✅ 在TodoWrite中标记为已完成的所有待办事项
• ✅ 所有测试均已通过（测试人员已通过截图验证）
• ✅ 代码运行时没有错误
• ✅ 满足要求（功能与用户请求匹配）
• ✅ 零404错误或断开链接
• ✅ 用户对结果满意

______________________________________________________________________

🐛 故障排除

“代理未加载”

• 验证 .claude/ 当前目录中存在该目录
• 检查代理文件是否存在： .claude/agents/*.md
• 在正确的目录中重新启动Claude Code

“编码器一直失败”

• 它应该自动调用卡住的代理
• 检查卡住的特工是否在问你问题
• 查看错误消息以确保清晰

“测试人员不提供屏幕截图”

• 确保安装了Node.js（Playwright需要）
• 检查 .mcp.json 配置
• 验证Playwright MCP是否可以运行： npx @playwright/mcp@latest

“进展似乎很慢”

• 正常！复杂的任务需要时间
• 检查TodoWrite列表以了解进度
• 询问编排者：“当前状态如何？”

“卡住的特工问了太多问题”

• 好！这意味着没有无声的失败
• 特工们正在进行彻底调查
• 你的决定正确地指导了项目

______________________________________________________________________

💡 专业建议

1. 从小做起 -首先用一个简单的项目测试系统
2. 具体说明 -你的要求越详细，结果就越好
3. 信任截图 -测试仪提供每个功能的视觉证明
4. 快速决策 -当卡住的代理询问时，请及时回复
5. 检查全部 -进度在TodoWrite中始终可见
6. 迭代 -完成后，您始终可以要求更改

______________________________________________________________________

🎓 最佳实践

编写明确的要求

❌ 坏：

"Build a website"

✅ 好：

"Build a portfolio website with:
- Homepage with hero section and project grid
- About page with bio and skills
- Contact form that sends emails
- Responsive design for mobile
- Dark mode toggle
Technology: Next.js 14, TypeScript, Tailwind CSS"

提供上下文

❌ 坏：

"Add authentication"

✅ 好：

"Add user authentication with:
- Email/password registration
- JWT tokens for session management
- Protected routes requiring login
- Password reset functionality
Use: Supabase Auth for backend"

快速做出决定

当卡住的代理问：

• ✅ 仔细阅读选项
• ✅ 根据您的需求选择最佳方法
• ✅ 别想太多，你以后总是可以改变的
• ✅ 提供明确的方向

______________________________________________________________________

📚 其他资源

• 克劳德代码文档： https://docs.claude.com/en/docs/claude-code
• 次级代理商指南： https://docs.claude.com/en/docs/claude-code/sub-agents
• 剧作家MCP： https://github.com/microsoft/playwright-mcp
• 原始代表： https://github.com/IncomeStreamSurfer/claude-code-agents-wizard-v2

______________________________________________________________________

🤝 贡献

这个系统是开放和可扩展的！请随意：

• 添加新的专业代理
• 改进现有代理提示
• 共享您的自定义配置
• 提交带有增强功能的PR

______________________________________________________________________

📝 许可证

MIT许可证-使用它，修改它，分享它！

______________________________________________________________________

🎯 快速参考卡

┌─────────────────────────────────────────────────┐
│  QUICK REFERENCE                                │
├─────────────────────────────────────────────────┤
│  Start:                                         │
│  $ cd your-project/claude-agent-system          │
│  $ claude                                       │
│                                                 │
│  Tell Claude:                                   │
│  "Build [project] with [features] using [tech]" │
│                                                 │
│  Agents:                                        │
│  • ORCHESTRATOR - Creates todos, delegates      │
│  • CODER - Implements one task at a time        │
│  • TESTER - Visual verification with Playwright │
│  • STUCK - Asks you when problems occur         │
│                                                 │
│  Key Principle:                                 │
│  NO FALLBACKS - You decide, not the AI          │
│                                                 │
│  Check Progress:                                │
│  TodoWrite list always shows current status     │
└─────────────────────────────────────────────────┘

______________________________________________________________________

准备好用人工智能辅助开发创造惊人的东西了吗？在此目录中启动Claude Code会话并描述您的项目！ 🚀