第一章：Claude Code 能做什么：场景定位与适用人群

你写代码时最烦什么？反复切窗口查文档、手动跑测试、改完一个文件忘了另一个、提交前漏了 lint 检查。这些事 Claude Code 能替你干。它不是聊天机器人，是直接跑在你终端里的 AI 工程师——能读你的代码、改你的文件、执行你的命令。

它到底能干什么

先看一个最直接的场景。你刚写完一个函数，想确认它有没有 bug。传统做法：切到浏览器、打开测试框架文档、手写测试用例、跑测试、看结果、修 bug、再跑。Claude Code 怎么做：

claude "给 src/utils/formatDate.ts 写单元测试，用 vitest，覆盖边界情况"

它自己读你的代码，自己决定用什么测试框架，自己写测试文件，自己跑一遍给你看结果。整个过程你只需要敲一行命令。

这不是演示视频里的特效，是每天能用的真实能力。Claude Code 能：

• 读整个项目——不是单个文件，是整个目录树。它知道你的项目结构、依赖关系、配置文件。
• 改代码——加功能、修 bug、重构。改完会告诉你改了哪几个文件、改了什么。
• 跑命令——npm test、git commit、docker build，它都能执行。你决定要不要放行。
• 写文档——从代码生成 README、API 文档、变更日志。
• 审查代码——提交前让它过一遍，能发现你漏掉的类型错误、未处理的边界情况。

谁该用、谁不该用

适合你，如果：

• 你每天花大量时间在重复操作上——跑测试、格式化代码、更新文档
• 你接手了一个老项目，想快速理解代码结构
• 你写代码时经常要查文档、翻 Stack Overflow
• 你一个人维护多个项目，精力不够分
• 你团队里新人多，需要统一的代码规范和质量检查

暂时别碰，如果：

• 你的项目涉及高度敏感数据，且公司不允许任何 AI 工具接触代码
• 你写的是纯算法研究代码，每一步都需要精确控制，不需要自动化辅助
• 你用的是 Claude Code 不支持的编程语言（目前主要支持 TypeScript、Python、Rust、Go、Java 等主流语言）

它不是什么

Claude Code 不是 Copilot 的替代品。Copilot 在你写代码时补全下一行，Claude Code 在你写完代码后帮你做剩下的活。它也不是 ChatGPT——你不会跟它闲聊，你给它任务，它执行任务。

它是个终端里的工程师助理。你负责设计、决策、关键逻辑，它负责执行、检查、重复劳动。

一个真实例子

假设你有个 Node.js 项目，目录结构如下：

my-app/
├── src/
│   ├── api/
│   ├── components/
│   └── utils/
├── tests/
├── package.json
└── tsconfig.json

你想加一个新 API 端点。传统流程：新建文件、写路由、写控制器、写类型定义、写测试、跑测试、修 bug。至少 20 分钟。

用 Claude Code：

claude "在 src/api 下加一个 /users/:id 的 GET 端点，返回用户信息，用已有的数据库模型"

它会先读你的项目结构，找到数据库模型的位置，理解你的路由风格，然后新建文件、写代码、更新路由注册。整个过程你只需要确认它做的对不对。

前置条件

开始用 Claude Code 之前，你只需要：

1. 一个终端（macOS/Linux 原生支持，Windows 用 WSL）
2. Node.js 18+（安装 Claude Code 需要）
3. Anthropic API Key（去 console.anthropic.com 申请）
4. 一个 Git 项目（Claude Code 基于 Git 工作，没有 Git 的项目它也能用，但很多功能会受限）

下一章我们直接上手安装，5 分钟让你跑起来。

装好 Claude Code，跑通你的第一条命令

这一章就干一件事：让你能在终端里敲 claude 然后看到它正常启动。别小看这一步——后面所有子代理、技能、工作流，全得从这里开始。

前置条件

• 一台能联网的电脑（macOS / Linux / Windows WSL2 都行）
• Node.js 18+（推荐 20 LTS）
• 一个 Anthropic 账号（去 console.anthropic.com 注册，免费额度够你玩一阵）
• 终端基础操作：cd、ls、npm 这几个命令不陌生

第一步：检查 Node.js

先确认你机器上有 Node.js：

node --version

如果返回 v18.x.x 或更高，跳过这步。否则去 nodejs.org 下载 LTS 版本。

常见报错：command not found: node → 没装 Node.js，或者装了但没加到 PATH。Windows 用户装完记得重启终端。

第二步：全局安装 Claude Code

npm install -g @anthropic-ai/claude-code

这条命令把 Claude Code 装到全局，之后在任何目录都能直接调用。

预期结果：终端滚动安装日志，最后没有报错。你可以验证：

claude --version

如果看到版本号（比如 0.2.30），装好了。

常见报错：

• EACCES: permission denied → 加 sudo 重跑：sudo npm install -g @anthropic-ai/claude-code
• npm ERR! 404 → 检查网络，或者换个 npm 镜像（npm config set registry https://registry.npmmirror.com）

第三步：登录你的 Anthropic 账号

claude login

浏览器会弹出一个页面让你授权。登录你的 Anthropic 账号，点确认。

预期结果：终端显示 Logged in as your@email.com。如果没弹出浏览器，终端里会给你一个链接，复制到浏览器打开就行。

实用技巧：登录一次之后，Claude Code 会把 token 存在 ~/.claude/credentials，下次不用再登。

第四步：找个项目目录，初始化

随便找个你手头的项目，或者新建一个空目录：

mkdir my-first-claude-project
cd my-first-claude-project
claude

第一次在项目里运行 claude，它会问你要不要创建项目配置文件。选 y。

预期结果：终端进入交互模式，光标前面出现 > 提示符。Claude Code 正在等你发号施令。

常见报错：Error: No API key found → 没登录成功，重新跑 claude login。

第五步：跑第一条命令

在 > 提示符后面输入：

帮我看看这个目录里有什么文件

Claude 会执行 ls -la（或者 Windows 上的 dir），然后把结果告诉你。

预期结果：看到文件列表，以及 Claude 对每个文件的简短说明。如果是个空目录，它会说“目录是空的”。

第六步：退出 Claude Code

/exit

或者直接按 Ctrl+C。

预期结果：回到普通终端。

小贴士：项目配置文件长什么样

初始化时生成的 .claude 目录里有个 settings.json：

{
  "permissions": {
    "allow": ["read", "write", "execute"]
  }
}

这个文件控制 Claude 能在你项目里做什么。默认是允许读、写、执行——够用，但后面第 10 章我们会收紧它。

如果卡住了怎么办

症状	排查
claude 命令找不到	检查 npm 全局安装路径是否在 PATH 里：npm list -g --depth=0
登录页面打不开	检查网络，或者手动复制终端里的链接到浏览器
启动后一直转圈	网络问题，检查能否访问 api.anthropic.com
中文乱码	终端编码问题，macOS/Linux 设 export LANG=zh_CN.UTF-8

一个真实场景：给现有项目加 Claude

假设你有个 React 项目，想用 Claude 帮忙改代码。直接进项目目录：

cd ~/projects/my-react-app
claude

Claude 会自动读取你的 package.json、tsconfig.json 等配置文件，知道这是个 React + TypeScript 项目。你可以直接问：

这个项目的依赖里有没有过时的包？

它会分析 package.json 里的版本号，对比 npm registry，给你一份过时列表。

下一步

装好、登录、跑通第一条命令——你已经完成了最麻烦的部分。下一章我们会让 Claude 帮你自动审查代码，用子代理并行干活。

子代理是什么，为什么需要它

代码审查是团队日常最耗时的环节之一。你提交 PR，等同事有空，看完提几个意见，你再改，再等一轮。如果能让 Claude 先帮你过一遍，把明显的问题筛出来，人工只看它拿不准的部分，效率能翻几倍。

子代理（Sub-agent）就是干这个的。你给它一个任务描述，它独立执行，把结果返回给你。和直接问 Claude 的区别在于：子代理有独立的上下文，不会干扰你当前正在进行的对话；而且你可以同时派多个子代理干不同的事。

这一章我们写一个代码审查子代理。它拿到你的代码变更，检查常见问题，输出一份结构化报告。

前置条件

• 已完成第 2 章的安装和项目初始化
• 当前在项目根目录下
• 项目里至少有一个 .py 或 .js 文件（随便写几行有问题的代码也行）

第一步：创建子代理文件

子代理放在 .claude/agents/ 目录下，每个子代理是一个 Markdown 文件。

mkdir -p .claude/agents
touch .claude/agents/code-review.md

这个文件就是子代理的"大脑"。你写清楚它该做什么、怎么做，Claude 就会照办。

第二步：编写子代理指令

打开 .claude/agents/code-review.md，写入以下内容：

# Code Review Agent

你是一个代码审查助手。你的任务是审查用户提供的代码变更，找出潜在问题。

## 审查范围

- 语法错误和运行时异常
- 安全漏洞（SQL 注入、XSS、硬编码密钥等）
- 性能问题（不必要的循环、重复计算等）
- 代码风格不一致（命名规范、缩进等）
- 缺少错误处理
- 可维护性问题（魔法数字、过长函数等）

## 输出格式

对每个发现的问题，按以下格式报告：

### [严重程度] 问题描述

- **文件**: 文件名
- **行号**: 行号范围
- **建议**: 如何修复
- **理由**: 为什么这是个问题

严重程度分为：CRITICAL / MAJOR / MINOR / INFO

## 工作流程

1. 先读取用户提供的代码或 diff
2. 逐项检查审查范围
3. 如果没有发现问题，输出 "✅ 未发现明显问题"
4. 如果发现问题，按严重程度从高到低排列输出
5. 最后给出总体评价和改进建议

保存文件。这就是子代理的全部配置——不需要写代码，不需要编译。

第三步：运行子代理

在 Claude Code 对话中，用 /agent 命令调用它：

/agent code-review

Claude 会读取 .claude/agents/code-review.md 的内容，进入子代理模式。接下来你给它代码，它就会按你写的规则审查。

先给它一段有问题的代码试试：

审查这段 Python 代码：

def process_user_input(data):
    query = "SELECT * FROM users WHERE id = " + data["id"]
    result = db.execute(query)
    for i in range(10000):
        print(i)
    return result

预期输出应该类似：

### CRITICAL SQL 注入风险

- **文件**: 用户提供的代码片段
- **行号**: 2
- **建议**: 使用参数化查询，例如 `db.execute("SELECT * FROM users WHERE id = ?", (data["id"],))`
- **理由**: 直接拼接用户输入到 SQL 查询中，攻击者可以注入恶意 SQL 语句

### INFO 不必要的循环

- **文件**: 用户提供的代码片段
- **行号**: 4
- **建议**: 移除调试用的循环，或限制循环次数
- **理由**: 循环 10000 次打印无实际用途，影响性能

第四步：审查实际文件变更

子代理不只是审查你粘贴的代码。在真实场景中，你刚改完一批文件，想让子代理看看有没有问题。

先准备一个简单的 diff。假设你改了 app.py：

# 旧版本
def get_user(user_id):
    return db.query(f"SELECT * FROM users WHERE id = {user_id}")

# 新版本
def get_user(user_id):
    return db.query(f"SELECT * FROM users WHERE id = {user_id}")
    print("user fetched")

在 Claude Code 里，你可以直接说：

/agent code-review
审查我刚刚对 app.py 的修改

Claude 会自动读取当前工作区的变更。如果你还没提交，它会看未暂存的修改；如果已经提交，它会看最近的 commit diff。

常见问题

子代理不按指令输出？ 检查 .claude/agents/code-review.md 的格式。文件必须是纯 Markdown，第一行是 # 标题。如果文件内容为空或格式不对，Claude 会忽略它。

子代理看不到我的文件？ 子代理的上下文默认只包含你给它的信息。如果你想让子代理直接读取项目文件，需要在指令里明确说"读取当前工作区的变更"或"读取 src/ 目录下的所有 .py 文件"。

可以同时跑多个子代理吗？ 可以。在 Claude Code 里，你可以先 /agent code-review 审查代码，然后 /agent security-audit 检查安全——两个子代理互不干扰。

一个小技巧

子代理指令写得越具体，输出越稳定。比如你团队用 Black 格式化 Python，就在指令里加上"检查代码是否符合 Black 格式规范"。你团队用 TypeScript，就加上"检查类型定义是否完整"。子代理是活的，随时可以改。

下一章我们会把审查子代理做成一个斜杠命令，一键触发，不用每次手动输入 /agent。

为什么需要自定义命令

你每天在终端里重复做的事情太多了：跑测试、格式化代码、提交 PR、启动 dev server。每次都要打一长串命令，或者反复跟 Claude 说“帮我运行测试”。斜杠命令就是把这些重复动作压缩成 /test 或 /fmt 的东西。

Claude Code 的自定义命令放在 .claude/commands/ 目录下，每个文件就是一个斜杠命令。你写一个 Markdown 文件，告诉 Claude 这个命令要做什么，然后就能在对话里直接 /你的命令名 调用。

前置条件

• 已完成第 2 章的安装和初始化
• 项目根目录下存在 .claude/ 文件夹（如果没有，先 mkdir -p .claude/commands）
• 你有一个想重复执行的任务（比如运行测试、代码审查、部署预览）

第一步：创建你的第一个命令

先跑起来再说。在项目根目录执行：

mkdir -p .claude/commands

然后创建一个文件 .claude/commands/test.md：

Run the project's test suite.

1. Install dependencies if needed: `npm install`
2. Run all tests: `npm test`
3. Show a summary of passed/failed tests

就这么简单。现在在 Claude Code 里输入 /test，Claude 会读取这个文件，按步骤执行。

预期结果：Claude 会先检查依赖是否安装，然后跑 npm test，最后给你一个测试结果摘要。

第二步：理解命令文件的结构

命令文件的核心规则只有一条：你写什么，Claude 就做什么。但有几个要点：

• 文件名去掉 .md 就是命令名（test.md → /test）
• 文件内容就是给 Claude 的指令，可以包含步骤、注意事项、甚至代码示例
• Claude 会按你写的顺序执行，但也会根据实际情况做判断（比如依赖已安装就跳过安装步骤）

一个更完整的例子 .claude/commands/fmt.md：

Format all source code files.

1. Run `npx prettier --write "src/**/*.{js,ts,jsx,tsx}"`
2. Run `npx eslint --fix src/`
3. If any files were changed, show the list of changed files

这里的关键是：步骤要具体，但不要过度约束。你不需要告诉 Claude 怎么安装 Prettier，它自己会处理。

第三步：给命令加参数

有时候你需要让命令接受输入。比如 /deploy staging 和 /deploy production 应该部署到不同环境。

Claude Code 的命令天然支持参数——你在命令名后面输入的任何内容，Claude 都能看到。你只需要在命令文件里告诉它怎么处理这些参数。

创建 .claude/commands/deploy.md：

Deploy the application to a specified environment.

The user will provide the environment name after the command, for example:
- `/deploy staging` - deploy to staging
- `/deploy production` - deploy to production

Steps:
1. Identify the target environment from the user's input
2. Run the appropriate deploy script: `npm run deploy:{environment}`
3. Wait for the deployment to complete
4. Show the deployment URL

预期结果：输入 /deploy staging，Claude 会识别出环境是 staging，然后执行 npm run deploy:staging。

第四步：多步骤工作流命令

有些任务需要多个步骤，而且步骤之间有依赖关系。比如“提交代码并创建 PR”：

创建 .claude/commands/pr.md：

Create a pull request from the current branch.

Steps:
1. Check the current git branch: `git branch --show-current`
2. If there are uncommitted changes, ask the user if they want to commit them
3. Push the branch: `git push origin HEAD`
4. Create a PR using gh CLI: `gh pr create --fill`
5. Show the PR URL

Notes:
- Do not commit without user confirmation
- If gh CLI is not installed, suggest installing it

这个命令做了几件事：

• 先检查当前分支
• 处理未提交的变更（需要用户确认）
• 推送代码
• 创建 PR
• 显示结果

预期结果：输入 /pr，Claude 会一步步执行，在需要你确认的地方停下来等你。

第五步：调试和优化命令

命令写好了不一定一次就完美。常见问题：

问题 1：命令没找到

Unknown command: /xxx

检查文件名拼写，确保文件在 .claude/commands/ 下，且扩展名是 .md。

问题 2：Claude 执行顺序不对 你的步骤写得太模糊了。比如“运行测试”不够具体，改成“运行 npm test 并等待结果”。

问题 3：参数没传进去 确认你在命令文件里明确写了“用户会在命令后面提供参数”。Claude 不会自动把用户输入映射到变量，你需要告诉它怎么解析。

优化技巧：在命令文件开头加一段“预期行为”的描述，让 Claude 先理解整体目标再执行细节。

实战小例子：一键代码审查命令

假设你团队每天要做代码审查，每次都手动指定文件太麻烦。创建一个命令，自动审查最近修改的文件：

创建 .claude/commands/review.md：

Review the most recently changed files in the project.

Steps:
1. Get the last 5 modified files: `git diff --name-only HEAD~1`
2. For each changed file, review it for:
   - Potential bugs or logic errors
   - Code style consistency
   - Missing error handling
   - Security vulnerabilities
3. Summarize findings in a table with: file name, issue type, severity (low/medium/high), suggestion
4. If there are high-severity issues, ask the user if they want to fix them

Notes:
- Focus on meaningful issues, not nitpicks
- If a file is auto-generated, skip it

现在你只需要输入 /review，Claude 就会自动找出最近修改的文件，逐行审查，给你一份结构化的报告。

什么时候用命令，什么时候用技能

命令适合一次性、有明确步骤的任务。技能（Skills）是更复杂的、需要上下文理解的能力。简单区分：

• 命令：跑测试、格式化、部署、创建 PR、代码审查
• 技能：理解项目架构、生成文档、重构代码

命令文件通常不超过 20 行，技能文件可能上百行。如果你发现命令文件越来越长、逻辑越来越复杂，考虑把它拆成多个命令，或者升级成技能。

记住一点

命令文件是给 Claude 看的指令，不是 shell 脚本。你不需要写 if 判断或循环，Claude 自己会做决策。你只需要告诉它“做什么”，不用教它“怎么做”。

技能是什么，为什么你需要它

斜杠命令解决的是“重复执行固定操作”，但 Claude 能做的事远不止跑脚本。技能（Skill）是教 Claude 一个全新的能力——不是调用你写好的函数，而是让它学会“怎么做一件事”。

举个例子：你希望 Claude 能分析代码的圈复杂度，或者能按你的代码风格自动格式化，或者能识别项目里的安全漏洞模式。这些不是简单的一条命令能搞定的，需要 Claude 理解规则、步骤、判断标准。技能就是干这个的。

技能文件放在 .claude/skills/<技能名>/SKILL.md 里。Claude 启动时会读取这些文件，把它们当作“内置知识”来用。

前置条件

• 已完成第 2 章的安装和初始化
• 项目根目录下存在 .claude/ 文件夹
• 你有一个想教 Claude 的具体能力（别想太复杂，先从一个简单的开始）

第一步：创建技能目录和文件

直接动手：

mkdir -p .claude/skills/code-review-lite
touch .claude/skills/code-review-lite/SKILL.md

技能目录名就是技能的名字，用短横线连接。SKILL.md 是固定文件名，不能改。

第二步：写技能内容

打开 SKILL.md，写清楚你要教 Claude 什么。格式很自由，但核心是说清楚步骤和规则。

先写一个最简单的——让 Claude 学会检查代码里有没有硬编码的 API Key：

# Code Review Lite

## 目标
检查代码中是否存在硬编码的敏感信息（API Key、Token、密码等）。

## 触发方式
当用户说“检查敏感信息”或“扫一下密钥”时，执行此技能。

## 检查规则
1. 扫描所有 `.py`、`.js`、`.ts`、`.env.example` 文件
2. 查找以下模式：
   - `api_key = "..."` 或 `API_KEY="..."`
   - `token = "..."` 或 `TOKEN="..."`
   - `password = "..."` 或 `PASSWORD="..."`
   - `secret = "..."` 或 `SECRET="..."`
3. 排除 `node_modules/`、`.git/`、`dist/`、`build/` 目录
4. 对每个匹配项，报告：
   - 文件路径和行号
   - 匹配到的变量名（不输出具体值）
   - 建议：移到环境变量或密钥管理服务

## 输出格式

🔍 发现 [数量] 处硬编码敏感信息：

• [文件路径]:[行号] - [变量名] 建议：...

## 注意事项
- 只检查代码文件，不检查二进制文件
- 如果项目有 `.env` 文件，提醒用户检查是否被 git 跟踪

保存文件。就这么简单。

第三步：测试技能

在项目目录里运行 Claude Code：

claude

然后输入：

检查敏感信息

Claude 会读取 SKILL.md，按你写的规则执行。如果项目里确实有硬编码的密钥，它会列出来。

预期结果：Claude 开始扫描文件，输出格式跟你定义的一致。如果没触发，检查一下你的措辞是否跟“触发方式”里写的一致。

技能的核心设计原则

写技能时记住三点：

1. 步骤要可执行

不要写“分析代码质量”，要写“检查函数长度是否超过 50 行”“检查是否有未处理的异常”。Claude 是语言模型，不是魔法师——它需要明确的判断标准。

2. 给例子

在技能文件里放输入输出的例子，Claude 会模仿这个模式。比如：

## 示例
输入：
```python
def login():
    api_key = "sk-1234567890abcdef"
    return api_key

输出：

🔍 发现 1 处硬编码敏感信息：
- src/auth.py:2 - api_key
建议：将 api_key 移到环境变量，使用 os.getenv("API_KEY")

**3. 限定范围**

一个技能只做一件事。不要写“检查代码质量和性能和安全”，拆成三个技能。Claude 在单一任务上表现更好。

## 常见问题

**技能没生效？**
- 检查文件名是不是 `SKILL.md`（全大写）
- 检查目录结构是不是 `.claude/skills/<技能名>/SKILL.md`
- 运行 `claude` 时确保在项目根目录

**Claude 不按我的格式输出？**
- 在技能文件里明确写“输出格式”，最好给完整示例
- 在规则里加一句“严格按照此格式输出，不要添加额外说明”

**技能跟斜杠命令搞混了？**
- 斜杠命令（`/xxx`）是执行你写好的脚本或命令
- 技能是教 Claude 怎么做一件事，不需要你写代码
- 简单区分：技能是“教方法”，命令是“调工具”

## 真实场景：让技能更实用

上面那个检查密钥的技能太基础了。我们来升级一下——让 Claude 学会检查代码中的常见安全问题（OWASP Top 10 简化版）：

```markdown
# Security Scan Lite

## 目标
扫描代码中的常见安全漏洞模式。

## 触发方式
用户说“安全扫描”或“安全检查”或“扫一下安全”

## 检查项
### 1. SQL 注入
- 查找：直接拼接 SQL 字符串的模式
- 规则：如果发现 `f"SELECT * FROM {user_input}"` 或 `"SELECT * FROM " + user_input`，标记为高危

### 2. 命令注入
- 查找：`os.system()`、`subprocess.run()`、`subprocess.Popen()` 中使用了用户输入
- 规则：如果参数不是硬编码字符串，标记为高危

### 3. 路径遍历
- 查找：`open()`、`read()`、`write()` 中使用了用户输入作为路径
- 规则：如果没有使用 `os.path.basename()` 或路径白名单，标记为中危

### 4. 不安全的反序列化
- 查找：`pickle.loads()`、`yaml.load()`（不带 SafeLoader）
- 规则：标记为高危

## 输出格式

[严重级别] [文件路径]:[行号] - [问题描述] 建议：[修复建议]

## 示例输出

高危 src/db.py:42 - SQL 注入风险：直接拼接用户输入到查询字符串 建议：使用参数化查询，例如 cursor.execute("SELECT * FROM users WHERE id = ?", (user_id,))

这个技能让 Claude 变成了一个基础的代码安全扫描器。你不需要装任何工具，不需要写 Python 脚本，只需要把规则写清楚。

技能文件里还能放什么

除了步骤和规则，你还可以在 SKILL.md 里放：

• 背景知识：Claude 需要了解的领域概念
• 判断标准：什么算通过，什么算不通过
• 边界情况：特殊场景怎么处理
• 参考链接：官方文档或标准（Claude 会去读）

但别写太长。一个技能文件控制在 50-100 行以内最好。太长 Claude 会“记不住”重点。

下一步

技能写好了，但每次都要手动输入“检查敏感信息”有点麻烦。下一章我们会讲怎么把技能串成工作流——比如“提交代码前自动跑安全扫描 + 代码审查 + 单元测试”。

为什么需要工作流

单个子代理能完成一件事，但真实项目需要多步协作：先分析代码结构，再生成测试，最后运行验证。手动一步步输入太慢，而且容易漏掉中间步骤。工作流就是把这些步骤写成编排脚本，一次执行。

前置条件

• 已完成第 3 章，至少有一个可用的子代理（比如 code-review）
• 项目根目录有 .claude/ 文件夹
• 理解斜杠命令的基本写法（第 4 章内容）

工作流本质就是命令

Claude Code 没有单独的工作流语法。工作流就是一个斜杠命令文件，里面用 @ 符号调用子代理。你已经在第 4 章写过命令了，现在只是让命令变得更复杂——串联多个子代理。

先看一个最简单的例子。在 .claude/commands/ 下新建 full-check.md：

---
description: "完整检查：lint → 类型检查 → 测试"
---

先运行 lint 检查代码风格：
@lint

再运行类型检查：
@type-check

最后运行测试：
@test

这个文件干了三件事：依次调用三个子代理。每个 @子代理名 会让 Claude 切换到对应子代理的上下文执行任务。

第一步：准备三个子代理

先创建三个子代理文件，每个负责单一任务。

.claude/agents/lint.md：

---
description: "运行 ESLint 并修复可自动修复的问题"
---

你是一个 lint 专家。执行以下步骤：
1. 运行 `npx eslint . --fix`
2. 如果有报错，列出前 5 个错误并给出修复建议
3. 不要修改业务逻辑，只修复格式问题

.claude/agents/type-check.md：

---
description: "运行 TypeScript 类型检查"
---

你是一个类型检查专家。执行：
1. 运行 `npx tsc --noEmit`
2. 如果有类型错误，按严重程度排序输出
3. 对每个错误给出修复方案

.claude/agents/test.md：

---
description: "运行测试并报告覆盖率"
---

你是一个测试专家。执行：
1. 运行 `npm test`
2. 如果测试失败，分析失败原因
3. 输出测试覆盖率摘要

创建完后，在终端单独测试每个子代理：

claude

然后输入：

@lint

确认它能正常工作。再试 @type-check 和 @test。任何一个报错都要先修好，否则工作流会卡住。

第二步：编写编排命令

现在把三个子代理串起来。新建 .claude/commands/ci-check.md：

---
description: "CI 检查流水线：lint → 类型检查 → 测试"
---

你是一个 CI 编排者。按顺序执行以下步骤，每一步必须成功才能继续：

第一步：代码风格检查
@lint

如果上一步有错误，先修复再继续。

第二步：类型检查
@type-check

如果上一步有类型错误，先修复再继续。

第三步：运行测试
@test

全部完成后，输出一份总结报告，格式如下：
- ✅/❌ Lint: 结果摘要
- ✅/❌ TypeScript: 结果摘要
- ✅/❌ Tests: 结果摘要
- 总耗时估算

注意几个关键点：

1. 顺序依赖：用文字明确告诉 Claude "上一步失败就停"。Claude 会理解这个逻辑。
2. 状态传递：每个子代理运行后，文件系统的改动（比如 lint 修复后的代码）会保留给下一步。
3. 输出汇总：最后一步让 Claude 自己总结，省得你翻聊天记录。

第三步：运行工作流

在 Claude Code 会话中输入：

/ci-check

你会看到 Claude 依次：

1. 调用 lint 子代理 → 运行 ESLint → 输出结果
2. 调用 type-check 子代理 → 运行 tsc → 输出结果
3. 调用 test 子代理 → 运行测试 → 输出结果
4. 生成总结报告

整个过程可能持续几十秒到几分钟，取决于项目大小。

带条件分支的工作流

上面的例子是线性执行。真实场景需要条件判断：比如只有测试通过才部署。

新建 .claude/commands/deploy-check.md：

---
description: "部署前检查：测试通过才部署"
---

第一步：运行完整测试
@test

检查测试结果。如果测试失败，输出错误信息并停止，不要继续部署。

第二步：测试通过，开始构建
运行 `npm run build`

如果构建失败，输出错误信息并停止。

第三步：构建成功，部署到预览环境
运行 `npm run deploy:staging`

部署完成后，输出预览 URL。

这个工作流里，Claude 会根据上一步的输出决定是否继续。你不需要写 if-else 语法，用自然语言描述条件就行。

并行执行多个子代理

有些步骤可以同时跑，比如同时检查前端和后端。在命令文件里这样写：

---
description: "并行检查前后端"
---

同时运行以下两个检查：

前端检查：
@lint-frontend

后端检查：
@lint-backend

等两个都完成后，汇总结果。

Claude 会先启动第一个子代理，然后启动第二个。注意：Claude Code 目前是串行调用子代理的，但你可以让每个子代理内部执行并行任务（比如同时 lint 多个文件）。

常见问题

子代理执行顺序乱了 检查命令文件里的步骤编号。Claude 会按你写的顺序执行，但如果你写 "先做 A 再做 B 同时做 C"，它可能理解错。保持步骤编号清晰。

子代理之间状态丢失 每个子代理运行时会修改文件，这些修改会保留。但子代理的聊天上下文不会传递。如果下一步需要上一步的输出内容，让上一步把结果写入文件。比如：

第一步：运行 lint 并将结果保存到 lint-report.txt
@lint

第二步：读取 lint-report.txt，根据结果决定是否继续

工作流中途卡住 按 Ctrl+C 中断，检查是哪个子代理出了问题。单独运行那个子代理调试。

子代理返回错误但工作流继续 在命令文件里加明确指令："如果上一步返回错误代码，立即停止"。Claude 会检查命令的退出码。

真实场景：PR 检查工作流

把上面的东西拼成一个完整的 PR 检查工作流。新建 .claude/commands/pr-check.md：

---
description: "PR 检查：lint → 类型 → 测试 → 构建"
---

你是一个 PR 审查助手。按顺序执行：

1. 代码风格检查
@lint
如果 lint 有错误，输出 "❌ Lint 失败" 并停止。

2. 类型检查
@type-check
如果有类型错误，输出 "❌ 类型检查失败" 并停止。

3. 运行测试
@test
如果有测试失败，输出 "❌ 测试失败" 并停止。

4. 构建项目
运行 `npm run build`
如果构建失败，输出 "❌ 构建失败" 并停止。

5. 全部通过
输出 "✅ PR 检查全部通过"
列出本次检查的变更文件列表。

在项目根目录运行：

/pr-check

每次提交 PR 前跑一遍这个命令，确保不会把坏代码合进去。

记住一点

工作流文件就是命令文件，放在 .claude/commands/ 下。唯一的区别是它用 @子代理名 调用其他子代理。你不需要学新语法，只需要把步骤写清楚。

钩子（Hooks）：在关键节点注入自动化逻辑

写代码时总有那么几个重复动作：每次提交前跑一遍测试、每次启动项目时拉取最新依赖、每次 Claude 生成代码后自动格式化。手动做？太蠢。忘了做？更蠢。

钩子就是干这个的。它在 Claude Code 的生命周期里埋了几个“触发点”——你只要把脚本扔进 .claude/hooks/ 目录，到了那个节点，Claude 自动帮你跑。

前置条件

• 已完成第 2 章的安装和初始化
• 项目根目录下有 .claude/ 文件夹（没有就 mkdir -p .claude/hooks）
• 会写简单的 shell 脚本（不会也没事，复制粘贴改改就行）

钩子有哪些触发点

Claude Code 目前支持这些钩子：

钩子名	触发时机
pre-tool-use	每次调用工具之前
post-tool-use	每次调用工具之后
pre-command	执行斜杠命令之前
post-command	执行斜杠命令之后
pre-send-message	发送消息给模型之前
post-send-message	收到模型回复之后
pre-edit	编辑文件之前
post-edit	编辑文件之后

每个钩子就是一个可执行文件（shell 脚本、Python 脚本、二进制都行），放在 .claude/hooks/<钩子名>。

第一步：写一个最简单的钩子

先跑起来再说。我们写一个 post-edit 钩子，每次 Claude 改完文件后打印一行日志。

# .claude/hooks/post-edit
#!/bin/bash
echo "[HOOK] 文件被修改了: $(date)" >> /tmp/claude-hooks.log

给执行权限：

chmod +x .claude/hooks/post-edit

现在让 Claude 改个文件试试。随便说“把 README.md 第一行改成 Hello”。看看 /tmp/claude-hooks.log 里有没有新内容。

有就对了。没有？检查两件事：文件有没有执行权限，路径是不是 .claude/hooks/post-edit（不是 post-edit.sh，不是 post-edit/）。

第二步：拿到钩子上下文

光打印时间没意思。钩子运行时，Claude 会往环境变量里塞一堆信息，告诉你“刚才发生了什么”。

常用的环境变量：

• CLAUDE_HOOK_EVENT：触发的事件名（比如 post-edit）
• CLAUDE_HOOK_FILE：涉及的文件路径
• CLAUDE_HOOK_TOOL：调用的工具名
• CLAUDE_HOOK_COMMAND：执行的斜杠命令

写一个能看上下文的钩子：

# .claude/hooks/post-tool-use
#!/bin/bash
echo "[HOOK] 工具: $CLAUDE_HOOK_TOOL" >> /tmp/claude-hooks.log
echo "[HOOK] 文件: $CLAUDE_HOOK_FILE" >> /tmp/claude-hooks.log
echo "[HOOK] 事件: $CLAUDE_HOOK_EVENT" >> /tmp/claude-hooks.log
echo "---" >> /tmp/claude-hooks.log

给权限，然后让 Claude 做点事。看看日志里都记了啥。

第三步：干点实际的事

钩子最常用的场景：提交前自动跑测试。

# .claude/hooks/pre-command
#!/bin/bash

# 只在执行 /test 命令时触发
if [ "$CLAUDE_HOOK_COMMAND" = "test" ]; then
  echo "⏳ 检测到测试命令，先拉取最新代码..."
  git pull --rebase
  
  if [ $? -ne 0 ]; then
    echo "❌ 拉取失败，中止测试"
    exit 1
  fi
  
  echo "✅ 代码已更新"
fi

另一个实用场景：每次编辑后自动格式化。

# .claude/hooks/post-edit
#!/bin/bash

# 只格式化特定类型的文件
case "$CLAUDE_HOOK_FILE" in
  *.js|*.ts|*.jsx|*.tsx)
    npx prettier --write "$CLAUDE_HOOK_FILE" 2>/dev/null
    ;;
  *.py)
    black "$CLAUDE_HOOK_FILE" 2>/dev/null
    ;;
  *.go)
    gofmt -w "$CLAUDE_HOOK_FILE" 2>/dev/null
    ;;
esac

注意：钩子里 exit 1 会中断 Claude 当前的操作。比如 pre-edit 钩子返回非零，Claude 就不会执行编辑。这可以用来做准入检查。

第四步：用钩子做安全检查

假设你不想让 Claude 修改 config/production.json 这个文件：

# .claude/hooks/pre-edit
#!/bin/bash

if [ "$CLAUDE_HOOK_FILE" = "config/production.json" ]; then
  echo "❌ 禁止修改生产配置文件"
  exit 1
fi

Claude 尝试改这个文件时，会看到错误提示，然后停下来问你怎么办。

常见坑

钩子超时：默认 30 秒。你的脚本如果跑个 npm install 可能要一分钟，Claude 会报超时。解决办法：在脚本里加 trap 处理，或者把耗时操作扔到后台。

环境变量不生效：钩子是在 Claude Code 的子进程里跑的，不是你的 shell 环境。别指望 .bashrc 里的 alias 和 PATH 修改。需要什么就自己在脚本里 export。

多个钩子串行执行：同一个触发点可以有多个钩子吗？不行。每个触发点只认一个可执行文件。如果你需要跑多个操作，在脚本里自己串起来。

调试困难：钩子跑的时候你看不到 stdout，除非 Claude 把它打印出来。建议所有钩子都写日志到文件，方便排查。

# 调试模板
#!/bin/bash
exec 2>>/tmp/claude-hooks-errors.log
set -x  # 打印每条命令
echo "[DEBUG] 触发: $CLAUDE_HOOK_EVENT" >> /tmp/claude-hooks-debug.log

一个完整的小例子

假设你在做一个 Node.js 项目，想要：

1. 每次 Claude 改完代码自动跑 lint
2. 每次执行 /deploy 命令前检查 git 状态
3. 记录所有文件修改历史

三个钩子搞定：

# .claude/hooks/post-edit
#!/bin/bash
# 自动 lint
npx eslint --fix "$CLAUDE_HOOK_FILE" 2>/dev/null || true

# .claude/hooks/pre-command
#!/bin/bash
if [ "$CLAUDE_HOOK_COMMAND" = "deploy" ]; then
  if [ -n "$(git status --porcelain)" ]; then
    echo "❌ 有未提交的修改，先提交再部署"
    exit 1
  fi
fi

# .claude/hooks/post-tool-use
#!/bin/bash
if [ "$CLAUDE_HOOK_TOOL" = "Edit" ]; then
  echo "$(date) | $CLAUDE_HOOK_FILE" >> .claude/.edit-history
fi

给权限，重启 Claude Code，试试看。

什么时候别用钩子

钩子不是万能的。这些场景用别的方式更好：

• 项目级配置：用 CLAUDE.md 或 .claude/rules/
• 重复性对话模板：用斜杠命令
• 复杂多步骤流程：用工作流（Workflows）
• 需要外部 API：用 MCP 服务器

钩子最适合的是轻量、同步、无状态的自动化——改完文件顺手格式化、执行命令前检查条件、记录日志。超过 50 行的脚本，考虑拆出去单独维护。

为什么需要 MCP

Claude Code 自带的能力够用，但总有边界——它不能直接读数据库、不能发 HTTP 请求、不能操作文件系统之外的东西。MCP（Model Context Protocol）就是用来打破这些边界的。

MCP 服务器本质上是一个轻量级进程，Claude 可以调用它暴露的工具（tools）来执行特定操作。你写一个 MCP 服务器，Claude 就能用它查天气、搜网页、读写数据库、调用外部 API——只要你能写出来，它就能用。

这一章我们从一个最简单的 MCP 服务器开始，然后接入一个实用的第三方 MCP，最后自己写一个。

前置条件

• 已安装 Claude Code（版本 ≥ 0.2.0）
• 已初始化项目（有 .claude/ 目录）
• 本地有 Node.js 18+（写 MCP 服务器用，也可以用 Python）

第一步：理解 MCP 的配置位置

MCP 服务器的配置写在两个地方：

1. 项目级：.claude/settings.json 或 .mcp.json
2. 全局级：~/.claude/settings.json

项目级优先。我们只改项目级，不影响其他项目。

先看一眼你当前的 settings.json：

cat .claude/settings.json

如果文件不存在，直接创建它。MCP 配置放在 mcpServers 字段下：

{
  "mcpServers": {}
}

第二步：接入一个现成的 MCP 服务器

先跑起来再说。我们接入一个官方示例——@anthropic/mcp-server-demo，它提供一个 echo 工具，把输入原样返回。

安装并启动：

npx @anthropic/mcp-server-demo

看到输出 MCP server running on stdio 就对了。按 Ctrl+C 停掉，我们把它配进 Claude Code。

编辑 .claude/settings.json：

{
  "mcpServers": {
    "demo-echo": {
      "command": "npx",
      "args": ["@anthropic/mcp-server-demo"]
    }
  }
}

保存。重启 Claude Code（如果正在运行）。

在 Claude Code 里输入：

/echo 你好世界

Claude 会调用 MCP 服务器的 echo 工具，返回 你好世界。

预期结果：Claude 告诉你它调用了 echo 工具，返回了你输入的内容。

第三步：接入一个有用的 MCP——文件系统操作

官方有一个 @anthropic/mcp-server-filesystem，可以安全地读写文件。我们用它来演示 MCP 的实际价值。

安装：

npx @anthropic/mcp-server-filesystem --help

确认它能跑。然后配进 settings.json：

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["@anthropic/mcp-server-filesystem", "--allowed-directories", "/tmp"]
    }
  }
}

--allowed-directories 指定 MCP 服务器能访问的目录。必须指定，否则启动会报错。

重启 Claude Code，然后问它：

帮我读取 /tmp 目录下的所有文件

Claude 会调用 list_directory 工具，返回文件列表。

常见报错：如果看到 Error: MCP server "filesystem" exited with code 1，检查 --allowed-directories 路径是否存在，是否有读权限。

第四步：自己写一个 MCP 服务器

现成的 MCP 服务器够用，但真正强大的是自己写。我们写一个最简单的——返回当前时间的 MCP 服务器。

创建 mcp-time-server.js：

#!/usr/bin/env node
import { Server } from '@anthropic-ai/sdk/mcp/server.js';
import { StdioServerTransport } from '@anthropic-ai/sdk/mcp/transport/stdio.js';

const server = new Server({
  name: 'time-server',
  version: '1.0.0',
});

server.setRequestHandler('tools/list', async () => ({
  tools: [
    {
      name: 'get_current_time',
      description: '获取当前时间',
      inputSchema: {
        type: 'object',
        properties: {
          timezone: {
            type: 'string',
            description: '时区，如 Asia/Shanghai',
          },
        },
      },
    },
  ],
}));

server.setRequestHandler('tools/call', async (request) => {
  if (request.params.name === 'get_current_time') {
    const timezone = request.params.arguments?.timezone || 'UTC';
    const now = new Date();
    const timeStr = now.toLocaleString('zh-CN', { timeZone: timezone });
    return {
      content: [{ type: 'text', text: `当前时间 (${timezone}): ${timeStr}` }],
    };
  }
  throw new Error(`Unknown tool: ${request.params.name}`);
});

const transport = new StdioServerTransport();
await server.connect(transport);

安装依赖：

npm init -y
npm install @anthropic-ai/sdk

测试一下：

node mcp-time-server.js

它不会输出任何东西，因为它在等待 stdin 输入。按 Ctrl+C 停掉。

配进 settings.json：

{
  "mcpServers": {
    "time-server": {
      "command": "node",
      "args": ["mcp-time-server.js"],
      "cwd": "/你的项目绝对路径"
    }
  }
}

cwd 必须写绝对路径，否则 Claude Code 找不到文件。

重启 Claude Code，输入：

现在几点了？北京时间

Claude 会调用 get_current_time 工具，传入 timezone: "Asia/Shanghai"，返回当前时间。

预期结果：Claude 显示当前北京时间。

第五步：理解 MCP 服务器的生命周期

MCP 服务器不是一直运行的。Claude Code 在需要时启动它，用完后自动关闭。这意味着：

• 启动有延迟（几百毫秒到几秒）
• 不要在里面放需要长时间初始化的东西
• 状态不会跨会话保留（除非你自己写持久化）

如果你发现 MCP 服务器启动慢，检查它的 command 和 args——尽量用轻量级命令，不要用 npm run build 之类的。

第六步：调试 MCP 服务器

MCP 服务器跑在 stdio 上，调试起来有点麻烦。两个技巧：

技巧 1：查看日志

在 settings.json 里加 env 字段：

{
  "mcpServers": {
    "time-server": {
      "command": "node",
      "args": ["mcp-time-server.js"],
      "cwd": "/你的项目绝对路径",
      "env": {
        "DEBUG": "mcp:*"
      }
    }
  }
}

重启后，Claude Code 的输出面板会显示 MCP 的调试日志。

技巧 2：手动测试

用 echo 模拟 Claude Code 的请求：

echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | node mcp-time-server.js

应该输出：

{"jsonrpc":"2.0","id":1,"result":{"tools":[{"name":"get_current_time","description":"获取当前时间","inputSchema":{"type":"object","properties":{"timezone":{"type":"string","description":"时区，如 Asia/Shanghai"}}}}]}}

如果没输出或者报错，说明服务器代码有问题。

第七步：接入第三方 MCP 服务器

社区有很多现成的 MCP 服务器。我们接一个最常用的——@modelcontextprotocol/server-github，让 Claude 能操作 GitHub。

安装：

npx @modelcontextprotocol/server-github --help

配进 settings.json：

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "你的 GitHub Personal Access Token"
      }
    }
  }
}

Token 在 GitHub Settings → Developer settings → Personal access tokens 里生成，权限至少选 repo。

重启 Claude Code，输入：

列出我仓库 shanraisshan/claude-code-best-practice 最近 5 个 issue

Claude 会调用 GitHub MCP 的 list_issues 工具，返回结果。

注意：GitHub MCP 服务器功能很多——创建 issue、合并 PR、查看代码——但需要对应的 Token 权限。权限不够会报 403。

常见问题

Q：MCP 服务器启动失败，没有错误信息？

检查 command 是否在 PATH 里。用绝对路径试试：

{
  "command": "/usr/local/bin/npx",
  "args": ["@anthropic/mcp-server-demo"]
}

Q：多个 MCP 服务器冲突？

每个 MCP 服务器独立运行，工具名不能重复。如果两个服务器都暴露了 echo，Claude 会随机选一个调用。改工具名避免冲突。

Q：MCP 服务器返回的数据太大？

Claude 的上下文窗口有限。MCP 服务器返回的内容最好控制在几千字符以内。如果需要返回大量数据，分页返回。

实战：组合两个 MCP 服务器

我们让 Claude 同时用文件系统 MCP 和时间 MCP，完成一个实际任务。

先确保 settings.json 里有这两个 MCP 服务器：

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["@anthropic/mcp-server-filesystem", "--allowed-directories", "/tmp"]
    },
    "time-server": {
      "command": "node",
      "args": ["mcp-time-server.js"],
      "cwd": "/你的项目绝对路径"
    }
  }
}

重启 Claude Code，输入：

在 /tmp 目录下创建一个叫 report.txt 的文件，内容写上当前北京时间

Claude 会先调用时间 MCP 获取当前时间，再调用文件系统 MCP 创建文件。两步操作，一个指令。

预期结果：/tmp/report.txt 被创建，内容包含当前北京时间。

记住一点

MCP 服务器是 Claude 的"手"——它让 Claude 能触碰外部世界。但每多一个 MCP 服务器，就多一个攻击面。只接入你信任的 MCP 服务器，不要随便跑网上的 npx 命令。生产环境用 --allowed-directories 限制文件访问范围，用环境变量控制 Token 权限。

插件是什么，为什么需要它

前面几章你写了命令、技能、工作流，它们都藏在项目里的 .claude/ 目录下。换个项目想用，就得复制粘贴一遍。插件就是把这些东西打包成一个可分发、可安装的单元——别人跑一行命令就能装到你写的工具。

插件本质上是一个 .tgz 压缩包，里面包含 package.json 和 .claude/ 目录。装到目标项目后，Claude Code 会自动识别里面的命令、技能、钩子。

前置条件

• 已完成第 4-6 章，手头有一个能用的命令或技能
• 项目根目录下有 .claude/ 目录（没有的话先跑 claude init）
• 装了 Node.js 18+（打包用 npm pack）

第一步：准备插件目录结构

插件不要求特定目录名，但推荐按这个结构组织：

my-plugin/
├── package.json
└── .claude/
    ├── commands/
    │   └── hello.md
    └── skills/
        └── greet/
            └── SKILL.md

package.json 是插件的入口文件，Claude Code 靠它识别这是一个插件。

第二步：写 package.json

{
  "name": "@yourname/hello-plugin",
  "version": "1.0.0",
  "description": "一个打招呼的插件",
  "claude": {
    "commands": [".claude/commands/hello.md"],
    "skills": [".claude/skills/greet/SKILL.md"]
  }
}

关键字段是 claude，它告诉 Claude Code 这个插件提供了哪些能力。路径相对于 package.json 所在目录。

name 建议用 @scope/name 格式，避免和别人的插件重名。

第三步：把已有的命令/技能搬进来

假设你之前写过一个 /hello 命令，文件在项目 .claude/commands/hello.md：

# hello

向用户打招呼。

## Usage

`/hello [name]`

## Description

如果提供了 name，说"你好，{name}"；否则说"你好，世界"。

直接复制到 my-plugin/.claude/commands/hello.md。

技能同理，把 SKILL.md 和关联文件复制过来。

第四步：打包

cd my-plugin
npm pack

你会得到一个 yourname-hello-plugin-1.0.0.tgz 文件。这就是可分发的插件包。

第五步：安装到目标项目

在目标项目根目录执行：

claude plugins add ./path/to/yourname-hello-plugin-1.0.0.tgz

Claude Code 会把插件内容解压到项目的 .claude/plugins/ 目录下，并自动注册命令和技能。

验证安装：

claude plugins list

应该能看到 @yourname/hello-plugin 出现在列表里。

第六步：测试插件

在目标项目里启动 Claude Code：

claude

输入 /hello，应该能正常响应。如果没生效，检查 .claude/plugins/ 目录是否存在，以及 package.json 里的路径是否正确。

常见问题

安装后命令不出现

• 检查 package.json 里的路径，路径写错是最常见的原因
• 确认 claude 字段的格式正确，数组里每一项都是字符串路径

npm pack 报错

• 确保 package.json 有 name 和 version 字段
• 试试 npm pack --dry-run 看看会打包哪些文件，确认 .claude/ 目录被包含

插件更新后怎么升级

• 重新打包，然后在目标项目跑 claude plugins add ./新包.tgz，会覆盖旧版本

发布到市场

如果你想让别人也能搜到你的插件，可以发布到插件市场。

市场本质上是一个 Git 仓库，里面有一个 plugins.json 文件记录所有可用插件。Anthropic 官方维护了一个市场，你也可以自建。

发布到官方市场的流程：

1. 把插件包上传到 GitHub Releases 或 npm
2. 在市场的 plugins.json 里添加一条记录：

{
  "name": "@yourname/hello-plugin",
  "description": "一个打招呼的插件",
  "url": "https://github.com/yourname/hello-plugin/releases/download/v1.0.0/yourname-hello-plugin-1.0.0.tgz"
}

3. 提交 PR 到市场仓库

用户安装时只需要：

claude plugins add @yourname/hello-plugin

Claude Code 会自动从市场查找并下载。

自建市场

团队内部用，可以自己搭一个市场。创建一个 Git 仓库，根目录放 plugins.json，格式同上。用户安装时指定市场地址：

claude plugins add @team/internal-tool --market https://raw.githubusercontent.com/your-team/plugin-market/main/plugins.json

完整示例：把第 5 章的技能打包成插件

假设第 5 章你写了一个代码审查技能，目录结构是：

my-code-review-skill/
├── package.json
├── .claude/
│   └── skills/
│       └── code-review/
│           ├── SKILL.md
│           └── rules/
│               └── eslint-style.md

package.json：

{
  "name": "@team/code-review-skill",
  "version": "1.0.0",
  "description": "代码审查技能，检查 ESLint 风格问题",
  "claude": {
    "skills": [".claude/skills/code-review/SKILL.md"]
  }
}

打包：

npm pack

得到 team-code-review-skill-1.0.0.tgz，发给同事或上传到市场。

记住一点

插件只是把 .claude/ 目录打包，没有黑魔法。你之前写的命令、技能、工作流，放进插件结构就能直接分发。先在本机用 npm pack 测试，确认能用再考虑发布。

调校设置：让 Claude Code 按你的规矩干活

Claude Code 装好就能用，但默认配置不一定适合你的项目。权限太松可能乱改文件，模型选错可能浪费钱，输出太啰嗦浪费时间。本章教你改 .claude/settings.json，把工具调成趁手的状态。

前置条件

• 已完成第 2 章的安装和初始化
• 项目根目录下有 .claude/ 文件夹
• 如果还没有，先创建 settings 文件：

touch .claude/settings.json

1. 权限控制：别让 Claude 乱动东西

默认情况下 Claude Code 能读写项目里的所有文件。这在你盯着的时候没问题，但跑自动化任务时可能出事故。

打开 .claude/settings.json，写入：

{
  "permissions": {
    "allow": ["read", "write", "execute"],
    "deny": [],
    "allowPaths": ["src/", "tests/"],
    "denyPaths": [".env", "node_modules/", "dist/"]
  }
}

每项的作用：

• allow：允许的操作类型。read 读文件，write 写文件，execute 运行命令。删掉 execute 就禁止 Claude 跑任何 shell 命令。
• deny：明确禁止的操作。比如 ["execute"] 就彻底锁死命令执行。
• allowPaths：只允许操作这些路径下的文件。其他路径一律拒绝。
• denyPaths：禁止触碰的路径，优先级高于 allowPaths。

实战场景： 你接了个外包项目，只想让 Claude 改 src/ 里的代码，别碰 config/ 里的密钥。这么配：

{
  "permissions": {
    "allowPaths": ["src/"],
    "denyPaths": ["config/secrets.json", ".env"]
  }
}

常见报错： 如果 Claude 试图写一个不在 allowPaths 里的文件，会直接报 Permission denied。检查路径写对了没，相对路径是相对于项目根目录。

2. 模型配置：选对模型，省钱又省时间

Claude Code 默认用 Claude 3.5 Sonnet，但不同任务适合不同模型。改 model 字段：

{
  "model": {
    "model": "claude-sonnet-4-20250514",
    "maxTokens": 8192,
    "temperature": 0.3,
    "systemPrompt": "你是一个资深前端工程师，代码要简洁，注释用中文。"
  }
}

参数说明：

• model：模型 ID。可选值看官方文档，常用的是 claude-sonnet-4-20250514（平衡）和 claude-haiku-4-20250514（快速便宜）。
• maxTokens：每次回复的最大 token 数。设太小 Claude 会中途截断，设太大浪费钱。代码审查用 4096 够用，写大文件用 8192。
• temperature：0-1 之间的值。0 最确定（适合代码生成），1 最有创意（适合写文案）。代码任务建议 0.1-0.3。
• systemPrompt：系统提示词，覆盖默认行为。这里写你的角色和偏好。

省钱技巧： 跑单元测试、格式化代码这类简单任务，临时切到 Haiku：

claude --model claude-haiku-4-20250514

注意： maxTokens 设太大不会让模型输出更多，只是允许它输出更多。实际输出长度由任务决定。

3. 输出样式：让 Claude 闭嘴或者多说两句

Claude Code 默认输出很详细，每一步都解释。你也许只想看结果。改 outputStyle：

{
  "outputStyle": {
    "mode": "concise",
    "showProgress": false,
    "showToolUse": false
  }
}

三种模式：

• "verbose"：默认。每一步都解释，适合学习或调试。
• "concise"：只输出关键信息，省略解释性文字。
• "minimal"：只输出最终结果，不展示过程。

额外开关：

• showProgress：是否显示进度条和中间状态。false 就安静干活。
• showToolUse：是否显示 Claude 调用了什么工具。false 就只看到结果。

实战场景： 你在 CI 里跑 Claude Code，只想拿到最终输出，不要任何废话：

{
  "outputStyle": {
    "mode": "minimal",
    "showProgress": false,
    "showToolUse": false
  }
}

4. 沙箱：隔离危险操作

沙箱让 Claude 在隔离环境里运行命令，防止它搞坏你的系统。需要先装 Docker 或 Firecracker。

{
  "sandbox": {
    "enabled": true,
    "type": "docker",
    "image": "node:20-alpine",
    "memory": "512m",
    "timeout": 300
  }
}

参数说明：

• enabled：开/关沙箱。
• type："docker" 或 "firecracker"。Docker 更通用，Firecracker 更轻量。
• image：Docker 镜像。选你项目需要的环境。Node 项目用 node:20-alpine，Python 项目用 python:3.12-slim。
• memory：内存限制。设太小会 OOM，设太大浪费资源。
• timeout：单条命令超时时间（秒）。超过就杀掉。

先跑起来： 确保 Docker 在运行，然后测试：

claude -p "运行 ls 命令"

如果沙箱配置正确，你会看到命令在容器里执行，而不是本地。

常见报错： Docker is not running——启动 Docker Desktop 或 Docker daemon。Image not found——镜像名写错了，先 docker pull node:20-alpine 试试。

5. 完整配置示例

把上面所有配置合并成一个文件：

{
  "permissions": {
    "allow": ["read", "write", "execute"],
    "deny": [],
    "allowPaths": ["src/", "tests/"],
    "denyPaths": [".env", "node_modules/", "dist/"]
  },
  "model": {
    "model": "claude-sonnet-4-20250514",
    "maxTokens": 8192,
    "temperature": 0.2,
    "systemPrompt": "你是一个资深前端工程师，代码要简洁，注释用中文。"
  },
  "outputStyle": {
    "mode": "concise",
    "showProgress": false,
    "showToolUse": false
  },
  "sandbox": {
    "enabled": true,
    "type": "docker",
    "image": "node:20-alpine",
    "memory": "512m",
    "timeout": 300
  }
}

保存后重启 Claude Code，新配置立即生效。

6. 调试配置：确认当前生效的设置

不确定当前用了什么配置？运行：

claude settings

会打印当前生效的所有设置，包括从多个配置文件合并的结果。如果某个字段没生效，检查是不是有多个 settings.json 文件冲突了（项目级 > 用户级 > 全局）。

记住一点： 改完配置后，如果 Claude 行为没变，先确认文件语法正确（JSON 不能有注释和尾逗号），再重启 Claude Code。

为什么 Claude 记不住你上一轮说过的话

Claude Code 每次对话都是独立的。你关掉终端再打开，它不记得你昨天建了哪个模块、用了什么命名规范、项目有哪些特殊约定。这不是 Claude 笨，是设计如此——每次对话都是全新上下文。

但你可以给它装一个“外挂记忆”。用 CLAUDE.md 和 .claude/rules/ 两个文件，告诉 Claude：这个项目有什么规矩、你偏好什么风格、哪些事每次都要做。

前置条件

• 已完成第 2 章的项目初始化（项目根目录下有 .claude/ 文件夹）
• 有一个正在开发的项目（随便什么项目都行，空项目也可以）

第一步：创建项目级记忆文件

Claude Code 启动时，会自动读取项目根目录下的 CLAUDE.md。这个文件就是项目的“自我介绍”。

直接创建它：

touch CLAUDE.md

打开文件，写点项目基本信息：

# 项目名称：天气查询助手

## 技术栈
- Python 3.11+
- FastAPI
- SQLite

## 命名规范
- 函数名：snake_case
- 类名：PascalCase
- 常量：UPPER_SNAKE_CASE

## 项目结构
src/
  api/      - API 路由
  core/     - 核心业务逻辑
  models/   - 数据模型
  tests/    - 测试文件

## 常用命令
- 启动服务：uvicorn src.main:app --reload
- 运行测试：pytest
- 代码格式化：black .

保存。现在启动 Claude Code，问它“这个项目用什么框架”——它会直接回答 FastAPI，因为它读了 CLAUDE.md。

预期结果：Claude 能回答出你在 CLAUDE.md 里写的内容。

第二步：用规则文件组织更细粒度的记忆

CLAUDE.md 适合放项目级别的固定信息。但有些记忆是场景化的——比如“每次写 API 路由都要加错误处理”“测试文件必须用 pytest 的 fixture”。

这些放到 .claude/rules/ 目录下，按功能拆成多个文件。

创建规则目录：

mkdir -p .claude/rules

写一个 API 路由规则：

cat > .claude/rules/api-rules.md << 'EOF'
## API 路由规则

- 每个路由函数必须包含类型注解
- 返回格式统一为 {"code": 0, "data": ..., "message": "success"}
- 所有数据库操作放在 try/except 里，捕获 SQLAlchemyError
- 路由路径用复数名词：/users, /orders
EOF

再写一个测试规则：

cat > .claude/rules/testing-rules.md << 'EOF'
## 测试规则

- 每个模块对应一个 test_ 文件
- 使用 pytest fixture 管理数据库会话
- 测试函数命名：test_{功能}_{场景}_{预期结果}
- 覆盖率目标：核心逻辑 > 90%
EOF

预期结果：当你让 Claude 写一个新 API 路由时，它会自动遵循 api-rules.md 里的格式要求。

第三步：设置全局规则（所有项目共享）

有些规则你希望每个项目都生效——比如“代码里不要写死密码”“优先用 f-string 而不是 format()”。

这些放到用户主目录下的全局规则：

mkdir -p ~/.claude/rules

cat > ~/.claude/rules/global-security.md << 'EOF'
## 安全规则

- 密码、密钥、token 必须从环境变量读取
- 禁止在代码中硬编码任何凭据
- 日志中不能输出敏感信息
- 使用 .env 文件管理本地环境变量，但 .env 必须加入 .gitignore
EOF

预期结果：在任何项目里，只要涉及凭据，Claude 都会提示你从环境变量读取。

第四步：启用自动记忆（Auto Memory）

Claude Code 有个实验性功能——自动记忆。它会记录你在对话中强调过的事情，下次启动时自动加载。

启用方式：

claude --auto-memory

或者在 .claude/settings.json 里配置：

{
  "autoMemory": true
}

开启后，如果你在对话中说“记住，这个项目的数据库表名都用小写”，Claude 会把它记下来。下次启动项目时，它会自动应用这个规则。

注意：自动记忆还在 beta，偶尔会记错或漏记。重要规则还是手动写进 CLAUDE.md 或 rules/ 里更靠谱。

第五步：记忆的优先级与覆盖规则

多个记忆文件同时存在时，Claude 按这个顺序读取：

1. 全局规则 ~/.claude/rules/（优先级最低）
2. 项目规则 .claude/rules/（覆盖全局）
3. CLAUDE.md（覆盖规则文件）
4. 当前对话中的指令（优先级最高）

这意味着：如果你在 CLAUDE.md 里写了“使用 SQLite”，但在对话中说“这次用 PostgreSQL”，对话指令会覆盖文件里的设定。

常见问题

Q：Claude 不读我的 CLAUDE.md 怎么办？

检查文件名大小写。必须是 CLAUDE.md，全大写。claude.md 或 Claude.md 都不行。

Q：规则文件太多，Claude 会不会变慢？

会。每个规则文件都会增加上下文长度。建议控制在 5 个以内，每个文件不超过 50 行。太长的规则 Claude 会忽略后半段。

Q：自动记忆存到哪里了？

存在 ~/.claude/projects/<项目名>/memory/ 目录下。你可以直接编辑这些文件来修正 Claude 记错的内容。

Q：团队项目怎么统一记忆？

把 CLAUDE.md 和 .claude/rules/ 提交到 Git。所有成员 clone 后自动获得相同的记忆配置。

实战：给一个真实项目配置记忆

假设你接手了一个 Django 项目，代码风格混乱。你要让 Claude 记住三件事：

1. 项目用 Django 4.2 + PostgreSQL
2. 视图函数必须用类视图（Class-Based Views）
3. 所有模型必须包含 created_at 和 updated_at 字段

写 CLAUDE.md：

# Django CMS

## 技术栈
- Django 4.2
- PostgreSQL 15
- Django REST Framework

## 视图规范
- 所有视图使用类视图（ListView, DetailView, CreateView 等）
- 禁止使用函数视图

写 .claude/rules/models.md：

## 模型规则

- 每个模型必须包含：
  - created_at = DateTimeField(auto_now_add=True)
  - updated_at = DateTimeField(auto_now=True)
- 模型类名使用单数：Article, Comment
- 所有字段必须设置 verbose_name

现在让 Claude 创建一个新模型，它会自动加上时间戳字段，并且用单数命名。不需要你每次重复提醒。

下一步

记忆配置好了，Claude 不会每次问“这个项目用什么数据库”。但如果你改错了代码想回退怎么办？下一章讲检查点（Checkpointing），让你在 Claude 改坏代码时一键恢复到之前的状态。

检查点：让你的实验有后悔药

写代码最怕什么？改了一堆文件，跑起来全崩了，想回到半小时前的状态——发现回不去了。

Claude Code 的检查点（Checkpointing）就是干这个的。它自动记录你每次让 Claude 改文件之前的项目快照。改坏了？一条命令回到改之前。改了一半想换个思路？也能回去。

前置条件：你已经有一个用 Claude Code 操作过的项目（第 2 章做完就行）。不需要额外安装任何东西，检查点是内置的。

第一步：先看看检查点怎么工作的

打开终端，进到你的项目目录，启动 Claude Code：

cd your-project
claude

随便让 Claude 改个文件。比如：

把 README.md 里的第一行改成 "Hello Checkpoint"

Claude 会执行修改。注意看终端输出——每次它要改文件之前，你会看到一行类似这样的提示：

📸 Checkpoint saved

这就是在说：改之前我给你拍了张快照。

第二步：查看已有的检查点

改完几个文件后，输入：

/checkpoints

你会看到类似这样的列表：

Checkpoints:
  1. 2025-03-20 14:32:15 - "Edit README.md"
  2. 2025-03-20 14:28:03 - "Add new function to utils.py"
  3. 2025-03-20 14:22:41 - "Initial state"

每个检查点对应一次文件修改操作。时间戳加操作描述，一目了然。

第三步：回退到某个检查点

假设你刚改的 README 改坏了，想回到改之前的状态。找到对应的检查点编号（比如 1），执行：

/checkpoint 1

或者用更明确的写法：

/checkpoint restore 1

Claude 会问你是否确认回退。输入 y 确认。

预期结果：项目文件恢复到那个检查点时的状态。README.md 变回改之前的样子。

第四步：回退后继续工作

回退完，Claude 会告诉你当前状态。你可以接着让它做别的事。检查点不会因为回退而消失——你还能再次回退到其他点。

想看看回退后的效果？直接让 Claude 读一下文件：

cat README.md

确认内容确实回去了。

常见坑

坑 1：检查点只记录文件修改，不记录对话历史。 回退后，你和 Claude 的聊天记录不会清空。只是文件内容变了。这意味着你可以继续跟 Claude 讨论刚才的修改，然后让它再试一次。

坑 2：检查点只在当前会话中有效。 退出 Claude Code 再重新启动，之前的检查点就没了。如果你有重要的中间状态，建议手动用 git 提交。

坑 3：检查点数量有限。 默认保留最近 20 个检查点。超过之后最老的会被自动删除。如果你在做大量小修改，注意别把重要的覆盖了。

实用技巧

技巧 1：改大文件前先手动触发检查点 虽然 Claude 会自动保存，但如果你想在某个关键节点强制保存，可以输入：

/save

这会创建一个显式检查点，描述可以自己写。

技巧 2：用检查点做 A/B 测试 让 Claude 按方案 A 改代码，跑一下看看效果。不满意？回退到改之前，再让 Claude 按方案 B 改。不用手动备份文件，不用 git stash。

技巧 3：检查点 + git 双保险 检查点适合快速迭代，git 适合长期保存。我的习惯是：用 Claude Code 做实验时全靠检查点来回退，确定方案后再 git commit 保存。

小实战：用检查点安全重构

假设你有一个 utils.py，里面有个函数写得很难看。你想让 Claude 重构它，但又怕改坏了。

1. 先让 Claude 读一下当前代码：

cat utils.py

2. 让 Claude 重构：

重构 utils.py 里的 parse_data 函数，用更清晰的变量名，加上类型注解

Claude 改完，检查点自动保存。

3. 跑测试：

python -m pytest tests/test_utils.py

如果测试全过，完美。如果挂了：

4. 回退：

/checkpoint restore 1

5. 换个方式再试：

重构 parse_data 函数，只加类型注解，不改逻辑

这样反复试，直到满意为止。整个过程不需要手动备份任何文件。

什么时候别用检查点

• 你改了配置文件（比如 .claude/settings.json）——检查点不会回退这些
• 你删除了文件——检查点不会恢复被删的文件
• 你改了项目外的文件——检查点只跟踪项目目录内的变化

这些情况还是靠 git 靠谱。

检查点不是什么黑科技，就是给你一个快速反悔的按钮。每次让 Claude 改文件前自动拍张照，改坏了直接倒带。就这么简单。

让我们直接进入进阶技巧的世界。要使用 Ultrareview、Ultraplan、Auto Mode 和无闪烁模式，你需要先确保你的 Claude Code 项目已经正确设置并运行。

前置条件

• 你已经安装并初始化了 Claude Code 项目。
• 你对 Claude Code 的基本操作有所了解。

Ultrareview

直接运行以下命令来启用 Ultrareview：

claude ultrareview [target]

这将开启一个超级代码审查模式，帮助你高效地审查和管理代码。

Ultraplan

使用 Ultraplan 来规划你的项目：

/ultraplan

这会启动一个交互式的规划工具，帮助你组织和管理项目任务。

Auto Mode

启用 Auto Mode 来自动化你的工作流：

--permission-mode auto

或者使用快捷键 Shift+Tab 来切换 Auto Mode。这种模式可以帮助你减少手动输入的工作量。

无闪烁模式

要启用无闪烁模式，可以使用以下命令：

/tui fullscreen

或者设置环境变量 CLAUDE_CODE_NO_FLICKER=1。这将帮助你获得更流畅的用户体验。

实用技巧

• 在使用这些进阶技巧时，记得检查 Claude Code 的版本是否是最新的，以确保你能够使用到所有的功能。
• 如果你遇到任何问题，可以参考 Claude Code 的官方文档或社区论坛来寻找解决方案。

通过这些进阶技巧，你将能够更高效、更智能地使用 Claude Code 来管理你的项目和工作流。记住一点，实践是关键，直接去试验和探索这些功能吧！

我们要从零开始搭建一个带记忆与工具的智能助手。首先，确保你已经安装并初始化了 Claude Code 项目。

步骤 1：创建新项目

claude init my-assistant

这将创建一个名为 my-assistant 的新项目。

步骤 2：定义子代理

创建一个名为 memory-agent 的子代理，用于管理记忆：

claude agent create memory-agent

这将创建一个新的子代理文件 memory-agent.md。

步骤 3：定义命令

创建一个名为 remember 的命令，用于存储记忆：

claude command create remember

这将创建一个新的命令文件 remember.md。

步骤 4：定义技能

创建一个名为 memory-skill 的技能，用于管理记忆：

claude skill create memory-skill

这将创建一个新的技能文件夹 memory-skill。

步骤 5：定义工作流

创建一个名为 memory-workflow 的工作流，用于串联多个子代理：

claude workflow create memory-workflow

这将创建一个新的工作流文件 memory-workflow.md。

步骤 6：配置记忆

在 CLAUDE.md 文件中配置记忆设置：

# 记忆设置
memory:
  enabled: true
  path: ~/.claude/memory

这将启用记忆功能并设置记忆存储路径。

步骤 7：运行智能助手

运行智能助手：

claude run my-assistant

这将启动智能助手，并使其能够存储和检索记忆。

如果你遇到任何错误，可以检查 Claude Code 日志文件以获取更多信息。同时，记得定期备份你的记忆数据，以防止数据丢失。

现在，你已经成功搭建了一个带记忆与工具的智能助手。下一步，你可以尝试扩展智能助手的功能，例如添加更多的子代理、命令和技能。

常见问题（FAQ）

1. 安装后运行 claude 命令提示“command not found”，怎么办？

确保 Claude Code CLI 已正确安装并添加到 PATH。通常通过 npm install -g @anthropic-ai/claude-code 安装。如果仍找不到命令，尝试：

# 检查全局安装位置
npm list -g --depth=0

# 手动添加 PATH（以 macOS/Linux 为例）
export PATH="$PATH:$(npm bin -g)"

或将上述 export 添加到 ~/.zshrc 或 ~/.bashrc。

---

2. 如何配置项目级别的自定义指令和规则？

Claude Code 支持多种配置方式，优先级从高到低：

• 项目规则：.claude/rules/ 目录下的 .md 文件
• 项目记忆：项目根目录的 CLAUDE.md 文件
• 全局规则：~/.claude/rules/ 目录
• 全局记忆：~/.claude/projects/<project>/memory/ 目录

推荐在项目根目录创建 CLAUDE.md，写入项目背景、编码规范、架构说明等。Claude 会自动读取并记住这些信息。

---

3. Subagent、Command、Skill 有什么区别？何时用哪个？

特性	Subagent	Command	Skill
位置	.claude/agents/	.claude/commands/	.claude/skills/
触发方式	自动/手动分配任务	/命令名 斜杠命令	自动注入上下文
典型用途	独立执行复杂任务	快速执行固定流程	提供领域知识/工具

简单判断：

• 需要 Claude 自主调用 → Subagent
• 你想手动触发一个固定流程 → Command
• 想让 Claude 始终具备某领域能力 → Skill

---

4. 为什么 Claude 不记得之前的对话内容？如何启用记忆功能？

Claude Code 默认不保留跨会话记忆。要启用：

1. 项目记忆：在项目根目录创建 CLAUDE.md，写入需要持久化的信息
2. 自动记忆：在 .claude/settings.json 中启用：

   {
     "memory": {
       "auto": true
     }
   }

3. 手动记忆：使用 /remember 命令让 Claude 记录当前重要信息

记忆存储在 ~/.claude/projects/<project>/memory/ 目录下。

---

5. 如何让 Claude 自动执行任务而不需要每次都确认？

使用 Auto Mode（Beta 功能）：

# 启动时启用
claude --permission-mode auto

# 运行时切换
# 按 Shift+Tab 切换模式

Auto Mode 下 Claude 会自动执行文件读写、命令运行等操作，无需逐条确认。适合批量处理、自动化重构等场景。

注意：建议先在安全环境中测试，避免意外修改。

---

6. 如何集成外部工具（如数据库、API）到 Claude Code？

通过 MCP Servers（Model Context Protocol）集成：

1. 创建或安装 MCP Server（如 @anthropic/mcp-server-postgres）
2. 在 .claude/settings.json 或 .mcp.json 中配置：

   {
     "mcpServers": {
       "my-db": {
         "command": "npx",
         "args": ["@anthropic/mcp-server-postgres", "postgresql://user:pass@localhost/db"]
       }
     }
   }

3. 重启 Claude Code，即可让 Claude 直接查询数据库或调用外部 API

---

7. 与 GitHub Copilot、Cursor 等工具相比，Claude Code 有什么独特优势？

维度	Claude Code	GitHub Copilot	Cursor
核心能力	全栈 Agent	代码补全	编辑器集成
多文件编辑	✅ 原生支持	❌ 单文件为主	✅ 支持
命令行操作	✅ 可执行命令	❌	❌
子代理协作	✅ Subagent	❌	❌
自定义工作流	✅ Command/Skill	❌	有限
记忆系统	✅ 多层级记忆	❌	有限

总结：Claude Code 更适合需要自主执行复杂任务、多文件重构、集成外部工具的场景；Copilot 更适合快速代码补全；Cursor 在编辑器体验上更优。

---

8. 如何调试 Subagent 或 Command 不生效的问题？

按以下步骤排查：

1. 检查文件位置：确保文件在正确的目录下（.claude/agents/、.claude/commands/）
2. 检查文件格式：必须是 .md 文件，内容以 Markdown 编写
3. 检查文件名：Command 文件名（不含扩展名）即命令名，如 test.md 对应 /test
4. 检查权限：确保 Claude 有读取权限
5. 查看日志：运行 claude --verbose 查看详细日志
6. 重启 Claude：配置修改后需重启会话

如果仍不生效，尝试在 .claude/settings.json 中显式启用：

{
  "agents": { "enabled": true },
  "commands": { "enabled": true }
}