Claude Codeに「理由も書け」と指示してから変わったこと
Claude Codeでブログ基盤（urisol.com / urinosuke.com）を構築して約半年、実装スピードは上がったが同時に「なぜそのコードになったか」の記憶が残らない問題に直面した。数週間後に似た修正を依頼すると、前回と異なるアプローチで書かれ、過去の失敗が活かされない。
対策として「コードを出力する前に、なぜその実装を選んだか理由を3行で書け」というルールをプロンプトに追加した。結果、同じ失敗の繰り返しが減り、過去の判断履歴が自然に蓄積されるようになった。
AI開発で人間側の判断力を下げないために仕掛けた3つの運用を記録する。
① コード出力の前に「選択理由」を3行で言語化させる
最初の仕掛けは、実装コードを出す前に必ず選択理由を書かせること。プロンプトには次のように指示している。
「コードを出力する前に、なぜこの実装を選んだか理由を3行以内で書け。他の選択肢との比較も含めること。」
例えば、Astro Content Collectionsのスキーマ修正を依頼したとき、Claudeは「Zod の .optional() より .nullable() を選んだ理由：フロントマター省略時に undefined でなく null を明示的に扱うことで、テンプレート側の条件分岐を統一できるため」と先に説明してからコードを出す。
この「理由が先」の順序が効く。コードだけを見て「動くからOK」で流すと、次に似た修正を頼んだとき別の方法で書かれ、過去の失敗（例: .optional() だと undefined チェックが漏れてビルドエラー）を繰り返す。理由が残ることで、次回は「前回 .nullable() を選んだ理由」を引き継げる。
② 失敗事例を「なぜ失敗したか」付きで記録する
2つ目は、失敗したコードをそのまま捨てず「なぜ失敗したか」を必ずClaudeに言語化させること。
実例として、GitHub Actionsの自動投稿スクリプトで「記事ファイルのコミット後、即座にビルドを実行するとファイルが見つからずエラー」という失敗があった。Claudeに「なぜこのエラーが起きたか、Git操作とActionsの実行タイミングの観点で説明しろ」と指示すると、次のように返ってきた。
「git commit 直後に git push せず即座に npm run build を実行したため、リモートにファイルが反映されておらずActions側で参照できなかった。git push の完了を待つステップが必要。」
この説明をプロンプトの「失敗事例」セクションに追記することで、次に類似のワークフローを書くとき、Claudeは「前回 git push の待機ステップが必要だった理由」を参照して最初から正しく書ける。
失敗コードだけを捨てると、同じ失敗を繰り返す。「なぜ失敗したか」の言語化が次の判断材料になる。
③ 定期的に「判断履歴」を要約させて型を共有する
3つ目は、月に1回程度、Claudeに「今月行った実装判断の履歴を要約しろ」と指示すること。
例えば先月末に依頼した要約では、次のような型が抽出された。
- Astroのルーティングでは動的パラメータより静的生成を優先（ビルド時エラー検出のため）
- 環境変数の参照は
import.meta.envより Astro Config 経由で一元化（型安全性） - Cloudflare Pages のデプロイ設定は
.tomlファイルでなくダッシュボード側で管理（Git履歴の肥大化防止）
これらの「判断の型」をプロンプトの冒頭に追記することで、新しい機能を依頼したときも一貫した実装方針が保たれる。型が共有されていないと、同じ人間（私）が依頼しても毎回異なる流儀で書かれ、コードベース全体の一貫性が崩れる。
月次の要約作業は15分程度で済むが、判断の型を明文化することで次の1ヶ月の開発効率が上がる。
Claude Codeは「理由を説明する訓練相手」として使える
Claude Codeに理由を言語化させる運用を続けて気づいたのは、これが「人間側の判断力を育てる訓練」にもなることだ。
Claudeが「なぜこの実装を選んだか」を説明するとき、その理由を読んで「それは違う、別の理由で選ぶべきだった」と気づくことがある。逆に「その理由は盲点だった、次から判断基準に入れる」と学ぶこともある。
AIに丸投げして「動くコードが出ればOK」で流すと、人間側の判断力は下がる。理由を毎回説明させることで、判断のプロセスを可視化し、次の判断材料として蓄積できる。
Claude Codeは実装の速度を上げるツールだが、同時に「理由を説明する訓練相手」としても使える。同じ失敗を繰り返さない開発は、コードでなく判断履歴を残すことから始まる。
参考
- LLMのプロンプトエンジニアリング — Chain-of-Thought（思考の連鎖）の概念が、理由を先に書かせる設計の理論的支柱
- 実践Claude Code入門 — 失敗事例の言語化と型の共有がチーム導入の鍵と述べられている
- Anthropic Claude公式ドキュメント
関連記事
- 『実践Claude Code入門』を読んで自社ブログにサブエージェント設計を導入した実録：チーム開発の知見を一人開発に転用する3つの適用例
- AI社員に「予測を先に言わせる」ルールで判断力が育った話：Claude Codeに答え合わせの前に宣言させる学習設計3段階
- 38歳が『達人プログラマー（第2版）』を読んでClaude Code時代に再確認した「何を書かないか」の判断軸3つ：DRY・直交性・信頼性の原則を一人開発に適用する
まとめて読む: AI活用・自動化