AI コーディングで陥るアンチパターン11選 — 観察と文献を4カテゴリで整理した

Claude Code、Cursor、Codex、Antigravity といったツールが日常使いされるようになって、「ふだんよく見る失敗の形」がいくつかのパターンに固まってきました。
2026年6月時点で、複数の実践者ブログと一次ソースに繰り返し出てくるものをまとめ、自分が運用しながら観察したものと突き合わせて整理しました。

この記事では、よく見るアンチパターンを11個、4つのカテゴリに分けて並べます。
それぞれの「典型的な姿」「なぜ起きるか」「避け方の最小フォーマット」を、できるだけ短く揃えました。
全部を自分が踏んだわけではないので、文献ベースのものは出典付きで、自分の運用観察のものは「私の運用では」と書き分けています。

なぜこのカテゴリ分けか

11個を1列に並べると忘れます。
それぞれの裏側にある「なぜそうなるか」で4つに分けると、対策が CLAUDE.md や AGENTS.md にそのまま書ける形になります。

• A. 検証不足系: 「動いた」と言うのに動かない、テストが通っているふりをする、計画なしで走り出す

• B. 仮定の暗黙取り系: 解釈を勝手に選ぶ、触らなくていい所を触る、リファクタを勝手にする

• C. 知識の古さ系: 古い API を hallucinate、存在しないパッケージを呼ぶ、バージョンを混ぜる

• D. 過剰系・横滑り系: 過剰抽象化、危険なデフォルトを選ぶ

順に見ていきます。

A. 「動いた」と言うのに動かない系 — 検証不足

1. 「実装しました、テストも通っています」と返ってくるが、テストを実行していない

最も古典的で、最もよく見るパターンです。
LLM はテストを書くところまでは得意ですが、書いた直後に「これで通るはずです」と言い切って次に進もうとする傾向があります。
実際にテストを走らせる前にレポートが返ってくる、というかたちで現れます。

避け方は「返答する前に必ずテストを走らせて、結果を貼ってください」を CLAUDE.md なり system prompt に明示で書くことです。
Claude Code なら Plan Mode を有効にしておくと、計画段階で「テスト実行ステップ」が組み込まれるので、走らせ忘れが減ります（Best practices for Claude Code）。

2. テストが赤くなるので、コードでなくテストを書き換える

これも頻出です。
失敗するテストを直そうとせず、テスト側の期待値や assertion を「現状に合わせて」緩める、という方向に走ります。
表面上は緑に戻るのでパスしますが、本来検出したかった不具合は静かに残ります。

避け方は「テスト側を変更したい場合は、必ず先に理由をこちらに確認してから」を明記することです。
それでもやってくる場合は、テストファイル自体を `permissions: { deny: ["test_*"] }` のような形で書き込み禁止にする、という強い手も使えます。

3. プランを立てずにいきなり実装に入る

「Claude Code に Plan Mode があるのは、これを防ぐためです」と Anthropic 公式ドキュメントが明言しています。
複数ファイルにまたがる変更を、計画なしで走り出して、途中で迷子になるか、半端に書き散らかすか、のどちらかになるのが典型です。

避け方は単純で、重い変更の前は「まずプランだけ出して、実装は私の承認のあと」と固定することです。
Plan Mode を恒久的に ON にしておくか、ultracode を使うことで「軽い質問は即答、重いタスクは workflow + 検証」が自動でかかります。

B. 仮定を黙って取る系 — 確認不足

ここは Andrej Karpathy が SNS で「LLM コーディングのいちばん大きな失敗パターン」として繰り返し挙げているところです（andrej-karpathy-skills に整理されています）。

4. あいまいな指示の解釈を、勝手に1つ選んで走り続ける

「ユーザー一覧の表示を直して」のような曖昧な指示に対して、本来なら「どこの表示か」「並び順は」「ページネーションを変えるか」を聞き返すべきところを、内部で勝手に1つの解釈を採用してそれで作り始める、という挙動です。
途中の出力を読まないと、間違った方向に進んでいることに気づけません。

避け方は、Karpathy の4原則の Assumption Surfacing（仮定の表面化） を CLAUDE.md に1行入れることです。
「曖昧な指示を受けたとき、解釈を選ぶ前に必ず仮定をリスト化して提示し、こちらの確認を待つ」と書いておくと、解釈を黙って取らなくなります。

5. 触らなくていい所まで「ついでに」リファクタする

頼んでいないファイルのフォーマットを変えたり、無関係な変数名を改名したり、見つけたタイポを直したりする挙動です。
本人としては親切のつもりですが、diff が膨らんで、本来の変更がレビューしづらくなり、副作用も入りやすくなります。

避け方は Karpathy 4原則の Surgical Changes（外科的な変更） をそのまま採用することです。
「触らなくていい所には触らない。自分が作った汚れだけを片付け、隣のコードや書式を『ついでに改善』しない」と CLAUDE.md に書いておきます。
それでもやりたい場合は、必ず別 PR / 別コミットに分けるルールを併記します。

6. 「コメントを残しておきました」「TODO を入れておきました」で誤魔化す

実装しきれない部分を、コメントや `TODO:` で埋めて「全体としては完了」と報告するパターンです。
特に「ここはあとで実装してください」というコメントで終わると、人間側がそのまま忘れてマージしてしまいます。

避け方は「未実装の関数や TODO で済ませた箇所がある場合、必ずレポートの冒頭に列挙する」を CLAUDE.md で固定することです。
さらに `grep -rE "TODO|FIXME|XXX" src/` のような確認コマンドを自動で実行させ、新規追加された TODO を提示させる、というのも効きます。

C. 知識の古さ系 — hallucinate と古い API

7. ライブラリの古いバージョンの API を、自信を持って書く

Next.js、React、Prisma、Tailwind のように変化の速いライブラリでは、LLM の学習データに残っている古い書き方をそのまま提案してくる、というのがよくあります。
12 だった頃の Next.js の getServerSideProps を、15 のプロジェクトで提案してくるような形です。
ローカルでは動くこともあるので、本番に出てから気づくケースが特に厄介です。

避け方は、最新ドキュメントを取りに行く仕組みを差し込むことです。
Context7 のような MCP プラグインを入れて「該当ライブラリの最新ドキュメントを毎回プロンプトに注入させる」と、この種の hallucinate がだいぶ減ります。
あるいは、CLAUDE.md に「ライブラリのバージョン特定を、まず `package.json` を読むことから始めてください」と書くだけでも違います。

8. 存在しないパッケージ名を提案する

「dependency hallucination」と呼ばれる挙動です。
パターンマッチで「ありそうな名前」を生成して、`npm install` させようとします。
セキュリティ研究者によると、攻撃者がこの hallucinate されやすい名前で実際にパッケージを公開して悪意のコードを混ぜる「slopsquatting」という攻撃手法も観測されています。

避け方は「`npm install` / `pip install` する前に、必ず npmjs.com / pypi.org で実在を確認するコマンドを実行してから」を CLAUDE.md に書くことです。
あるいは Anthropic の Best Practices にあるように、依存追加の前にユーザー確認を入れる permission policy を有効にします。

9. 異なるメジャーバージョンの書き方を1ファイル内で混ぜる

Tailwind v3 と v4 の書き方、React Class Component と Function Component、ESLint 8 系と 9 系の設定など、世代の違う書き方が同じファイル内に混ざる、というパターンです。
ここも変化の速い領域でよく見ます。

避け方は2段階で、まず CLAUDE.md に「この project の前提バージョン」を明示すること（例: `Next.js: 15.3, React: 19, Tailwind: 4.0`）。
そのうえで「これら以外のバージョンの書き方が混ざっていないか、変更後に確認する」を Plan Mode のステップに入れる、という形です。

D. 過剰系・横滑り系 — やりすぎと誤魔化し

10. 過剰抽象化と、要求されていない汎用化

「もしかしたら将来こういう拡張が必要になるかもしれないので」という理由で、interface を切り、戦略パターンを使い、設定ファイルに切り出す、という風に肥らせるパターンです。
具体的な要求は1つの URL を fetch するだけだったのに、抽象的な HTTPClient interface を作って依存性注入する、というような展開がよく起きます。

避け方は Karpathy 4原則の Simplicity（簡潔さ） をそのまま借ります。
「求められた問題だけを解く最小のコードを書く。投機的な機能、要求されていない抽象化、使われない柔軟性を入れない」と CLAUDE.md に明記します。
私の運用では、これを書く前と後で、生成される実装行数が体感で半分くらいに減りました。

11. セキュリティ的に危険なデフォルトを「動くから」と選ぶ

Vibe coding antipatterns（The Weather Report） でも筆頭に挙げられているパターンです。
具体的には、Supabase の service-role キーをブラウザ側のコードに含める、Storage バケットを「画像アップロードができるように」と全公開に切り替える、`.env.example` に本物のキーを書く、というような選択をしてしまいます。
動かすには楽な道なので、AI が「動くまでの最短手」を取りに行くと、こちらに流れがちです。

避け方は、CLAUDE.md に 明示の禁止リストを書くことです。
「サービスロール / アドミン権限のキーをクライアント側に置かない」「ストレージバケットのデフォルトを `public` に変えない」「`.env.example` には型と説明だけ書き、値は書かない」のように、具体的な禁則として書きます。
さらに、コミット直前に `grep -rE "service_role|sk_live|secret" --include=".{ts,tsx,js,jsx,env}" .` のようなチェックを CI に組み込むと、誤って漏れた時に止まります。

11個をどう CLAUDE.md に書き込むか

11個を全部書き写すと CLAUDE.md が長くなりすぎて、Claude が読んでもブレます。
私の運用では、4カテゴリの代表だけ書き、残りはリンクで参照する形にしています。

## 開発の原則（このプロジェクトで AI と一緒に書く時の規律）

### 検証不足を防ぐ
- 「実装しました」と返す前に、必ずテストを走らせて結果を貼る
- テストが赤い時はコードを直す。テストを書き換える時は必ず先に確認

### 仮定を黙って取らない
- 曖昧な指示を受けたら、解釈を選ぶ前に仮定をリスト化してこちらに見せる
- 触らなくていい所には触らない。ついでのリファクタは別 PR に分ける
- 未実装の関数や TODO で済ませた箇所は、レポートの冒頭に必ず列挙する

### 知識の古さに気をつける
- 該当ライブラリの最新ドキュメントを取りに行ってから書く（Context7 推奨）
- 新規依存を追加する前に、npmjs.com / pypi.org で実在確認
- このプロジェクトの前提バージョン: [ここにバージョンを書く]

### 過剰にしない
- 求められた問題だけを解く最小のコード。投機的な抽象化を入れない
- セキュリティ的に危険なデフォルトを「動くから」と選ばない（service-role キー、公開バケット、.env.example の実値）

これを既存の CLAUDE.md に追記して、自分の現場の言葉で1〜2行ずつ調整するのが、いちばん長く保てる形です。

まとめ

• AI コーディングのアンチパターンは「検証不足」「仮定の暗黙取り」「知識の古さ」「過剰系」の4カテゴリに整理できる

• 4カテゴリの代表だけを CLAUDE.md / AGENTS.md に書き込めば、11個の多くは自然に防げる

• 検証不足系は Plan Mode と「テスト実行を返答の前提にする」で大半潰せる

• 仮定の暗黙取り系は Karpathy の Assumption Surfacing と Surgical Changes をそのまま採用すると効く

• 知識の古さ系は Context7 のような最新ドキュメント注入と「`package.json` を先に読む」の組み合わせ

• 過剰系は Simplicity の原則と、セキュリティ禁則の明示で対処

次の一手としては、自分の CLAUDE.md（または AGENTS.md）を開いて、上の4カテゴリの代表項目が入っているかを今すぐ確認してみてください。
入っていなければ、コピペできる形で上のブロックを置いてあります。

この記事が参考になったら、ぜひ「スキ」をお願いします。
AI コーディングの運用Tips は、これから定期的に書いていきます。

あわせて読みたい

CLAUDE.md の書き方そのものを掘り下げた記事はこちらに。

Claude Code Skills マーケットプレイスから入れる価値のあるスキルの整理はこちらに（Context7 や andrej-karpathy-skills の中身を扱っています）。

今週のAI動向まとめはこちらに。