Hooks designer

Hooks 设计 Skill

识别哪些环节适合增加 hooks，设计触发时机、执行动作、失败处理、回退策略。区分应该做成 hooks 的能力和不应该 hook 化的能力。

何时使用

• 想在 agent 工作流的特定环节自动执行某些操作
• 需要设计自动化检查、通知、转换等"旁路"逻辑
• 审计现有 hooks 是否合理、是否有遗漏
• 团队讨论"这个能力应该做成 hook 还是别的方式"

不适用：核心业务逻辑设计、用户界面设计、与 agent 工作流无关的自动化。

Hooks 适用性判断

应该做成 hook 的场景

特征	示例
在固定时机触发	每次提交前、每次文件修改后、每次测试运行后
动作可独立于主流程	lint 检查不影响代码生成逻辑
需要一致地应用于所有场景	所有 PR 都需要格式化
失败时有明确的处理策略	lint 失败 → 阻止提交
跨项目可复用	同一个 hook 可用于多个项目

不应该做成 hook 的场景

特征	示例	应该怎么做
只在特定上下文触发	只在某个项目的某次任务中需要	内联逻辑
依赖复杂的运行时状态	需要知道用户当前的心理模型	对话中手动执行
动作本身是核心流程	代码生成、文件编辑	主流程的一部分
无法定义明确的失败策略	"感觉不对就停下来"	人工判断
触发频率过高导致干扰	每次字符输入都触发	调整触发时机

输入

输入	说明	必需
工作流描述	agent 的典型工作流程	是
痛点或需求	希望自动化的环节	是
现有 hooks	已有的 hook 配置（若存在）	否
技术约束	使用的 agent 平台、可用的 hook 类型	否

输出

• Hook 设计方案：每个 hook 的完整定义
• 触发时机与条件
• 执行动作与参数
• 失败处理策略
• 回退方案
• 适用性分析：为什么这个能力适合/不适合做成 hook
• 配置文件内容（可直接使用的 JSON/YAML）

执行步骤

1. 梳理工作流

• 列出 agent 的典型工作流步骤
• 标注每个步骤的输入、输出、可能的失败点
• 识别用户提到的痛点和期望自动化的环节

2. 识别 hook 候选点

对工作流中的每个环节，判断是否需要 hook：

1. 这个环节是否有固定的触发时机？ → 是：继续；否：不适合 hook
2. 触发时的动作是否明确可定义？ → 是：继续；否：不适合 hook
3. 动作是否独立于主流程？ → 是：继续；否：考虑内联
4. 失败时是否有明确处理策略？ → 是：继续；否：需补充策略
5. 这个 hook 是否跨项目可复用？ → 是：通用 hook；否：项目级 hook

3. 设计每个 hook

对每个确认的 hook，定义：

hook-name: string              # 小写短横线命名
trigger:
  event: string                # 触发事件（如 pre-commit, post-edit）
  condition: string            # 触发条件（可选，如 "仅对 .ts 文件"）
action:
  command: string              # 执行的命令或动作
  timeout: number              # 超时时间（秒）
  params: object               # 参数（可选）
failure:
  strategy: block | warn | skip  # 失败策略
  message: string              # 失败时的提示消息
  retry: number                # 重试次数（可选）
rollback:
  enabled: boolean             # 是否有回退操作
  action: string               # 回退动作（可选）
metadata:
  scope: global | project      # 作用范围
  priority: number             # 执行优先级
  description: string          # 一句话说明

4. 失败策略设计

策略	适用场景	行为
block	必须通过的检查（lint、安全扫描）	阻止后续操作，显示错误
warn	建议但不强制（性能建议、风格提醒）	显示警告，允许继续
skip	尽力而为的操作（通知、日志记录）	失败时跳过，不影响主流程

5. 输出配置

生成可直接使用的配置内容：

{
  "hooks": {
    "pre-commit": [
      {
        "command": "pnpm lint",
        "timeout": 30,
        "failure": "block",
        "message": "Lint 检查未通过，请修复后再提交"
      }
    ],
    "post-edit": [
      {
        "matcher": "*.ts",
        "command": "pnpm typecheck",
        "timeout": 60,
        "failure": "warn",
        "message": "类型检查发现问题"
      }
    ]
  }
}

边界与非目标

• 不做具体的 shell 脚本编写（只设计 hook 的配置和策略）
• 不做替代 agent 的核心工作流设计
• 不做CI/CD pipeline 设计（这是不同的关注点，虽然概念相似）
• 不做hooks 的运行时实现
• 专注于设计，实现交给具体的 agent 平台

验收标准

• 每个 hook 都有明确的触发时机、动作和失败策略
• 适用性判断有理有据，不是所有东西都设计成 hook
• 失败策略与 hook 的重要性匹配（关键检查用 block，建议性用 warn）
• 配置内容可直接复制到目标平台使用
• 设计方案中区分了通用 hook 和项目级 hook