はじめに
2025年の12月を迎え、ソフトウェア開発の現場におけるAI活用は「コードを書かせる」フェーズから「タスクを完遂させる」フェーズへと、よりシフトしつつあると感じています。
2024年がGitHub CopilotやCursorによる「入力支援」の普及が進んだ年だったとすれば、2025年は Agentic Workflow がより現実的な選択肢として広がってきた年、と捉えることもできます。
しかし、AIのエージェント化が進むにつれ、私たちは新たなボトルネックに直面しています。それは、「生成されたコードの正当性をいかに低コストで担保するかです。
- AIが高速に生成した実装は、既存のテストを破壊していないか？
- 修正を依頼した後、その品質チェックを行うのは結局人間ではないか？
- AIの待ち時間に発生するコンテキストスイッチが、生産性向上の恩恵を相殺していないか？
本記事では、Claude Code の拡張性を活用し、開発プロセスにおける 「実装→品質チェック→修正」 のループを、可能な範囲でAIが主導して回す仕組みを紹介します。
1. 課題設定：分断された品質チェックプロセス
従来のAIコーディングアシスタントとの対話（Chat）では、フローが「実装」で止まり、品質チェックが分断されがちでした。
- AI: コードを実装（ここでAIのターン終了）
- 人間: コンテキストを切り替え、ターミナルでテスト実行
- 人間: エラーログを目視確認し、コピペしてAIにフィードバック
- AI: 再修正
このフローにおける問題は、「品質チェックの責務（Feedback Loop）」が人間側に残りやすい 点です。その結果、人間が「実行・ログ転記・再依頼」を都度担うことになり、アーキテクチャ設計や仕様検討などに集中しづらくなります。
目指したい姿：品質チェックまでの委譲
ここで目指したいのは、人間が「司令塔」として振る舞い、AIが「作業者」として、品質チェックまでを一連で進められるフローです。
これを実現するために実装したのが、suggest-check フック と カスタムコマンド /check です。
2. 実装詳細
2-1. suggest-check フック：認知的ナッジの実装
AIエージェントは、明示的な指示がない限り「タスク完了」と同時に停止します。ここで人間が品質チェックを忘れないよう、システム側から適切なアクションを促す（ナッジする）仕組みが必要です。
Claude Codeの PostToolUse フック（または同等のイベントハンドラ）を利用し、ファイル変更が発生した直後に提案メッセージを表示します。
.claude/hooks/suggest-check.sh
#!/bin/bash
# Hook script to suggest running /check after file modifications
# This script is triggered by PostToolUse hook for Write|Edit operations
# Simple suggestion message to the user
cat << 'EOF'
💡 コードを変更しました。品質チェックを実行しますか？
/check - 全てのチェックを実行（typecheck + lint + tests）
/check -f - 全てのチェック+エラー自動修正
/check typecheck -f - 型チェック+型エラー自動修正
/check lint -f - 自動修正付きリント
/check backend -f - バックエンドテスト+失敗したテスト修正
/check frontend -f - フロントエンドテスト+失敗したテスト修正
/check backend --coverage - バックエンドカバレッジ
/check frontend --coverage - フロントエンドカバレッジ
ヒント: -f は --fix のショートカットです
EOF
exit 0
この仕組みによって、新たに開発に参加したメンバーでも必要なコマンドを把握でき、AIとの対話の流れを途切れさせることなく、スムーズに品質チェックのフェーズへ移行できます。
2-2. /check コマンド：品質チェックロジックのカプセル化
次に、提案されたコマンドの中身である /check を実装します。
これは単なるシェルスクリプトのエイリアスではなく、「AIへの振る舞い指示（Prompt）」 と 「実行環境の抽象化（Script）」 を分離した構造を持たせています。
Layer 1: AIへの指示書 (check.md)
カスタムスラッシュコマンドの定義ファイルには、AIに対する「役割定義（System Prompt）」を記述します。ここで重要なのは、「エラー発生時の判断基準」 を明確に与えることです。
.claude/commands/check.md（抜粋）
---
description: 型チェック、リント、テストを自動修正オプション付きで実行
argument-hint: [typecheck|lint|backend|frontend|all] [test-path] [--fix] [--coverage] [--verbose]
---
プロジェクトの品質チェックとテストを実行します。
## 引数の解析
- **重要**: 全ての引数をチェックして以下のフラグが含まれているかを確認してください：
- `--fix` または `-f`: エラーの自動修正を有効化（`-f`は`--fix`のショートカット）
- `--coverage`: テストカバレッジを有効化
- `--verbose`: 詳細出力を有効化
Layer 2: 実行環境の抽象化 (run-checks.sh)
AIに任せると不安定になりがちな「環境依存の処理（DB接続、パス解決など）」は、堅牢なシェルスクリプトで隠蔽します。AIにDockerコマンドを一から叩かせるのではなく、抽象化されたインターフェースを提供することが安定稼働の鍵です。
.claude/scripts/run-checks.sh（抜粋）
#!/bin/bash
set -e
# 第一引数が -f の場合、allに変更して --fix を追加
CHECK_TYPE=${1:-all}
if [ "$CHECK_TYPE" = "-f" ]; then
CHECK_TYPE="all"
shift || true
EXTRA_ARGS="--fix $@"
else
shift || true
EXTRA_ARGS="$@"
fi
# -f を --fix に変換（ショートカット）
EXTRA_ARGS=$(echo "$EXTRA_ARGS" | sed -e 's/\(^\| \)-f\( \|$\)/\1--fix\2/g')
# backend 実行時は、ローカルDBの疎通をチェックして必要なら起動
if ! nc -z localhost "$DB_PORT" 2>/dev/null; then
pnpm test-db:setup
fi
このように、「高度な判断はMarkdown（AI）に」、「定型的な処理はShell（スクリプト）に」 責務を分離することで、柔軟性と安定性を両立させたコマンドを実現しています。
3. 実際の開発体験
このワークフローを導入して以降、開発体験は一定程度改善したと感じています。
Before(AI任せの場合)
バグ修正を依頼 → テストが落ちる → ログをコピペしてAIに投げる → また別のテストが落ちる → （品質チェックが分断されがち）
After
バグ修正を依頼 → /check --fix を入力 → （待つ） → 「全テスト通過しました」の報告を確認
特に、「実装を変更したらテストが落ちた → 実はテストデータ側の不整合だった → AIがテストデータを修正して解決」 のような一連の流れを短いサイクルで回せるようになると、AIが「コードを書く」だけでなく「通すところまで」を支援できます。
また、実際にはAI任せにせず、手作業での微修正や補完を繰り返しながら作成しており、完全な自動化を目指すのではなく、AIと人間が役割を分担しながら品質を仕上げていくワークフローとして、私は運用しています。
4. おわりに
今回紹介した内容は小さな工夫ですが、AIに「実装→品質チェック→修正」を一気通貫で進めてもらえると、日々のコンテキストスイッチを減らせる場面がありました。
今後もキャッチアップを続けつつ、実際に使ってみた知見をアウトプットしていきたいと思います。