Claude Code Agent 使用与扩展手册

> 一份写给「正在用 Claude Code 的你」的桌面手册。 > 上半部分帮你理解它怎么运转（这样你能预测它的行为）；下半部分教你怎么用好、怎么自己扩展（这样你能把它调成自己的工具）。

快速导读：它到底是个什么东西

Claude Code 是一个会动手的编程助手，运行在终端、桌面应用或 IDE（如 VS Code）里。

类比：它不是一个「只会回话的聊天机器人」，而是一个「坐在你电脑前、能读文件、能改代码、能跑命令、能上网查资料的实习生」。

• 会动手：它能读你的文件、改你的代码、执行命令、搜索网络。
• 有记忆边界：它在一个会话里记得你们聊了什么；但会话一关，默认什么都不留——除非它主动写盘。
• 可被调教：你可以通过 CLAUDE.md、设置、技能、钩子等，把它改成你的专属工具。

用一句话记住它：会话内记得，会话外默认忘；写了盘才持久，说了才遵守。

第一部分 · 工作机制

1.1 会话与上下文窗口

你每打开一个会话（session），就有一个上下文窗口——一个有限容量的「工作记忆」。

• 你的每句话、它的每句回答、它读过的每个文件、每次工具调用的结果，都会进入这个窗口。
• 窗口是有限的。聊得长了，早期的内容会被压缩（compact）：把细节总结成摘要，丢掉枝节。

> 类比：像一块固定大小的白板。写满了，就得把最早写的内容擦掉、只留一句摘要，腾出地方写新的。

实际影响： - 一个会话里，它「记得」最近聊的、和刚看过的文件，但很早的细节可能已经淡出。 - 所以别指望它在一个超长会话里仍精确记得第 1 条消息的每个字。

1.2 工具调用：它不只是聊天

它回答你之前，常常会先「动手」——通过一系列工具（tools）：

关键：它做「会改动系统」的动作（改文件、跑命令、联网）时，是否先问你，取决于权限模式（见 1.6）。

1.3 记忆系统：什么会留下、什么会消失

这是最容易误解的地方。分清三层：

最重要的结论： - 它不会「每问你一句话就永久记住」。 - 跨会话能留下来的，只有两类：你写的指令（CLAUDE.md、settings），和它主动写盘的东西（改过的文件、git 提交、写下的 memory 文件）。 - 纯粹的问答，聊完就散，不留痕。

Memory 是什么：它判断某条信息「值得记」时，会往 memory 目录写一个小文件。每个文件一条事实，带 frontmatter 元数据；MEMORY.md 是指引索引。类型分四种： - user：你这个人（角色、偏好） - feedback：你给它的工作方式指导（含 why 和 how to apply） - project：项目状态、目标、约束 - reference：外部资源指针（URL、看板、工单）

> 类比：CLAUDE.md 是你给它的员工手册（你写、它遵守）；Memory 是它自己的笔记本（它判断该记什么才记）。

1.4 工作区与隔离

• 每个工作目录（working directory）是独立的战场。
• Memory 按项目路径分目录隔离：在 A 项目记的东西，不会串到 B 项目。
• CLAUDE.md 分层：全局（~/.claude/CLAUDE.md）所有项目共享；项目级（./CLAUDE.md）各自独立。
• 换句话说：你在一个工作区里做的事，默认不会污染另一个工作区。

1.5 上下文压缩（compact）与延续性

上下文满了会自动压缩；你也可以手动 /compact。

压缩会丢细节，所以重要任务要靠「文档」保命： - 让它把进度、决策、踩坑写进 docs/、README。 - 会话被压缩后，它能靠这些文档 + git 历史「找回」上下文，而不是凭残缺记忆硬猜。

这就是「文档是延续性保障」的含义。

1.6 权限模式：动手前会不会问你

它做「改动型」动作前是否要你确认，由权限模式决定：

用 Shift+Tab 循环切换。

第二部分 · 10 个必记要点

1. 会话内记得，会话外默认忘——除非它主动写盘。
2. 只有「写盘」才持久：改文件、写文档、git 提交、记 Memory 才算留下痕迹；纯问答不留痕。
3. 上下文有限，满了会压缩、丢细节。
4. CLAUDE.md 是最高优先级的「你写的指令」，每次会话都读。
5. 它会动手（读、写、跑命令、联网），不只是聊天。
6. 权限模式决定它动手前问不问你，Shift+Tab 可切换。
7. 工作区之间记忆隔离，全局 CLAUDE.md 共享。
8. 临时任务：你说「插入/临时」，它就不污染主线（不写文档、不提交、不记 Memory）。
9. 交付前它会自测（如果你要求了）；要它自测，直接说。
10. 文档是延续性保障：重要任务让它落盘，别只靠聊天记录。

第三部分 · 怎么用好

提问方式 - 说清目标，而不是只给结论。「帮我修这个 bug」不如「这个接口返回 500，帮我定位原因并修好」。 - 给上下文：相关文件、报错信息、你已试过什么。 - 复杂任务先让它计划（进入 plan 模式），对齐方案再动手。

让它记住 / 不要记住 - 要它长期记住：「这个以后默认这样处理」→ 让它写进全局/项目 CLAUDE.md。 - 要它别记：「这个别写进文档 / 别记 Memory」→ 一句话即可。

临时任务不污染主线 - 插入临时问题时，开头加「插入的 / 临时的」，它会自动：不写主线文档、不提交 git、不记 Memory、产物隔离或清理、不改主线决策。

交付与验证 - 要求它「交付前自测」：跑测试、验证关键路径、查边界情况。 - 让它把「做了什么、怎么验证的」讲清楚，别只给一句「完成了」。

长任务 / 多步骤 - 用 plan 模式先把步骤定下来。 - 让它维护进度文档，跨会话也能接着干。

验证它说的 - 关键结论让它标出处（文件路径、commit、数据来源），别空口断言。 - 拿不准的技术细节，它会查证，而不是瞎编——你也可以要求它「先查再答」。

第四部分 · 怎么自己扩展

> 本部分教你「改造」Claude Code。先看一张地图，再按需深入。配置细节以官方文档 code.claude.com/docs 为准。Windows 下 ~/.claude 即 %USERPROFILE%\.claude。

4.0 先看地图：扩展点有哪些、什么时候用

Claude Code 有一堆「扩展点」，乍看容易懵。其实它们只干三类事：立规矩、教能力、自动化。

学习建议：80% 的情况你只需要 CLAUDE.md + 一两个 Skill/命令；想自动化再加 Hooks；MCP / Subagent / Plugin / Workflow 按需再学，不用一次学完。

下面每节统一按「是什么 → 解决什么 → 完整例子 → 放哪 → 关键提醒」展开。

4.1 CLAUDE.md：先从这里开始

是什么：一个纯文本文件，写你想让它长期遵守的指令。 类比：你给实习生写的「入职须知」。

解决什么：跨会话记住你的规矩——编码规范、构建命令、项目约定、个人偏好。它每次会话都会自动读。

完整例子（项目根目录 ./CLAUDE.md）：

# 构建
- 装依赖: npm install
- 测试: npm test
- 打包: npm run build

# 规范
- 2 空格缩进，不用 tab
- 组件放 src/components/，工具函数放 src/utils/
- 提交前必须跑 npm test

# 偏好
- 注释和文档用中文，代码用英文
- 先做 MVP，别过度设计

这段的效果：以后在这个项目里，它会自动知道怎么构建、按什么规范写、遵循你的偏好——不用你每次重复。

放哪：

关键提醒： - 写得具体、可验证（「提交前跑 npm test」）比「代码要整洁」有用得多。 - 它是「上下文」不是「硬约束」——要强制执行，得靠 Hooks 或 permissions（见 4.6）。 - /init 自动生成；/context 验证是否加载。

4.2 settings.json：机器级设置

是什么：JSON 配置文件，管「机器层面」的设置（模型、权限、环境变量、hooks）。 类比：软件的「设置面板」，只是用文件写。

解决什么：改模型、设权限（允许/禁止哪些命令）、注入环境变量。

完整例子（项目 .claude/settings.json）：

{
  "model": "sonnet",
  "permissions": {
    "allow": ["Bash(npm run *)", "Bash(npm test)"],
    "deny": ["Read(./.env)", "Bash(curl *)", "Bash(rm -rf *)"]
  }
}

这段的效果：允许它直接跑 npm run xxx 和 npm test（不打断你）；禁止它读 .env、禁止 curl 和 rm -rf。

放哪：用户级 ~/.claude/settings.json；项目 .claude/settings.json；本地 .claude/settings.local.json（自动 gitignore）。

关键提醒： - permissions 语法是 工具(参数)，* 是通配符。 - model 只在启动时读一次，中途改要 /model 或重启。 - 加 $schema 键能获得校验提示；设置文件热重载，但一个非法键会导致整个文件被拒。

4.3 Memory：自动记忆

是什么：它判断「值得记」时，主动写的小笔记文件。 类比：它自己的笔记本（区别于 CLAUDE.md 是你写的员工手册）。

解决什么：让一些事实跨会话留存（你的偏好、项目状态、关键决策）。

它记成什么样（~/.claude/projects/<项目路径>/memory/ 下的一个文件）：

---
name: my-preference
description: 用户偏好中文注释
metadata:
  type: feedback
---

用户希望代码注释和文档用中文。

**Why:** 团队习惯，便于协作。
**How to apply:** 写代码时默认中文注释。

怎么用： - 想让它记：「记住：这个项目 API 都走 /api/v2」→ 它会写 memory 文件。 - 想让它忘：「别记这个」或「删掉关于 X 的那条记忆」。 - 开关：settings 里 autoMemoryEnabled，或用 /memory 命令。

关键提醒：CLAUDE.md 是你写的（权威、稳定）；Memory 是它写的（可能被它更新/删除）。立规矩用 CLAUDE.md，记事实交给它。

4.4 Skills：技能

是什么：把「一段流程 + 指令」打包成一个技能文件，按需加载。 类比：游戏里的「宏」或「快捷指令包」——喊一声就执行整套流程。

解决什么：把重复的流程（部署、发版、代码审查）做成可复用技能，不占常驻上下文，需要时才加载。

完整例子（做一个部署技能）：

目录结构：

.claude/skills/deploy/
└── SKILL.md

SKILL.md 内容：

---
name: deploy
description: 部署应用到生产环境
---

按下面步骤部署到生产：
1. 跑测试：npm test
2. 构建：npm run build
3. 用 rsync 推送到服务器并重启服务

怎么用：输入 /deploy，它就会按 SKILL.md 的步骤执行。

放哪：个人 ~/.claude/skills/<name>/SKILL.md；项目 .claude/skills/<name>/SKILL.md。

关键提醒： - description 决定它什么时候被自动调用（它读到你的需求，觉得匹配就会用）。 - 常用 frontmatter：allowed-tools（技能期间预批准的工具）、disable-model-invocation: true（只许手动 /名字 调用，不许它自己触发）。

4.5 Slash commands：自定义命令

是什么：一个 .md 文件 = 一个 /命令。 类比：给命令行加了个自定义命令。

解决什么：一个命令触发一段固定流程（比技能更轻量）。

完整例子（.claude/commands/release.md）：

请生成当前版本的发布说明：
1. 查看 git log 收集本次改动
2. 按「新增 / 修复 / 改进」分类
3. 输出 Markdown 格式的 CHANGELOG

→ 输入 /release 触发。

放哪：.claude/commands/（项目）或 ~/.claude/commands/（全局）。

与 Skill 的区别：命令更轻量（就是一段 prompt），技能更完整（可带脚本、参考文件、工具权限）。简单流程用命令，复杂流程用技能。

4.6 Hooks：生命周期钩子

是什么：在特定时点自动执行一段脚本/命令。 类比：像「IFTTT」——「当它要做 X 时，先跑我的脚本」。

解决什么：自动拦截危险操作、提交前自动跑测试、格式化提交信息。这是唯一能「强制执行」的地方（CLAUDE.md 只是建议）。

完整例子（拦截 rm -rf，防止误删）：

第 1 步，写脚本 .claude/hooks/block-rm.sh：

#!/bin/bash
# 收到要执行的命令，包含 rm -rf 就阻止
if echo "$2" | grep -q "rm -rf"; then
  exit 2   # 退出码 2 = 阻止这个操作
fi
exit 0

第 2 步，在 .claude/settings.json 里注册：

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          { "type": "command", "command": ".claude/hooks/block-rm.sh" }
        ]
      }
    ]
  }
}

效果：每当它要执行 Bash 命令时，先跑 block-rm.sh；如果命令里有 rm -rf，脚本返回 2，就阻止这次执行。

常用事件：PreToolUse（工具调用前）、PostToolUse（调用后）、UserPromptSubmit（你发消息时）、Stop（它要停时）、SessionStart/SessionEnd。

关键提醒：退出码 0=放行，2=阻止，其它=非阻塞错误。

4.7 Subagents：子代理

是什么：用 .md 定义一个「有特定人设 + 工具权限」的专用小助手，主 agent 可以派活给它。 类比：你招了个专管代码审查的「专员」，主 agent 是「经理」，遇到审查的活就派给专员。

解决什么：让某类活用专门的「人设 + 工具集」，更聚焦、更省上下文。

完整例子（.claude/agents/code-reviewer.md）：

---
name: code-reviewer
description: 代码审查专家，写完代码后主动用来做审查
tools: Read, Grep, Glob, Bash
model: sonnet
---

你是资深代码审查者。审查最近改动，按优先级输出：
1. Critical：会导致 bug 或安全问题
2. Warnings：潜在问题
3. Suggestions：改进建议

怎么用： - 自动：它读到 description，会在合适时自己派活给这个子代理。 - 手动：「用 code-reviewer 子代理审查我的改动」。 - 提及：@code-reviewer (agent) 看下 auth 改动。

放哪：.claude/agents/（项目）或 ~/.claude/agents/（全局）。

关键提醒：name 和 description 必填；tools 限定它能用哪些工具（省略则继承全部）。

4.8 MCP：接外部系统

是什么：Model Context Protocol，接外部工具/数据源的标准接口。 类比：给 AI 装「转接头」，让它能连你的数据库、工单系统、浏览器。

解决什么：让 AI 直接读/操作你公司内部系统（数据库、Jira、监控、Notion 等）。

完整例子（项目根 .mcp.json，接一个本地文件系统服务器）：

{
  "mcpServers": {
    "filesystem": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "C:\\my-data"]
    }
  }
}

效果：装好这个 MCP 服务器后，它就能通过 MCP 工具读写 C:\my-data 目录。

放哪：local（默认，~/.claude.json）、project（.mcp.json，随 git 共享）、user。

关键提醒： - 需要一个「MCP server 程序」在背后跑（上例的 @modelcontextprotocol/server-filesystem 就是官方提供的一个）。 - 管理用 /mcp 命令，或命令行 claude mcp add ...。

4.9 Plugins：插件

是什么：把 skills / agents / hooks / MCP 打包成一个可分发的「包」。 类比：把散装工具打包成「插件」（像浏览器扩展或 VS Code 插件）。

解决什么：把一套扩展打包分享给团队，或从插件市场安装别人做好的。

目录结构：

my-plugin/
├── .claude-plugin/plugin.json   # 唯一放这里的文件
├── skills/hello/SKILL.md        # 技能
├── agents/                      # 子代理
└── hooks/hooks.json             # 钩子

最小 plugin.json：

{
  "name": "my-first-plugin",
  "description": "我的第一个插件",
  "version": "1.0.0"
}

安装：会话内 /plugin install <name>@<市场>；本地测试 claude --plugin-dir ./my-plugin。

关键提醒：只有 plugin.json 放 .claude-plugin/ 里；改插件后 /reload-plugins 生效。

4.10 Workflows：多代理编排（进阶）

是什么：用一个脚本编排多个子代理并行干活。 类比：给团队开会分工——几个 agent 并行扫描，最后汇总。

解决什么：大型审计、多维度评审这类要「铺开很多 agent 同时干」的活。

关键提醒：会消耗较多 token，只在明确要求多代理编排时才用；日常任务用不到。属于进阶玩法，这里不展开，需要时再单独问。

4.11 其它零碎扩展点

用到再查，知道有这些就行：

• .claude/rules/：把 CLAUDE.md 拆成按主题/按文件作用域的规则文件。
• statusline：自定义状态栏（进度、成本）。
• keybindings：~/.claude/keybindings.json，/keybindings 打开。
• 环境变量：大量 CLAUDE_* 变量控制行为（MAX_THINKING_TOKENS 等），可放 settings 的 env。
• /add-dir：会话级添加额外工作目录。
• 完整 CLI：claude --help 列出全部 flag。

第五部分 · 速查表

心智模型

常用命令

配置文件一览

第六部分 · 常见问题与踩坑

Q：改了 settings.json 没生效？ 多数设置热重载，但 model、outputStyle 要重启或 /clear。一个非法键会导致整个文件被拒——加 $schema 键获得校验。

Q：CLAUDE.md 写了但它没照做？ CLAUDE.md 是「上下文」而非「硬约束」。要强制执行，用 hooks 或 permissions（比如 deny: ["Bash(rm *)"]）。

Q：记 Memory 和写 CLAUDE.md 有什么区别？ CLAUDE.md 是你写的指令（权威、稳定）；Memory 是它判断该记才写的事实（可能被它更新/删除）。定规矩用 CLAUDE.md，记事实让它自己处理。

Q：会话被压缩后，重要上下文丢了怎么办？ 靠文档和 git 找回。重要任务让它在关键节点写进度文档。

Q：Windows 下 ~/.claude 在哪？ %USERPROFILE%\.claude，即 C:\Users\<你的用户名>\.claude。

Q：同一个项目两个人用，各自偏好会不会打架？ 项目级 CLAUDE.md、.claude/settings.json 随 git 共享；个人偏好放 ~/.claude/（全局）或 CLAUDE.local.md / settings.local.json（自动 gitignore）。

手册完 · 配置细节以官方文档 code.claude.com/docs 为准，标注版本差异处以对应文档页核对。