ECC Hookify 规则系统实战:用 /hookify 将 Claude Code 的不良行为固化为可管理的钩子规则【免费下载链接】ECCThe agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.项目地址: https://gitcode.com/GitHub_Trending/ev/ECCECC(Everything Claude Code)仓库中的 hookify 是一套行为防火墙工作流:通过/hookify命令,把你在对话中反复纠正、反复回滚的 Agent 行为,沉淀为存放在.claude/目录下的 Markdown 规则文件,由 Claude Code 的钩子(hook)系统在 bash 命令、文件编辑、用户输入或会话结束时自动拦截或告警。读完本篇,你将掌握 hookify 规则的完整文件格式(基础与多条件两种形态)、五种事件类型的模式匹配写法,以及/hookify、/hookify-list、/hookify-configure三件套命令的协同管理方式。一、hookify 在 ECC 中的定位hookify 的核心思路来自 commands/hookify.md:它不是让你手写一整套钩子脚本,而是提供一条从对话中的问题行为到机器可执行的防护规则的生成链路。按 commands/hookify-help.md 的描述,Hookify 创建的规则文件会集成到 Claude Code 的 hook 系统中,用于阻止不想要的行为。在 ECC 的仓库结构中,这套能力由四类文件共同支撑:四个命令文件:commands/hookify.md(创建)、commands/hookify-list.md(列表)、commands/hookify-configure.md(启停)、commands/hookify-help.md(帮助);一个规则编写技能:skills/hookify-rules/SKILL.md,定义了规则的完整语法、事件类型指南与模式编写技巧;一个分析代理:agents/conversation-analyzer.md,在/hookify不带参数时负责从会话历史中挖掘值得拦截的行为;项目级钩子注册文件 hooks/hooks.json,其中从第 4 行起即注册了PreToolUse事件(如 hooks/hooks.json),第 136 行起注册PostToolUse事件(如 hooks/hooks.json),构成规则生效所依赖的钩子管道。从源码结构看,skills/hookify-rules被纳入了 manifests/install-modules.json 中的安装模块清单,说明它属于 ECC 可选安装的能力包之一。二、/hookify 命令的使用方式基本用法只有一条命令(commands/hookify.md):/hookify [description of behavior to prevent]带参数:直接解析你对不想要的行为的文字描述,进入规则生成流程;不带参数:自动调用conversation-analyzer代理分析当前会话,主动找出值得预防的行为。Step 1:收集行为信息agents/conversation-analyzer.md 定义了这个无参数路径的挖掘标准,重点扫描四类信号:信号类型识别特征显式纠正(Explicit Corrections)No, dont do that、Stop doing X、I said NOT to...、Thats wrong, use Y instead沮丧反应(Frustrated Reactions)用户回滚 Claude 做的改动、反复说 no/wrong、手动修正 Claude 的输出、语气升级回滚的改动(Reverted Changes)Claude 编辑后出现git checkout -- file或git restore file、用户撤销或重做 Claude 刚改过的文件重复性问题(Repeated Issues)同一错误在对话中多次出现、Claude 反复以不期望的方式使用某个工具、用户反复纠正的行为模式该代理的产出是结构化的行为清单,每个行为按如下 YAML 格式输出,供 Step 2 呈现给用户:behavior: Description of what Claude did wrong frequency: How often it occurred severity: high|medium|low suggested_rule: name: descriptive-rule-name event: bash|file|stop|prompt pattern: regex pattern to match action: block|warn message: What to show when triggered文档同时要求优先处理高频、高严重度的行为(Prioritize high-frequency, high-severity behaviors first),避免把一次性的偶发问题也固化成规则。Step 2:向用户呈现发现对每个候选行为,hookify 会把四要素摆出来征求批准:行为描述(behavior description);建议的事件类型(proposed event type);建议的模式或匹配器(proposed pattern or matcher);建议的动作(proposed action)。这一步是关键的人机确认点:只有用户认可后,规则才会落盘。Step 3:生成规则文件对每条被批准的规则,创建一个文件,路径为.claude/hookify.{name}.local.md。最小可用格式(commands/hookify.md):--- name: rule-name enabled: true event: bash|file|stop|prompt|all action: block|warn pattern: regex pattern --- Message shown when rule triggers.Step 4:确认与后续管理命令最后会汇报已创建的规则,并提示用/hookify-list和/hookify-configure管理它们(见第五节)。三、规则文件的完整语法skills/hookify-rules/SKILL.md 给出了比命令文件更完整的字段定义。规则文件是带 YAML frontmatter 的 Markdown,规则主体(消息文本)支持多行与 Markdown 格式,用于在规则触发时展示给 Claude/用户。基础字段表字段必填取值说明name是kebab-case 字符串唯一标识符,建议动词开头:warn-*、block-*、require-*enabled是true/false开关,可不删除文件直接停用event是bash/file/stop/prompt/all决定规则在哪个钩子事件上触发action否warn/block默认为warn(只提示);block会阻止操作继续pattern是*正则字符串匹配模式(*也可改用 conditions 表达复杂规则)进阶格式:多条件(conditions)单个正则不够用时,可以用conditions组合多个条件,所有条件全部满足规则才触发(AND 语义):--- name: warn-env-api-keys enabled: true event: file conditions: - field: file_path operator: regex_match pattern: \.env$ - field: new_text operator: contains pattern: API_KEY --- Youre adding an API key to a .env file. Ensure this file is in .gitignore!不同事件可用的条件字段:事件可匹配字段bashcommandfilefile_path、new_text、old_text、contentpromptuser_prompt支持的运算符:regex_match、contains、equals、not_contains、starts_with、ends_with。四、事件类型与模式编写指南四种事件类型的典型用途bash—— 匹配 Bash 工具执行的完整命令串:危险命令:rm\s-rf、dd\sif、mkfs权限提升:sudo\s、su\s权限问题:chmod\s777file—— 匹配 Edit/Write/MultiEdit 操作的文件路径与内容:调试代码残留:console\.log\(、debugger安全风险:eval\(、innerHTML\s*敏感文件:\.env$、credentials、\.pem$stop—— 会话结束时触发,适合收尾检查与提醒;模式写.*表示恒匹配prompt—— 匹配用户提交的消息内容,适合强制工作流(例如禁止跳过测试直接提交)all—— 在所有事件上触发正则编写要点来自 skills/hookify-rules/SKILL.md 的三条实用建议:基础转义:.写成\.,(写成\(;\s空白、\d数字、\w单词字符;一次或多次、*零次或多次、?可选、|或;常见坑:过宽 ——log会命中 login、dialog,应写成console\.log\(;过窄 ——rm -rf /tmp只能拦住一条命令,应写成rm\s-rf;YAML 转义 —— 优先使用不带引号的 pattern;若用引号包裹,\s需写作\\s;先测试再部署—— 用一行 Python 验证正则是否按预期命中:python3 -c import re; print(re.search(ryour_pattern, test text))五、规则的生命周期管理hookify 提供了三个配套命令完成查看—启停—求助闭环:/hookify-list(commands/hookify-list.md):扫描所有.claude/hookify.*.local.md,读取每个文件的 frontmatter(name、enabled、event、action、pattern),以表格呈现:RuleEnabledEventPatternFile(规则名)(true/false)(事件)(模式)(文件路径)并显示规则总数,提醒可用/hookify-configure修改状态。/hookify-configure(commands/hookify-configure.md):交互式列出全部规则及当前启停状态,询问要切换哪些规则,然后只更新所选文件中enabled:字段,最后确认变更。这意味着停用规则不需要删文件,/hookify-list也能如实反映状态。/hookify-help(commands/hookify-help.md):输出完整的 hookify 文档,包括事件类型、规则文件格式、命令清单与模式技巧(上文第四节的Pattern Tips即出自此处)。文件组织约定位置:项目根目录下的.claude/目录;命名:.claude/hookify.{descriptive-name}.local.md,文件名与name字段对应;版本控制:.local.md后缀表明规则是个人/本机的局部配置,文档建议将.claude/*.local.md加入.gitignore,避免把个人偏好提交进仓库共享给他人。六、规则如何接入 ECC 的钩子体系ECC 的钩子注册文件 hooks/hooks.json 中,PreToolUse管道(从 hooks/hooks.json 开始)负责在工具执行前同步拦截命令,PostToolUse管道(从 hooks/hooks.json 开始)负责在工具执行后异步/同步地做日志与检查,例如统一的分发器scripts/hooks/posttooluse-dispatcher.js会一次性跑完多个 PostToolUse 钩子并保留各自独立的开关控制。从源码结构看,hookify 规则文件本身存放在项目侧的.claude/目录中,由 hookify 命令族负责生成与读写,而钩子事件(如PreToolUse下的 bash 拦截)提供了规则真正生效的挂载点。两者是本地规则层 全局钩子管道的分工:你只维护声明式的 Markdown 规则,不需要自己编写 Node 钩子脚本。七、实战落地建议结合命令文档与技能文档,给出三条可执行的落地顺序:先积累,后固化:在真实会话中用一段时间,记录 Agent 反复踩坑的行为;再用无参数/hookify让conversation-analyzer按高频优先、高严重度优先的次序输出建议规则,逐条批准;warn先行,block后置:新规则先用默认warn观察误报率(模式过宽是第一大坑),确认精确后再改为block;保持可审计:定期/hookify-list核对规则总数,长期未触发的规则用/hookify-configure停用而非删除,方便日后恢复;新增规则前用第四节的 Python 一行命令验证正则。整套机制的价值在于:把口头纠正这种会随会话消失的隐性知识,转化为版本可控、逐条可开关、可随项目演进的显式约束,让同类错误不再依赖你每次都记得说别那样做。【免费下载链接】ECCThe agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.项目地址: https://gitcode.com/GitHub_Trending/ev/ECC创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考