🚀 SOLO 开发指南

Appearance

SOLO 快速开始指南 ​

本指南将带您快速体验SOLO工作模式，学会如何将其与现有的API-First开发流程结合使用。

🎯 学习目标 ​

完成本指南后，您将能够：

  • ✅ 理解SOLO四阶段工作流程
  • ✅ 启动一个SOLO+API-First项目
  • ✅ 体验从需求到API实现的完整流程
  • ✅ 掌握SOLO命令和子代理的使用

🛠️ 前置条件 ​

环境要求 ​

  • Claude Code CLI 已安装并配置
  • 熟悉基本的API-First开发概念
  • 了解OpenAPI规范基础知识

技术栈选择 ​

本指南支持以下技术栈，请选择您熟悉的：

  • Java: Spring Boot + Maven/Gradle
  • Python: FastAPI + Poetry/pip
  • TypeScript: Express + npm/yarn

🚀 第一步：启动SOLO项目 ​

1.1 创建项目目录 ​

bash
# 创建新项目目录
mkdir user-management-api
cd user-management-api

# 初始化Git仓库
git init

1.2 启动SOLO工作模式 ​

bash
# 使用SOLO主命令启动项目
/solo 创建一个用户管理API系统，支持用户注册、登录、权限管理等功能

# SOLO会自动调用product-manager子代理开始需求收集

1.3 体验需求澄清对话 ​

Product Manager子代理会引导您进行结构化的需求收集：

🤖 Product Manager: 我来帮您分析用户管理API的产品需求。

首先，让我们明确核心问题：
1. 这个API主要解决什么业务问题？
2. 谁是主要用户？他们现在如何管理用户？
3. 核心价值主张是什么？

请详细描述您的需求...

📋 第二步：完成需求分析 ​

2.1 回答产品问题 ​

根据提示回答以下关键问题：

业务背景：

  • 目标：为现有系统提供统一的用户认证和权限管理服务
  • 用户：内部开发团队和系统管理员
  • 痛点：当前多个系统各自维护用户信息，数据不一致

功能需求 (示例回答)：

  • 用户注册和登录
  • 角色和权限管理
  • JWT Token管理
  • 用户信息CRUD操作
  • 密码策略和安全控制

非功能需求：

  • 并发：支持1000+并发用户
  • 性能：API响应时间 < 200ms
  • 安全：支持HTTPS、密码加密、防暴力破解

2.2 查看生成的PRD文档 ​

需求分析完成后，检查生成的文档：

bash
# 查看PRD文档
cat .solo/docs/PRD.md

# 检查项目结构
tree .solo/

PRD文档将包含：

  • 产品概述和目标用户
  • 结构化的用户故事
  • 功能和非功能需求
  • MVP范围定义
  • 验收标准

🏗️ 第三步：架构设计阶段 ​

3.1 自动切换到架构模式 ​

PRD完成后，SOLO会自动调用architect子代理：

🤖 Architect: 基于PRD文档，我来设计技术架构和项目计划。

技术栈建议：
- 后端：Java Spring Boot 3.x
- 安全：Spring Security + JWT
- 数据库：PostgreSQL
- 文档：OpenAPI 3.0
- 测试：JUnit 5 + TestContainers

是否接受这个技术选型？

3.2 查看架构设计结果 ​

bash
# 查看项目计划
cat .solo/docs/PROJECT_PLAN.md

# 查看技术决策记录
cat .solo/docs/DECISIONS.md

# 查看任务分解
grep "TASK" .solo/docs/PROJECT_PLAN.md

3.3 OpenAPI规范生成 ​

架构师会基于需求生成初始的OpenAPI规范：

yaml
# api-spec.yaml (示例)
openapi: 3.0.3
info:
  title: User Management API
  version: 1.0.0
  description: 统一用户认证和权限管理服务

paths:
  /api/v1/users:
    get:
      summary: 获取用户列表
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            default: 1
      responses:
        '200':
          description: 成功返回用户列表
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserListResponse'

components:
  schemas:
    UserListResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/User'
        pagination:
          $ref: '#/components/schemas/Pagination'

🛠️ 第四步：代码生成和TDD实现 ​

4.1 生成服务端代码骨架 ​

使用OpenAPI Generator生成初始代码：

bash
# Java Spring Boot 代码生成
openapi-generator generate \
  -i api-spec.yaml \
  -g spring \
  -o ./backend \
  --additional-properties=packageName=com.example.userapi

# 查看生成的代码结构
tree backend/src/main/java/

4.2 启动TDD实现阶段 ​

bash
# 切换到工程实现模式
/solo__switch engineer

# 或者让SOLO自动判断当前应该执行的阶段
/solo__switch

Engineer子代理会开始TDD循环：

🤖 Engineer: 准备开始TDD实现。当前任务：TASK001 - 实现用户注册功能

我将遵循RED-GREEN-REFACTOR循环：
1. RED: 编写失败的测试用例
2. GREEN: 编写最小代码使测试通过
3. REFACTOR: 重构代码提升质量

开始编写用户注册的测试用例...

4.3 体验TDD循环 ​

java
// 示例：RED阶段 - 编写失败的测试
@Test
void shouldRegisterNewUser() {
    // Given
    RegisterRequest request = new RegisterRequest("john@example.com", "password123");
    
    // When
    RegisterResponse response = userService.register(request);
    
    // Then
    assertThat(response.isSuccess()).isTrue();
    assertThat(response.getUserId()).isNotNull();
}

// GREEN阶段 - 最小实现
public RegisterResponse register(RegisterRequest request) {
    // 最简单的实现使测试通过
    return new RegisterResponse(true, UUID.randomUUID().toString());
}

// REFACTOR阶段 - 完善实现
public RegisterResponse register(RegisterRequest request) {
    validateRequest(request);
    
    User user = User.builder()
        .email(request.getEmail())
        .password(passwordEncoder.encode(request.getPassword()))
        .createdAt(Instant.now())
        .build();
    
    User savedUser = userRepository.save(user);
    
    return new RegisterResponse(true, savedUser.getId());
}

🧪 第五步：质量保证阶段 ​

5.1 切换到QA模式 ​

功能实现完成后：

bash
# 切换到质量保证模式
/solo__switch qa

5.2 体验全面测试 ​

QA Engineer会设计全面的测试策略：

🤖 QA Engineer: 开始质量保证流程

测试计划：
1. 单元测试覆盖率检查 (目标 >80%)
2. 集成测试验证
3. API契约测试
4. 安全测试
5. 性能测试

正在分析测试覆盖率...

5.3 查看测试报告 ​

bash
# 查看测试报告
cat .solo/reports/tests/TEST_TASK001.md

# 查看覆盖率汇总
cat .solo/reports/tests/coverage-summary.md

📊 第六步：项目状态管理 ​

6.1 查看项目整体状态 ​

bash
# 检查项目状态
/solo__status

输出示例：

# SOLO 项目状态报告

## 项目概览
- 项目名称: 用户管理API系统
- 当前阶段: QA
- 整体进度: 75%

## 文档状态
- ✅ .solo/docs/PRD.md (完整)
- ✅ .solo/docs/PROJECT_PLAN.md (完整)
- ✅ .solo/docs/DECISIONS.md (完整)

## 任务进度
- 总任务: 8
- 已完成: 6 (75%)
- 进行中: 1
- 待处理: 1

## 测试状态
- 测试覆盖率: 85%
- 通过测试: 24
- 失败测试: 0

## 下一步建议
- 完成最后的性能测试
- 准备生产环境部署配置

6.2 恢复中断的工作 ​

如果工作被中断，可以智能恢复：

bash
# 恢复中断的工作
/solo__resume

# 指定恢复特定任务
/solo__resume TASK007

🎯 第七步：与现有工具集成 ​

7.1 集成OpenAPI文档 ​

bash
# 使用Redocly生成文档
npx @redocly/cli build-docs api-spec.yaml

# 启动Swagger UI
npx swagger-ui-serve api-spec.yaml

7.2 集成CI/CD流程 ​

yaml
# .github/workflows/api-pipeline.yml
name: API Pipeline

on: [push, pull_request]

jobs:
  solo-quality-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Check SOLO Status
        run: |
          # 检查SOLO项目状态
          /solo__status
          
      - name: Run Tests
        run: |
          mvn test
          
      - name: Generate OpenAPI Docs
        run: |
          npx @redocly/cli build-docs api-spec.yaml

🏆 完成检查清单 ​

确认您已经完成以下步骤：

  • [ ] ✅ 成功启动SOLO项目
  • [ ] ✅ 完成需求分析，生成PRD文档
  • [ ] ✅ 完成架构设计，生成项目计划
  • [ ] ✅ 体验TDD实现流程
  • [ ] ✅ 完成质量保证检查
  • [ ] ✅ 学会使用SOLO状态管理命令
  • [ ] ✅ 了解与现有工具的集成方式

🚀 下一步学习 ​

深入学习 ​

高级主题 ​

技术栈专用快速开始 ​

💡 小贴士 ​

新手建议 ​

  1. 从小项目开始: 先在简单项目中体验完整流程
  2. 逐步采用: 可以只使用SOLO的部分阶段
  3. 保持文档同步: 及时更新PRD和项目计划
  4. 重视测试: TDD是SOLO成功的关键

团队协作 ​

  1. 角色明确: 让团队成员了解各自在SOLO中的角色
  2. 定期同步: 使用 /solo__status 定期检查项目状态
  3. 版本控制: 将 .solo/docs/ 纳入Git管理
  4. 持续改进: 根据实践经验优化SOLO流程

🎉 恭喜！ 您已经掌握了SOLO工作模式的基础使用。SOLO将帮助您构建更高质量、更可维护的API项目。

有问题？查看 故障排除指南 或联系团队获取支持。

SOLO Development Guide

Copyright © 2024 Team