「このコード、なんでこんな書き方になってるんだろう…」
過去の自分が書いたコードを見返したとき、そう思ったことはありませんか？コミットログには「何を書いたか」は残っていても、「なぜそう書いたか」は残っていないんですよね。😔
最近、海外の開発者コミュニティでこんな体験談が話題になっています。「認証機能の実装が完成していた。でも、なぜそのアプローチを選んだのか、どんな失敗を経てそこに至ったのか──その記録はChatGPTのスレッドと、もう存在しないターミナルの中に散らばっていた」という話です。
これ、AI時代のあるあるすぎて、思わずうなずいてしまいませんか？
🤖 AIコーディング時代に失われる「文脈」の問題
ChatGPTやClaude、GitHub CopilotなどのAIツールと一緒にコードを書くことが当たり前になってきました。でも、こんな情報がどこにも残らないまま消えていきます。
- なぜそのアプローチを選んだのか
- 試してダメだった方法は何か
- AIがどんな警告やアドバイスをくれたか
- 「あとで対応しよう」と先送りにしたタスク
Gitのコミットログはコードの変化を記録してくれますが、意思決定のプロセスまでは保存してくれません。AIとのチャット履歴はブラウザを閉じれば消え、ローカルのターミナルセッションは再起動すれば終わり。開発の「文脈」がどんどん失われていくんです。
✅ 解決策：AIとの会話を「開発ドキュメント」として残す
対策はシンプルです。AIとのやり取りから得た重要な判断を、コードと一緒に残す習慣をつけましょう。おすすめの方法をご紹介します。
① DECISION_LOG.md をリポジトリに作る
コミットと一緒に「なぜこう実装したか」をメモしていくファイルです。
# DECISION_LOG.md
## 2025-07-XX：認証方式の選定
### 選んだアプローチ
JWTではなくセッションベースの認証を採用
### 理由
- JWTのリフレッシュトークン管理が複雑になると判断
- AIとの検討で「小〜中規模なら session の方がシンプル」というアドバイスあり
### 試して失敗したこと
- JWTで実装 → トークン失効処理が煩雑で断念
### 先送りにしたタスク
- レートリミットの実装（要対応）
ポイントをまとめるとこんな感じです👇
- 選んだ理由だけでなく「やめた理由」も書く
- AIからのアドバイスはかいつまんでメモする
- 「あとで」タスクも必ず記録する
② コミットメッセージに「なぜ」を1行添える
よくやりがちなコミットメッセージ → fix: auth
これだと何もわからないですよね。代わりにこうしてみましょう。
fix: セッションタイムアウトを30分→15分に変更
AIとのレビューで「デフォルト30分はセキュリティ的にリスクあり」
との指摘を受けて修正。OWASP推奨値に合わせた。
たった2〜3行で、未来の自分（とチームメンバー）への説明書になります。✨
🔖 まとめ
AIと一緒に開発することで作業スピードは上がりましたが、「なぜそのコードになったか」という文脈まで自動で保存されるわけではありません。
DECISION_LOG.mdの作成やコミットメッセージへの一言追加など、ちょっとした工夫で「未来の自分」がとても助かります。ぜひ今日のプロジェクトから試してみてください！💪
こちらも読まれています
📚 関連商品・おすすめ書籍
※本記事にはアフィリエイトリンクが含まれます。
PR
