AIコーディングで「なぜそうしたか」が消える問題──意思決定の記録を残す3つの実践手法

Claude、ChatGPT、GitHub Copilotなどのコーディング支援AIは、もはや開発現場の標準ツールです。数行のプロンプトで数百行のコードが生成され、リファクタリングも瞬時に完了する──この生産性の向上は疑いようがありません。

しかし、AIコーディングが日常化するにつれ、見過ごせない問題が浮上してきました。それは**「意思決定のコンテキストが記録されない」**という本質的な課題です。Gitには差分が残りますが、「なぜこの実装を選んだのか」「どんな議論があったのか」という重要な情報は、AIとの対話の中に埋もれてしまいます。

従来、人間がコードを書く際には、思考プロセス自体が記憶として残りました。「あの要件を満たすために書いた」「パフォーマンスを優先してこのアルゴリズムにした」といった背景情報は、コミットメッセージやプルリクエストの説明、あるいは開発者の記憶として保持されていました。

AI生成コードには、この「記憶の糸」がありません。プロンプトを投げて生成されたコードは、確かに動作します。しかし3ヶ月後に見返したとき、「なぜこの実装なのか」を誰も説明できない状況が生まれます。

具体的に何が問題になるのか

従来の記録手法との比較

**コミットメッセージ文化**との比較が興味深いポイントです。Conventional Commitsなどの規約では、`feat:` や `fix:` といったプレフィックスで「何を」したかを記録しますが、「なぜ」までは強制しません。AIコーディング時代には、この「なぜ」の記録が決定的に重要になります。

**ADR（Architecture Decision Records）**の考え方が、ここで再評価されるべきです。ADRは設計判断を明示的に文書化する手法ですが、従来は大規模な設計判断にのみ適用されてきました。AI時代には、より小さな粒度の判断──たとえば「このライブラリを選んだ理由」「この実装パターンを選択した背景」──まで記録する必要があります。

メリットと注意点の両面分析

**コンテキスト記録のメリット**:

**注意すべき落とし穴**:

適用範囲の考察

このアプローチは**すべてのコード変更に適用すべき**ではありません。効果が高いのは以下のケースです:

1. **複数の選択肢から意図的に選んだ実装**: アルゴリズム選択、ライブラリ選定など

2. **トレードオフを含む判断**: パフォーマンスと可読性、汎用性と効率性など

3. **将来の変更が予想される部分**: ビジネスロジック、設定値、インターフェース設計

4. **チーム共有が必要な知見**: ハマりポイント、特殊な制約条件

逆に、自明な変更（タイポ修正、フォーマット調整など）には不要です。記録の粒度を適切に保つことが、持続可能な運用の鍵となります。

GitHub Copilotとの比較視点

GitHub Copilotは「コードを書く」ことに特化していますが、意思決定の記録機能は持ちません。一方、Claude Code（Artifacts機能）やCursorのようなツールは、対話履歴が比較的保持されやすい設計です。しかし、いずれもプロジェクト全体のコンテキスト管理までは自動化されていません。

この「記録の空白」を埋めるには、**開発者側のワークフロー変更**が不可欠です。AIはあくまでコード生成ツールであり、意思決定の記録責任は人間が持つべきだという認識が重要です。

1. プロンプト＆アウトプットのペア保存

AIに投げたプロンプト（質問・指示）と、生成されたコードをセットで記録します。最も簡単な方法は、プロジェクトルートに `ai-context/` フォルダを作成し、日付やタスクIDでファイルを管理することです。

# ai-context/2026-05-06-user-auth.md

## プロンプト
ユーザー認証機能を実装してください。JWTを使い、リフレッシュトークンも含めてください。

## 生成コード
[コードのスニペットまたはコミットハッシュ]

## 判断のポイント
- セッション方式ではなくJWTを選択した理由: ステートレスなAPI設計のため
- リフレッシュトークンの有効期限を7日に設定: セキュリティとUXのバランス

この記録は、コードレビュー時の参考資料としても機能します。

2. コミットメッセージに「Why」セクションを追加

コミットメッセージの構造を拡張し、意思決定の理由を明記します。

feat: JWT認証機能を実装

What:
- ユーザー登録・ログイン機能
- アクセストークンとリフレッシュトークン

Why:
- ステートレスなAPI設計が将来の水平スケーリングに有利
- モバイルアプリとの連携を見据えてJWT形式を採用

AI-generated: Claude 3.5にて生成、エラーハンドリングは手動で追加

`AI-generated:` タグを追加することで、どの部分がAI生成かを明示できます。

3. 週次の「AI利用振り返り」ミーティング

チーム開発では、週に一度、AIで生成したコードをレビューする時間を設けます。ここでは次の観点で議論します:

この習慣により、チーム全体のAI活用スキルが向上し、同時に重要な意思決定が記録されます。15分程度の短時間でも、継続すれば大きな効果があります。

---

この情報は @solidtofu さんの投稿を参考にしています。