ClaudeCode 学习记录ClaudeCode 学习记录一、模式切换按 Shift+Tab(官方文档是这么写的，

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 的步骤

在 Claude Code 中运行 /agents

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

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

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

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

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

配置内存：决定 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
---

ClaudeCode 学习记录