Zennでエンジニアたちが「Claude Codeの使い方でハマりやすいポイント」を共有している。コマンドの使い方より「どう考えるか」という視点の記事が参考になったのでまとめる。
いきなりコードを書かせるのではなく、「まずPLAN.mdに実装計画を書いて」と指示してから動かすと品質が上がる。Claude Codeは指示がざっくりしていると勝手に「良さそう」な方向に進むが、それがユーザーの意図とズレることが多い。
計画段階でズレを発見できれば、コード修正コストがかからない。「計画だけ出して、実装はまだしなくていい」と伝えるのがポイント。
エラーが出たとき「〇〇というエラーが出ました」と要約して渡すより、ターミナル出力をそのままコピペした方が解決が早い。スタックトレースや前後の出力に含まれるコンテキストが重要な手がかりになることが多い。
特にTypeScriptの型エラーや依存関係エラーは、省略すると原因を誤診しやすい。
同じミスを繰り返させないために、失敗パターンや「うちのプロジェクト固有のルール」を lessons.md に記録してCLAUDE.mdから参照させる運用が効果的だと報告されている。
例えば：
# lessons.md
- テストは必ずVitest使用（Jestではない）
- DBマイグレーションはdry-runを先に実行すること
- src/lib/utils.ts の関数は変更前にコメントで理由を残すことこのファイルをプロンプトに自動ロードする設定にすることで、「前も言ったのに」という状況を減らせる。
長いセッションが続くとモデルの応答品質が落ちることがある。これはコンテキストウィンドウの圧迫が原因で、特に大量のファイルを読み込んだ後は顕著だ。
対策として：
/clear で会話をリセット@file の使い過ぎに注意）Claude Codeは「できる」なら「やる」方向に動く。ファイル削除・外部API呼び出し・DBへの書き込みなどリバーシブルでない操作は、事前に「これをやっていいか確認して」と指示するか、Auto Modeのapprovalゲートを活用するのが安全だ。
特にはじめて触るコードベースでは「変更前にgit statusを確認して、変更するファイルを教えてから実装してください」という一言が有効。
Claude Codeは「使い方を覚える」より「どう指示するかを設計する」ツールだという感覚が重要だ。計画を先に出させる・エラーを要約しない・学習記録を育てる、この3つを意識するだけでも体験がかなり変わる。特にlessons.mdは小さいコストで大きな効果が出るのでおすすめ。