Claude Codeのベストプラクティスを読む
マロンAnthropicが以前投稿してた、Claude Codeのベストプラクティスをまとめる
正直、日本語でいい感じにまとめられている記事はたくさんあるが、英語に慣れる意味合いも兼ねて読んだ内容を雑にまとめる。
（追記）
このまとめより何倍・何十倍も有益なブログがあったので、基本的にはそちらを参照してください。
マロン1. Customize your setup
a. Create CLAUDE.md files
- 簡単な要約:Claude Codeが動く時に参照するカスタムインストラクションファイルを作りましょう
- 目的: Claudeが会話開始時に自動的にコンテキストに取り込む特別なファイル
-
推奨される記載内容:
- よく使うbashコマンド
- コアファイルとユーティリティ関数
- コードスタイルガイドライン
- テスト手順
- リポジトリのエチケット（ブランチ命名、merge vs rebase等）
- 開発環境のセットアップ（pyenv使用、動作するコンパイラ等）
- プロジェクト固有の予期しない動作や警告
- その他Claudeに覚えておいてもらいたい情報
- 例は以下の形
# Bash commands
- npm run build: Build the project
- npm run typecheck: Run the typechecker
# Code style
- Use ES modules (import/export) syntax, not CommonJS (require)
- Destructure imports when possible (eg. import { foo } from 'bar')
# Workflow
- Be sure to typecheck when you’re done making a series of code changes
- Prefer running single tests, and not the whole test suite, for performance
-
配置場所による挙動:
- claudeを実行するディレクトリ: 起動時に自動読み込み
- claudeを実行するディレクトリの親ディレクトリ（モノレポに有用）: 起動時に自動読み込み
-
claudeを実行するディレクトリの子ディレクトリ: 該当ディレクトリのファイルを扱う際にオンデマンドで読み込み
- 例えば、Claude Codeがそのディレクトリ内のコードを扱う時に、そのディレクトリ内にあるCLAUDE.mdを読み取る
-
ホームフォルダ（
~/.claude/CLAUDE.md）: 全セッションに適用
-
Git管理:
- プロジェクトで共有したいものはCLAUDE.mdでGit管理することを推奨
- 自分用にはCLAUDE.local.mdにして、.gitignoreに追加しておくと良い
-
自動生成:
/initコマンドで自動生成可能
b. Tune your CLAUDE.md files
-
CLAUDE.mdファイルはCloudeのプロンプトの一部になるため、頻繁に使用されるプロンプトと同様に洗練が必要
-
よくある間違い: 効果を反復検証せずに大量のコンテンツを追加すること
-
推奨アプローチ: 時間をかけて実験し、モデルから最適な指示実行を引き出すものを見極める
-
#キーを押してCloudeに指示を与え、関連するCLAUDE.mdに自動的に組み込むことが可能
-
Anthropicでは時々CLAUDE.mdファイルをプロンプト改善ツールに通し、「IMPORTANT」や「YOU MUST」などの強調を追加して遵守率を向上
c. Curate Claude's list of allowed tools
-
デフォルト: システムを変更する可能性のあるアクション（ファイル書き込み、多くのbashコマンド、MCPツール等）は許可を要求
-
許可ツール管理の4つの方法:
(個人的には3が良いと思います)
- セッション中に「Always allow」を選択
-
/permissionsコマンドでツールを追加/削除- 例:
Edit（ファイル編集を常に許可） - 例:
Bash(git commit:*)（gitコミットを許可）
- 例:
-
設定ファイルを手動編集:
-
.claude/settings.json（プロジェクト固有、ソース管理にチェックイン推奨） -
~/.claude.json（グローバル設定）
-
-
-allowedToolsCLIフラグでセッション固有の許可
d. If using GitHub, install the gh CLI
- Claudeは
ghCLIを使ってGitHubと連携可能- イシュー作成
- プルリクエスト作成
- コメント読み取り
- その他GitHub操作
-
ghがない場合でもGitHub APIやMCPサーバーを使用可能
マロン2. Give Claude more tools
a. Use Claude with bash tools
- 環境継承: Claude Codeは自分のbash環境を継承し、すべてのツールにアクセス可能
-
Claudeの知識範囲:
- 一般的なユーティリティ（unixツールやgh）は既知なので、よしなにやってくれる
- カスタムbashツールは指示なしには認識できないので、以下のような指示が必要
-
カスタムツールの使用方法:
- ツール名と使用例を説明
-
-helpを実行してツールドキュメントを確認するよう指示 - 頻繁に使用するツールはCLAUDE.mdに記載
b. Use Claude with MCP
- Claude CodeのMCP対応: MCPサーバーとクライアントの両方として機能
-
MCPサーバー接続の3つの方法:
- プロジェクト設定（そのディレクトリでのみ利用可能）
- グローバル設定（全プロジェクトで利用可能）
-
チェックイン済み
.mcp.jsonファイル（コードベースを使う全員が利用可能）
-
設定例: PuppeteerやSentryサーバーを
.mcp.jsonに追加し、チーム全体で使用可能に -
デバッグ:
-mcp-debugフラグで設定問題を特定可能
c. Use custom slash commands
-
目的: 繰り返しワークフロー（デバッグループ、ログ解析等）の自動化
-
設定方法:
-
.claude/commandsフォルダ内にMarkdownファイルでプロンプトテンプレートを保存 -
/と入力するとスラッシュコマンドメニューで利用可能 - gitにチェックインしてチーム共有可能
-
-
特別なキーワード:
$ARGUMENTSでコマンド実行時にパラメータを渡すことが可能 -
例: GitHubイシューを自動解決するコマンド
- ファイル:
.claude/commands/fix-github-issue.md - コード:
Please analyze and fix the GitHub issue: $ARGUMENTS. Follow these steps: 1. Use `gh issue view` to get the issue details 2. Understand the problem described in the issue 3. Search the codebase for relevant files 4. Implement the necessary changes to fix the issue 5. Write and run tests to verify the fix 6. Ensure code passes linting and type checking 7. Create a descriptive commit message 8. Push and create a PR Remember to use the GitHub CLI (`gh`) for all GitHub-related tasks.- 使用方法:
/project:fix-github-issue 1234で$ARGUMENTSには1234がセットされ、イシュー番号1234に関して記載した内容を実行する
- ファイル:
-
個人用コマンド:
~/.claude/commandsフォルダで全セッションで利用可能なコマンドを作成
マロン3. Try common workflows
概要: Claude Codeは特定のワークフローに特化したものではなく、汎用的に使用できる。その中でコミュニティで上手くいっているものを記載している。
a. Explore, plan, code, commit
探索・計画・実装・コミットを行わせる。
探索
- 関連ファイル、画像、URLを読み取らせる
- 一般的な指示（「ログを処理するファイルを読んで」）または具体的なファイル名を指定
- この段階では明示的にコードを書かないよう指示
- まずは問題の把握に努めさせる。
計画
- 探索で問題の概要を把握できれば、特定の問題にどうアプローチするかの計画を立てさせる
- 「think」という単語を使って拡張思考モードを使い、解消方法を幅広い視点から考えさせる
- 思考レベル: "think" < "think hard" < "think harder" < "ultrathink"の形で深くなる。
- 結果が妥当であれば、ドキュメントやGitHubイシューとして計画を作成
実装
- ソリューションをコードで実装
- 実装中に解決策の妥当性を明示的に検証させることを推奨
コミット＆プルリクエスト
- 結果をコミットしプルリクエストを作成
- 必要に応じてREADMEやchangelogの更新も依頼
探索・計画・実装・コミット＆プルリクエストの中では探索・計画が重要になる。
これらなしでは、Claudeはすぐにコーディングに飛びつく傾向がある。
上手く行く場合もあるが、この手順をふんだほうがパフォーマンスが良い。
b. Write tests, commit; code, iterate, commit
概要: Anthropicお気に入りのワークフロー。単体、統合、E2Eテストで簡単に検証可能な変更に適用。
TDDはエージェントによる開発をより強固なものにする。
テスト作成
期待される入力/出力ペアに基づいてテストを書かせる
この時、テストを通す必要はないので、モック実装を避けあくまでテストすることの作成に注力させる。
テスト実行:
テストを実行して失敗することを確認
この段階では実装コードを書かないよう明示的に指示
テストコミット:
実装したテストに過不足を感じなければ、コミットさせる。
実装
テストを通すコードを書かせる
この時、テストを変更しないよう指示
全テストが通るまで継続させる（通常数回の反復が必要）
実装がテストにオーバーフィットしていないか独立したサブエージェントで検証
コードコミット
テストとアプリコードに満足したらコードをコミット
Claudeは明確なターゲット（ビジュアルモック、テストケース、その他の出力）がある時に最高のパフォーマンスを発揮
c. Write code, screenshot result, iterate
テストワークフローと似た、ビジュアルターゲットを提供する方法
スクリーンショット環境の準備
ブラウザスクリーンショットを撮る方法を提供
PuppeteerMCPサーバー、iOSシミュレーターMCPサーバー、または手動でのスクリーンショット貼り付け
ビジュアルモックの提供:
画像のコピー/貼り付け、ドラッグ&ドロップ、またはファイルパスで提供
実装と反復
デザインをコードで実装し、結果のスクリーンショットを撮り、モックと一致するまで反復
コミット
満足したらコミット
人間と同様、Claudeの出力は反復により大幅に改善。2-3回の反復で通常大幅に向上。
一回で完成を目指すのではなく、何度も試行させる前提で行う。
d. Safe YOLO mode
Claudeが開発者に作業しても良いかの確認をとらず、完了まで中断なく作業させる方法
使用方法: claude --dangerously-skip-permissionsで全ての許可チェックをさせないように実行する。
適用場面: lintエラーの修正やボイラープレートコード生成などのワークフロー
リスク:任意のコマンド実行によるデータ損失、システム破損、データ流出の可能性。プロンプトインジェクション攻撃のリスク
安全対策: インターネットアクセスのないコンテナ内での使用を推奨
e. Codebase Q&A
新しいコードベースへのオンボーディング時の学習と探索に使用する。
ペアプログラミング時に他のエンジニアに聞くような質問をCloudeに投げかける
質問例:
- ログはどのように動作しますか？
- 新しいAPIエンドポイントはどう作りますか？
- foo.rsの134行目のasync move { ... }は何をしていますか？
- CustomerOnboardingFlowImplはどのようなエッジケースを処理しますか？
- 333行目でbar()ではなくfoo()を呼んでいるのはなぜですか？
- baz.pyの334行目のJava相当のコードは何ですか？
Anthropicでは、これがコアオンボーディングワークフローとなり、立ち上がり時間が大幅に改善し、他のエンジニアへの負荷も軽減
f. Use Claude to interact with git
Claudeは多くのgit操作を効果的に処理することが可能。
そして、Anthropicエンジニアはgitやりとりの90%以上でCloudeを使用
主な用途
- gitヒストリー検索
- 「v1.2.3に入った変更は？」「この機能の所有者は？」「このAPIがこう設計された理由は？」
- コミットメッセージ作成
- 変更と最近の履歴を見て、全ての関連コンテキストを考慮したメッセージを作成
- 複雑なgit操作
- ファイルのリバート、リベース競合の解決、パッチの比較と移植
g. Use Claude to interact with GitHub
Glaude CodeはGitHubの多くの機能を操作できる。
例えば、以下の通り。
- プルリクエスト作成
- 「pr」という短縮形を理解し、diffと周辺コンテキストに基づいて適切なコミットメッセージを生成
- コードレビューコメントの一括解決
- 簡単なコメントに対するワンショット解決の実装
ビルド失敗やlinter警告の修正
- 簡単なコメントに対するワンショット解決の実装
- イシューの分類とトリアージ
- オープンなGitHubイシューをループして分類
これらによって、ghコマンドライン構文を覚える必要がなくなり、ルーチンタスクが自動化される
h. Use Claude to work with Jupyter notebooks
対象ユーザー: Anthropicの研究者とデータサイエンティスト
機能は以下の通り。
- Jupyterノートブックの読み書き
- 画像を含む出力の解釈
- データの探索と対話のための高速な方法
推奨方法として、 VS CodeでClaude Codeと.ipynbファイルを並べて開く
その他、Jupyter notebookのクリーンアップアップやデータを可視化した時の見た目を改善できる。