Claude Code 工程化实践：Hooks + Skills 全能力激活指南

核心目标：通过构建 .claude 配置体系，解决 AI 编程“不遵循规范”的痛点，将 Skills 调用率从 25% 提升至 90%+，并实现自动化与安全防护。

---

📂 目录结构总览

在项目根目录下创建 .claude 文件夹，核心结构如下：

.claude/
├── settings.json              # [配置] 注册钩子、权限、MCP
├── CLAUDE.md                  # [全局] 项目通用规范
├── hooks/                     # [核心] 生命周期钩子
│   ├── skill-forced-eval.js   # 🚀 强制技能评估（关键文件）
│   ├── pre-tool-use.js        # 🛡️ 安全防护（拦截 rm -rf 等）
│   ├── session-start.js       # 🏁 会话启动（显示 Git/Todo）
│   └── stop.js                # 🛑 结束反馈（总结与建议）
├── skills/                    # [知识] 技能库
│   ├── crud-development/      # 示例：CRUD 开发规范
│   │   └── SKILL.md
│   └── ...
├── commands/                  # [流程] 斜杠命令 (/dev, /crud)
└── agents/                    # [分工] 专项代理 (@reviewer)

---

🚀 核心实现：强制技能评估 (Step-by-Step)

这是解决 AI “选择性失忆”的关键。通过 Hook 挂载，强制 AI 在回答每一个问题前，先进行“自我反思”和“技能检索”。

1. 配置 settings.json

注册 UserPromptSubmit 事件，当用户提问时触发评估脚本。

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

2. 编写强制评估脚本

此脚本会在 AI 开始思考之前注入指令，构建“思维链”。

// .claude/hooks/skill-forced-eval.js

// 0. 逃生通道：如果是斜杠命令（如 /dev），跳过评估，保证命令执行速度
const prompt = process.env.USER_PROMPT || "";
if (/^\/[^\/\s]+$/.test(prompt.split(/\s/)[0])) {
  process.exit(0);
}

// 1. 定义提示词模板：强制 AI 对照技能列表进行二选一
const instructions = `## 指令：强制技能激活流程（必须执行）

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

可用技能列表：
- crud-development: 业务CRUD/四层架构
- api-development: RESTful API规范
- database-ops: SQL/建表/字典
- ui-pc: Element Plus组件规范
// ... (在此处列出你所有的 skills)

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

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

// 2. 输出指令给 AI
console.log(instructions);

3. 定义技能 (SKILL.md)

每个技能必须遵循统一模板，确保 AI 易于理解。

<!-- .claude/skills/crud-development/SKILL.md -->

# [技能名称：CRUD开发]

## 触发条件
- 关键词：CRUD、增删改查、Service、业务模块
- 场景：开发新的功能模块时

## 核心规范 (Do's)
1. **架构**：Controller → Service (禁止继承 Impl) → DAO (构建 Wrapper) → Mapper
2. **Entity**：必须继承 `TenantEntity`，主键使用雪花算法。
3. **转换**：对象转换必须使用 `MapstructUtils.convert()`。

## 禁止事项 (Don'ts)
- ❌ 禁止在 Controller 写业务逻辑
- ❌ 禁止使用 `BeanUtil.copyProperties`

## 参考代码
- Entity: `ruoyi-modules/.../domain/Demo.java`

---

🛡️ 安全与生命周期管理 (Hooks)

除了核心的技能激活，还需要通过其他 Hook 管理全生命周期，防止 AI “幻觉”导致的灾难。

1. 安全防护 (PreToolUse)

拦截高危命令，物理阻断误删库或删文件。

// .claude/hooks/pre-tool-use.js
const command = process.env.TOOL_COMMAND || "";

const dangerousPatterns = [
  /rm\s+(-rf?|--recursive).*\//,  // 禁止根目录递归删除
  /drop\s+(database|table)/i,      // 禁止删库删表
  /format\s+[a-z]:/i               // 禁止格式化
];

if (dangerousPatterns.some(p => p.test(command))) {
  console.log(JSON.stringify({
    decision: "block",
    reason: "🚫 安全拦截：检测到危险命令，操作已阻止。"
  }));
  process.exit(0);
}

2. 会话启动感知 (SessionStart)

• 功能：读取 git status 和 docs/TODO.md。
• 价值：让 AI 开局就知道项目进度，避免覆盖未提交代码。

---

⚡ 提效工具：Commands 与 Agents

1. Commands (斜杠命令)

将复杂流程标准化，避免重复 Prompt。

• /dev [功能名]：执行标准的 7 步开发流（需求→设计→DB→后端→前端→测试→文档）。
• /crud [表名]：一键生成四层架构代码。
• /check：运行全栈代码规范检查。

2. Agents (专项代理)

• @code-reviewer：不参与写代码，专门负责读取 Git 变更，逐条核对 SKILL.md 中的规范，输出审查报告。

---

📊 效率量化

• 规范执行率：从 25% (靠运气) → 90%+ (靠制度)。
• 开发耗时：标准 CRUD 模块从 2-4 小时缩短至 5-10 分钟。
• 安全性：彻底杜绝 AI 误删文件的风险。

---

🔌 基础设施基石：稳定高并发的 API 支持

要实现上述的 90% 技能激活率，代价是 Token 消耗量的激增。

因为我们强制 Hooks 在每次对话前注入几百 tokens 的“评估指令”，并且一旦激活 Skills，会加载数千 tokens 的上下文文档。如果底层 API 响应慢或网络波动，AI 的反应会变得极其迟钝，甚至因为超时导致代码生成中断。

这套工程化架构，需要像赛车一样的高性能燃油支持。

推荐使用 🔗weelinking Claude直连：

• ⚡ 极速响应：专线优化，国内直连低延迟，确保 Hooks 瞬间加载，代码生成不卡顿。
• 🛡️ 稳定高并发：支持企业级并发请求，无论是 CI/CD 中的自动审查 (@code-reviewer) 还是多开发并行，都能稳如磐石。
• 💰 成本优化：相比直连，我们提供更灵活的计费策略，让您在享受“重上下文”开发模式时，无需为 Token 账单焦虑。
• 🔑 一键接入：完全兼容 Claude Code 及各类 IDE 插件，只需一行配置即可替换 Endpoint。

** 🔗👉 立即获取高性能 API Key**
让 AI 的思考不再等待，让工程化落地更顺畅。

---

📥 快速部署清单

1. 准备环境：获取稳定的 API Key（推荐上述中转服务以确保体验）。
2. 创建目录：.claude/hooks, .claude/skills。
3. 配置：复制本文的 settings.json 和 skill-forced-eval.js。
4. 编写技能：至少创建一个 SKILL.md（如你的编码规范）。
5. 重启：重启 Claude Code 会话生效。