Claude Code 使用指南

本文档整理自 Claude Code 官方文档及社区最佳实践，帮助团队高效使用 Claude Code CLI、IDE、Desktop 和 Web 等入口。

注意： 如果在防火墙或代理后使用，通常需要设置 HTTP_PROXY、HTTPS_PROXY 环境变量，或按企业网络策略配置。
维护： 涉及安装方式、模型名称、CLI 参数、订阅权益、权限策略、Hooks、Skills、MCP、IDE 插件和 Desktop/Web 能力时，使用前应重新核对官方文档或当前账号界面；本仓库最后核对日期为 2026-05-26。

目录

• 概述
• 安装与入门
• 核心概念
• CLAUDE.md — 项目基础设施
• 权限管理
• Hooks 自动化
• 模型与配置
• Slash Commands 常用命令
• Subagents 与 Agent Teams
• MCP 集成
• IDE 集成
• 成本优化
• 最佳实践清单
• 常见问题
• 迭代记录
• 参考

---

概述

Claude Code 是 Anthropic 的 agentic coding 工具，可以读取代码库、编辑文件、运行命令，并和终端、IDE、Desktop、Web、CI/CD、MCP 等开发工具集成。它不只是命令行工具，但 CLI 仍然是本地开发中最常用、最直接的入口。

常见能力：

• 读写文件、运行命令、管理 Git
• 多模型切换（default / opus / sonnet / haiku 等别名，具体解析取决于账号和部署方式）
• 并行子代理（Subagents / Agent Teams）
• MCP 协议扩展外部工具
• VS Code / JetBrains IDE 集成、Desktop/Web 入口
• 自定义 Hooks、Skills、Slash Commands

---

安装与入门

环境要求

• Claude 订阅或 Anthropic Console 账号，具体可用入口和额度以当前账号为准。
• macOS、Linux、WSL、Windows 均可使用，入口和安装方式不同。
• 在原生 Windows 中建议安装 Git for Windows，方便 Claude Code 使用 Bash 工具；WSL 场景不需要 Git for Windows。
• 如果使用旧的 npm 安装方式，需单独确认当前官方是否仍推荐以及本机 Node.js 版本要求。

安装

官方当前推荐优先使用 Native Install。

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 或 WinGet：

brew install --cask claude-code

winget install Anthropic.ClaudeCode

旧版 npm 安装方式如果仍在使用，升级前先核对官方说明：

npm install -g @anthropic-ai/claude-code

首次运行：

claude

Native Install 通常会自动后台更新；Homebrew 和 WinGet 安装需要分别用 brew upgrade 或 winget upgrade 更新。

基本使用

# 进入项目目录后启动
cd my-project
claude

# 非交互模式（单次问答）
claude -p "解释这个项目的架构"

# 指定模型
claude --model opus

# 打印模式 + 管道
cat error.log | claude -p "分析这些错误日志"

---

核心概念

Claude Code 的配置体系分为几层，各有分工：

机制	作用	强制力
CLAUDE.md	描述项目规范、约定、架构	建议性（Claude 自行判断是否适用）
settings.json	控制权限（允许/拒绝哪些工具）	确定性（强制执行）
Hooks	在工具调用前后自动执行脚本	确定性（可阻断操作）
Skills	可复用的多步骤工作流	按需加载

核心原则：settings.json 管"你能做什么"，CLAUDE.md 管"你怎么做"。如果一个规则每次都必须执行（提交前 lint、禁止写 migrations/），放到 Hooks 里，不要放 CLAUDE.md。

配置层级（优先级从高到低）

优先级	层级	文件	是否入库
1（最高）	组织强制策略	managed-settings.json	否
2	命令行参数	启动参数	否
3	项目个人	.claude/settings.local.json	否（自动 gitignore）
4	项目共享	.claude/settings.json	是
5（最低）	用户全局	~/.claude/settings.json	否

普通设置按上述优先级覆盖。权限规则比较特殊，会跨 scope 合并；涉及企业托管策略时，以 managed / policy 设置为最终约束。

目录结构总览

~/.claude/
├── CLAUDE.md                 # 全局指令（所有项目生效）
├── settings.json             # 全局权限与 Hooks
└── projects/                 # 会话历史 + 自动记忆

your-project/
├── CLAUDE.md                 # 团队共享指令（入库）
├── CLAUDE.local.md           # 个人覆盖（不入库）
├── .mcp.json                 # MCP 服务器配置（入库）
└── .claude/
    ├── settings.json         # 团队共享权限 + Hooks（入库）
    ├── settings.local.json   # 个人覆盖（不入库）
    ├── rules/                # 模块化的路径规则文件
    ├── commands/             # 自定义 Slash Commands
    ├── skills/               # 技能工作流
    ├── agents/               # 自定义子代理
    └── hooks/                # Hook 脚本

---

CLAUDE.md — 项目基础设施

加载机制

CLAUDE.md 按层级加载（高优先级覆盖低优先级）：

1. 组织策略 — 托管策略，最高优先级
2. 用户全局 — ~/.claude/CLAUDE.md
3. 项目根目录 — ./CLAUDE.md 或 ./.claude/CLAUDE.md
4. 本地项目 — ./CLAUDE.local.md（不入库）
5. 父目录 — 启动时加载（支持 monorepo）
6. 子目录 — 按需加载（当 Claude 读取该目录文件时）

应该写什么 vs 不该写什么

应该写	不该写
Claude 猜不到的 bash 命令	能从代码直接读出的信息
与默认风格不同的代码规范	标准语言约定
测试指令和运行器	详细 API 文档（放链接）
仓库礼仪（分支命名、PR 规则）	频繁变动的信息
架构决策和环境怪癖	逐文件的代码库描述
常见陷阱和非明显行为	不言自明的实践（如"写干净代码"）

@import 语法

See @README.md for project overview and @package.json for available commands.
# Additional Instructions
- Git workflow: @docs/git-workflow.md

• 加载时内联解析（非惰性加载）
• 支持最多 5 层递归引用

路径规则（.claude/rules/）

---
paths:
  - "src/api/**/*.ts"
  - "src/handlers/**/*.ts"
---

# API Design Rules
- All handlers return { data, error } shape
- Use zod for request body validation

不含 paths 的规则启动时加载；含 paths 的规则按需加载。

---

权限管理

三种权限级别

• allow — 静默允许，不询问
• deny — 完全阻止，无法继续
• 未列出 — 每次询问确认（默认安全层）

推荐配置示例

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "allow": [
      "Bash(git status)",
      "Bash(git diff *)",
      "Bash(git log *)",
      "Bash(git add *)",
      "Bash(npm run *)",
      "Read",
      "Write",
      "Edit",
      "Glob",
      "Grep"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(curl *)",
      "Bash(wget *)",
      "Read(.env)",
      "Read(.env.*)"
    ]
  }
}

警告： permissions.allow 会完全绕过 Hooks。如果把工具加到 allow，对应的 PreToolUse hook 不会再触发。

Auto Mode

{
  "permissions": {
    "defaultMode": "auto"
  }
}

安全的编辑和命令自动放行，破坏性操作被阻断并提示。

---

Hooks 自动化

Hooks 是 Claude Code 的确定性自动化层，可以在生命周期事件触发时运行命令、HTTP hook 或 MCP tool hook，用于审计、注入上下文、阻断风险操作或通知外部系统。

维护： Hook 事件、输入字段和可阻断能力变化较快。写生产级 hook 前应以官方 Hooks reference 为准，并在本机用 /hooks 查看当前实际加载结果。

Hook 事件

事件	触发时机	常见用途
SessionStart	会话开始时	注入上下文（分支名、PR 摘要）
InstructionsLoaded	指令文件加载时	审计 CLAUDE.md / 规则加载情况
UserPromptSubmit	用户提交 prompt 后、模型处理前	检查敏感信息、按 prompt 注入上下文
UserPromptExpansion	slash command 或 MCP prompt 展开时	限制某些命令直接调用、补充上下文
PreToolUse	工具调用之前	门禁 — 阻断、放行或警告
PostToolUse	工具成功执行后	Lint、格式化、通知
PostToolUseFailure	工具执行失败后	告警、日志
PostToolBatch	一批工具调用结束后	批量汇总、延迟校验
PreCompact	上下文压缩前	保存重要状态
SubagentStart / SubagentStop	子代理启动或结束	子代理审计和结果检查
Stop	会话结束时	通知、清理

Hook 退出码

退出码	行为
0	静默放行
1	显示消息 + 询问用户
2	硬阻断（无法继续）

部分事件还支持返回 JSON，例如 additionalContext、decision: "block"、reason 等字段。不要只靠退出码设计复杂策略，先确认该事件支持哪些 decision control。

示例：提交前自动 lint

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Bash(git commit *)",
      "hooks": [{
        "type": "command",
        "command": ".claude/hooks/lint-staged.sh"
      }]
    }]
  }
}

Hook 输入（通过 stdin JSON）

{
  "session_id": "abc-123",
  "hook_event_name": "PreToolUse",
  "tool_name": "Bash",
  "tool_input": { "command": "git commit -m 'feat: add login'" }
}

---

模型与配置

模型别名与默认值（2026-05-26 核对）

Claude Code 支持 default、opus、sonnet、haiku 等别名，也支持在企业或第三方部署中用完整模型 ID、环境变量或托管策略固定解析结果。

选择	适用场景
default	使用当前账号或部署方式的默认模型；最省心，但会随官方策略变化
opus	复杂重构、安全审查、跨文件大改动、架构判断
sonnet	日常编码实现、测试生成、常规 review
haiku	快速搜索、简单问答、低成本探索

当前官方说明中，default 会随账号类型变化：Max 和 Team Premium 默认偏向 Opus；Pro、Team Standard、Enterprise、Anthropic API 默认偏向 Sonnet；Bedrock、Vertex、Foundry 默认值可能不同。不要把模型版本号写死到长期团队规范里，除非你明确需要版本锁定。

切换模型

# 启动时指定
claude --model opus

# 会话中切换
/model

推理力度（Effort）

/effort low      # 快速响应
/effort medium   # 默认
/effort high     # 复杂推理
/effort xhigh    # 最强推理（Opus）
/effort max      # 极限推理

max 适合少量高难度任务，不建议作为团队默认值。需要强制固定模型体验时，组合使用 model、availableModels 和 ANTHROPIC_DEFAULT_*_MODEL 环境变量；仅设置 model 只是初始选择，用户仍可能在 /model 中切换。

Fast Mode

/fast             # 开关快模式（同模型，更快输出）

---

Slash Commands 常用命令

Claude Code 命令会随版本、平台、账号计划和已启用插件变化。输入 / 查看当前会话实际可用命令；本文只记录高频命令和使用边界。

会话与上下文管理

命令	说明
/clear	清除对话历史，释放上下文窗口
/compact [focus]	压缩对话摘要，可选聚焦某主题
/rewind	回退对话或代码到之前的检查点
/resume [name]	恢复之前的会话
/branch [name]	从当前点创建对话分支
/rename [name]	命名当前会话（便于后续恢复）
/teleport	把 Web 会话拉回当前终端
/remote-control	让当前会话可从其他设备远程控制

代码与质量

命令	说明
/init	初始化项目，生成 CLAUDE.md
/plan [desc]	进入计划模式（只读探索，不改代码）
/commit	暂存并提交，自动生成提交信息
/diff	交互式 diff 查看器
/review [PR]	在本地会话中审查 PR
/security-review	安全审查当前改动
/ultrareview [PR]	云端深度多代理 code review，具体额度以账号为准
/simplify [focus]	3 个并行审查代理检查复用性、质量、效率
/pr-comments [PR]	获取并处理 GitHub PR 评审意见
/autofix-pr	云端代理监控当前 PR 并自动推送修复

监控与诊断

命令	说明
/context	可视化上下文窗口占用（颜色网格）
/usage	查看 session cost、计划用量限制和活动统计；/cost、/stats 是别名
/status	显示版本、模型、账户信息
/doctor	诊断安装、配置、认证问题
/bug	提交 bug 报告（含会话日志）
/insights	生成会话分析报告

系统与配置

命令	说明
/help	显示所有可用命令
/config	打开设置面板（主题、权限等）
/theme	切换颜色主题
/terminal-setup	配置终端快捷键
/statusline	配置状态栏
/permissions	查看/管理工具权限
/hooks	查看/管理已配置的 Hooks
/mcp	管理 MCP 服务器连接
/memory	查看/编辑记忆文件
/agents	管理 agent 配置
/skills	查看可用 skills，并隐藏不希望出现在菜单中的 skill

/vim 在新版本中已移除，编辑模式改到 /config 的 Editor mode 中设置。

自动化与循环

命令	说明
/loop [interval] [prompt]	按间隔循环运行命令
/schedule	管理定时远程代理任务
/stop	停止当前 background session
/tasks	查看和管理后台任务

自定义命令

# 项目级 skill（入库）:
.claude/skills/<name>/SKILL.md → /<name>

# 用户级 skill（所有项目可用）:
~/.claude/skills/<name>/SKILL.md → /<name>

# 旧式项目命令（入库）:
.claude/commands/<name>.md     →  /<name>

# 旧式用户命令（所有项目可用）:
~/.claude/commands/<name>.md   →  /<name>

# 子目录前缀:
.claude/commands/db/migrate.md →  /db:migrate

Skills 和命令文件中可用 $ARGUMENTS 获取完整参数，也可以使用 $ARGUMENTS[N] 或 $N 获取指定位置参数。!command 和 ````!代码块可以在 Claude 看到 prompt 之前执行 shell 并把输出注入上下文；团队环境中如需禁用，可在 managed settings 中设置disableSkillShellExecution`。

---

Subagents 与 Agent Teams

三种并行策略对比

维度	Subagents	Agent Teams	手动分屏
通信方式	只向父代理汇报	代理间直接通信	你手动传递
上下文	独立小窗口	每个完整会话	完整会话
协调方式	父代理分派	共享任务列表	你的大脑
最大并行数	约 5-8	2-16	取决于注意力
Token 成本	最低（~1.75x）	最高（~3.5x）	中等（~2x）

决策框架

问题一：代理之间需要共享发现吗？

• 是 → Agent Teams。如果 A 的输出会改变 B 的工作方向，Subagents 做不了。
• 否 → Subagents。独立任务用 Subagents 更便宜更简单。

问题二：有多少并行任务？

任务数	推荐策略
1-3	Subagents
4-8	手动分屏（要控制）或 Agent Teams（要自动化）
8+	Agent Teams

快速决策表

场景	推荐方案	原因
并行研究 5 个主题	Subagents	任务独立，成本最低
前后端 + 测试联动开发	Agent Teams	需共享类型定义、API 规格
调试 4 个独立问题	手动分屏	你想看每个修复过程
跨 30 个文件重构认证	Agent Teams	改动级联，代理间需协调
快速代码搜索分析	Subagents	快速、用完即弃

Subagents 最佳实践

1. 明确任务范围："探索支付模块如何工作"比"探索一切"好
2. 显式要求并行：“这几项可以并行执行”
3. 指定返回格式：摘要 + 文件:行号引用，不要完整文件
4. 定义自定义子代理（.claude/agents/）：

---
name: security-reviewer
description: 审查代码安全漏洞。在涉及认证、支付、用户数据的提交前主动使用。
tools: Read, Grep, Glob
model: sonnet
---
你是安全审查专家。重点检查：
- SQL 注入、XSS、命令注入风险
- 认证和授权缺陷
- 日志/错误中的敏感信息泄露
按优先级返回发现列表，附文件:行号引用。

Agent Teams 最佳实践

1. 启用条件：设置 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
2. 为每个队员指定模型——不要用默认值
3. 在 CLAUDE.md 中定义通信规则：

# Agent Teams
派发 Agent 团队时：
- 始终为每个队员指定模型
- 队员必须用 SendMessage 通信（纯文本输出对其他代理不可见）
- 队长用 TaskCreate/TaskUpdate 分配任务
- 队员完成任务后通过 TaskUpdate 标记
- 每个队员同一时间只做一件事
- 不允许两个队员同时编辑同一文件

4. 先 Plan 再执行：派发团队前先跑 /plan，避免浪费 Token
5. 从小开始：3-5 个队员是最佳点，超过 5-6 个边际收益递减

效率层级

单会话 > Subagents > 手动分屏 > Agent Teams

从左边开始，只有任务真正需要时才向右移。 大多数看起来需要 Agent Teams 的任务，3 个 Subagents 就能搞定。

---

MCP 集成

MCP（Model Context Protocol）让 Claude 连接外部工具和数据源。

添加 MCP 服务器

# 本地 stdio 服务器
claude mcp add my-server -- node /path/to/server.js

# NPX 包（最常用）
claude mcp add playwright -- npx @anthropic-ai/mcp-server-playwright@latest

# 远程 HTTP 服务器
claude mcp add my-server --transport http https://example.com/mcp

# 带认证头
claude mcp add my-server --transport http https://example.com/mcp \
  --header "Authorization: Bearer your-token"

作用域

# 用户全局（所有项目可用）
claude mcp add my-server -s user -- node server.js

# 项目级（写入 .mcp.json，可入库）
claude mcp add my-server -s project -- node server.js

项目级配置（.mcp.json）

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}

管理命令

claude mcp list          # 列出所有服务器及健康状态
claude mcp remove <name> # 移除服务器
/mcp                     # 会话中重连服务器

常用 MCP 服务器

服务器	命令
Playwright（浏览器）	npx @anthropic-ai/mcp-server-playwright@latest
GitHub	npx -y @modelcontextprotocol/server-github
Filesystem	npx -y @modelcontextprotocol/server-filesystem /path
Linear	--transport http https://mcp.linear.app/mcp
Notion	--transport http https://mcp.notion.com/mcp

---

IDE 集成

VS Code

1. 扩展市场搜索 “Claude Code”（发布者 Anthropic）
2. 安装后点击右上角 ✱ 图标打开
3. 需要 VS Code 1.98.0+

常用快捷键：

快捷键	操作
Ctrl+Esc	切换编辑器 ↔ Claude 面板
Alt+K	插入 @-mention（当前文件/选区）
Ctrl+Shift+Esc	新建对话标签页

JetBrains（IntelliJ / PyCharm / WebStorm / GoLand）

1. Settings → Plugins → Marketplace 搜索 “Claude Code [Beta]”
2. 安装后重启
3. 在 IDE 集成终端中运行 claude，插件自动检测并激活

与 VS Code 的关键区别： JetBrains 插件是对 CLI 的包装——你在 IDE 终端里运行 claude，插件自动附加 diff 查看器和文件引用功能。

第三方代理配置（如 Bedrock / 自定义 API）

// VS Code settings.json
"claudeCode.environmentVariables": [
  { "name": "ANTHROPIC_BASE_URL", "value": "http://localhost:8082" },
  { "name": "ANTHROPIC_AUTH_TOKEN", "value": "your-token" }
]

---

成本优化

策略	预期节省
混合模型：Sonnet 干活，Opus 把关	40-50%
紧缩任务范围（每个代理一个明确任务）	避免空闲上下文浪费
代码搜索用 Grep/Glob，不读取全文件	大幅减少 Token
Plan 模式先设计再执行	避免团队跑偏浪费
使用 WarpGrep 做语义搜索	比串行搜索省 40%+ 上下文
/compact 及时压缩长会话	保持上下文精简
.claudeignore 排除不需要的文件	Claude Code 比 Cursor 省 5.5x tokens

.claudeignore 示例

node_modules/
.venv/
dist/
build/
.next/
*.lock
*.min.js
*.map
coverage/
*.png
*.jpg

---

最佳实践清单

会话管理

• [ ] 两个纠错原则：同一问题上纠正 Claude 超过两次，直接 /clear 重开会话。干净的新会话 + 更好的 prompt 几乎总是优于累积纠正的长会话。
• [ ] 任务隔离：不相关的任务用 /clear 分隔，避免上下文污染。
• [ ] 上下文 70% 时就 /compact，不要等满才处理。
• [ ] 长时间任务用 Plan Mode：先探索、出方案、确认后再编码。

任务拆分

• [ ] 一次只做一件事——一个提交只表达一个意图。
• [ ] 大任务先 Plan——“我想做 X，先采访我细节”（Interview Pattern），出 SPEC.md 后再开新会话实现。
• [ ] 什么时候不用 Plan：修 typo、加日志、重命名变量——如果你能用一句话描述 diff。

代理使用

• [ ] 独立查询用 Subagents（省钱省上下文）。
• [ ] 需要协调用 Agent Teams（3-5 人起步）。
• [ ] 想全程看过程用手动分屏。
• [ ] 先 Plan 再派发团队。

Git 工作流

• [ ] 提交信息符合 Conventional Commits。
• [ ] 提交前 /diff 自检一遍。
• [ ] 高风险改动走短期分支。
• [ ] /security-review 在涉及认证、支付、用户数据时必跑。

---

常见问题

代理环境

如果需要通过代理访问 Anthropic API：

export HTTP_PROXY=http://proxy-server:port
export HTTPS_PROXY=http://proxy-server:port

安装问题

# 版本检查
claude --version

# 诊断
/claude doctor

权限问题

• 如果某工具始终被拒绝，检查 .claude/settings.json 的 deny 列表
• 如果某工具始终自动通过但不应该，检查 allow 列表（它绕过了 Hooks）

Hook 不触发

• 确认工具没有被加到 permissions.allow（allow 会绕过 Hooks）
• 检查 matcher 模式是否正确
• 退出码 2 会硬阻断，0 会静默放行

MCP 服务器断开

• 验证环境变量
• 单独运行服务器测试
• 会话中执行 /mcp 重连

---

迭代记录

• 2026-05-26：按 Claude Code 官方文档复核安装方式、配置 scope 优先级、Hooks 事件、模型别名、默认模型、effort 规则、Commands 和 Skills；将安装方式改为 Native Install 优先，移除过期 /vim 说明，并降低具体模型版本和订阅价格的硬编码。
• 2026-05-06：初始化 Claude Code 使用指南，整理 CLI、CLAUDE.md、权限、Hooks、模型、Slash Commands、Subagents、MCP 和 IDE 集成。

---

参考

• Claude Code 官方文档
• Claude Code 配置参考
• Claude Code Commands
• Claude Code 更新日志
• Claude Code Model configuration
• Claude Code Skills
• MCP 官方规范
• Conventional Commits 1.0.0
• Claude Code Best Practices (Morph, 2026)
• Claude Code Slash Commands Reference (2026)
• Agent Teams vs Subagents (Morph, 2026)
• Claude MCP Guide (GitHub)