初识 Claude Code
从安装到第一次对话——理解 AI 编程助手的完整架构
Claude Code 是什么?
想象你有一个超级编程搭档:它读过你整个项目,能直接读写文件、运行命令、搜索代码——而且永远不会忘记你说过的话。这就是 Claude Code。
Claude Code 不是聊天机器人——它是能动手的 AI 工程师。它能读写文件、执行终端命令、搜索代码库,甚至能调用外部 API。它住在你的终端里,理解你的整个项目。
终端原生
直接在你最熟悉的终端环境中运行,无需切换窗口,命令行就是你的 IDE。
项目感知
读取整个代码库的上下文——文件结构、依赖关系、代码风格,一目了然。
即时行动
不只是建议——它直接动手修改文件、运行测试、执行部署,说干就干。
无限扩展
通过 MCP 协议连接 GitHub、数据库、Slack 等外部服务,打通所有工具链。
核心架构:谁是 Claude Code 的"大脑"?
Claude 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 前置信息是用 --- 包裹的元数据块。它不是给用户看的,而是给 Claude 看的"使用说明"。description 字段帮助 Claude 理解这个命令什么时候该被使用。
Claude Code 的文件结构
Claude Code 的配置文件就像一个工具箱——每个文件都是一件特定的工具,放在特定的位置。来看看这个"工具箱"长什么样:
检验你的理解
当你在 Claude Code 中输入一条指令时,谁负责理解你的意图并制定执行计划?
如果你想创建一个新的斜杠命令,应该把文件放在哪里?
你希望 Claude Code 每次写完文件后自动格式化代码。应该使用哪个功能?
斜杠命令与技能系统
用 /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):命令的升级版
命令是单个文件,技能是整个文件夹。想象从"只带一把锤子"升级到"带了一个工具箱"——技能包含命令定义、脚本、模板和参考资料。
定义命令名称、描述和执行指令——这是技能的"大脑"
Python/Shell 脚本做数据分析——比如代码复杂度计算
标准化的输出格式——比如代码审查报告模板
代码坏味道清单、重构模式目录——给 Claude 提供专业知识
对话还原:当你输入 /commit 时发生了什么?
看看各组件之间是怎么"对话"的。就像一个项目群里,不同角色各司其职:
代码翻译:技能定义文件长什么样?
这是创建技能的 YAML 模板。左边是真实代码,右边是逐行解释:
---
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 分钟做一个自己的技能
mkdir -p .claude/skills/my-optimizer — 在项目的 .claude/skills 下新建技能文件夹
创建 .claude/skills/my-optimizer/SKILL.md,写入 YAML 前置信息和指令正文
重启 Claude Code 或重新加载,然后输入 /my-optimizer 即可使用
检验你的理解
在 SKILL.md 中,如何让 Claude 自动获取当前 git 分支名?
技能和旧版命令放在不同的目录。如果你想创建一个新技能,推荐的位置是?
你的技能需要运行 npm test 但不应该执行 rm 命令。如何在 SKILL.md 中限制工具权限?
记忆系统
让 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-howto 仓库中提取的项目级 CLAUDE.md 示例:
# 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%
当项目记忆和个人记忆冲突时,项目记忆优先。就像公司制度(项目级)优先于个人习惯(个人级)。这确保团队协作时所有人"看到"相同的规则。
互动练习:匹配记忆层级
把左边的记忆文件拖到右边正确的描述区域:
项目级——所有团队成员共享,包含代码规范和架构决策
个人级——只影响你自己,记录个人偏好和常用命令
目录级——只在特定子目录生效,定义模块级规范
记忆管理命令速查
/memory
打开 CLAUDE.md 编辑器,手动添加或修改记忆内容
/init
初始化 CLAUDE.md——Claude 会分析项目自动生成初始版本
/compact [指令]
压缩对话上下文——当对话太长时,Claude 会精简之前的内容,可以指定保留重点
Claude 的"短期记忆"有上限(约 200K token)。当对话超过上限,老的内容会被"遗忘"。用 /compact 可以主动压缩,保留关键信息。
检验你的理解
你刚确定了一个重要的架构决策(比如"所有 API 必须返回统一格式")。应该写在哪里?
你和一个新项目已经聊了 2 小时,对话变得很长,Claude 开始"忘记"早期的内容。最佳做法是?
你刚接手一个新项目,想让 Claude 快速"了解"项目。最高效的做法是?
子智能体与 MCP
从"一个人干所有事"到"组建专家团队"——委派与连接的艺术
子智能体:Claude 的"专家团队"
想象你是一个创业公司的 CEO——你不会自己写代码、自己测试、自己写文档。你会委派给专业的人。子智能体就是 Claude 的"员工"。
权限:只读。专注代码质量、安全漏洞和性能问题——像质检员只管检查,不动产品。
权限:读写 + 执行。编写和运行测试,提高代码覆盖率——能读代码也能写测试。
权限:只读。扫描 SQL 注入、XSS、认证漏洞——专门抓"坏人"。
权限:读写。生成 API 文档、README 和代码注释——把技术翻译成人类语言。
代码翻译:定义一个代码审查智能体
这是 Markdown 格式的子智能体定义文件。放在 .claude/agents/ 目录下:
---
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
MCP 服务器(中间层)
代码翻译:MCP 配置文件
这是连接 GitHub 的 MCP 配置。放在项目根目录的 .mcp.json 中:
{
"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。配置应该放在哪里?
当你说"帮我审查代码"时,谁决定把任务分配给代码审查员和安全审查员?
钩子、插件与高级工作流
自动化工作流、组合能力、构建完整的 AI 工程师团队
钩子(Hooks):Claude 的"条件反射"
想象你每次出门都会自动检查钥匙、手机、钱包——不需要刻意记住,已经成为习惯。钩子就是 Claude 的"条件反射"——在特定事件发生时自动触发预设动作。
PreToolUse
工具执行前触发。比如在 Claude 写文件之前验证代码风格——不合格就阻止写入。
PostToolUse
工具执行后触发。比如 Claude 写完文件后自动运行 prettier 格式化——写完就美。
Notification
通知事件触发。比如任务完成后发 Slack 消息——不用一直盯着终端等结果。
SessionStart
会话开始时触发。比如自动检查项目状态、加载环境变量——开局就有上下文。
代码翻译:自动格式化钩子
这是一个真实的 PostToolUse:Write 钩子——Claude 每次写文件后自动执行,根据文件类型选择格式化工具:
#!/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 文件中。以下是一个完整的钩子配置示例:
{
"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 配置结束
插件:把所有能力打包
如果说斜杠命令是"一把锤子",技能是"一个工具箱",子智能体是"一个工人"——那插件就是一整个"施工队"。
/plugin install pr-review —— 一条命令搞定,不用手动复制文件
/review-pr —— 自动调用安全审查员、测试检查员和性能分析师
综合所有专家的意见,生成完整的 PR 审查报告——安全、性能、测试全覆盖
完整的自动化工作流
把所有能力组合起来,一个完整的自动化代码审查流程长这样:
更多高级特性
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 的那一行:
找出安全漏洞
{
"mcpServers": {
"github": {
"command": "npx",
"args": ["@modelcontextprotocol/server-github"],
"env": { "GITHUB_TOKEN": "ghp_xxxxxxxxxxxx" }
}
}
}