SOLO系统安装指引

完整的Claude Code SOLO工作模式安装和配置指南

📋 安装前准备

环境要求

Claude Code: 最新版本 (安装指引)
操作系统: macOS, Linux, Windows
Node.js: 16+ (用于team-docs文档系统)

文件结构概览

claude-settings/                    # SOLO系统配置根目录
├── commands/                      # 斜杠命令配置
│   ├── solo.md                   # 🎯 智能主工作流
│   ├── solo__status.md           # 📊 多维度状态分析
│   ├── solo__switch.md           # 🎛️ 智能模式切换
│   └── solo__resume.md           # 🚑 中断恢复专家
├── agents/                       # 子代理配置
│   ├── product-manager.md        # 👨‍💼 产品需求分析
│   ├── architect.md              # 🏗️ 技术架构设计
│   ├── engineer.md               # 👨‍💻 TDD代码实现
│   ├── qa-engineer.md            # 👨‍🔬 质量保证测试
│   ├── general-purpose.md        # 🤖 通用任务协调
│   ├── data-scientist.md         # 📊 数据分析洞察
│   ├── code-reviewer.md          # 🔍 代码质量审查
│   └── debugger.md               # 🐛 问题诊断修复
└── SOLO_FILE_STRUCTURE.md        # 📋 项目文件结构说明

🚀 快速安装

方法一：一键安装（推荐）

全局安装项目安装Windows PowerShell

bash

# 复制完整配置到Claude Code全局目录
cp -r claude-settings/ ~/.claude/

# 验证安装
/solo
/agents

bash

# 复制到当前项目目录
cp -r claude-settings/ .claude/

# 验证安装
/solo
/agents

bash

# Windows用户使用PowerShell
Copy-Item -Recurse claude-settings\ $env:USERPROFILE\.claude\

# 验证安装
/solo
/agents

方法二：选择性安装

核心功能增强功能专业功能

bash

# 仅安装核心SOLO命令和代理
mkdir -p ~/.claude/commands ~/.claude/agents

# 核心命令
cp claude-settings/commands/solo.md ~/.claude/commands/

# 核心代理（SOLO四阶段）
cp claude-settings/agents/{product-manager,architect,engineer,qa-engineer}.md ~/.claude/agents/

bash

# 添加增强功能命令
cp claude-settings/commands/solo__*.md ~/.claude/commands/

# 添加支持代理
cp claude-settings/agents/{general-purpose,code-reviewer,debugger}.md ~/.claude/agents/

bash

# 添加专业分析功能
cp claude-settings/agents/data-scientist.md ~/.claude/agents/

⚙️ 配置管理

安装位置优先级

Claude Code按以下优先级查找配置：

配置策略建议

使用场景	推荐位置	优势
个人开发	`~/.claude/`	全局可用，一次配置处处使用
团队项目	`.claude/`	项目专用，团队配置一致
实验测试	`.claude/`	隔离测试，不影响其他项目

权限配置

每个agent可配置不同的工具权限：

基础权限增强权限完整权限

yaml

---
name: product-manager
tools: Read, Write, Edit, Grep, Glob, TodoWrite
---

yaml

---
name: engineer  
tools: Read, Write, Edit, MultiEdit, Bash, Grep, Glob, TodoWrite
---

yaml

---
name: general-purpose
tools: Read, Write, Edit, MultiEdit, Bash, Grep, Glob, LS, WebFetch, WebSearch, TodoWrite, Task
---

✅ 安装验证

1. 验证Commands安装

bash

# 测试主要命令
/solo                    # 应显示智能工作模式启动界面
/solo__status           # 应显示状态分析选项
/solo__switch          # 应显示模式切换选项
/solo__resume          # 应显示恢复模式选项

期望输出示例：

🎯 SOLO 智能工作模式
智能识别当前项目状态，继续或启动SOLO工作流程。

当前任务：
我将首先分析当前项目状态，然后智能决定下一步行动...

2. 验证Agents安装

bash

# 查看已安装的agents
/agents

# 应该看到以下agents列表：
# ✅ product-manager - 产品需求分析专家
# ✅ architect - 技术架构设计专家  
# ✅ engineer - TDD实现专家
# ✅ qa-engineer - 质量保证专家
# ✅ general-purpose - 通用任务协调专家
# ✅ data-scientist - 数据分析专家
# ✅ code-reviewer - 代码审查专家
# ✅ debugger - 问题诊断专家

3. 功能完整性测试

完整测试流程

创建一个测试项目来验证SOLO系统是否正常工作：

bash

# 1. 创建测试目录
mkdir solo-test && cd solo-test

# 2. 启动SOLO工作流
/solo "创建一个简单的用户注册API"

# 3. 检查生成的文件结构
ls -la .solo/

# 4. 验证状态检查
/solo__status brief

🔧 高级配置

自定义Agent权限

编辑对应的agent文件修改权限：

yaml

# ~/.claude/agents/engineer.md
---
name: engineer
description: TDD工程师专家，负责高质量代码实现
tools: Read, Write, Edit, MultiEdit, Bash, Grep, Glob, TodoWrite
---

自定义Command参数

修改command文件的参数提示：

yaml

# ~/.claude/commands/solo.md
---
allowed-tools: Task, TodoWrite, Read, Grep, Glob, LS
description: 启用SOLO工作模式，智能识别项目状态并继续执行
argument-hint: [产品描述] - 可选的初始产品描述
---

团队共享配置

Git管理符号链接

bash

# 在团队仓库中保持配置
git add claude-settings/
git commit -m "Add SOLO system configuration"

# 团队成员同步配置
git pull
cp -r claude-settings/ ~/.claude/

bash

# 创建符号链接共享配置
ln -s $(pwd)/claude-settings ~/.claude/shared-solo

# 在项目中使用共享配置
ln -s ~/.claude/shared-solo .claude

🚨 常见问题解决

问题1：命令不可用

点击查看解决方案

症状: 输入/solo后没有响应或提示命令不存在

诊断步骤:

bash

# 1. 检查文件是否存在
ls ~/.claude/commands/solo*.md
ls .claude/commands/solo*.md

# 2. 检查文件权限
chmod 644 ~/.claude/commands/*.md
chmod 644 ~/.claude/agents/*.md

# 3. 检查文件格式
head -10 ~/.claude/commands/solo.md

解决方案:

确保文件路径正确
验证文件包含正确的YAML头部
重启Claude Code会话

问题2：Agent无法调用

点击查看解决方案

症状: 系统提示找不到指定的agent

诊断步骤:

bash

# 1. 验证agent文件
/agents
head -10 ~/.claude/agents/product-manager.md

# 2. 检查YAML格式
# 确认文件包含正确的头部：
# ---
# name: product-manager
# description: ...
# tools: ...
# ---

解决方案:

检查agent文件的YAML头部格式
确保name字段与文件名匹配
验证tools字段的权限设置

问题3：权限不足

点击查看解决方案

症状: Agent运行时提示工具权限不足

解决方案:

bash

# 检查agent配置中的tools字段
grep -A 5 "tools:" ~/.claude/agents/engineer.md

# 根据需要添加权限，例如：
# tools: Read, Write, Edit, MultiEdit, Bash, Grep, Glob, TodoWrite

🌍 不同环境安装

开发环境 vs 生产环境

开发环境生产环境

bash

# 开发环境使用项目目录，便于测试和调试
mkdir -p .claude/commands .claude/agents
cp claude-settings/commands/* .claude/commands/
cp claude-settings/agents/* .claude/agents/

# 开启调试模式
export CLAUDE_DEBUG=true

bash

# 生产环境使用用户目录，稳定可靠
mkdir -p ~/.claude/commands ~/.claude/agents
cp claude-settings/commands/* ~/.claude/commands/
cp claude-settings/agents/* ~/.claude/agents/

# 设置只读权限
chmod 444 ~/.claude/commands/*.md
chmod 444 ~/.claude/agents/*.md

Docker环境

Dockerfiledocker-compose.yml

dockerfile

FROM node:18-alpine

# 安装Claude Code SOLO系统
COPY claude-settings/ /root/.claude/

# 设置工作目录
WORKDIR /workspace

# 验证安装
RUN /solo --version

yaml

version: '3.8'
services:
  solo-dev:
    build: .
    volumes:
      - .:/workspace
      - ./claude-settings:/root/.claude
    environment:
      - CLAUDE_DEBUG=true

📈 安装后优化

性能优化

bash

# 清理临时文件
find .solo/tmp/ -type f -mtime +7 -delete

# 压缩历史上下文
gzip .solo/contexts/CONTEXT_*.md

# 定期备份配置
cp -r ~/.claude ~/.claude.backup.$(date +%Y%m%d)

监控和维护

定期维护建议

每周: 运行 /solo__status diagnose 检查系统健康
每月: 更新到最新版本的配置文件
每季度: 清理过期的上下文和报告文件

🔄 升级指南

检查版本

bash

# 查看当前配置版本信息
grep -r "version\|date" claude-settings/agents/

# 对比官方最新版本
curl -s https://api.github.com/repos/your-repo/releases/latest | jq .tag_name

安全升级

bash

# 1. 备份现有配置
cp -r ~/.claude ~/.claude.backup.$(date +%Y%m%d)

# 2. 下载最新版本
git pull origin main

# 3. 安装新版本
cp -r claude-settings/* ~/.claude/

# 4. 验证升级结果
/solo__status
/agents

✅ 安装检查清单

基础安装验证

[ ] /solo 命令可用且响应正常
[ ] 4个核心agents可以被调用
[ ] .solo/ 目录结构可以正确创建
[ ] PRD.md 文档可以正确生成

功能完整性验证

[ ] /solo__status 提供多种视图选项
[ ] /solo__switch 支持安全模式切换
[ ] /solo__resume 可以智能恢复工作
[ ] 所有8个agents均可独立工作

集成测试验证

[ ] 完整SOLO工作流可以端到端执行
[ ] TDD循环可以正常运行
[ ] 质量门控检查正常工作
[ ] 状态报告生成完整

📞 获取帮助

自助诊断

bash

# Claude Code内置帮助
/help

# SOLO系统状态诊断
/solo__status diagnose

# 查看详细配置
/config

技术支持

文档中心: 使用指南 | 故障排除
示例项目: SOLO案例
社区支持: GitHub Issues | 开发者论坛

🎉 安装完成

恭喜！您已成功安装Claude Code SOLO系统。立即开始您的第一个SOLO项目：/solo "创建一个待办事项API"

SOLO系统安装指引 ​

📋 安装前准备 ​

环境要求 ​

文件结构概览 ​

🚀 快速安装 ​

方法一：一键安装（推荐） ​

方法二：选择性安装 ​

⚙️ 配置管理 ​

安装位置优先级 ​

配置策略建议 ​

权限配置 ​

✅ 安装验证 ​

1. 验证Commands安装 ​

2. 验证Agents安装 ​

3. 功能完整性测试 ​

🔧 高级配置 ​

自定义Agent权限 ​

自定义Command参数 ​

团队共享配置 ​

🚨 常见问题解决 ​

问题1：命令不可用 ​

问题2：Agent无法调用 ​

问题3：权限不足 ​

🌍 不同环境安装 ​

开发环境 vs 生产环境 ​

Docker环境 ​

📈 安装后优化 ​

性能优化 ​

监控和维护 ​

🔄 升级指南 ​

检查版本 ​

安全升级 ​

✅ 安装检查清单 ​

基础安装验证 ​

功能完整性验证 ​

集成测试验证 ​

📞 获取帮助 ​

自助诊断 ​

技术支持 ​

SOLO系统安装指引

📋 安装前准备

环境要求

文件结构概览

🚀 快速安装

方法一：一键安装（推荐）

方法二：选择性安装

⚙️ 配置管理

安装位置优先级

配置策略建议

权限配置

✅ 安装验证

1. 验证Commands安装

2. 验证Agents安装

3. 功能完整性测试

🔧 高级配置

自定义Agent权限

自定义Command参数

团队共享配置

🚨 常见问题解决

问题1：命令不可用

问题2：Agent无法调用

问题3：权限不足

🌍 不同环境安装

开发环境 vs 生产环境

Docker环境

📈 安装后优化

性能优化

监控和维护

🔄 升级指南

检查版本

安全升级

✅ 安装检查清单

基础安装验证

功能完整性验证

集成测试验证

📞 获取帮助

自助诊断

技术支持