Common Mistakes & Solutions

「ログイン機能を作って」→「ついでにデザインも直して」→「あ、あとこのバグも...」 と1つのセッションに色々詰め込むと、後半で指示を忘れたり、関係ない変更をし始めます。

対策: 1セッション = 1タスク。タスクが変わったら /clear。
たとえ: 1つの会議で10個の議題を話すと、最後には最初の話を誰も覚えていない。会議を分けましょう。

「違う」→「まだ違う」→「そうじゃない」を繰り返すと、 失敗した会話がどんどん溜まって、Claude がますます混乱します。

対策: 2回失敗したら /clear。もっと具体的な書き方でゼロからやり直す。
たとえ: 道に迷って何度も引き返すより、一度止まって地図を確認するほうが早い。

500行以上のルールを書き連ねると、Claude は重要なルールまで見落とします。

対策: 100~200行に収める。詳細は別ファイルにして「あのファイルを参照して」と書く。
たとえ: 新人に100ページのマニュアルを渡しても読まない。A4 1枚の要点メモのほうが効果的。

詳しくは CLAUDE.md 徹底解説 へ。

Claude が書いたコードをテストせずにそのまま使うと、本番で問題が発生します。 調査によると、AIが生成するコードは人間の約1.75倍のロジックエラーを含む傾向があります。

対策: 「テストを書いて → 実行して → 全部通るまで直して」を毎回伝える。
たとえ: 料理を味見せずに客に出す人はいない。AIのコードも「味見(テスト)」が必要。

Claude に「このプロジェクト全体を調べて」と頼むと、 調査結果だけで記憶容量がいっぱいになり、肝心の実装ができなくなります。

対策: 調査はサブエージェント(Explore)に任せる。要約だけ返してもらう。
たとえ: 自分で図書館に行くのではなく、秘書に「要点だけまとめて」と頼む。

完璧な設定を目指して、Hook、スキル、サブエージェントを大量に作り込む。 しかし実際にはほとんど使わない。

対策: まずはデフォルト設定で使い始める。不便を感じたら、その都度カスタマイズする。 Claude Code の生みの親 Boris Cherny 氏のセットアップが「驚くほど普通」なのは示唆的。
たとえ: 新しいスマホの設定を3日かけて完璧にするより、まず使い始めてから調整するほうが効率的。

Claude Code にはレート制限（一定時間内に使える量の上限）があります。この制限に引っかかると、一定時間（数分〜数十分）Claude Code が使えなくなります。作業の途中で突然止まるため、締め切りが迫っているときほどダメージが大きい失敗です。

たとえると: スマホのデータ通信量を使い切って「速度制限」がかかるのと同じです。月末に動画を見すぎると、残りの日は低速でしか使えなくなる。Claude Code でも、短時間に大量のリクエスト（処理の依頼）を送ると、同じように制限がかかります。

レート制限の仕組み: Claude Code は裏側で API（プログラムの窓口）を通じてサーバーと通信しています。この通信には「トークン」（テキスト量の単位、日本語1文字が約1〜2トークン）という単位でコストがかかり、一定時間内のトークン消費量に上限が設けられています。

よくある原因:
・ 不要なコンテキストの蓄積 — 終わったタスクの会話を /clear せずに残しておくと、毎回の通信に過去の全会話が含まれ、トークンを大量消費する
・ /clear せずに長時間使い続ける — セッションが長くなるほど1回の通信で送られるデータ量が増え、制限に到達しやすくなる
・ 大量のファイルを一度に読み込ませる — 「プロジェクト全体を把握して」のような広範な指示で、何十ものファイルを一度にスキャンさせると一気にトークンを消費する

対策:
・ こまめに /clear — タスクが変わるたびにセッションをリセット。最も効果的な対策
・ 必要なファイルだけ @指定 — 「@src/auth/login.ts を修正して」のように、対象ファイルを明示的に指定する。Claude に探させない
・ /compact で圧縮 — 会話が長くなったとき、要約して短くすることでトークン消費を抑える
・ サブエージェントに調査を委任 — 広範な調査はサブエージェント（別プロセスで動く部下 AI）に任せ、要約だけもらう。メインセッションのトークン消費を節約できる

たとえると: スマホの通信量を節約するために、Wi-Fi（/clear で軽くした状態）を使い、動画は低画質（/compact で圧縮）にし、大容量のダウンロードは夜間（サブエージェント）に回す — そんなイメージです。