AIの「過剰な熱心さ」がプロジェクトに災いをもたらす時
筆者はここ一週間、Anthropicの新しいCLIツールであるClaude Codeを使い倒してきました。認めざるを得ないのは、その文脈理解の速さです。しかし、AIに完全に自由にさせてしまうと、思わず笑ってしまうような（あるいは泣きたくなるような）状況がすぐに発生します。
よくあるシナリオはこうです。auth_service.pyのロジックエラーの修正をClaudeに頼みます。AIは5秒で処理を終えます。しかしその直後、ファイル全体が崩れていることに気づきます。AIがチームのRuffやBlackの設定を無視したからです。ある時は、Claudeが勝手にrequirements.txtにライブラリを追加したものの、pip installを忘れていました。結果として、実行時にあちこちでエラーが発生します。さらに, AIがコードを修正した後に自信満々に「テスト通過」と報告してきたのに、実際にはモックデータのファイルを更新していなかったということもありました。
時間を節約するためにAIを使っているのに、フォーマットの乱れや環境エラーの後始末に追われるのは、本末転倒と言わざるを得ません。
なぜClaude Codeはあなたの規約を「忘れ」てしまうのか？
これはAIの知能が低いからではありません。問題はTool Calls（ツール呼び出し）のメカニズムにあります。ファイルの読み書きやシェルコマンドの実行といった各アクションは、Claudeにとって独立したタスクとして認識されます。プロジェクトにおいて、.jsファイルを修正したら必ずESLintを実行しなければならない、といったルールをデフォルトで知っているわけではないのです。
write_to_fileコマンドを実行する際、Claudeは単に新しい内容で上書きするだけです。個々の操作を各チームの全体的なワークフローに結びつける能力はありません。この欠落こそが、コードベースの一貫性が徐々に失われていく原因なのです。
Hooksを使ってAIを規律に従わせる
これを解決する最も簡単な方法は、修正のたびにコードをフォーマットし直すようClaudeに要求することです。しかし、この方法はトークンを大量に消費し、待ち時間も増えてしまいます。
別の方法は、CLAUDE.mdに指示を書き込むことです。これは比較的有効ですが、要求リストが長すぎるとAIが無視してしまうことがあります。最も抜本的な解決策は、Hooksを使用することです。この仕組みにより、以下の2つの重要なタイミングでスクリプトを自動実行できます。
- Pre-tool-call: AIがコードベースを変更する直前に厳格なチェックを行います。
- Post-tool-call: AIが操作を終えた直後に、クリーンアップ、フォーマット、再チェックを行います。
最初のチェックポイントを設置する
複雑な設定メニューを探す必要はありません。まずは、厳密に監視すべきイベントを特定することから始めましょう。例えば、Pythonファイルが変更されるたびに、システムが自動的にRuffを呼び出すようにします。
これらのスクリプトは.claudecode/hooks/ディレクトリに整理できます。分離して管理することで、メインの設定ファイルを汚さずに、ワークフローの更新や管理が容易になります。
# 整理された自動化管理構造
.claudecode/
└── hooks/
├── pre-save-check.sh
└── post-save-format.shコーディング時間を1時間あたり15分節約する3つの実践的シナリオ
itfromzeroでは、以下のHooksセットを導入したことで、AIによる初歩的なミスを80%削減できました。
1. 標準フォーマットの強制適用
これは不可欠なステップです。このHookにより、シングルクォートかダブルクォートか、インデントのスペース数など、AIが常にルールを遵守することを保証します。
# .claudecode/hooks/post-save-format.sh
#!/bin/bash
file_path=$1
if [[ $file_path == *.py ]]; then
# Pythonフォーマットと修正の実行
ruff format $file_path && ruff check --fix $file_path
elif [[ $file_path == *.ts ]]; then
# TypeScriptのスタイルチェック
npx stylelint --fix $file_path
fi2. セキュリティ・チェック（Security Hook）
AIはバグ修正に集中するあまり、うっかりログファイルにAPIキーを露出させたり、.envを誤った方法で修正したりすることがあります。Pre-tool-callスクリプトにより、機密情報の漏洩を即座に阻止できます。
# ファイル書き込み前にシークレットをチェック
grep -E "password|api_key|token" $TEMP_FILE && echo "危険：機密情報が含まれています！" && exit 1 || exit 03. 環境の自動同期
Claudeがpackage.jsonを修正した場合、スクリプトが自動的にnpm installを実行します。コードは正しいのに、ローカル環境のライブラリ不足で動かないという事態を心配する必要はもうありません。
# Pythonによる自動処理
def post_tool_hook(tool_name, args):
if "package.json" in args.get("path", ""):
print("新しい依存関係を検出しました。インストール中...")
os.system("npm install")CLAUDE.mdとシェルスクリプトによる展開
Claude Codeは急速に進化しているため、最も持続可能な方法は標準作業手順書（SOP）を作成することです。ツールを直接呼び出すのではなく、ラッパースクリプトを使用するようAIに強制しましょう。
システムの指示セクションに以下の行を追加してください。
write_to_file ツールの代わりに、常に `scripts/safe_write.sh` コマンドを使用してください。
このスクリプトは以下の動作をします：
1. 旧ファイルのバックアップを作成する。
2. 新しい内容を書き込む。
3. リンターとテストを実行する。
いずれかのステップで失敗した場合、システムは自動的にリバートします。このアプローチにより、AIによるすべての変更が「アトミック（原子性）」になります。100%完璧でない限り、コードベースへの書き込みは許可されません。
結論：自動化を「門番」にしよう
HooksなしでClaude Codeを使うのは、腕の良い職人を雇いながら、定規を渡さないようなものです。仕事は非常に速いですが、時々壁が数センチ傾き、建物全体の美観を損ねてしまいます。
自動的なチェックポイントを設置することで、AIに鉄の規律を与えているのです。これにより、あなたは細かいディテールから解放され、システムアーキテクチャの設計に完全に集中できるようになります。
今日、20分だけ時間を割いて、基本的なHooksセットを設定してみてください。信じてください、AIのフォーマットミスによる徹夜のトラブル対応を回避できるようになります！
