Claude Code 深度使用指南 从命令行到多智能体平台

目录

• 一、安装与认证（正确姿势）
• 二、Claude Code 的进化时间线
• 三、CLAUDE.md：项目记忆的核心
• 四、斜杠命令与基本工作流
• 五、MCP：连接外部世界
• 六、Subagents：专属子智能体
• 七、Hooks：自动化守卫
• 八、Skills：可复用的工作流模板
• 九、Plugins：生态系统的打包
• 十、Agent Teams：多智能体协作
• 十一、成本控制与模型选择
• 十二、实战最佳实践

一、安装与认证（正确姿势）

博客之前介绍的安装命令已经过时。Claude Code 的 npm 包名早已更改，现在正确的安装方式如下：

⚠️ 注意：旧包名 claude-code 已废弃，请使用 @anthropic-ai/claude-code，当前最新版本为 v2.1.x。

macOS / Linux

# 确保 Node.js v18+ 已安装
node --version

# 安装 Claude Code（正确包名）
npm install -g @anthropic-ai/claude-code

# 验证安装
claude --version

# 启动（首次会引导你认证）
claude

macOS 推荐：使用 Homebrew

brew install node@20
npm install -g @anthropic-ai/claude-code

Windows（必须使用 WSL2）

# PowerShell 管理员模式安装 WSL
wsl --install -d Ubuntu

# 在 WSL 中安装 Node.js 20
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

# 安装 Claude Code
npm install -g @anthropic-ai/claude-code

常用启动参数

# 直接执行单个任务（非交互）
claude -p "帮我分析项目结构并写一份说明文档"

# 继续上次对话
claude --continue

# 恢复指定历史会话
claude --resume

# 跳过所有权限确认（危险，仅用于自动化脚本）
claude --dangerously-skip-permissions

# 指定使用的模型
claude --model claude-opus-4-6

二、Claude Code 的进化时间线

短短一年多时间，Claude Code 从一个简单的终端编码助手演变为功能完整的 AI 智能体平台。理解这条时间线，有助于你知道为什么"旧文章"已经完全过时。

截至 2026 年 2 月，公开 GitHub 上约 4% 的提交（每天约 13.5 万个）由 Claude Code 完成，Anthropic 内部 90% 的代码也已是 AI 辅助编写。

三、CLAUDE.md：项目记忆的核心

CLAUDE.md 是 Claude Code 最重要的配置文件，没有之一。它是 AI 的"项目宪法"——每次会话启动时自动注入，无需你手动说明项目背景。

"Claude Code 没有记忆，但 CLAUDE.md 有。"

文件层级

Claude Code 会按以下顺序查找并合并 CLAUDE.md 文件：

~/.claude/CLAUDE.md        # 用户级（所有项目通用）
./CLAUDE.md                # 项目级（团队共享，纳入 git）
./src/CLAUDE.md            # 子目录级（特定模块）

一个好的 CLAUDE.md 模板

# 项目：我的应用名称

## 技术栈
- 前端：React 18 + TypeScript + Tailwind CSS
- 后端：Node.js + Express + PostgreSQL
- 测试：Jest + Testing Library
- 部署：Docker + Vercel

## 开发规范
- 组件使用函数式写法 + Hooks，文件名 PascalCase
- 工具函数文件名 camelCase，放在 src/utils/
- 所有 API 路由加 /api/v1 前缀
- 提交信息格式：feat/fix/refactor(scope): 说明

## 常用命令
- `npm run dev`：启动开发服务器（端口 3000）
- `npm run test`：运行全部测试
- `npm run build`：生产环境构建
- `npm run lint`：代码检查

## 重要约定
- 禁止修改 src/config/secrets.ts
- 数据库 migration 需要人工审核后再执行
- 不要在组件里直接调用 API，统一走 hooks/

💡 CLAUDE.md 中的 HTML 注释（<!-- -->）在自动注入时对 Claude 不可见，但通过 Read 工具手动读取时可见，适合放运维备注。

四、斜杠命令与基本工作流

内置斜杠命令速查

自定义斜杠命令

把常用的长提示词做成命令，放在 .claude/commands/ 目录：

<!-- 文件：.claude/commands/catchup.md -->

请读取当前 git branch 所有改动的文件，
总结本次分支的主要变更内容，
并列出还未完成的 TODO 注释。

使用时直接在对话中输入 /catchup 即可。

📝 不要过度依赖自定义斜杠命令。如果你的命令列表越来越长，说明该把那些指令写进 CLAUDE.md，让 Claude 自主理解，而不是强迫用户记忆魔法命令。

五、MCP：连接外部世界

MCP（Model Context Protocol）是 Claude Code 连接外部工具的标准接口，相当于 AI 的"USB-C 接口"。通过 MCP，你可以让 Claude 直接操作 GitHub、数据库、Figma、Slack 等系统。

添加 MCP 服务器

# 基本语法
claude mcp add <名称> [选项] -- <命令> [参数]

# 示例：添加文件系统访问
claude mcp add filesystem -s user -- \
  npx -y @modelcontextprotocol/server-filesystem ~/Documents ~/Projects

# 示例：添加 GitHub 集成（需要 token）
claude mcp add github -s user \
  -e GITHUB_TOKEN=ghp_your_token -- \
  npx -y @modelcontextprotocol/server-github

# 查看已添加的 MCP 服务器
claude mcp list

# 删除 MCP 服务器
claude mcp remove <名称>

作用域说明

添加后如何使用

# MCP 工具以斜杠命令形式调用
/mcp__playwright__create-test [参数]

# 或者直接用自然语言，Claude 会自动判断调用哪个 MCP 工具
> 帮我在 GitHub 上创建一个 issue，标题是"修复登录 bug"

六、Subagents：专属子智能体

Subagent（子智能体）是 Claude Code 的专属 AI 助手——你可以为它定义独立的系统提示词、工具集、权限模式，甚至持久记忆。当主对话把某个子任务委托给 Subagent 时，它在独立的上下文中工作，完成后把结果返回主对话。

创建一个 Subagent 文件

---
name: code-reviewer
description: 代码审查专家，发现问题并给出改进建议。当用户提交代码改动时自动激活。
tools: Read, Grep, Glob
model: sonnet
memory: project
permissionMode: acceptEdits
---

你是一位资深代码审查员。审查代码时请关注：
1. 安全漏洞（SQL 注入、XSS 等）
2. 性能问题（N+1 查询、不必要的循环）
3. 可读性和命名规范
4. 缺失的错误处理

发现问题后，请指出具体文件和行号，解释问题所在，并提供改进后的代码片段。

将文件保存到 .claude/agents/code-reviewer.md（项目级）或 ~/.claude/agents/（用户级）。

使用 Subagent

# 自然语言调用
> 使用 code-reviewer 检查 src/auth/ 目录下的所有改动

# 通过 /agents 交互式菜单选择
/agents

# 命令行启动时指定默认 Subagent
claude --agent code-reviewer

Subagent 支持的 frontmatter 字段

⚠️ 注意：Subagent 无法再生成 Subagent（禁止无限递归）。如果需要多智能体真正协作，请使用 Agent Teams。

七、Hooks：自动化守卫

Hooks 是 Claude Code 的 Git Hooks——在特定生命周期节点自动执行脚本，靠的是确定性的代码控制，与 AI 能力无关。你想要"每次 Claude 写完文件就自动 lint"？Hooks 是答案。

四种钩子类型

配置示例（.claude/settings.json）

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write",
        "hooks": [
          {
            "type": "command",
            "command": "npm run lint --fix"
          }
        ]
      }
    ],
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "./scripts/check-dangerous-cmd.sh"
          }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "./scripts/notify-slack.sh"
          }
        ]
      }
    ]
  }
}

也可以通过 /hooks 交互式命令配置，无需手动编辑 JSON。

💡 原则：任何"必须始终执行"的操作，都应该用 Hooks 而不是提示词。提示词是建议，Hooks 是规则。

八、Skills：可复用的工作流模板

Skills 是存储在 SKILL.md 文件里的工作流模板。和斜杠命令不同，Skills 的神奇之处在于：Claude 会在认为某个 Skill 相关时主动加载它，无需你手动触发。

可以把它想象成《黑客帝国》里的"我会功夫了"——Claude 按需从 SKILL.md 下载领域专业知识，不需要时不占用上下文。

创建一个 Skill

---
name: database-migration
description: 创建和管理数据库 migration 文件。当用户需要修改数据库结构时使用。
---

## 数据库 Migration 规范

创建 migration 时，请遵循以下步骤：

1. 在 `db/migrations/` 创建新文件，命名格式：`YYYYMMDD_HHMMSS_描述.sql`
2. 始终包含 `UP`（应用）和 `DOWN`（回滚）两个部分
3. 添加必要的索引，写清楚原因注释
4. 对影响大量数据的操作，必须包含估算的执行时间

Skills 的存放位置

九、Plugins：生态系统的打包

Plugin 是将斜杠命令、Subagents、Hooks、Skills、MCP 服务器打包成一个可分发单元的机制。想象成 VS Code 的扩展——安装一个插件，整套工作流配置到位。

使用插件市场

# 进入插件管理
/plugin

# 添加插件市场
/plugin marketplace add anthropics/claude-code-plugins

# 安装插件
/plugin install code-review-toolkit

# 查看已安装插件
/plugin list

# 插件提供的命令带命名空间前缀
/code-review-toolkit:review-pr

自定义插件的目录结构

my-plugin/
├── plugin.json          # 插件描述文件
├── agents/
│   └── reviewer.md      # Subagent 定义
├── skills/
│   └── deploy.md        # Skills 定义
├── commands/
│   └── release.md       # 斜杠命令
└── hooks/
    └── post-build.sh    # Hook 脚本

十、Agent Teams：多智能体协作（2026.02 新）

Agent Teams 是 2026 年 2 月随 Claude Sonnet 4.6 一起发布的最新功能。

和 Subagents 不同——Subagent 是向主 Claude 汇报的下级，而 Agent Teams 的成员是平等的协作者，可以互相通讯、并行完成任务。

Agent Teams vs Subagents

启动多智能体团队

# 推荐在 tmux 中启动
tmux new-session -s dev-team
claude

然后在对话中用自然语言描述团队任务：

> 组建一个3人团队来审查这个代码库：
  - 成员1：安全审查（认证、输入验证、密钥管理）
  - 成员2：性能审查（SQL查询、循环优化、缓存策略）
  - 成员3：测试覆盖（缺失的测试、边界情况）
  请并行工作，完成后汇总报告。

Git Worktrees：并行安全保障

每个智能体在独立的 worktree 中工作，彻底避免文件冲突：

# 两个智能体各自在独立分支工作
claude --worktree feature-auth
claude --worktree feature-payment

# 结合 tmux 分屏同时监控
claude --worktree feature-auth --tmux

💡 Agent Teams 最适合可以清晰拆分的并行任务：多模块同时开发、代码库多维度审查等。不适合紧密耦合、需要频繁同步状态的任务。

十一、成本控制与模型选择

Claude Code 提供三种模型，选对模型能显著降低成本而不影响效果。

一次典型编码会话消耗约 50K–200K 输入 token + 10K–50K 输出 token。将探索型 Subagent 切换到 Haiku，通常可节省 40–50% 的费用。

成本优化策略

# 在 Subagent frontmatter 中按角色指定模型
model: haiku   # 只读文件的探索 agent
model: sonnet  # 写代码的实现 agent
model: opus    # 需要深度推理的架构 agent

# 查看当前会话费用
/cost

# 上下文过大时压缩
/compact

# 新任务开始前清空
/clear

十二、实战最佳实践

✅ 高效使用原则

1. CLAUDE.md 是投资，不是负担。 花时间把项目规范写清楚，Claude 会越用越懂你的项目。把它当成新队友的入职文档来写。

2. 用 Hooks，不要用提示词做约束。 如果你反复在对话里说"记得跑 lint"，把这件事交给 PostToolUse Hook，从根本上解决问题。

3. 不要过度 Subagent 化。 与其创建一堆定制 Subagent，不如把上下文写好放在 CLAUDE.md，让 Claude 用内置的 Task() 自主决定何时委托子任务——这更灵活、更少维护成本。

4. 长任务用会话恢复。 claude --resume 能从历史会话列表恢复，搭配 --continue 无缝续接上次工作。

5. 大型项目按阶段切分会话。 一个超长会话会导致上下文膨胀、成本飙升、质量下降。合理的节点用 /clear 重置，把当前进度写进 CLAUDE.md 再继续。

❌ 常见误区

别让 AI 自由选择技术栈。 尤其是小项目，不约束的话 AI 倾向于过度工程化。在提示词里明确指定：使用 SQLite、不用框架、单文件实现。

别用模糊词汇。 "用户友好"、"现代化"、"最佳实践"——这些对 Claude 没有意义。换成："移动端适配"、"错误信息用中文"、"每个函数加 JSDoc 注释"。

别忽略 /doctor 命令。 遇到奇怪问题时，先运行 claude /doctor 检查环境，而不是反复重试。

一个推荐的日常工作流

# 1. 开始新任务前，确认 Claude 理解项目规范
claude
> 读取 CLAUDE.md，确认你了解本项目的技术栈和规范

# 2. 描述清晰、有约束的任务目标
> 实现用户头像上传功能：
  - 支持 JPG/PNG，最大 5MB
  - 上传到 /api/v1/users/avatar
  - 存储到 S3，返回 CDN 地址
  - 加载状态和错误处理都要有

# 3. 实现过程中随时检查成本
/cost

# 4. 完成后让 Claude 总结改动
> 总结本次改动的核心内容，格式化为 git commit message