Claude Codeで失敗しやすい指示と改善例

はじめに

Claude Codeを使う上で、指示の質が結果を大きく左右します。本記事では、初心者が陥りやすい「失敗しやすい指示パターン」を具体例で示し、改善方法を解説します。Claude Codeに最初に渡すべき指示テンプレート集と合わせて参考にしてください。

失敗パターン1：スコープが曖昧

❌ 失敗例

「authモジュールを改善してください」

何が起きるか：

• どのファイルを編集するか不明確
• サーバー側auth、フロント側auth、テストコード…複数の候補がある
• AIが勝手に複数ファイルを編集してしまう可能性
• git diff が巨大になり、レビュー不可能

✅ 改善例

対象ファイル: src/services/auth.ts のうち、login() 関数のみ

現在の問題: login() が「ユーザー不在」と「パスワード不正」の区別をしていない

改善内容: 
- 404（ユーザー不在）と 401（パスワード不正）を分けて返す
- エラーメッセージを整理
- テストケースは既存のまま

他のファイルは変更しないでください。

改善のポイント：

• ファイル名を明記
• 関数名を明記
• 何が問題かを説明
• 明確な改善内容

失敗パターン2：要件が曖昧

❌ 失敗例

「このコードを最適化してください」

何が起きるか：

• 「最適化」の定義が不明確
• パフォーマンス最適化？可読性改善？保守性向上？
• AIが勝手に大規模リファクタリングをしてしまう
• 既存テストが通るかわからない

✅ 改善例

対象ファイル: src/utils/sort.ts

要件: quickSort() 関数の処理速度を改善

目標:
- 入力が 10,000 要素のランダム配列のとき、1秒以内に完了
- 既存テストは全て通過
- アルゴリズムの変更は OK（ただしスワップアルゴリズムの選択理由を説明）

測定方法:
実装後、console.time() で実行時間を確認。

他の関数は変更しないでください。

改善のポイント：

• 「最適化」を具体化（速度か可読性か）
• 測定可能な目標
• 既存テスト維持を明示

失敗パターン3：複数の関心事が混在

❌ 失敗例

「データベース処理を新しいライブラリに移行して、
同時にエラーハンドリングも改善して、
さらに不要な関数も削除してください」

何が起きるか：

• 一度に複数の変更が起きて何が何だかわからなくなる
• テスト失敗したときに原因の切り分けができない
• rollback が困難

✅ 改善例

【ステップ1】（まずこれだけ）
対象: src/db/connection.ts

タスク: 新しい db ライブラリへの移行計画を作成
- 既存コード上の db 呼び出し個所を全て列挙
- 新旧ライブラリの API の差分を整理
- 最小限の変更セットを提案

実装はしないでください。計画だけ提示してください。

【ステップ2】（計画承認後）
ステップ1 の計画に基づいて、1ファイルのみを移行。

【ステップ3】
他のファイルも同じパターンで移行。

改善のポイント：

• 大きなタスクは複数ステップに分割
• 各ステップの終わりに人間の確認を入れる
• 一度に複数の関心事を混ぜない

失敗パターン4：制約が不明確

❌ 失敗例

「ログイン機能を作ってください」

何が起きるか：

• パスワードをプレーンテキストで保存するコードが生成されるかもしれない
• HTTPS チェックが入っていないかもしれない
• CSRF 対策がないかもしれない
• テストが十分でないかもしれない

✅ 改善例

対象ファイル: src/routes/auth.ts（新規作成）

タスク: POST /api/login エンドポイント

要件:
- bcrypt でパスワード ハッシング必須
- 署名なし平文での通信禁止（HTTPS only の指示を追加）
- CSRF トークン検証を実装
- 失敗時は「ユーザー不在」「パスワード不正」を区別しない
  （セキュリティのため）
- テストケース: 正常系、ユーザー不在、パスワード不正

テンプレートは既存の src/routes/users.ts を参考に。
他の機能は追加しないでください。

実装前に計画を確認させてください。

改善のポイント：

• セキュリティ要件を明示
• 既存テンプレートを参照
• テストケースを列挙

失敗パターン5：範囲が大きすぎる

❌ 失敗例

「バックエンド全体を Node.js から Python に移行してください」

何が起きるか：

• これはAIで完結する作業ではなく、複数人・複数週間のプロジェクト
• 一度に全て変わってテストが不可能
• rollback が致命的

✅ 改善例

【マイルストーン1】
対象: src/api/users.ts のみ

タスク: 既存の GET /api/users/:id エンドポイント（Node.js）を
同じ動作の Python Flask で実装

要件:
- 既存のテストケースから期待値を抽出
- Flask エンドポイントの実装
- unit test を pytest で記述
- Node.js 版は削除しない（後で並行運用テスト）

他の API は変更しないでください。

改善のポイント：

• 大規模な移行は 1 API ずつ
• 既存テストを使い回す
• 並行検証の期間を設ける

まとめ

Claude Codeに全部任せると危ない理由の本質は、指示の曖昧さにあります。

避けるべき指示：

• スコープが不明確
• 要件が曖昧
• 複数の関心事が混在
• 制約が明記されていない
• 範囲が大きすぎる

改善ポイント：

• ファイル・関数・ステップを明確に
• 「何が問題か」「何が改善か」を定義
• 複数の変更は分割
• セキュリティ・テスト・既存との互換性を明示
• 計画確認のステップを挟む

テンプレート集を参考に、明確な指示を心がけましょう。