gavin/remoteconn-gitea

Fork 0

Files

douboer c49aa1a5e9 first commit

2026-03-21 18:57:10 +08:00

4.8 KiB

Raw Permalink Blame History

Hook Setup Guide

为 AI coding agents 配置自动 self-improvement triggers。

Overview

hooks 会在关键时机注入提醒，以便主动记录 learnings：

UserPromptSubmit：每次 prompt 后提醒是否需要记录 learnings
PostToolUse (Bash)：当 command 失败时进行 error detection

Claude Code Setup

Option 1: Project-Level Configuration

在项目根目录创建 .claude/settings.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"
          }
        ]
      }
    ]
  }
}

Option 2: User-Level Configuration

将以下内容加入 ~/.claude/settings.json，实现全局启用：

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

Minimal Setup（仅 Activator）

如果希望降低开销，只使用 UserPromptSubmit hook：

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

Codex CLI Setup

Codex 使用与 Claude Code 相同的 hook system。在 .codex/settings.json 中写入：

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

GitHub Copilot Setup

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

## Self-Improvement

在完成包含以下情况的任务后：
- Debugging non-obvious issues
- 发现 workarounds
- 学到项目特定 patterns
- 解决 unexpected errors

考虑使用 self-improvement skill 的格式，将这条 learning 记录到 `.learnings/`。

对于对其他 sessions 也有价值的高价值 learnings，考虑做 skill extraction。

Verification

Test Activator Hook

启用 hook 配置
启动新的 Claude Code session
发送任意 prompt
确认上下文中出现 <self-improvement-reminder>

Test Error Detector Hook

为 Bash 启用 PostToolUse hook
运行一个会失败的 command：ls /nonexistent/path
确认出现 <error-detected> reminder

Dry Run Extract Script

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

预期输出会展示将要创建的 skill scaffold。

Troubleshooting

Hook Not Triggering

Check script permissions：chmod +x scripts/*.sh
Verify path：使用绝对路径，或使用相对项目根目录的路径
Check settings location：确认是 project 级还是 user 级配置
Restart session：hooks 会在 session 启动时加载

Permission Denied

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

Script Not Found

如果使用相对路径，请确认当前目录正确；否则使用绝对路径：

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

Too Much Overhead

如果 activator 让你觉得太打断：

Use minimal setup：仅启用 UserPromptSubmit，不启用 PostToolUse
Add matcher filter：只在特定 prompts 下触发：

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

Hook Output Budget

activator 被设计为轻量输出：

Target：约 50-100 tokens 每次触发
Content：结构化 reminder，而不是冗长说明
Format：XML tags，便于解析

如果还需要进一步降低开销，可以直接修改 activator.sh，让输出更短。

Security Considerations

hook scripts 以与 Claude Code 相同的权限运行
scripts 只输出文本；不会修改文件，也不会执行额外 commands
error detector 会读取 CLAUDE_TOOL_OUTPUT environment variable
所有 scripts 都是 opt-in 的（必须手动配置才会启用）

Disabling Hooks

如果想临时停用，又不想删除配置：

Comment out in settings：

{
  "hooks": {
    // "UserPromptSubmit": [...]
  }
}

或直接删除 settings file：没有配置时 hooks 就不会运行

4.8 KiB Raw Permalink Blame History Unescape Escape