跳到主要内容

Claude Code

Claude.md​

Claude.md是全局记忆，每一次对话都会全量发送

模型越强——claude.md应该越小

全局记忆带来的影响

  • 他会占用上下文长度
  • 他会诱发更多行为
    例如,在 md里写了 “每次任务开始前***，每次任务结束后***”
    • 扩大阅读范围
    • 读更多目录
  • 增加判断负担
    • 写了太多泛泛规则

Cluade.md 越长不代表帮助越大，很多时候成为了模型的负担

Claude.md 应该怎么写？​

  • 核心
    • 没有这条内容，AI 将犯错
    • Cluade.md 要不断迭代，不能一次到位
    • 模型越强，Claude.md 反而越简单

官方建议内容行数越少越好

总结：

  1. 写规则，不要写介绍
  2. 写约束，不写常识
  3. 写长期有效的流程信息，不写临时任务
  4. 某个错误模型出现两次以上，则更新到 claude.md 中

如果不知道写什么，就空着或使用 /init 生成，否则就等到模型出现重复性的错误时，将错误写入

Skills​

Skills 是可以复用、可自动触发的能力包。一个 skill 通常包含 SKILL.md、参考文件、脚本和模板。Claude 在合适的场景下会自动加载它。

主要好处

  • 可复用
  • 可渐进加载
  • 可以把脚本、模板、说明放在一起
  • 适合标准化流程

Skills 的工作方式：渐进式披露​

Skills 不会一次性把所有内容都塞进上下文，而是按需加载。

三层加载

  • 只看描述：先判断这个 skill 是否相关
  • 加载 SKILL.md：读取核心说明
  • 按需加载支持文件：脚本、模板、参考资料

Skill 加载流程​

  • Claude 扫描技能目录
  • 根据描述判断是否匹配当前任务
  • 读取 SKILL.md
  • 如有需要，再加载脚本和辅助文件

Skill 类型与位置​

Skills 可以放在：

  • 项目目录下的 .claude/skills/
  • 用户目录下的 ~/.claude/skills/

创建自定义 Skills​

基本目录结构

my-skill/
└── SKILL.md

SKILL.md 格式

---
name: my-skill
description: 这个 skill 的用途，以及什么时候触发
---

# Your Skill Name

## Instructions

## Examples

必填字段

  • name
  • description

可选 frontmatter 字段

  • argument-hint
  • allowed-tools
  • model
  • disable-model-invocation
  • user-invocable
  • context
  • agent
  • hooks

Skill 内容类型​

参考内容​

适合放规则、标准、文档片段和示例。

任务内容​

适合放具体步骤、执行流程和结果格式要求。

控制 Skill 的调用​

你可以通过 disable-model-invocation、user-invocable 和工具白名单来控制 Claude 是否能自动调用这个 skill。

字符串替换​

Skills 支持 $ARGUMENTS、$0、$1 等参数替换。

动态上下文注入​

你可以在 prompt 里插入 shell 命令结果：

  • 当前 git 状态：!git status
  • 当前 diff：!git diff HEAD
  • 当前分支：!git branch --show-current

Subagents​

Subagents 是专门处理某类任务的独立 AI 助手。它们拥有隔离的上下文、自己的提示词和工具权限，适合把复杂工作拆分给不同角色。

主要好处:​

  • 上下文隔离
  • 角色分工清晰
  • 适合并行和委派
  • 便于把复杂任务拆开

文件位置​

项目级：.claude/agents/ 用户级：~/.claude/agents/

配置​

文件格式​

Subagent 通常是一个带 frontmatter 的 Markdown 文件。

---
name: code-reviewer
description: 审查代码质量和安全问题
tools: Read, Grep, Bash
---

# Code Reviewer

配置字段​

字段说明
namesubagent 名称
description何时该调用它
tools允许使用的工具
model指定模型
prompt任务提示词
context上下文策略

内置 Subagents​

Claude Code 自带一些常见角色，例如：

  • 通用助手
  • Planning agent
  • Explore agent
  • Bash agent
  • Statusline 相关 agent
  • Claude Code Guide agent

管理 Subagents​

  1. 使用 /agents 命令（推荐）

  2. 直接管理文件

创建项目 subagent

mkdir -p .claude/agents

创建用户 subagent

mkdir -p ~/.claude/agents

使用 Subagents​

自动委派​

主 agent 可以根据任务描述自动把工作分配给合适的 subagent。

显式调用​

你也可以明确让 Claude 使用某个 subagent。

@ 提及调用​

在一些场景里，可以通过 @agent-name 方式引用。

会话级 agent​

可以在整个会话中固定使用某个 agent。

列出可用 agents​

claude agents

可恢复的 agents​

某些 subagent 可以先启动，之后再恢复，便于长任务接力。

串联 Subagents​

复杂任务里可以让多个 subagent 依次协作，例如：

  • 代码审查
  • 测试生成
  • 文档更新

Subagents 的持久记忆​

Subagents 可以拥有自己的 memory 范围，让它们在各自职责内保持一致。

Memory 范围

  • 项目级
  • 用户级
  • 子目录级

工作方式 Subagent 会在自己的上下文中读取对应记忆，不和主会话完全混在一起。

后台 Subagents​

配置 有些 subagent 可以作为后台任务执行，不阻塞主会话。

快捷键 在支持的界面中，可用快捷键查看或切换后台 subagent。

关闭后台任务 如果你不想让任务后台运行，可以在设置中关闭。

Worktree 隔离​

配置 可以为 subagent 分配独立的 worktree。

工作方式 这样不同任务就不会互相污染文件状态。

限制可启动的 Subagents​

你可以限制 Claude 只能 spawn 某些 subagent，以降低风险。

示例 只允许审查类 agent 禁止高风险自动化 agent

Hook​

Hooks 是在 Claude Code 事件发生时自动执行的 shell 命令，用来做格式化、校验、通知、审计等自动化工作。

Claude Code 提供 4 类、25 个事件：

  • Tool Hooks：
    • PreToolUse：工具被使用前触发
    • PostToolUse：工具使用后触发
    • PostToolUseFailure：工具使用失败后触发
    • PermissionRequest：权限请求
  • Session Hooks：
    • SessionStart：会话开始时触发
    • SessionEnd：会话结束时触发
    • Stop：停止
    • StopFailure：停止失败
    • SubagentStart：子Agent开始时触发
    • SubagentStop：子Agent结束时触发
  • Task Hooks：
    • UserPromptSubmit：用户提交任务时触发
    • TaskCompleted：任务完成时触发
    • TaskCreated：任务创建时触发
    • TeammateIdle：队友空闲时触发
  • Lifecycle Hooks：
    • ConfigChange：配置改变
    • CwdChanged：当前工作目录改变
    • FileChanged：文件改变
    • PreCompact：压缩前
    • PostCompact：压缩后
    • WorktreeCreate：创建工作树
    • WorktreeRemove：移除工作树
    • Notification：通知
    • InstructionsLoaded：指令加载
    • Elicitation：询问
    • ElicitationResult：询问结果

用法​

  1. 提供脚本文件，例如提供一个format-code.sh
    将脚本文件放到~/.claude/hooks/
  2. 配置~/.claude/settings.json
{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Write",
      "hooks": ["~/.claude/hooks/format-code.sh"]
    }],
    "PostToolUse": [{
      "matcher": "Write",
      "hooks": ["~/.claude/hooks/security-scan.sh"]
    }]
  }
}

配置成功后，Hooks 会在匹配到事件时自动执行

最佳实践​

  • 把 hooks 保持短小明确
  • 只做单一职责
  • 先在本地测试
  • 不要在 hook 里放复杂业务逻辑
  • 对副作用保持谨慎

插件​

把多个 Claude Code 功能打包成可安装的一体化方案

Claude Code 插件是把 slash commands 、subagents 、MCP servers 、hooks 组合在一起的功能集合，可以通过一条命令安装。它们代表了 Claude Code 最高级别的扩展方式，把多个功能整合成可共享、可复用的完整方案。

一个插件通常会把以下能力打包在一起：

  • slash commands
  • subagents
  • MCP servers
  • hooks

这样做的好处是：

  • 一次安装即可使用完整工作流
  • 团队共享更容易
  • 配置更统一
  • 便于版本控制和分发

插件架构​

插件定义结构​

插件清单使用 .claude-plugin/plugin.json 中的 JSON 格式：

{
  "name": "my-first-plugin",
  "description": "一个问候插件",
  "version": "1.0.0",
  "author": {
    "name": "Your Name"
  },
  "homepage": "https://example.com",
  "repository": "https://github.com/user/repo",
  "license": "MIT"
}

插件结构示例​

my-plugin/
├── .claude-plugin/
│   └── plugin.json       # 清单（名称、描述、版本、作者）
├── commands/             # 以 Markdown 文件形式存放的命令
│   ├── task-1.md
│   ├── task-2.md
│   └── workflows/
├── agents/               # 自定义 agent 定义
│   ├── specialist-1.md
│   ├── specialist-2.md
│   └── configs/
├── skills/               # 带有 SKILL.md 文件的技能
│   ├── skill-1.md
│   └── skill-2.md
├── hooks/                # hooks.json 中的事件处理器
│   └── hooks.json
├── .mcp.json             # MCP server 配置
├── .lsp.json             # LSP server 配置
├── settings.json         # 默认设置
├── templates/
│   └── issue-template.md
├── scripts/
│   ├── helper-1.sh
│   └── helper-2.py
├── docs/
│   ├── README.md
│   └── USAGE.md
└── tests/
    └── plugin.test.js

LSP server 配置​

插件可以包含 Language Server Protocol（LSP）支持，以获得实时代码智能。LSP server 会在你编写代码时提供诊断、代码导航和符号信息。

配置位置：

  • 插件根目录中的 .lsp.json 文件
  • plugin.json 中的内联 lsp 键

示例：

{
  "typescript": {
    "command": "typescript-language-server",
    "args": ["--stdio"],
    "extensionToLanguage": {
      ".ts": "typescript",
      ".tsx": "typescriptreact",
      ".js": "javascript",
      ".jsx": "javascriptreact"
    }
  }
}

Checkpoints 与 Rewind​

Checkpoints 可以让你保存对话状态，并在 Claude Code 会话中回退到之前的时间点。无论你是在探索不同方案、修复错误，还是比较多个实现路径，这个能力都非常有用。

Checkpoints 会保存会话状态，让你可以安全地试验和探索多种方案。它们本质上是当前对话状态的快照，包含：

  • 所有已交换的消息
  • 已做出的文件修改
  • 工具使用历史
  • 当前会话上下文

当你在尝试不同实现方式、从错误中恢复，或比较替代方案时，这个功能尤其好用。

核心概念​

概念说明
Checkpoint保存消息、文件和上下文的对话快照
Rewind回到之前的 checkpoint，并丢弃之后的更改
Branch Point从同一个 checkpoint 出发，探索多个方案

访问 Checkpoints​

快捷键：两次 Esc

rewind 命令，别名：/checkpoint

Rewind 选项​

回退时，你会看到一个包含五个选项的菜单：

  • 恢复代码和对话 - 把文件和消息都恢复到那个 checkpoint
  • 恢复对话 - 只回退消息，保留当前代码不变
  • 恢复代码 - 只回退文件修改，保留完整对话历史
  • 从这里开始总结 - 把从这里往后的对话压缩成 AI 生成的摘要，而不是直接丢弃。原始消息仍会保留在记录中。你也可以额外指定摘要应聚焦哪些主题。
  • 算了 - 取消并返回当前状态

使用场景​

场景工作流
探索不同方案保存 → 试方案 A → 保存 → Rewind → 试方案 B → 比较
安全重构保存 → 重构 → 测试 → 如果失败：Rewind
A/B 测试保存 → 设计 A → 保存 → Rewind → 设计 B → 比较
错误恢复发现问题 → Rewind 到最后一个正常状态

如何使用 Checkpoints​

查看和回退​

按两次 Esc，或者使用 /rewind 打开 checkpoint 浏览器。你会看到一个带时间戳的可用 checkpoint 列表。选择任意一个 checkpoint，即可回退到该状态。

Checkpoint 详情​

每个 checkpoint 会显示：

  • 创建时间
  • 被修改的文件
  • 对话中的消息数量
  • 使用过的工具

实战示例​

示例 1：探索不同方案​

User: 我们给 API 加一个缓存层吧

Claude: 我会为你的 API 端点添加 Redis 缓存……
[在 checkpoint A 处做出修改]

User: 其实我们先试试内存缓存

Claude: 我会 rewind 回去，探索另一种方案……
[用户按下 Esc+Esc 并回退到 checkpoint A]
[在 checkpoint B 处实现内存缓存]

User: 现在我可以比较两种方案了

示例 2：从错误中恢复​

User: 把认证模块重构成 JWT

Claude: 我会重构认证模块……
[做出大量修改]

User: 等等，这把 OAuth 集成弄坏了。我们回去。

Claude: 我来帮你回退到重构之前……
[用户按下 Esc+Esc，并选择重构前的 checkpoint]

User: 这次我们试一个更保守的方案

技巧​

设置 cc 别名​

例如 使用 c-d 命令 启动 Claude 绕过权限

# claude code 的路径
alias c-d="claude --dangerously-skip-permissions"

用 /init 命令 重构/初始化 claude.md 文档​

Esc 停止，两次 Esc /rewind 回滚​

安装 LSP 插件​

LSP 插件可以在 修改代码后 自动诊断，发现代码语法问题

尽可能 多使用/创建 skills​

合理使用计划模式 plan​

在执行无关的新任务时，使用 /clear 或新 session​

使用 子 Agent（subagent） 能保持上下文清晰​

使用 /btw 进行快速提问​

这个命令可以边运行边提问，不会加入上下文

使用 worktree 并行开发​

使用 MCP 提升能力​

指定具体文件，提高效率​

指令说明​

/init​

/memery​

/config​

/status​

@file​

/diff​

/review​

/simplify​

/compact​

Shift + Tab​

Ctrl + b​

Option + p​

/loop​

/plan​

/batch​

/clear​

/cost​

context​

/export​