# Claude Code 完全研究

> 全面解析 Anthropic Claude Code：安装、配置、最佳实践
>
> 归档：2026-04-22

---

## 📊 项目概览

| 项目 | 数据 |
|------|------|
| **仓库** | https://github.com/anthropics/claude-code |
| **Stars** | ⭐ 116,974 |
| **Forks** | 19,474 |
| **定位** | 终端 AI 编程助手 |
| **更新** | 2026-04-22 |

---

## 🎯 核心定位

Claude Code 是一个**代理式（Agentic）编程工具**，能：
- 读取代码库、理解结构
- 编辑文件和执行命令
- 处理 Git 工作流
- 集成开发工具
- 通过自然语言驱动

---

## 📦 安装方式

### macOS / Linux（推荐）
```bash
curl -fsSL https://claude.ai/install.sh | bash
```

### Windows PowerShell
```powershell
irm https://claude.ai/install.ps1 | iex
```

### Windows CMD
```batch
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd
```

### Homebrew
```bash
brew install --cask claude-code        # 稳定版（约滞后1周）
brew install --cask claude-code@latest # 最新版
```

### Winget（Windows）
```powershell
winget install Anthropic.ClaudeCode
```

### npm 全局安装
```bash
npm install -g @anthropic-ai/claude-code
```

---

## 🔐 认证要求

| 账户类型 | 支持 |
|---------|------|
| Pro / Max / Team / Enterprise | ✅ 支持 |
| 免费 Claude.ai 账户 | ❌ 不支持 |

**第三方提供商**：
- Amazon Bedrock
- Google Vertex AI
- Microsoft Foundry

---

## 🏗️ 核心架构

### 子代理（Sub-agents）

Claude Code 内置三类子代理：

| 子代理 | 模型 | 工具 | 用途 |
|--------|------|------|------|
| **Explore** | Haiku | 只读 | 代码搜索、分析 |
| **Plan** | 继承主对话 | 只读 | 规划模式研究 |
| **General** | 继承主对话 | 全部 | 复杂多步任务 |

### 自定义子代理

创建位置：
- `~/.claude/agents/` — 个人，所有项目可用
- `.claude/agents/` — 项目级别，仅当前项目
- 插件目录 — 通过插件分发

```markdown
---
name: code-reviewer
description: 代码审查助手
tools: Read, Glob, Grep
model: sonnet
---

你是一个高级代码审查员。专注于代码质量、安全性和最佳实践。
```

---

## 🛠️ 核心命令

| 命令 | 用途 |
|------|------|
| `/add-dir <path>` | 添加工作目录访问 |
| `/agents` | 管理子代理配置 |
| `/batch <instruction>` | 并行大规模代码修改 |
| `/branch [name]` | 创建对话分支 |
| `/btw <question>` | 快速侧问 |
| `/clear` | 清空上下文开始新对话 |
| `/compact [instructions]` | 压缩上下文 |
| `/config` | 打开设置界面 |
| `/context` | 可视化上下文使用 |
| `/copy [N]` | 复制回复 |
| `/cost` | 显示 token 费用统计 |
| `/debug [description]` | 调试模式 |
| `/diff` | 查看未提交变更 |
| `/help` | 帮助 |
| `/history` | 查看历史消息 |
| `/install` | 安装/更新 Claude Code |
| `/join <session-url>` | 加入他人会话 |
| `/kill <id>` | 终止子代理 |
| `/load` | 加载文件到上下文 |
| `/linter` | 代码检查配置 |
| `/loop <instruction>` | 循环执行直到完成 |
| `/model [model]` | 切换模型 |
| `/mcp` | MCP 服务器管理 |
| `/memory` | 内存管理 |
| `/mcp` | MCP 工具管理 |
| `/new` | 新会话 |
| `/opinion [question]` | 询问观点 |
| `/pause` | 暂停子代理 |
| `/permissions` | 权限管理 |
| `/plan` | 规划模式 |
| `/preview` | 预览修改 |
| `/prompt` | 改进提示词 |
| `/reject` | 拒绝修改 |
| `/resume [session]` | 恢复会话 |
| `/review` | 代码审查 |
| `/search <query>` | 搜索 |
| `/share` | 分享会话 |
| `/shortcuts` | 快捷键 |
| `/simplify` | 简化回复 |
| `/status` | 状态 |
| `/steer <message>` | 引导代理 |
| `/style [style]` | 调整输出风格 |
| `/table` | 生成表格 |
| `/test` | 测试相关 |
| `/undo` | 撤销 |
| `/upgrade` | 升级订阅 |
| `/web` | 网页搜索 |

---

## 📁 目录结构

```
.claude/               # 项目级配置
├── agents/           # 子代理定义
├── commands/         # 自定义命令（已被 skills 取代）
├── skills/           # 技能定义
├── settings.json     # 项目设置
└── CLAUDE.md         # 项目说明文档

~/.claude/            # 用户级配置
├── agents/          # 个人子代理
├── skills/          # 个人技能
└── settings.json    # 用户设置
```

---

## 🔧 CLAUDE.md 最佳实践

### 基础结构
```markdown
# 项目名称

简短描述。

## 技术栈
- Node.js 18+
- Express 框架

## 代码规范
- 使用 async/await
- 错误优先回调

## Git 流程
- 从 main 创建分支
- PR 需要代码审查
```

### 最佳实践要点

| 要点 | 说明 |
|------|------|
| **简洁具体** | 避免冗长，用具体示例 |
| **分块组织** | 按主题分组，用标题 |
| **优先级** | 最重要放最前面 |
| **包含例外** | 说明特殊情况和边界 |
| **定期更新** | 随项目演进更新 |

---

## ⚡ Skills 系统

Skills 扩展 Claude 的能力，通过 `SKILL.md` 文件定义。

### 目录结构
```
my-skill/
├── SKILL.md           # 主指令文件（必需）
├── template.md        # 模板
├── examples/          # 示例
└── scripts/           # 可执行脚本
```

### SKILL.md 格式
```yaml
---
name: my-skill
description: 技能的描述，用来说明何时使用
disable-model-invocation: true  # 禁止自动调用
allowed-tools: Read, Grep        # 允许的工具
---

技能的具体指令内容...
```

### 内置 Skills

| Skill | 用途 |
|-------|------|
| `/simplify` | 简化回复 |
| `/batch` | 大规模并行修改 |
| `/debug` | 调试模式 |
| `/loop` | 循环执行直到完成 |
| `/claude-api` | Claude API 参考 |

---

## 🔀 并行与大规模操作

### /batch 命令
适合大规模重构：
```text
/batch migrate all components from Angular to React
```

自动分解任务，并行执行，创建 PR。

### Git Worktrees
Claude Code 使用 Git Worktrees 实现并行会话隔离。

---

## 🛡️ 权限与安全

### 权限模式
- **allow** — 允许所有操作（默认）
- **ask** — 每次询问
- **deny** — 拒绝所有

### 工具级控制
```json
{
  "permissions": {
    "allow": ["Read", "Glob", "Grep"],
    "deny": ["Bash"]
  }
}
```

---

## 📊 上下文管理

### 上下文压缩
```text
/compact
```

### 上下文可视化
```text
/context
```

显示：
- Token 使用分布
- 优化建议
- 容量警告

### 内存系统
```text
/memory
```

- 跨会话持久化
- 自动总结
- 搜索功能

---

## 🌐 网络配置

### 代理设置
```json
{
  "env": {
    "HTTP_PROXY": "http://proxy:8080",
    "HTTPS_PROXY": "http://proxy:8080"
  }
}
```

### 访问要求
- api.anthropic.com
- claude.ai
- github.com
- 模型提供商 API

---

## 💡 最佳实践

### 1. 项目初始化
```bash
cd project
claude
# 首次：创建 CLAUDE.md
```

### 2. 任务分解
- 大任务用 `/batch` 分解
- 复杂调试用 `/debug`
- 重复任务创建 Skills

### 3. 权限控制
- 生产环境用 `ask` 模式
- 信任的开发目录用 `allow`
- 危险操作（rm, push -f）始终确认

### 4. 子代理使用
- 代码探索 → Explore
- 复杂修改 → General
- 创建自定义子代理处理重复任务

### 5. 上下文管理
- 定期 `/compact`
- 保持 CLAUDE.md 更新
- 大项目创建项目级 Skills

---

## 🔄 工作流示例

### 新功能开发
```bash
# 1. 开启会话
claude

# 2. 描述任务
帮我实现用户认证功能

# 3. Claude 自动规划并执行
# - 创建分支
# - 编写代码
# - 编写测试
# - 提交 PR

# 4. 代码审查
/review

# 5. 合并后
/compact  # 清理上下文
```

### 大规模重构
```bash
# 使用 batch 命令
/batch migrate database layer from SQLAlchemy to Prisma

# Claude 自动：
# 1. 研究代码库
# 2. 分解成独立任务
# 3. 并行处理
# 4. 创建多个 PR
```

---

## 📱 多端支持

| 平台 | 方式 |
|------|------|
| **终端** | `claude` 命令 |
| **桌面 App** | macOS/Windows 原生应用 |
| **VS Code** | 插件市场安装 |
| **JetBrains** | IntelliJ/PyCharm/WebStorm 插件 |
| **浏览器** | Claude Code on the Web |

---

## 🔮 高级功能

### MCP（Model Context Protocol）支持
```text
/mcp
```
管理 MCP 服务器，扩展工具能力。

### Agent Teams
多代理协作模式，适合复杂项目。

### Web Search
```text
/web <query>
```
直接搜索网页。

---

## ❌ 常见问题

| 问题 | 解决方案 |
|------|---------|
| 安装失败 | 检查 Node.js 18+ |
| 权限错误 | 使用 `claude doctor` 诊断 |
| 上下文溢出 | `/compact` 压缩 |
| 更新失败 | Homebrew/WinGet 需手动更新 |

### 诊断命令
```bash
claude doctor    # 完整诊断
claude --version # 版本检查
```

---

## 📚 学习路径

1. **入门**：安装 → 认证 → 基础对话
2. **进阶**：CLAUDE.md → 子代理 → Skills
3. **高级**：batch 命令 → Agent Teams → MCP
4. **专家**：自定义子代理 → 工作流自动化 → 团队协作

---

## 🔗 相关资源

| 资源 | 链接 |
|------|------|
| 官方文档 | https://docs.anthropic.com/claude-code |
| GitHub | https://github.com/anthropics/claude-code |
| Skills 市场 | https://agentsskills.io |
| API 文档 | https://docs.anthropic.com/api |

---

## AI工程索引

相关笔记：
- [[INDEX_AI工程]] - AI工程知识索引
- [[Claudian插件]] - Obsidian 嵌入 Claude Code

---

*整理：知识库管理员 | 归档：2026-04-22*