1. 系统要求与环境准备
1.1 硬件与软件要求
💻 操作系统
- macOS 13.0+ (Ventura 或更高)
- Windows 10 1809+ 或 Windows Server 2019+
- Ubuntu 20.04+, Debian 10+
- Alpine Linux 3.19+
- WSL 1/2 (Windows Subsystem for Linux)
🧠 硬件配置
- 内存：最低 4GB RAM，推荐 8GB+
- CPU：双核 2.0GHz+
- 磁盘：约 500MB 可用空间
- 网络：稳定互联网连接（必需）
🛠️ 必需软件
- Shell: Bash, Zsh, PowerShell, 或 CMD
- Windows: Git for Windows（必需）
- ripgrep: 通常已包含（搜索功能需要）
- Node.js 18+（仅 npm 安装需要）
🌍 地区限制
- 仅限 Anthropic 支持的国家/地区
- 中国大陆用户需使用合规 API 代理
- 支持第三方 API 提供商（Bedrock/Vertex AI）
1.2 环境诊断命令
# ===== 系统检查 =====
# 1. 检查操作系统版本
# macOS:
sw_vers
# Linux:
cat /etc/os-release
# Windows:
systeminfo | findstr /B /C:"OS Name" /C:"OS Version"
# 2. 检查内存
free -h
# Windows:
wmic OS get FreePhysicalMemory,TotalVisibleMemorySize
# 3. 检查磁盘空间
df -h ~
# 4. 检查 Shell 类型
echo $SHELL
# 5. 检查网络连接
curl -I https://claude.ai
curl -I https://api.anthropic.com
# ===== Windows 额外检查 =====
# 6. 检查 Git for Windows
git --version
# 7. 检查 WSL（如使用）
wsl --list --verbose
# 8. 检查 PowerShell 版本
$PSVersionTable.PSVersion
💡 重要提示：
Claude Code 需要稳定的互联网连接来访问 Anthropic API。中国大陆用户建议使用以下方案之一：
- 方案 A：使用合规的 API 中转服务（如 SiliconFlow、Z.ai 等）
- 方案 B：配置 HTTP/HTTPS 代理
- 方案 C：使用第三方云服务商（Amazon Bedrock、Google Vertex AI、Microsoft Foundry）
2. 安装方式选择与对比
2.1 四种安装方式对比
| 安装方式 | 适用平台 | 优点 | 缺点 | 推荐度 |
|---|---|---|---|---|
| 原生安装 | macOS/Linux/Windows | 最快、自动更新、无需依赖 | 需要管理员权限 | ⭐⭐⭐⭐⭐ |
| Homebrew | macOS/Linux | 包管理统一、易卸载 | 不自动更新、需要 Homebrew | ⭐⭐⭐⭐ |
| WinGet | Windows | Windows 原生包管理 | 不自动更新、更新滞后 | ⭐⭐⭐⭐ |
| npm（已弃用） | 全平台 | 跨平台一致 | 需要 Node.js、慢、已弃用 | ⭐ |
✅ 推荐方案：
原生安装是官方推荐的方式，具有以下优势：
- ✓ 二进制文件直接执行，启动速度快
- ✓ 后台自动更新，始终保持最新版本
- ✓ 无需 Node.js 等额外依赖
- ✓ 代码签名验证，安全性更高
3. 原生安装（推荐）
步骤 1：执行一键安装脚本
# ===== macOS / Linux / WSL =====
curl -fsSL https://claude.ai/install.sh | bash
# 安装完成后，重新加载 shell 配置
source ~/.bashrc
# 或
source ~/.zshrc
# ===== Windows PowerShell =====
irm https://claude.ai/install.ps1 | iex
# ===== Windows CMD =====
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd
# 安装位置：
# macOS/Linux: ~/.local/bin/claude
# Windows: %USERPROFILE%\.local\bin\claude.exe
步骤 2：验证安装
# 检查版本
claude --version
# 期望输出：claude-code 2.1.71
# 运行诊断检查
claude doctor
# 诊断输出示例：
✓ Claude Code binary found: ~/.local/bin/claude
✓ Version: 2.1.71
✓ ripgrep available
✓ Network connectivity: OK
✓ Shell configuration: OK
步骤 3：配置 PATH（如需要）
# 如果 claude 命令不可用，添加 PATH
# macOS/Linux (添加到 ~/.bashrc 或 ~/.zshrc):
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
# Windows PowerShell (添加到 $PROFILE):
$envPath = [Environment]::GetEnvironmentVariable("Path", "User")
$newPath = "$envPath;$env:USERPROFILE\.local\bin"
[Environment]::SetEnvironmentVariable("Path", $newPath, "User")
# 重启终端后验证
claude --version
步骤 4：安装特定版本（可选）
# 安装最新稳定版（延迟约 1 周，跳过有问题的版本）
curl -fsSL https://claude.ai/install.sh | bash -s stable
# 安装指定版本号
curl -fsSL https://claude.ai/install.sh | bash -s 2.1.50
# Windows PowerShell 安装稳定版
& ([scriptblock]::Create((irm https://claude.ai/install.ps1))) stable
4. Homebrew/WinGet 安装
4.1 macOS/Linux Homebrew 安装
# 安装 Homebrew（如未安装）
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
# 安装 Claude Code
brew install --cask claude-code
# 验证安装
claude --version
# 手动更新（Homebrew 不自动更新）
brew upgrade claude-code
# 清理旧版本释放空间
brew cleanup claude-code
4.2 Windows WinGet 安装
# 安装 WinGet（Windows 10 1809+ 已预装）
# 如未安装，从 Microsoft Store 获取"App Installer"
# 安装 Claude Code
winget install Anthropic.ClaudeCode
# 验证安装
claude --version
# 手动更新
winget upgrade Anthropic.ClaudeCode
4.3 从 npm 迁移到原生安装
⚠️ 注意：npm 安装方式已弃用。如果您之前使用 npm 安装，建议迁移到原生安装。
# 1. 先安装原生版本
curl -fsSL https://claude.ai/install.sh | bash
# 2. 卸载 npm 版本
npm uninstall -g @anthropic-ai/claude-code
# 或使用 claude 内置命令迁移
claude install
npm uninstall -g @anthropic-ai/claude-code
# 3. 验证迁移成功
claude --version
which claude
# 应指向 ~/.local/bin/claude 而非 node_modules
5. API 认证与账户配置
5.1 支持的账户类型
| 账户类型 | Claude Code 访问 | 价格 | 适用场景 |
|---|---|---|---|
| Claude Pro | ✅ 包含 | $20/月 | 个人开发者 |
| Claude Max | ✅ 包含 | $200/月 | 重度用户/专业开发者 |
| Teams | ✅ 包含 | $30/用户/月 | 小团队（2-50 人） |
| Enterprise | ✅ 包含 | 联系销售 | 大型企业 |
| API Console | ✅ 按量付费 | $3-15/1M tokens | 按使用量付费 |
| Free Plan | ❌ 不支持 | 免费 | 仅限 claude.ai 网页版 |
5.2 认证登录流程
# 1. 启动 Claude Code
cd /path/to/your/project
claude
# 2. 首次运行会自动打开浏览器进行 OAuth 认证
# 3. 登录您的 Claude 账户（Pro/Max/Teams/Enterprise）
# 4. 授权 Claude Code 访问权限
# 5. 认证成功后返回终端继续会话
# 认证令牌存储在：
# macOS/Linux: ~/.config/claude/tokens.json
# Windows: %APPDATA%\claude\tokens.json
5.3 使用 API Key 认证（Console 账户）
# 方法 1：环境变量
export ANTHROPIC_API_KEY="sk-ant-api03-xxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
claude
# 方法 2：配置文件 (~/.claude.json)
cat > ~/.claude.json << 'EOF'
{
"auth": {
"apiKey": "sk-ant-api03-xxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
},
"model": "claude-sonnet-4-20250514",
"maxTokens": 8192
}
EOF
# 方法 3：每次启动时传入
ANTHROPIC_API_KEY=sk-ant-api03-xxx claude
5.4 使用第三方 API 提供商
# Amazon Bedrock
export AWS_PROFILE=your-profile
export AWS_REGION=us-east-1
claude --model bedrock/anthropic.claude-3-5-sonnet-20241022-v2:0
# Google Vertex AI
export GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json
export CLOUD_ML_REGION=us-central1
claude --model vertex/claude-3-5-sonnet-v2@20241022
# Microsoft Foundry (Azure)
export AZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com/
export AZURE_OPENAI_API_KEY=your-azure-key
claude --model azure/claude-3-5-sonnet
# 国内 API 中转（如 SiliconFlow、Z.ai 等）
export ANTHROPIC_BASE_URL="https://api.siliconflow.cn/v1"
export ANTHROPIC_API_KEY="sk-xxxxxx"
claude --model deepseek-ai/DeepSeek-V3
5.5 多账户配置
# 创建多个配置文件
cat > ~/.claude.work.json << 'EOF'
{
"auth": { "apiKey": "sk-ant-work-xxx" },
"model": "claude-sonnet-4-20250514"
}
EOF
cat > ~/.claude.personal.json << 'EOF'
{
"auth": { "apiKey": "sk-ant-personal-xxx" },
"model": "claude-opus-4-20250514"
}
EOF
# 使用别名切换
alias claude-work='claude --config ~/.claude.work.json'
alias claude-personal='claude --config ~/.claude.personal.json'
6. 终端优化配置
6.1 VS Code 终端配置
// settings.json
{
"terminal.integrated.env.osx": {
"CLAUDE_CODE_EDITOR": "vscode"
},
// Option 键作为 Meta 键（用于 Alt+B/F 等快捷键）
"terminal.integrated.sendKeyBindingsToShell": true,
// 启用通知
"terminal.integrated.enableNotifications": true,
// 字体优化
"terminal.integrated.fontFamily": "JetBrains Mono, Fira Code, monospace",
"terminal.integrated.fontSize": 14,
"terminal.integrated.lineHeight": 1.5
}
6.2 iTerm2 配置（macOS）
# iTerm2 偏好设置 → Profiles → Keys
# Left Option 键：设置为 "+Esc"
# Right Option 键：设置为 "+Esc"
# 通知设置（Profiles → Terminal）
# ✓ Silence bell
# ✓ Show growl notifications
# ✓ Trigger for: Bell
# 外观优化（Profiles → Colors）
# 推荐使用 Solarized Dark 或 One Dark 配色
# 字体（Profiles → Text）
# Font: JetBrains Mono NL
# Size: 14
# Non-ASCII Font: Same
6.3 快捷键配置
# ~/.inputrc (Bash/Zsh 通用快捷键)
set editing-mode emacs
set show-all-if-ambiguous on
set completion-ignore-case on
set mark-modified-lines on
set colored-stats on
# Ctrl+左右箭头按单词移动
"\e[1;5C": forward-word
"\e[1;5D": backward-word
# Alt+左右箭头按单词移动
"\e[1;3C": forward-word
"\e[1;3D": backward-word
# 重新加载配置
bind -f ~/.inputrc
6.4 Claude Code 内置快捷键
| 快捷键 | 功能 | 说明 |
|---|---|---|
| Ctrl+C | 中断当前操作 | 停止正在执行的命令或生成 |
| Ctrl+D | 退出 Claude Code | 发送 EOF 信号结束会话 |
| Ctrl+G | 在编辑器中打开 | 用默认编辑器编辑当前提示 |
| Ctrl+R | 搜索历史 | 反向搜索之前的命令 |
| Ctrl+V | 粘贴图片 | 从剪贴板粘贴图像（iTerm2） |
| Alt+B/F | 前后移动单词 | 需要配置 Option 为 Meta 键 |
| Alt+Y | 循环替换 | 循环之前的删除内容 |
| ? | 显示帮助 | 查看当前环境可用的快捷键 |
7. 核心插件安装配置
7.1 插件市场概览
Claude Code 插件系统允许扩展核心功能，包括自定义命令、Agents、Skills 和工具集成。插件可以通过官方市场或 GitHub 仓库安装。
🔧 Git Workflow Plugin
官方推荐用途：完整的 Git 工作流自动化，包括提交、推送、PR 创建
- 智能提交消息生成（遵循 Conventional Commits）
- 自动代码审查和问题检测
- PR 描述自动生成
- 分支管理和合并冲突解决
# 安装
/plugin marketplace add git-workflow
# 使用示例
/git commit -m "feat: add user authentication"
/git pr create --title "Add auth" --reviewer @team
🏗️ Architecture Review Agent
企业级用途：代码架构评审和设计模式建议
- 代码库结构分析
- 设计模式识别和建议
- 技术债务评估
- 重构建议和优先级排序
# 安装
/plugin marketplace add architecture-review
# 使用示例
/arch review src/
/arch debt-analysis
/arch suggest-refactor --focus performance
🧪 Test Generator Plugin
热门用途：自动生成单元测试和集成测试
- 基于代码自动生成测试用例
- 边界条件和异常场景覆盖
- Mock 数据和 Fixture 生成
- 测试覆盖率分析和报告
# 安装
/plugin marketplace add test-generator
# 使用示例
/test generate src/services/user.service.ts
/test coverage report
/test fix --file tests/user.test.ts
🔒 Security Scanner Plugin
安全必备用途：代码安全漏洞扫描和修复建议
- OWASP Top 10 漏洞检测
- 敏感信息泄露扫描（API Key、密码）
- 依赖项漏洞检查（CVE）
- 安全修复建议和自动修复
# 安装
/plugin marketplace add security-scanner
# 使用示例
/security scan src/
/security check-secrets
/security audit-dependencies
📊 Documentation Generator
文档自动化用途：自动生成 API 文档和技术文档
- 从代码注释生成 API 文档
- README.md 自动生成和更新
- 架构图自动生成（Mermaid）
- 变更日志（CHANGELOG）维护
# 安装
/plugin marketplace add doc-generator
# 使用示例
/docs generate api
/docs update-readme
/docs diagram --output architecture.md
🚀 Deployment Engineer
DevOps用途：CI/CD 配置和云部署自动化
- Dockerfile 和 docker-compose 生成
- GitHub Actions/GitLab CI 配置
- Kubernetes manifests 生成
- 云平台部署（AWS/GCP/Azure）
# 安装
/plugin marketplace add deployment-engineer
# 使用示例
/deploy dockerize --port 3000
/deploy ci github-actions
/deploy k8s --namespace production
7.2 批量安装插件脚本
#!/bin/bash
# install-claude-plugins.sh - 批量安装推荐插件
PLUGINS=(
"git-workflow"
"architecture-review"
"test-generator"
"security-scanner"
"doc-generator"
"deployment-engineer"
)
echo "开始安装 Claude Code 插件..."
for plugin in "${PLUGINS[@]}"; do
echo "Installing: $plugin"
/plugin marketplace add "$plugin"
done
echo "✅ 所有插件安装完成！"
/plugin list
8. Skills 工作流配置
8.1 Skills 目录结构
# 创建 Skills 目录
mkdir -p ~/.claude/skills
mkdir -p .claude/skills # 项目级别 Skills
# Skills 目录结构
~/.claude/
├── skills/
│ ├── code-review.skill.md
│ ├── pr-description.skill.md
│ ├── test-generation.skill.md
│ └── refactoring.skill.md
└── commands/
├── review
├── test
└── deploy
8.2 创建自定义 Skill
# ~/.claude/skills/code-review.skill.md
---
name: Code Review
description: 执行全面的代码审查，检查代码质量、安全性和最佳实践
version: 1.0.0
author: Your Team
---
## 目标
对指定的代码文件或 Pull Request 进行全面的技术审查。
## 审查维度
1. **代码质量**
- 命名规范（变量、函数、类）
- 函数复杂度（圈复杂度 < 10）
- 代码重复率
- 注释充分性
2. **安全性**
- SQL 注入风险
- XSS 漏洞
- CSRF 保护
- 敏感信息硬编码
3. **性能**
- 时间复杂度分析
- 内存泄漏风险
- 数据库查询优化
- 缓存策略
4. **可维护性**
- 单一职责原则
- 依赖注入
- 接口抽象
- 测试覆盖率
## 输出格式
```markdown
## Code Review Report
### 📊 Summary
- Files reviewed: X
- Issues found: Y (Critical: A, Major: B, Minor: C)
- Overall quality: ⭐⭐⭐⭐☆
### 🔴 Critical Issues
1. [文件：行号] 问题描述
**建议修复：** 具体建议
### 🟡 Major Issues
...
### 🟢 Suggestions
...
```
## 触发命令
- `/review ` - 审查单个文件
- `/review pr ` - 审查 PR
- `/review diff` - 审查暂存区变更
8.3 研发工作流 Skills
# ~/.claude/skills/prd-writer.skill.md
---
name: PRD Writer
description: 根据需求描述生成完整的产品需求文档
---
## 输入
用户需求描述（口头或书面）
## 输出结构
1. **文档信息**
- 版本号、日期、作者
2. **产品概述**
- 背景与目标
- 用户画像
- 使用场景
3. **功能需求**
- 功能列表（MoSCoW 优先级）
- 详细功能描述
- 用户故事（As a... I want... So that...）
4. **非功能需求**
- 性能指标（响应时间、并发量）
- 安全要求
- 兼容性要求
5. **技术方案建议**
- 架构草图
- 技术选型
- 风险评估
6. **验收标准**
- 功能验收清单
- 性能验收指标
- 测试用例大纲
## 使用示例
"帮我写一个用户登录功能的 PRD"
8.4 自动热重载
💡 实验性功能：Claude Code 2.0+ 支持 Skills 自动热重载，修改后无需重启会话即可生效。
# 启用自动热重载（默认已启用）
# 技能文件位置：~/.claude/skills 或 .claude/skills
# 验证热重载
echo "# Updated $(date)" >> ~/.claude/skills/code-review.skill.md
# Claude 会自动检测到更改并重新加载
# 手动重新加载（如需要）
/reload-skills
9. MCP Server 集成
9.1 什么是 MCP
MCP（Model Context Protocol）是一个开放协议，允许 Claude Code 与外部数据源和工具交互。通过 MCP，Claude 可以访问数据库、文件系统、API 等资源。
9.2 配置 MCP Servers
# ~/.mcp.json 全局 MCP 配置
{
"mcpServers": {
"filesystem": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/username/workspace"],
"disabled": false
},
"github": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"],
"env": {
"GITHUB_TOKEN": "ghp_xxxxxxxxxxxxxxxxxxxx"
}
},
"postgres": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-postgres", "postgresql://localhost:5432/mydb"]
},
"slack": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-slack"],
"env": {
"SLACK_BOT_TOKEN": "xoxb-xxxxxxxxxxxx"
}
},
"memory": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-memory"]
}
}
}
9.3 项目级别 MCP 配置
# .mcp.json（项目根目录）
{
"mcpServers": {
"project-db": {
"command": "docker",
"args": [
"run",
"--rm",
"-i",
"-e",
"DATABASE_URL=postgresql://user:pass@host:5432/db",
"mcp/postgres"
]
}
}
}
9.4 常用 MCP Servers
| MCP Server | 用途 | 安装命令 |
|---|---|---|
| Filesystem | 安全文件访问 | npx @modelcontextprotocol/server-filesystem |
| GitHub | GitHub API 集成 | npx @modelcontextprotocol/server-github |
| PostgreSQL | 数据库查询 | npx @modelcontextprotocol/server-postgres |
| Slack | Slack 消息发送 | npx @modelcontextprotocol/server-slack |
| Memory | 长期记忆存储 | npx @modelcontextprotocol/server-memory |
| Puppeteer | 浏览器自动化 | npx @modelcontextprotocol/server-puppeteer |
10. 研发 Agent 角色配置
10.1 定义研发角色 Agents
# .claude/agents/product-manager.agent.md
---
name: Product Manager Agent
role: 产品经理
expertise: 需求分析、PRD 撰写、用户研究
tools: search, file_read, file_write
---
## 职责
1. 收集和分析用户需求
2. 编写产品需求文档（PRD）
3. 定义功能优先级（MoSCoW）
4. 制定验收标准
5. 协调技术和业务团队
## 工作流程
1. **需求收集**
- 与利益相关者访谈
- 竞品分析
- 用户调研
2. **PRD 撰写**
- 产品概述
- 功能规格
- 非功能需求
- 验收标准
3. **评审与迭代**
- 组织 PRD 评审会议
- 收集反馈
- 更新文档
## 输出模板
使用 `prd-template.md` 作为标准格式
# .claude/agents/architect.agent.md
---
name: System Architect Agent
role: 系统架构师
expertise: 系统设计、技术选型、架构评审
tools: search, file_read, file_write, execute
---
## 职责
1. 系统架构设计
2. 技术栈选型
3. 架构决策记录（ADR）
4. 性能和安全评估
5. 技术债务管理
## 架构设计流程
1. **需求分析**
- 功能需求
- 非功能需求（性能、可用性、扩展性）
2. **架构设计**
- 高层架构图
- 组件划分
- 数据流设计
- 接口定义
3. **技术选型**
- 框架和库
- 数据库
- 中间件
- 云服务
4. **风险评估**
- 技术风险
- 单点故障
- 扩展瓶颈
## 输出物
- 架构图（Mermaid/C4）
- 技术选型报告
- ADR 文档
# .claude/agents/developer.agent.md
---
name: Senior Developer Agent
role: 高级开发工程师
expertise: 全栈开发、代码质量、最佳实践
tools: search, file_read, file_write, execute, git
---
## 职责
1. 功能开发实现
2. 单元测试编写
3. 代码审查
4. 技术文档编写
5. Bug 修复
## 开发流程
1. **理解需求**
- 阅读 PRD
- 确认技术方案
- 评估工作量
2. **编码实现**
- TDD 驱动开发
- 遵循编码规范
- 编写清晰注释
3. **自测**
- 单元测试（覆盖率 > 80%）
- 集成测试
- 手动测试
4. **代码审查**
- 自查清单
- 同行评审
- 修复意见
## 编码规范
- 遵循团队 Style Guide
- 函数不超过 50 行
- 圈复杂度 < 10
- 必须有单元测试
# .claude/agents/qa.agent.md
---
name: QA Engineer Agent
role: 测试工程师
expertise: 测试策略、自动化测试、质量保证
tools: search, file_read, file_write, execute
---
## 职责
1. 测试计划和策略制定
2. 测试用例设计和执行
3. 自动化测试框架搭建
4. 缺陷跟踪和管理
5. 质量报告和度量
## 测试类型
1. **单元测试**
- 覆盖核心业务逻辑
- Mock 外部依赖
- 断言明确
2. **集成测试**
- API 接口测试
- 数据库交互
- 第三方服务
3. **E2E 测试**
- 用户旅程
- 关键业务流程
- 回归测试
4. **性能测试**
- 负载测试
- 压力测试
- 基准测试
## 输出物
- 测试计划
- 测试用例
- 缺陷报告
- 质量度量报告
10.2 多 Agent 协同配置
# .claude/orchestration.json 多 Agent 协同配置
{
"orchestration": {
"mode": "collaborative",
"agents": [
"product-manager",
"architect",
"developer",
"qa"
],
"workflow": {
"phases": [
{
"name": "Requirements",
"lead": "product-manager",
"participants": ["architect"],
"deliverables": ["PRD", "Acceptance Criteria"]
},
{
"name": "Design",
"lead": "architect",
"participants": ["developer"],
"deliverables": ["Architecture Doc", "API Spec"]
},
{
"name": "Implementation",
"lead": "developer",
"participants": [],
"deliverables": ["Source Code", "Unit Tests"]
},
{
"name": "Testing",
"lead": "qa",
"participants": ["developer"],
"deliverables": ["Test Report", "Bug List"]
}
]
},
"handoff": {
"enabled": true,
"requireApproval": ["PRD", "Architecture", "Production Deploy"]
}
}
}
11. 验证测试与故障排查
11.1 完整验证流程
✅ Claude Code 环境验证清单
11.2 常见问题排查
| 问题现象 | 可能原因 | 解决方案 |
|---|---|---|
| claude 命令找不到 | PATH 未配置 | 添加 ~/.local/bin 到 PATH |
| 认证失败 | 账户类型不符、网络问题 | 确认 Pro/Max 账户、检查网络 |
| 无法执行命令 | 权限不足、沙箱限制 | 授予工具权限、检查沙箱配置 |
| 插件加载失败 | 版本不兼容、依赖缺失 | 更新 Claude Code、安装依赖 |
| MCP 连接超时 | Server 未启动、网络问题 | 检查 Server 状态、验证配置 |
| 响应速度慢 | 网络延迟、上下文过大 | 优化网络、减少上下文 |
11.3 调试模式
# 启用详细日志
export CLAUDE_LOG_LEVEL=debug
claude
# 查看日志文件
tail -f ~/.claude/logs/claude.log
# 诊断网络问题
curl -v https://api.anthropic.com/v1/messages \
-H "Authorization: Bearer $ANTHROPIC_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"claude-3-5-sonnet-20241022","max_tokens":10,"messages":[{"role":"user","content":"Hi"}]}'
# 重置认证
rm ~/.config/claude/tokens.json
claude
# 重新登录
12. 最佳实践与工作流
12.1 日常开发工作流
典型开发流程：
1. 晨会同步
$ claude
> /standup # 生成昨日完成、今日计划、阻塞问题
2. 需求分析
> @product-manager 分析这个需求，输出 PRD 大纲
3. 技术方案
> @architect 基于 PRD 设计技术方案，包括架构图
4. 任务分解
> 将功能拆分为小的开发任务，每个任务 < 4 小时
5. 编码实现
> @developer 实现用户登录功能，包括单元测试
6. 代码审查
> /review src/auth/ # 执行代码审查
7. 提交代码
> /git commit -m "feat: add user authentication"
8. 创建 PR
> /git pr create --title "Add Auth" --assignee @reviewer
9. 测试验证
> @qa 执行集成测试，输出测试报告
10. 部署上线
> /deploy staging # 部署到预发环境
12.2 提示词最佳实践
✅ 高效提示词技巧：
- 明确角色：@architect 设计一个微服务架构...
- 提供上下文：附上相关文件、错误日志、需求文档
- 分步指令：第一步...第二步...第三步...
- 指定格式：输出为 Markdown 表格/JSON/Mermaid 图
- 设定约束：使用 TypeScript、遵循 SOLID 原则、覆盖率>80%
- 迭代优化：基于输出继续追问、修正方向
12.3 团队协作规范
# .claude/team-rules.md 团队协作规则
## 代码规范
1. 所有代码必须经过单元测试
2. 函数复杂度不得超过 10
3. 必须有 JSDoc/TSDoc 注释
4. 遵循 ESLint/Prettier 配置
## 提交流程
1. 本地测试通过
2. 执行 /review 自查
3. 提交信息遵循 Conventional Commits
4. 关联 Issue 编号
## PR 规范
1. PR 描述包含变更说明
2. 至少 1 人 Review 批准
3. CI 全部通过
4. Squash Merge 保持历史清晰
## 值班制度
1. 每周轮换 On-call
2. 响应时间 < 30 分钟
3. 严重问题升级机制
4. 事后复盘文档化
12.4 性能优化建议
| 优化项 | 方法 | 效果 |
|---|---|---|
| 减少上下文 | 只 include 相关文件、使用 @file 精确引用 | 响应速度提升 30-50% |
| 模型选择 | 简单任务用 Sonnet、复杂推理用 Opus | 成本优化 40-60% |
| 批处理 | 多个小请求合并为一个大请求 | 减少 API 调用次数 |
| 缓存结果 | 使用 Memory MCP 保存常用知识 | 避免重复生成 |
| 流式输出 | 启用 stream 模式实时查看 | 提升用户体验 |