HooksとSubagentsを使ってClaude Codeで恥ずかしいコードを書かないようにする

Last updated at 2025-08-06Posted at 2025-08-03

[2025/08/04 更新] quality-gate-keeperの結果から直接判定方式にアップデートしました。より確実な品質チェックが可能になりました。

Claude Code皆さん使ってますか？皆さんこんな経験ないでしょうか？

Claude Codeに書いてもらったコードを確認してみたら...

謎のコメントがびっしり書いてあった
テストコードでassertが抜けていてprintlnだけ書いてあった
assertの期待結果が間違っていて、テストが通るように書いてあった
不要なif文やpropertyが増えて複雑になっていた

コードのチェックが抜けてこういうコードをコミットしてしまうことはよくあります。実際に自分は一度assertの期待結果が間違っていてコードレビューで指摘されました。

こういった「恥ずかしいコード」をコミットしてしまう前に品質チェックする仕組みを作ってみました。似たようなことは皆さんすでにやっていると思いますが、私はやっていなかったので作ってメモしておきます。HookとSubagentを使ったアプローチは色々あると思いますが、自分がやっている方法を紹介します。

全体の流れ

一言でいうと: Final Result: ✅ APPROVEDをquality-gate-keeper Subagentに言わせるまで、HookでSubagent起動と修正を繰り返す仕組みです。

実行フロー

通常の開発作業中: Claude Codeは普通にコードを書きます
作業終了時（Stop Hook）: 変更がある場合、quality-gate-keeper Subagentの起動を指示
コミット時（PreToolUse Hook）: git commit実行時に、最新のquality-gate-keeper判定を確認
- Final Result: ✅ APPROVEDが履歴にある → StopやCommitをそのまま許可
- Final Result: ❌ REJECTEDが履歴にある → quality-gate-keeperのSubagentの起動するように指示

コミットされてしまうと差分のレビューが難しくなるので、作業終了時とコミット前の2つのタイミングで品質チェックを入れています。

判定システムについて

quality-gate-keeper Subagentが必ず明確な判定をして、それがAPPROVEDになるまで、繰り返させます。
以下のフォーマットで出力するように指示し、それを元に繰り返しを行います。

Final Result: ✅ APPROVED - 品質基準をクリア
Final Result: ❌ REJECTED - 品質問題があり修正が必要

なぜmainのClaude Codeに"承認を得た"などを言わせるパスフレーズを廃止したのか

以前のバージョンでは、Claude Codeの「すぐルール忘れる問題」をHooksで解決すると同様のパスフレーズシステムを使っていました。

しかし、パスフレーズシステムには問題があったので、サブエージェントが許可したときのみにしました：

Claude Codeが「承認を得た」と言っても、実際には品質問題が残っている場合がある
パスフレーズを言えば通過できるため、品質チェックをバイパスできてしまう

判定の仕組み

get_quality_result()関数がtranscript(チャット履歴)から最新の「Final Result:」を検索し、その内容に基づいて処理を決定します。

ただし、一度APPROVEDが出てもその後にファイル編集（Edit、Writeなど）があれば、その承認は自動的に無効化されます。これにより、古い承認でコミットしてしまう問題を防ぎます。

インストール方法（グローバル設定）

GitHubリポジトリをクローン：

git clone https://github.com/takahirom/claude-code-quality-gate-example.git ~/claude-quality-gate
chmod +x ~/claude-quality-gate/.claude/scripts/*.sh

グローバルのClaude Code設定（~/.claude/settings.json）に追加：

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "~/claude-quality-gate/.claude/scripts/quality-gate-pre-commit.sh",
            "timeout": 30
          }
        ]
      }
    ],
    "Stop": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "command",
            "command": "~/claude-quality-gate/.claude/scripts/quality-gate-stop.sh",
            "timeout": 30
          }
        ]
      }
    ]
  }
}

Subagent定義をリンク：

mkdir -p ~/.claude/agents
ln -s ~/claude-quality-gate/.claude/agents/quality-gate-keeper.md ~/.claude/agents/

必要な依存関係をインストール：

# macOS
brew install jq

# Ubuntu/Debian  
sudo apt-get install jq

Hookの設定

.claude/settings.jsonに以下の設定を追加します：

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "./.claude/scripts/quality-gate-pre-commit.sh",
            "timeout": 30
          }
        ]
      }
    ],
    "Stop": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "command",
            "command": "./.claude/scripts/quality-gate-stop.sh",
            "timeout": 30
          }
        ]
      }
    ]
  }
}

スクリプトの概要

このシステムは3つの主要なスクリプトで構成されています：

1. 共通設定ファイル（common-config.sh）

依存関係（jq, git）のチェック機能
get_quality_result()関数：transcriptから最新の判定を取得（ファイル編集後の古い承認は無効化）
返り値：0=APPROVED、1=REJECTED、2=判定なし

2. Stop Hook スクリプト（quality-gate-stop.sh）

作業終了時に自動実行
Gitの変更を検出して品質チェックの必要性を判断
transcriptから最新のFinal Resultを検索
APPROVEDなら通過、それ以外は品質チェックを要求

3. PreToolUse Hook スクリプト（quality-gate-pre-commit.sh）

git commitコマンド実行時に動作
最新のquality-gate-keeper判定を確認
APPROVED：コミット許可
REJECTED：コミットブロック、修正を要求
判定なし：quality-gate-keeper実行を要求

すべてのスクリプトはGitHubリポジトリで確認できます。

Subagent設定（quality-gate-keeper.md）

品質チェックを実行するSubagentの定義ファイルです。ここにはあなたがよくClaudeに指摘する内容を記載しておくと良いでしょう。

詳細な設定内容はGitHubリポジトリで確認できます。私はこの記事の最初に書いた困ったポイント（謎のコメント、assertの欠落など）を検出するルールを書いています。

実装のポイント

うまく動作しない場合は、ログファイルを確認したり、一時的にtranscriptの内容を出力してみると原因が分かりやすいです。

まとめ

HookとSubagentを組み合わせることで、Claude Codeが生成するコードの品質をチェックする仕組みを作ることができました。この仕組みにより、「恥ずかしいコード」がリポジトリに混入するリスクを減らし、コードレビューの負担も軽減できます。

皆さんもプロジェクトに合わせた品質ゲートを作ってみてはいかがでしょうか？

quality-gate-keeperを複数のSubagentに分けて並列実行するなど、もっと高度な使い方もできると思うので、ぜひ試してみてください。

注意事項

REJECTED判定について: quality-gate-keeperがREJECTEDと判定した場合、必ず修正が必要です。パスフレーズで抜け出せた以前のシステムと異なり、実際に問題を修正しないと先に進めません。これは無限ループに陥るリスクがあるため、品質基準が厳しすぎる場合は、quality-gate-keeper.mdで基準を調整するか、スクリプトを調整してみてください。

自己責任でご利用ください。

変更履歴

2025/08/04 - quality-gate-keeperの結果から直接判定方式

パスフレーズシステムを廃止
quality-gate-keeperの判定（APPROVED/REJECTED）を直接チェック
get_quality_result()関数を追加
ファイル編集後の古い承認を自動的に無効化する機能を実装

2025/08/03 - 初版

パスフレーズベースの品質ゲートシステム
Stop HookとPreToolUse Hookの実装
quality-gate-keeper Subagentの作成

参考リンク

You get articles that match your needs
You can efficiently read back useful information
You can use dark theme

What you can do with signing up