hooks でリンターの結果をエージェントに返し、リンター設定は書き換えさせない（ハーネスの組み方）

どんな問題を解決する？

• エージェントがリンターのエラーを見ないまま作業を進める
• エラーを直す代わりに、設定ファイルでルールを無効化したり --no-verify でコミットしたりする
• エラー文が短すぎて、エージェントが正しい直し方を選べない

手順

1. PostToolUse（Edit|Write）で自動修正 → 残りだけ返す: 例として biome format --write と oxlint --fix を先に実行し、それでも残った問題を集める。エージェントに見せるには JSON で返す（hook の普通の標準出力はエージェントに渡らない）
   bash

   #!/usr/bin/env bash
   FILE=$(jq -r '.tool_input.file_path')   # hook の入力は標準入力の JSON
   npx biome format --write "$FILE" >/dev/null 2>&1
   npx oxlint --fix "$FILE" >/dev/null 2>&1
   msg=$(npx oxlint "$FILE" 2>&1) && exit 0   # 残りがなければ何も返さない
   jq -n --arg m "$msg" '{hookSpecificOutput:{hookEventName:"PostToolUse",additionalContext:$m}}'

2. PreToolUse で設定ファイルを守る: 編集対象のパスが .eslintrc*・eslint.config.*・biome.json・.prettierrc*・tsconfig.json・pyproject.toml・Cargo.toml・.golangci.yml・.swiftlint.yml・lefthook.yml・.pre-commit-config.yaml などなら、理由を標準エラーに書いて exit 2 で止める
3. 抜け道もふさぐ: git commit --no-verify を deny する。Rust なら allow_attributes = "deny" で #[allow(...)] による黙らせを禁止する
4. エラー文を「直し方つき」にする: 自作のリンタールールやチェックスクリプトのメッセージを ERROR（何が悪いか）／WHY（理由。設計判断の記録 ADR へのリンク）／FIX（直し方）／EXAMPLE（正しい例）の形にする
5. 速い層に寄せる: 編集ごとの hook（ミリ秒）→ コミット前（秒）→ CI（分）の順に、なるべく速い段階で検出する
6. Stop hook で「テストが通るまで止めない」ようにする場合は、入力の stop_hook_active を見て、すでに hook で続行中なら止めさせる（無限ループ防止）

注意点

• hook はターンごと・編集ごとに走るので、重いチェック（全体のテストなど）は Stop hook や CI に回す
• 設定ファイルの保護は、人が設定を変えたいときにも効く。変更するときは hook を一時的に外すか、人の手で編集する
• hooks の基本は Claude Code: 「〜したら〜して」はルールではなく hooks（settings.json）に書く、判断が必要な止め方は Claude Code: agent hook（type: "agent"）でファイルやテスト結果を見てから止める・通す

出典

• @gyakuse · 2026-03-09
• 記事「Harness Engineering ベストプラクティス」: nyosegawa.github.io