Claude Code 高效用法 — 完整手册

解决一个核心问题：如何减少"一问一答"的低效循环，让 Agent 一次做对事。

一、为什么聊天效率低

默认行为的问题

你：帮我修这个 Bug
        ↓
Agent 扫一眼代码 → *猜*一个原因 → 直接改
        ↓
     改错了
        ↓
你：不对，是 xxx 的原因
        ↓
Agent 又 *猜*一个 → 又改
        ↓
     还是不对
        ↓
... 来回 3-5 轮

根因：Agent 没有花那 30 秒先彻底搞懂问题就动手了。 "猜 → 改 → 错 → 再猜" 的循环。

解决方案：先出计划，再执行

你：帮我修这个 Bug
        ↓
Agent 先输出一个排查计划（用 systematic-debugging skill）
        ↓
你扫一眼计划 → "方向不对，先检查日志"
        ↓
Agent 修正计划
        ↓
你确认 → Agent 按计划执行 → 一次到位

从"改代码 3-5 次"变成"改计划 1 次 + 执行 1 次"。计划是文本，改起来 5 秒；代码改错了要回滚重来。

二、强制规则：写在 CLAUDE.md 里

在项目根目录 CLAUDE.md 写入：

## 效率规则（强制）

遇到以下情况，**必须先输出计划/方案，确认后再执行**：

1. **修 Bug** → 先用 `systematic-debugging` 输出排查步骤
   - 定位根因 → 确认 → 修复
2. **加功能** → 先用 `writing-plans` 输出实现方案
   - 方案 A / 方案 B / 方案 C → 确认用哪个 → 实现
3. **重构** → 先用 `brainstorming` 或 `writing-plans` 输出方案
   - 涉及哪些文件、不改哪些、分几步、怎么验证
4. **复杂变更** → 用 `writing-plans` + `executing-plans`

未经确认就动手改代码 → 驳回。

实际对话效果

加上这条规则后：

你：战斗系统退出战斗时有 Bug
    ↓
Agent：好的，让我用 systematic-debugging 排查。

排查计划：
1. 检查 B_SEND(fid=14) 发送的结束战斗指令格式
2. 检查服务端 BU 消息的处理
3. 检查客户端 Battle 状态机是否在等待超时

你看这个方向对吗？
    ↓
你：先查第 3 项，我怀疑是状态机没重置
    ↓
Agent：好，直接检查 Battle.ts → 找到问题 → 一次修好

总对话轮数：3 轮（确认计划 1 轮 + 确认修正 1 轮 + 执行结果 1 轮） 没有规则时：5-8 轮（猜→改→错→再猜→再改...）

三、并行工作：run_in_background

什么时候用

场景	效果
你在改 A 文件，让后台去查 B 文件的 Bug	省掉等你改完 A 再查 B 的时间
你在调 UI，让后台去跑测试	不用在那干等测试跑完
你在写客户端，让后台去看服务端代码	两边同时推进

怎么用

不需要记任何语法，说人话就行：

帮我在后台检查一下 Nacos 上的接口契约和 server/mock.js 有没有对齐
查完了告诉我

Claude 会自己决定要不要在后台跑。

内部原理（不用记，了解即可）

Claude Code 会调用 Agent 工具，设置 run_in_background: true，启动一个独立的子会话。子会话有自己的上下文窗口，不占用你当前会话的 token。做完后通知你。

进阶：Worktree 隔离

如果后台任务也要改代码，用 worktree 隔离，互不干扰：

在后台帮我做一个独立的分支实现登录接口，跟我当前改的代码不冲突

四、后台持续监听：Monitor

不是所有场景都要后台 Agent 跑一遍就结束。有些场景需要持续监控：

# 场景：正在构建项目，你想知道什么时候完成
Monitor(
  command="npm run build 2>&1 | tail -f",
  description="等待构建完成"
)

Monitor vs run_in_background	Monitor	run_in_background
做一次就结束	❌	✅
持续监听变化	✅	❌
每有一条新输出就通知	✅	❌
例	等构建完成、等测试跑完、等服务器启动	去查一个 Bug、去改一个文件

五、Task 跟踪列表

Claude Code 内置了任务列表功能，让你看到当前在做什么：

TaskCreate("修复登录 Bug")         # 创建一个任务
TaskList()                         # 查看所有任务
TaskUpdate(taskId, status="done")  # 标记完成
TaskStop(taskId)                   # 终止任务

和 Kanban/Nacos 的关系

如果你需要：                        用：
────────────────────────────────────────────────
当前会话内跟踪进度 → TaskCreate
跨会话任务跟踪     → Hermes Kanban / Nacos 配置
跨机器任务协调     → Nacos 通知（sa-notify）

六、CLAUDE.md 最佳实践

必须包含的内容

## 📋 项目信息
- 技术栈、构建工具、目录结构

## 🎯 开发工作流
- 每次任务自动执行：改代码 → 跑测试 → lint → 提交

## 🧰 Skills 映射表
- 什么场景用什么 skill（方便 Agent 匹配）

## 📝 行为约定
- 每次开始先说用了什么 skills
- 修改前先读
- 不随意删除

## ⚡ 效率规则
- 先计划再执行（上面写的强制规则）

## ✅ 检查清单
- 测试通过了？lint 过了？提交了？

跨 Agent 共享

你机器上有 10 个 Agent。想让所有 Agent 读同一套规则：

# Claude Code 读 CLAUDE.md
# Codex 读 AGENTS.md
# Cline 读 .clinerules

# 全部指向同一个文件
ln -sf CLAUDE.md AGENTS.md       # Codex 用

已经通过 nacos-cli skill-sync 做好了的配置：

Claude Code: 191 skills
Codex: 191 skills（含 AGENTS.md symlink）
Cursor / OpenClaw / Hermes / 其他: 同步完成

Claude Code 常用高效用法