Claude Code 使用指南

Claude Code 的执行机制、命令语义、上下文控制、以及 Superpower 的用法。

一、Claude Code 的本质：一个"可执行的 AI Agent"

很多人把 Claude Code 当 CLI 聊天工具，这是误解。

它本质是一个具备以下能力的 Agent：

上下文感知（Context-aware）
文件系统操作（Read / Write / Patch）
命令执行（Shell / Build / Test）
多步推理（Plan → Execute → Verify）

你发出的不是"问题"，而是任务指令（Task Instruction）

二、命令体系的底层逻辑

Claude Code 的命令可以分为 4 层：

层级	类型	作用
L1	上下文控制	/read /project
L2	修改操作	/edit /write
L3	行为控制	/plan /ask
L4	执行验证	/run /diff /review

三、核心命令详解

1️⃣ 上下文控制类

🔹 /read ------ 精准上下文注入

复制代码

/read internal/service/user_service.go

机制：

将文件内容注入上下文窗口
提升语义理解准确性
降低 hallucination（幻觉）

工程实践：

❌ 错误：

复制代码

帮我改 userService

✅ 正确：

复制代码

/read internal/service/user_service.go
/edit user_service.go

🔹 /project ------ 全局上下文加载

复制代码

/project .

行为：

扫描目录结构
建立文件索引（不是全部加载）
按需动态读取

注意：

并不是把整个项目塞进上下文（会爆 token）
而是建立"引用能力"

类似：

IDE 的 "Go to Definition" + "全局索引"

🔹 /search ------ 语义级搜索

复制代码

/search "OrderService"

区别于 grep：

理解语义（不仅是字符串匹配）
能定位接口实现、调用链

2️⃣ 修改操作类

🔹 /edit ------ AST 级局部修改（核心）

复制代码

/edit user_service.go

输入：

复制代码

为所有数据库操作增加 context 超时控制（2s）

底层行为：

分析 AST（抽象语法树）
定位目标函数
局部 patch，而非全文覆盖

优势：

保持代码结构
减少误修改
更安全

🔹 /write ------ 全量重写（高风险）

复制代码

/write main.go

适用于：

新文件
原型生成
小文件

❗ 风险：

覆盖全部内容
可能丢失逻辑

90% 场景用 /edit，不要滥用 /write

3️⃣ 行为控制类

🔹 /plan ------ 显式推理

复制代码

/plan 为博客系统设计评论模块

输出：

数据结构
API 设计
依赖关系
实现步骤

作用：

强制 AI 先思考再行动
避免"直接乱写代码"

🔹 /ask ------ 限制为"只回答"

复制代码

/ask 为什么这里会出现 goroutine 泄漏？

用于：

Debug 分析
原理解释
不希望修改代码

4️⃣ 执行与验证类

🔹 /run ------ 执行命令（反馈驱动）

复制代码

/run go build ./...

或：

复制代码

/run go test ./...

Claude 会：

执行命令
解析输出
自动修复错误（如果你继续指令）

这是实现 自修复循环（Self-healing loop） 的基础

🔹 /diff ------ 差异检查

复制代码

/diff

👉 输出：

修改前后对比
精确到行级

工程规范建议：

任何 AI 修改，必须先 diff 再提交

🔹 /review ------ 静态分析 + 规范检查

复制代码

/review

能力：

Code smell
潜在 bug
不规范命名
并发问题

四、Superpower：从"工具"到"自动执行系统"

1️⃣ Superpower 的执行模型

标准循环：

复制代码

Plan → Act → Observe → Reflect → Repeat

展开：

规划任务
修改代码
执行测试
分析结果
再次修复

本质：一个简化版 AutoGPT / Agent Loop

2️⃣ Superpower 触发方式

不是一个"命令"，而是一种指令风格：

复制代码

修复当前项目所有编译错误，并确保测试通过

或：

复制代码

为项目添加 JWT 鉴权，并保证现有接口不受影响

3️⃣ 典型工程场景

场景一：编译失败自动修复

复制代码

运行 go build，如果失败就自动修复，直到成功

Claude 行为：

/run build
解析错误
/edit 修复
重复

场景二：大规模重构

复制代码

将项目从单体结构改为 controller/service/repository 分层

涉及：

文件拆分
依赖重构
import 修改

场景三：引入新中间件

复制代码

为所有 HTTP 接口增加日志中间件（zap）

它会：

找路由入口
插入 middleware
修改初始化逻辑

场景四：性能优化

复制代码

分析项目中所有数据库查询，减少 N+1 问题

高级能力：

跨文件分析
调整调用方式

五、Superpower 使用约束

1️⃣ 明确边界（必须）

复制代码

不要修改 API 返回结构
不要改数据库 schema

2️⃣ 控制范围

❌：

复制代码

优化整个项目

✅：

复制代码

只优化 user_service.go 中的数据库访问逻辑

3️⃣ 强制验证

复制代码

修改后必须通过 go test ./...

4️⃣ 分阶段执行（工程级）

复制代码

Step1: 重构 service
Step2: 运行测试
Step3: 修复错误

六、高级用法：构建"AI 开发流水线"

标准工作流（推荐）

复制代码

/project .

/plan 实现文章发布功能

/read article_service.go

/edit article_service.go

/diff

/run go test ./...

/review

然后：

复制代码

根据 review 结果自动修复问题

自动化闭环（高阶）

复制代码

实现文章点赞功能：
1. 写代码
2. 写测试
3. 运行测试
4. 修复直到通过

七、常见失败原因（真实工程问题）

❌ 上下文不足

→ AI 改错文件

❌ 指令不约束

→ 改崩接口

❌ 不看 diff

→ 引入隐蔽 bug

❌ 一步做太多

→ 无法 debug

八、结论（工程视角总结）

Claude Code 的能力可以抽象为：

代码理解 + 文件操作 + 命令执行 + 多步推理

而你的任务是：

👉 控制它，而不是使用它

最后的建议

如果你想真正拉开差距：

所有操作先 /plan
所有修改用 /edit
所有结果看 /diff
所有问题用 /run 验证
所有复杂任务用 Superpower 分阶段执行