ClaudeCode 学习记录

ClaudeCode 学习记录

---

一、模式切换

按 Shift+Tab(官方文档是这么写的，但我的是alt+m) 键循环切换三种模式：

模式	说明
默认模式	Claude 在文件编辑和 shell 命令之前都会询问确认
Accept Edits	平常的代码修改自动执行，只有涉及 shell 命令时才需要手动批准
Plan Mode	不动手执行，只生成计划方案

---

二、特殊符号快捷操作

符号	名称	用法	示例
!	Shell 命令	输入 ! 后面接命令，直接执行对应的 shell 命令	!dir → 直接执行 dir 命令，显示当前目录下的文件
@	引用文件	输入 @ 后接路径，会列出该路径下的文件和文件夹供选择	已知路径 x1/x2/x3，输入 @x1 → 列出 x1 目录下的文件和文件夹
&	备注约束	在一段要求之后追加 & 加约束条件，作为补充说明	写了一大堆要求后输入 & 用英语回答

---

三、命令参考

会话与对话管理

命令	说明
/init	使用 CLAUDE.md 指南初始化项目。设置 CLAUDE_CODE_NEW_INIT=1 获得交互式流程
/clear [name]	启动新对话，之前的对话在 /resume 中保持可用。别名：/reset、/new
/resume [session]	按 ID 或名称恢复对话，或打开会话选择器。别名：/continue
/compact [instructions]	通过总结对话来释放上下文，可传递焦点说明
/recap	按需生成当前会话的单行摘要
/branch [name]	创建当前对话的分支，可用 /resume 返回。别名：/fork
/rewind	将对话和/或代码倒回到上一个点。别名：/checkpoint、/undo
/rename [name]	重命名当前会话，不传名称则自动生成
/export [filename]	将当前对话导出为纯文本
/btw <question>	提出快速附加问题，不添加到对话中

项目与环境

命令	说明
/add-dir <path>	为当前会话添加工作目录。.claude/ 配置不会从添加的目录中发现
/diff	交互式差异查看器，显示未提交更改和每轮差异
/context [all]	将当前上下文使用情况可视化为彩色网格，传递 all 展开详情
/doctor	诊断并验证 Claude Code 安装和设置。按 f 让 Claude 修复问题
/status	显示版本、模型、账户和连接性状态
/tasks	列出并管理后台任务。别名：/bashes

模型与权限

| 命令 | 说明 |
|-------------------|---------------------------------------|----------------------------------------------------------|
| /model [model] | 选择或更改 AI 模型，可调整工作量级别 |
| `/effort [level | auto]` | 设置工作量级别：low/medium/high/xhigh/max，auto 重置为默认 |
| /permissions | 管理工具权限的允许、询问和拒绝规则。别名：/allowed-tools |
| /sandbox | 切换沙箱模式，仅在支持的平台上可用 |
| `/fast [on | off]` | 切换快速模式 |
| /extra-usage | 配置额外使用量，达到速率限制时继续工作 |

记忆与配置

命令	说明
/memory	编辑 CLAUDE.md 内存文件，启用/禁用自动记忆，查看自动记忆条目
/config	打开设置界面（主题、模型、输出样式等）。别名：/settings
/skills	列出可用 skills。按 t 按 token 排序，按 Space 隐藏 skill
/hooks	查看工具事件的 hook 配置
/agents	管理 agent 配置（详见「十、Subagents 实操指南」）
/plugin	管理 Claude Code plugins
/mcp	管理 MCP server 连接和 OAuth 身份验证

成本与统计

命令	说明
/usage	显示会话成本、计划使用限制和活动统计。别名：/cost、/stats

PR 与代码审查

命令	说明
/review [PR]	在当前会话中本地审阅 pull request
/ultrareview [PR]	在云沙箱中运行多 agent 深度代码审查。Pro/Max 含 3 次免费
/autofix-pr [prompt]	监视当前分支 PR，CI 失败或审阅者评论时自动推送修复。需要 gh CLI
/security-review	分析待处理更改的安全漏洞（注入、认证问题、数据泄露等）

Skill 命令（高级功能模块）

| 命令 | 说明 |
|-----------------------------|---------------------------------------------------------|---------------------------------------------------------------------------------------|
| /batch <instruction> | 在整个代码库中并行编排大规模更改，分解为独立单元，在隔离 worktree 中生成后台 agent 并开 PR |
| /loop [interval] [prompt] | 重复运行提示。省略间隔自动调速，省略提示运行自主维护检查。别名：/proactive |
| /simplify [focus] | 审阅最近更改的文件，查找代码重用、质量和效率问题并修复 |
| /debug [description] | 为当前会话启用调试日志并排查问题 |
| `/claude-api [migrate | managed-agents-onboard]` | 加载 Claude API 参考资料。migrate 升级 API 代码到新模型，managed-agents-onboard 创建新 Managed Agent |
| /fewer-permission-prompts | 扫描历史记录，为常用只读操作添加允许列表，减少权限提示 |

规划与远程

命令	说明
/plan [description]	直接进入 Plan Mode，可传描述立即开始任务
/ultraplan <prompt>	在浏览器中审阅计划，然后远程执行或发送回终端
/schedule [description]	创建/更新/列出/运行 routines（在 Anthropic 云基础设施上执行）。别名：/routines

远程与网络

命令	说明
/remote-control	使会话可从 claude.ai 远程控制。别名：/rc
/teleport	将网络版 Claude Code 会话拉入终端。别名：/tp
/desktop	在 Claude Code Desktop 应用中继续会话（macOS/Windows）。别名：/app
/remote-env	配置默认远程环境（网络会话用）
/web-setup	用本地 gh CLI 凭证连接 GitHub 到网络版 Claude Code

外观与个性化

| 命令 | 说明 |
|------------------|-----------------------------|--------------------------------------------------------|
| /theme | 更改颜色主题，含 auto、色盲友好、自定义主题等 |
| `/color [color | default]` | 设置提示栏颜色（red/blue/green/yellow/purple/orange/pink/cyan） |
| /focus | 切换焦点视图，仅显示提示、工具摘要和最终响应 |
| /statusline | 配置状态行内容 |
| `/tui [default | fullscreen]` | 设置终端 UI 渲染器，fullscreen 启用无闪烁渲染器 |

其他

| 命令 | 说明 |
|-----------------------|---------------------------------------------------|---------|----------|
| /login | 登录 Anthropic 账户 |
| /logout | 登出 Anthropic 账户 |
| /help | 显示帮助和可用命令 |
| /exit | 退出 CLI。别名：/quit |
| /copy [N] | 复制第 N 个最新响应到剪贴板。有代码块时显示交互式选择器，按 w 写入文件 |
| /keybindings | 打开或创建快捷键配置文件 |
| /terminal-setup | 配置终端快捷键（Shift+Enter 等），仅在需要的终端中可见 |
| `/voice [hold | tap | off]` | 切换语音听写模式 |
| /chrome | 配置 Claude in Chrome 设置 |
| /ide | 管理 IDE 集成并显示状态 |
| /insights | 分析 Claude Code 会话（项目领域、交互模式、摩擦点） |
| /install-github-app | 为存储库设置 Claude GitHub Actions 应用 |
| /install-slack-app | 安装 Claude Slack 应用 |
| /mobile | 下载 Claude 移动应用二维码。别名：/ios、/android |
| /release-notes | 查看版本更新日志 |
| /team-onboarding | 从使用历史生成团队入职指南 |
| /powerup | 快速交互式课程发现 Claude Code 功能 |
| /radio | 打开 Claude FM lo-fi 电台 |
| /stickers | 订购 Claude Code 贴纸 |
| /passes | 分享一周免费 Claude Code |
| /upgrade | 打开升级页面 |
| /privacy-settings | 查看和更新隐私设置（Pro/Max 可用） |
| /heapdump | 导出 JavaScript 堆快照，诊断高内存使用 |
| /feedback [report] | 提交反馈。别名：/bug |
| /setup-bedrock | 配置 Amazon Bedrock（需 CLAUDE_CODE_USE_BEDROCK=1） |
| /setup-vertex | 配置 Google Vertex AI（需 CLAUDE_CODE_USE_VERTEX=1） |
| /reload-plugins | 重新加载所有活跃 plugins，无需重启 |

已移除的命令：

命令	说明
/pr-comments	v2.1.91 移除，改为直接问 Claude 查看 PR 评论
/vim	v2.1.92 移除，用 /config → 编辑器模式切换

---

四、核心架构概念

1. CLAUDE.md --- 持久上下文

详见「七、CLAUDE.md 深入」。

2. Skills --- 可重用工作流

添加可重用的知识和可调用的工作流。

3. MCP --- 外部服务连接

将 Claude 连接到外部服务和工具，类似调用外部接口。

4. Subagents --- 隔离上下文子代理

在隔离的上下文中运行自己的循环，处理完成后返回摘要给主 agent。

特点：

• 有独立的执行环境，不占用主 agent 的上下文

• 适合处理相对独立但又复杂麻烦的任务

• 处理完后将精简结果返回主 agent

• 解决大模型在复杂任务中因上下文过长导致的注意力分散、信息遗漏和性能下降问题

使用方式：

• 需要预先手动创建 Subagents

• 创建完成后，后续会话中符合触发条件的任务会自动调用对应的 Subagent，无需每次手动指定

• 自动触发的效果高度依赖创建时的配置质量，并非所有场景都能 100% 可靠触发

5. Agent Teams --- 多会话协作

协调多个独立会话，具有共享任务和点对点消息传递。

对比维度	Subagents	Agent Teams
本质	单会话内的任务委派，结果单向返回主对话	多个物理独立的会话并行运行
通信方式	单向汇报	共享任务列表 + 点对点消息传递
协作模式	传统单向汇报	真正的网状协作

6. Hooks --- 生命周期钩子

在生命周期事件上触发，可运行脚本、HTTP 请求、提示或 subagent。相当于钩子函数，100% 会触发。

7. Plugin --- 插件包

一个包含特定功能的压缩包 ，把 Skills + Agents + Commands + Hooks 打包在一起。核心价值：复用与分享。

---

五、组件加载机制与上下文成本

功能	何时加载	加载内容	上下文成本
CLAUDE.md	会话开始	整个文件内容	每个请求
Skills	会话开始 + 使用时	启动时加载描述，使用时加载完整内容	低（每个请求仅描述）*
MCP 服务器	会话开始	工具名称；完整 schema 按需加载	低，直到使用工具
Subagents	生成时	具有指定 skills 的新鲜上下文	与主会话隔离
Hooks	触发时	无（外部运行）	零，除非 hook 返回额外上下文

*** Skills 的上下文成本说明：仅在使用时才加载完整内容，日常请求只消耗描述部分的 token。

---

六、典型使用场景

组件	典型用途
CLAUDE.md	处理项目约定（编码规范、架构约定等）
Skills	处理工作流（可复用的标准操作流程）
MCP	连接到数据库（接入外部服务/工具）
Hooks	每次编辑后自动运行审查（代码检查、格式校验等）

---

七、CLAUDE.md 深入

1. 双记忆系统

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

记忆系统	说明
CLAUDE.md 文件	Markdown 文件，为 Claude 提供持久指令，每个会话开始时读取
Claude 自动记忆	Claude 主动识别出"值得长期保留的更正和偏好"，不是每一句对话都记

自动记忆记录的两类内容：

类型	说明	示例
更正	你纠正了 Claude 的做法	"不对，这里应该用 log.error，不要用 print"
偏好	你告诉它你希望始终遵循的编码方式	"以后所有数据库操作都用 LambdaWrapper 而不是 updateById"

2. 导入其他文件

CLAUDE.md 文件可使用 @path/to/import 语法导入其他文件。

规则：

• 导入的文件在启动时展开并加载到上下文中，与引用它们的 CLAUDE.md 一起

• 允许相对路径 和绝对路径

• 相对路径相对于包含导入的文件解析，而不是工作目录

• 导入的文件可以递归导入 其他文件，最大深度为 5 跳

示例：

有关项目概述，请参阅 @README
有关此项目的可用 npm 命令，请参阅 @package.json

# 其他指令
- git 工作流 @docs/git-instructions.md

3. .claude/rules/ 目录组织规则

在项目的 .claude/rules/ 目录中放置 markdown 文件，每个文件应涵盖一个主题，使用描述性文件名。

规则：

• 所有 .md 文件都被递归发现

• 可将规则组织到子目录中（如 frontend/、backend/）

• 规则在每个会话 或打开匹配文件时加载到上下文中

• 对于不需要始终在上下文中的特定任务指令，改用 Skills（仅在调用时或 Claude 判定相关时加载）

目录结构示例：

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

4. 特定路径的规则（paths 字段）

规则可以使用 YAML frontmatter 中的 paths 字段范围限定到特定文件。这些条件规则仅在 Claude 处理与指定模式匹配的文件时适用。

没有 paths 字段的规则：无条件加载，适用于所有文件。

路径匹配模式：

模式	匹配范围
**/*.ts	任何目录中的所有 TypeScript 文件
src/**/*	src/ 目录下的所有文件
*.md	项目根目录中的 Markdown 文件
src/components/*.tsx	特定目录中的 React 组件

示例： ```yaml

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

> 注意：路径范围规则在 Claude **读取与模式匹配的文件时触发**，而不是在每次工具使用时。

### 5. 用户级规则

`~/.claude/rules/` 中的个人规则适用于你机器上的**每个项目**。用于处理**非项目特定的偏好**。

**加载顺序：** 用户级规则在项目规则**之前加载**，项目规则拥有**更高优先级**。

### 6. 自动记忆配置

**开关控制：**

| 方式 | 操作 |
|------|------|
| 会话中切换 | 打开 `/memory`，使用自动记忆切换 |
| 项目设置 | 设置 `"autoMemoryEnabled": false` |
| 环境变量 | 设置 `CLAUDE_CODE_DISABLE_AUTO_MEMORY=1` |

**存储位置：**
- 每个项目在 `~/.claude/projects/<project>/memory/` 获得自己的记忆目录
- 可在用户设置 `~/.claude/settings.json` 中自定义路径：

```json
{
  "autoMemoryDirectory": "~/my-custom-memory-dir"
}

值必须是绝对路径或以 ~/ 开头。

加载限制：

• MEMORY.md 的前 200 行 或前 25KB（以先到者为准）在每次对话开始时加载

• 超过该阈值的内容在会话开始时不加载

浏览管理：

• 运行 /memory 并选择自动记忆文件夹来浏览 Claude 保存的内容

• 一切都是纯 markdown，可读取、编辑或删除

7. CLAUDE.md 文件层级

文件位置	作用	说明
~/.claude/CLAUDE.md	主文件夹	适用于所有 Claude 会话
./CLAUDE.md	项目根目录	检入 git，与团队共享
./CLAUDE.local.md	项目根目录	个人项目特定笔记，添加到 .gitignore 不与团队共享

---

八、工作流最佳实践

1. Plan Mode 启动方式

claude --permission-mode plan

2. 先探索，再规划，最后编码

步骤	操作	说明
① 探索	进入 Plan Mode	Claude 读取文件并回答问题，不进行任何更改
② 规划	要求 Claude 创建详细的实现计划	充分理解代码结构后再动手
③ 编码	切换回 Normal Mode	让 Claude 根据计划编码并验证
④ 提交	要求 Claude 提交并创建 PR	使用描述性消息

3. 给 Claude 明确的上下文

Claude 可以推断意图，但不能读心术。建议：

• 引用特定文件（用 @ 引用）

• 明确提及约束条件

• 指出示例模式

---

九、目录结构参考

1. 整体架构：项目级 + 用户级

Claude Code 的配置分为两个层级：

层级	路径	说明
项目级	项目根目录 .claude/	仅当前项目生效，可提交 git 与团队共享
用户级（全局）	~/.claude/	所有项目通用，存放个人偏好

2. 项目级目录结构（.claude/）

your-project/
├── .claude/
│   ├── CLAUDE.md              # 项目规则与持久上下文
│   ├── .mcp.json              # MCP 外部服务连接配置
│   ├── .worktreeinclude       # 开发分支创建时的文件复制清单
│   ├── settings.json          # 项目共享设置（权限、环境变量、模型）
│   ├── settings.local.json    # 个人覆盖设置（不提交 git）
│   ├── rules/                 # 条件触发的规则文件（按主题分文件）
│   ├── skills/                # 可复用的技能（/技能名 调用）
│   ├── commands/              # 快捷命令封装（比 skills 更简单）
│   ├── output-styles/         # 回答格式模板
│   ├── agents/                # 项目级 subagent 定义文件
│   └── agent-memory/          # subagent 的记忆存储

各文件说明：

文件/目录	作用
CLAUDE.md	项目规则和持久上下文，每次会话开始加载。建议 ≤200 行
.mcp.json	配置外部服务连接（数据库、API、部署工具等）
.worktreeinclude	创建 git worktree 分支时需复制的配置文件清单
settings.json	项目基础设置，团队共用
settings.local.json	个人覆盖设置，不提交 git
rules/	按主题分文件的条件规则，相关话题出现时按需加载
skills/	封装标准流程的技能卡片，/技能名 调用
commands/	封装单一操作的快捷命令
output-styles/	控制 Claude 输出格式（列表、步骤等）
agents/	subagent 定义文件（如 code-reviewer.md）
agent-memory/	subagent 的长期记忆（如 code-reviewer/MEMORY.md）

3. 用户级目录结构（~/.claude/）

~/.claude/
├── CLAUDE.md                  # 跨项目通用行为准则
├── settings.json              # 全局基础设置（权限、环境变量、模型）
├── settings.local.json        # 个人偏好覆盖
├── rules/                     # 通用规则库
├── skills/                    # 全局技能
├── commands/                  # 全局命令
├── output-styles/             # 统一回答风格
├── agents/                    # 跨项目可复用的 subagent
├── agent-memory/              # subagent 跨项目记忆
├── projects/<project>/memory/ # 各项目自动记忆
├── keybindings.json           # 键盘快捷键配置
├── themes/*.json              # 自定义颜色主题
└── plugins/                   # 已安装插件

关键全局文件：

文件	作用	注意
~/.claude.json	核心状态存储：登录凭证、UI 设置、插件列表	切勿手动删除
keybindings.json	自定义键盘组合键	-
themes/*.json	自定义颜色主题	-
projects/<project>/memory/	各项目的自动记忆笔记	纯 markdown

4. 运行时临时数据

Claude 工作时自动生成，默认 30 天后自动清理：

数据	说明
projects/<project>/<session>.jsonl	完整对话记录
projects/<project>/<session>/tool-results/	工具输出结果（过大时单独存储）
file-history/<session>/	修改文件前的备份快照（用于检查点恢复）
plans/	Plan Mode 生成的任务分解草稿
debug/	调试日志（仅开启调试时生成）
paste-cache/、image-cache/	粘贴内容和图片缓存
session-env/	当前会话环境元数据
tasks/	当前会话任务列表
shell-snapshots/	命令行环境快照
backups/	~/.claude.json 更新前的时间戳备份

不会自动删除的数据：

数据	说明
history.jsonl	所有提示词历史（按 ↑ 键回忆）
stats-cache.json	聚合使用统计（/usage 展示）
todos/	旧版任务列表（已废弃，可安全删除）

5. 数据清理

# 官方推荐清理命令
claude project purge [参数]

参数	说明
--dry-run	预览将删除的内容，不执行
--yes	跳过确认提示
--all	清除所有项目状态数据
-i	逐项确认删除

切勿手动删除： ~/.claude.json、~/.claude/settings.json、~/.claude/plugins/

---

十、Subagents 实操指南

1. 创建 Subagent 的步骤

1. 在 Claude Code 中运行 /agents

2. 切换到 Library 选项卡 → Create new agent → Personal （保存到 ~/.claude/agents/，所有项目可用）

3. 选择 Generate with Claude，描述 subagent 的功能

4. 选择工具：只读审查者取消选择除 Read-only tools 之外的所有内容；保持全选则继承主对话的所有工具

5. 选择模型：如 Sonnet（分析代码模式的能力与速度平衡）

6. 选择颜色：为 subagent 选择背景颜色，便于在 UI 中识别

7. 配置内存：决定 subagent 是否在对话中积累见解，不需要则选 None

2. /agents 管理界面

选项卡	功能
Running	显示实时 subagents，可打开或停止
Library	查看所有可用 subagents；创建/编辑/删除

3. Subagent 范围

范围	路径	说明
项目级	.claude/agents/	仅当前项目可用
用户级	~/.claude/agents/	所有项目可用

直接在磁盘上添加/编辑 subagent 文件后需重启会话 才能加载；通过 /agents 界面创建的则立即生效。

4. Subagent 文件格式

---
name: code-reviewer
description: Reviews code for quality and best practices
tools: Read, Glob, Grep
model: sonnet
---

You are a code reviewer. When invoked, analyze the code and provide
specific, actionable feedback on quality, security, and best practices.

5. 控制 Subagent 能力

通过 tools（允许列表）或 disallowedTools（拒绝列表）控制：

# 允许列表：只能读取和搜索
---
name: safe-researcher
description: Research agent with restricted capabilities
tools: Read, Grep, Glob, Bash
---

# 拒绝列表：继承所有工具，但禁止写入和编辑
---
name: no-writes
description: Inherits every tool except file writes
disallowedTools: Write, Edit
---

---