01

初识 Claude Code

从安装到第一次对话——理解 AI 编程助手的完整架构

Claude Code 是什么?

想象你有一个超级编程搭档:它读过你整个项目,能直接读写文件、运行命令、搜索代码——而且永远不会忘记你说过的话。这就是 Claude Code

💡
核心理念

Claude Code 不是聊天机器人——它是能动手的 AI 工程师。它能读写文件、执行终端命令、搜索代码库,甚至能调用外部 API。它住在你的终端里,理解你的整个项目。

🖥️

终端原生

直接在你最熟悉的终端环境中运行,无需切换窗口,命令行就是你的 IDE。

🧠

项目感知

读取整个代码库的上下文——文件结构、依赖关系、代码风格,一目了然。

即时行动

不只是建议——它直接动手修改文件、运行测试、执行部署,说干就干。

🔌

无限扩展

通过 MCP 协议连接 GitHub、数据库、Slack 等外部服务,打通所有工具链。

核心架构:谁是 Claude Code 的"大脑"?

Claude Code 就像一个公司——有管理层(主智能体)做决策,有执行层(工具)干实事,还有顾问(子智能体)提供专业意见。

交互层 — 你看到的部分

💬
终端对话界面
斜杠命令 (/)

智能层 — 思考和决策

🧠
主智能体 (Orchestrator)
👥
子智能体 (Subagents)
💾
记忆系统 (Memory)

工具层 — 连接外部世界

🔌
MCP 服务器
🪝
钩子 (Hooks)
📁
内置工具 (Tools)
点击任意组件,了解它在架构中的作用

消息的旅程:从你的键盘到代码修改

当你输入一条指令后,数据在各个组件之间流转。想象一个快递系统——你的指令是包裹,经过分拣、处理、配送,最终到达目的地(代码文件)。

⌨️
用户输入
🧠
主智能体
💾
记忆/工具
🪝
钩子/输出
点击"下一步"开始旅程

代码翻译:读懂第一个斜杠命令

这是 斜杠命令 的源码——一个优化分析命令。左边是原始代码,右边是逐行中文解释:

CODE
---
description: Analyze code for performance
  issues and suggest optimizations
---

# Code Optimization

Review the provided code for the
following issues in order of priority:

1. Performance bottlenecks
2. Memory leaks
3. Algorithm improvements
4. Caching opportunities
5. Concurrency issues
中文翻译

这是 YAML 前置信息开头——告诉 Claude 这个命令的元数据

描述:分析代码性能问题,建议优化方案——这是命令的"身份证"

前置信息结束标记

命令标题:代码优化

指示 Claude 按优先级审查代码

第 1 优先:性能瓶颈(如 O(n^2) 嵌套循环)

第 2 优先:内存泄漏(未释放的资源)

第 3 优先:算法改进(更好的数据结构选择)

第 4 优先:缓存机会(避免重复计算)

第 5 优先:并发问题(竞态条件、线程安全)

📖
YAML 前置信息是什么?

YAML 前置信息是用 --- 包裹的元数据块。它不是给用户看的,而是给 Claude 看的"使用说明"。description 字段帮助 Claude 理解这个命令什么时候该被使用。

Claude Code 的文件结构

Claude Code 的配置文件就像一个工具箱——每个文件都是一件特定的工具,放在特定的位置。来看看这个"工具箱"长什么样:

.claude/ Claude Code 的配置大本营
commands/ 旧版斜杠命令(仍可使用)
skills/ 新版技能包(推荐)——命令 + 脚本 + 模板
agents/ 子智能体定义——专家角色的"简历"
settings.json 项目级设置——权限、钩子配置
CLAUDE.md 项目记忆文件——Claude 的"项目手册"
.mcp.json MCP 服务器配置——连接外部服务的"通讯录"

检验你的理解

当你在 Claude Code 中输入一条指令时,谁负责理解你的意图并制定执行计划?

如果你想创建一个新的斜杠命令,应该把文件放在哪里?

你希望 Claude Code 每次写完文件后自动格式化代码。应该使用哪个功能?

02

斜杠命令与技能系统

用 /optimize、/pr 等快捷指令,让 Claude 执行复杂工作流

斜杠命令:你的快捷工作流

想象快捷键——按 Ctrl+S 保存文件,你不用点菜单、选选项。斜杠命令也一样:输入 /optimize,Claude 立刻执行完整的代码优化流程。

/optimize 分析代码性能瓶颈,找出 O(n^2) 循环、内存泄漏等问题
/pr 准备 PR——自动检查代码规范、运行测试、生成提交信息
/commit 智能生成 git 提交信息,自动读取代码差异作为上下文
/clear 清空对话历史,重新开始(就像擦掉白板重新写)
/compact 压缩对话上下文——当对话太长时,Claude 会"总结"之前的内容
/model 切换 AI 模型——Sonnet(快)、Opus(强)、Haiku(便宜)
💡
命令分类

Claude Code 有 60+ 个内置命令。输入 / 看全部列表,输入 /op 就会过滤出 optimize。就像手机通讯录的搜索——输入首字母就能找到联系人。

技能(Skills):命令的升级版

命令是单个文件,技能是整个文件夹。想象从"只带一把锤子"升级到"带了一个工具箱"——技能包含命令定义、脚本、模板和参考资料。

1
SKILL.md — 命令定义

定义命令名称、描述和执行指令——这是技能的"大脑"

2
scripts/ — 自动化脚本

Python/Shell 脚本做数据分析——比如代码复杂度计算

3
templates/ — 输出模板

标准化的输出格式——比如代码审查报告模板

4
references/ — 参考知识库

代码坏味道清单、重构模式目录——给 Claude 提供专业知识

对话还原:当你输入 /commit 时发生了什么?

看看各组件之间是怎么"对话"的。就像一个项目群里,不同角色各司其职:

代码翻译:技能定义文件长什么样?

这是创建技能的 YAML 模板。左边是真实代码,右边是逐行解释:

CODE
---
name: my-command
description: What this command
  does. Use when [trigger].
allowed-tools: Bash(npm *),
  Read, Grep
---

# My Command

## Context
- Current branch: !`git branch
    --show-current`
- Related files: @package.json

## Instructions
1. First step
2. With argument: $ARGUMENTS
中文翻译

YAML 前置信息开始标记

命令名称——用户输入 /my-command 就能触发

描述——帮助 Claude 理解"什么时候该用这个命令"

允许的工具列表——限制命令只能用 npm、读文件和搜索

YAML 前置信息结束标记

命令标题——Markdown 格式的指令正文

上下文区域——提供背景信息

动态执行:!` 反引号内的命令会被实时执行,结果插入此处

文件引用:@ 符号会自动读取文件内容并嵌入

指令步骤——Claude 会按顺序执行

$ARGUMENTS 会被替换为用户输入的参数

动手创建:5 分钟做一个自己的技能

1
创建目录结构

mkdir -p .claude/skills/my-optimizer — 在项目的 .claude/skills 下新建技能文件夹

2
编写 SKILL.md

创建 .claude/skills/my-optimizer/SKILL.md,写入 YAML 前置信息和指令正文

3
在 Claude Code 中调用

重启 Claude Code 或重新加载,然后输入 /my-optimizer 即可使用

检验你的理解

在 SKILL.md 中,如何让 Claude 自动获取当前 git 分支名?

技能和旧版命令放在不同的目录。如果你想创建一个新技能,推荐的位置是?

你的技能需要运行 npm test 但不应该执行 rm 命令。如何在 SKILL.md 中限制工具权限?

03

记忆系统

让 Claude "记住"项目规范和你的偏好——从每次对话都"失忆"到"过目不忘"

没有记忆的 AI 就像金鱼

想象每次和新同事聊天,他都要重新问:"项目用什么框架?代码风格是什么?数据库在哪?"——这就是没有记忆的 Claude。每次新对话,它都是一张白纸。

CLAUDE.md 解决了这个问题。它是一份写在项目根目录的文件,Claude 每次启动都会读取——相当于给 AI 发了一份"项目手册"。

📋

项目级记忆

放在项目根目录的 ./CLAUDE.md——所有团队成员共享。定义代码规范、架构决策。

👤

个人记忆

放在 ~/.claude/CLAUDE.md——只属于你。记录个人偏好、常用命令。

📁

目录级记忆

放在子目录的 CLAUDE.md——比如 src/api/CLAUDE.md 定义 API 模块的规范。

📝

自动记忆

Claude 可以自动保存你提到的重要信息——用 /memory 命令管理。

记忆加载流程

当你启动 Claude Code 时,记忆系统像一个图书馆管理员——按照特定顺序把"书"(记忆文件)递给 Claude:

👤
个人记忆
📋
项目记忆
📁
目录记忆
🧠
Claude 上下文
点击"下一步"看记忆如何加载

代码翻译:一个真实的项目记忆文件

这是从 claude-howto 仓库中提取的项目级 CLAUDE.md 示例:

CODE
# Project Conventions

## Tech Stack
- Frontend: Next.js 14 + React
- Backend: NestJS 11 + Prisma
- Database: PostgreSQL

## API Rules
- All routes use /api/v1 prefix
- JWT auth required on /api/v1/*
- Response format: { data, error }

## Code Style
- Use TypeScript strict mode
- No any types allowed
- Test coverage > 80%
中文翻译

项目约定——告诉 Claude 项目的基本规则

技术栈部分——让 Claude 知道用什么框架

前端:Next.js 14 + React 框架

后端:NestJS 11 + Prisma ORM

数据库:PostgreSQL 关系型数据库

API 规则——让 Claude 生成符合规范的代码

所有路由使用 /api/v1 前缀

JWT 认证——访问 API 需要身份验证令牌

统一响应格式——包含 data 和 error 字段

代码风格——强制类型安全

使用 TypeScript 严格模式

禁止使用 any 类型——所有变量必须有明确类型

测试覆盖率必须超过 80%

📖
记忆的优先级

当项目记忆和个人记忆冲突时,项目记忆优先。就像公司制度(项目级)优先于个人习惯(个人级)。这确保团队协作时所有人"看到"相同的规则。

互动练习:匹配记忆层级

把左边的记忆文件拖到右边正确的描述区域:

./CLAUDE.md
~/.claude/CLAUDE.md
src/api/CLAUDE.md

项目级——所有团队成员共享,包含代码规范和架构决策

拖到这里

个人级——只影响你自己,记录个人偏好和常用命令

拖到这里

目录级——只在特定子目录生效,定义模块级规范

拖到这里

记忆管理命令速查

/memory 打开 CLAUDE.md 编辑器,手动添加或修改记忆内容
/init 初始化 CLAUDE.md——Claude 会分析项目自动生成初始版本
/compact [指令] 压缩对话上下文——当对话太长时,Claude 会精简之前的内容,可以指定保留重点
⚠️
上下文窗口是有限的

Claude 的"短期记忆"有上限(约 200K token)。当对话超过上限,老的内容会被"遗忘"。用 /compact 可以主动压缩,保留关键信息。

检验你的理解

你刚确定了一个重要的架构决策(比如"所有 API 必须返回统一格式")。应该写在哪里?

你和一个新项目已经聊了 2 小时,对话变得很长,Claude 开始"忘记"早期的内容。最佳做法是?

你刚接手一个新项目,想让 Claude 快速"了解"项目。最高效的做法是?

04

子智能体与 MCP

从"一个人干所有事"到"组建专家团队"——委派与连接的艺术

子智能体:Claude 的"专家团队"

想象你是一个创业公司的 CEO——你不会自己写代码、自己测试、自己写文档。你会委派给专业的人。子智能体就是 Claude 的"员工"。

🔍
代码审查员 (code-reviewer)

权限:只读。专注代码质量、安全漏洞和性能问题——像质检员只管检查,不动产品。

🧪
测试工程师 (test-engineer)

权限:读写 + 执行。编写和运行测试,提高代码覆盖率——能读代码也能写测试。

🔒
安全审查员 (secure-reviewer)

权限:只读。扫描 SQL 注入、XSS、认证漏洞——专门抓"坏人"。

📝
文档编写者 (documentation-writer)

权限:读写。生成 API 文档、README 和代码注释——把技术翻译成人类语言。

代码翻译:定义一个代码审查智能体

这是 Markdown 格式的子智能体定义文件。放在 .claude/agents/ 目录下:

CODE
---
name: code-reviewer
description: Expert code review
  specialist. Use PROACTIVELY
  after writing or modifying code.
tools: Read, Grep, Glob, Bash
---

# Code Reviewer Agent

You are a senior code reviewer
ensuring high standards.

## Review Priorities
1. Security Issues
2. Performance Problems
3. Code Quality
4. Test Coverage
5. Design Patterns
中文翻译

YAML 前置信息开始

智能体名称——主智能体通过这个名字调用它

描述:专家级代码审查员——关键信息是"PROACTIVELY",意味着 Claude 会主动调用它

工具权限:只读(Read)、搜索(Grep/Glob)、执行命令(Bash)——注意没有 Write,所以它只能审查不能修改代码

YAML 前置信息结束

角色定义:告诉智能体它是"资深代码审查员"

审查优先级——按重要程度排序

第 1 优先:安全问题(认证、授权、数据泄露)

第 2 优先:性能问题(O(n^2) 操作、内存泄漏)

第 3 优先:代码质量(可读性、命名规范)

第 4 优先:测试覆盖率(缺少测试、边界情况)

第 5 优先:设计模式(SOLID 原则、架构合理性)

MCP:让 Claude 连接全世界

子智能体是 Claude 的"内部团队",而 MCP 是 Claude 连接"外部世界"的桥梁。想象 MCP 是一个万能适配器——插上不同的"插头"(MCP 服务器),Claude 就能访问不同的服务。

Claude Code

🧠
Claude 智能体

MCP 服务器(中间层)

🐙
GitHub
🗄️
Database
📁
Filesystem
点击任意组件了解 MCP 架构

代码翻译:MCP 配置文件

这是连接 GitHub 的 MCP 配置。放在项目根目录的 .mcp.json 中:

CODE
{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": [
        "@modelcontextprotocol
         /server-github"
      ],
      "env": {
        "GITHUB_TOKEN":
          "${GITHUB_TOKEN}"
      }
    }
  }
}
中文翻译

JSON 配置的开始

mcpServers:定义所有 MCP 服务器

服务器名称:github——之后用 /mcp__github__* 调用

启动命令:用 npx 运行 npm 包

参数:指定要安装的 MCP 服务器包名

@modelcontextprotocol/server-github——官方 GitHub MCP 服务器

环境变量配置区域

GITHUB_TOKEN:GitHub API 访问令牌——从系统环境变量读取,不硬编码密码

github 服务器配置结束

mcpServers 配置结束

整个配置文件结束

⚠️
安全提醒

永远不要在配置文件中硬编码 API Token!用 ${VARIABLE_NAME} 引用环境变量。Token 泄露就像把家门钥匙贴在门上。

对话还原:主智能体如何委派任务?

当你让 Claude "审查一下代码",主智能体不是自己动手——它像一个项目经理,把任务分配给专业的人:

检验你的理解

代码审查员(code-reviewer)子智能体的工具权限中,故意没有包含哪个工具?为什么?

你想让 Claude 能访问 GitHub API 来管理 PR 和 Issue。配置应该放在哪里?

当你说"帮我审查代码"时,谁决定把任务分配给代码审查员和安全审查员?

05

钩子、插件与高级工作流

自动化工作流、组合能力、构建完整的 AI 工程师团队

钩子(Hooks):Claude 的"条件反射"

想象你每次出门都会自动检查钥匙、手机、钱包——不需要刻意记住,已经成为习惯。钩子就是 Claude 的"条件反射"——在特定事件发生时自动触发预设动作。

📝

PreToolUse

工具执行前触发。比如在 Claude 写文件之前验证代码风格——不合格就阻止写入。

PostToolUse

工具执行后触发。比如 Claude 写完文件后自动运行 prettier 格式化——写完就美。

🔔

Notification

通知事件触发。比如任务完成后发 Slack 消息——不用一直盯着终端等结果。

🚀

SessionStart

会话开始时触发。比如自动检查项目状态、加载环境变量——开局就有上下文。

代码翻译:自动格式化钩子

这是一个真实的 PostToolUse:Write 钩子——Claude 每次写文件后自动执行,根据文件类型选择格式化工具:

CODE
#!/bin/bash
# Auto-format after writing
# Hook: PostToolUse:Write

INPUT=$(cat)
FILE_PATH=$(echo "$INPUT" |
  sed -n 's/.*"file_path".*"
    \([^"]*\)".*/\1/p')

case "$FILE_PATH" in
  *.ts|*.tsx)
    prettier --write "$FILE_PATH"
    ;;
  *.py)
    black "$FILE_PATH"
    ;;
esac
中文翻译

Shebang——告诉系统用 bash 执行这个脚本

注释:自动格式化钩子,在 Write 操作后触发

从标准输入读取 JSON 数据(Claude 传递的钩子信息)

用 sed 从 JSON 中提取 file_path 字段——知道 Claude 刚写了哪个文件

根据文件扩展名选择不同的格式化工具

TypeScript/TSX 文件 → 用 prettier 格式化

执行 prettier 格式化,--write 参数表示直接修改原文件

case 分支结束

Python 文件 → 用 black 格式化

执行 black 格式化 Python 代码

case 语句结束——整个钩子脚本执行完毕

如何配置钩子?

钩子配置写在 JSON 格式的 settings 文件中。以下是一个完整的钩子配置示例:

CODE
{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Write",
      "hooks": [{
        "type": "command",
        "command":
          "bash hooks/format.sh",
        "timeout": 30
      }]
    }]
  }
}
中文翻译

配置文件开始

hooks 配置区域

监听 PostToolUse 事件——工具使用后触发

matcher: "Write"——只在 Write(写文件)操作时触发,不是所有工具

具体的钩子定义

类型:command——执行 shell 命令

要执行的命令——运行格式化脚本

超时时间 30 秒——超过就放弃,不阻塞 Claude

钩子定义结束

PostToolUse 监听结束

hooks 配置结束

插件:把所有能力打包

如果说斜杠命令是"一把锤子",技能是"一个工具箱",子智能体是"一个工人"——那插件就是一整个"施工队"。

pr-review/(PR 审查插件) 完整的 PR 审查工作流——一键安装
commands/ 3 个斜杠命令:/review-pr, /check-security, /check-tests
agents/ 3 个子智能体:安全审查员、测试检查员、性能分析师
hooks/ 1 个钩子:审查前自动验证
mcp/ GitHub 集成配置——直接读取 PR 数据
plugin.json 插件清单——描述插件的元数据和依赖
1
安装插件

/plugin install pr-review —— 一条命令搞定,不用手动复制文件

2
使用命令

/review-pr —— 自动调用安全审查员、测试检查员和性能分析师

3
获得报告

综合所有专家的意见,生成完整的 PR 审查报告——安全、性能、测试全覆盖

完整的自动化工作流

把所有能力组合起来,一个完整的自动化代码审查流程长这样:

⌨️
用户
🪝
钩子验证
👥
子智能体
🔌
MCP/GitHub
📋
技能模板
📊
审查报告
点击"下一步"看完整工作流

更多高级特性

🎯

Planning Mode

只分析不执行——让 Claude 先出方案再动手。用 /plan--permission-mode plan 进入。

Checkpoints

自动保存对话快照——出错了随时"时光倒流"。按 Esc+Esc 或 /rewind 回退。

🤖

Headless Mode

无交互模式——适合 CI/CD。用 claude -p "指令" 在脚本中自动执行。

🔄

Loop 模式

定时重复执行——用 /loop 5m /check-deploy 每 5 分钟检查部署状态。

💡
学习路径总结

从 Module 1 到 Module 5,你已经掌握了 Claude Code 的完整能力图谱:斜杠命令(快捷操作)→ 技能(工具箱)→ 记忆(项目手册)→ 子智能体(专家团队)→ MCP(外部连接)→ 钩子(条件反射)→ 插件(施工队)。现在你可以组装属于自己的 AI 工程师团队了!

找 Bug 挑战

下面这段钩子配置有一个安全问题。点击你认为有 Bug 的那一行:

找出安全漏洞

1 {
2   "mcpServers": {
3     "github": {
4       "command": "npx",
5       "args": ["@modelcontextprotocol/server-github"],
6       "env": { "GITHUB_TOKEN": "ghp_xxxxxxxxxxxx" }
7     }
8   }
9 }

最终测验

你希望 Claude 每次写完 TypeScript 文件后自动运行 prettier。应该用哪个钩子事件?

想想哪种形式是'终极打包'——包含了所有其他组件。">

你想要一个完整的 PR 审查工作流——包含安全扫描、测试检查和性能分析。最高效的方式是?

你想在 GitHub Actions 中自动让 Claude 检查 PR 代码质量。应该用哪种模式?