Claude Flow 入门指南

发表于 分类于 ，

Claude Flow 入门指南

🚀 Claude Flow v2.0.0-alpha - 企业级AI代理编排平台，让开发更智能、更高效！

📋 目录

🚀 快速开始

第1步：初始化项目

1
2
3
npm init -y
# 启动MCP服务器，让Claude能够协调多个AI代理
npx claude-flow@alpha mcp start

第2步：开发功能 (推荐TDD)

1
2
# 一条命令完成从需求到代码的全流程
npx claude-flow sparc tdd "用户注册功能"

第3步：查看结果

1
2
3
ls src/         # 查看源码
npm test        # 运行测试  
npm run build   # 构建项目

🎯 基本命令

5个最常用命令

1
2
3
4
5
6
7
8
9
10
11
12
13
14
# 1. 查看所有可用模式
npx claude-flow sparc modes

# 2. 运行TDD完整流程 (最推荐)
npx claude-flow sparc tdd "创建用户登录功能"

# 3. 单独运行某个阶段
npx claude-flow sparc run architect "设计API架构"

# 4. 并行执行多个模式
npx claude-flow sparc batch spec-pseudocode,architect "构建支付系统"

# 5. 启动MCP协调服务器
npx claude-flow@alpha mcp start

MCP命令详解

npx claude-flow@alpha mcp start 的作用：

  • 启动协调服务器：让Claude能够管理多个AI代理
  • 建立通信桥梁：不同代理之间可以共享信息和协调工作
  • 内存管理：代理可以存储和检索共享知识
  • 任务编排：自动分配和监控复杂任务的执行

什么时候需要运行：

  • 第一次使用claude-flow时
  • 想要使用多代理协调功能时
  • 执行复杂的SPARC工作流时

🧪 TDD是什么

TDD = Test-Driven Development (测试驱动开发)

TDD的3个步骤：

  1. 🔴 Red - 先写测试 (测试失败，红色)
  2. 🟢 Green - 写代码让测试通过 (绿色)
  3. 🔵 Refactor - 优化代码 (保持测试通过)

为什么用TDD？

  • ✅ 代码质量高 - 有测试保障，不容易出bug
  • ✅ 需求清晰 - 先写测试，强迫你想清楚要做什么
  • ✅ 重构安全 - 改代码时有测试保护，不怕改坏
  • ✅ 文档作用 - 测试就是活的使用文档

传统开发 vs TDD

1
2
3
4
5
# 传统方式：
写代码 → 手动测试 → 发现bug → 修复 → 重复...

# TDD方式：
写测试 → 写代码 → 测试通过 → 重构 → 完成！

claude-flow中的TDD

npx claude-flow sparc tdd "功能描述" 会自动：

  1. 分析需求 (Specification)
  2. 设计算法 (Pseudocode)
  3. 架构设计 (Architecture)
  4. 写测试+代码 (Refinement)
  5. 集成完善 (Completion)

💻 实战Demo

🆕 Demo 1: 新建项目完整流程

1
2
3
4
5
6
7
8
9
10
11
12
13
14
# 1. 创建新项目目录
mkdir my-new-app && cd my-new-app

# 2. 初始化项目
npm init -y

# 3. 启动MCP协调服务器 (只需运行一次)
npx claude-flow@alpha mcp start

# 4. 使用TDD开发新功能 (一条命令完成全流程)
npx claude-flow sparc tdd "创建用户注册和登录系统"

# 5. 查看生成的代码
ls src/ && npm test && npm run build

🔧 Demo 2: 修改现有项目

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
# 1. 进入现有项目目录
cd existing-project

# 2. 启动MCP服务器 (如果还没启动)
npx claude-flow@alpha mcp start

# 3. 添加新功能到现有项目
npx claude-flow sparc tdd "添加支付功能到现有电商系统"

# 4. 只修改特定部分 (不用完整TDD)
npx claude-flow sparc run architect "重构用户认证模块"
npx claude-flow sparc run code "优化数据库查询性能"

# 5. 批量处理多个改进
npx claude-flow sparc batch architect,code,tester "升级API版本到v2"

🚀 Demo 3: 特定场景命令

1
2
3
4
5
6
7
8
9
10
11
# 只做架构设计 (不写代码)
npx claude-flow sparc run architect "设计微服务架构"

# 只写代码 (已有设计)
npx claude-flow sparc run code "实现用户管理API"

# 只写测试 (已有代码)
npx claude-flow sparc run tester "为现有功能添加单元测试"

# 代码审查和优化
npx claude-flow sparc run security-review "审查代码质量并提供改进建议"

🎯 所有模式详解

🏗️ 核心开发流程

  • 📋 spec-pseudocode - 需求分析，写项目规格和伪代码
  • 🏗️ architect - 架构设计，设计可扩展的模块化架构
  • 🧠 code - 核心编码，写干净高效的代码
  • 🧪 tdd - 测试驱动开发，先写测试再写代码

🔧 质量保障

  • 🪲 debug - 调试问题，排查运行时错误和逻辑问题
  • 🛡️ security-review - 安全审查，检查代码安全漏洞
  • 🧹 refinement-optimization-mode - 代码优化，重构和性能提升

📚 文档与集成

  • 📚 docs-writer - 写文档，生成清晰的使用说明
  • 🔗 integration - 系统集成，合并各模块成完整系统
  • 📈 post-deployment-monitoring-mode - 部署监控，观察线上系统表现

🚀 运维部署

  • 🚀 devops - 运维自动化，CI/CD和基础设施管理

🎓 专业工具

  • 🔐 supabase-admin - Supabase数据库专家
  • ♾️ mcp - MCP服务集成专家
  • ❓ ask - 任务指导，帮你选择合适的模式
  • 📘 tutorial - SPARC教学，学习完整开发流程
  • ⚡️ sparc - 工作流编排，分解复杂任务

💡 实用场景示例

1
2
3
4
5
6
7
8
9
10
11
12
13
# 🔍 不知道从哪开始？
npx claude-flow sparc run ask "我想做一个博客系统"

# 📋 分析需求 → 🏗️ 设计架构 → 🧠 写代码
npx claude-flow sparc run spec-pseudocode "用户注册登录功能"
npx claude-flow sparc run architect "微服务电商平台"
npx claude-flow sparc run code "实现用户管理API"

# 🪲 修复bug → 🛡️ 安全检查 → 📚 写文档 → 🚀 部署
npx claude-flow sparc run debug "登录后页面白屏"
npx claude-flow sparc run security-review "检查支付模块安全性"
npx claude-flow sparc run docs-writer "为API生成使用文档"
npx claude-flow sparc run devops "部署到AWS"

📊 分析报告查看

claude-flow执行完成后会生成详细的分析报告，帮你了解性能和成本。

4种报告类型

1. 性能报告 📈

1
2
3
4
5
6
7
8
# 查看24小时性能报告 (默认)
npx claude-flow@alpha analysis performance-report

# 查看7天详细报告
npx claude-flow@alpha analysis performance-report --timeframe 7d --format detailed

# 导出JSON格式报告
npx claude-flow@alpha analysis performance-report --format json

2. Token使用分析 💰

1
2
3
4
5
# 分析Token消耗和成本
npx claude-flow@alpha analysis token-usage --breakdown --cost-analysis

# 查看特定代理的Token使用
npx claude-flow@alpha analysis token-usage --agent coder

3. 性能瓶颈检测 🔍

1
2
3
4
5
# 检测系统瓶颈
npx claude-flow@alpha analysis bottleneck-detect --scope system

# 检测特定代理瓶颈
npx claude-flow@alpha analysis bottleneck-detect --scope agent --target coordinator-1

4. 查看执行状态 📋

1
2
3
4
5
# 查看系统整体状态
npx claude-flow@alpha status

# 查看Hive Mind指标
npx claude-flow@alpha hive-mind metrics

📁 报告文件位置

  • HTML报告: analysis-reports/performance-*.html (很有价值！)
  • 执行记录: coordination/orchestration/ 目录
  • 内存数据: memory/claude-flow-data.json

💡 完整分析流程

1
2
3
4
5
6
7
8
9
# 1. 执行开发任务
npx claude-flow@alpha sparc tdd "用户登录功能"

# 2. 查看详细报告
npx claude-flow@alpha analysis performance-report --format detailed
npx claude-flow@alpha analysis token-usage --breakdown  

# 3. 如果有问题，检查具体瓶颈
npx claude-flow@alpha analysis bottleneck-detect --scope system

⚙️ 代码规范设置

claude-flow支持设置个人代码规范，让所有生成的代码都遵循你的风格，无需每次都提醒。

方法1: 修改CLAUDE.md配置文件 (推荐)

编辑项目根目录的 CLAUDE.md 文件，添加你的代码规范：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
## 代码风格与规范

### 编程语言规范
**JavaScript/TypeScript:**
- 使用 ESLint + Prettier
- 缩进: 2个空格, 字符串: 单引号, 分号: 必须添加
- 变量命名: camelCase, 函数命名: 动词开头
- 常量: UPPER_SNAKE_CASE

**Python:**
- 遵循 PEP 8, 缩进: 4个空格
- 变量命名: snake_case, 类名: PascalCase
- 最大行长: 88字符 (Black格式化)

### 项目结构规范
- 源码放在 `src/` 目录, 测试放在 `tests/` 目录
- 每个模块不超过500行代码
- 函数必须有JSDoc注释, 使用中文注释

### 安全规范
- 永远不要硬编码密钥, 敏感信息使用环境变量
- 输入验证和SQL注入防护

方法2: 使用配置命令设置

1
2
3
4
5
6
7
# 设置代码风格配置
npx claude-flow@alpha config set codeStyle.javascript.indent 2
npx claude-flow@alpha config set codeStyle.javascript.quotes "single"

# 设置项目结构偏好
npx claude-flow@alpha config set project.sourceDir "src"
npx claude-flow@alpha config set project.maxFileLines 500

方法3: 创建风格模板文件

1
2
3
4
5
6
7
8
9
10
mkdir -p .claude
cat > .claude/style-guide.md << 'EOF'
# 个人代码风格指南

## TypeScript/React规范
- 使用函数式组件 + Hooks
- Props接口以Props结尾: UserCardProps
- 自定义Hook以use开头: useUserData
- 组件文件名使用PascalCase: UserCard.tsx
EOF

💡 验证设置效果

1
2
3
# 生成代码测试风格
npx claude-flow@alpha sparc run code "创建一个用户列表组件"
# 检查生成的代码是否符合你设置的风格规范

🏗️ 项目信息配置

为了避免每次执行任务都要重新分析项目，可以在配置文件中预设项目的基本情况。

方法1: 在CLAUDE.md中设置项目信息 (推荐)

编辑 CLAUDE.md 文件，添加项目全局信息：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
## 项目基本信息

### 🎯 项目概述
- **项目名称**: 电商管理系统 
- **业务领域**: 电子商务/零售
- **目标用户**: 商家管理员、客服人员
- **核心功能**: 商品管理、订单处理、用户管理、数据分析

### 🏗️ 技术架构
- **前端**: React 18 + TypeScript + Vite
- **后端**: Node.js + Express + TypeScript  
- **数据库**: PostgreSQL + Redis (缓存)
- **部署**: Docker + AWS EC2

### 📁 目录结构
├── frontend/                 # 前端项目
│   ├── src/components/      # 通用组件
│   ├── src/pages/          # 页面组件
│   └── tests/              # 前端测试
├── backend/                 # 后端项目  
│   ├── src/controllers/    # 控制器
│   ├── src/services/       # 业务逻辑
│   └── tests/              # 后端测试
├── shared/                 # 共享代码
└── docs/                   # 项目文档

### 💡 开发注意事项
- **数据安全**: 所有敏感数据必须加密存储
- **性能要求**: 页面加载时间 < 2秒，API响应 < 500ms
- **浏览器兼容**: 支持Chrome 90+, Safari 14+, Firefox 88+

### 📊 业务规则
- **订单状态**: 待付款 → 已付款 → 已发货 → 已完成
- **用户权限**: 超级管理员 > 管理员 > 普通用户

方法2: 创建项目配置文件

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
mkdir -p .claude
cat > .claude/project.json << 'EOF'
{
  "project": {
    "name": "电商管理系统",
    "type": "full-stack-web",
    "domain": "e-commerce"
  },
  "structure": {
    "frontend": {"path": "./frontend", "framework": "react"},
    "backend": {"path": "./backend", "framework": "express"}
  },
  "business": {
    "modules": ["用户管理", "商品管理", "订单处理"],
    "workflows": {
      "订单流程": ["创建订单", "支付", "发货", "收货"]
    }
  }
}
EOF

💡 配置效果

1
2
3
4
5
6
7
# 执行任务时，AI会自动读取项目信息
npx claude-flow@alpha sparc run code "为商品管理模块添加批量导入功能"

# AI会自动了解：
# - 这是电商系统的商品管理模块
# - 需要放在正确的目录结构中
# - 遵循已设定的安全和性能规范

🔧 环境问题解决

🚨 WSL环境下无法运行Maven/测试时

问题: 在WSL中无法执行Windows的Maven，导致TDD无法完成测试阶段

解决方案: 使用SPARC但跳过测试阶段

1
2
3
4
5
6
7
8
9
10
11
# 方案1: 分步执行 (推荐)
npx claude-flow sparc run spec-pseudocode "用户登录功能"
npx claude-flow sparc run architect "用户登录功能"
npx claude-flow sparc run code "用户登录功能"
# 跳过 tester 阶段

# 方案2: 批量执行但排除测试
npx claude-flow sparc batch spec-pseudocode,architect,code "用户登录功能"

# 方案3: 只要代码实现 (最简单)
npx claude-flow sparc run code "根据需求实现用户登录功能的完整代码"

🎯 不同场景的最佳选择

环境 推荐命令 说明
完整开发环境 sparc tdd 完整TDD流程
WSL/受限环境 sparc batch spec-pseudocode,architect,code 跳过测试阶段
快速原型 sparc run code 直接编码

📁 文件管理详解

根据你的项目结构，以下是各文件的作用和管理建议：

🔧 可执行文件 (不要修改)

  • claude-flow - Linux/macOS CLI主程序
  • claude-flow.bat - Windows批处理文件
  • claude-flow.ps1 - PowerShell脚本
  • 说明: 这些是claude-flow的核心执行文件，不要手动修改

⚙️ 配置文件 (可以修改)

  • claude-flow.config.json ✅ - 系统配置文件，可调整最大代理数、执行策略等
  • CLAUDE.md ✅ - 项目指令和规范文档，强烈建议修改

📊 运行时数据 (自动生成，不要修改)

  • analysis-reports/*.html ⭐⭐⭐⭐⭐ - 性能报告HTML文件，很有价值，定期查看
  • coordination/ - 代理协调目录，存储多代理协调记录
  • memory/ - 持久化存储，代理学习和记忆数据

🎯 版本控制建议

✅ 提交到Git的文件

1
2
3
4
5
6
git add CLAUDE.md                    # 项目配置核心
git add claude-flow.config.json     # 系统配置
git add docs/                       # 文档目录
git add src/                        # 源代码 (生成后)
git add tests/                      # 测试文件 (生成后)
git add package.json                # 项目依赖 (生成后)

❌ 添加到.gitignore的文件

1
2
3
4
5
6
7
8
9
10
11
12
13
14
# Claude Flow 运行时文件
claude-flow
claude-flow.bat
claude-flow.ps1
coordination/
memory/
analysis-reports/
*.log

# 标准忽略
node_modules/
.env
dist/
build/

💡 文件管理关键提醒

  1. 只修改配置文件 - CLAUDE.md 和 claude-flow.config.json
  2. 定期查看性能报告 - analysis-reports/*.html 了解性能和成本
  3. 不要删除运行时目录 - coordination/ 和 memory/ 让系统自动管理
  4. 备份重要配置 - 修改前先备份 CLAUDE.md

💡 实用小贴士

🎯 使用建议

  • 初学者首选: 用 sparc tdd 命令，自动完成所有阶段
  • WSL用户: 用 sparc batch spec-pseudocode,architect,code 替代 sparc tdd
  • 执行完成后记得查看分析报告，了解性能和成本
  • 设置好代码规范和项目信息，所有任务都会自动遵循

⚙️ 环境要求

  • Node.js版本: 需要18+
  • MCP服务: mcp start 只需要运行一次，除非重启终端
  • 任务描述: 使用中文描述，AI理解更准确

📊 成本控制

  • 定期查看 token-usage 报告控制成本
  • TDD让代码更可靠，初学者强烈推荐使用
  • 无法运行测试时，记得手动验证生成的代码功能

🚀 项目类型选择

  • 新项目: 用 sparc tdd
  • 现有项目: 用单独的 sparc run 命令
  • 快速验证: 用 sparc run code 直接生成代码

📞 获取帮助

🎉 恭喜！你已经掌握了Claude Flow的核心用法。现在开始你的AI驱动开发之旅吧！