Claude Codeベストプラクティスまとめ

自分が読む用にMarpでまとめたものを、読後に調整して公開しました。

Transcript

1. Claude Code ベストプラクティスまとめ みのるん @minorun365　with Claude
2. おことわり このスライドは、いま話題のAnthropicの公式ベストプラクティスガイドをもとに、 Claude CodeとMarpを使って作成したものです。 Best Practices for Claude Code - Claude Code Docs https://code.claude.com/docs/en/best-practices 内容面は作成者のみのるんが責任を持って監修・レビュー・調整していますが、 予めご留意のうえお楽しみください。 2
3. そもそもClaude Codeとは？ いま一番人気のコーディングAIエージェントです。 チャットボットではない（質問に答えて待つのではなく、自律的に作業する） ファイルを読み、コマンドを実行し、変更を加える あなたは見守る、リダイレクトする、または離席もOK 従来の開発スタイルとの違いは？ 従来 Claude Code 自分でコードを書いてレビューを依頼 やりたいことを伝えるだけ 実装方法を考える Claudeが探索・計画・実装 3
4. 最初に、最も重要なポイントとは？ 4
5. 「コンテキストウィンドウを管理せよ」 Claude Codeの最重要リソース ＝ 入力トークン数の上限！ コンテキストウィンドウには以下がすべて蓄積される。 会話履歴 読み込んだファイル内容 コマンド出力 問題点 1回のデバッグで数万トークンを消費することも コンテキストが埋まると精度が低下する 以前の指示を「忘れる」ことがある 5
6. 7つのベストプラクティス 6
7. 1. 検証方法を与えよう Claudeが自分で作業をチェックできるようにする これが最も効き目の高い施策！ Before After 「メール検証関数を実 装して」 「validateEmail関数を書いて。test@example.comはtrue、invalidは false。実装後にテスト実行して」 「ダッシュボードを良 くして」 「[スクショ貼付] このデザインを実装して。結果のスクショを撮って比較 し、差分を修正して」 「ビルドが失敗する」 「このエラーで失敗：[エラー貼付]。根本原因を修正してビルド成功を確認 して」 7
8. 2. 「探索→計画→実装」の順に進めよう 調査とコーディングを分離する 4つのフェーズ： 1. 探索 → Plan Modeで質問。ファイルを読み、変更なし 2. 計画 → 詳細な実装計画を作成 3. 実装 → Normal Modeで計画に沿ってコーディング 4. コミット → PRを作成 Plan Modeが有効なケースとは？ アプローチが不明確 複数ファイルに変更を加える 馴染みのないコードを使う ※ タイポ修正などは直接実行でOK 8
9. 3. 具体的なコンテキストを提供しよう 曖昧さをなくし、修正回数を減らそう！ Before After 「foo.pyのテストを 追加して」 「foo.pyのテストを書いて。ログアウト時のエッジケースを対象に。モック不 使用で」 「ログインのバグを 直して」 「セッションタイムアウト後にログイン失敗する報告あり。src/auth/のトー クンリフレッシュを確認。再現テストを書いてから修正して」 「カレンダーウィジ ェットを追加」 「ホームページの既存ウィジェットを見てパターンを理解して。 HotDogWidget.phpを参考に」 9
10. 3. 具体的なコンテキストを提供しよう リッチなデータを渡す方法とは？ @ でファイルを参照する ファイルの場所を説明するより直接参照 画像をコピペまたはドラッグ&ドロップする URLを渡す /permissions で頻出ドメインを許可リストに パイプでデータ投入する cat error.log | claude Claude自身に取得させる Bashコマンド、MCPツールで自分で取得させる 10
11. 4. 環境を設定しよう CLAUDE.md を効果的に書く # Code style - CommonJS (require) ではなくES modules (import/export) を使う。 - インポートは分割代入で (例： import { foo } from 'bar') # Workflow - 一連のコード変更後は必ず型チェック - パフォーマンスのため、テスト全体ではなく単一テストを実行 ポイントは？ /init でスターターを生成する 短く、人間が読める形式で書く 「これを削除するとミスが起きるか？」と自問してみる 11
12. 4. 環境を設定しよう CLAUDE.md に含めるもの vs 含めないもの 含める 含めない Claudeが推測できないBashコマンド コードを読めばわかること デフォルトと異なるコードスタイル 言語の標準慣習 テスト実行方法 詳細なAPIドキュメント（リンクで） リポジトリのルール（ブランチ命名等） 頻繁に変わる情報 アーキテクチャ上の決定事項 ファイル毎の説明 環境変数などの開発環境の癖 「きれいなコードを書け」等の自明な指示 12
13. 4. 環境を設定しよう その他の役立つ設定は？ 設定 コマンド 説明 権限設定 /permissions 安全なコマンドを許可リストに サンドボックス /sandbox OS レベルで分離 CLIツール gh , aws , gcloud 等 外部サービスとの効率的な連携 MCPサーバー claude mcp add Notion, Figma, DB 等と接続 フック /hooks 特定のタイミングでスクリプト実行 スキル .claude/skills/ ドメイン知識や再利用ワークフロー 13
14. 5. Claudeとうまく会話しよう コードベースについて質問する つよつよの先輩に聞くように質問してみよう。 「ログはどう動いてる？」 「新しいAPIエンドポイントはどう作る？」 「foo.rsの134行目の async move { ... } は何？」 「なぜこのコードはbar()じゃなくてfoo()を呼んでる？」 Claudeにインタビューさせるのもアリ！ [簡単な説明]を作りたい。AskUserQuestionツールで詳しくインタビューして。 技術実装、UI/UX、エッジケース、トレードオフについて掘り下げて。 14
15. 6. セッションを管理しよう 早めに、頻繁に軌道修正すること！ 操作 説明 Esc 途中で停止（コンテキストは保持） Esc × 2 または /rewind 以前の状態に巻き戻し "Undo that" 変更を元に戻させる /clear 無関係なタスク間でコンテキストをリセット 【重要】 同じ問題で2回以上修正したら → /clear してより具体的なプロンプトで再開しよう 15
16. 6. セッションを管理しよう サブエージェントに調査を委任する サブエージェントを使って、認証システムがトークンリフレッシュを どう処理しているか、再利用可能なOAuthユーティリティがあるか調査して メリット 別のコンテキストウィンドウで実行 要約だけが返ってくる メインの会話がクリーンに保たれる セッションを再開するには？ claude --continue → 最新の会話を再開 claude --resume → 過去のセッションから選択 16
17. 7. 自動化して生産性を上げよう ヘッドレスモード（対話なしで実行） claude -p "プロンプト" で、対話セッションなしで実行できる！ # 単発の質問 claude -p "このプロジェクトが何をするか説明して" # JSON出力（スクリプトで結果をパースしたいとき） claude -p "すべてのAPIエンドポイントをリスト" --output-format json 活用例： CIパイプライン、pre-commitフック、シェルスクリプト組み込みなど 17
18. 7. 自動化して生産性を上げよう 複数セッションの活用 Writer/Reviewerパターンの例 セッション A (Writer) への指示 セッション B (Reviewer) への指示 APIエンドポイントにレート制限を実装して src/middleware/rateLimiter.tsのレート制限実装を レビューして。エッジケース、競合状態、既存パターン との一貫性を確認 レビューのフィードバック：[Session Bの 出力]。これらを対処して 別のパターン例： 1つ目がテストを書き、2つ目がテストを通すコードを書く 18
19. よくある失敗パターン 19
20. 避けるべき5つのパターン パターン 問題 解決策 "キッチンシンク・セッ ション" 無関係なタスクを混ぜてコンテ キストが散らかる /clear でタスク間をリセット 繰り返しの修正 失敗アプローチでコンテキスト が汚染 2回失敗したら /clear して再プロン プト 長すぎるCLAUDE.md 重要なルールがノイズに埋もれる 容赦なく削除。フックに変換も検討 検証なしの信頼 エッジケースを扱わない実装 常に検証手段を提供（テスト、スクリ プト、スクショ） 無限の探索 スコープを絞らずに調査→大量フ ァイル読み込み 狭くスコープするか、サブエージェント を使う 20
21. まとめ Claude Code 成功の鍵は？ 1. コンテキストウィンドウを管理する これが最重要のリソース！ 2. 検証方法を与える テスト、スクショ、期待出力 3. 探索→計画→実装 調査と実装を分離 4. 具体的なコンテキスト ファイル参照、画像、URL 5. 環境を設定 CLAUDE.md、権限、MCP 6. サブエージェントを活用 調査を委任しコンテキストを節約 7. 早めの軌道修正 /clear を頻繁に使う そして直感を磨こう！ 何がうまくいったか観察し、パターンを見つけよう 21