最佳实践

本文档汇总了 Claude Code SOLO 系统的最佳实践和专业建议，帮助团队最大化开发效率和代码质量。

工作流最佳实践

1. SOLO 四阶段最佳实践

PRODUCT 阶段 - 需求分析

# ✅ 推荐做法
/solo "用户管理系统：支持注册、登录、权限管理，需要支持 1000+ 并发用户"

# ❌ 避免
/solo "做一个系统"  # 描述过于模糊

最佳实践：

• 🎯 明确业务场景：详细描述用户故事和使用场景
• 📊 量化需求：明确性能指标、用户规模、响应时间要求
• 🔄 渐进式细化：先整体后局部，逐步细化需求
• 📝 文档驱动：确保 PRD 完整且可追溯

质量检查清单：

✅ 用户故事完整且可测试
✅ 非功能性需求明确
✅ 技术约束和限制清楚
✅ 验收标准可量化
✅ 风险和假设已识别

ARCHITECT 阶段 - 架构设计

# 检查架构设计完整性
/solo__status detailed --phase=architect

最佳实践：

• 🏗️ 分层架构：清晰的表现层、业务层、数据层分离
• 🔌 接口优先：先定义 API 接口再实现
• 📐 SOLID 原则：遵循面向对象设计原则
• 🔄 可扩展性：考虑未来扩展和性能优化
• 📊 技术选型：基于需求和团队技能选择合适的技术栈

架构文档模板：

# 系统架构设计

## 1. 架构概述
- 整体架构风格：分层架构 / 微服务 / 六边形架构
- 核心技术栈：Java + Spring Boot + PostgreSQL
- 部署方式：Docker + Kubernetes

## 2. API 设计
- RESTful API 设计规范
- OpenAPI 3.0 规范文件
- 版本管理策略

## 3. 数据库设计
- ER 图和表结构
- 索引策略
- 数据一致性保证

## 4. 安全设计
- 认证授权机制
- 数据加密策略
- 安全漏洞防护

ENGINEER 阶段 - TDD 实现

# 严格 TDD 模式
/solo__switch engineer --tdd-mode=strict

TDD 最佳实践：

• 🔴 RED：先写失败的测试，明确要实现的功能
• 🟢 GREEN：写最简单的代码让测试通过
• 🔄 REFACTOR：重构代码，保持测试通过

代码质量标准：

# 测试覆盖率要求
coverage_threshold: 80%

# 静态分析标准
sonarqube_quality_gate: passed
checkstyle_violations: 0
findbugs_violations: 0

# 性能基准
response_time_p95: < 500ms
memory_usage: < 512MB

QA 阶段 - 质量保证

测试策略分层：

E2E 测试 (10%)     ← 用户旅程和关键业务流程
集成测试 (20%)     ← 模块间接口和数据流
单元测试 (70%)     ← 业务逻辑和边界条件

2. 阶段切换策略

智能切换判断

# 检查切换条件
/solo__switch architect --dry-run

# 有风险时的处理
/solo__switch architect --assess-risk

切换时机判断：

• ✅ PRODUCT → ARCHITECT：PRD 完整、需求澄清、验收标准明确
• ✅ ARCHITECT → ENGINEER：架构设计完成、API 定义清晰、数据库设计完整
• ✅ ENGINEER → QA：核心功能实现、单元测试通过、集成测试就绪
• ✅ QA → 交付：所有测试通过、性能达标、文档完整

团队协作最佳实践

1. 配置管理

项目标准化配置

// .solo/config/team-standards.json
{
  "codeStyle": {
    "formatter": "prettier",
    "linter": "eslint",
    "indentation": "2-spaces"
  },
  "testing": {
    "framework": "jest",
    "coverageThreshold": 80,
    "e2eFramework": "playwright"
  },
  "git": {
    "conventionalCommits": true,
    "branchNaming": "feature/TASK-123-short-description",
    "requirePR": true
  }
}

团队共享配置

# 共享命令和代理配置
git add claude-settings/
git commit -m "feat: add shared SOLO configuration"

# 个人配置排除
echo ".solo/.solo-metadata.json" >> .gitignore
echo ".solo/contexts/" >> .gitignore

2. 代码审查集成

自动化质量检查

# .github/workflows/solo-quality.yml
name: SOLO Quality Check
on:
  pull_request:
    branches: [main, develop]

jobs:
  quality-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: SOLO Architecture Review
        run: |
          # 检查架构决策记录
          test -f .solo/docs/DECISIONS.md
          
          # 验证 API 设计一致性
          npm run api-lint
          
          # 检查测试覆盖率
          npm run test:coverage
          
      - name: Generate SOLO Report
        run: |
          /solo__status detailed --export=github-comment > solo-report.md
          
      - name: Comment PR
        uses: actions/github-script@v6
        with:
          script: |
            const fs = require('fs');
            const report = fs.readFileSync('solo-report.md', 'utf8');
            github.rest.issues.createComment({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body: report
            });

3. 知识管理

决策记录管理

# .solo/docs/DECISIONS.md

## ADR-001: 选择 Spring Boot 框架
**日期**: 2024-01-15
**状态**: 已采纳
**决策**: 使用 Spring Boot 2.7.x 作为后端框架
**理由**: 
- 团队熟悉度高
- 生态成熟
- 支持微服务架构
**影响**: 
- 开发效率提升 30%
- 学习成本降低
- 长期维护成本可控

## ADR-002: API-First 开发方式
**日期**: 2024-01-16  
**状态**: 已采纳
**决策**: 采用 OpenAPI 3.0 规范，先设计 API 再实现
**理由**:
- 前后端并行开发
- 接口文档自动生成
- 测试用例自动化

性能优化最佳实践

1. 代理性能优化

并发控制

// .solo/config/performance.json
{
  "agents": {
    "concurrency": {
      "maxParallel": 2,
      "timeoutMs": 60000,
      "retryAttempts": 3
    },
    "caching": {
      "enabled": true,
      "ttlSeconds": 3600,
      "maxSizeMB": 100
    }
  }
}

上下文管理

# 定期清理上下文
find .solo/contexts -name "*.json" -mtime +7 -delete

# 压缩历史上下文
tar -czf .solo/archives/contexts-$(date +%Y%m).tar.gz .solo/contexts/
rm -rf .solo/contexts/old/

2. 工作区优化

文件组织

.solo/
├── docs/                    # 核心文档（版本控制）
│   ├── PRD.md
│   ├── PROJECT_PLAN.md
│   └── DECISIONS.md
├── contexts/                # 工作上下文（本地）
│   ├── current-session.json
│   └── agent-states/
├── cache/                   # 缓存数据（临时）
│   ├── api-responses/
│   └── code-analysis/
└── archives/                # 历史数据（备份）
    ├── completed-phases/
    └── old-contexts/

磁盘空间管理

# 自动清理脚本
#!/bin/bash
# cleanup-solo.sh

# 清理超过 30 天的缓存
find .solo/cache -type f -mtime +30 -delete

# 压缩超过 7 天的上下文
find .solo/contexts -name "*.json" -mtime +7 -exec gzip {} \;

# 移动超过 30 天的压缩文件到归档
find .solo/contexts -name "*.gz" -mtime +30 -exec mv {} .solo/archives/ \;

echo "SOLO workspace cleanup completed"

安全最佳实践

1. 敏感信息管理

环境变量使用

# .env (不提交到 Git)
DATABASE_PASSWORD=secure-password
API_KEY=your-api-key
JWT_SECRET=random-secret-key

# docker-compose.yml
version: '3.8'
services:
  app:
    environment:
      - DATABASE_PASSWORD=${DATABASE_PASSWORD}
      - API_KEY=${API_KEY}
      - JWT_SECRET=${JWT_SECRET}

配置文件加密

# 加密敏感配置
gpg --symmetric --cipher-algo AES256 .solo/config/secrets.json

# 解密使用
gpg --decrypt .solo/config/secrets.json.gpg > .solo/config/secrets.json

2. 代理权限控制

最小权限原则

// claude-settings/agents/engineer.md
{
  "allowed-tools": [
    "Read", "Write", "Edit", "MultiEdit", 
    "Bash", "Grep", "Glob", "TodoWrite"
  ],
  "restricted-commands": [
    "rm -rf", "sudo", "curl", "wget"
  ],
  "file-access-patterns": [
    "src/**/*.java",
    "test/**/*.java", 
    "pom.xml",
    "*.properties"
  ]
}

审计日志

# 启用操作日志
claude config set audit.enabled true
claude config set audit.logFile ".solo/logs/audit.log"

# 查看操作历史
tail -f .solo/logs/audit.log | jq '.timestamp, .agent, .action, .files[]'

代码质量最佳实践

1. 测试策略

测试分层实现

// 单元测试 - 业务逻辑
@Test
void shouldCalculateUserAgeCorrectly() {
    // Given
    User user = new User("2000-01-01");
    
    // When  
    int age = userService.calculateAge(user);
    
    // Then
    assertThat(age).isEqualTo(24);
}

// 集成测试 - 数据库交互
@SpringBootTest
@Transactional
class UserRepositoryIntegrationTest {
    
    @Test
    void shouldSaveAndRetrieveUser() {
        // 测试数据库操作
    }
}

// E2E 测试 - 完整用户旅程
@Test
void shouldCompleteUserRegistrationFlow() {
    // 模拟完整的用户注册流程
}

测试数据管理

# test-data.yml
users:
  - id: 1
    username: "test-user"
    email: "test@example.com"
    role: "USER"
  - id: 2
    username: "admin-user"
    email: "admin@example.com"
    role: "ADMIN"

scenarios:
  registration:
    valid-user:
      username: "new-user"
      email: "new@example.com"
      password: "SecurePass123!"
    invalid-email:
      username: "invalid-user"
      email: "invalid-email"
      password: "SecurePass123!"

2. 代码审查清单

自动化检查

# pre-commit hook
#!/bin/sh
# .git/hooks/pre-commit

# 运行 SOLO 质量检查
/solo__status brief --exit-on-failure

# 运行静态分析
npm run lint
npm run type-check

# 运行测试
npm run test:unit
npm run test:integration

# 检查测试覆盖率
npm run test:coverage -- --threshold=80

人工检查清单

## 代码审查清单

### 架构和设计
- [ ] 代码符合架构设计文档
- [ ] API 接口与 OpenAPI 规范一致
- [ ] 数据库变更有对应的迁移脚本
- [ ] 新增的依赖已在架构决策中记录

### 代码质量
- [ ] 代码遵循团队编码规范
- [ ] 方法和类的职责单一且清晰
- [ ] 错误处理完整且合理
- [ ] 没有硬编码的配置和密钥

### 测试质量
- [ ] 测试覆盖率达到 80% 以上
- [ ] 测试用例覆盖正常和异常场景
- [ ] 集成测试验证模块间交互
- [ ] E2E 测试覆盖关键用户流程

### 安全性
- [ ] 输入验证和输出编码
- [ ] 认证授权正确实现
- [ ] 敏感信息正确处理
- [ ] SQL 注入和 XSS 防护

### 可维护性
- [ ] 代码注释清晰且必要
- [ ] 变量和方法命名有意义
- [ ] 复杂逻辑有充分的文档
- [ ] 配置参数化且可配置

监控和运维最佳实践

1. 应用监控

健康检查端点

@RestController
public class HealthController {
    
    @GetMapping("/health")
    public ResponseEntity<Map<String, String>> health() {
        Map<String, String> status = new HashMap<>();
        status.put("status", "UP");
        status.put("timestamp", Instant.now().toString());
        status.put("version", getClass().getPackage().getImplementationVersion());
        return ResponseEntity.ok(status);
    }
    
    @GetMapping("/health/detailed")
    public ResponseEntity<Map<String, Object>> detailedHealth() {
        // 检查数据库连接、外部服务等
        return ResponseEntity.ok(healthCheckService.getDetailedStatus());
    }
}

指标收集

# application.yml
management:
  endpoints:
    web:
      exposure:
        include: health,info,metrics,prometheus
  metrics:
    export:
      prometheus:
        enabled: true
  endpoint:
    health:
      show-details: always

2. 日志管理

结构化日志

// 使用 SLF4J + Logback
private static final Logger logger = LoggerFactory.getLogger(UserService.class);

public User createUser(CreateUserRequest request) {
    logger.info("Creating user: username={}, email={}", 
                request.getUsername(), request.getEmail());
    
    try {
        User user = userRepository.save(buildUser(request));
        logger.info("User created successfully: id={}, username={}", 
                    user.getId(), user.getUsername());
        return user;
    } catch (Exception e) {
        logger.error("Failed to create user: username={}, error={}", 
                     request.getUsername(), e.getMessage(), e);
        throw new UserCreationException("Failed to create user", e);
    }
}

日志配置

<!-- logback-spring.xml -->
<configuration>
    <springProfile name="production">
        <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
            <encoder class="net.logstash.logback.encoder.LogstashEncoder">
                <includeContext>true</includeContext>
                <includeMdc>true</includeMdc>
            </encoder>
        </appender>
    </springProfile>
    
    <logger name="com.example" level="INFO"/>
    <logger name="org.springframework.web" level="INFO"/>
    <logger name="org.springframework.security" level="DEBUG"/>
    
    <root level="INFO">
        <appender-ref ref="STDOUT"/>
    </root>
</configuration>

持续改进最佳实践

1. 度量和分析

SOLO 效率指标

# 生成效率报告
/solo__status analytics --period=last-month

# 输出示例
📊 SOLO 效率分析报告 (2024-01-01 to 2024-01-31)
══════════════════════════════════════════════════

🚀 项目交付情况:
- 完成项目: 12 个
- 平均开发周期: 5.2 天 (↓15% vs 上月)
- 平均代码质量评分: 4.7/5.0 (↑8% vs 上月)

⏱️ 阶段效率分析:
- PRODUCT 阶段: 平均 0.8 天 (目标 1.0 天) ✅
- ARCHITECT 阶段: 平均 1.2 天 (目标 1.5 天) ✅
- ENGINEER 阶段: 平均 2.8 天 (目标 3.0 天) ✅
- QA 阶段: 平均 0.4 天 (目标 0.5 天) ✅

🐛 质量指标:
- 生产环境 bug 率: 0.8% (↓40% vs 上月)
- 测试覆盖率: 87.3% (↑5% vs 上月)  
- 代码审查通过率: 94.2%

🔄 流程优化建议:
1. ARCHITECT 阶段可进一步优化 API 设计模板
2. 增加 E2E 测试覆盖率到 15%
3. 引入更多自动化代码生成

2. 团队能力建设

技能矩阵管理

# 团队技能矩阵

| 成员   | SOLO流程 | TDD实践 | API设计 | 架构设计 | 代码审查 |
|--------|----------|---------|---------|----------|----------|
| Alice  | ⭐⭐⭐⭐⭐  | ⭐⭐⭐⭐    | ⭐⭐⭐⭐⭐   | ⭐⭐⭐      | ⭐⭐⭐⭐    |
| Bob    | ⭐⭐⭐     | ⭐⭐⭐⭐⭐   | ⭐⭐⭐     | ⭐⭐⭐⭐⭐   | ⭐⭐⭐     |
| Carol  | ⭐⭐⭐⭐    | ⭐⭐⭐     | ⭐⭐⭐⭐    | ⭐⭐       | ⭐⭐⭐⭐⭐   |

培训计划:
- Bob: API 设计最佳实践培训
- Carol: 系统架构设计进阶
- 全员: 高级 TDD 技巧工作坊

知识分享机制

# 每周技术分享
/solo__status export --format=tech-share > weekly-learnings.md

# 季度最佳实践总结
/solo__status best-practices --period=quarter > quarterly-practices.md

# 案例库建设
/solo__status case-study --success-only > success-cases.md

3. 工具链优化

自定义命令开发

# 创建项目特定的命令
cat > claude-settings/commands/deploy.md << 'EOF'
# 部署命令

自动化部署到测试和生产环境。

## 使用方法

/deploy [environment] [--dry-run]

## 参数
- environment: target, production
- --dry-run: 预演模式，不实际执行部署

## 工作流程
1. 检查当前分支和代码状态
2. 运行完整测试套件
3. 构建应用镜像
4. 执行滚动更新部署
5. 验证部署结果
6. 发送通知

EOF

集成工具定制

// .solo/config/integrations.json
{
  "slack": {
    "webhook": "${SLACK_WEBHOOK_URL}",
    "channels": {
      "development": "#dev-notifications",
      "deployment": "#deployment-alerts",
      "quality": "#code-quality"
    },
    "notifications": {
      "phaseComplete": true,
      "qualityIssues": true,
      "deploymentStatus": true
    }
  },
  "jira": {
    "server": "${JIRA_SERVER_URL}",
    "project": "PROJ",
    "issueTracking": {
      "autoLink": true,
      "statusSync": true,
      "timeTracking": true
    }
  }
}

---

总结

通过遵循这些最佳实践，团队可以：

1. 提高开发效率 - 标准化的流程和自动化工具
2. 保证代码质量 - 严格的 TDD 实践和多层测试策略
3. 增强团队协作 - 清晰的配置管理和知识分享机制
4. 持续改进优化 - 基于数据的度量和反馈循环

记住，最佳实践需要根据团队的具体情况进行调整和优化。定期回顾和更新这些实践，确保它们始终能够为团队创造价值。