# Hook 配置指南

为 AI 编码 agent 配置自动化的自我改进触发器。

## 概览

Hooks 可以在关键时刻注入提醒，从而主动捕获 learnings：
- **UserPromptSubmit**：每次 prompt 后提醒评估是否需要记录 learnings
- **PostToolUse (Bash)**：命令失败时进行错误检测

## Claude Code 配置

### 方案 1：项目级配置

在项目根目录创建 `.claude/settings.json`：

```json
{
  "hooks": {
    "UserPromptSubmit": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "./skills/self-improvement/scripts/activator.sh"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "./skills/self-improvement/scripts/error-detector.sh"
          }
        ]
      }
    ]
  }
}
```

### 方案 2：用户级配置

将以下配置加入 `~/.claude/settings.json`，实现全局启用：

```json
{
  "hooks": {
    "UserPromptSubmit": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "~/.claude/skills/self-improvement/scripts/activator.sh"
          }
        ]
      }
    ]
  }
}
```

### 最小配置（仅启用 Activator）

如果想降低开销，只启用 UserPromptSubmit hook：

```json
{
  "hooks": {
    "UserPromptSubmit": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "./skills/self-improvement/scripts/activator.sh"
          }
        ]
      }
    ]
  }
}
```

## Codex CLI 配置

Codex 使用与 Claude Code 相同的 hook 机制。创建 `.codex/settings.json`：

```json
{
  "hooks": {
    "UserPromptSubmit": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "./skills/self-improvement/scripts/activator.sh"
          }
        ]
      }
    ]
  }
}
```

## GitHub Copilot 配置

Copilot 本身不直接支持 hooks。可以改为在 `.github/copilot-instructions.md` 中加入提示：

```markdown
## Self-Improvement

完成以下类型任务后，考虑将经验记录到 `.learnings/`：
- 调试不直观的问题
- 发现绕行方案
- 学到项目特有模式
- 解决意外错误

请使用 self-improvement skill 中定义的格式记录。

如果某条 learning 价值很高，并且对其他 session 也有帮助，可考虑提炼为 skill。
```

## 验证

### 测试 Activator Hook

1. 启用 hook 配置
2. 启动一个新的 Claude Code session
3. 发送任意 prompt
4. 确认上下文中出现了 `<self-improvement-reminder>`

### 测试 Error Detector Hook

1. 为 Bash 启用 PostToolUse hook
2. 运行一个会失败的命令：`ls /nonexistent/path`
3. 确认出现了 `<error-detected>` 提醒

### Dry Run 提炼脚本

```bash
./skills/self-improvement/scripts/extract-skill.sh test-skill --dry-run
```

预期输出会展示将要创建的 skill 脚手架。

## 故障排查

### Hook 没有触发

1. **检查脚本权限**：`chmod +x scripts/*.sh`
2. **确认路径正确**：使用绝对路径，或使用相对于项目根目录的路径
3. **确认 settings 文件位置正确**：区分项目级和用户级
4. **重启 session**：hooks 会在 session 启动时加载

### 权限不足

```bash
chmod +x ./skills/self-improvement/scripts/activator.sh
chmod +x ./skills/self-improvement/scripts/error-detector.sh
chmod +x ./skills/self-improvement/scripts/extract-skill.sh
```

### 找不到脚本

如果使用相对路径，请确认当前目录正确；或者直接改用绝对路径：

```json
{
  "command": "/absolute/path/to/skills/self-improvement/scripts/activator.sh"
}
```

### 开销过大

如果 activator 让你感觉过于打扰：

1. **使用最小配置**：只启用 UserPromptSubmit，跳过 PostToolUse
2. **增加 matcher 过滤**：只在某些 prompt 下触发：

```json
{
  "matcher": "fix|debug|error|issue",
  "hooks": [...]
}
```

## Hook 输出预算

activator 设计得比较轻量：
- **目标**：每次触发约 50-100 tokens
- **内容**：结构化提醒，而不是长篇说明
- **格式**：使用 XML 标签，便于解析

如果还想进一步降低开销，可以直接编辑 `activator.sh`，减少输出文本。

## 安全注意事项

- Hook 脚本以与 Claude Code 相同的权限运行
- 脚本只输出文本，不会修改文件或主动执行命令
- error detector 会读取 `CLAUDE_TOOL_OUTPUT` 环境变量
- 所有脚本都是 opt-in，必须显式配置后才会生效

## 禁用 Hooks

如果想临时禁用，而不是删除整个配置：

1. **在 settings 中注释掉**：
```json
{
  "hooks": {
    // "UserPromptSubmit": [...]
  }
}
```

2. **或者直接删除 settings 文件**：没有配置时 hooks 不会运行