全面的 Claude Code CLI 指南

快速链接： 开始使用 · 命令 · MCP 设置 · 设置 · SDK · 变更日志

🔄 实时指南：每 2 天从 官方文档、GitHub 发布 和 Anthropic 变更日志 自动更新。请参阅 update-log.md。

🤖 适用于 AI 代理：针对人类和 AI 均进行了优化。[OFFICIAL] = 来自 code.claude.com。[COMMUNITY] = 观察到的模式。[EXPERIMENTAL] = 尚未验证。

什么是 Claude Code？

Claude Code 是一款驻留在终端中的智能体式 AI 编程助手。 它能够理解你的代码库，直接编辑文件、运行命令，并通过自然语言对话帮助你更快地编写代码。

主要功能：

• 💬 终端中的自然语言界面
• 📝 直接编辑文件和执行命令
• 🔍 全面的项目上下文感知
• 🔗 通过 MCP（模型上下文协议）实现外部集成
• 🤖 可通过技能、钩子和插件进行扩展
• 🛡️ 沙箱执行以确保安全性

安装方法：

# 快速安装（macOS、Linux、WSL）
curl -fsSL https://claude.ai/install.sh | bash

# 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

# 替代方案：Homebrew（macOS/Linux）
brew install --cask claude-code

# 替代方案：WinGet（Windows）
winget install Anthropic.ClaudeCode

# 替代方案：NPM（⚠️ 已弃用 - 请使用原生安装方式）
npm install -g @anthropic-ai/claude-code

claude --version  # 验证安装

官方文档： https://code.claude.com/docs/en/overview

目录

快速参考

基本命令 [OFFICIAL]

# 启动 Claude Code
claude                    # 启动交互式会话
claude -p "task"          # 打印模式（非交互式）
claude --continue         # 继续上次会话
claude --resume <id>      # 恢复特定会话

# 会话管理
/help                     # 显示可用命令
/exit                     # 结束会话
/compact                  # 减少上下文大小
/compact [instructions]  # 带有可选重点指令的精简对话

# 后台任务
/bashes                   # 列出后台进程
/kill <id>               # 停止后台进程

# 发现
/commands                 # 列出技能和命令
/hooks                   # 显示已配置的钩子
/skills                  # 列出可用技能（NEW）
/plugin                  # 管理插件

来源： CLI 参考

CLI 标志参考 [OFFICIAL]

# 输出控制
claude -p, --print "task"          # 打印模式：非交互式，打印结果并退出
claude --output-format json         # 输出格式：文本、json 或 stream-json
claude --input-format text          # 输入格式：文本或 stream-json
claude --verbose                    # 启用详细日志记录（全程逐轮输出）

# 会话管理
claude --continue                   # 从上次会话继续
claude --resume <session-id>        # 根据 ID 或名称恢复特定会话
claude --from-pr <pr>               # 恢复与 GitHub PR 编号或 URL 关联的会话 [NEW]
claude --fork-session               # 创建新的会话 ID，而非重复使用原有 ID
claude --session-id <uuid>          # 使用特定会话 ID（必须是有效的 UUID）

# 远程会话（claude.ai 订阅用户）
claude --remote "task"              # 在 claude.ai 上创建网页会话
claude --teleport                   # 将网页会话恢复到本地终端

# 调试与日志记录
claude --debug                      # 启用调试模式（可选择性过滤类别）
claude --debug "api,mcp"            # 调试特定类别
claude --debug "!statsig,!file"     # 排除某些类别

# 模型与代理配置
claude --model <name>               # 指定模型（sonnet、opus、haiku 或完整名称）
claude --fallback-model <name>      # 默认模型过载时的备用模型（打印模式）
claude --agent <name>               # 指定自定义代理（覆盖设置）
claude --agents '<json>'            # 通过 JSON 动态定义自定义子代理

# 系统提示自定义
claude --system-prompt "prompt"     # 替换整个默认系统提示
claude --system-prompt-file <path>  # 用文件内容替换（仅限打印模式）
claude --append-system-prompt "..."  # 在默认系统提示后追加内容
claude --append-system-prompt-file <path>  # 在默认系统提示后追加文件内容（仅限打印模式）

# 工具与权限管理
claude --tools "Bash,Read,Edit"     # 限制内置工具（使用 "" 可禁用所有工具）
claude --allowedTools "Bash(git:*)" # 不需提示即可执行的工具
claude --disallowedTools "Edit"     # 从上下文中移除特定工具
claude --permission-mode plan       # 以指定权限模式开始
claude --dangerously-skip-permissions  # 跳过所有权限提示 ⚠️
claude --allow-dangerously-skip-permissions  # 启用绕过选项而不激活 [NEW]
claude --permission-prompt-tool <mcp-tool>  # 用于权限提示的 MCP 工具（非交互式）[NEW]

# 预算与执行限制（打印模式）
claude --max-budget-usd 5.00        # API 调用的最大美元金额
claude --max-turns 3                # 代理轮次的限制数量
claude --json-schema '<schema>'     # 获取符合模式的验证 JSON 输出（打印模式）[新增]

# 目录与配置
claude --add-dir ../apps ../lib     # 添加额外的工作目录
claude --plugin-dir ./my-plugins    # 从目录加载插件
claude --settings ./settings.json   # 设置 JSON 文件的路径
claude --setting-sources user,project  # 以逗号分隔的设置来源列表 [新增]
claude --mcp-config ./mcp.json      # 从 JSON 文件加载 MCP 服务器
claude --strict-mcp-config          # 仅使用 --mcp-config 中的 MCP 服务器

# IDE 与浏览器集成
claude --ide                        # 启动时自动连接到 IDE
claude --chrome                     # 启用 Chrome 浏览器集成
claude --no-chrome                  # 禁用 Chrome 浏览器集成

# 代理团队 [新增]
claude --teammate-mode in-process   # 团队成员显示在主终端中
claude --teammate-mode tmux         # 每个团队成员在自己的窗格中（需要 tmux/iTerm2）
claude --teammate-mode auto         # 自动检测（默认）

# 设置与维护
claude --init                       # 运行设置钩子并启动交互模式
claude --init-only                  # 运行设置钩子并退出（无交互会话）
claude --maintenance                # 运行带有维护触发器的设置钩子并退出

# 其他选项
claude --disable-slash-commands     # 禁用所有技能和斜杠命令
claude --no-session-persistence     # 禁用会话持久化（打印模式）
claude --betas interleaved-thinking # API 请求的测试版头信息
claude --include-partial-messages   # 包含部分流式事件（配合 stream-json 使用）[新增]

常见标志组合：

# 一次性任务并输出 JSON
claude --print "分析这段代码" --output-format json

# 调试 MCP 和 API 问题
claude --debug "api,mcp"

# 使用特定模型恢复会话
claude --resume auth-refactor --model opus

# 非交互式且有预算限制（CI/CD）
claude -p --max-budget-usd 5.00 --output-format json "运行测试"

# 用于专业工作的自定义子代理
claude --agents '{"reviewer":{"description":"代码审查员","prompt":"检查代码中的错误"}}'

# claude.ai 订阅用户的远程会话
claude --remote "修复登录漏洞"

来源: CLI 参考

核心工具 [官方]

来源: 设置参考

核心概念

1. Claude Code 的工作原理 [官方]

Claude Code 通过您终端中的 对话式界面 运行：

# 您描述所需内容
$ claude
> “为 API 添加用户认证功能”

# Claude Code:
1. 分析您的代码库结构
2. 制定实现计划
3. 首次请求文件编辑权限
4. 直接将代码写入您的文件
5. 可以运行测试并验证更改
6. 如有要求，创建 Git 提交

关键原则：

• 自然语言：只需描述需求，无需特殊语法
• 直接操作：在获得您的许可后编辑文件并执行命令
• 上下文感知：理解整个项目结构
• 逐步信任：根据需要请求新操作的权限
• 可脚本化：可通过 SDK 自动化

来源: 概述

2. 权限模型 [官方]

Claude Code 使用 渐进式权限系统 以确保安全：

# 权限模式
“ask”    # 每次使用时提示（新操作的默认设置）
“allow”  # 不提示直接允许
“deny”   # 完全阻止

# 权限优先级 [新增 v2.1.27]
# 内容级规则优先于工具级规则
# 示例: allow: ["Bash"], ask: ["Bash(rm *)"]
#   -> Bash 总体上被允许，但“rm *”命令需要确认

# 需要权限的工具
- Bash（执行命令）
- Write/Edit/NotebookEdit（修改文件）
- WebFetch/WebSearch（访问网络）
- Skill（技能和自定义命令）

# 不需要权限的工具（安全操作）
- Read/NotebookRead（读取文件）
- Grep/Glob（搜索）
- TodoWrite（任务跟踪）
- Task（子代理）

配置权限：

在您的项目中创建 .claude/settings.json，或在全局级别创建 ~/.claude/settings.json：

{
  "permissions": {
    "defaultMode": "ask",
    "allow": {
      "Bash": ["git status", "git diff", "git log", "npm test", "npm run*"],
      "Read": {},
      "Edit": {}
    },
    "deny": {
      "Write": ["*.env", ".env.*", ".git/*"],
      "Edit": ["*.env", ".env.*"]
    },
    "additionalDirectories": [
      "/path/to/other/project"
    ]
  }
}

来源: 设置

3. 项目背景 - CLAUDE.md [社区]

项目根目录下的 CLAUDE.md 文件可在不同会话间提供持久化的上下文：

# 项目：我的应用

## 关键背景信息（请先阅读）
- 语言：TypeScript + Node.js
- 框架：Express + React
- 数据库：PostgreSQL，使用 Prisma ORM
- 测试：Jest + React Testing Library

## 可用命令
npm run dev          # 启动开发服务器（端口 3000）
npm test             # 运行所有测试
npm run lint         # 运行 ESLint 检查
npm run typecheck    # TypeScript 类型检查
npm run db:migrate   # 执行 Prisma 数据库迁移

## 重要规范
- 所有 API 路由位于 /src/routes，采用 RESTful 风格
- 数据库查询使用 Prisma Client
- 认证基于 JWT 令牌实现，代码位于 /src/auth
- 前端组件存放在 /src/components
- API 响应格式：{success: boolean, data: any, error?: string}

## 常见陷阱及注意事项
- 请勿修改 /generated 目录（由 Prisma 自动生成）
- 请勿提交 .env 文件，应使用 .env.example
- 拉取到新的数据库模式变更后，务必运行 npm run db:migrate
- 在 TypeScript 中请避免使用 `any` 类型，请使用明确的类型定义

## 文件结构
/src
  /routes       # Express API 路由
  /services     # 业务逻辑
  /models       # 类型定义
  /middleware   # Express 中间件
  /utils        # 共享工具
  /auth         # 认证逻辑

## 最新学习心得
- [2026-01-15] 处理 Stripe 支付 Webhook 时需要使用 raw body 解析器
- [2026-01-10] Redis 连接池配置：{maxRetriesPerRequest: 3}

CLAUDE.md 的作用：

• ✅ 在每次会话开始时立即提供项目背景信息
• ✅ 减少重复解释项目结构的需求
• ✅ 存储项目特有的开发规范和约定
• ✅ 记录哪些方法有效、哪些不可取
• ✅ 可通过 Git 分享给团队成员
• ✅ 格式经过优化，便于 Claude 快速理解

注： 尽管 CLAUDE.md 并非官方功能，但它已成为社区广泛采纳的一种实践。如果项目根目录下存在 CLAUDE.md 文件，Claude Code 会自动读取并解析。

4. 工具参考 [官方]

Read 工具

用途： 读取并分析文件

# 示例
Read file_path="/src/app.ts"
Read file_path="/docs/screenshot.png"  # 可以读取图片！
Read file_path="/docs/guide.pdf"       # 可以读取 PDF！
Read file_path="/docs/guide.pdf" pages="1-5"  # 读取指定页码的 PDF 内容 [新增 v2.1.30]

功能：

• 可读取任何文本文件（代码、配置、日志等）
• 支持处理图片（截图、图表、架构图等）
• 能够解析 PDF 文件，提取文本和图像内容
• 可解析 Jupyter 笔记本文件（.ipynb）
• 返回带行号的内容（类似 cat -n 格式）
• 支持通过 offset/limit 参数读取大文件

PDF 参数 [新增 v2.1.30]：

• pages：可选参数，用于指定要读取的页码范围（如 "1-5" 或 "1,3,5"），以读取特定页面
• 对于超过 10 页的大 PDF 文件，当被 @ 提及时，仅返回轻量级引用
• PDF 文件限制：最多 100 页，文件大小不超过 20MB

特别功能：

• 图片： Claude 可以读取错误截图、UI 设计图、架构示意图等
• PDF： 提取并分析 PDF 内容，适用于文档和需求分析
• 笔记本： 完整访问代码单元、Markdown 和输出结果

Write 工具

用途： 创建新文件

Write file_path="/src/newFile.ts"
      content="export const config = {...}"

行为：

• 创建具有指定内容的新文件
• 如果文件已存在，则会覆盖原有内容（若需编辑现有文件，请使用 Edit 工具）
• 每次会话首次使用时需获得权限
• 如有必要，会自动创建父目录

最佳实践： 使用 Edit 工具修改现有文件，而 Write 工具仅用于创建新文件。

Edit 工具

用途： 通过精确字符串替换来修改现有文件

Edit file_path="/src/app.ts"
     old_string="const port = 3000"
     new_string="const port = process.env.PORT || 3000"

重要提示：

• 必须完全匹配目标字符串，包括空格和缩进
• 如果 old_string 在文件中不唯一，则操作将失败（此时可扩大上下文范围或使用 replace_all 参数）
• 使用 replace_all=true 可替换所有匹配项（适用于重命名场景）
• 必须先读取文件，才能进行编辑

常见模式：

# 1. 读取文件以确认具体内容
Read file_path="/src/app.ts"

# 2. 使用精确字符串匹配进行编辑
Edit file_path="/src/app.ts"
     old_string="function login() {
  return 'TODO';
}"
     new_string="function login() {
  return authenticateUser();
}"

Bash 工具

用途： 执行 Shell 命令

Bash command="npm test"
Bash command="git status"
Bash command="find . -name '*.test.ts'"

特性：

• 可执行任意 Shell 命令
• 支持后台执行（run_in_background=true）
• 可配置超时时间（默认 2 分钟，最大 10 分钟）
• Git 操作较为常见（状态、差异、日志、提交、推送）

安全措施：

• 需要权限
• 可根据设置中的规则模式进行限制
• 在 macOS/Linux 系统上支持沙盒机制

常见的 Git 操作模式：

# 查看当前状态
Bash command="git status"

# 查看更改内容
Bash command="git diff"

# 创建提交
Bash command='git add . && git commit -m "feat: 添加认证功能"'

# 查看提交历史
Bash command="git log --oneline -10"

Grep 工具

用途： 使用正则表达式搜索文件内容

# 查找函数
Grep pattern="function.*auth" path="src/" output_mode="content"

# 查找带有上下文的 TODO
Grep pattern="TODO" output_mode="content" -C=3

# 统计出现次数
Grep pattern="import.*from" output_mode="count"

# 不区分大小写
Grep pattern="error" -i=true output_mode="files_with_matches"

参数：

• pattern：正则表达式模式（ripgrep 语法）
• path：要搜索的目录或文件（默认为当前目录）
• output_mode：
  • "files_with_matches"（默认）：仅显示匹配文件的路径
  • "content"：显示匹配的行
  • "count"：显示每文件的匹配次数
• -A、-B、-C：上下文行数（分别表示匹配行之后、之前或前后）
• -i：不区分大小写
• -n：显示行号
• type：按文件类型筛选（如 "js"、"py"、"rust" 等）
• glob：按 glob 模式筛选（如 "*.test.ts"）

高效强大： 内部使用 ripgrep 引擎，在大型代码库中比 Bash 的 grep 命令快得多。

Glob 工具

用途： 按模式查找文件

# 查找测试文件
Glob pattern="**/*.test.ts"

# 查找特定扩展名的文件
Glob pattern="src/**/*.{ts,tsx}"

# 查找配置文件
通配符模式="**/config.{json,yaml,yml}"

功能：

• 快速模式匹配（适用于任何规模的代码库）
• 返回按修改时间排序的文件（最近的在前）
• 支持复杂的 glob 模式（** 表示递归，{} 表示选项）

TodoWrite 工具

用途： 在工作过程中管理任务列表

TodoWrite todos=[
  {
    "content": "添加认证端点",
    "status": "in_progress",
    "activeForm": "添加认证端点"
  },
  {
    "content": "编写集成测试",
    "status": "pending",
    "activeForm": "编写集成测试"
  },
  {
    "content": "更新 API 文档",
    "status": "pending",
    "activeForm": "更新 API 文档"
  }
]

任务状态：

• "pending" - 尚未开始
• "in_progress" - 正在进行中（同一时间只能有一个）
• "completed" - 已成功完成

依赖跟踪 [新功能]：v2.1.16 引入了任务依赖跟踪功能，允许任务定义必须先完成的前置条件。这使得复杂的多步骤工作流能够按照正确的顺序执行。

最佳实践：

• 用于多步骤任务（3 步及以上）
• 同一时间只保持一个任务为 in_progress
• 完成后立即标记为已完成
• 使用描述性的 content（要做什么）和 activeForm（正在做什么）

适用场景：

• ✅ 复杂的多步骤功能
• ✅ 用户提供多个任务
• ✅ 需要规划的非 trivial 工作
• ❌ 单一的简单任务
• ❌ 简单的操作

任务工具（子代理）

用途： 启动专门处理特定任务的 AI 代理

# 探索代码库
Task subagent_type="Explore"
     prompt="查找所有 API 端点及其认证要求"

# 通用型代理，用于复杂任务
Task subagent_type="general-purpose"
     prompt="研究 API 限流的最佳实践，并实现解决方案"

可用的子代理类型：

• "general-purpose" - 复杂的多步骤任务、研究、实施
• "Explore" - 快速代码库探索（Glob、Grep、Read、Bash）

适用场景：

• 需要网络搜索 + 分析的研究任务
• 代码库探索（寻找模式、理解架构）
• 可以独立运行的复杂多步骤操作
• 在您继续其他任务时进行的后台工作

WebFetch 工具

用途： 获取并分析网页内容

WebFetch url="https://docs.example.com/api"
         prompt="提取所有端点文档"

功能：

• 将 HTML 转换为 Markdown 以便分析
• 可以通过提示提取特定信息
• 适用于研究文档、文章、参考资料

WebSearch 工具

用途： 在网上搜索最新信息

WebSearch query="React 19 新特性 2024"

使用场景：

• 研究当前的最佳实践
• 查找最新的库文档
• 检查已知问题或解决方案
• 验证最新框架的功能

来源： CLI 参考、设置

LSP 工具（语言服务器协议）[官方]

用途： 获取代码智能功能，如跳转到定义、查找引用和悬停文档。

LSP operation="goToDefinition"
    filePath="src/utils/auth.ts"
    line=42
    character=15

可用操作：

参数：

• operation（必填）：要执行的 LSP 操作
• filePath（必填）：文件的绝对路径或相对路径
• line（必填）：行号（从 1 开始，与编辑器显示一致）
• character（必填）：字符偏移量（从 1 开始，与编辑器显示一致）

使用场景：

# 查找函数的定义位置
> “跳转到 getUserById 的定义处”

# 查找函数的所有使用处
> “查找 authenticate 函数的所有引用”

# 获取符号的文档
> “validateToken 函数是做什么的？”

# 探索代码结构
> “列出 auth.ts 文件中的所有符号”

注意： 必须为文件类型配置 LSP 服务器。如果某种语言没有可用的服务器，则会返回错误。

来源： CLI 参考

5. 上下文管理 [官方]

Claude Code 通过智能管理来维护对话上下文：

上下文命令

/compact                   # 减少上下文，移除旧信息
/compact "keep auth work"  # 带指令压缩上下文（保留指定内容）

使用时机

使用 /compact 的情况：

• 长时间会话且读取了大量文件
• 出现“上下文过大”错误
• 完成一项重要任务后希望重新开始

使用带指令的 /compact 的情况：

• 上下文变得庞大但仍需保留近期工作
• 在相关任务之间切换
• 希望智能清理而不丢失重要上下文
• 示例：/compact "keep the authentication implementation context"

保留与清除的内容

保留：

• CLAUDE.md 内容（您的项目上下文）
• 最近的交互和决策
• 当前任务信息和待办事项
• 近期仍相关的文件读取

清除：

• 不再需要的旧文件读取
• 已完成的操作
• 过时的搜索结果
• 不再相关的旧上下文

自动上下文管理

Claude Code 可能会在以下情况下自动压缩上下文：

• 令牌限制即将达到
• 存在大量旧文件读取
• 会话持续时间过长

来源： 设置

6. 工作区管理 [官方]

使用 /add-dir 添加目录

Claude Code 可以同时处理多个目录：

# 向当前会话添加另一个目录
/add-dir /path/to/other/project

# 跨多个项目工作
> “更新后端的 User 类型，并将其同步到前端”

# 克劳德现在可以访问这两个目录

使用场景：

• 单体仓库开发（前端 + 后端 + 共享库）
• 跨项目重构
• 多个项目中的依赖更新
• 协调相关仓库之间的变更

配置：

你也可以在 .claude/settings.json 中预先配置额外的目录：

{
  "permissions": {
    "additionalDirectories": [
      "/path/to/frontend",
      "/path/to/backend",
      "/path/to/shared-libs"
    ]
  }
}

状态栏配置与 /statusline

自定义状态栏中显示的信息：

# 配置状态栏
/statusline

# 选项通常包括：
# - 当前模型
# - Token 使用情况
# - 会话时长
# - 活跃工具
# - 后台进程

好处：

• 实时监控 Token 使用情况
• 跟踪会话时长
• 查看活跃的后台进程
• 了解正在使用的工具

来源: CLI 参考

快速入门指南

您的第一个会话

# 1. 导航到您的项目
cd /path/to/your/project

# 2. 启动 Claude Code
claude

# 3. 让 Claude 了解您的项目
> “阅读代码库并解释项目结构”

# Claude 将会：
- 查找 README、package.json 或类似的入口文件
- 阅读相关文件（首次会询问权限）
- 分析代码结构
- 提供总结

# 4. 请求分析
> “检查认证系统是否存在安全问题”

# Claude 将会：
- 找到与认证相关的文件
- 分析实现方式
- 识别潜在漏洞
- 提出改进建议

# 5. 进行更改
> “在登录接口上添加限流功能”

# Claude 将会：
- 规划实现方案
- 展示将要进行的更改
- 请求编辑文件的权限
- 实施更改
- 可以运行测试来验证

# 6. 创建提交
> “为这些更改创建一个 Git 提交”

# Claude 将会：
- 运行 git status 查看更改
- 审查 git diff
- 创建描述性的提交信息
- 提交更改

为 Claude Code 设置您的项目

1. 创建 CLAUDE.md [社区]

这提供了在所有会话中持续存在的上下文：

# 让 Claude 帮助创建
> “创建一个 CLAUDE.md 文件，记录该项目的结构、命令和规范”

# 或者手动创建：
- 使用的语言和框架
- 重要命令（开发、测试、构建、代码检查）
- 项目结构概述
- 编码规范
- 已知的陷阱或问题

2. 配置权限（可选）[官方]

在您的项目中创建 .claude/settings.json：

{
  "permissions": {
    "defaultMode": "ask",
    "allow": {
      "Bash": [
        "npm test",
        "npm run*",
        "git status",
        "git diff",
        "git log*"
      ],
      "Read": {},
      "Grep": {},
      "Glob": {}
    },
    "deny": {
      "Write": ["*.env", ".env.*"],
      "Edit": ["*.env", ".env.*", ".git/*"]
    }
  }
}

此配置：

• 允许常见的安全命令而无需询问
• 阻止编辑敏感文件
• 仍然会为文件修改请求权限

3. 测试设置

> “运行测试”
# 如果已配置，应无需权限提示即可执行

> “有哪些可用的命令？”
# Claude 将会读取 package.json 并列出脚本

> “CLAUDE.md 里写了什么？”
# Claude 将会读取并总结您的项目背景

来源: 快速入门、设置

高级功能

思考模式 [官方]

Claude Code 支持扩展思考，适用于复杂的推理任务。Opus 4.5 默认启用了思考模式。

激活方法：

# 使用快捷键切换
Alt+T（或 macOS 上的 Option+T） # 切换思考模式的开启与关闭

# 或者使用自然语言
> “思考一下这个问题”
> “更深入地思考架构问题”
> “针对这个安全问题进行超深度思考”

# Tab 键（粘性切换）
按下 Tab 键可在后续提示中保持思考模式的开启或关闭状态

思考级别：

最佳实践：

• 对于复杂问题的调试，使用 think harder
• 对于架构决策或安全审查，使用 ultrathink
• 思考内容可以在 Ctrl+O 的转录模式中查看
• 思考模式具有粘性——除非手动关闭，否则会一直保持开启状态

来源: 思考模式

快速模式 [新] [官方]

快速模式是 Claude Opus 4.6 的高速配置，使响应速度提升 2.5 倍，但每 token 的成本更高。自 v2.1.36 版本起可用。

切换快速模式：

# 使用内置命令切换
/fast          # 开启或关闭快速模式

# 或在设置中启用
"fastMode": true   # 在用户设置文件中

视觉指示器：

• 当快速模式激活时，提示旁边会出现 ↯ 图标
• 在速率限制冷却期间，图标会变为灰色

定价（每 MTok）：

注意： 快速模式在 2026 年 2 月 16 日之前享受 50% 折扣。

要求：

• 需要有 Claude 订阅计划（Pro/Max/Team/Enterprise）或 Claude Console API
• 需启用额外用量（/extra-usage）
• 不适用于第三方提供商（Bedrock、Vertex、Azure Foundry）
• 对于团队/企业版：管理员必须在组织设置中启用

何时使用：

• ✅ 快速迭代代码更改
• ✅ 实时调试会话
• ✅ 时间敏感的工作
• ❌ 长时间的自主任务（成本较高）
• ❌ 批量处理或 CI/CD 流程

快速模式与努力等级：

您可以将两者结合使用，以在简单任务上获得最大速度。

速率限制：

• 与标准 Opus 4.6 的速率限制分开
• 冷却期间会自动回落到标准模式
• 冷却结束后重新启用

来源: 快速模式

计划模式 [官方]

计划模式通过选择合适的模型，为复杂任务提供结构化的规划。

# 进入计划模式
/plan

# 或者 Claude 可能会在遇到复杂任务时建议进入计划模式
> “实现一个完整的认证系统”

# 克劳德：“这是一项复杂的任务。您希望我先制定一个计划吗？”

计划模式功能：

• Opus规划，Sonnet执行 - 使用更强的模型进行规划，更快的模型进行实施
• SonnetPlan模式 - Sonnet规划，Haiku执行（经济高效）
• Shift+Tab - 在计划模式下自动接受编辑
• 计划持久化 - 计划在 /clear 后仍会保留

计划模式工作流程：

1. 克劳德分析任务并创建结构化计划
2. 您审查并批准或修改计划
3. 克劳德逐步执行计划
4. 进度通过TodoWrite进行跟踪

来源: 计划模式

后台任务与代理 [官方]

在继续工作的同时，在后台运行命令和代理。

快捷键：

Ctrl+B  # 将当前命令或代理置于后台（统一快捷键）

后台命令：

# 在后台启动命令
> “在后台运行开发服务器”
> “在后台以监听模式启动测试”

# 或者在命令前加上 &
> “& npm run dev”

# 查看后台任务
/tasks
/bashes

# 杀死某个后台任务
/kill <任务编号>

后台代理：

# 在后台启动代理
> “让Explore代理在后台分析代码库架构”

# 代理异步运行，并在完成时通知您
# 当后台代理完成时，您会收到唤醒消息

特性：

• 实时输出流到状态栏
• 任务完成时的唤醒通知
• 多个并发后台进程
• 大量输出可持久化到文件中

来源: 后台任务

自动记忆 [新功能]

Claude Code 现在会在工作时自动记录和回忆记忆（v2.1.32及以上版本）。

工作原理：

• 克劳德会自动记住重要的上下文、决策和模式
• 记忆会跨会话保存，并为未来的工作提供参考
• 无需手动干预

代理的记忆范围：

---
name: my-agent
memory: project  # 选项：user, project, local
---

禁用自动记忆：

export CLAUDE_CODE_DISABLE_AUTO_MEMORY=1

键盘快捷键 [官方]

导航与编辑：

模型与模式切换：

输入与提交：

图片与文件处理：

Vim绑定（若启用）：

登录与认证：

Bash模式自动补全 [新功能 v2.1.14]：

提示建议 [官方]

Claude Code 会根据上下文提供建议提示（默认已启用）。

# 克劳德会给出上下文相关的提示
> _  # 光标闪烁
# 出现建议：“回顾我们所做的更改”

# 按Tab键编辑建议
Tab → 编辑建议内容

# 按Enter键立即提交
Enter → 按原样提交建议

配置：

# 在/config中切换
/config
# 搜索“提示建议”
# 切换开启/关闭

环境变量 [官方]

核心配置：

显示与 UI：

Bash 与命令：

模型配置：

MCP 配置：

文件与上下文：

网络与代理：

自动更新与插件：

监控与遥测：

高级设置：

新设置 [官方]

近期新增的设置（可在 /config 或 settings.json 中配置）：

{
  // 回应语言
  "language": "en",  // Claude 的回应语言

  // Git 集成
  "attribution": true,  // 在提交署名中添加模型名称
  "respectGitignore": true,  // 搜索时尊重 .gitignore

  // UI 偏好
  "showTurnDuration": true,  // 显示回合持续时间消息
  "fileSuggestion": "custom-cmd",  // 自定义 @ 文件搜索命令
  "spinnerVerbs": ["analyzing", "thinking", "processing"],  // 自定义旋转动画文案
  "prefersReducedMotion": false,  // 减少 UI 动画以提升可访问性 [新增 v2.1.30]

  // 会话行为
  "companyAnnouncements": true,  // 显示公司公告

  // 计划模式
  "plansDirectory": ".claude/plans"  // 自定义计划文件目录
}

技能变量替换： [新增]

# 在技能文件中，使用 ${CLAUDE_SESSION_ID} 进行会话特定的操作
会话 ID：${CLAUDE_SESSION_ID}

项目规则：

# 新增：.claude/rules/ 目录用于项目特定规则
.claude/rules/
├── coding-style.md      # 编码规范
├── testing.md           # 测试要求
└── security.md          # 安全指南

通配符权限：

{
  "permissions": {
    "allow": {
      "Bash": ["npm *", "git *"],  // 通配符模式
      "mcp__myserver__*": {}       // MCP 工具通配符
    }
  }
}

技能系统

技能是统一的功能模块，扩展了 Claude Code 的能力——既可以由 Claude 自动激活，也可以通过 /技能名 手动调用。

注意： 自定义斜杠命令（.claude/commands/ 文件）已于 v2.1.3 合并到技能中。你现有的命令文件仍可继续使用。建议新工作采用技能，因为它支持附加功能，如支持文件、调用控制和子代理执行。请参阅 命令迁移至技能。

Claude Code 的技能遵循 Agent Skills 开放标准，该标准适用于多种 AI 工具。Claude Code 在此基础上增加了调用控制、子代理执行和动态上下文注入等功能。

什么是技能？[官方]

技能是以 SKILL.md 文件形式封装的指令，用于扩展 Claude Code 的功能。Claude 会在相关请求时加载这些技能，或者你可以直接调用它们：

# Claude 根据你的请求自动激活技能
你： “检查这段代码是否存在安全问题”
Claude： [自动加载安全审查技能]

# 或者你直接调用技能
你： /security-reviewer src/auth.ts
Claude： [加载并执行安全审查技能]

两种类型的技能内容：

• 参考内容 — Claude 应用于当前工作的知识（规范、模式、风格指南）。在对话上下文中内联运行。
• 任务内容 — 针对特定操作的分步说明（部署、提交、代码生成）。通常通过 /技能名 手动调用。

技能的存储位置 [官方]

技能的存储位置决定了谁可以使用它：

当多个技能具有相同名称时，优先级较高的位置会生效：企业级 > 个人级 > 项目级。插件技能使用 plugin-name:skill-name 命名空间，因此不会发生冲突。

旧版兼容性： .claude/commands/ 中的文件仍然有效，并支持相同的 frontmatter。如果某个技能和命令同名，则技能优先。

自动检测嵌套目录： 当您在子目录中工作时，Claude Code 会从嵌套的 .claude/skills/ 目录中发现技能。例如，在 packages/frontend/ 中编辑文件时，也会加载 packages/frontend/.claude/skills/ 中的技能。这支持多仓库（monorepo）结构，其中每个包都有自己的技能。

实时更改检测： 通过 --add-dir 添加的目录中的技能会自动加载，并被实时更改检测机制捕获——您可以在会话期间直接编辑这些技能，无需重启。

技能目录结构 [官方]

每个技能都是一个包含 SKILL.md 作为入口文件的目录：

my-skill/
├── SKILL.md           # 主要说明文档（必填）
├── template.md        # Claude 可填充的模板（可选）
├── examples/
│   └── sample.md      # 示例输出（可选）
└── scripts/
    └── validate.sh    # Claude 可执行的脚本（可选）

在 SKILL.md 中引用辅助文件，以便 Claude 知道每个文件的内容：

## 附加资源
- 完整的 API 详情，请参阅 [reference.md](reference.md)
- 使用示例，请参阅 [examples.md](examples.md)

提示： 将 SKILL.md 保持在 500 行以内。将详细参考材料移至单独的文件。

创建技能 [官方]

步骤 1： 创建技能目录：

# 个人技能（在所有项目中可用）
mkdir -p ~/.claude/skills/explain-code

# 项目技能（通过 git 与团队共享）
mkdir -p .claude/skills/explain-code

步骤 2： 编写带有 frontmatter 和说明的 SKILL.md：

---
name: explain-code
description: 用可视化图表和类比解释代码。适用于解释代码如何运行、讲解代码库，或当用户询问“这是如何工作的？”时。
---

解释代码时，务必包括以下内容：

1. **从类比开始**：将代码与日常生活中的事物进行比较
2. **绘制图表**：使用 ASCII 艺术展示流程、结构或关系
3. **逐步解释代码**：逐行说明代码的执行过程
4. **指出常见陷阱**：常见的错误或误解是什么？

保持解释的对话式风格。对于复杂概念，可以使用多种类比。

步骤 3： 测试技能：

# 让 Claude 自动调用
> “这段代码是如何工作的？”

# 或直接调用
> /explain-code src/auth/login.ts

Frontmatter 参考 [官方]

通过在 SKILL.md 文件顶部的 --- 标记之间的 YAML frontmatter 配置技能行为。所有字段均为可选；仅建议填写 description。

控制技能调用 [官方]

默认情况下，您和 Claude 都可以调用任何技能。有两个 frontmatter 字段可以限制这一行为：

• disable-model-invocation: true — 只有您可以调用。适用于具有副作用的工作流（如 /deploy、/commit）。
• user-invocable: false — only Claude can invoke. Use for background knowledge that isn't actionable as a command.

# 仅供用户调用的技能（Claude 不会自动触发）
---
name: deploy
description: 将应用程序部署到生产环境
disable-model-invocation: true
---

# 仅供模型调用的技能（隐藏在 / 菜单之外）
---
name: legacy-system-context
description: 关于遗留系统的背景知识
user-invocable: false
---

调用与上下文加载行为：

通过 /permissions 限制 Claude 的访问权限：

# 仅允许特定技能
Skill(commit)
Skill(review-pr *)

# 拒绝特定技能
Skill(deploy *)

# 禁用所有技能
Skill    # 添加到拒绝规则中

权限语法：Skill(name) 用于精确匹配，Skill(name *) 用于前缀匹配，后跟任意参数。

传递参数 [官方]

技能通过占位符替换接受参数：

示例：

---
name: fix-issue
description: 修复 GitHub 问题
disable-model-invocation: true
---

按照我们的编码标准修复 GitHub 问题 $ARGUMENTS。

1. 阅读问题描述
2. 实施修复
3. 编写测试
4. 提交更改

/fix-issue 123
# Claude 接收到：“按照我们的编码标准修复 GitHub 问题 123……”

索引参数：

---
name: compare-files
description: 比较两个文件
---

# 比较：$ARGUMENTS[0] 与 $ARGUMENTS[1]

# 缩写：$0 与 $1

比较 $0 和 $1 的差异。

/compare-files "src/v1/api.ts" "src/v2/api.ts"
# $0 = "src/v1/api.ts", $1 = "src/v2/api.ts"

如果技能内容中不存在 $ARGUMENTS，参数将以 ARGUMENTS: <value> 的形式追加。

高级模式 [官方]

动态上下文注入

!`command` 语法会在技能内容发送给 Claude 之前运行 Shell 命令。命令的输出会替换占位符：

---
name: pr-summary
description: 总结拉取请求中的更改
context: fork
agent: Explore
allowed-tools: Bash(gh *)
---

## 拉取请求上下文
- PR 差异：!`gh pr diff`
- PR 评论：!`gh pr view --comments`
- 更改文件：!`gh pr diff --name-only`

## 你的任务
总结这个拉取请求……

每个 !`command` 都会立即执行（在 Claude 看到任何内容之前）。Claude 只能看到包含实际数据的最终结果。

在子代理中运行

添加 context: fork 可以让技能独立运行。技能内容会成为驱动子代理的提示（无法访问对话历史）：

---
name: deep-research
description: 深入研究某个主题
context: fork
agent: Explore
---

深入研究 $ARGUMENTS：

1. 使用 Glob 和 Grep 查找相关文件
2. 阅读并分析代码
3. 总结发现，并附上具体的文件引用

agent 字段指定要使用的子代理。选项包括内置代理（Explore、Plan、通用型）或来自 .claude/agents/ 的自定义子代理。默认为通用型。

警告： context: fork 只适用于具有明确指令的技能。如果没有任务指引的技能将不会返回有意义的输出。

扩展思考

要在技能中启用扩展思考功能，在技能内容中的任意位置加入 ultrathink 一词：

---
name: architecture-review
description: 深度架构分析
---

使用 ultrathink 对架构进行深度分析。

审查整体结构，识别模式，并提出改进建议。

实用示例

示例：代码审查技能

.claude/skills/code-reviewer/SKILL.md:

---
name: code-reviewer
description: 审查代码中的安全漏洞、Bug、性能问题以及代码风格问题。当用户要求审查、审计或检查代码质量时使用此技能。
allowed-tools: [Read, Grep, Glob]
---

# 代码审查技能

## 激活时机
当用户要求以下内容时使用此技能：
- 审查代码中的问题
- 进行安全审计或查找漏洞
- 检查代码质量或最佳实践

## 审查流程

### 1. 范围检测
- 使用 Glob 确定需要审查的文件
- 优先考虑最近修改的文件
- 如果提到特定区域，则重点关注该区域

### 2. 分层分析
- **安全**：SQL 注入、XSS、认证问题、敏感信息泄露
- **Bug**：逻辑错误、空值检查、错误处理
- **性能**：N+1 查询、不必要的循环、内存泄漏
- **风格**：命名规范、代码组织、可读性

### 3. 报告
提供按严重程度分类的结构化反馈：
- **严重/高危**：安全问题
- **中等**：性能问题
- **低危**：代码风格和最佳实践

每个问题都应包含文件路径、描述及修复建议。

示例：测试生成技能

.claude/skills/test-generator/SKILL.md:

---
name: test-generator
description: 生成全面的单元测试和集成测试。当用户要求编写测试、增加测试覆盖率或创建测试用例时使用此技能。
allowed-tools: [Read, Write, Grep, Glob, Bash]
---

# 测试生成技能

## 激活时机
当用户提出以下请求时使用此技能：
- “为……编写测试”
- “增加测试覆盖率”
- “生成测试用例”

## 测试生成流程

### 1. 分析目标代码
- 阅读待测试的文件或函数
- 确定输入、输出及副作用
- 检查现有的测试模式

### 2. 生成全面测试
覆盖所有场景：
- 正常流程（预期使用情况）
- 错误情况（无效输入）
- 边界情况（空值、null、边界值）
- 副作用（数据库操作、API 调用）

### 3. 遵循项目规范
- 查看 CLAUDE.md 中的测试约定
- 匹配现有测试文件结构
- 使用项目的测试框架

示例：安全审查技能

.claude/skills/security-review/SKILL.md:

---
name: security-review
description: 对代码库进行全面的安全审计。当被要求审查安全性、审计漏洞或检查是否存在利用风险时使用此技能。
allowed-tools: [Read, Grep, Glob]
disable-model-invocation: true
---

# 安全审查：$ARGUMENTS

针对：$ARGUMENTS 进行彻底的安全审计

## 审查清单

### 1. 认证与授权
- 检查弱密码策略
- 验证 JWT 令牌验证机制
- 审查会话管理
- 检查访问控制是否失效

### 2. 输入验证
- SQL 注入漏洞
- XSS（跨站脚本攻击）风险
- 命令注入的可能性
- 路径遍历漏洞

### 3. 数据保护
- 敏感数据暴露
- 静态及传输中的加密
- 代码中是否存在 API 密钥和机密信息
- 数据库凭证的安全性

### 4. 依赖项
- 包中已知的漏洞
- 过时的依赖包
- 许可证合规问题

### 5. 配置
- 安全头设置（CSP、HSTS 等）
- CORS 配置
- 是否有错误信息泄露
- 生产环境中是否开启了调试模式

**输出格式** - 提供详细的报告，分为以下几个部分：
- 严重问题（需立即修复）
- 高优先级
- 中优先级
- 低优先级 / 建议
- 安全优势
- 行动计划（按优先级排列的修复清单）

使用方法：

/security-review "authentication and API endpoints"

示例：API 文档生成技能

.claude/skills/api-docs/SKILL.md:

---
name: api-docs
description: 根据代码生成全面的 API 文档。当被要求记录 API、创建 API 文档或生成 OpenAPI 规范时使用此技能。
allowed-tools: [Read, Write, Grep, Glob]
disable-model-invocation: true
---

# 生成 API 文档

分析代码库，为：$ARGUMENTS 生成全面的 API 文档

## 流程

### 1. 发现
- 找到所有 API 路由/端点
- 确定请求/响应类型
- 记录认证要求
- 文档化查询参数

### 2. 文档化
对于每个端点，记录：
- 方法和路径
- 描述
- 认证要求
- 请求体/参数
- 响应码和响应内容
- 示例请求

### 3. 输出
- 创建 `/docs/API.md` 包含完整文档
- 如适用，创建 `/openapi.yaml` 包含 OpenAPI 规范

使用方法：

/api-docs "all endpoints"
/api-docs "authentication routes"

文件引用与 @ 语法 [官方]

使用 @ 前缀快速引用文件：

# 引用单个文件
/review-code @src/auth.ts

# 引用多个文件
/review-code @src/auth.ts @src/api.ts @tests/auth.test.ts

# 也可用于普通提示
> “审查 @src/services/payment.ts 中的安全问题”

# 引用包含技能参数的文件
/analyze-file @src/components/UserProfile.tsx

@ 引用的工作原理：

• @filename 会自动展开以包含文件内容
• 支持绝对路径和相对路径
• 可以在一个命令中引用多个文件
• 文件会被自动读取并纳入上下文中
• 减少了显式指定“先读取文件X”的需求

使用场景：

# 带上下文的代码审查
> "比较 @src/api/v1.ts 和 @src/api/v2.ts，并列出差异"

# 跨文件重构
> "使 @src/models/User.ts 与 @src/types/user.d.ts 保持一致"

# Bug调查
> "此错误发生在 @src/services/auth.ts 中，请查看 @logs/error.log 寻找线索"

# 测试生成
> "为 @src/utils/validator.ts 生成测试"

最佳实践：

• 当你知道确切的文件路径时使用 @ 引用
• 结合技能以实现可重用的工作流
• 非常适合对特定文件进行聚焦分析
• 相比读取整个目录，能减少令牌使用量

MCP集成 [官方]

MCP服务器可以暴露提示，这些提示会自动成为可调用的技能：

{
  "prompts": [
    {
      "name": "search-docs",
      "description": "搜索内部文档",
      "arguments": [{"name": "query", "description": "搜索查询"}]
    }
  ]
}

这将在Claude Code中作为 /search-docs 可用。

# 添加MCP服务器
claude mcp add github -- gh-mcp

# MCP提示会变成技能：
/github-pr-review      # 审查当前PR
/github-issues         # 列出未解决问题
/github-create-pr      # 从当前分支创建PR

技能最佳实践 [官方]

1. 编写清晰、具体的描述

description字段至关重要——它帮助Claude决定何时激活技能：

好的：

description: "根据代码注释生成API文档。当用户请求记录API、创建API文档、更新端点文档或生成OpenAPI规范时使用。"

坏的：

description: "文档生成器"  # 太模糊

2. 使用自然触发词

包含用户自然会说的术语：

# 用于安全审查技能
description: "审查代码安全性。当被要求：审查安全、审计代码、查找漏洞、检查是否存在利用、分析风险时使用。"

# 用于性能优化技能
description: "优化代码性能。当被要求：提升性能、优化速度、减少内存使用、加快速度、对代码进行性能分析时使用。"

3. 适当限制工具

# 仅限分析（不能修改代码）
allowed-tools: [Read, Grep, Glob]

# 可以创建/修改代码
allowed-tools: [Read, Write, Edit, Bash]

# 研究与实施
allowed-tools: [Read, Write, Edit, WebFetch, WebSearch]

4. 保持技能专注

好的（专注）：

• sql-optimizer — 仅优化SQL查询
• api-docs-generator — 生成API文档
• security-scanner — 查找安全问题

坏的（过于宽泛）：

• database-everything — 太模糊
• code-helper — 帮助什么？

5. 提供清晰的说明

按照以下结构编写SKILL.md：

1. 何时激活 — 清晰的触发条件
2. 流程 — 分步骤的操作指南
3. 输出格式 — 如何呈现结果
4. 示例 — 展示预期行为

6. 注意上下文预算

技能描述会被加载到上下文中，以便Claude知道有哪些可用技能。如果有太多技能，可能会超出字符预算（上下文窗口的2%，默认为16,000字符）。运行 /context 来检查是否有被排除技能的警告。

可以通过设置环境变量 SLASH_COMMAND_TOOL_CHAR_BUDGET 来覆盖此限制。

技能故障排除 [官方]

技能未触发：

1. 检查描述是否包含用户自然会说的关键词
2. 确认在输入“有哪些可用技能？”时技能是否出现
3. 尝试改写请求以匹配描述
4. 直接使用 /技能名 调用，确认其是否正常工作

技能触发过于频繁：

1. 使描述更加具体
2. 添加 disable-model-invocation: true 以实现仅手动调用

Claude看不到所有技能：

• 如果技能描述过多，可能会超出字符预算
• 运行 /context 检查是否有被排除技能的警告
• 设置 SLASH_COMMAND_TOOL_CHAR_BUDGET 为更高的值

迁移：命令到技能

自定义斜杠命令（.claude/commands/文件）已被合并到技能系统中。您现有的命令文件仍可继续使用且无需更改。 对于新工作，建议使用技能，因为它们支持：

• 支持文件 — 可将模板、脚本和参考文档与您的技能打包在一起
• 调用控制 — 可选择由您、Claude或两者共同调用
• 子代理执行 — 在隔离的分叉上下文中运行技能
• 嵌套发现 — 自动从子目录加载（支持monorepo）

迁移路径：

# 旧结构（仍然有效）
.claude/commands/review.md

# 新结构（推荐）
.claude/skills/review/SKILL.md

两者都会创建 /review 并以相同的方式工作。如果两者同时存在，则技能优先。

来源： Agent Skills

内置命令

内置命令是用于管理Claude Code会话的原生CLI命令。 它们被硬编码到Claude Code中，而不是技能——您无法自定义或覆盖它们。

注意： 对于自定义工作流命令，请使用技能代替。像 /help 和 /compact 这样的内置命令无法通过技能工具使用。

命令参考 [官方]

# 会话管理
/help              # 显示所有可用命令
/exit              # 结束当前会话
/clear             # 清除对话历史
/compact [instr]   # 整理上下文（可选指定关注的内容）
/rewind            # 撤销对话中的代码更改

# 会话与历史
/rename <name>     # 为当前会话命名
/resume [name|id]  # 根据名称或ID恢复之前的会话
/export            # 将对话导出为文件
/copy              # 将最后一条回复复制到剪贴板 [新功能]

# 使用情况与统计
/usage             # 查看套餐限额及使用情况 [新功能]
/stats             # 使用统计与参与度指标（支持7天/30天/全部时间） [新功能]
/extra-usage       # 为Max套餐订阅者启用额外使用额度 [新功能]
/fast              # 切换快速模式（使用更快的模型，需先启用/extra-usage） [新功能]

# 后台进程管理
/bashes            # 列出所有后台进程
/tasks             # 列出所有后台任务（代理、Shell等）
/kill <id>         # 停止某个后台进程

# 发现与调试
/bug               # 报告错误（将对话发送至 Anthropic）
/commands          # 列出所有技能和命令
/debug             # 诊断会话问题 [新功能 v2.1.30]
/hooks             # 显示已配置的钩子
/skills            # 列出可用的技能
/plugin            # 插件管理界面
/context           # 以彩色网格形式查看当前上下文使用情况
/cost              # 显示 token 使用统计信息
/doctor            # 运行诊断程序（显示带有自动更新频道的更新部分）

# 配置
/config            # 常规设置（可键入搜索和筛选）
/permissions       # 管理工具权限（支持搜索）
/privacy-settings  # 查看并更新隐私设置
/status            # 显示会话状态（状态选项卡）
/statusline        # 配置状态栏显示
/model             # 切换模型
/output-style      # 直接或通过选择菜单设置输出样式
/theme             # 主题选择器（Ctrl+T 切换语法高亮）
/terminal-setup    # 配置终端（Kitty、Alacritty、Zed、Warp）
/vim               # 进入 vim 模式，可在插入模式和命令模式之间切换
/sandbox           # 启用沙盒化的 bash，具备文件系统和网络隔离

# 工作区管理
/add-dir <path>    # 向工作区添加额外目录
/agents            # 管理自定义 AI 子代理
/init              # 使用 CLAUDE.md 指南初始化项目
/memory            # 编辑 CLAUDE.md 内存文件
/install-github-app # 为仓库设置 Claude GitHub Actions
/pr-comments       # 查看拉取请求评论
/review            # 请求代码审查
/security-review   # 完成待处理更改的安全审查
/todos             # 列出当前待办事项

# MCP 服务器管理
/mcp               # MCP 服务器管理和 OAuth 认证
/mcp enable <srv>  # 启用一个 MCP 服务器
/mcp disable <srv> # 禁用一个 MCP 服务器

# 远程会话（claude.ai 订阅用户）
/teleport          # 通过会话 ID 从 claude.ai 恢复远程会话
/remote-env        # 配置远程会话环境

# 账户与更新
/login             # 切换 Anthropic 账户
/logout            # 退出 Anthropic 账户
/release-notes     # 查看发布说明

# 计划模式
/plan              # 进入计划模式，进行结构化规划

来源: CLI 参考、交互模式

钩子系统

钩子是自动化脚本，在 Claude Code 工作流中的特定点执行。

什么是钩子？[官方]

钩子允许你 拦截并控制 Claude 的行为：

# 钩子可以实现的功能示例：
- 阻止编辑敏感文件（如 .env）
- 在会话开始时注入上下文
- 在文件编辑前运行代码检查
- 验证 Git 提交
- 审计所有执行的命令
- 添加自定义安全检查

两种类型：

1. Bash 命令钩子 (type: "command") - 执行 Shell 脚本
2. 基于提示的钩子 (type: "prompt") - 使用 LLM 进行上下文感知决策

钩子配置 [官方]

钩子在 .claude/settings.json 或 ~/.claude/settings.json 中配置：

{
  "hooks": {
    "EventName": [
      {
        "matcher": "ToolPattern",
        "hooks": [
          {"type": "command", "command": "script"}
        ]
      }
    ]
  }
}

钩子事件 [官方]

示例：保护敏感文件 [官方]

.claude/settings.json:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "bash -c 'FILE=$(echo \"$HOOK_INPUT\" | jq -r \".tool_input.file_path // empty\"); if [[ \"$FILE\" == *\".env\"* ]] || [[ \"$FILE\" == \".git/\"* ]]; then echo \"Cannot modify sensitive files\" >&2; exit 2; fi'"
          }
        ]
      }
    ]
  }
}

工作原理：

• 在任何 Edit 或 Write 工具执行前运行
• 检查文件路径是否包含 ".env" 或 ".git/"
• 以退出码 2 阻止操作
• Claude 收到错误消息，不会编辑该文件

示例：会话上下文注入 [官方]

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "cat .claude/session-context.txt"
          }
        ]
      }
    ]
  }
}

创建内容： .claude/session-context.txt

今日重点：进行身份验证重构
近期背景：已从会话迁移到 JWT
当前分支：feature/jwt-auth
重要提醒：请勿修改 /old-auth 中的旧版认证代码

此上下文会在每次会话开始时被注入。

示例：智能决策钩子 [官方]

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "prompt",
            "prompt": "评估当前任务是否已完成。参数：$ARGUMENTS。检查所有子任务是否完成、测试是否通过以及文档是否更新。请回复 {\"decision\": \"stop\" 或 \"continue\", \"reason\": \"解释\"}"
          }
        ]
      }
    ]
  }
}

使用 LLM（Haiku）智能判断 Claude 是否应停止工作。

钩子输入/输出 [官方]

输入（通过 stdin 以 JSON 格式传递）：

{
  "sessionId": "abc123",
  "tool_name": "Edit",
  "tool_input": {
    "file_path": "/src/app.ts",
    "old_string": "...",
    "new_string": "..."
  },
  "project_dir": "/home/user/project"
}

输出（退出码）：

• 0 - 成功，继续
• 2 - 阻止操作
• 其他 - 非阻断性错误（记录日志）

JSON 输出（可选）：

{
  "decision": "stop",
  "reason": "所有任务已完成",
  "continue": false
}

安全最佳实践 [官方]

⚠️ 重要提示： “使用钩子时，您需对所配置的命令承担全部责任，这些命令可能会修改或删除您用户有权访问的文件。”

最佳实践：

# 1. 始终对变量加引号
FILE="$HOOK_INPUT"  # 正确
FILE=$HOOK_INPUT    # 错误 - 包含空格时可能出错

# 2. 验证路径
if [[ "$FILE" == ../* ]]; then
  echo "路径遍历尝试" >&2
  exit 2
fi

# 3. 使用绝对路径
cd "$CLAUDE_PROJECT_DIR" || exit 1

# 4. 对输入进行清理
jq -r '.tool_input.file_path' <<< "$HOOK_INPUT"  # 好
eval "$SOME_VAR"  # 不好 - 存在代码注入风险

# 5. 阻止敏感操作
case "$FILE" in
  *.env|.git/*|.ssh/*)
    echo "已阻止：敏感文件" >&2
    exit 2
    ;;
esac

调试钩子 [官方]

# 以调试模式运行 Claude
claude --debug

# 检查钩子配置
> /hooks

# 手动测试钩子命令
echo '{"tool_name":"Edit","tool_input":{"file_path":".env"}}' | bash your-hook-script.sh

# 查看日志
tail -f ~/.claude/logs/claude.log

钩子配方库 [官方 + 社区]

全面的生产就绪型钩子模式集合，满足常见的自动化需求。

1. 保存时自动格式化代码 [社区]

使用适合语言的格式化工具，在 Claude 编辑文件后自动格式化代码。

配置（.claude/settings.json）：

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|MultiEdit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "bash ~/.claude/hooks/format-code.sh"
          }
        ]
      }
    ]
  }
}

脚本（~/.claude/hooks/format-code.sh）：

#!/bin/bash
# 从 JSON 输入中提取文件路径
FILE=$(echo "$HOOK_INPUT" | jq -r '.tool_input.file_path // empty')

[[ -z "$FILE" ]] && exit 0

# 根据文件扩展名进行格式化
case "$FILE" in
  *.ts|*.tsx|*.js|*.jsx)
    # 先尝试 Biome，若失败则使用 Prettier
    if command -v biome &> /dev/null; then
      biome format --write "$FILE" &> /dev/null || true
    elif command -v prettier &> /dev/null; then
      prettier --write "$FILE" &> /dev/null || true
    fi
    ;;
  *.py)
    # Python：Ruff
    if command -v ruff &> /dev/null; then
      ruff format "$FILE" &> /dev/null || true
    fi
    ;;
  *.go)
    # Go：goimports + gofmt
    if command -v goimports &> /dev/null; then
      goimports -w "$FILE" &> /dev/null || true
    fi
    go fmt "$FILE" &> /dev/null || true
    ;;
  *.md)
    # Markdown：Prettier
    if command -v prettier &> /dev/null; then
      prettier --write "$FILE" &> /dev/null || true
    fi
    ;;
esac

赋予可执行权限： chmod +x ~/.claude/hooks/format-code.sh

2. 编辑时自动修复 ESLint [社区]

自动对 JavaScript/TypeScript 文件运行带有 --fix 选项的 ESLint。

配置：

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|MultiEdit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "bash -c 'FILE=$(echo \"$HOOK_INPUT\" | jq -r \".tool_input.file_path // empty\"); if [[ \"$FILE\" =~ \\.(ts|tsx|js|jsx)$ ]] && command -v eslint &>/dev/null; then eslint --fix \"$FILE\" &>/dev/null || true; fi'"
          }
        ]
      }
    ]
  }
}

3. 阻止读取 .gitignore 匹配的文件 [社区]

防止 Claude 读取与 .claudeignore 模式匹配的文件。

配置：

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Read",
        "hooks": [
          {
            "type": "command",
            "command": "claude-ignore"
          }
        ]
      }
    ]
  }
}

安装： npm install -g claude-ignore && claude-ignore init

4. 提交前运行测试 [社区]

在允许 Git 提交之前，验证测试是否通过。

配置：

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "bash ~/.claude/hooks/pre-commit-test.sh"
          }
        ]
      }
    ]
  }
}

脚本（~/.claude/hooks/pre-commit-test.sh）：

#!/bin/bash
COMMAND=$(echo "$HOOK_INPUT" | jq -r '.tool_input.command // empty')

# 只拦截 git commit 命令
if [[ "$COMMAND" == git*commit* ]]; then
  echo "正在提交前运行测试..." >&2

  # 运行测试
  if npm test &>/dev/null; then
    echo "✅ 测试通过" >&2
    exit 0
  else
    echo "❌ 测试失败 - 阻止提交" >&2
    exit 2
  fi
fi

exit 0

5. 审计日志钩子 [社区]

记录所有工具使用情况，用于安全审计。

配置：

{
  "hooks": {
    "PostToolUse": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "bash -c 'echo \"$(date -Iseconds) $TOOL_NAME: $(echo \\\"$HOOK_INPUT\\\" | jq -c .)\" >> ~/.claude/audit.log'"
          }
        ]
      }
    ]
  }
}

6. Token 使用量跟踪器 [社区]

监控并记录每个会话的 Token 使用情况。

配置：

{
  "hooks": {
    "SessionEnd": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "bash ~/.claude/hooks/log-session.sh"
          }
        ]
      }
    ]
  }
}

脚本：

#!/bin/bash
SESSION_ID=$(echo "$HOOK_INPUT" | jq -r '.session_id // "unknown"')
TRANSCRIPT=$(echo "$HOOK_INPUT" | jq -r '.transcript_path // empty')

if [[ -f "$TRANSCRIPT" ]]; then
  TOKENS=$(jq '[.[] | select(.role=="assistant") | .usage.total_tokens] | add' "$TRANSCRIPT" 2>/dev/null || echo 0)
  echo "$(date -Iseconds) 会话 $SESSION_ID: $TOKENS tokens" >> ~/.claude/token-usage.log
fi

7. 提交信息验证 [社区]

强制遵守规范化的提交信息格式。

配置：

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "bash ~/.claude/hooks/validate-commit.sh"
          }
        ]
      }
    ]
  }
}

脚本：

#!/bin/bash
COMMAND=$(echo "$HOOK_INPUT" | jq -r '.tool_input.command // empty')

if [[ "$COMMAND" == git*commit*-m* ]]; then
  MSG=$(echo "$COMMAND" | sed -n 's/.*-m[[:space:]]*["'"'"']\([^"'"'"']*\)["'"'"'].*/\1/p')

  # 检查规范化的提交格式：type(scope): message
  if [[ ! "$MSG" =~ ^(feat|fix|docs|style|refactor|test|chore)(\(.+\))?: ]]; then
    echo "❌ 提交信息必须遵循格式：type(scope): message" >&2
    echo "有效类型：feat, fix, docs, style, refactor, test, chore" >&2
    exit 2
  fi
fi

exit 0

8. 安全密钥扫描器 [社区]

防止提交包含潜在密钥的文件。

配置：

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "bash ~/.claude/hooks/detect-secrets.sh"
          }
        ]
      }
    ]
  }
}

脚本：

#!/bin/bash
FILE=$(echo "$HOOK_INPUT" | jq -r '.tool_input.file_path // empty')
NEW_CONTENT=$(echo "$HOOK_INPUT" | jq -r '.tool_input.new_string // .tool_input.content // empty')

# 检查常见的密钥模式
if echo "$NEW_CONTENT" | grep -iE '(api[_-]?key|password|secret|token|auth)["\s:=]+\S{16,}' &>/dev/null; then
  echo "⚠️  在 $FILE 中检测到潜在的敏感信息" >&2
  echo "请审查并改用环境变量" >&2
  exit 2
fi

exit 0

9. 自动更新文档 [社区]

当代码发生变更时，自动更新 README 文件。

配置：

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|MultiEdit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "bash -c 'echo \"📝 考虑为最近的更改更新文档\" >&2'"
          }
        ]
      }
    ]
  }
}

10. 性能 profiling [社区]

跟踪工具操作的执行时间。

配置：

{
  "hooks": {
    "PreToolUse": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "bash -c 'echo \"$HOOK_INPUT\" > /tmp/claude-pre-$$.json; date +%s%N > /tmp/claude-time-$$.txt'"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "bash ~/.claude/hooks/profile-tool.sh"
          }
        ]
      }
    ]
  }
}

脚本：

#!/bin/bash
START=$(cat /tmp/claude-time-$$.txt 2>/dev/null || echo 0)
END=$(date +%s%N)
DURATION=$(( (END - START) / 1000000 ))  # 毫秒
TOOL=$(echo "$HOOK_INPUT" | jq -r '.tool_name // "unknown"')

echo "$(date -Iseconds) $TOOL: ${DURATION}ms" >> ~/.claude/performance.log

rm -f /tmp/claude-pre-$$.json /tmp/claude-time-$$.txt

来源： Hooks 参考, Hooks 指南, 社区 GitHub 仓库

MCP 集成

模型上下文协议（MCP）将 Claude Code 连接到外部数据源和工具。

什么是 MCP？[官方]

MCP 允许 Claude Code：

• 访问外部数据（Google Drive、Slack、Jira、Notion 等）
• 使用专用工具（数据库、API、服务）
• 与企业系统集成
• 扩展本地文件系统之外的功能

常见用例：

• 读取/写入 Google Drive 文档
• 搜索 Slack 对话
• 直接查询数据库
• 从内部 API 获取数据
• 访问设计文件（Figma）
• 管理项目任务（Jira、Linear）

MCP 服务器安装 [官方]

可以通过 CLI 或配置文件添加 MCP 服务器：

CLI 安装（推荐）：

# 远程 HTTP 服务器（推荐用于托管服务）
claude mcp add --transport http notion https://mcp.notion.com/mcp
claude mcp add --transport http github https://api.githubcopilot.com/mcp/

# 带身份验证头
claude mcp add --transport http secure-api https://api.example.com/mcp \
  --header "Authorization: Bearer your-token"

# 本地 Stdio 服务器（用于本地包）
claude mcp add --transport stdio airtable -- npx -y airtable-mcp-server
claude mcp add --transport stdio postgres -- npx -y @modelcontextprotocol/server-postgres "$DATABASE_URL"

# 带环境变量
claude mcp add --transport stdio --env AIRTABLE_API_KEY=your_key airtable -- npx -y airtable-mcp-server

# Windows（需要 cmd /c 包装）
claude mcp add --transport stdio myserver -- cmd /c npx -y @some/package

MCP 服务器管理：

claude mcp list              # 列出所有已配置的服务器
claude mcp get github        # 获取特定服务器的详细信息
claude mcp remove github     # 移除一个服务器
/mcp                         # 在 Claude Code 中进行交互式管理

安装范围：

# 本地范围（默认）——存储在 ~/.claude.json 的项目路径下
claude mcp add --transport http stripe https://mcp.stripe.com

# 项目范围——存储在 .mcp.json 中（可通过 git 共享）
claude mcp add --scope project --transport http paypal https://mcp.paypal.com/mcp

# 用户范围——存储在 ~/.claude.json 中（可在所有项目中使用）
claude mcp add --scope user --transport http hubspot https://mcp.hubspot.com

配置文件（.mcp.json）：

{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/"
    },
    "postgres": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres", "${DATABASE_URL}"],
      "env": {
        "DB_URL": "${DB_URL}",
        "API_KEY": "${API_KEY:-default-value}"
      }
    },
    "slack": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-slack"],
      "env": {
        "SLACK_BOT_TOKEN": "${SLACK_BOT_TOKEN}",
        "SLACK_TEAM_ID": "${SLACK_TEAM_ID}"
      }
    }
  }
}

OAuth 身份验证 [官方]

许多 MCP 服务器支持 OAuth 进行安全身份验证：

# 添加需要 OAuth 的服务器
claude mcp add --transport http sentry https://mcp.sentry.dev/mcp

# 在 Claude Code 中通过浏览器进行身份验证
/mcp
# 按照浏览器步骤完成 OAuth 登录

手动 OAuth 配置：

{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/",
      "oauth": {
        "provider": "github",
        "scopes": ["repo", "read:user"]
      }
    }
  }
}

Claude Code 会在首次使用时打开浏览器以完成 OAuth 流程。

使用 MCP 工具 [官方]

一旦配置完毕，MCP 工具会以 mcp__<server>__<tool> 的模式出现：

# 示例：Google Drive 搜索
> “在我们的 Google Drive 中搜索 Q4 计划文档”

# Claude 使用：mcp__google-drive__search_files

# 示例：数据库查询
> “显示上周创建的所有用户”

# Claude 使用：mcp__postgres__query 并执行 SQL 查询

# 示例：Slack 搜索
> “查找关于 API 重新设计的对话”

# Claude 使用：mcp__slack__search_messages

Hooks 中的 MCP [官方]

可以在 hooks 中引用 MCP 工具：

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "mcp__postgres__query",
        "hooks": [
          {
            "type": "command",
            "command": "echo '数据库查询需要审核' && read -p '批准吗？(y/n) ' -n 1 -r && [[ $REPLY =~ ^[Yy]$ ]]"
          }
        ]
      }
    ]
  }
}

流行的 MCP 服务器 [社区]

# 官方服务器
@modelcontextprotocol/server-google-drive      # Google Drive 访问
@modelcontextprotocol/server-slack             # Slack 集成
@modelcontextprotocol/server-github            # GitHub API
@modelcontextprotocol/server-postgres          # PostgreSQL 数据库
@modelcontextprotocol/server-sqlite            # SQLite 数据库
@modelcontextprotocol/server-filesystem        # 扩展文件访问

# 社区服务器
# 可以在 GitHub 上查看社区构建的 MCP 服务器

MCP 配置管理 [官方]

# 自动启用所有项目中的 MCP 服务器
{
  "enableAllProjectMcpServers": true
}

# 将特定服务器加入白名单
{
  "enabledMcpjsonServers": ["google-drive", "postgres"]
}

# 将服务器加入黑名单
{
  "disabledMcpjsonServers": ["risky-server"]
}

# 企业版：仅限受管服务器
{
  "useEnterpriseMcpConfigOnly": true,
  "allowedMcpServers": ["approved-server-1", "approved-server-2"]
}

MCP 工具搜索 [新功能]

当 MCP 工具定义超出上下文窗口的阈值时，它们会通过 MCPSearch 工具自动延迟执行：

# 配置工具搜索阈值（占上下文窗口的百分比）
ENABLE_TOOL_SEARCH=auto:5 claude    # 在达到 5% 时激活
ENABLE_TOOL_SEARCH=auto:10 claude   # 在达到 10% 时激活（默认）
ENABLE_TOOL_SEARCH=true claude      # 始终启用
ENABLE_TOOL_SEARCH=false claude     # 始终禁用

# 或者在 settings.json 中配置
{
  "permissions": {
    "deny": ["MCPSearch"]  # 禁用 MCP 工具搜索
  }
}

来源: MCP 文档, 设置

MCP 设置示例 [官方]

适用于热门 MCP 服务器的快速入门配置。

GitHub 集成

# 安装
claude mcp add --transport stdio github -- npx -y @modelcontextprotocol/server-github

# 或通过 .mcp.json
{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}

常用操作: 创建问题、管理 PR、搜索代码、审查仓库。

Slack 集成

# 安装
claude mcp add --transport stdio slack -- npx -y @modelcontextprotocol/server-slack

# 配置
{
  "mcpServers": {
    "slack": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-slack"],
      "env": {
        "SLACK_BOT_TOKEN": "${SLACK_BOT_TOKEN}",
        "SLACK_TEAM_ID": "T01234567"
      }
    }
  }
}

用法: > "在 Slack 中搜索关于 API 重新设计的对话"

Google Drive 集成

# 使用 OAuth 安装
claude mcp add --transport http gdrive https://mcp.google.com/drive

# 或使用 stdio 并提供凭据
{
  "mcpServers": {
    "gdrive": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-gdrive"],
      "env": {
        "GDRIVE_CREDENTIALS_PATH": "${HOME}/.gdrive-credentials.json"
      }
    }
  }
}

认证: 在 Claude Code 中运行 /mcp 并按照 OAuth 流程操作。

PostgreSQL 数据库

# 安装
claude mcp add --transport stdio postgres -- npx -y @modelcontextprotocol/server-postgres postgresql://user:pass@localhost/db

# 配置
{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "${DATABASE_URL}"
      ]
    }
  }
}

用法: > "显示过去一周内数据库中创建的所有用户"

Notion 集成

# 安装
claude mcp add --transport http notion https://mcp.notion.com/mcp

# 需要 Notion OAuth - 通过 /mcp 命令进行认证

常用操作: 查询数据库、创建页面、搜索工作区。

Stripe 支付集成

# 配置
{
  "mcpServers": {
    "stripe": {
      "command": "npx",
      "args": ["-y", "@stripe/mcp-server"],
      "env": {
        "STRIPE_API_KEY": "${STRIPE_API_KEY}"
      }
    }
  }
}

用法: > "列出最近的 Stripe 交易并汇总收入"

MCP 故障排除 [社区]

来自 GitHub 问题和实际使用中的常见问题及解决方案。

问题: MCP 服务器未显示在列表中

# 问题
claude mcp list
# 输出: "未配置任何 MCP 服务器"

# 解决方案
1. 检查文件位置:
   - 用户范围: ~/.claude/settings.json
   - 项目范围: .mcp.json（位于项目根目录）

2. 验证 JSON 语法:
   cat .mcp.json | jq .

3. 检查作用域设置:
   claude mcp add --scope project <name> ...

4. 在更改配置后重启 Claude Code

问题: 工具虽已“连接”但仍不可用

# 问题
/mcp 显示“✓ 已连接”，但工具未出现

# 解决方案
1. 检查工具输出大小（最大 25,000 个 token）:
   export MAX_MCP_OUTPUT_TOKENS=50000

2. 验证服务器是否已启动:
   ps aux | grep mcp

3. 检查调试日志:
   claude --debug
   tail -f ~/.claude/logs/claude.log

4. 重置项目批准:
   claude mcp reset-project-choices

问题: OAuth 认证失败

# 问题
浏览器打开后，OAuth 却失败或无法完成

# 解决方案
1. 使用 /mcp 命令（而非直接 URL）

2. 检查网络/代理设置:
   # 尝试关闭 VPN/Cloudflare Warp

3. 清除 OAuth 缓存:
   rm -rf ~/.claude/oauth-cache

4. 验证提供商设置中的重定向 URI

问题: Windows 上出现“连接已关闭”错误

# 问题
MCP 服务器在 Windows 上立即关闭

# 解决方案 - 使用 cmd /c 包装器:
claude mcp add --transport stdio myserver -- cmd /c npx -y package-name

# 在 .mcp.json 中:
{
  "mcpServers": {
    "myserver": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "package-name"]
    }
  }
}

问题: 环境变量未展开

# 问题
${VAR} 直接显示为文字，而非展开

# 解决方案
1. 检查 .env 文件是否存在并已加载

2. 使用默认语法:
   "${API_KEY:-default_value}"

3. 在运行前先在 shell 中设置:
   export API_KEY=xxx && claude

4. 对于敏感值，可使用 settings.local.json

问题: MCP 服务器进程崩溃

# 调试步骤:
1. 直接测试服务器:
   npx @modelcontextprotocol/server-github

2. 检查 stdout/stderr:
   claude --debug | grep mcp

3. 验证依赖项是否已安装:
   npm list -g | grep mcp

4. 检查内存/资源限制:
   ulimit -a

子代理

子代理是为特定任务配置的专业 AI 助手。

什么是子代理？[官方]

子代理是针对特定工作流优化的 Claude 实例：

# 内置子代理
- 通用型: 复杂的多步任务
- 探索型: 快速探索代码库

# 自定义子代理
- 您可以使用自定义提示和工具创建自己的子代理

使用子代理 [官方]

通过 Task 工具启动：

# 探索代码库
> "查找代码库中的所有数据库查询"

# Claude 使用:
Task subagent_type="Explore"
     prompt="查找所有数据库查询，并列出包含 SQL、Prisma 或 ORM 代码的文件"

# 通用研究
> "研究 API 速率限制的最佳实践，并提出实施建议"

# Claude 使用:
Task subagent_type="general-purpose"
     prompt="研究 API 速率限制的方法，比较各种方案，并为 Express.js 提出实施建议"

创建自定义子代理 [官方]

子代理被定义为位于 .claude/agents/ 或 ~/.claude/agents/ 中的 Markdown 文件：

示例：调试助手

.claude/agents/debugger.md:

---
name: debugger
description: 用于生产环境问题的专用调试代理
model: claude-sonnet-4
allowedTools: [Read, Grep, Glob, Bash]
---

# 调试助手

你是一名专门的调试代理。你的职责是系统地调查并找出问题的根本原因。

## 调试流程

### 1. 收集上下文
- 阅读错误信息和堆栈跟踪
- 检查最近的代码变更（git log）
- 审核相关的日志文件
- 理解预期行为与实际行为之间的差异

### 2. 提出假设
- 列出可能的原因
- 按可能性排序
- 首先考虑最近的变更

### 3. 系统性调查
- 有条不紊地测试每个假设
- 使用 Grep 查找相关代码
- 阅读实现细节
- 检查其他地方是否存在类似模式

### 4. 根因分析
- 确定确切的原因
- 解释其发生的原因
- 追踪执行路径

### 5. 提出解决方案
- 建议具体的修复方案
- 说明各种方案的权衡
- 提供代码示例
- 推荐防止问题再次发生的测试方法

## 限制条件
- 不得修改代码（仅限只读分析）
- 必须提供详细的解释
- 必须引用具体的文件和行号
- 必须考虑边界情况

示例：代码审查代理

.claude/agents/reviewer.md:

---
name: reviewer
description: 专注于代码质量和最佳实践的代码审查专家
model: claude-sonnet-4
allowedTools: [Read, Grep, Glob]
---

# 代码审查员

你是一位资深的代码审查员。请提供建设性的、可操作的反馈。

## 审查标准

### 代码质量
- 可读性和可维护性
- 命名规范
- 代码组织
- 遵循 DRY 原则

### 正确性
- 逻辑错误
- 边界情况处理
- 错误处理
- 空值/未定义检查

### 性能
- 算法效率
- 不必要的计算
- 内存使用
- 数据库查询优化

### 安全性
- 输入验证
- SQL 注入风险
- XSS 漏洞
- 身份验证/授权

### 测试
- 测试覆盖率
- 测试质量
- 是否覆盖了边界情况

## 输出格式
提供结构化的反馈：
- **优点**：做得好的地方
- **问题**：发现的问题（附带严重程度）
- **建议**：改进建议
- **示例**：修复代码片段

子代理特性 [官方]

模型选择

可以为每个代理选择不同的模型：

---
name: fast-explorer
model: claude-haiku-4  # 快速且经济高效
---

---
name: deep-analyzer
model: claude-opus-4  # 功能最强大
---

工具限制

可以通过限制工具来实现专注运行：

---
name: readonly-analyzer
allowedTools: [Read, Grep, Glob]  # 仅限分析
---

---
name: implementation-agent
allowedTools: [Read, Write, Edit, Bash]  # 可以修改代码
---

子代理模式 [社区]

并行分析

> “让多个代理分别分析不同方面”

# 同时启动多个代理：
- 安全审查代理
- 性能分析代理
- 代码风格代理
- 测试覆盖率代理

# 汇总结果

顺序流水线

> “研究 → 设计 → 实现认证功能”

# 依次运行的子代理：
1. 研究代理：寻找最佳实践
2. 设计代理：创建架构
3. 实现代理：编写代码
4. 审查代理：验证实现效果

专业化团队

{
  "frontend-agent": "React/UI 专家",
  "backend-agent": "API/数据库专家",
  "devops-agent": "部署/基础设施专家"
}

来源： 子代理

代理团队

代理团队使多个 Claude Code 实例能够在共享上下文和直接通信的情况下协作完成复杂任务。

什么是代理团队？[官方]

代理团队（实验性）允许您协调多个协同工作的 Claude Code 会话：

# 与子代理的主要区别：
- 子代理：在同一会话内运行，仅向主代理汇报
- 代理团队：独立的会话，可以直接相互沟通

# 何时使用代理团队：
✅ 研究与评审（同时从多个角度进行）
✅ 新模块/新功能开发（团队成员各自负责不同部分）
✅ 调试具有竞争性假设的情况（并行调查）
✅ 跨层协调（前端、后端、测试）

# 不适合使用代理团队的情况：
❌ 有依赖关系的顺序任务
❌ 对同一文件的编辑（协调开销过大）
❌ 简单任务（过于复杂）

启用代理团队 [官方]

代理团队默认关闭。可在设置中启用：

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

或者设置环境变量：

export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
claude

开始一个团队 [官方]

# 描述任务和团队结构
> “创建一个代理团队来评审 PR #142。生成三个审查员：
   - 一名专注于安全影响
   - 一名检查性能影响
   - 一名验证测试覆盖率
   让他们各自审查并报告发现。”

# Claude 创建团队并协调工作
# 使用 Shift+向上/向下键选择队友并直接与其交流

团队显示模式 [官方]

可在设置中配置：

{
  "teammateMode": "in-process"
}

或者通过 CLI 标志：

claude --teammate-mode in-process

团队控制 [官方]

# 选择队友
Shift+向上/向下          # 循环切换队友

# 查看队友会话
Enter                  # 查看选定队友的会话
Escape                 # 中断队友的发言

# 管理任务
Ctrl+T                 # 切换共享任务列表

# 委派模式
Shift+Tab              # 切换委派模式（只有负责人协调，不参与具体实施）

# 关闭团队
> “请研究队友关闭”
> “清理团队”

团队架构 [官方]

存储位置：

• 团队配置：~/.claude/teams/{team-name}/config.json
• 任务列表：~/.claude/tasks/{team-name}/

团队钩子 [官方]

使用钩子来强制执行质量门控：

{
  "hooks": {
    "TeammateIdle": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "bash -c 'if [ ! -f ./dist/output.js ]; then echo \"构建产物缺失\" >&2; exit 2; fi'"
          }
        ]
      }
    ],
    "TaskCompleted": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "bash -c 'if ! npm test 2>&1; then echo \"测试失败\" >&2; exit 2; fi'"
          }
        ]
      }
    ]
  }
}

• TeammateIdle：当队友即将进入空闲状态时运行。退出码 2 会发送反馈并让队友继续工作。
• TaskCompleted：当任务被标记为完成时运行。退出码 2 会阻止完成，并提供反馈。

当前限制 [官方]

• 无法与正在进行中的队友恢复会话
• 任务状态可能会滞后（卡住的任务需要手动干预）
• 关闭速度较慢（队友会先完成当前工作）
• 每个会话只能有一个团队
• 不支持嵌套团队（队友无法创建新团队）
• 领队固定（无法晋升队友）
• 权限在创建时设定（无法预先为每个队友设置权限）
• 分屏功能需要 tmux 或 iTerm2 支持

来源：Agent Teams

插件

插件将技能、钩子和 MCP 服务器打包在一起，便于共享。

什么是插件？ [官方]

插件是扩展 Claude Code 的软件包：

# 一个插件可以包含：
- 技能（功能和工作流模板）
- 钩子（自动化）
- MCP 服务器（外部集成）
- 子代理定义

插件管理 [官方]

# 交互式插件管理
> /plugin

# 选项：
- 浏览市场
- 安装插件
- 启用/禁用插件
- 移除插件
- 添加自定义市场
- 搜索已安装的插件 [v2.1.14]

插件固定 [新增 v2.1.14]：现在可以将插件固定到特定的 git 提交 SHA，以确保版本稳定性：

{
  "plugins": {
    "enabledPlugins": {
      "security-toolkit@official#abc123def": true
    }
  }
}

插件结构 [官方]

my-plugin/
├── .claude-plugin/
│   └── plugin.json          # 元数据
├── commands/                 # 旧版命令（被视为技能）
│   └── my-command.md
├── skills/                   # 技能
│   └── my-skill/
│       └── SKILL.md
├── hooks.json               # 钩子定义
└── agents/                  # MCP 服务器及子代理
    └── mcp.json

plugin.json：

{
  "name": "my-plugin",
  "version": "1.0.0",
  "description": "我的超棒插件",
  "author": "你的名字",
  "homepage": "https://github.com/user/plugin",
  "keywords": ["效率", "测试"]
}

安装插件 [官方]

# 从市场安装
> /plugin
# 选择“浏览市场”
# 选择并安装

# 团队配置
# .claude/settings.json
{
  "plugins": {
    "enabledPlugins": {
      "security-toolkit@official": true,
      "custom-workflows@team": true
    }
  }
}

创建自定义市场 [官方]

{
  "extraKnownMarketplaces": [
    {
      "name": "company-internal",
      "type": "github",
      "url": "https://github.com/company/claude-plugins"
    },
    {
      "name": "local-dev",
      "type": "directory",
      "path": "/path/to/plugins"
    }
  ]
}

团队插件自动安装 [官方]

在 .claude/settings.json 中配置（提交到 git）：

{
  "plugins": {
    "enabledPlugins": {
      "team-workflows@company": true
    }
  },
  "extraKnownMarketplaces": [
    {
      "name": "company",
      "type": "github",
      "url": "https://github.com/company/claude-plugins"
    }
  ]
}

当团队成员信任该仓库时，插件会自动安装。

VSCode 插件功能 [新增]

在 VSCode 中使用 Claude Code 时：

• 安装次数显示：查看每个插件已被多少用户安装
• 信任警告：从不受信任的来源安装插件时会显示安全提示
• 原生插件管理 [v2.1.16]：VSCode 扩展内置插件管理支持
• 远程会话浏览 [v2.1.16]：OAuth 用户可以直接从会话对话框浏览和恢复远程 Claude 会话
• /usage 命令 [v2.1.14]：直接在 VSCode 中显示当前套餐使用情况
• 会话分叉与回溯 [v2.1.19]：所有用户现在都可以使用会话分叉和回溯功能
• Python 虚拟环境激活 [v2.1.21]：自动激活可确保 python 和 pip 使用正确的解释器（通过 claudeCode.usePythonEnvironment 设置进行配置）
• Claude 与 Chrome 集成 [v2.1.27]：将 Claude Code 连接到 Chrome 浏览器，用于网页自动化和测试

来源：Plugins

桌面应用功能 [新增]

Claude 桌面应用提供了一个原生界面，用于在本地运行 Claude Code 会话，并与网页端的 Claude Code 集成。

主要功能：

• 差异视图：在创建 PR 之前逐文件审查 Claude 的更改，并添加内联评论
• 使用 git worktrees 的本地并行会话：在同一仓库中运行多个会话，每个会话都有独立的工作树
• .worktreeinclude 文件：自动将 .gitignore 中的文件（如 .env）复制到新的工作树中
• 启动云端会话：直接从桌面应用启动网页端的 Claude Code
• 捆绑的 Claude Code 版本：包含一个稳定且受管理的 Claude Code 版本

差异视图：

• 点击差异统计指标（+12 -1）打开差异查看器
• 点击任意一行添加内联评论
• 按 Enter 键接受每条评论，按 Cmd+Enter 键发送所有评论

Git Worktrees： 在仓库根目录下创建 .worktreeinclude 文件：

.env
.env.local
**/.claude/settings.local.json

匹配这些模式且同时存在于 .gitignore 中的文件会被复制到新的工作树中。

安装：

• macOS：https://claude.ai/api/desktop/darwin/universal/dmg/latest/redirect
• Windows x64：https://claude.ai/api/desktop/win32/x64/exe/latest/redirect
• Windows ARM64：https://claude.ai/api/desktop/win32/arm64/exe/latest/redirect

来源：Desktop Documentation

开发工作流

核心开发方法 [社区]

阶段 1：理解

# 首先了解代码库
> “阅读项目结构并解释架构”
> “使用了什么测试框架？”
> “给我看看认证流程”

# Claude 将：
- 阅读 README、package.json 等文件
- 分析项目结构
- 识别关键模式

阶段 2：计划

# 对于复杂功能，先制定计划
> “我需要添加用户角色和权限。请制定一个计划。”

# Claude 将：
- 将功能分解
- 识别受影响的文件
- 考虑边界情况
- 创建 TodoWrite 任务

阶段 3：实施

# 逐步实施
> “实施步骤 1：在用户模型中添加角色”

# 然后验证
> “运行测试”

# 继续
> “执行步骤2：为API添加权限检查”

阶段4：验证

# 始终验证更改
> “运行所有测试”
> “检查TypeScript错误”
> “审查我们所做的更改”

# 创建提交
> “为这些更改创建一个git提交”

使用TodoWrite进行任务管理 [社区]

对于复杂的多步骤工作：

> “添加用户认证系统”

# Claude创建待办事项：
TodoWrite 待办事项=[
  {"内容": "创建带有密码哈希的User模型", "状态": "in_progress", ...},
  {"内容": "实现JWT令牌生成", "状态": "pending", ...},
  {"内容": "添加登录/注册端点", "状态": "pending", ...},
  {"内容": "添加认证中间件", "状态": "pending", ...},
  {"内容": "编写集成测试", "状态": "pending", ...}
]

# 随着工作的推进，待办事项会更新：
# ✅ “创建User模型…”已完成
# ⏳ “实现JWT令牌…”正在进行中
# ⏸️ “添加登录/注册…”待处理

并行与串行工作 [社区]

并行（独立任务）：

> “创建这三个独立的组件”

# Claude可以同时处理所有任务：
- 组件A（无依赖）
- 组件B（无依赖）
- 组件C（无依赖）

串行（有依赖）：

> “先设置数据库，再添加用户模型，然后创建API”

# 必须按顺序完成：
1. 数据库设置（其他步骤依赖于此）
2. 用户模型（API依赖于此）
3. API端点（依赖于模型）

质量保证模式 [社区]

自动化验证：

# 更改后，自动验证
> “运行以下检查：
   - TypeScript编译
   - Linting
   - 所有测试
   - 构建流程”

# 或者创建一个技能：
/verify-changes

多视角评审：

# 使用子代理进行全面评审
> “从多个角度审查这些更改：
   - 安全问题
   - 性能影响
   - 代码质量
   - 测试覆盖率”

# 启动专门的评审代理

工具协同效应

Claude Code的功能构成了一个分层的自动化堆栈。理解它们如何结合使用，能够解锁强大的工作流。

快速参考：15种协同模式

功能堆栈 [官方]

每个功能都有其独特的作用，并且彼此相互补充：

关键洞察： MCP连接外部系统。技能提供专业知识和工作流程（可自动触发也可手动调用）。钩子用于强制执行标准。子代理则用于隔离繁重的任务。

协同效应1：探索→计划→编码→提交 [官方]

Anthropic最佳实践推荐的工作流程如下：

# 步骤1：探索——了解现有情况
“阅读src/auth/目录，并解释当前的认证流程。
列出所有涉及的文件及其职责。”

# 步骤2：计划——扩展思维
“深入思考如何添加OAuth2支持。制定详细计划，
包括需要修改的文件、新增文件、依赖关系以及测试策略。”

# 步骤3：编码——明确指定文件
“按照计划实施OAuth2的改动。首先从
src/auth/oauth.ts开始，然后更新src/auth/index.ts使其导出该模块。”

# 步骤4：提交——结构化提交信息
“创建一个提交，提交信息为：‘feat(auth): 添加OAuth2提供商支持’”

为何有效： 每个步骤都在构建上下文。先探索可以避免错误假设。通过“深入思考”进行规划，能够调动更深层次的推理能力。明确指定文件名则减少了歧义。

协同效应2：测试驱动开发 [社区]

先编写测试，再进行实现：

# 1. 先编写失败的测试
“为src/utils/validation.ts中的新函数validateEmail编写测试。
覆盖：合法邮箱、非法格式、空输入、null输入。
使用Jest框架。该函数尚未实现——测试应该会失败。”

# 2. 确认测试确实失败
“运行npm test -- --testPathPattern=validation”

# 3. 提交失败的测试
“提交信息为：‘test(validation): 添加邮箱验证测试（红色）’”

# 4. 实现使测试通过
“现在在src/utils/validation.ts中实现validateEmail函数，使其通过所有测试。
使用标准的正则表达式模式，无需外部依赖。”

# 5. 验证并提交
“再次运行测试。如果全部通过，则提交：‘feat(validation): 实现邮箱验证（绿色）’”

为何有效： 测试在实现之前就定义了接口契约。Claude围绕具体目标反复迭代。Git历史清晰地展示了TDD的规范性。

协同效应3：MCP + 技能 [官方]

MCP服务器暴露的提示可以转化为技能：

# 添加MCP服务器
claude mcp add github -- gh-mcp

# 现在可用的命令包括：
/github-pr-review      # 审查当前PR
/github-issues         # 列出未解决的问题
/github-create-pr      # 从当前分支创建PR

# 示例工作流 - 完成工单
/github-issues         # “给我看看第42号问题”
# Claude 通过 MCP 获取问题详情

“实现第42号问题中描述的功能。
请在 src/features/ 中遵循我们的代码规范。”

/github-create-pr      # 创建与问题关联的 PR

真实的 MCP 集成： GitHub、Jira、Linear、Notion、PostgreSQL、Slack、Figma、Google Drive。每个集成都增加了特定领域的命令。

协同效应 4：技能 + 钩子（自动应用 + 强制执行）[官方]

技能会自动激活；钩子则在生命周期事件时强制执行：

.claude/
├── skills/
│   └── security-review/
│       └── SKILL.md        # 在安全相关任务时自动激活
└── settings.json           # 钩子：若发现安全问题则阻止提交

技能定义（.claude/skills/security-review/SKILL.md）：

---
name: security-review
description: 分析代码中的安全漏洞。在审查认证代码、API 端点或用户输入处理时激活。
allowed-tools: [Read, Grep, Glob]
---

激活后，检查以下内容：
- SQL 注入（查询中使用字符串拼接）
- XSS（HTML 中未转义的用户输入）
- 泄露的敏感信息（代码中的 API 密钥、密码等）
- 认证机制缺陷（缺少令牌验证）

将发现的问题按文件和行号标注，并标明严重程度。

钩子定义（在 settings.json 中）：

{
  "hooks": {
    "PreToolUse": [{
      "tool": "Bash",
      "command": "git commit",
      "script": ".claude/hooks/security-check.sh"
    }]
  }
}

工作流程：

“审查 src/auth/ 中的认证代码是否存在安全问题”
# 技能自动激活，发现安全问题

“修复 src/auth/login.ts 第45行的 SQL 注入漏洞”
# 您进行修复

“提交安全修复”
# 钩子会在允许提交前运行 security-check.sh
# 若仍有问题则阻止提交，若无问题则允许提交

协同效应 5：子代理 + 后台任务 [官方]

隔离工作并并行执行：

# 在后台启动服务（Ctrl+B 或显式命令）
“在后台运行 npm run dev”
“在后台运行 npm test -- --watch”

# 查看正在运行的任务
/tasks

# 主会话：使用探索代理进行研究
“使用探索代理查找所有 API 端点及其处理函数”

# 并行进行的工作：
# - 后台：端口 3000 的开发服务器
# - 后台：测试监视器随代码变化重新运行
# - 子代理：扫描代码库以查找端点
# - 主会话：可用于下一个任务

# 稍后获取代理结果
“探索代理发现了什么？”

子代理类型： Explore（代码库搜索）、Plan（架构设计），以及在 .claude/agents/ 中自定义的代理。

协同效应 6：多 Claude 工作流 [社区]

运行多个 Claude 实例以独立工作：

# 终端 1：功能开发
cd feature-branch-worktree
claude
“实现用户仪表板功能”

# 终端 2：代码审查（同一仓库，不同工作树）
cd review-worktree
claude
“审查 user-dashboard 分支中的更改，重点关注安全性与性能”

# 终端 3：文档编写
cd docs-worktree
claude
“根据最近的更改更新 API 文档”

进阶：Claude 审查 Claude：

# Claude 1 编写代码
“为 src/api/ 中的 API 端点实现限流功能”

# Claude 2 进行审查（不同会话）
“审查限流功能的实现。检查以下内容：
- 边界情况（达到限制时会发生什么？）
- 竞争条件（并发请求）
- 配置灵活性（是否可以在不部署的情况下调整限制？）”

协同效应 7：跨会话上下文保持 [社区]

结合 CLAUDE.md 和技能以实现连续性：

项目 CLAUDE.md：

# 项目：电商 API

## 当前冲刺
- [ ] 实现支付 Webhook
- [ ] 添加库存跟踪
- [x] 用户认证（已于 1 月 10 日完成）

## 关键决策
- 使用 Stripe 处理支付（参见 docs/adr/001-payment-provider.md）
- 使用 PostgreSQL 管理库存（参见 src/db/schema.sql）

## 命令
npm run dev      # 在端口 3000 上启动
npm test         # 运行 Jest 测试
npm run db:seed  # 初始化测试数据

用于加载上下文的技能（.claude/skills/resume/SKILL.md）：

---
name: resume
description: 继续当前冲刺的工作
---

阅读 CLAUDE.md 和当前冲刺的任务。查看 Git 提交记录。总结已完成、正在进行和接下来要做的工作。询问我想要继续做什么。

使用方法：

claude
/resume
# Claude 读取上下文，总结当前状态，准备继续工作

协同效应 8：质量流水线（钩子 + 测试 + Lint）[社区]

自动化质量保证：

钩子配置：

{
  "hooks": {
    "PostToolUse": [{
      "tool": "Write",
      "script": "npm run lint:fix -- $FILE"
    }, {
      "tool": "Edit",
      "script": "npm run lint:fix -- $FILE"
    }],
    "PreToolUse": [{
      "tool": "Bash",
      "command": "git commit",
      "script": ".claude/hooks/pre-commit.sh"
    }]
  }
}

预提交钩子脚本：

#!/bin/bash
npm run lint || exit 1
npm test || exit 1
echo "所有检查已通过"

结果： 每次文件编辑都会自动运行 Lint。每次提交都需要通过测试。无需人工干预即可确保质量。

协同效应 9：视觉驱动开发 [社区]

使用截图和原型作为实现目标：

# 分享设计原型
“这是新仪表板的 Figma 原型 @mockups/dashboard.png
请使用我们现有的 Button、Card 和 Chart 组件，在 src/components/Dashboard.tsx 中实现它。布局必须完全一致。”

# 根据视觉反馈迭代
“这是当前效果的截图 @screenshots/current.png
与原型对比一下。问题在于卡片之间的间距不对，
而且图表的颜色也不匹配。”

# 调试视觉问题
“这张截图显示了移动端的布局错误 @bugs/mobile-layout.png
侧边栏覆盖了内容。请修复 src/styles/layout.css 中的响应式样式。”

为什么有效： Claude 能够识别图像。具体的视觉目标可以减少歧义。迭代速度很快。

协同效应 10：日志分析流水线 [官方]

Unix 管道 + Claude 实现实时分析：

# 监控日志中的异常
tail -f /var/log/app.log | claude -p "如果看到错误或异常模式，请提醒我"

# 分析崩溃转储
cat crash.log | claude -p "分析这次崩溃。找出根本原因并提出修复建议。"

# 解析并汇总
grep "ERROR" app.log | claude -p "将这些错误按类型和频率分类。哪种最为严重？"

# CI/CD 集成
npm test 2>&1 | claude -p "如果测试失败，请解释原因并提出修复建议"

为什么有效： Claude 可以与 Unix 管道集成，能够与现有工具组合使用。

协同效应 11：模式驱动开发 [社区]

数据库模式作为事实来源：

# 从模式生成类型
“读取 prisma/schema.prisma，并在 src/types/database.ts 中生成 TypeScript 接口。
包括 JSDoc 注释，解释每个字段的作用。”

# 根据模式创建 API 端点
“基于 schema.prisma 中的 User 模型，在 src/api/users.ts 中创建 CRUD 端点。使用 zod 进行验证。”

# 生成测试 fixture
“读取模式并在 tests/fixtures/users.ts 中创建真实的测试 fixture。覆盖边界情况：空字符串、最大长度、特殊字符。”

# 迁移安全检查
“比较 prisma/schema.prisma 与当前数据库。识别破坏性更改，并提出迁移策略。”

为什么有效： 模式是契约。一切皆由此生成，它是单一事实来源。

协同效应 12：依赖管理 [社区]

在一个流程中完成更新、测试和修复：

# 检查更新
“运行 npm outdated。对于每个重大更新，解释破坏性变更及升级所需的工作量。”

# 带安全网的升级
“将 lodash 升级到 v5。运行测试。如果出现问题，立即修复。仅在测试通过时提交代码。”

# 安全审计流程
“运行 npm audit。针对每个漏洞：
1. 检查我们是否真的使用了受影响的代码路径
2. 如果是，升级或寻找替代方案
3. 如果否，记录为何可以接受”

# 许可证合规
“检查所有依赖项的许可证。标记任何 GPL 或未知许可证。我们只需要 MIT/Apache/BSD 许可证。”

为什么有效： 依赖管理非常繁琐。Claude 负责研究和修复工作。

协同效应 13：文档生成 [社区]

代码库探索 → 实时文档：

# API 文档
“探索 src/api/ 目录，并在 docs/api.yaml 中生成 OpenAPI 规范。包含来自实际代码的请求/响应示例。”

# 架构文档
“分析代码库结构。创建 docs/ARCHITECTURE.md，说明：文件夹结构、数据流、使用的关键模式。”

# 新员工入职指南
“为新开发者创建 docs/ONBOARDING.md。内容包括：设置步骤、需要首先理解的关键文件、常见任务以及你在代码中发现的陷阱。”

# 从提交记录生成变更日志
“阅读过去一个月的 git 日志。按功能、修复和破坏性更改分组，生成 CHANGELOG.md。”

为什么有效： 文档始终与代码保持同步。它源自源代码，而非记忆。

协同效应 14：带安全网的重构 [社区]

大规模重构而不破坏系统：

# 放心重命名
“在整个代码库中将 User 类重命名为 Account。更新所有导入、类型和文档。完成后运行测试。”

# 提取组件
“Dashboard 组件有 500 行代码。将其图表逻辑提取到 src/components/DashboardChart.tsx 中。确保所有行为完全一致。测试必须仍然通过。”

# 更改数据结构
“从存储 user.fullName 迁移到 user.firstName + user.lastName。更新：数据库模式、API 响应、前端显示和测试。为现有数据创建迁移脚本。”

# 升级编码模式
“将 src/services/ 目录中的所有回调式异步代码替换为 async/await。一次处理一个文件，每处理完一个文件就进行测试。”

为什么有效： TodoWrite 跟踪进度。测试验证正确性。安全地逐步修改。

协同效应 15：事件响应 [社区]

系统性调试生产环境问题：

# 初步分类
“生产环境返回 500 错误。以下是错误日志：
[粘贴日志]
找出最可能的原因，并列出需要调查的文件。”

# 根因分析
“阅读已识别的文件，追踪从 API 端点到错误的代码路径。精确说明哪里出错以及原因。”

# 以最小影响范围修复
“实施尽可能小的修复方案。不要进行重构。只需止住‘出血’即可。添加 TODO 以便日后进行彻底修复。”

# 事后文档记录
“创建 docs/incidents/2024-01-15-500-errors.md，记录以下内容：发生了什么、根本原因、已应用的修复措施以及预防措施。”

为什么有效： 结构化的方法可以防止慌乱。文档则能避免问题再次发生。

提示最佳实践 [官方]

基于 Anthropic 的指导：

思考模式（逐步加深推理深度）：

• "think" - 标准扩展思考
• "think hard" - 更全面的分析
• "think harder" - 深入探索各种选项
• "ultrathink" - 最大化推理预算

文件引用：

# 使用 Tab 键补全或明确路径
“阅读 @src/auth/login.ts 并解释认证流程”

# 多个文件
“比较 @src/api/v1/users.ts 和 @src/api/v2/users.ts —— 有什么变化？”

关键原则 [社区]

1. 理解每个功能的触发时机：

2. 组合能成倍提升价值：

仅 MCP           = 1 倍（获取数据）
MCP + 技能         = 3 倍（获取数据 + 自动专业知识）
MCP + 技能 + 钩子  = 9 倍（获取数据 + 专业知识 + 强制执行）

每一层都会使前一层的效果倍增。请务必投入精力进行前期配置。

3. 提示是基础： 如果提示过于模糊，所有协同效应都将失效。首先要掌握具体性：

• 明确指定文件名
• 清晰说明具体要求
• 定义明确的成功标准

4. 我们展示了 15 种协同效应，但还有更多。 这些模式只是起点。您可以组合、调整它们，甚至发现属于自己的方法。最适合您的工作流，就是那些专为您的项目量身定制的。

5. 设置成本可以摊销： 花一小时配置 .claude/ 文件夹，就能在未来无数次会话中节省数百小时。请把它当作基础设施来对待。

示例库

示例 1：添加身份验证

# 了解当前系统
> “分析当前的用户管理系统”

# 规划
> “制定添加基于 JWT 的身份验证计划”

# 实施
> “按照计划实现身份验证系统”
# (Claude 创建 TodoWrite 任务并逐步完成)

# 测试
> “为身份验证创建全面的测试”

# 安全审查
> “审查身份验证实现的安全性问题”

# 文档
> “更新 API 文档，加入身份验证端点”

# 提交
> “为身份验证功能创建一个 git 提交”

示例 2：性能优化

# 识别问题
> “分析代码库中的性能瓶颈”

# 制定优化计划
> “针对发现的最关键问题制定优化计划”

# 实施优化
> “实施数据库查询优化”

# 基准测试
> “创建基准测试以衡量改进效果”

# 验证
> “运行基准测试并比较前后结果”

示例 3：Bug 调查

# 提供背景信息
> “用户报告登录偶尔失败。以下是错误日志：[粘贴日志]”

# 使用调试代理进行调查
> “使用调试代理调查此问题”

# 根因分析
> “解释导致此问题的原因以及为什么是间歇性的”

# 修复
> “针对此问题实施修复方案”

# 预防
> “添加测试和日志记录，以防止未来再次发生”

# 文档化
> “更新 CLAUDE.md，记录我们从该问题中学到的内容”

示例 4：API 迁移

# 分析现有 API
> “记录 v1 API 中的所有端点”

# 制定迁移计划
> “基于以下变更制定从 v1 到 v2 的迁移计划：[列出变更]”

# 实现新版本
> “在 v1 的基础上实现 v2 API”

# 确保向后兼容性
> “创建兼容层，使 v1 客户端仍能正常工作”

# 测试
> “编写测试用例，确保 v1 和 v2 均正常运行”

# 文档化
> “为 API 消费者生成迁移指南”

示例 5：设置 CI/CD

# 调研
> “调研适用于 Node.js 项目的 GitHub Actions 最佳实践”

# 创建工作流
> “创建一个 GitHub Actions 工作流，用于：
   - 在拉取请求上运行
   - 检查 TypeScript 编译
   - 执行代码风格检查
   - 运行所有测试
   - 报告测试覆盖率”

# 安全扫描
> “将安全扫描加入工作流”

# 部署
> “在合并到主分支时自动部署到预发布环境”

# 文档化
> “在 README.md 中记录 CI/CD 配置”

示例 6：多目录项目

# 添加目录
> “将前端和后端目录添加到工作区”

# 同步更改
> “更新后端中的 User 类型定义，并将其同步到前端”

# 跨项目验证
> “确保前端的 API 调用与后端端点一致”

# 并行测试
> “在后台并行运行后端测试和前端测试”

# 监控两端
> “启动两个开发服务器，并监控错误”

示例 7：后台开发工作流

# 在后台启动所有开发服务
> “在后台启动前端开发服务器”
> “在后台启动后端 API 服务器”
> “在后台以监听模式运行测试”

# 配置状态栏以跟踪所有服务
/statusline

# 同时监控所有服务
> “监控所有后台进程是否有错误”

# Claude 监控所有后台任务的日志
# 识别跨服务的问题
# 在不停止服务的情况下提出修复建议

# 动态修复问题
> “我看到一个 API 超时错误”
# Claude 检查后端日志，找出原因并提出解决方案

# 检查所有后台任务
/bashes

# 如需停止特定服务
/kill <id>

示例 8：智能上下文管理

# 开始重大功能开发
> “构建一个完整的用户认证系统，包含 JWT、刷新令牌和密码重置功能”

# 随着工作的推进，上下文逐渐积累……
# 阅读了大量文件并执行了多次操作后
# 上下文变得非常庞大

# 使用 microcompact 进行智能清理
/compact “focus”
# 保留：当前认证相关的工作、近期更改、已学习的模式
# 移除：旧文件读取、已完成的搜索、过时的上下文

# 继续无缝开发，保持干净的上下文
> “为系统添加双因素认证”
# 当前认证工作所需的完整上下文仍然可用

# 切换到新功能，进行大规模上下文重置
/compact
# 完全重置，以便全新开始

> “实现 Stripe 支付集成”
# 为支付功能提供一个全新的起点

示例 9：安全优先开发

# 结合安全考虑进行规划
> “设计我们表单的用户输入处理系统，重点关注安全最佳实践”

# 实施并立即进行安全审查
> “实现表单验证系统”
> “审查表单验证代码是否存在安全漏洞”

# 修复已发现的问题
> “修复电子邮件字段验证中的 XSS 漏洞”
> “验证修复是否解决了所有注入途径”

# 记录安全模式
> “更新 CLAUDE.md，记录我们的输入验证安全模式”

# 设置持续的安全监控
> “创建一个 GitHub Action，在每次 PR 提交时运行安全扫描”

示例 10：全栈多仓库开发

# 初始化多仓库工作区
/add-dir ~/projects/backend
/add-dir ~/projects/frontend
/add-dir ~/projects/shared-types

# 在各项目之间同步类型定义
> “更新 shared-types 中的 User 类型，并确保后端和前端保持一致”

# 并行类型检查
> “在后台同时对三个项目运行 TypeScript 类型检查”

# 监控并修复类型错误
> “检查后台任务中是否存在类型错误”
> “修复在前端发现的类型不匹配问题”

# 跨仓库验证
> “验证后端的所有 API 类型是否与前端客户端的预期一致”

# 启动所有开发服务器
> “在后台启动后端服务器、前端服务器以及类型监听服务”

# 统一的开发体验
> “构建结账流程，协调后端 API 和前端 UI 的更改”
# Claude 在所有仓库中协同完成更改

最佳实践

针对开发者 [社区]

1. 首先设置 CLAUDE.md

- 记录项目结构
- 列出重要命令
- 注明规范和模式
- 添加已知陷阱
- 随着学习不断更新

2. 使用描述性请求

# 良好
> “为登录端点添加输入验证，检查邮箱格式和密码长度”

# 效果较差
> “修复登录”

3. 验证更改

# 提交前务必审查
> “向我展示所有更改”
> “运行测试以验证这些更改”

4. 增量式开发

# 将大型功能分解为步骤
> “首先，让我们添加数据库模型”
> “现在添加 API 端点”
> “最后添加前端表单”

5. 智能利用工具

# 使用 Grep 查找模式
> “查找所有使用原生 SQL 的数据库查询”

# 使用 Glob 发现文件
> “查找所有测试文件”

# 使用子代理进行探索
> “让 Explore 代理绘制出认证流程”

决策模式 [社区]

常见场景的快速决策树：

某处出现问题：

→ 能否复现？
  → 是：系统性调试
  → 否：先收集更多信息
→ 之前是否正常工作？
  → 是：检查最近的改动（git diff）
  → 否：检查假设
→ 错误信息是否清晰？
  → 是：直接解决
  → 否：通过日志追踪执行流程

添加新功能：

→ 是否已有类似功能？
  → 是：沿用该模式
  → 否：调研最佳实践
→ 是否涉及现有代码？
  → 是：先理解其逻辑（阅读、分析）
  → 否：独立设计
→ 是否包含复杂逻辑？
  → 是：先拆解（使用TodoWrite）
  → 否：直接实现

代码运行缓慢：

→ 是否已测量性能？ → 否：先进行性能分析
→ 是否已知瓶颈？ → 否：找出瓶颈（使用ultrathink）
→ 是否有解决方案？ → 否：先调研，再实施并再次测量

问题发生时的恢复策略：

# 确认事实
> “当前代码库的状态是什么？”

# 寻找最小可行方案
> “最简单的修复方案是什么？”

# 质疑假设
> “让我重新阅读相关代码”

# 找到稳定状态
> “让我们使用/rewind回退到上一个可用状态”

基于复杂度的方法：

团队协作 [社区]

1. 共享配置

# 提交至Git：
.claude/
├── settings.json      # 共享权限与配置
├── commands/          # 团队工作流
├── skills/            # 团队技能
└── agents/            # MCP服务器及子代理

# Git忽略：
.claude/settings.local.json  # 个人覆盖配置

2. 在CLAUDE.md中记录规范

## 团队约定
- 所有API路由遵循RESTful风格
- 数据库迁移使用Prisma
- 测试采用AAA模式（安排、行动、断言）
- 永不直接提交到主分支

3. 创建工作流技能

# .claude/skills/
├── code-review/
│   └── SKILL.md
├── deploy-staging/
│   └── SKILL.md
├── run-checks/
│   └── SKILL.md
└── security-audit/
    └── SKILL.md

4. 使用钩子确保标准执行

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {"type": "command", "command": "eslint-check.sh"}
        ]
      }
    ]
  }
}

安全措施 [社区]

1. 保护敏感文件

{
  "permissions": {
    "deny": {
      "Write": ["*.env", ".env.*", "*.key", "*.pem"],
      "Edit": ["*.env", ".env.*", "*.key", "*.pem", ".git/*"]
    }
  }
}

2. 执行前审查

{
  "permissions": {
    "defaultMode": "ask"
  }
}

3. 使用钩子进行审计

{
  "hooks": {
    "PostToolUse": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "echo \"$(date): $TOOL_NAME\" >> .claude/audit.log"
          }
        ]
      }
    ]
  }
}

4. 定期安全审查

# 使用安全审查技能或命令
> “对认证系统进行安全审计”

故障排除

常见问题 [社区]

问题：“上下文过大”错误

# 解法1：压缩上下文
> /compact

# 解法2：智能清理
> /compact "focus"

# 预防：长时间会话中定期压缩

问题：编辑工具报“未找到字符串”错误

# 解决方案：先读取文件以确认具体内容
> 读取文件以查看确切内容

# 确保完全匹配，包括：
- 空格和缩进
- 换行符
- 特殊字符

# 如果字符串多次出现，可扩大上下文范围

问题：权限被拒绝

# 解法1：在提示时授予权限

# 解法2：提前在settings.json中配置
{
  "permissions": {
    "allow": {
      "Bash": ["npm test"],
      "Edit": {}
    }
  }
}

问题：Claude无法识别最新文件更改

# 解决方案：明确要求重新读取
> “请再次读取app.ts文件”

# 或者提供具体更改内容
> “我刚刚更新了配置，以下是变更内容：[粘贴]”

问题：后台任务无响应

# 检查状态
> /bashes

# 如果卡住则终止
> /kill <id>

# 重启
> “请在后台重新启动开发服务器”

问题：Git操作失败

# 检查Git状态
> “运行git status”

# 常见解决方法：
- 未暂存的更改：“请先使用git add暂存文件”
- 合并冲突：“请显示冲突并协助解决”
- 分支问题：“请切换到正确的分支”

问题：MCP服务器无法运行

# 检查配置
> “请展示MCP配置”

# 确认服务器是否已启动
> “请检查MCP服务器是否正确启动”

# 查看日志
~/.claude/logs/mcp-<server-name>.log

# 重新安装
> “请重新安装MCP服务器软件包”

错误恢复模式 [社区]

针对常见错误场景的系统化处理方法。

会话中断后的恢复

# 若会话中途中断：
1. 检查最近的历史记录：
   > “我刚才在做什么？”

2. 查看文件变更：
   git diff

3. 重建状态：
   > “根据最近的变更，继续我们之前的工作”

钩子故障

# 若钩子意外阻止操作：
1. 检查钩子输出：
   claude --debug

2. 手动测试钩子：
   echo '{"tool_name":"Edit","tool_input":{...}}' | ~/.claude/hooks/script.sh

3. 暂时禁用：
   mv ~/.claude/settings.json ~/.claude/settings.json.bak

4. 修复并恢复：
   # 修复钩子脚本后，再恢复设置

任务中上下文溢出

# 当复杂任务过程中出现“上下文过大”提示时：

# 快速恢复：
> /compact "focus"
> “继续完成[简要任务摘要]”

# 如需彻底重置：
> /compact
> “让我简要说明一下：[关键上下文]”

# 预防措施：
- 每约50次操作使用一次/compact "focus"
- 新功能应开启全新会话

工具权限问题

# 当权限反复被请求时：

# 永久授权：
{
  "permissions": {
    "allow": {
      "Bash": {},      # 允许所有Bash操作
      "Edit": {},      # 允许所有编辑
      "Write": {}      # 允许所有写入
    }
  }
}

# 或针对特定场景授权：
{
  "permissions": {
    "allow": {
      "Bash": ["npm test", "npm run build"]
    }
  }
}

网络/API超时

# 若操作超时：

# 使用指数退避重试：
第一次尝试失败
等待2秒后重试
等待4秒后重试
等待8秒后重试

# 若持续超时，则更换模型：
> “请换一个模型再试”

# 检查网络连接：
ping anthropic.com
curl -v https://api.anthropic.com

丢失工作的恢复

# 如果更改未保存：

1. 检查 Git：
   git status
   git diff

2. 检查文件备份：
   ls -la ~/.claude/backups/

3. 查看会话记录：
   # 会话记录保存在 ~/.claude/transcripts/

4. 根据记忆重建：
   > “根据我们的对话，重新创建 [功能]”

针对持续性问题的调试模式

# 启用全面调试：
claude --debug --log-level trace

# 实时跟踪日志：
tail -f ~/.claude/logs/claude.log

# 过滤特定问题：
grep -i error ~/.claude/logs/claude.log
grep -i "mcp" ~/.claude/logs/claude.log

安全考虑

安全模型 [官方]

Claude Code 的运行机制包括：

1. 权限系统

• 工具需要明确的权限
• 权限是会话特定的
• 可以在设置中预先配置

2. 沙箱机制（macOS/Linux）

{
  "sandbox": {
    "enabled": true,
    "allowUnsandboxedCommands": false
  }
}

3. 文件访问控制

{
  "permissions": {
    "additionalDirectories": ["/allowed/path"],
    "deny": {
      "Read": ["*.key", "*.pem"],
      "Write": ["*.env"],
      "Edit": [".git/*"]
    }
  }
}

最佳安全实践 [社区]

1. 绝不提交敏感信息

# 在设置中阻止
{
  "permissions": {
    "deny": {
      "Write": ["*.env", "*.key", "*.pem", "*secret*"],
      "Edit": ["*.env", "*.key", "*.pem", "*secret*"]
    }
  }
}

# 使用钩子扫描敏感信息
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {"type": "command", "command": "detect-secrets-hook.sh"}
        ]
      }
    ]
  }
}

2. 审核 AI 生成的代码

# 始终在部署前审核
> “请解释这段代码的安全影响”
> “请检查其中是否存在潜在漏洞”

3. 限制工具访问

// 用于执行分析的子代理
{
  "allowedTools": ["Read", "Grep", "Glob"]  // 不允许修改
}

// 用于实现的代理
{
  "allowedTools": ["Read", "Write", "Edit", "Bash"]  // 允许修改
}

4. 审计追踪

{
  "hooks": {
    "PostToolUse": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "logger.sh"  // 记录所有操作
          }
        ]
      }
    ]
  }
}

5. 网络限制

{
  "sandbox": {
    "network": {
      "allowUnixSockets": ["/var/run/docker.sock"],
      "allowLocalBinding": true,
      "httpProxyPort": 8080
    }
  }
}

来源： 设置、沙箱机制

SDK 集成

Claude Code 可通过 TypeScript/Python SDK 以编程方式使用。

使用场景 [官方]

• 自动化 CI/CD 流程
• 在 Claude Code 上构建自定义工具
• 创建自动化代码审查系统
• 集成到现有开发工具中
• 批量处理多个项目

TypeScript SDK 示例 [官方]

import { ClaudeCodeSDK } from '@anthropic-ai/claude-code';

const sdk = new ClaudeCodeSDK({
  apiKey: process.env.ANTHROPIC_API_KEY
});

// 启动会话
const session = await sdk.startSession({
  projectDir: '/path/to/project',
  systemPrompt: '你是一名代码审查员'
});

// 发送任务
const response = await session.chat({
  message: '请审查这个代码库是否存在安全问题'
});

console.log(response.content);

// 结束会话
await session.end();

Python SDK 示例 [官方]

from anthropic_sdk import ClaudeCodeSDK

sdk = ClaudeCodeSDK(api_key=os.environ["ANTHROPIC_API_KEY"])

# 开始会话
session = sdk.start_session(
    project_dir="/path/to/project",
    system_prompt="你是一名测试生成员"
)

# 发送任务
response = session.chat(
    message="为所有 API 端点生成测试"
)

print(response.content)

# 结束会话
session.end()

来源： SDK 概览

实验性概念

⚠️ 警告：本节包含尚未在官方文档中验证的理论概念和模式。这些是供高级用户探索的实验性想法。

概念：认知模式 [实验性]

关于根据任务类型优化 Claude 处理方式的未经验证的理论：

# 简单创作模式
> “创建 5 个类似的 React 组件”
# 理论：并行处理，基于模板

# 优化模式
> “优化这个算法”
# 理论：深度分析，多种方法

# 研究模式
> “研究并实现 X 的最佳实践”
# 理论：网络搜索 → 分析 → 实施流程

状态：官方文档并未支持“模式”这一说法。Claude Code 对所有任务都采用相同的模型。

概念：内核架构 [实验性]

关于多层智能的未经验证的理论框架：

理论：
┌─────────────────┐
│   协调器  │
└────────┬────────┘
         │
    ┌────┴────┬────────┬─────────┐
    │         │        │         │
  内存   意图  提取  验证
  内核   内核  内核   内核

状态：这是一个概念模型，而非实际的 Claude Code 功能。Claude Code 使用的是：

• 子代理（真实功能）
• 技能（真实功能）
• 钩子（真实功能）

但并没有所谓的“内核架构”系统。

概念：元待办系统 [实验性]

关于由 AI 验证的高级任务管理的未经验证的理论：

# 理论：多代理任务验证
1. 捕捉意图（四种方法）
2. 多代理验证
3. 背景执行
4. 学习整合

状态：TodoWrite 是一个真实存在的工具，但带有多代理验证的“元待办”仍属于理论范畴。请按照文档说明使用实际的 TodoWrite 工具。

为何要分开 [编辑说明]

原始指南将以下内容混在一起：

• 真实功能（技能、钩子、MCP）
• 使用模式（如何使用这些功能）
• 理论框架（未经验证的概念）

这导致了人们对 Claude Code 实际功能与概念性想法之间的混淆。

对于阅读此指南的人工智能代理而言：请重点关注标有 [OFFICIAL] 和 [COMMUNITY] 的部分。将 [EXPERIMENTAL] 视为可尝试的想法，而非已确立的功能。

其他资源

官方文档 [官方]

• 主文档：https://code.claude.com/docs/en/overview
• CLI 参考：https://code.claude.com/docs/en/cli-reference
• 设置：https://code.claude.com/docs/en/settings
• 技能：https://code.claude.com/docs/en/skills
• 钩子：https://code.claude.com/docs/en/hooks
• MCP：https://code.claude.com/docs/en/mcp
• 子代理：https://code.claude.com/docs/en/sub-agents
• 插件：https://code.claude.com/docs/en/plugins

社区资源 [社区]

• GitHub：https://github.com/anthropics/claude-code
• Awesome Claude Code：https://github.com/hesreallyhim/awesome-claude-code
• Awesome Claude Skills：https://github.com/travisvn/awesome-claude-skills

获取帮助

• GitHub Issues: https://github.com/anthropics/claude-code/issues
• Discord: 请查看 Anthropic 的社区频道
• 文档: https://code.claude.com

更改日志

Claude Code CLI 发布 [官方]

完整详情请参阅官方 CHANGELOG.md。

版本 2.1.39（2026年2月10日）- 最新

• ⚡ 改进了终端渲染性能
• 🐛 修复了致命错误被吞没而非显示的问题
• 🐛 修复了会话关闭后进程挂起的问题
• 🐛 修复了终端屏幕边界处字符丢失的问题
• 🐛 修复了详细转录视图中的空白行问题

版本 2.1.38（2026年2月10日）

• 🐛 修复了 VS Code 终端滚动到顶部的回归问题（在 2.1.37 中引入）
• 🐛 修复了 Tab 键会排队发送斜杠命令而非自动补全的问题
• 🐛 修复了使用环境变量包装器的命令的 bash 权限匹配问题
• 🐛 修复了不使用流式传输时工具使用之间的文本消失的问题
• 🐛 修复了在 VS Code 扩展中恢复时出现重复会话的问题
• 🔒 改进了 heredoc 分隔符解析，以防止命令走私
• 🔒 在沙盒模式下阻止向 .claude/skills 目录写入

版本 2.1.37（2026年2月7日）

• 🐛 修复了启用 /extra-usage 后 /fast 无法立即使用的问题

版本 2.1.36（2026年2月7日）

• ⚡ Fast 模式现已适用于 Opus 4.6 [新功能]

版本 2.1.34（2026年2月6日）

• 🐛 修复了代理团队设置在两次渲染之间更改时导致的崩溃问题
• 🐛 修复了被排除在沙盒之外的命令在启用 autoAllowBashIfSandboxed 时绕过 Bash 提问权限的问题

版本 2.1.33（2026年2月6日）

• 🤖 现在 tmux 中的代理队友会话可以正确地发送和接收消息
• 🪝 新增了用于多代理工作流的 TeammateIdle 和 TaskCompleted 钩子事件 [新功能]
• 🔧 增加了通过 Task(agent_type) 语法限制子代理的支持
• 📝 为代理添加了 memory 前置字段（user、project 或 local 范围）
• 🔌 插件名称现在会显示在技能描述中，以便更好地发现
• 🐛 修复了提交新消息时扩展思考被打断的问题
• 🐛 修复了流式传输端点上的 API 代理 404 错误
• 🐛 修复了通过 settings.json 环境变量设置的代理配置未应用于 WebFetch 的问题
• 📊 改进了 /resume 会话选择器，使其标题更清晰（移除了原始 XML 标记）
• 📝 增强了 API 连接失败的错误信息（显示具体原因，如 ECONNREFUSED、SSL 错误）
• 🔌 [VSCode] 添加了支持 OAuth 的远程会话功能
• 🔌 [VSCode] 在会话选择器中增加了 Git 分支和消息数量，并支持按分支名称搜索
• 🔌 [VSCode] 修复了加载或切换会话时滚动到底部时出现的下拉不足问题

版本 2.1.32（2026年2月5日）

• ✨ Claude Opus 4.6 现已可用！ [新功能]
• 🤖 新增了研究预览版的 Agent Teams 功能，用于多代理协作 [新功能]
• 🧠 Claude 现在会在工作时自动记录并回忆 记忆 [新功能]
• 📊 在消息选择器中新增了“从这里总结”选项，用于部分对话的总结
• 📁 在额外目录（--add-dir）内的 .claude/skills/ 中的技能现在会自动加载
• 🐛 修复了 @ 文件补全在子目录中显示错误相对路径的问题
• 🔄 --resume 现在会复用之前对话中的 --agent 值
• 🐛 修复了包含 JavaScript 模板字面量的 heredocs 导致的 bash “Bad substitution” 错误
• 📊 技能字符预算现在会根据上下文窗口进行调整（上下文的 2%）
• 🐛 修复了泰语/老挝语空格元音渲染问题
• 🔌 [VSCode] 修复了斜杠命令在前面有文本时错误执行的问题
• 🔌 [VSCode] 在加载过往对话时增加了加载动画

版本 2.1.31（2026年2月4日）

• 💡 在退出时增加了会话恢复提示，说明如何稍后再继续对话
• 🌐 在复选框选择中增加了来自日本 IME 的全角空格输入支持
• 🤖 改进了系统提示，引导模型使用专用工具（Read、Edit、Glob、Grep），而不是 bash 等效工具
• 🐛 修复了 PDF 过大导致会话永久卡死的问题
• 🐛 修复了在沙盒模式下 bash 命令错误报告“只读文件系统”错误的问题
• 🐛 修复了在进入计划模式后由于 ~/.claude.json 中缺少默认字段而导致的崩溃问题
• 🐛 修复了在流式 API 路径中 temperatureOverride 被忽略的问题
• 🐛 修复了 LSP 关闭/退出与严格语言服务器兼容性的问题
• ⚡ 减少了旋转动画期间终端布局的抖动
• 📝 改进了 PDF 和请求大小错误信息（显示实际限制：100 页、20MB）
• 💰 移除了针对第三方提供商用户（Bedrock、Vertex、Foundry）的误导性 Anthropic API 定价显示

版本 2.1.30（2026年2月3日）

• 📄 为 Read 工具添加了用于 PDF 的 pages 参数（例如，pages: "1-5"）[新功能]
• 📄 大型 PDF（超过 10 页）现在在被提及时会返回轻量级引用
• 🔑 为没有动态客户端注册的 MCP 服务器添加了预配置的 OAuth 凭证
• 🔍 新增了用于排查会话问题的 /debug 命令 [新功能]
• 📊 在任务结果中增加了 token 数量、工具使用次数和持续时间指标
• ♿ 新增了减少运动模式的配置选项（prefersReducedMotion 设置）[新功能]
• 🐛 修复了 API 对话历史中出现的幽灵“(无内容)”文本块
• 🐛 修复了提示缓存失效问题（现在会在工具描述或 schema 变化时正确重新验证）
• 🐛 修复了在对话中带有思考块的情况下 /login 后出现 400 错误的问题
• 🐛 修复了恢复会话时因转录损坏而导致的挂起问题
• 🐛 修复了 Max 20x 用户的速率限制消息
• 🐛 修复了子代理无法访问 SDK 提供的 MCP 工具的问题
• 🐛 修复了 Windows 上使用 .bashrc 文件时 bash 执行失败的问题
• 🐛 修复了 VS Code 中的重复会话问题
• ⚡ 使用 --resume 时，内存占用减少了 68%，尤其在会话较多的情况下
• 📊 TaskStop 工具现在会显示已停止的命令/任务描述
• ⚡ /model 现在会立即执行，而不是排队
• ⌨️ [VSCode] 在问题对话框中支持多行输入（Shift+Enter）

版本 2.1.29（2026年1月31日）

• ⚡ 修复了在使用 saved_hook_context 恢复会话时的启动性能问题

版本 2.1.27（2026年1月30日）

• 🔗 新增了 --from-pr 标志，用于恢复与特定 GitHub PR 编号或 URL 相关的会话
• 🔗 现在会话在通过 gh pr create 创建时会自动链接到 PR
• 🔒 权限现在会尊重内容级别的 ask 而不是工具级别的 allow（例如，allow: ["Bash"]，ask: ["Bash(rm *)"])
• 🔍 工具调用失败和拒绝现在会被添加到调试日志中
• 🐛 修复了 /context 命令彩色输出显示的问题
• 🐛 修复了状态栏与 PR 状态一起复制后台任务指示器的问题
• 🔌 [VSCode] 启用了与 Chrome 集成的 Claude
• 🪟 [Windows] 修复了使用 .bashrc 文件的用户 bash 命令执行失败的问题
• 🪟 [Windows] 修复了控制台窗口在派生子进程时闪烁的问题
• 🔌 [VSCode] 修复了 OAuth 令牌过期导致长时间会话后出现 401 错误的问题

版本 2.1.25（2026年1月29日）

• 🔧 修复了 Bedrock 和 Vertex 上网关用户的测试版标头验证错误
• 💡 临时解决方案：设置 CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1 以避免该错误

版本 2.1.23（2026年1月29日）

• ⚙️ 新增可自定义的加载动词设置（spinnerVerbs）
• 🔧 修复了位于企业代理后或使用客户端证书的用户的 mTLS 和代理连接问题
• 🔧 修复了按用户隔离的临时目录，以防止在共享系统上出现权限冲突
• 🐛 修复了启用提示缓存范围时导致 400 错误的竞争条件
• 🐛 修复了无头流式会话结束时未取消待处理的异步钩子的问题
• 🐛 修复了接受建议时选项卡补全无法更新输入框的问题
• 🐛 修复了 ripgrep 搜索超时 silently 返回空结果而非报告错误的问题
• ⚡ 通过优化屏幕数据布局提升了终端渲染性能
• ⏱️ 将 Bash 命令修改为在显示已用时间的同时也显示超时持续时间
• 🟣 将已合并的拉取请求在提示符底部显示紫色状态指示器
• 🔌 [IDE] 修复了无头模式下 Bedrock 用户的模型选项显示错误区域字符串的问题

版本 2.1.22（2026年1月28日）

• 🔧 修复了非交互式（-p）模式下的结构化输出

版本 2.1.21（2026年1月28日）

• 🌐 在选项选择提示中增加了对来自日语 IME 的全角数字输入的支持
• 🐛 修复了 Shell 补全缓存文件在退出时被截断的问题
• 🐛 修复了在工具执行过程中中断的会话恢复时出现的 API 错误
• 🐛 修复了对于具有大输出令牌限制的模型，自动压缩过早触发的问题
• 🐛 修复了任务 ID 在删除后可能被重复使用的问题
• 🐛 修复了 Windows 系统上 VS Code 扩展中文件搜索无法正常工作的问题
• 📊 改进了读取/搜索进度指示器，在进行中时显示“正在读取…”，完成时则显示“已读”
• 🤖 改进了 Claude，使其优先选择文件操作工具（读取、编辑、写入），而非 Bash 等效命令（cat、sed、awk）
• 🐍 [VSCode] 新增了 Python 虚拟环境的自动激活功能（claudeCode.usePythonEnvironment 设置）
• 🔌 [VSCode] 修复了消息操作按钮背景颜色不正确的问题

版本 2.1.20（2026年1月27日）

• ⌨️ 在 Vim 普通模式中支持箭头键历史导航
• ⌨️ 在帮助菜单中新增了外部编辑器快捷键（Ctrl+G）
• 📊 提示符底部新增 PR 审核状态指示器（已批准/要求更改/待处理/草稿）
• 📁 支持通过 --add-dir 从额外目录加载 CLAUDE.md 文件（需设置 CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1）
• 🗑️ 通过 TaskUpdate 工具实现任务删除
• 📱 根据终端高度动态调整任务列表
• 📋 /copy 命令现已向所有用户开放
• ⚙️ 配置备份现带有时间戳并进行轮转（保留最近 5 个）
• 🐛 修复了会话压缩问题，该问题会导致恢复时加载完整历史记录
• 🐛 修复了智能体在主动工作期间忽略用户消息的问题
• 🐛 修复了宽字符（表情符号、CJK 文字）渲染出现的瑕疵
• 🐛 修复了 MCP 响应中包含特殊 Unicode 字符时的 JSON 解析错误
• 🐛 修复了在浏览命令历史时草稿提示丢失的问题
• 🐛 修复了取消工具使用时可能出现的崩溃问题

版本 2.1.19（2026年1月23日）

• ✨ 新增环境变量 CLAUDE_CODE_ENABLE_TASKS——将其设置为 false 可使用旧版任务系统
• ✨ 新增简写 $0、$1 等，用于在自定义命令中访问单个参数
• 🔄 将索引参数语法从 $ARGUMENTS.0 更改为 $ARGUMENTS[0]（方括号语法）
• ✅ 不再需要审批那些没有额外权限或钩子的技能
• 🐛 修复了在不支持 AVX 指令集的处理器上发生的崩溃问题
• 🐛 修复了关闭终端时残留的 Claude Code 进程问题（处理 EIO 错误，并回退至 SIGKILL 信号）
• 🐛 修复了 /rename 和 /tag 在从不同目录恢复会话时未能更新正确会话的问题
• 🐛 修复了从不同目录通过自定义标题恢复会话的问题
• 🐛 修复了使用提示暂存功能（Ctrl+S）时粘贴文本丢失的问题
• 🐛 修复了智能体列表显示“Sonnet（默认）”而非“继承（默认）”的问题
• 🐛 修复了后台运行的钩子命令未能提前返回的问题
• 🐛 修复了文件写入预览遗漏空行的问题
• 🔌 [SDK] 新增了将 queued_command 附件消息重放为 SDKUserMessageReplay 事件的功能
• 🔌 [VSCode] 启用了所有用户的会话分叉和回溯功能

版本 2.1.17（2026年1月22日）

• 🔧 修复了在不支持 AVX 指令集的处理器上发生的崩溃问题

版本 2.1.16（2026年1月22日）

• ✨ 新的任务管理系统，支持依赖关系跟踪
• 🔌 [VSCode] 原生插件管理支持
• 🔌 [VSCode] OAuth 用户可通过“会话”对话框浏览并恢复远程 Claude 会话
• 🐛 修复了在恢复大量使用子智能体的会话时出现的内存不足崩溃问题
• 🐛 修复了运行 /compact 后“剩余上下文”警告仍未消失的问题
• 🐛 修复了恢复界面中的会话标题未尊重用户语言设置的问题
• 🪟 [IDE] 修复了 Windows 系统上 Claude Code 侧边栏视图容器启动时无法显示的竞争条件问题

版本 2.1.15（2026年1月21日）

• ⚠️ 对 npm 安装添加了弃用通知——引导用户运行 claude install 或访问 https://docs.anthropic.com/en/docs/claude-code/getting-started
• ⚡ 使用 React Compiler 提升了 UI 渲染性能
• 🐛 修复了“距离自动压缩还剩上下文”警告在执行 /compact 后仍未消失的问题
• 🐛 修复了 MCP stdio 服务器超时未杀死子进程而导致 UI 卡死的问题

版本 2.1.14（2026年1月20日）

• ⌨️ 在 Bash 模式中新增基于历史的自动补全功能（!）——按下 Tab 键即可补全部分命令
• 🔍 在已安装插件列表中新增搜索功能
• 📌 支持将插件固定到特定的 Git 提交 SHA 值
• 🔧 修复了上下文窗口阻塞限制计算过于激进的问题（约 65% 而不是约 98%）
• 🐛 修复了导致并行子智能体运行时崩溃的内存问题
• 🐛 修复了长时间运行会话中流资源清理不彻底造成的内存泄漏问题
• 🐛 修复了在 Bash 模式中输入 @ 符号时触发文件自动补全的问题
• 📊 [VSCode] 新增了 /usage 命令，用于显示当前套餐使用情况

版本 2.1.12（2026年1月17日）

• 🔧 修复了消息渲染错误

版本 2.1.11（2026年1月17日）

• 🔧 修复了 HTTP/SSE 传输方式下过多的 MCP 连接请求问题

版本 2.1.10（2026年1月17日）

• 🪝 新增 Setup 钩子事件，可通过 --init、--init-only 或 --maintenance CLI 标志触发
• ⌨️ 登录时新增键盘快捷键 ‘c’，用于复制 OAuth URL
• 🐛 修复了包含 JavaScript 模板字面量的 heredoc 的 Bash 命令问题
• ⚡ 改进了启动流程，以便在 REPL 准备就绪之前捕获按键输入
• 📎 文件建议现在显示为可移除的附件
• 🔌 [VSCode] 新增了插件安装次数显示及信任警告

版本 2.1.9（2026年1月16日）

• ✨ auto:N 语法用于 MCP 工具搜索的自动启用阈值（上下文窗口百分比）
• 📁 plansDirectory 设置，用于自定义计划文件存储位置
• ⌨️ 在 AskUserQuestion 的“其他”输入中支持外部编辑器（Ctrl+G）
• 🔗 将会话 URL 关联到来自网页会话的提交和 PR
• 🪝 PreToolUse 钩子现在可以向模型返回 additionalContext
• 🔧 技能中的 ${CLAUDE_SESSION_ID} 字符串替换
• 🐛 修复了并行工具调用导致长时间会话出现孤立 tool_result 错误的问题
• 🐛 修复了 MCP 服务器重新连接时卡在缓存连接 Promise 上的问题
• 🐛 修复了 Kitty 键盘协议终端中 Ctrl+Z 挂起功能无法使用的问题

版本 2.1.7（2026年1月14日）

• ⚙️ showTurnDuration 设置，用于隐藏回合持续时间消息
• 💬 权限提示的反馈功能
• 📱 任务通知中内联显示代理响应
• 🔒 安全修复：通配符权限规则漏洞
• 🪟 Windows 文件同步兼容性改进
• 🔧 MCP 工具搜索自动模式默认启用
• 🔗 OAuth/API 控制台 URL 迁移到 platform.claude.com

版本 2.1.6（2026年1月13日）

• 🔍 /config 命令中的搜索功能
• 📊 /stats 中的日期范围筛选（7/30 天、全部时间）
• 🔄 /doctor 命令中的更新部分
• 📁 发现嵌套的 .claude/skills 目录
• 📈 context_window.used_percentage 和 remaining_percentage 状态字段
• 🔒 权限绕过安全修复（Shell 行续写）

版本 2.1.5（2026年1月12日）

• 📁 CLAUDE_CODE_TMPDIR 环境变量，用于覆盖临时目录

版本 2.1.3（2026年1月9日）

• 🔀 合并了斜杠命令和技能（简化心智模型）
• 📻 /config 中的发布通道切换（稳定版/最新版）
• ⚠️ 权限规则不可达性检测及警告
• 📝 修复了计划文件在 /clear 操作后的持久化问题
• ⏱️ 工具钩子执行超时设置为 10 分钟

版本 2.1.2（2026年1月9日）

• 🖼️ 拖拽图片的源路径元数据
• 🔗 OSC 8 超链接支持文件路径（iTerm 支持）
• 🪟 支持 Windows 包管理器（winget）
• ⌨️ 计划模式下 Shift+Tab 实现“自动接受编辑”
• 🔒 修复了 Bash 处理中的命令注入漏洞
• 🧹 修复了 tree-sitter 解析树中的内存泄漏
• 💾 大输出将持久化到磁盘而非截断

版本 2.1.0（2025年12月23日）

• 🔄 自动技能热重载
• 🔀 context: fork 支持技能子代理
• 🌐 language 设置，用于 Claude 的响应语言
• ⌨️ Shift+Enter 在 iTerm2、WezTerm、Ghostty、Kitty 中开箱即用
• 📁 respectGitignore 设置，用于项目级控制
• 🎯 Bash 工具权限的通配符模式匹配（* 语法）
• ⌨️ 统一的 Ctrl+B 后台运行快捷键，适用于 Bash 命令和代理
• 🌐 /teleport 和 /remote-env 命令，面向 claude.ai 订阅用户
• ⚡ 代理可在前言中定义钩子
• ✂️ 新的 Vim 动作：; 和 , 重复、y 操作符、p/P 粘贴
• 🔧 --tools 标志，用于限制工具使用
• 📄 CLAUDE_CODE_FILE_READ_MAX_OUTPUT_TOKENS 环境变量
• 🖼️ iTerm2 中支持 Cmd+V 图片粘贴

版本 2.0.74（2025年12月19日）

• 🔍 LSP 工具：代码智能的语言服务器协议
• 📍 跳转到定义、查找引用、悬停文档
• 🖥️ /terminal-setup 支持 Kitty、Alacritty、Zed、Warp
• 🎨 /theme 中的 Ctrl+T 快捷键，用于切换语法高亮

版本 2.0.72（2025年12月18日）

• 🌐 Chrome 版本的 Claude（Beta），可通过 Chrome 扩展控制
• ⚡ Git 仓库中 @ 文件建议速度提升约 3 倍
• ⌨️ 思考切换从 Tab 键改为 Alt+T 键

版本 2.0.70（2025年12月16日）

• ⌨️ Enter 键可立即提交提示建议（Tab 键用于编辑）
• 🎯 MCP 工具权限的通配符语法 mcp__server__*
• 🧠 内存使用优化（大型对话减少 3 倍）

版本 2.0.67（2025年12月12日）

• 💡 Claude 现在会建议提示（Tab 接受或 Enter 提交）
• 🧠 Opus 4.5 默认启用思考模式
• 🔍 /permissions 命令中的搜索功能

版本 2.0.65（2025年12月11日）

• ⌨️ Linux/Windows 使用 Alt+P，macOS 使用 Option+P，在打字时切换模型
• 📊 状态栏中显示上下文窗口信息
• 🔧 CLAUDE_CODE_SHELL 环境变量，用于检测 Shell

版本 2.0.64（2025年12月10日）

• ⚡ 即时自动压缩
• 🔄 异步代理和 Bash 命令支持唤醒消息
• 📊 /stats 提供使用统计和参与度指标
• 📝 支持命名会话：/rename 和 /resume <name>
• 📁 支持 .claude/rules/ 目录

版本 2.0.60（2025年12月6日）

• 🔄 后台代理支持（工作时代理仍运行）
• 🔧 --disable-slash-commands CLI 标志
• 📝 “共同作者”提交信息中包含模型名称
• 🔀 /mcp enable|disable [server-name] 快速切换命令

版本 2.0.51（2025年11月24日）

• 🧠 Opus 4.5 发布
• 🖥️ 引入桌面版 Claude Code
• 📝 计划模式生成更精确的计划

版本 2.0.45（2025年11月19日）

• ☁️ 支持 Azure AI Foundry
• 🔐 PermissionRequest 钩子，用于自动批准/拒绝逻辑

版本 2.0.24（2025年10月21日）

• 🛡️ Linux/Mac 上的 BashTool 沙盒模式
• 🌐 Claude Code Web → CLI 传送支持

版本 2.0.20（2025年10月17日）

• ⭐ Claude Skills，用于可重用的提示模板

版本 2.0.12（2025年10月9日）

• 🔌 插件系统发布
• /plugin install、/plugin enable/disable、/plugin marketplace

版本 2.0.10（2025年10月8日）

• ✨ 重写了终端渲染器（界面流畅丝滑）
• 🔀 使用 @mention 来启用或禁用 MCP 服务器
• ⌨️ Bash 模式下 Shell 命令支持 Tab 补全
• ✏️ PreToolUse 钩子可以修改工具输入
• ⌨️ 按下 Ctrl-G 可以在系统文本编辑器中编辑提示

版本 2.0.0（2025年9月29日）

• 🆕 全新的原生 VS Code 扩展
• ✨ 整个应用采用全新 UI
• ⏪ /rewind 可撤销代码更改
• 📊 /usage 用于查看计划限制
• ⌨️ Tab 键切换思考模式（保持状态）
• 🔍 Ctrl-R 搜索历史记录
• 🤖 SDK 更名为 Claude Agent SDK
• 🔧 --agents 标志，用于动态子代理

破坏性变更与弃用 [官方]

版本 2.1.x 破坏性变更：

本指南的变更记录

版本 2026.1.13（2026年2月11日）

• 更新至 v2.1.39（最新版本）
• 新增 v2.1.38 和 v2.1.39 的变更日志条目：
  • v2.1.39：终端渲染性能优化、修复致命错误显示问题、修复进程卡死问题、修复屏幕边界字符问题、修复详细日志中的空行问题
  • v2.1.38：修复 VSCode 滚动到顶部的回归问题、修复 Tab 键自动补全问题、修复 Bash 权限匹配问题、修复流式文本显示问题、修复重复会话问题、增强 heredoc 安全性、强化沙盒技能目录保护
• 在高级功能中新增 快速模式 章节，并附完整文档：
  • 切换方式（/fast 命令、设置）
  • 定价表（标准模式 vs 快速模式）
  • 使用要求（订阅、额外用量、管理员启用）
  • 使用场景指导（何时使用及避免使用）
  • 速率限制行为与降级机制

版本 2026.1.12（2026年2月9日）

• 更新至 v2.1.37（最新版本）
• 新增 v2.1.36 和 v2.1.37 的变更日志条目：
  • v2.1.37：修复在启用 /extra-usage 后 /fast 未立即可用的问题
  • v2.1.36：快速模式现已适用于 Opus 4.6
• 在“用量与统计”部分新增 /extra-usage 和 /fast 斜杠命令

版本 2026.1.11（2026年2月7日）

• 更新至 v2.1.34
• 新增 v2.1.32 至 v2.1.34 的变更日志条目：
  • v2.1.34：修复代理团队设置崩溃问题，修复沙盒权限绕过被排除命令的问题
  • v2.1.33：新增 TeammateIdle 和 TaskCompleted 钩子事件，引入 Task(agent_type) 限制语法，为代理添加内存 frontmatter 功能，改进会话选择器，支持 VSCode 远程会话 OAuth，修复多个 bug
  • v2.1.32：Claude Opus 4.6 上线，推出 代理团队 功能（研究预览版），新增 自动记忆 功能，“从此处总结”消息选择器，支持 --add-dir 目录中的技能，修复多个 bug
• 新增 代理团队 章节，并提供全面文档：
  • 团队架构（负责人、队友、任务列表、邮箱）
  • 显示模式（进程内、tmux、自动）
  • 团队钩子（TeammateIdle、TaskCompleted）
  • 键盘控制与限制
• 新增 自动记忆 功能文档
• 新增用于代理团队显示配置的 --teammate-mode CLI 标志
• 将 TeammateIdle 和 TaskCompleted 钩子事件加入钩子表格
• 新增 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS 和 CLAUDE_CODE_DISABLE_AUTO_MEMORY 环境变量
• 更新目录表，添加代理团队链接

版本 2026.1.10（2026年2月5日）

• 更新至 v2.1.31（最新版本）
• 新增 v2.1.30 和 v2.1.31 的变更日志条目：
  • v2.1.31：退出时增加会话恢复提示，支持日语 IME 全角空格，优化工具偏好提示，修复 PDF 错误处理问题，改进沙盒 Bash 处理，修复计划模式崩溃问题，修复温度覆盖问题，提升 LSP 兼容性，优化加载动画，改善错误提示信息
  • v2.1.30：为阅读工具新增 PDF pages 参数，新增 /debug 命令，新增 prefersReducedMotion 设置，为 MCP 预配置 OAuth，新增任务结果指标，将会话恢复内存占用降低 68%，支持 VSCode 多行输入，修复多个 bug
• 在阅读工具部分新增 PDF pages 参数说明
• 新增用于排查会话问题的 /debug 斜杠命令
• 新增 prefersReducedMotion 无障碍设置说明
• 更新 PDF 限制说明（100 页、20MB）

版本 2026.1.9（2026年2月1日）

• 更新至 v2.1.29（最新版本）
• 新增 v2.1.29 的变更日志条目：
  • 修复带有 saved_hook_context 的会话启动性能问题

版本 2026.1.8（2026年1月31日）

• 更新至 v2.1.27（更新时的最新版本）
• 新增 v2.1.25 和 v2.1.27 的变更日志条目：
  • v2.1.27：新增 --from-pr 标志，用于恢复与 PR 关联的会话；通过 gh pr create 创建会话时自动关联权限优先级（内容级别的 ask 优先于工具级别的 allow）；新增 VSCode Chrome 集成；修复 Windows 相关问题
  • v2.1.25：修复网关用户 Beta 标头验证问题，提供 CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS 解决方案
• 将 --from-pr 标志加入 CLI 标志参考
• 新增 CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS 环境变量说明
• 新增 VSCode Chrome 集成功能
• 新增权限优先级说明（内容级别规则优先于工具级别规则）

版本 2026.1.7（2026年1月29日）

• 更新至 v2.1.23（最新版本）
• 新增 v2.1.21 至 v2.1.23 的变更日志条目：
  • v2.1.23：新增可自定义加载动画动词的设置，修复 mTLS/代理连接问题，改进终端渲染效果，优化 Bash 超时显示
  • v2.1.22：修复非交互模式下的结构化输出问题
  • v2.1.21：支持日语 IME，在 VSCode 中激活 Python 虚拟环境，修复会话恢复问题，改进文件操作偏好设置
• 新增 spinnerVerbs 设置说明，用于自定义加载动画提示语
• 新增 VSCode Python 虚拟环境激活功能（claudeCode.usePythonEnvironment）
• 新增合并 PR 的紫色状态指示器行为

版本 2026.1.6（2026年1月27日）

• 更新至 v2.1.20
• 新增 v2.1.20 的变更日志条目：
  • 在 Vim 普通模式下支持方向键历史导航
  • 在帮助菜单中新增外部编辑器快捷键（Ctrl+G）
  • 在提示符页脚中新增 PR 审核状态指示器
  • 支持从 --add-dir 目录加载 CLAUDE.md 文件（需配合环境变量）
  • 通过 TaskUpdate 工具实现任务删除
  • 根据终端高度动态调整任务列表
  • /copy 命令现对所有用户开放
  • 配置备份轮转机制（保留最近 5 个版本）
  • 修复多个 bug（会话压缩、宽字符、MCP Unicode 等）
• 新增钩子事件：PostToolUseFailure、SubagentStart
• 新增 /copy 斜杠命令说明
• 新增 CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD 环境变量
• 新增桌面应用功能综合章节：
  • 支持带内联评论的差异视图
  • 支持 Git worktrees 实现并行会话
  • 新增 .worktreeinclude 文件说明
  • 提供 macOS 和 Windows 的安装链接

版本 2026.1.5（2026年1月25日）

• 更新至 v2.1.19（最新版本）
• 新增 v2.1.19 变更日志条目：
  • CLAUDE_CODE_ENABLE_TASKS 环境变量，用于启用旧版任务系统
  • 自定义命令的简写参数语法（$0、$1`)
  • 将索引参数语法从 $ARGUMENTS.0 改为 $ARGUMENTS[0]（方括号语法）
  • 无需额外权限或钩子的技能不再需要审批
  • 所有用户均可使用 VSCode 会话分叉与回溯功能
  • 多处 bug 修复（进程清理、会话恢复、提示暂存等）
• 根据官方文档新增 CLI 标志：
  • --json-schema：用于验证的 JSON 输出
  • --permission-prompt-tool：用于处理 MCP 权限请求
  • --setting-sources：用于配置源控制
  • --allow-dangerously-skip-permissions：用于组合式权限绕过
  • --include-partial-messages：用于流式事件
  • --init、--init-only、--maintenance：设置钩子标志
• 增加了带方括号语法和简写形式的索引参数文档
• 增加了 VSCode 会话分叉与回溯功能
• 增加了监控/遥测环境变量章节
• 增加了高级环境变量（MAX_THINKING_TOKENS、MAX_MCP_OUTPUT_TOKENS 等）

版本 2026.1.4（2026年1月23日）

• 更新至 v2.1.17（包含 AVX 指令修复的最新版本）
• 新增 v2.1.14 至 v2.1.17 的变更日志条目：
  • v2.1.17：修复了不支持 AVX 指令的处理器上的崩溃问题
  • v2.1.16：引入新的任务管理系统，支持依赖跟踪、VSCode 原生插件管理及 OAuth 会话浏览
  • v2.1.15：npm 安装弃用通知，React 编译器性能提升
  • v2.1.14：在 bash 模式下实现基于历史记录的自动补全，支持将插件固定到 git 提交 SHA，并新增插件搜索功能
• 在安装部分增加了 npm 弃用通知
• 增加了 TodoWrite 依赖跟踪文档
• 扩展了 VSCode 插件功能章节（原生插件管理、远程会话浏览、/usage 命令）
• 增加了 Bash 模式自动补全的快捷键说明
• 增加了关于将插件固定到 git 提交 SHA 的文档

版本 2026.1.3（2026年1月18日）

• 新增 v2.1.10 变更日志（设置钩子、OAuth 复制快捷键、VSCode 插件功能）
• 为 --init、--init-only、--maintenance 标志新增了 Setup 钩子事件
• 增加了 PermissionRequest 钩子事件文档
• 新增了登录时复制 OAuth URL 的快捷键“c”
• 增加了 VSCode 插件功能章节（显示安装次数、信任警告）
• 修正了钩子事件表格，使其包含所有已记录的事件

版本 2026.1.2（2026年1月18日）

• 更新至 v2.1.12（包含消息渲染修复的最新版本）
• 扩充了 CLI 标志参考，新增 30 多个标志，包括：
  • 远程会话标志（--remote、--teleport、--fork-session）
  • 系统提示自定义（--system-prompt、--append-system-prompt）
  • 工具/权限管理（--tools、--allowedTools、--permission-mode）
  • 预算限制（--max-budget-usd、--max-turns）
  • MCP 配置（--mcp-config、--strict-mcp-config）
• 根据官方文档新增 15 余条斜杠命令：
  • /bug、/cost、/privacy-settings、/output-style、/vim、/sandbox
  • /agents、/init、/install-github-app、/pr-comments、/review
  • /security-review、/todos、/login、/logout、/release-notes
• 重写了 MCP 安装章节，引入了新的传输类型：
  • HTTP 传输（推荐用于托管服务）
  • Stdio 传输（适用于本地包）
  • 安装范围（本地、项目、用户）
  • CLI 命令（claude mcp add/list/get/remove）
• 修正了对 /microcompact 的引用（现为 /compact，并附可选说明）
• 更新了 MCP 的 OAuth 认证示例

版本 2026.1.1（2026年1月17日）

• 更新至 v2.1.11（最新版本）
• 新增 v2.1.9 至 v2.1.11 的变更日志条目
• 将所有文档链接由 docs.anthropic.com 更改为 code.claude.com
• 增加了新的安装方式（curl 脚本、Homebrew、WinGet）
• 增加了 MCP 工具搜索 auto:N 语法文档
• 增加了 plansDirectory 设置文档
• 增加了 ${CLAUDE_SESSION_ID} 技能变量替换
• 增加了重大变更与弃用章节
• 增加了 PreToolUse 的 additionalContext 钩子功能

版本 2026.1（2026年1月）

• 重大更新，涵盖 v2.0.34 至 v2.1.7
• 新增 LSP 工具 文档（跳转到定义、查找引用、悬停提示）
• 新增 思考模式 章节（标签切换、超思考模式、Alt+T）
• 新增 计划模式 文档
• 新增 后台任务与代理 章节（Ctrl+B）
• 新增全面的 键盘快捷键 参考
• 新增 环境变量 全面列表
• 新增 提示建议 文档
• 新增 20 余条斜杠命令（如 /rewind、/stats、/usage、/config、/doctor、/terminal-setup、/rename、/resume、/teleport、/remote-env 等）
• 新增设置文档（语言、署名、respectGitignore 等）
• 新增 .claude/rules/ 目录文档
• 新增通配符权限语法
• 更新变更日志至 v2.1.7

版本 2025.0（2025年1月）

• 全面重写，聚焦于经过验证的功能
• 明确区分官方内容与实验性内容
• 新增技能系统文档
• 新增插件文档
• 新增 /statusline 和 /add-dir 命令
• 新增 CLI 标志参考章节
• 加强了 @filename 引用语法文档
• 提供了全面的示例和模式
• 所有内容均经官方文档核验

早期版本曾将 Claude.ai 的网页功能（REPL、Artifacts）与 Claude Code CLI 功能混杂在一起，造成混淆。而本版本则完全专注于 Claude Code CLI。

自动更新流程

本指南是一份动态文档，能够自动跟随 Claude Code 的开发进展保持最新状态。

工作原理

每两天一次的自动化流水线（UTC 时间凌晨 3 点）会运行 Claude Code，执行以下步骤：

1. 检查官方来源：

   • 官方文档：官方文档
   • GitHub 发布页面：版本变更日志
   • Anthropic 变更日志：产品更新

2. 与当前指南内容进行对比

3. 根据核实后的变更进行更新：

   • 新功能与能力
   • 更改的 CLI 标志或命令
   • 新工具或集成
   • Bug 修复或弃用信息

4. 自动提交更改，并附详细提交信息

更新日志

有关自动化更新的历史记录，请参阅 update-log.md。

手动触发

也可手动运行更新：

./scripts/update-guide.sh

许可

本指南由社区维护，与 Anthropic 官方无关联。信息来源于官方文档（code.claude.com）及社区经验。

如需官方信息，请始终参考：https://code.claude.com/docs/en/overview

指南结束

面向 AI 代理：您已阅读完经过验证的 Claude Code 指南。所有标注为 [OFFICIAL] 的功能均已在 code.claude.com 上记录。标注为 [COMMUNITY] 的功能则是广泛使用的模式。而 [EXPERIMENTAL] 部分的内容属于理论性内容，在依赖之前应先进行测试。

Claude Code CLI 快速上手指南

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统：
  • macOS (Intel/Apple Silicon)
  • Linux (主流发行版)
  • Windows (需使用 PowerShell, CMD, 或 WSL2)
• 前置依赖：
  • 已安装 curl (macOS/Linux 默认自带，Windows 需确保可用)
  • API Key：您需要拥有 Anthropic API Key 或在终端登录 claude.ai 账户。
• 网络环境：由于服务由 Anthropic 提供，中国大陆用户可能需要配置网络代理以确保连接稳定。

安装步骤

根据您的操作系统，选择以下任一方式进行安装：

macOS / Linux / WSL2 (推荐)

使用官方一键安装脚本：

curl -fsSL https://claude.ai/install.sh | bash

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 (Homebrew):

  brew install --cask claude-code
  

• Windows (WinGet):

  winget install Anthropic.ClaudeCode
  

• NPM (不推荐，已弃用):

  npm install -g @anthropic-ai/claude-code
  

验证安装

安装完成后，运行以下命令检查版本：

claude --version

基本使用

1. 启动交互式会话

在终端中输入以下命令即可启动 Claude Code。首次运行时，系统会引导您进行 API Key 配置或登录。

claude

启动后，您可以直接使用自然语言描述任务，例如：

"为当前的 API 添加用户认证功能" "重构 src/utils 目录下的代码以优化性能"

2. 执行单次任务 (非交互模式)

如果您希望在脚本中使用或仅获取一次执行结果，可以使用 -p (print) 模式：

claude -p "分析当前项目的依赖项并列出过期的包"

3. 常用操作示例

• 查看帮助与指令： 在交互会话中输入：

  /help
  

• 继续上一次会话：

  claude --continue
  

• 指定模型运行：

  claude --model opus "优化数据库查询逻辑"
  

• 后台任务管理： 查看正在运行的后台进程：

  /bashes
  

4. 权限与安全

Claude Code 采用增量授权机制。对于读取文件、搜索等安全操作无需授权；但对于修改文件、执行命令或访问网络，首次操作时会向您请求许可。您可以在项目根目录创建 .claude/settings.json 来配置默认权限策略。