AIに実装を任せると、動くけれど「2年前の書き方」のコードが返ってくる——この感覚、心当たりはありませんか。
私はある案件で、AIが提案してきた非推奨APIをそのままレビューに通してしまい、リリース直前に警告ログの山を見て青ざめたことがあります。原因はシンプルで、LLMの知識は学習データの鮮度に縛られているからです。しかも厄介なのは、AIが「古い」ことを一切自己申告しないこと。堂々と、平気な顔で古いコードを書いてきます。
この記事は「AIは古いコードを書きがち」という問題提起の先——実運用でどう矯正するかに振り切った内容です。個人で運用しているプロジェクトで確立した5つのパターンと、コピペで使えるチートシートをまとめました。
なぜAIは「古いコード」を書くのか
理由は大きく3つあります。
- 学習データのカットオフ: モデルの知識はある時点で止まっている。最新のメジャーバージョンで変わったAPIは知らない。
- 多数決バイアス: 学習データには「古い書き方」のサンプルの方が圧倒的に多い。世に出回っているコードの蓄積は、新しい記法より古い記法に偏る。だからAIは無難な＝古い方を選びがち。
- バージョン無指定のプロンプト: こちらが「Reactで書いて」としか言わなければ、AIは「どのバージョンか」を自分で決める。そして往々にして古い方に倒れる。
つまり、放っておけば古くなるのはモデルの性質であり、運用側で明示的に矯正しない限り直らない。ここを「AIが賢くなるのを待つ」ではなく「仕組みで殴る」に切り替えたのが、以降のパターン集です。
「古い」には3つの顔がある
矯正の前に、敵の正体を分けておきます。検出のしやすさが全然違うからです。
| 種類 | 例 | 検出難易度 |
|---|---|---|
| 非推奨API | 動くが警告が出る旧メソッド | 中（警告ログで気づける） |
| 古いイディオム | 動くし警告も出ない旧来の書き方 | 高（レビューでしか気づけない） |
| 存在しないAPI | 新旧が混ざったハルシネーション | 低（実行すれば即エラー） |
一番やっかいなのは真ん中の「古いイディオム」です。動くし、テストも通るし、警告も出ない。だからこそレビュー観点を仕込まないとすり抜けます。
3つ目の「存在しないAPI」、いわゆるハルシネーションも侮れません。実際に私も、生成コードに存在しないライブラリのメソッドが紛れ込み、そのまま動かしてエラー、デバッグに時間を取られたことが何度もありました。当時はハルシネーション由来のエラーが月10件ほど発生していて、これが後述のパターン2を作るきっかけになりました。
矯正パターン集（5つ）
パターン1: CLAUDE.mdにバージョンを明記する
一番効くのがこれです。AIへの前提共有ファイル（Claude CodeならCLAUDE.md）に、使用しているバージョンを名指しで書く。
新規プロジェクトでは、毎回同じ前提をチャットで説明していて1回あたり5〜10分かかっていました。そこで技術スタック・規約・禁止事項を約200行のCLAUDE.mdにまとめたところ、前提説明が不要になり1日あたり約30分を削減。ついでに、ここにバージョンを書くだけで古いコードの発生率が体感で激減しました。
## 技術スタック（バージョン厳守）
- Node.js 22 LTS / TypeScript 5.x
- フロントエンド: React 19（Server Components 前提。class component 禁止）
- 状態管理: 標準のuseState / useReducer（旧来のライフサイクルメソッドは使わない）
## 禁止事項
- 非推奨API・レガシーイディオムの使用（不明ならまず確認すること）
- バージョン不明のまま実装を進めない
ポイントは「React 19」のようにメジャーバージョンを数字で書くこと。「最新の」という曖昧語は効きません。AIにとっての「最新」は学習時点の最新だからです。
パターン2: 外部APIには公式ドキュメントURLを添えさせる
ハルシネーション対策の本丸。CLAUDE.mdに次の一文を足しました。
## 外部ライブラリ利用時のルール
- 外部ライブラリのメソッドを使う場合は、公式ドキュメントの該当URLをコメントで添えること
- URLを提示できないメソッドは「使わない」か「要確認」と明記する
これに加えて生成コードの自動テスト実行をワークフローに組み込むと、効果が跳ね上がります。私の環境では、この2つでハルシネーション由来のエラーが月10件から2件に減りました。URLを添えさせることでAIが「本当に存在するか」を自問するようになり、テスト実行で残りをすくい取る、という二段構えです。
注意: URL自体をでっち上げてくることもあります（嘘URL問題）。なので「URLを書かせて満足」ではなく、必ずテスト実行とセットで運用します。
パターン3: 最新のAPI仕様を「参照ファイル」として渡す
カットオフ以降に変わったAPIは、AIに知りようがありません。ここはこちらから最新情報を渡すしかない。
私は社内ナレッジが400ページ超のWikiに散在していた問題を、マークダウン化してRAG構成で解決したことがあります。同じ発想で、変更が激しいライブラリの公式ドキュメント（移行ガイドやCHANGELOG）を抜粋してプロジェクト内に置き、Claude CodeのSkillsや参照ファイルとして読ませています。「知らないなら教える」——RAGは既存資産を活かすAI活用の王道で、ここでも効きます。チャンクは要点だけに絞るのがコツです（全部貼ると逆に埋もれる）。
パターン4: レビューで「バージョン観点」を重要度別に検出させる
前述の「古いイディオム」は動いてしまうので、レビューで捕まえるしかありません。ただ、AIレビューは指摘の粒度がバラバラで、些細なスタイル指摘と重大な問題が混在しがちでした。
そこでレビュー依頼プロンプトに、重要度レベルの分類基準をFew-shot例として3パターン添付したところ、出力が整理され、重要な指摘の見逃しがなくなり、確認時間が半分になりました。バージョン観点を組み込むと、こんなプロンプトになります。
以下のコードをレビューし、指摘を重要度別に分類してください。
特に「非推奨API」「古いイディオム」を Critical / Warning として検出すること。
分類基準（例）:
- Critical: 非推奨で将来削除されるAPI（例: componentWillMount → useEffect）
- Warning: 動くが現在は非推奨のイディオム（例: 旧来のライフサイクル記法）
- Info: 新しい書き方が存在するスタイル上の改善提案
出力フォーマット:
[Critical] file:line — 指摘内容 — 推奨: ...
ルールを文章で長々書くより、具体例を3つ見せる方が確実に効きます。
パターン5: 移行タスクは「現行と目標のバージョンを名指し」する
古い技術からの移行こそAIの得意領域ですが、ここでもバージョン明示が効きます。jQueryで書かれた約3,000行のフロントを移行したときは、コンポーネント単位で読み込ませ、状態管理はuseState、Ajaxはfetch APIに、と変換後の作法を具体的に指定しました。結果、約2,500行のReactコードに変換でき、1週間の見積もりが3日で完了。バージョンと作法を名指しした分、生成物が古い書き方に戻りませんでした。
設計段階での壁打ちも有効です。一人開発でレビュー相手がいなかったとき、設計書をAIに読ませ「経験20年のシニアアーキテクトとして問題点を指摘して」と依頼したら、5つの改善提案のうち2つは本番で問題になりうる重大な設計漏れでした。「今どきはこう書く」という観点をレビュー役に持たせると、古い設計判断も早期に矯正できます。
チートシート：AIの古コード矯正 早見表
| フェーズ | やること | 具体アクション |
|---|---|---|
| 事前設定 | バージョン明記 | CLAUDE.mdにメジャーバージョンを数字で書く |
| 事前設定 | 禁止事項の宣言 | 非推奨API・レガシーイディオムを明示的に禁止 |
| 実装時 | 出典の強制 | 外部APIは公式ドキュメントURLをコメントで添えさせる |
| 実装時 | 最新情報の供給 | 移行ガイド/CHANGELOGを参照ファイル・Skillsで渡す |
| 検証時 | テスト自動実行 | ハルシネーション・存在しないAPIをすくい取る |
| レビュー時 | 重要度別検出 | Few-shot例でバージョン観点を Critical/Warning 分類 |
| 移行時 | 双方向の名指し | 現行と目標のバージョン・変換後の作法を具体指定 |
運用して分かった、外してはいけない前提
- バージョンを書いても、たまに古いコードは出る。だから「書けば終わり」ではなく、テスト実行とレビューで最終的に捕まえる多層防御にする。
- URLは嘘をつくことがある。出典を書かせる仕組みは、必ず自動テストとセットで。
- 参照ファイルは要点だけ。全部渡すと重要な差分が埋もれて逆効果になる。
結局のところ、AIが古いコードを書くのは「バグ」ではなく「性質」です。ならば直す方向ではなく、性質を前提に運用の仕組みで矯正する。バージョンを名指しし、出典を強制し、最新情報を供給し、テストとレビューで受ける——この多層防御が、私が実運用でたどり着いた現実解でした。
この記事が参考になったら、いいね・ストックしていただけると励みになります。
Claude Code・AIエージェント・業務自動化の実装Tipsを継続的に発信しています。フォローしておくと新着が届きます。
みなさんは、AIが古いコードを書かないようにどんな工夫をしていますか？ CLAUDE.mdの書き方やレビューの仕込み方など、ぜひコメントで教えてください。