25% → 90%！别让 Skills 吃灰：Hooks + Commands + Agents 协同激活 AI 全部能力：Claude Code 工程化实践

25% → 90%！别让 Skills 吃灰：Hooks + Commands + Agents 协同激活 AI 全部能力：Claude Code 工程化实践

一、引言：AI 编程助手的"失忆症"

你有没有遇到过这样的场景？

明明给 AI 配置了详细的项目规范，它却视而不见，生成的代码完全不符合架构要求。你告诉它"我们用四层架构"，它偏要写成三层。你强调"禁止使用 el-input"，它下一秒就给你来一个 <el-input v-model="value" />。

这不是 AI 不够聪明，而是它患上了"选择性失忆症"。

我们团队在使用 Claude Code 开发 RuoYi-Plus 项目时，做过一个统计：在没有任何干预的情况下，AI 主动调用项目 Skills（技能配置）的概率只有 25% 左右。也就是说，你精心编写的项目规范，有 75% 的概率被 AI 直接忽略。

这就像你给新员工发了一本 500 页的开发手册，但他从来不翻，全凭自己的"经验"写代码。

问题的本质是：AI 有能力，但缺乏"制度约束"。

于是我们开始思考：能不能设计一套机制，让 AI 在每次回答前，强制检查应该调用哪些技能？

答案是：Hooks（钩子）。

在原先基础上经过一个多月的迭代，我们构建了一套完整的 .claude 配置体系，核心是 4 个生命周期钩子 + 26 个专业技能 + 多个斜杠命令 + 自定义代理。这套体系让开发场景下的技能激活率从约 25% 飙升到 90% 以上，彻底解决了 AI "不听话"的问题。

本文将完整拆解这套配置的设计思路和实现细节。

二、破局：一个 Hook 的魔法

问题根源

为什么 AI 不主动调用 Skills？

因为在默认情况下，Claude Code 的工作流程是这样的：

用户提问 → AI 直接回答

Skills 只是"可选参考"，AI 会根据自己的判断决定是否调用。而 AI 的判断标准往往是"这个问题看起来需不需要"，而不是"项目规范要求我必须这样做"。

解决方案：强制评估钩子

我们在 .claude/hooks/ 目录下创建了一个关键文件：skill-forced-eval.js。

这个钩子挂载在 UserPromptSubmit 事件上，也就是用户每次提交问题时自动触发。它的作用是：在 AI 开始思考之前，强制输出一段"技能评估指令"。

核心代码逻辑：

// skill-forced-eval.js 核心逻辑
const instructions = `## 指令：强制技能激活流程（必须执行）

### 步骤 1 – 评估
针对以下每个技能，陈述：[技能名] – 是/否 – [理由]

可用技能列表：
– crud-development: CRUD/业务模块开发
– api-development: API设计/RESTful规范
– database-ops: 数据库/SQL/建表
– ui-pc: 前端组件/AForm/AModal
– ui-mobile: 移动端/WD UI组件
…（共26个技能）

### 步骤 2 – 激活
如果任何技能为"是" → 立即使用 Skill() 工具激活
如果所有技能为"否" → 说明"不需要技能"并继续

### 步骤 3 – 实现
只有在步骤 2 完成后，才能开始实现。`;

console.log(instructions);

效果对比

优化前（无 Hook）：

用户：帮我开发一个优惠券管理功能
AI：好的，我来帮你写代码…（直接开始，忽略项目规范）

优化后（有 Hook）：

用户：帮我开发一个优惠券管理功能

AI 评估结果：
– crud-development: 是 – 涉及业务模块CRUD开发
– database-ops: 是 – 需要建表和字典配置
– ui-pc: 否 – 用户未要求前端页面

激活技能：
> Skill(crud-development)
> Skill(database-ops)

[加载技能知识后开始实现…]

数据验证： 经过两周的实际使用统计，开发类任务的技能激活率从约 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] 检查 → 通过
→ 提交成功

八、效率量化

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

最显著的改变

九、快速复用指南

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

必备文件（最小化配置）

.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 也是一样。

最后，附上我们项目的 .claude 目录结构，供参考：

.claude/
├── settings.json # 核心配置
├── CLAUDE.md # 项目总规范
├── hooks/ # 4 个生命周期钩子
│ ├── session-start.js
│ ├── skill-forced-eval.js
│ ├── pre-tool-use.js
│ └── stop.js
├── skills/ # 26 个专业技能
│ ├── crud-development/
│ ├── api-development/
│ ├── ui-pc/
│ ├── ui-mobile/
│ └── …
├── commands/ # 斜杠命令
│ ├── dev.md
│ ├── crud.md
│ └── check.md
├── agents/ # 自定义代理
│ ├── code-reviewer.md
│ └── project-manager.md
└── templates/ # 模板文件
└── 项目状态模板.md

希望这套实践能帮助你打造属于自己的 AI 开发工作流。

如果觉得有帮助，欢迎点赞、在看、转发三连！

视频教程链接：https://www.bilibili.com/video/BV1rnBKB2EME/

*作者：抓蛙师