Claude Code 质量自愈钩子：让提交失败自动迭代修复到通过

flowchart TD
    A[Claude 调用 Write/Edit] --> B[PostToolUse 钩子]
    B --> C[quality-gate.sh 读 stdin JSON]
    C --> D{改的是 ts/tsx/js?}
    D -->|否| Z[exit 0 放行]
    D -->|是| E[tsc --noEmit 与 eslint]
    E --> F{门禁通过?}
    F -->|是| Z
    F -->|否| G["exit 2 + 报错写 stderr"]
    G --> H[Claude 接收反馈]
    H --> I[自动重新编辑]
    I --> B
    style G fill:#fdd,stroke:#c00
    style Z fill:#dfd,stroke:#0a0

mkdir heal-demo && cd heal-demo
npm init -y
npm i -D typescript eslint @typescript-eslint/parser @typescript-eslint/eslint-plugin
npx tsc --init

"scripts": {
  "typecheck": "tsc --noEmit",
  "lint": "eslint src --ext .ts"
}

{
  "compilerOptions": {
    "strict": true,
    "noUnusedLocals": true,
    "noImplicitAny": true,
    "target": "ES2020",
    "module": "CommonJS",
    "outDir": "dist"
  },
  "include": ["src"]
}

function add(a, b) {
  const unused = 42;
  return a + b
}

#!/usr/bin/env bash
# PostToolUse 质量门禁：对刚改过的 TS 文件跑 tsc + eslint
# 失败时 exit 2，把报错反馈给 Claude 让它自愈

set -uo pipefail

# 1) 从 stdin 读取钩子输入 JSON
INPUT="$(cat)"

# 2) 用 jq 抽取字段（无 jq 时换 python3 -c 'import sys,json;...'）
FILE_PATH="$(printf '%s' "$INPUT" | jq -r '.tool_input.file_path // empty')"

# 3) 只关心源码文件，跳过配置/文档
case "$FILE_PATH" in
  *.ts|*.tsx|*.js|*.jsx) ;;
  *) exit 0 ;;
esac

# 4) 文件可能已删，存在性检查
[ -f "$FILE_PATH" ] || exit 0

# 5) 跑门禁，捕获合并输出
ERRS="$(npx --no-install tsc --noEmit 2>&1; npx --no-install eslint "$FILE_PATH" 2>&1)"

# 6) 有报错就 exit 2，stderr 是 Claude 唯一能看到的反馈
if [ -n "$ERRS" ]; then
  echo "❌ 质量门禁未通过，请修复后继续：" >&2
  echo "$ERRS" >&2
  exit 2
fi

exit 0

chmod +x scripts/quality-gate.sh

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit|MultiEdit",
        "hooks": [
          {
            "type": "command",
            "command": "bash scripts/quality-gate.sh"
          }
        ]
      }
    ]
  }
}

#!/usr/bin/env bash
# PreToolUse 提交门禁：拦截 git commit，强制全量检查

set -uo pipefail
INPUT="$(cat)"

CMD="$(printf '%s' "$INPUT" | jq -r '.tool_input.command // empty')"

# 只关心 commit 类命令
echo "$CMD" | grep -qE '\bgit\b.*\bcommit\b' || exit 0

# 全量门禁（不只是单文件）
if ! npm run -s typecheck 2>&1 || ! npm run -s lint 2>&1; then
  echo "🛑 提交被拦截：全量 typecheck/lint 未通过，请先修复。" >&2
  exit 2
fi
exit 0

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit|MultiEdit",
        "hooks": [{ "type": "command", "command": "bash scripts/quality-gate.sh" }]
      }
    ],
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [{ "type": "command", "command": "bash scripts/commit-gate.sh" }]
      }
    ]
  }
}

# 非交互执行，限制最多 20 轮 agent 循环，自动接受文件编辑
claude -p "让 src/ 下所有文件通过 tsc 和 eslint，修完用 git 提交" \
  --permission-mode acceptEdits \
  --max-turns 20 \
  --output-format json \
  --allowedTools "Edit Write Bash" \
  > heal-run.json

#!/usr/bin/env bash
set -uo pipefail
FILES="src/legacy-a.ts src/legacy-b.ts src/legacy-c.ts"
for f in $FILES; do
  echo "=== 自愈 $f ==="
  claude -p "只修复 $f 使其通过 tsc 与 eslint，不要动其他文件" \
    --permission-mode acceptEdits \
    --max-turns 10 \
    --allowedTools "Edit Read Bash" \
    > "heal-$(basename $f).log" 2>&1
done
echo "全部完成，结果见 heal-*.log"

# 加在 quality-gate.sh 报错分支里
COUNTER="/tmp/heal-counter.$(md5sum <<<"$FILE_PATH" | cut -c1-8)"
COUNT=$(cat "$COUNTER" 2>/dev/null || echo 0)
COUNT=$((COUNT + 1))
echo "$COUNT" > "$COUNTER"
if [ "$COUNT" -ge 5 ]; then
  echo "⚠️ $FILE_PATH 连续 5 次未通过，疑似修不动，请人工查看" >&2
  rm -f "$COUNTER"
  exit 0   # 放行，跳出死循环
fi

echo "[$(date -Is)] $FILE_PATH result=$?" >> logs/quality.log

heal-demo/
├── .claude/
│   └── settings.json        # 两个 hook 注册
├── scripts/
│   ├── quality-gate.sh      # PostToolUse 单文件校验
│   ├── commit-gate.sh       # PreToolUse 提交拦截
│   └── batch-heal.sh        # -p 批量驱动
├── src/
│   └── calc.ts              # 故意写坏的文件
├── logs/
├── package.json
└── tsconfig.json

# 1) 启动一次交互式自愈（亲眼看到循环）
claude
# 输入：把 src/calc.ts 修到通过 tsc 和 eslint，然后用一句话提交
# 观察：Claude 编辑→钩子报错→Claude 再改→钩子变绿→git commit→commit-gate 放行

# 2) 退出交互，改用 -p 无人值守重跑（先把 calc.ts 再改坏以验证）
claude -p "修复 src/ 下所有类型与 lint 错误并提交" \
  --permission-mode acceptEdits --max-turns 15 --output-format json

# 3) 多文件批量
bash scripts/batch-heal.sh

flowchart LR
    U[开发者 / 定时任务] -->|claude -p| C[Claude Agent]
    C -->|Write/Edit| F[改文件]
    F --> P1[PostToolUse: 单文件门禁]
    P1 -->|exit 2| C
    P1 -->|exit 0| G[继续]
    G -->|Bash: git commit| P2[PreToolUse: 全量门禁]
    P2 -->|exit 2 拦截| C
    P2 -->|exit 0| CM[(commit 落库)]
    CM --> L[logs/quality.log 留痕]
    style P1 fill:#fef3c7
    style P2 fill:#fef3c7
    style CM fill:#d1fae5