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 会：

1. 执行命令

2. 解析输出

3. 自动修复错误（如果你继续指令）

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

---

🔹 /diff —— 差异检查

/diff

👉 输出：

• 修改前后对比

• 精确到行级

工程规范建议：

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

---

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

/review

能力：

• Code smell

• 潜在 bug

• 不规范命名

• 并发问题

---

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

---

1️⃣ Superpower 的执行模型

标准循环：

Plan → Act → Observe → Reflect → Repeat

展开：

1. 规划任务

2. 修改代码

3. 执行测试

4. 分析结果

5. 再次修复

本质：一个简化版 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 的能力可以抽象为：

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

而你的任务是：

👉 控制它，而不是使用它

---

最后的建议

如果你想真正拉开差距：

1. 所有操作先 /plan

2. 所有修改用 /edit

3. 所有结果看 /diff

4. 所有问题用 /run 验证

5. 所有复杂任务用 Superpower 分阶段执行