Article

Claude Codeでよくある失敗パターンと回避策

Claude Codeを使い始めると必ずハマる10種の失敗パターンを、原因・回避策・関連記事リンクとともに整理します。曖昧な依頼・テスト不足・依存追加の暴走・コンテキスト不足・AI過信などを具体例ベースで扱います。

This article is not published in this language yet, so the Japanese version is shown instead.

Claude Codeを1か月使うと、誰でも同じ場所で詰まります。曖昧な依頼、テスト不足、勝手な依存追加、AIの自信満々な嘘。本記事では、開発現場で実際に出る10種の失敗パターンを、典型シナリオ・原因・回避策の3点セットで整理します。

結論：失敗の8割は「具体性」「テスト」「人間レビュー」の不足

ハマる場所はだいたい決まっています。

依頼が曖昧で、AIが余白を勝手に埋めてしまう
テストがない、または書かせたテストがトートロジー
AIが追加した依存・新規ファイルを誰も見ていない
「動いた」をユーザー側で確認していない
失敗の責任が「Approveした人」に紐付いていない

10パターン中ほぼすべてが、この5つの組み合わせです。詳しい依頼文設計は「Claude Codeでやりがちな悪い依頼文と改善例」、セキュリティ観点は「Claude Codeを使うときのセキュリティチェックリスト」、完了条件の書き方は「Claude Codeの成功率を上げる制約条件と受け入れ条件の作り方」に任せ、本記事は「現場で繰り返し出るパターン」をハブ的に並べます。

失敗パターン10種

1. 「いい感じに直して」依頼

典型：「ログイン周りいい感じに直しといて」「このバグ修正して」

原因：完了条件と禁止事項が無いため、AIが範囲を勝手に決め、リファクタや無関係な変更まで混入します。

回避：

対象ファイル・完了条件・禁止事項を最低限書く
1依頼=1意図。複数を混ぜない
「対象範囲外は触らない」を禁止事項として明示

詳細は「Claude Codeに伝わるプロンプトの基本構造」、依頼前チェックリストは「Claude Codeへの依頼前に確認するチェックリスト」。

2. テストを書かないまま実装

典型：「動いてるからOK」のコミット。後日、別の修正で壊れているのを発見。

原因：完了条件にテストを入れていない。あるいは「テスト書いて」と頼んだら自明アサート（expect(result).toBeDefined()）が生成された。

回避：

受け入れ条件に「失敗テストが1つ以上ある状態から始める」と明記
バグ修正は再現テスト先行（Red→Green）
AI生成テストは6危険サイン（弱アサート／モック戻り値そのままアサート／コピペ羅列／アサート0／実装名コピー名／skip混入）でレビュー

詳細は「Claude Codeでテスト駆動開発をする手順」と「Claude Codeにテストコードを生成させるときの依頼文と注意点」。

3. 依存追加の暴走

典型：1機能追加のPRに、3つの新規ライブラリが入っている。package.jsonを見て驚く。

原因：CLAUDE.mdに「依存追加は別PRに切り出す」「採用基準を満たすこと」を書いていない。

回避：

依存追加は禁止事項に入れ、必要なら別PRで人間レビュー
採用基準（ダウンロード数・最終更新日・ライセンス・代替の有無）をCLAUDE.mdに明記
CIにpackage.json差分検出を入れる

# 例: PRに package.json 変更が含まれる場合に警告
git diff --name-only origin/main...HEAD | grep -q '^package.json$' && echo "dependency change detected"

包括的な観点は「AI生成コードをチームで扱うための品質ルールとレビュー基準」。

4. 新規ファイルの量産

典型：1機能追加で15個の新規ファイルが生成される。utils/、helpers/、types/が際限なく増える。

原因：「分割しないと壊しそう」というAIの保守的挙動と、ファイル分割の判断軸が共有されていない。

回避：

完了条件に「新規ファイル数を理由とともに報告」を入れる
ドメイン境界／公開API境界／テスト境界の3基準で分割を判断
utils/／helpers/をやめてドメイン単位に置く

詳細は「AI開発でファイルが増えすぎる問題を防ぐ設計ルール」。

5. コンテキスト不足で見当外れな提案

典型：「このバグ直して」とエラーだけ貼り、AIが架空のフレームワークの解決策を提示。

原因：プロジェクトのバージョン、関連ファイル、再現手順をどれも渡していない。

回避：

症状・再現手順・関連ファイル・確認したいことを依頼文の6ブロックで構造化
@参照でファイル本体を渡す。エラーログはgrep -B 2 -A 20で前後だけ
バージョンはpackage.jsonの関連箇所だけ抜粋して貼る

詳細は「Claude Codeでスタックトレースを読ませてバグ原因を調べる方法」。

6. AIの自信満々な嘘（hallucination）

典型：存在しない関数名を使ったコード、存在しないAPIドキュメントの引用、存在しないライブラリのバージョン。

原因：知識カットオフ後の情報を必要としている、または曖昧な指示で推測を強要した。

回避：

仕様確認系は「ドキュメントに書いていなければ『不明』と返す」を依頼文に入れる
バージョン固有の挙動は人間が一次情報を確認
「○○というAPIがあるはず」のような誘導尋問をしない

7. コンテキストの溢れによる劣化

典型：午後になるとAIの応答品質が朝より明らかに落ちる。同じバグを2回直したのに3回目で再発する。

原因：1セッションで複数タスクを抱え、autocompactで重要情報が落ちた。

回避：

1セッション1主題。タスク切り替え時は/clear
2回連続で同じバグ修正に失敗したら、依頼文を書き直して/clear
重要事実はNOTES.mdに書き出してCLAUDE.mdから参照

詳細は「Claude Codeでコンテキストウィンドウを無駄にしない運用方法」。

8. 過信レビュー（AIに自分の出力をレビューさせる）

典型：「セルフレビューして」と頼んで、AIが「問題ありません」と返す。実際には未テストブランチがある。

原因：同じセッションの同じAIに「公平な評価」はできない。バイアスがかかる。

回避：

claude --from-prで**別セッション（fresh context）**にレビューさせる
/review／/security-reviewを一次フィルタとし、最終判断は人間
Critical／Should／Nitラベルで重要度を分けさせる

詳細は「Claude Codeをコードレビューに使う方法と人間が見るべきポイント」。

9. 秘密情報・本番接続事故

典型：.envをうっかり@参照、本番DSNを誤って渡してしまった、ログにAuthorizationヘッダーが残った。

原因：deny ruleやサンドボックスを設定していない、ログ整形を依頼前にしていない。

回避：

Read denyに.env*／~/.aws/／~/.ssh/／~/.config/gcloud/／~/.netrc／~/.pgpass
ログはgrep -B 2 -A 20で必要部分を抽出し、API Key・Cookie・Authorizationを伏字化してから渡す
本番DBへの直接アクセスはdeny。読み取り用のリードレプリカに分離

詳細は「Claude Codeに秘密情報を渡さないための実践ルール」、本番障害対応は「障害対応でClaude Codeを使うときの安全な進め方」。