📖 官方文档中文版 🔄 实时同步

Claude Code
完全教程

从安装到精通，系统学习 Claude Code
基于 官方文档 整理

开始安装 快速开始

🚀 安装 Claude Code

推荐方式：原生安装

自动更新，始终保持最新版本

curl -fsSL https://claude.ai/install.sh | bash
💡 提示：原生安装会在后台自动更新，确保你始终使用最新版本。

PowerShell（推荐）

irm https://claude.ai/install.ps1 | iex

CMD

curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd
⚠️ 注意：Windows 需要先安装 Git for Windows。

Homebrew 安装

brew install --cask claude-code
💡 提示：Homebrew 安装不会自动更新。定期运行 brew upgrade claude-code 获取最新功能。

WinGet 安装

winget install Anthropic.ClaudeCode
💡 提示：WinGet 安装不会自动更新。定期运行 winget upgrade Anthropic.ClaudeCode。

📱 其他平台

💻 VS Code 编辑器内联差异、@提及 🌐 Web 浏览器中运行，无需安装 🖥️ Desktop 独立桌面应用 🔥 JetBrains IntelliJ、PyCharm 等

⚡ 快速开始

1

启动 Claude Code

cd your-project
claude

首次使用会提示登录，按照指引完成认证。

2

提出你的第一个问题

这个项目做什么？
这个项目使用什么技术？
主入口点在哪里？

Claude 会自动分析你的代码库并回答问题。

3

进行第一次代码更改

在主文件中添加一个 hello world 函数

Claude Code 会：找到文件 → 显示建议 → 请求批准 → 进行编辑

4

使用 Git 操作

我更改了哪些文件？
用描述性消息提交我的更改

Git 操作变得对话式，自然语言即可完成。

📋 基本命令

命令 功能 示例
claude 启动交互模式 claude
claude "task" 运行一次性任务 claude "fix the build error"
claude -p "query" 运行一次性查询 claude -p "explain this function"
claude -c 继续最近的对话 claude -c
claude -r 恢复之前的对话 claude -r
/help 显示可用命令 /help
/clear 清除对话历史 /clear

🧠 Memory 记忆系统

Claude Code 有两个互补的记忆系统，在每次对话开始时加载：

📝

CLAUDE.md 文件

由你编写

包含指令和规则

项目、用户或组织范围

每个会话完整加载

用于：编码标准、工作流、项目架构

🤖

自动记忆

由Claude编写

包含学习和模式

每个工作树

前 200 行或 25KB

用于：构建命令、调试见解、发现的偏好

📁 CLAUDE.md 文件位置

范围 位置 用途 共享对象
项目指令 ./CLAUDE.md 或 ./.claude/CLAUDE.md 项目架构、编码标准 团队成员（通过 Git）
用户指令 ~/.claude/CLAUDE.md 个人偏好、工具快捷方式 仅你（所有项目）
托管策略 /etc/claude-code/CLAUDE.md 公司编码标准、安全策略 组织中的所有用户

📝 CLAUDE.md 示例

# 项目规则

## 代码规范
- 使用 TypeScript strict mode
- 遵循 ESLint 规则
- 测试覆盖率 > 80%

## 架构说明
- 前端: React + Vite
- 后端: Node.js + Express
- 数据库: PostgreSQL

## 工作流
- 提交前运行: npm run lint && npm test
- PR 需要 1 个以上 review

## 导入其他文件
- 详见 @README
- Git 工作流 @docs/git-instructions.md

📋 使用 .claude/rules/ 组织规则

对于大型项目，可以将规则拆分到多个文件：

your-project/
├── .claude/
│   ├── CLAUDE.md           # 主项目指令
│   └── rules/
│       ├── code-style.md   # 代码样式指南
│       ├── testing.md      # 测试约定
│       └── security.md     # 安全要求

特定路径的规则示例

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

# API 开发规则

- 所有 API 端点必须包括输入验证
- 使用标准错误响应格式
- 包括 OpenAPI 文档注释

💡 编写有效指令的技巧

✅ 具体

写具体到足以验证的指令：

  • "使用 2 空格缩进"而不是"正确格式化代码"
  • "提交前运行 npm test"而不是"测试你的更改"

📏 控制大小

每个 CLAUDE.md 文件目标在 200 行以下。较长的文件消耗更多上下文并降低遵守度。

🏗️ 结构化

使用 markdown 标题和项目符号分组相关指令。有组织的部分比密集段落更容易遵循。

🔄 一致性

如果两条规则相互矛盾，Claude 可能会任意选择一条。定期审查删除过时指令。

📂 .claude/ 与项目配置全景

Claude Code 通过多层目录与文件记住「你是谁、团队规范、自动化技能、子代理分工」。下方左为目录解剖、右为配置层级与合并规则（示意图）；读完图后再看三条合并规则与下表。

图 1 · 项目里 Claude 常看的文件：根目录 CLAUDE.md 给团队共享说明；CLAUDE.local.md 个人覆盖；.claude/ 下放权限、自定义斜杠命令、规则碎片、Skills、Agents 等。请将团队需要共享的 .claude/ 内容提交 git；带 .local 的保持私有。
your-project 根目录下 CLAUDE.md、CLAUDE.local.md 与 .claude 子目录 commands、rules、skills、agents、settings 等结构示意图
图 2 · 配置层级与合并规则：自上而下为全局 ~/.claude/、用户 ~/.claude.md、项目 your-project/，到底部「最终合并结果」。图中标注优先级从低到高；settings.json 为叠加合并，说明类文档按全局 → 用户 → 项目顺序拼接（非覆盖），任意层级 *.local 均应 gitignore、不入库。
Claude 配置：全局层、用户层、项目层与最终合并结果的纵向层级示意图，含优先级箭头与 settings 合并、文档拼接、local 不入库等说明

三条合并规则（务必与官方行为对照）

1 · CLAUDE.md 系：拼接，不是覆盖

有效层级通常按全局 → 用户 → 项目顺序依次追加到系统提示上下文中。模型能同时看到各层内容；后文与上文冲突时，模型一般会更重视更贴近当前仓库的段落，但技术上不是「只保留最后一层」——不要假设项目文件会删掉全局说明。

2 · settings.json：深度合并

JSON 配置按对象递归合并：同名字段以更具体的一层（通常是项目）为准；不冲突的键在各层保留。适合「全局默认 + 项目覆盖少数开关」。

3 · *.local：统一私有不入库

无论位于 ~/.claude/ 还是项目 .claude/，文件名含 .local 的（如 settings.local.json、CLAUDE.local.md）都应视为个人机密/本机偏好，加入 .gitignore，勿提交。

结合图 1：各目录干什么？

.claude/settings.json 团队配置 权限、模型偏好等与 JSON 可表达项；与全局 ~/.claude/settings.json 叠加，冲突键以项目为准。
.claude/commands/ 自定义斜杠命令 每个 Markdown（或当前版本支持的格式）对应一条 /命令名。部分环境会显示带命名空间前缀（如 /project:deploy），以本机 /help 为准。
.claude/rules/ 模块化规则 按文件拆分（代码风格、测试、API 约定等），可用 frontmatter 限定 paths；与根 CLAUDE.md 互补，减少单文件过长。
.claude/skills/ Skills 工作流 子目录 + SKILL.md，可被模型在合适时机自动选用或通过 /skills 浏览。
.claude/agents/ 子代理角色 定义隔离上下文的专家人设（如 code reviewer），由 /agents 或工具链挂载。

更多斜杠命令用法见本章后文 命令参考；与 Memory 章节中的 CLAUDE.md、rules frontmatter 可交叉阅读。

🔧 Skills 技能系统

Skills 扩展了 Claude 能做的事情。创建一个 SKILL.md 文件，Claude 会将其添加到其工具包中。你可以在相关时自动使用，或用 /skill-name 直接调用。

📦 内置 Skills

Skill 用途
/batch <instruction> 在代码库中并行编排大规模更改
/claude-api 加载 Claude API 参考资料和 Agent SDK 文档
/debug [description] 启用调试日志记录并排查问题
/loop [interval] <prompt> 按间隔重复运行提示
/simplify [focus] 查找代码重用、质量和效率问题并修复

🛠️ 创建你的第一个 Skill

步骤 1：创建目录

mkdir -p ~/.claude/skills/explain-code

步骤 2：编写 SKILL.md

---
name: explain-code
description: Explains code with visual diagrams and analogies. Use when explaining how code works.
---

When explaining code, always include:

1. **Start with an analogy**: Compare the code to something from everyday life
2. **Draw a diagram**: Use ASCII art to show the flow, structure, or relationships
3. **Walk through the code**: Explain step-by-step what happens
4. **Highlight a gotcha**: What's a common mistake or misconception?

步骤 3：测试 Skill

# 让 Claude 自动调用
How does this code work?

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

📁 Skills 存储位置

位置 路径 适用于
个人 ~/.claude/skills/<skill-name>/SKILL.md 你的所有项目
项目 .claude/skills/<skill-name>/SKILL.md 仅此项目
插件 <plugin>/skills/<skill-name>/SKILL.md 启用插件的位置

⚙️ Frontmatter 配置

---
name: my-skill              # Skill 名称
description: What it does   # 功能描述（推荐）
disable-model-invocation: true  # 阻止 Claude 自动调用
allowed-tools: Read Grep    # 限制可用工具
context: fork               # 在 subagent 中运行
agent: Explore              # 使用的代理类型
effort: high                # 工作量级别
paths:
  - "src/api/**/*.ts"       # 限定适用路径
---

常用字段说明

disable-model-invocation: true

只有你可以调用该 skill。用于有副作用的操作（如部署）。

user-invocable: false

只有 Claude 可以调用。用于背景知识。

allowed-tools

限制当 skill 处于活动状态时可用的工具。

context: fork

在隔离的 subagent 上下文中运行。

📤 参数传递

---
name: fix-issue
description: Fix a GitHub issue
disable-model-invocation: true
---

Fix GitHub issue $ARGUMENTS following our coding standards.

# 使用位置参数
Migrate the $0 component from $1 to $2.

运行 /fix-issue 123 时，$ARGUMENTS 会被替换为 123。

🔄 常见工作流

🔨

构建功能和修复错误

用自然语言描述你想要的内容：

向用户注册表单添加输入验证

有一个错误，用户可以提交空表单 - 修复它

Claude 会定位相关代码、理解上下文、实现解决方案并运行测试。

📝

创建提交和 PR

# 查看更改
我更改了哪些文件？

# 提交
用描述性消息提交我的更改

# 创建 PR
创建一个名为 feature/auth 的分支并打开 PR
🔍

重构和测试

# 重构
重构身份验证模块以使用 async/await

# 测试
为计算器函数编写单元测试

# 审查
审查我的更改并建议改进
🔌

MCP 集成

Model Context Protocol 让 Claude 连接外部工具：

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

CI/CD 自动化

# 分析日志
tail -200 app.log | claude -p "分析异常"

# CI 中运行
claude -p "review these changed files for security issues"

# 自动化翻译
claude -p "translate new strings into French and raise a PR"
⏰

定期任务

# 循环检查部署
/loop 5m check if the deploy finished

# 定期 PR 审查
/schedule every morning at 9am review open PRs

📖 命令参考

内置斜杠命令会随版本与账号类型变化；请以本机 /help 为准。下表补充常见命令的用途、典型用法与注意点。更完整说明见 Claude Code 官方文档；本教程 Skills 章节 可与 /skills 对照阅读。

🔌 扩展：Skills / Agents / Hooks / Plugin

/skills 浏览并启用技能包

怎么用：在 REPL 输入 /skills，进入交互界面，可查看项目 .claude/skills/、捆绑技能、插件技能等。

  • 技能目录下的说明文件常定义「何时用、分步怎么做」；部分技能会注册额外斜杠子命令（以实际 /help 为准）。
  • 与 自然语言配合：先 /skills 选对技能，再描述任务，减少模型猜流程。
/agents 管理子代理配置

怎么用：/agents 打开本地 JSX 界面，用于查看、编辑 .claude/agents/（或当前版本约定的 agents 配置目录）。

  • 典型流程：为重复子任务建专用 agent（工具白名单、提示词、工作目录），再在对话里通过工具或命令调用。
  • 修改后若未生效，可重启会话或按界面提示重载（视版本而定）。
/hooks 管理生命周期钩子

怎么用：/hooks 用于配置在工具前后、会话开始等时机运行的脚本或命令（具体事件名以文档与 /help 为准）。

  • 钩子应幂等、快速失败，避免阻塞主循环；敏感操作仍应走工具权限，不可在钩子里绕过。
/plugin 管理插件

怎么用：启用/禁用插件、查看插件提供的命令与技能；插件可能向 /skills 与斜杠命令列表注入条目。

📎 自定义斜杠命令与 Rules（易混点）

.claude/commands/ 项目自定义「命令」

产品里通常没有一个叫 /command 的内置总闸；你在仓库放 .claude/commands/复盘.md，REPL 里用的是 /复盘（文件名决定命令名，扩展名按版本约定）。

  • 用法：编辑 Markdown（或当前版本支持的格式）→ 保存 → 在同目录项目开新会话 → /help 或补全里应出现对应命令。
  • 适合固化团队流程（如「发版检查清单」），内容长时可拆成多条命令。
.claude/rules/ 按路径生效的规则

社区常统称「Rules」。一般没有单独内置 /rules 斜杠；规则以 Markdown 放在 .claude/rules/，可通过 frontmatter（如 paths）限定作用文件，与会话上下文一起注入模型。

  • 用法：与 /init 生成/补全项目说明配合；大项目按主题拆文件（代码风格、测试、安全）。
  • 修改后依赖缓存策略，必要时新开会话或按文档执行重载。

💬 会话分支、导出与「使用报告」

/branch 从当前点分叉会话

语法：/branch 或 /branch 特性名（参数 hint 为可选名称）。

在当前对话状态复制出一条新线程，便于「试 risky 方案」而不污染主线；与 Git 分支无关，是会话级分叉。

部分构建若启用 /fork 子代理功能，可能与 /branch 别名策略有关，以 /help 为准。
/export 导出当前对话

语法：/export（剪贴板或默认行为）或 /export 文件名.md。

用于归档、分享复盘、贴到工单；导出内容可能含工具调用摘要，分享前请脱敏。
/insights 会话分析报告（使用报告）

内置描述为分析你的 Claude Code 使用会话并生成报告（实现较重，首次调用可能较慢）。

  • 用法：在 REPL 执行 /insights，按提示选择时间范围或确认分析范围（以当前 UI 为准）。
  • 适合周期性复盘：常用工具、失败模式、上下文膨胀等（具体字段随版本变化）。
/copy 复制助手回复

语法：/copy 复制最近一条；/copy N 复制倒数第 N 条。便于贴到 PR、文档或 issue。
/compact 压缩上下文

触发对话摘要/压缩以腾出 token；可与自动压缩策略配合。压缩后有信息损失风险，关键结论建议写入 CLAUDE.md 或仓库笔记。
/resume · /rename · /clear 会话列表与清理
  • /resume：从历史会话继续。
  • /rename "名称"：重命名当前会话便于检索。
  • /clear：清空当前对话历史（慎用，先 /export 如需留存）。
/rewind 回到检查点

将会话与文件状态回退到先前 checkpoint（能力依赖版本与权限）；用于误改代码后的恢复，使用前确认未提交工作是否允许丢弃。

🧠 记忆与上下文

/memory 编辑记忆文件

怎么用：打开交互界面，编辑项目级 CLAUDE.md、记忆片段等（具体文件列表以 UI 为准）。

  • 适合写「长期有效」的约定：目录结构、测试命令、禁止事项。
  • 与 .claude/rules/ 分工：memory 偏全局项目说明，rules 偏路径级细则。
/init 初始化项目说明

引导生成/补全 CLAUDE.md，并扫描现有 AI 配置（如 AGENTS.md、.cursor/rules 等）写入要点，减少冷启动成本。
/add-dir 扩展可读目录

语法：/add-dir <路径>，把额外目录纳入工具默认可读范围（仍受权限与工作区策略约束）。
/mcp 管理 MCP

查看、连接、调试 MCP 服务器；修改配置后常需重连或新开会话使 tools/list 生效。

📊 用量、统计与成本

/usage 套餐用量上限

在 Claude.ai 等场景下展示计划用量与限制；若你使用纯 API/第三方端点，该命令可能不可用或显示不同，以 /help 为准。
/stats 使用统计与活动

打开统计视图（活跃度、习惯等，随产品迭代变化）；适合与 /insights 搭配：一个偏实时统计，一个偏会话分析报告。
/cost 本会话成本与时耗

展示当前会话累计成本与耗时（部分账号类型下可能隐藏或简化，以实际界面为准）。

⚙️ 配置、模型、权限与安全

/config 查看/改设置 交互式编辑用户与项目配置；改模型、主题、键位等入口常在此。
/model 切换模型 在当前会话切换推理模型（可用列表依赖账号与地区）。
/permissions 允许/拒绝规则 管理工具权限规则（allow/deny 等），与 D 课「权限模型」对应；高危操作应先在此理清策略再开自动模式。
/plan 规划模式 进入少工具、偏计划的交互模式，适合先拆任务再执行。
/login · /logout 登录状态 部分环境由安装方式决定认证，第三方 API 用户可能不显示登录流。
/doctor · /bug 诊断与反馈 /doctor 自检环境；/bug 收集问题上下文上报（勿粘贴密钥）。
/help 命令总表 始终以此为准；下文未列出的命令（如 /diff、/theme、/vim 等）在 /help 中可查。