Claude Code 工程化实践：Hooks、Commands 与 Agents 协同激活技能

数据验证： 经过两周的实际使用统计，开发类任务的技能激活率从约 25% 提升到 90% 以上，提升了 3.6 倍。

为什么是 90% 而不是 100%？

因为我们设计了一个'逃生通道'：当用户输入的是斜杠命令（如 /dev、/crud）时，钩子会跳过评估，直接执行命令逻辑。

// 检测斜杠命令，跳过技能评估
const isSlashCommand = /^\/[^\/\s]+$/.test(prompt.split(/\s/)[0]);
if(isSlashCommand){
    process.exit(0); // 跳过
}

这样既保证了常规问答的技能激活率，又不干扰命令的执行效率。

Hooks 全景：四个生命周期钩子

除了核心的 skill-forced-eval.js，我们还设计了另外三个钩子，覆盖 AI 工作的完整生命周期。

3.1 SessionStart：开工先看项目状态

触发时机：每次启动 Claude Code 会话时

核心功能：

• 显示当前 Git 分支和未提交变更
• 加载项目待办事项
• 展示快捷命令菜单

实际效果：

## 🚀 RuoYi-Plus-Uniapp 会话已启动
**时间**: 2024/12/23 14:14:36
**Git 分支**: `master`
⚠️ **未提交变更** (5 个文件):
M plus-ui/src/views/user/index.vue
M ruoyi-modules/.../UserService.java
📋 **待办事项**: 3 未完成 / 12 已完成
💡 **快捷命令**:
| /dev | 开发新功能 |
| /crud | 快速生成 CRUD |
| /check| 代码规范检查 |

价值：让 AI 在开始工作前，先了解项目的当前状态，避免'两眼一抹黑'。

3.2 UserPromptSubmit：强制技能评估（核心）

这就是前面详细讲解的 skill-forced-eval.js，不再赘述。

3.3 PreToolUse：安全防护层

触发时机：AI 执行 Bash 命令或写入文件之前

核心功能：

• 拦截危险命令（rm -rf /、drop database、format）
• 警告敏感操作（删除文件、修改系统配置）
• 阻止运行未经授权的脚本

代码示例：

// 危险命令黑名单
const dangerousPatterns = [
    /rm\s+(-rf?|--recursive).*\//, // rm -rf
    /drop\s+(database|table)/i, // SQL 删库
    /format\s+[a-z]:/i, // 格式化磁盘
    />\s*\/dev\/sda/, // 写入磁盘设备
];
// 检测到危险命令，直接阻止
if(dangerousPatterns.some(p=> p.test(command))){
    console.log(JSON.stringify({decision:"block",reason:"检测到危险命令，已阻止执行"}));
    process.exit(0);
}

价值：防止 AI 因为'理解偏差'执行灾难性操作。我们实际遇到过 AI 试图用 rm -rf 清理临时文件的情况，幸好被这个钩子拦截了。

3.4 Stop：总结反馈 + 下一步建议

触发时机：AI 完成回答后

核心功能：

• 播放完成音效（提醒用户）
• 分析本次代码变更类型
• 智能推荐下一步操作
• 清理临时文件（如 Windows 下误创建的 nul 文件）

实际效果：

--- ✅ **任务完成** | 检测到 8 个文件变更
**建议操作**:
- 使用 `@code-reviewer` 审查后端代码
- 新增了 Service，记得更新项目文档
- SQL 文件有变更，确保更新所有数据库脚本
**项目管理**:
- `/update-status` 更新项目状态
- `git add . && git commit -m "feat: xxx"` 提交代码

价值：每次任务结束后给出明确的'收尾指引'，避免遗漏重要步骤。

四个钩子的协同工作流

┌─────────────────────────────────────────────────────────┐
│ 用户启动会话                                            │
└─────────────────────────────────────────────────────────┘
↓
┌────────────────────────┐
│ [Hook] SessionStart    │
│ 展示项目状态、待办事项 │
└────────────────────────┘
↓
┌─────────────────────────────────────────────────────────┐
│ 用户提问                                                │
└─────────────────────────────────────────────────────────┘
↓
┌────────────────────────┐
│ [Hook] UserPromptSubmit│
│ 强制评估 26 个技能       │
│ 激活率 25% → 90%+      │
└────────────────────────┘
↓
┌────────────────────────┐
│ AI 开始执行任务         │
│ （调用工具、写代码）   │
└────────────────────────┘
↓
┌────────────────────────┐
│ [Hook] PreToolUse      │
│ 拦截危险命令            │
│ 警告敏感操作            │
└────────────────────────┘
↓
┌────────────────────────┐
│ AI 完成回答             │
└────────────────────────┘
↓
┌────────────────────────┐
│ [Hook] Stop            │
│ 播放音效、分析变更      │
│ 推荐下一步操作          │
└────────────────────────┘

Skills：被激活的知识库

有了钩子保证'激活率'，接下来的问题是：被激活的技能里面有什么？

4.1 技能分类

我们设计了 26 个专业技能，覆盖开发的各个领域：

4.2 SKILL.md 的结构设计

每个技能都有一个 SKILL.md 文件，遵循统一的结构：

# [技能名称]
## 触发条件
- 关键词：xxx、xxx、xxx
- 场景：当用户需要 xxx 时
## 核心规范
### 规范 1：xxx（详细说明 + 代码示例）
### 规范 2：xxx（详细说明 + 代码示例）
## 禁止事项
- ❌ 禁止 xxx
- ❌ 禁止 xxx
## 参考代码
- 文件路径：`xxx/xxx.java`
- 文件路径：`xxx/xxx.vue`
## 检查清单
- [ ] 是否遵循 xxx
- [ ] 是否使用 xxx

4.3 示例：crud-development 技能

以最常用的 crud-development 技能为例：

# CRUD 开发技能
## 触发条件
- 关键词：CRUD、增删改查、业务模块、Entity、Service、DAO
- 场景：开发新的业务功能模块
## 核心规范
### 四层架构 Controller → Service（不继承）→ DAO（buildQueryWrapper）→ Mapper
### Entity 规范
- 必须继承 TenantEntity
- 主键使用雪花 ID，不用自增
### Service 规范
- 禁止继承 ServiceImpl
- 禁止在 Service 层构建查询条件
- 对象转换必须用 MapstructUtils.convert()
### DAO 规范
- 查询条件必须在 buildQueryWrapper() 中构建
- String 类型用 like()，其他类型用 likeCast()
## 禁止事项
- ❌ Service 继承 ServiceImpl
- ❌ 使用 BeanUtil.copyProperties()
- ❌ Controller 使用通用路径如 /page、/{id}
## 参考代码
- Entity: `ruoyi-modules/.../domain/Ad.java`
- Service: `ruoyi-modules/.../service/impl/AdServiceImpl.java`
- DAO: `ruoyi-modules/.../dao/impl/AdDaoImpl.java`

价值：当 AI 被激活这个技能后，它会先'学习'这些规范，然后再生成代码。这就像给 AI 发了一本'岗位手册'，而且强制它在开工前必须阅读。

Commands：复杂流程的编排器

Skills 解决的是'知识储备'问题，而 Commands（斜杠命令）解决的是'流程编排'问题。

5.1 /dev：7 步智能开发流程

当用户输入 /dev 开发用户管理功能 时，AI 会按照预设的 7 个步骤执行：

步骤 1：需求澄清 - AI 主动询问功能细节 - 确认业务规则和边界条件
步骤 2：技术设计 - 确定涉及的数据库表 - 设计 API 接口 - 规划前端页面
步骤 3：数据库设计 - 生成建表 SQL - 配置数据字典 - 插入菜单数据
步骤 4：后端开发 - 按四层架构生成代码 - Entity → BO/VO → DAO → Service → Controller
步骤 5：前端开发 - 生成 API 定义 - 生成页面组件 - 配置路由和权限
步骤 6：测试验证 - 启动服务 - 执行功能测试
步骤 7：文档更新 - 更新项目进度 - 记录待办事项

价值：把'最佳实践'固化成可重复执行的流程，确保每次开发都遵循相同的标准。

5.2 /crud：一键生成四层架构代码

/crud 是使用频率最高的命令。它能从现有数据库表，一键生成完整的四层架构代码：

输入：/crud b_coupon
输出：
✅ 生成 Entity: Coupon.java
✅ 生成 BO: CouponBo.java
✅ 生成 VO: CouponVo.java
✅ 生成 DAO: ICouponDao.java / CouponDaoImpl.java
✅ 生成 Service: ICouponService.java / CouponServiceImpl.java
✅ 生成 Controller: CouponController.java
✅ 生成 Mapper: CouponMapper.java
✅ 生成前端 API: couponApi.ts / couponTypes.ts
✅ 生成前端页面：coupon.vue

效率对比：

• 手动开发：2-4 小时
• 使用 /crud：5-10 分钟

5.3 /check：全栈代码规范检查

输入：/check
输出：
## 后端检查
✅ Entity 继承 TenantEntity
✅ Service 未继承 ServiceImpl
⚠️ UserDao.java:45 - 建议使用 likeCast() 替代 like()
## 前端检查
✅ 使用 AFormInput 替代 el-input
⚠️ user.vue:23 - 建议使用 AModal 替代 el-dialog
## 移动端检查
✅ 使用 wd-form 组件
✅ useToast 从 @/wd 导入

5.4 命令与技能的关系

命令和技能不是孤立的，它们相互配合：

/dev 命令执行时：
├── 步骤 3（数据库设计）→ 激活 database-ops 技能
├── 步骤 4（后端开发）→ 激活 crud-development 技能
└── 步骤 5（前端开发）→ 激活 ui-pc 技能

命令是流程的骨架，技能是填充的血肉。

Agents：并行处理的子任务专家

有些任务比较独立，不需要在主对话中处理，这时候就可以派发给 Agent（代理）。

6.1 code-reviewer：自动代码审查

触发方式：

• 完成代码编写后自动触发
• 手动调用 @code-reviewer

审查内容：

## 后端审查清单
- [ ] Entity 是否继承 TenantEntity
- [ ] Service 是否禁止继承 ServiceImpl
- [ ] DAO 是否实现 buildQueryWrapper
- [ ] Controller 路径是否包含实体名
- [ ] 是否使用 MapstructUtils 转换对象
## 前端审查清单
- [ ] 是否使用 A* 封装组件
- [ ] API 调用是否使用 [err, data] 格式
- [ ] 是否存在 el-* 原生组件
## 移动端审查清单
- [ ] 是否使用 wd-* 组件
- [ ] useToast 是否从 @/wd 导入
- [ ] 样式单位是否使用 rpx

6.2 project-manager：项目进度管理

触发方式：

• 手动调用 @project-manager
• 通过 /update-status 命令

核心功能：

• 维护 docs/项目状态.md
• 更新 docs/待办清单.md
• 统计开发进度

6.3 代理的工作模式

主对话              代理
│                    │
│ "帮我审查刚写的代码"
│ ─────────────────────────→
│                    │
│ [code-reviewer 启动]
│ 读取变更文件
│ 逐项检查规范
│ 生成审查报告
│ ←─────────────────────────
│ 收到审查报告
│                    │
│ [继续主对话]

价值：代理可以并行处理，不阻塞主对话。你可以一边让 AI 继续开发下一个功能，一边让代理审查上一个功能的代码。

协同架构：完整工作流

现在，让我们把所有组件串联起来，看看它们是如何协同工作的：

┌─────────────────────────────────────────────────────────────────┐
│ .claude 目录                                                    │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│ ┌─────────────┐                                                 │
│ │settings.json│ ← 核心配置：定义钩子、权限、MCP 服务器           │
│ └──────┬──────┘                                                 │
│        │                                                         │
│        ▼                                                         │
│ ┌─────────────────────────────────────────────────────────┐     │
│ │ hooks/ (钩子层)                                          │     │
│ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐     │     │
│ │ │session-start │ │skill-forced- │ │pre-tool-use │     │     │
│ │ │.js           │ │eval.js       │ │.js           │     │     │
│ │ │项目状态感知  │ │技能激活率    │ │安全防护      │     │     │
│ │ │              │ │25%→90%+      │ │              │     │     │
│ │ └──────────────┘ └──────────────┘ └──────────────┘     │     │
│ │ ┌──────────────┐                                         │     │
│ │ │stop.js       │                                         │     │
│ │ │总结反馈      │                                         │     │
│ │ └──────────────┘                                         │     │
│ └─────────────────────────────────────────────────────────┘     │
│                                                                 │
│        ▼                                                         │
│ ┌─────────────────────────────────────────────────────────┐     │
│ │ skills/ (技能层)                                         │     │
│ │ ┌──────────────┐                                         │     │
│ │ │crud-development│ api-development database-ops         │     │
│ │ │ui-pc          │ ui-mobile payment-...                 │     │
│ │ │security-guard │ performance-... ...（共 26 个）         │     │
│ │ └──────────────┘                                         │     │
│ └─────────────────────────────────────────────────────────┘     │
│                                                                 │
│        ▼                                                         │
│ ┌─────────────────────────────────────────────────────────┐     │
│ │ commands/ (命令层)                                       │     │
│ │ ┌──────────────┐                                         │     │
│ │ │/dev (7 步开发) /crud (代码生成) /check (规范检查)     │     │
│ │ │/init-docs /progress /add-todo                        │     │
│ │ └──────────────┘                                         │     │
│ └─────────────────────────────────────────────────────────┘     │
│                                                                 │
│        ▼                                                         │
│ ┌─────────────────────────────────────────────────────────┐     │
│ │ agents/ (代理层)                                         │     │
│ │ ┌──────────────┐                                         │     │
│ │ │code-reviewer (代码审查) project-manager (项目管理)   │     │
│ │ └──────────────┘                                         │     │
│ └─────────────────────────────────────────────────────────┘     │
└─────────────────────────────────────────────────────────────────┘

一个实际场景的完整演示

用户需求：开发一个优惠券管理功能

1. [SessionStart Hook] 会话启动 → 显示：当前分支 master，3 个未提交文件，2 个高优先级待办
2. 用户输入：帮我开发一个优惠券管理功能
3. [UserPromptSubmit Hook] 强制技能评估 → 评估结果：
   - crud-development: 是
   - database-ops: 是
   - ui-pc: 否（用户未要求）
   → 激活 Skill(crud-development)、Skill(database-ops)
4. AI 加载技能知识，开始工作 → 参考 crud-development 的四层架构规范
   → 参考 database-ops 的建表规范
5. AI 执行 Bash 命令创建文件 → [PreToolUse Hook] 检查命令安全性 → 通过
6. AI 完成代码生成
7. [Stop Hook] 任务完成 → 播放提示音 → 分析：新增 8 个 Java 文件，1 个 SQL 文件
   → 建议：使用 @code-reviewer 审查代码
8. 用户：@code-reviewer
9. [Agent] code-reviewer 启动 → 审查所有新增文件 → 返回报告：2 个警告，0 个错误
10. 用户：提交代码
11. AI 执行 git commit → [PreToolUse Hook] 检查 → 通过 → 提交成功

效率量化

经过两个月的实际使用，我们统计了以下数据：

最显著的改变

1. AI 终于'懂'项目了：不再生成不符合架构的代码
2. 开发流程标准化：每个人的代码风格趋于一致
3. 安全兜底：再也不用担心 AI 执行危险命令
4. 知识沉淀：项目规范不再口口相传，全部固化到 Skills

快速复用指南

如果你想在自己的项目中复用这套体系，以下是核心文件清单：

必备文件（最小化配置）

.claude/
├── settings.json # 核心配置
├── hooks/
│   ├── skill-forced-eval.js # 强制技能评估（最重要）
│   └── pre-tool-use.js # 安全防护
├── skills/
│   └── your-skill/
│       └── SKILL.md # 至少一个技能
└── CLAUDE.md # 项目规范（可选但推荐）

3 步快速部署

步骤 1：创建 settings.json

{
  "hooks": {
    "UserPromptSubmit": [{
      "matcher": "",
      "hooks": [{
        "type": "command",
        "command": "node .claude/hooks/skill-forced-eval.js"
      }]
    }]
  }
}

步骤 2：创建 skill-forced-eval.js

复制本文第二章的代码，修改技能列表为你自己的技能。

步骤 3：创建至少一个 SKILL.md

按照第四章的模板，编写你项目最核心的开发规范。

扩展建议

• 逐步迭代：先从 1-2 个核心技能开始，根据实际使用情况逐步增加
• 收集反馈：记录 AI 的'错误行为'，转化为新的技能规范
• 团队共建：让每个开发者贡献自己领域的技能知识

总结

回到开篇的问题：如何让 AI 从'通用助手'变成'项目专家'？

答案是：用制度约束能力，用知识填充认知。

• Hooks 是纪律：确保 AI 在每个关键节点执行正确的动作
• Skills 是知识：把项目规范固化成 AI 可学习的文档
• Commands 是流程：把最佳实践编排成可重复执行的步骤
• Agents 是分工：让专业的子任务交给专业的代理处理

这套体系的核心洞察是：AI 的能力需要'制度'来激发。

就像一个聪明的新员工，如果没有明确的规章制度和岗位手册，他可能会按自己的理解乱来。但如果你给他一套完善的制度体系，他就能快速成长为团队的中坚力量。

AI 也是一样。