Hooks Claude Code: Contoh Guardrail yang Selalu Berjalan

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "node \"${CLAUDE_PROJECT_DIR:-.}/scripts/review-blog-figures.mjs\" --hook 2>/dev/null || true",
            "timeout": 30,
            "statusMessage": "Checking whether the figures fit"
          }
        ]
      }
    ]
  }
}

Seluruh konfigurasi hook bersama di repo ini. Matcher persis Write|Edit menjalankan pemeriksaan gambar setiap kali ada Write atau Edit, dan tidak pernah untuk Bash. Hook ini memakai shell form, bukan exec form, karena butuh 2>/dev/null || true milik shell, dan placeholder path-nya dibungkus tanda kutip ganda seperti yang diminta dokumentasi untuk shell form. timeout: 30 menggantikan default 600 detik; statusMessage adalah teks yang muncul di spinner selama hook berjalan.

if (HOOK_MODE) {
  let file = "";
  try {
    const payload = JSON.parse((await readStdin()) || "{}");
    file =
      payload.tool_input?.file_path ?? payload.tool_response?.filePath ?? "";
  } catch {
    process.exit(0); // Not our payload; a hook must never break the edit.
  }
  const component = WATCHED.component.exec(file);
  if (component) only = component[1];
  checkPixels = WATCHED.registry.test(file) || WATCHED.inline.test(file);
  // Editing anything else — a page, a script, a message file for a post we
  // cannot identify — is not a figure change worth a report.
  if (!component && !checkPixels && !WATCHED.messages.test(file))
    process.exit(0);
}

Sisi input. Skrip mem-parse payload dari stdin dan mengambil tool_input.file_path, dengan tool_response.filePath sebagai cadangan. Payload yang gagal di-parse, atau file yang bukan komponen blog, registry gambar, gambar inline, atau file pesan, langsung keluar dengan exit 0. Jadi sebagian besar edit hanya memakan satu kali start Node, tidak lebih.

    const shown = ordered.slice(0, HOOK_MAX_FINDINGS);
    const omitted = ordered.length - shown.length;
    const lines = shown.map(
      (f) => `- ${f.component} [${f.check}] ${f.message}`,
    );
    if (omitted)
      lines.push(
        `- …and ${omitted} more not listed here (run the script for all)`,
      );
    process.stdout.write(
      JSON.stringify({
        hookSpecificOutput: {
          hookEventName: "PostToolUse",
          additionalContext:
            `Figure-fitness review (${scope}) — ADVISORY, nothing is broken:\n${lines.join("\n")}\n` +
            `Look at each image before deciding: does its subject match the section's subject? ` +
            `If the post is about experience or methodology, draw a diagram (scripts/generate-blog-diagram.mjs) ` +
            `instead of borrowing a photograph. Run node scripts/review-blog-figures.mjs for the full report.`,
        },
      }),
    );
  }
  process.exit(0);

Sisi jawaban. Satu objek JSON berisi hookSpecificOutput, hookEventName, dan additionalContext, dan selalu exit 0. Jumlah temuan dibatasi HOOK_MAX_FINDINGS, yaitu 12, supaya pemeriksaan yang berisik tidak membanjiri konteks yang justru ingin dibantunya, dan teksnya dibuka dengan pernyataan jelas bahwa ini hanya saran. Kalau tidak ada temuan, skrip tidak mencetak apa pun.