用途
RuleZ 是一个高性能的 AI 策略引擎,用于拦截 AI 编程助手事件并执行配置好的动作。它通过基于适配器的事件转换在多个平台上工作。本技能(mastering-hooks)是用于安装、调试和优化 RuleZ 的智能助手。
工作流程示意:
User Prompt --> AI Assistant --> RuleZ Binary --> [Match Rules] --> Execute Actions
| |
v v
PreToolUse inject/run/block
PostToolUse context/validation
BeforeAgent
PermissionRequest
支持的平台:
- Claude Code(原生)——完整事件支持
- Gemini CLI——通过适配器,双触发事件
- GitHub Copilot——通过适配器
- OpenCode——通过适配器,双触发事件
系统组件:
- RuleZ Binary(Rust):运行时快速、确定性地执行钩子
- hooks.yaml:声明式配置,定义规则、匹配器和动作
- 平台适配器:将平台特定事件转换为统一的 RuleZ 事件类型
- 本技能:用于安装、调试和优化的智能助手
主要能力
1. 安装与初始化 RuleZ
适用场景:首次在项目中或用户范围内设置 RuleZ。
检查清单:
- 验证 RuleZ 二进制已安装:
rulez --version - 初始化配置:
rulez init(创建 .claude/hooks.yaml) - 注册到 Claude Code:
rulez install(项目本地)或rulez install --global - 验证配置:
rulez validate - 验证安装:检查 .claude/settings.json 中的钩子条目
参考:cli-commands.md
2. 创建钩子规则
适用场景:添加新行为,如上下文注入、命令验证或工作流自动化。
检查清单:
- 确定事件类型(PreToolUse、PostToolUse、BeforeAgent 等)
- 定义匹配器(工具、扩展名、目录、模式)
- 选择动作类型(inject、run、block、require_fields)
- 在 hooks.yaml 中编写规则
- 验证:
rulez validate - 测试:
rulez debug <event> --tool <tool_name>
规则结构示例:
rules:
- name: rule-name # kebab-case 标识符
matchers:
operations: [PreToolUse] # 何时触发
tools: [Write, Edit] # 匹配什么
extensions: [.py] # 可选:文件过滤
actions:
inject: .claude/context/python-standards.md # 做什么
参考:hooks-yaml-schema.md | rule-patterns.md
3. 解释配置
适用场景:理解现有钩子的作用、存在原因或它们如何交互。
检查清单:
- 运行
rulez explain rule <rule-name>进行特定规则分析 - 运行
rulez explain rules获取完整配置概览 - 检查规则优先级(同一事件内先匹配者胜出)
- 识别潜在冲突或重叠
rulez explain rule python-standards 的示例输出:
Rule: python-standards
Event: PreToolUse
Triggers when: Write or Edit tool used on .py files
Action: Injects content from .claude/context/python-standards.md
参考:cli-commands.md
4. 排查钩子问题
适用场景:钩子未触发、行为异常或出现错误消息。
诊断检查清单:
- 验证配置:
rulez validate——捕获 YAML/schema 错误 - 检查注册:
cat .claude/settings.json | grep hooks - 启用调试日志:
rulez debug PreToolUse --tool Write --verbose - 检查日志:
rulez logs --limit 20 - 验证文件路径:确保所有 path: 引用存在
常见问题:
| 症状 | 可能原因 | 修复 |
|---|---|---|
| 钩子从不触发 | 事件/匹配器不匹配 | 使用 rulez debug 追踪匹配 |
| "file not found" | 动作中的路径无效 | 检查相对于项目根目录的路径 |
| 上下文未注入 | 脚本返回无效 JSON | 验证脚本输出格式 |
| Permission denied | 脚本不可执行 | chmod +x script.sh |
| Gemini 上事件不触发 | 事件名称错误 | 查看 platform-adapters.md 中的映射 |
参考:troubleshooting-guide.md
5. 优化配置
适用场景:规则过多、执行缓慢或维护复杂。
优化检查清单:
- 用更宽的匹配器合并重叠规则
- 使用 enabled_when 实现条件规则,而非重复规则
- 将共享上下文移至可复用的 markdown 文件
- 按频率排序规则(最常见的在前)
- 尽早使用 block 短路不必要的处理
参考:rule-patterns.md
6. 多平台设置
适用场景:配置 RuleZ 以在 Claude Code 之外还支持 Gemini CLI、GitHub Copilot 或 OpenCode。
关键概念:
- RuleZ 使用平台适配器将各平台的原生事件转换为统一的 RuleZ 事件类型
- 使用 RuleZ 事件类型(如 PreToolUse)编写规则——适配器自动处理转换
- 某些平台会触发双事件(例如 Gemini 的 BeforeAgent 会同时触发 BeforeAgent 和 UserPromptSubmit)
检查清单:
- 安装 RuleZ:
rulez install - 使用标准 RuleZ 事件类型编写规则
- 使用
rulez debug <event>测试以验证匹配 - 查看 platform-adapters.md 了解平台特定事件映射
参考:platform-adapters.md
使用方式
根据需求选择路径(决策树):
What do you need?
|
+-- New to RuleZ? --> [1. Install & Initialize]
|
+-- Have hooks.yaml but hooks not working? --> [4. Troubleshoot]
|
+-- Need to add new behavior? --> [2. Create Rules]
|
+-- Want to understand existing config? --> [3. Explain Configuration]
|
+-- Performance or complexity issues? --> [5. Optimize]
|
+-- Setting up for Gemini/Copilot/OpenCode? --> [6. Multi-Platform Setup]
适用场景
- 首次在项目中或用户范围内安装与初始化 RuleZ
- 添加上下文注入、命令验证或工作流自动化等新行为
- 理解现有钩子配置的作用与交互
- 排查钩子未触发、行为异常或错误消息
- 优化规则数量、执行速度或维护复杂度
- 为 Gemini CLI、GitHub Copilot 或 OpenCode 进行多平台设置
限制
以下情况不适合使用本技能:
- 简单的 Claude Code 配置:直接使用 settings.json 进行基本权限设置
- 一次性上下文注入:直接粘贴到提示词中即可
- 动态运行时决策:RuleZ 是确定性的;复杂逻辑请使用 MCP 服务器
参考资料
| 文档 | 用途 |
|---|---|
| quick-reference.md | 事件、匹配器、动作、文件位置 |
| hooks-yaml-schema.md | 完整 YAML 配置参考 |
| cli-commands.md | 所有 CLI 命令及示例 |
| rule-patterns.md | 常见模式与配方 |
| troubleshooting-guide.md | 诊断流程 |
| platform-adapters.md | 多平台事件映射与双触发 |
完整 hooks.yaml 示例
# .claude/hooks.yaml
version: "1"
rules:
# Inject Python standards before writing Python files
- name: python-standards
matchers:
operations: [PreToolUse]
tools: [Write, Edit]
extensions: [.py]
actions:
inject: .claude/context/python-standards.md
# Block dangerous git commands
- name: block-force-push
priority: 10
matchers:
operations: [PreToolUse]
tools: [Bash]
command_match: "git push.*--force"
actions:
block: true
# Run security check before committing
- name: pre-commit-security
matchers:
operations: [PreToolUse]
tools: [Bash]
command_match: "git commit"
actions:
run: .claude/validators/check-secrets.sh
# Track agent activity (works on Claude Code and Gemini)
- name: log-agent-start
description: Ensure agents follow project conventions
matchers:
operations: [BeforeAgent]
actions:
inject_inline: |
**Agent Policy**: Follow project conventions in CLAUDE.md.