最近、私たちはコマンドラインツール「Claude Code」をリリースしました。これはエージェント的コーディングを可能にするツールで、Anthropic のエンジニアや研究者が Claude をよりネイティブにコーディングワークフローに組み込めるよう設計された研究プロジェクトです。
Claude Code は意図的にロー レベルかつアンオピニオンテッド（特定のワークフローを強制しない）に作られており、モデルへのほぼ生のアクセスを提供します。このデザイン哲学により、柔軟でカスタマイズ可能、スクリプト化が容易、かつ安全なパワーツールとなっています。しかしその柔軟さゆえ、エージェント的コーディングツールに不慣れなエンジニアには学習コストがかかります──少なくとも、自身のベストプラクティスを確立するまでは。
この記事では、Anthropic の内部チームやさまざまなコードベース／言語／環境で Claude Code を使っている外部エンジニアにとって効果的だった一般的なパターンを紹介します。ここに挙げた内容は不変でも普遍的でもありません。あくまで出発点としてご参考にしていただき、ぜひ試行錯誤しながら最適な方法を見つけてください。
もっと詳しい情報をお探しですか？本記事で述べたすべての機能を網羅し、追加の例や実装詳細、高度なテクニックを掲載した包括的ドキュメントは claude.ai/code にあります。
Claude Code は、対話開始時に自動的にコンテキストをプルインするエージェント型コーディングアシスタントです。コンテキスト収集には時間とトークンを消費しますが、環境設定を調整することで最適化できます。
CLAUDE.md は Claude が対話開始時に自動的に読み込む特別ファイルです。以下のような情報をまとめておくのに最適です。
- よく使う bash コマンド
- コアとなるファイルやユーティリティ関数
- コードスタイルガイドライン
- テスト手順
- リポジトリのエチケット（ブランチ命名規則、マージ vs リベースなど）
- 開発環境セットアップ方法（pyenv の利用法、動作するコンパイラなど）
- プロジェクト固有の予期しない挙動や警告
- その他、Claude に覚えておいてほしい情報
CLAUDE.md に形式の指定はありませんが、簡潔で人間が読みやすいことをおすすめします。例えば：
# Bash コマンド
- npm run build: プロジェクトをビルド
- npm run typecheck: 型チェックを実行
# コードスタイル
- ES モジュール（import/export）構文を使用、CommonJS（require）は避ける
- 可能な限り分割代入してインポート（例: import { foo } from 'bar'）
# ワークフロー
- 一連の変更を終えたら必ず型チェックを実行
- パフォーマンスのため、全テストではなく単一のテストを実行するのを優先CLAUDE.md ファイルは次の場所に置けます。
-
リポジトリのルート（または
claudeコマンドを実行するディレクトリ）- 名前を
CLAUDE.mdとして git 管理し、セッション間やチームで共有（推奨） - 名前を
CLAUDE.local.mdとして.gitignoreに加え、ローカルのみ適用
- 名前を
-
claudeを実行するディレクトリの親ディレクトリ- モノレポで有用。例：
root/fooで実行する際、root/CLAUDE.mdとroot/foo/CLAUDE.mdの両方が自動読み込みされる
- モノレポで有用。例：
-
claudeを実行するディレクトリの子ディレクトリ- 逆パターン。子ディレクトリ内の
CLAUDE.mdを、そこに関連するファイルを扱うときにオンデマンドで読み込む
- 逆パターン。子ディレクトリ内の
-
ホームフォルダ（
~/.claude/CLAUDE.md）- すべての Claude セッションに適用
/init コマンドを実行すると、Claude が自動で CLAUDE.md を生成してくれます。
CLAUDE.md ファイルは Claude のプロンプトの一部となるため、頻繁に使用されるプロンプトと同様に改善を重ねる必要があります。よくある失敗例は、効果を検証せずに大量の情報を詰め込んでしまうことです。時間をかけて試行錯誤し、最も効果的にモデルが指示に従ってくれる内容を見極めてください。
内容は手動で書き加えることもできますし、# キーを押して Claude に指示を与え、それを自動的に該当の CLAUDE.md に追加させることも可能です。多くのエンジニアはコーディング中に # を使って、コマンド、ファイル、スタイルガイドなどを記録し、その後 CLAUDE.md への変更をコミットしてチームと共有しています。
Anthropic 社内では、CLAUDE.md を定期的に プロンプト改善ツール に通しており、「IMPORTANT」や「YOU MUST」などの強調語を追加して、指示の遵守率を高めることもしばしばあります。
Claude Code は、システムに変更を加える可能性のある操作（ファイル書き込み、多くの bash コマンド、MCP ツール など）には、デフォルトで許可を求める設計になっています。この保守的な設計は、安全性を最優先にしているためです。ただし、信頼できるツールや元に戻しやすい操作（例：ファイル編集、git commit）などは、許可リストを調整することで自由に実行できるようにできます。
ツールの許可管理には以下の4つの方法があります：
-
セッション中にプロンプトが表示されたときに 「Always allow（常に許可）」 を選択する
-
Claude Code 起動後に
/permissionsコマンド を使ってツールを追加／削除する- 例：常にファイル編集を許可するには
Editを、git commitを許可するにはBash(git commit:*)を追加 - MCP サーバーによる操作（例：Puppeteer ナビゲーション）を許可するには、
mcp__puppeteer__puppeteer_navigateを追加
- 例：常にファイル編集を許可するには
-
.claude/settings.jsonまたは~/.claude.jsonを 手動で編集（前者はソース管理で共有可能） -
セッション単位で
--allowedToolsCLI フラグ を使用して指定
Claude は gh CLI を使って GitHub 上で issue 作成、プルリクエスト作成、コメント閲覧などを実行できます。gh がインストールされていない場合でも GitHub API または MCP サーバー経由である程度操作は可能ですが、gh を使うことでよりスムーズに連携できます。
Claude はシェル環境にアクセスできるため、自身のために用意するようなスクリプトや関数群を Claude 向けにも整備できます。また、より複雑なツールを MCP や REST API を通じて使わせることも可能です。
Claude Code はあなたの bash 環境を継承します。標準的な Unix ツールや gh などは既に知っていますが、あなた独自の bash ツールについては以下のような手順で教える必要があります：
- Claude にツール名と使用例を伝える
--helpを実行するよう指示して、ツールのドキュメントを読ませる- よく使うツールは
CLAUDE.mdに記載する
Claude Code は MCP サーバーおよびクライアントの両方として機能します。クライアントとしては、複数の MCP サーバーに接続して、それらのツールを以下の3つの方法で利用できます：
-
プロジェクト構成ファイル内
- 該当ディレクトリで Claude Code を実行したときに利用可能
-
グローバル構成ファイル内
- すべてのプロジェクトで利用可能
-
.mcp.jsonファイルにチェックインする- コードベースに関わるすべての開発者が利用可能
- 例として、Puppeteer や Sentry の MCP サーバーを
.mcp.jsonに追加すれば、そのリポジトリで作業するすべての開発者がすぐにそれらを使用可能になります
MCP を使う際には、起動時に --mcp-debug フラグを付けることで構成の問題を特定しやすくなります。
デバッグループやログ解析など、繰り返し行うワークフローについては、プロンプトテンプレートを .claude/commands フォルダ内の Markdown ファイルとして保存しておくと便利です。これらはスラッシュコマンドメニューで / を入力したときに使用可能になります。これらのコマンドは git にチェックインしてチーム全体で共有可能です。
カスタムスラッシュコマンドでは、$ARGUMENTS という特別なキーワードを使用することで、コマンド実行時の引数を渡せます。
以下は GitHub issue を自動的に取得して修正するスラッシュコマンドの例です：
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.
この内容を .claude/commands/fix-github-issue.md に保存すると、Claude Code 上では /project:fix-github-issue コマンドとして利用できます。たとえば、/project:fix-github-issue 1234 と入力することで issue #1234 の修正処理が走ります。同様に、個人用コマンドを ~/.claude/commands フォルダに保存すれば、すべてのセッションでそれらを使用可能です。
Claude Code は特定のワークフローを強制せず、自由度の高い使い方が可能です。その中でも、Anthropic ユーザーコミュニティの中で効果的だったワークフローのいくつかを紹介します。
多くの問題に対応できる汎用的なワークフローです：
-
Claude に関連ファイル、画像、URL を読ませる
- 一般的な指示（「ログ処理してるファイル読んで」）でも、ファイル名指定（「logging.py を読んで」）でも良い
- ただし「まだコードは書かないで」と明確に伝えること
- この時点で サブエージェントの利用を検討すると効果的です。初期段階で Claude に「調査」や「検証」などを複数エージェントに分担させることで、コンテキストの節約と効率化を両立できます
-
Claude に「どう問題にアプローチするか」の計画を立てさせる
- 「think」という単語を使うと、Claude の「思考モード」が強化され、選択肢をより深く評価します
- 以下のように段階的に思考予算を増やせます：
"think"<"think hard"<"think harder"<"ultrathink" - 計画内容が良さそうであれば、そのままドキュメントや GitHub issue に落とし込んでおくと、実装フェーズで失敗した際に戻れる安全ポイントになります
-
Claude に実際のコードを実装させる
- 実装中にも、随時「この解決策は妥当か？」とセルフチェックを促すとよい
-
Claude にコミットさせ、必要であればプルリクを作成させる
- README や Changelog の更新もこのタイミングで指示すると良い
特に #1 と #2 の段階が重要です。いきなり実装に進ませると、Claude が「見切り発車」的にコードを書いてしまうことがあります。複雑な問題では、先に調査・計画を挟むことで成功率が大きく向上します。
このワークフローは、ユニットテスト、統合テスト、E2E テストなどによって容易に検証可能な変更に特に有効で、Anthropic 社内でも人気のスタイルです。エージェント型コーディングにおいて、テスト駆動開発（TDD）はさらに強力になります。
-
想定される入力／出力ペアをもとに、Claude にテストを書かせる
- Claude に「テスト駆動開発をする」と明示的に伝えましょう。これにより、まだ存在しない実装をモックで埋めるような行動を避けられます。
-
Claude にテストを実行させ、失敗を確認させる
- この段階では「実装コードはまだ書かないで」と指示しておくと効果的です。
-
テストが納得のいくものになったら、Claude にそれをコミットさせる
-
Claude に「テストが通るコードを書く」よう依頼する
- このとき「テストは変更しないで」と明記する
- Claude に「すべてのテストが通るまで繰り返す」ように指示すると、コード→テスト→修正のループを自動的に実行します
- また、この段階では「この実装がテストに過剰適合していないか？」を サブエージェントに確認させる 指示も効果的です
-
最終的にコードに満足したら、Claude にそれをコミットさせる
Claude は、明確な目標（＝テストケース、UIモック、期待される出力など） を与えることで最も力を発揮します。Claude に結果を観察させ、評価し、改善させるサイクルを回すことが鍵です。
これは b のテスト駆動と似ていますが、視覚的な成果物（デザインモックなど）を Claude に目標として与える点が異なります。
-
Claude にブラウザのスクリーンショットを撮らせる方法を用意する
- 例：Puppeteer MCP サーバー、iOS シミュレータ MCP、あるいは手動でスクショをコピー＆ペースト
-
Claude に視覚的なモック（スクショなど）を提供する
- 画像をコピー＆ペーストするか、ファイルパスを指定するだけで良い
-
Claude にデザインをコードで実装させ、スクリーンショットを撮らせ、モックと一致するまで繰り返す
-
満足したらコミットさせる
人間と同様、Claude も反復を重ねることで成果が大きく改善されます。1回目の出力はそこそこかもしれませんが、2〜3回繰り返すだけで大きく洗練されていきます。Claude に「自分の成果物を見る手段」を与えると効果的です。
Claude の操作をすべて監視する代わりに、claude --dangerously-skip-permissions を使えば、すべての許可チェックをスキップし、Claude にタスクを一気にやらせることができます。これは lint エラーの修正やボイラープレート生成などのタスクに特に便利です。
ただし、任意コマンドを実行させるのは危険であり、データ損失やシステム破損、さらにはデータ漏洩（例：プロンプトインジェクション） のリスクがあります。これを最小限に抑えるには、インターネット接続のないコンテナ内でこのオプションを使ってください。以下は安全な実行環境の例です：
新しいコードベースにオンボーディングする際には、Claude Code を学習や探索目的で使うと非常に効果的です。ペアプログラミング中に他のエンジニアに聞くような質問を、Claude にそのまま聞いてみましょう。Claude はコードベース全体をエージェント的に探索して、以下のような一般的な質問にも答えられます：
- ログ機能はどう実装されている？
- 新しい API エンドポイントはどう作る？
foo.rsの 134 行目のasync move { ... }は何をしてる？CustomerOnboardingFlowImplはどんな例外ケースに対応している？- なぜ 333 行目では
bar()ではなくfoo()を呼んでいるの？ baz.pyの 334 行目と同等の Java のコードは？
Anthropic 社内では、Claude Code を使ったこの方法がオンボーディングの標準となっており、立ち上がり時間を大幅に短縮し、他のエンジニアへの負担も軽減しています。特別なプロンプトは不要で、ただ質問すれば OK です。
Claude は、多くの Git 操作を効果的にこなすことができます。Anthropic のエンジニアの中には、Git 関連の操作の90%以上を Claude に任せている人もいます。
Claude が得意とする Git 操作例：
-
Git 履歴の検索
- 例：「v1.2.3 に含まれた変更は何か？」「この機能のオーナーは誰か？」「なぜこの API の設計になったのか？」といった質問に答えるために、Claude に Git 履歴を探索させることができます。
-
コミットメッセージの作成
- Claude は差分や直近の履歴を自動的に読み取り、文脈に合った適切なメッセージを生成します。
-
複雑な Git 操作の処理
- ファイルの巻き戻し、リベースの競合解決、パッチの比較や適用などを自動化できます。
Claude Code は GitHub 上での作業も自動化できます：
-
プルリクエストの作成
- Claude は
"pr"という短縮表記を理解し、差分と周辺文脈を元に適切なコミットメッセージや PR を生成します。
- Claude は
-
コードレビューコメントの修正対応
- PR 上のシンプルなレビューコメントに対して「修正して」と伝えるだけで、Claude が修正し PR ブランチにプッシュしてくれます。
-
ビルド失敗やリント警告の修正
-
オープンな issue の分類・トリアージ
- Claude に「open issue をひとつずつ見てカテゴリ分けして」と依頼すれば処理可能です。
これらを使えば、gh コマンドラインの構文を覚えずに、日常的な GitHub 作業を自動化できます。
Anthropic の研究者やデータサイエンティストは、Claude Code を用いて Jupyter ノートブックを読み書きしています。Claude は画像を含む出力を解釈できるため、データの探索や対話的分析がスムーズに行えます。
明示的なプロンプトやワークフローは不要ですが、以下のような方法が推奨されています：
- Claude Code と
.ipynbファイルを VS Code で横並び に開いて作業する
また、ノートブックの可読性や見栄えの向上を Claude に依頼することも可能です。「このノートブックを他の人に見せる用に美しく整えて」と伝えるだけで、見た目や視覚化を改善してくれます。特に「美的に見やすくして」といった明示は効果的です。
以下のベストプラクティスは、どのようなワークフローにも共通して有効です。
Claude Code の成功率は、最初の指示が具体的であるほど大幅に向上します。明確な初期指示を与えることで、途中の修正が少なくなり、スムーズに目的にたどり着けます。
具体例：
| 悪い例 | 良い例 |
|---|---|
foo.py にテストを追加して |
foo.py に新しいテストケースを書いて。ログアウト中のユーザーを扱うエッジケースに対応して。モックは使わないこと。 |
ExecutionFactory の API ってなんで変なの？ |
ExecutionFactory の git 履歴を見て、API の設計がこうなった経緯を要約して。 |
カレンダーウィジェット追加して |
ホームページに既存のウィジェットがどう実装されているかを確認して、コードとインターフェースの分離の仕方を理解して。例として HotDogWidget.php を参考に。次に、同じパターンに従って、月を選択できて前後の年にページ移動できる新しいカレンダーウィジェットを作って。既存ライブラリ以外は使わないで。 |
Claude は意図を推測する力はありますが、心を読むことはできません。具体性があるほど、期待通りの結果になりやすいです。
Claude は画像や図の理解に優れており、以下の方法で活用できます：
-
スクリーンショットを貼り付ける
- Mac の場合、
cmd+ctrl+shift+4を押すとクリップボードにスクリーンショットを保存できます（cmd+vではなくctrl+vで貼り付け） - リモート環境ではこの方法は動作しないことがあります
- Mac の場合、
-
画像を直接ドラッグ & ドロップでプロンプトに追加する
-
画像ファイルのパスを指定する
これらは特に UI 開発でデザインモックを参照したい場合や、視覚的チャートを使った分析・デバッグに有効です。 視覚的コンテキストを追加できない場合でも、「見た目が重要である」と Claude に伝えることは効果的です。
Claude に見せたい／編集してほしいファイルやフォルダは、明確にファイルパスを伝えましょう。 リポジトリ内の任意のファイルやフォルダは タブ補完で素早く指定できます。
プロンプトと一緒に具体的な URL を貼ることで、Claude に外部の情報を取得・読み込みさせることができます。
同じドメイン（例：docs.foo.com）に繰り返しアクセスする場合は、/permissions を使って 許可リストにドメインを追加すると、今後の確認プロンプトを回避できます。
Claude の「自動承認モード（shift+tab で切替）」を使えば、自律的に作業を進めさせることも可能ですが、最良の結果を得るには人間が積極的に関与し、調整を重ねるのが効果的です。
最初にタスクを詳しく説明するのがベストですが、途中での方向修正も重要です。
Claude で効果的に方向修正するための 4 つのツール：
-
コードを書かせる前に計画を立てさせる
- 「まずプランを立てて、それが良ければコード書いて」と明示的に伝える
-
Escape キーで途中停止する
- Claude が「思考中」「ツール実行中」「ファイル編集中」など、どの段階でも ESC で処理を一時停止し、指示の追加や方向転換が可能
-
ESC を 2 回タップして履歴をさかのぼる
- 過去のプロンプトを編集して別の方向性を試す。結果が良くなるまで何度でも繰り返し調整可能
-
Claude に「変更を元に戻して」と頼む
- ②と組み合わせて、別のアプローチを試すことができます
Claude Code が最初の試行で完璧な回答をすることもありますが、これらの調整ツールを活用することで、より良い解決策をより早く得られる可能性が高まります。
長時間のセッションでは、会話履歴・ファイル内容・コマンドなどが増えすぎて Claude のコンテキストが汚れてしまうことがあります。これによりパフォーマンスが低下したり、Claude が関係のない情報に注意を奪われることもあります。
タスクごとに /clear を使ってコンテキストをリセットすることで、集中力を保った出力が得られます。
コードの移行、大量の lint エラー修正、複雑なビルドスクリプト実行など、ステップが多く、網羅性が求められるタスクでは、Claude に Markdown ファイルや GitHub issue を「チェックリスト兼作業メモ」として使わせると効果的です。
例：大量の lint エラーを修正したいとき
-
Claude に lint コマンドを実行させる
- エラー内容（ファイル名と行番号付き）を Markdown チェックリストとして出力させる
-
Claude にチェック項目を一つずつ処理させる
- 修正→検証→完了チェックという流れを繰り返させる
このように「可視化された作業リスト」を Claude に使わせることで、長期的なタスク管理や進捗の把握が容易になります。
Claude にデータを渡す方法は複数あります：
-
プロンプトに直接コピペ（最も一般的）
-
Claude Code にパイプで渡す（例：
cat foo.txt | claude）- ログ、CSV、大量データの解析に便利
-
bash コマンド、MCP ツール、カスタムスラッシュコマンドを使ってデータ取得を指示
-
ファイルパスや URL を指定して、Claude にファイルを読むよう指示する
- 画像ファイルも対象にできます
多くのセッションでは、これらの手段を組み合わせることで、より高度な解析や調査を実現しています。 例：ログファイルをパイプで渡し、その後ツールで追加のコンテキストを取得しながらデバッグさせる。
Claude Code は、CI（継続的インテグレーション）、プリコミットフック、ビルドスクリプト、自動化処理など、非対話型コンテキストに適した ヘッドレスモード を備えています。
プロンプトに -p フラグを付けて起動することでヘッドレスモードが有効になります。--output-format stream-json を使えば JSON 形式でのストリーム出力も可能です。
注意：ヘッドレスモードはセッション間で状態を保持しません。毎回明示的に起動する必要があります。
ヘッドレスモードは、GitHub イベントをトリガーとした自動処理に活用できます。たとえば、新しい issue が作成されたときに Claude を起動し、内容を分析・分類してラベルを付けることができます。
参考：Anthropic の公開リポジトリ Claude Code GitHub Action
Claude Code は、一般的なリントツールでは検出できないような 主観的コードレビューも自動化できます。たとえば：
- タイポ
- 古いコメント
- 誤解を招く関数名／変数名
- 非一貫性のある記述 など
参考：Claude Code Action (コードレビュー用)
Claude はこれらの「見落としがちな問題」を検出し、改善案を提示してくれます。
Claude を単体で使うだけでなく、複数の Claude インスタンスを並列に実行することで、より強力なワークフローを実現できます。
この方法は、あたかも「ペアプログラミング」を自動化するようなものです。エンジニア同士のように、異なる視点や独立した文脈でタスクを分けることで、より高品質な結果が得られます。
手順例：
- Claude にコードを書かせる
/clearを実行する、または別のターミナルで 2 つ目の Claude を起動- 2 つ目の Claude に、1 つ目が書いたコードのレビューを依頼
- 3 つ目の Claude（または再度
/clear）を起動し、コードとレビュー結果の両方を読み取らせて修正させる
テスト作成にも同様の方法が使えます：
- Claude A がテストを書く
- Claude B がそれを通すコードを書く
さらに高度な使い方として、Claude 間で 作業ノート（scratchpad）を共有させることで、メッセージのやり取りも可能になります。
Claude のステップ完了を待つのではなく、Anthropic の多くのエンジニアは以下のように運用しています：
- 複数（3〜4）の Git チェックアウトを別フォルダに作成
- それぞれのフォルダを別のターミナルタブで開く
- 各タブで Claude を起動し、異なるタスクを割り当てる
- タブを切り替えながら進捗を確認し、必要に応じて承認や却下を行う
複数のチェックアウトが必要な場合、より軽量な方法として **git worktree（ワークツリー）**が有効です。これは、ひとつの Git 履歴を共有しながら、複数のブランチを異なるフォルダで同時に作業できるというものです。
用途：認証システムのリファクタと、データ可視化コンポーネントの新規開発を並行で進めたいときなど、タスクが重複しない場合に最適。
手順：
-
ワークツリーを作成する
git worktree add ../project-feature-a feature-a -
それぞれのワークツリーで Claude を起動する
cd ../project-feature-a && claude -
必要な数だけワークツリーを追加して、ターミナルタブを分けて管理
運用のコツ：
- 命名規則を統一する
- タブごとにワークツリーを固定
- Mac の iTerm2 を使っている場合は、通知設定を有効にして Claude の応答を見逃さないようにする
- IDE もタブ分けで整理
- 終了後は
git worktree remove ../project-feature-aでクリーンアップ
claude -p を使ってヘッドレスモードを起動すれば、Claude Code をより大きな自動化ワークフローに統合できます。以下は主な2パターンです：
例：2000件のファイルを React → Vue に移行したい
- Claude に、作業リストを生成するスクリプトを書かせる
- 各タスクに対して、以下のように自動で Claude を呼び出す：
claude -p "foo.py を React から Vue に移行して。完了したら OK を返し、失敗したら FAIL を返して。" \
--allowedTools Edit Bash(git commit:*)- スクリプトを何度か実行し、プロンプトの調整を繰り返す
既存のデータ処理パイプラインに Claude を組み込む場合：
claude -p "<プロンプト内容>" --json | your_commandこのようにパイプで次の処理に渡すだけで自動化できます。JSON 出力（オプション）を使えば、構造的なデータ処理がしやすくなります。
補足：
--verboseフラグを使うと Claude の呼び出しデバッグに便利。 本番環境では--verboseを OFF にしてクリーンな出力を推奨します。
執筆：Boris Cherny
本記事は、Claude Code を活用している幅広いユーザーコミュニティのベストプラクティスに基づいています。彼らの創造的なアプローチやワークフローは、常に私たちにインスピレーションを与えてくれています。
また、次の Anthropic のエンジニアたちにも特別な感謝を捧げます：
- Daisy Hollman
- Ashwin Bhat
- Cat Wu
- Sid Bidasaria
- Cal Rueb
- Nodir Turakulov
- Barry Zhang
- Drew Hodun
そして、他にも多くの Anthropic エンジニアたちが、Claude Code に関する貴重な知見と実務経験を提供してくれました。彼らの協力により、この記事の推奨事項が実践的かつ有用なものとなりました。
原文
Claude Code Best Practices \ Anthropic
Engineering at Anthropic
We recently released Claude Code, a command line tool for agentic coding. Developed as a research project, Claude Code gives Anthropic engineers and researchers a more native way to integrate Claude into their coding workflows.
Claude Code is intentionally low-level and unopinionated, providing close to raw model access without forcing specific workflows. This design philosophy creates a flexible, customizable, scriptable, and safe power tool. While powerful, this flexibility presents a learning curve for engineers new to agentic coding tools—at least until they develop their own best practices.
This post outlines general patterns that have proven effective, both for Anthropic's internal teams and for external engineers using Claude Code across various codebases, languages, and environments. Nothing in this list is set in stone nor universally applicable; consider these suggestions as starting points. We encourage you to experiment and find what works best for you!
Looking for more detailed information? Our comprehensive documentation at claude.ai/code covers all the features mentioned in this post and provides additional examples, implementation details, and advanced techniques.
1. Customize your setup
Claude Code is an agentic coding assistant that automatically pulls context into prompts. This context gathering consumes time and tokens, but you can optimize it through environment tuning.
a. Create
CLAUDE.mdfilesCLAUDE.mdis a special file that Claude automatically pulls into context when starting a conversation. This makes it an ideal place for documenting:There’s no required format for
CLAUDE.mdfiles. We recommend keeping them concise and human-readable. For example:You can place
CLAUDE.mdfiles in several locations:claudefrom (the most common usage). Name itCLAUDE.mdand check it into git so that you can share it across sessions and with your team (recommended), or name itCLAUDE.local.mdand.gitignoreitclaude. This is most useful for monorepos, where you might runclaudefromroot/foo, and haveCLAUDE.mdfiles in bothroot/CLAUDE.mdandroot/foo/CLAUDE.md. Both of these will be pulled into context automaticallyclaude. This is the inverse of the above, and in this case, Claude will pull inCLAUDE.mdfiles on demand when you work with files in child directories~/.claude/CLAUDE.md), which applies it to all your claude sessionsWhen you run the
/initcommand, Claude will automatically generate aCLAUDE.mdfor you.b. Tune your
CLAUDE.mdfilesYour
CLAUDE.mdfiles become part of Claude’s prompts, so they should be refined like any frequently used prompt. A common mistake is adding extensive content without iterating on its effectiveness. Take time to experiment and determine what produces the best instruction following from the model.You can add content to your
CLAUDE.mdmanually or press the#key to give Claude an instruction that it will automatically incorporate into the relevantCLAUDE.md. Many engineers use#frequently to document commands, files, and style guidelines while coding, then includeCLAUDE.mdchanges in commits so team members benefit as well.At Anthropic, we occasionally run
CLAUDE.mdfiles through the prompt improver and often tune instructions (e.g. adding emphasis with "IMPORTANT" or "YOU MUST") to improve adherence.c. Curate Claude's list of allowed tools
By default, Claude Code requests permission for any action that might modify your system: file writes, many bash commands, MCP tools, etc. We designed Claude Code with this deliberately conservative approach to prioritize safety. You can customize the allowlist to permit additional tools that you know are safe, or to allow potentially unsafe tools that are easy to undo (e.g., file editing,
git commit).There are four ways to manage allowed tools:
/permissionscommand after starting Claude Code to add or remove tools from the allowlist. For example, you can addEditto always allow file edits,Bash(git commit:*)to allow git commits, ormcp__puppeteer__puppeteer_navigateto allow navigating with the Puppeteer MCP server..claude/settings.jsonor~/.claude.json(we recommend checking the former into source control to share with your team).--allowedToolsCLI flag for session-specific permissions.d. If using GitHub, install the gh CLI
Claude knows how to use the
ghCLI to interact with GitHub for creating issues, opening pull requests, reading comments, and more. Withoutghinstalled, Claude can still use the GitHub API or MCP server (if you have it installed).2. Give Claude more tools
Claude has access to your shell environment, where you can build up sets of convenience scripts and functions for it just like you would for yourself. It can also leverage more complex tools through MCP and REST APIs.
a. Use Claude with bash tools
Claude Code inherits your bash environment, giving it access to all your tools. While Claude knows common utilities like unix tools and
gh, it won't know about your custom bash tools without instructions:--helpto see tool documentationCLAUDE.mdb. Use Claude with MCP
Claude Code functions as both an MCP server and client. As a client, it can connect to any number of MCP servers to access their tools in three ways:
.mcp.jsonfile (available to anyone working in your codebase). For example, you can add Puppeteer and Sentry servers to your.mcp.json, so that every engineer working on your repo can use these out of the box.When working with MCP, it can also be helpful to launch Claude with the
--mcp-debugflag to help identify configuration issues.c. Use custom slash commands
For repeated workflows—debugging loops, log analysis, etc.—store prompt templates in Markdown files within the
.claude/commandsfolder. These become available through the slash commands menu when you type/. You can check these commands into git to make them available for the rest of your team.Custom slash commands can include the special keyword
$ARGUMENTSto pass parameters from command invocation.For example, here’s a slash command that you could use to automatically pull and fix a Github issue:
Putting the above content into
.claude/commands/fix-github-issue.mdmakes it available as the/project:fix-github-issuecommand in Claude Code. You could then for example use/project:fix-github-issue 1234to have Claude fix issue #1234. Similarly, you can add your own personal commands to the~/.claude/commandsfolder for commands you want available in all of your sessions.3. Try common workflows
Claude Code doesn’t impose a specific workflow, giving you the flexibility to use it how you want. Within the space this flexibility affords, several successful patterns for effectively using Claude Code have emerged across our community of users:
a. Explore, plan, code, commit
This versatile workflow suits many problems:
Steps #1-#2 are crucial—without them, Claude tends to jump straight to coding a solution. While sometimes that's what you want, asking Claude to research and plan first significantly improves performance for problems requiring deeper thinking upfront.
b. Write tests, commit; code, iterate, commit
This is an Anthropic-favorite workflow for changes that are easily verifiable with unit, integration, or end-to-end tests. Test-driven development (TDD) becomes even more powerful with agentic coding:
Claude performs best when it has a clear target to iterate against—a visual mock, a test case, or another kind of output. By providing expected outputs like tests, Claude can make changes, evaluate results, and incrementally improve until it succeeds.
c. Write code, screenshot result, iterate
Similar to the testing workflow, you can provide Claude with visual targets:
Like humans, Claude's outputs tend to improve significantly with iteration. While the first version might be good, after 2-3 iterations it will typically look much better. Give Claude the tools to see its outputs for best results.
d. Safe YOLO mode
Instead of supervising Claude, you can use
claude --dangerously-skip-permissionsto bypass all permission checks and let Claude work uninterrupted until completion. This works well for workflows like fixing lint errors or generating boilerplate code.Letting Claude run arbitrary commands is risky and can result in data loss, system corruption, or even data exfiltration (e.g., via prompt injection attacks). To minimize these risks, use
--dangerously-skip-permissionsin a container without internet access. You can follow this reference implementation using Docker Dev Containers.e. Codebase Q&A
When onboarding to a new codebase, use Claude Code for learning and exploration. You can ask Claude the same sorts of questions you would ask another engineer on the project when pair programming. Claude can agentically search the codebase to answer general questions like:
async move { ... }do on line 134 offoo.rs?CustomerOnboardingFlowImplhandle?foo()instead ofbar()on line 333?baz.pyin Java?At Anthropic, using Claude Code in this way has become our core onboarding workflow, significantly improving ramp-up time and reducing load on other engineers. No special prompting is required! Simply ask questions, and Claude will explore the code to find answers.
f. Use Claude to interact with git
Claude can effectively handle many git operations. Many Anthropic engineers use Claude for 90%+ of our git interactions:
g. Use Claude to interact with GitHub
Claude Code can manage many GitHub interactions:
This eliminates the need to remember
ghcommand line syntax while automating routine tasks.h. Use Claude to work with Jupyter notebooks
Researchers and data scientists at Anthropic use Claude Code to read and write Jupyter notebooks. Claude can interpret outputs, including images, providing a fast way to explore and interact with data. There are no required prompts or workflows, but a workflow we recommend is to have Claude Code and a
.ipynbfile open side-by-side in VS Code.You can also ask Claude to clean up or make aesthetic improvements to your Jupyter notebook before you show it to colleagues. Specifically telling it to make the notebook or its data visualizations “aesthetically pleasing” tends to help remind it that it’s optimizing for a human viewing experience.
4. Optimize your workflow
The suggestions below apply across all workflows:
a. Be specific in your instructions
Claude Code’s success rate improves significantly with more specific instructions, especially on first attempts. Giving clear directions upfront reduces the need for course corrections later.
For example:
Claude can infer intent, but it can't read minds. Specificity leads to better alignment with expectations.
b. Give Claude images
Claude excels with images and diagrams through several methods:
This is particularly useful when working with design mocks as reference points for UI development, and visual charts for analysis and debugging. If you are not adding visuals to context, it can still be helpful to be clear with Claude about how important it is for the result to be visually appealing.
c. Mention files you want Claude to look at or work on
Use tab-completion to quickly reference files or folders anywhere in your repository, helping Claude find or update the right resources.
d. Give Claude URLs
Paste specific URLs alongside your prompts for Claude to fetch and read. To avoid permission prompts for the same domains (e.g., docs.foo.com), use
/permissionsto add domains to your allowlist.e. Course correct early and often
While auto-accept mode (shift+tab to toggle) lets Claude work autonomously, you'll typically get better results by being an active collaborator and guiding Claude's approach. You can get the best results by thoroughly explaining the task to Claude at the beginning, but you can also course correct Claude at any time.
These four tools help with course correction:
Though Claude Code occasionally solves problems perfectly on the first attempt, using these correction tools generally produces better solutions faster.
f. Use
/clearto keep context focusedDuring long sessions, Claude's context window can fill with irrelevant conversation, file contents, and commands. This can reduce performance and sometimes distract Claude. Use the
/clearcommand frequently between tasks to reset the context window.g. Use checklists and scratchpads for complex workflows
For large tasks with multiple steps or requiring exhaustive solutions—like code migrations, fixing numerous lint errors, or running complex build scripts—improve performance by having Claude use a Markdown file (or even a GitHub issue!) as a checklist and working scratchpad:
For example, to fix a large number of lint issues, you can do the following:
h. Pass data into Claude
Several methods exist for providing data to Claude:
cat foo.txt | claude), particularly useful for logs, CSVs, and large dataMost sessions involve a combination of these approaches. For example, you can pipe in a log file, then tell Claude to use a tool to pull in additional context to debug the logs.
5. Use headless mode to automate your infra
Claude Code includes headless mode for non-interactive contexts like CI, pre-commit hooks, build scripts, and automation. Use the
-pflag with a prompt to enable headless mode, and--output-format stream-jsonfor streaming JSON output.Note that headless mode does not persist between sessions. You have to trigger it each session.
a. Use Claude for issue triage
Headless mode can power automations triggered by GitHub events, such as when a new issue is created in your repository. For example, the public Claude Code repository uses Claude to inspect new issues as they come in and assign appropriate labels.
b. Use Claude as a linter
Claude Code can provide subjective code reviews beyond what traditional linting tools detect, identifying issues like typos, stale comments, misleading function or variable names, and more.
6. Uplevel with multi-Claude workflows
Beyond standalone usage, some of the most powerful applications involve running multiple Claude instances in parallel:
a. Have one Claude write code; use another Claude to verify
A simple but effective approach is to have one Claude write code while another reviews or tests it. Similar to working with multiple engineers, sometimes having separate context is beneficial:
/clearor start a second Claude in another terminal/clearagain) to read both the code and review feedbackYou can do something similar with tests: have one Claude write tests, then have another Claude write code to make the tests pass. You can even have your Claude instances communicate with each other by giving them separate working scratchpads and telling them which one to write to and which one to read from.
This separation often yields better results than having a single Claude handle everything.
b. Have multiple checkouts of your repo
Rather than waiting for Claude to complete each step, something many engineers at Anthropic do is:
c. Use git worktrees
This approach shines for multiple independent tasks, offering a lighter-weight alternative to multiple checkouts. Git worktrees allow you to check out multiple branches from the same repository into separate directories. Each worktree has its own working directory with isolated files, while sharing the same Git history and reflog.
Using git worktrees enables you to run multiple Claude sessions simultaneously on different parts of your project, each focused on its own independent task. For instance, you might have one Claude refactoring your authentication system while another builds a completely unrelated data visualization component. Since the tasks don't overlap, each Claude can work at full speed without waiting for the other's changes or dealing with merge conflicts:
git worktree add ../project-feature-a feature-acd ../project-feature-a && claudeSome tips:
git worktree remove ../project-feature-ad. Use headless mode with a custom harness
claude -p(headless mode) integrates Claude Code programmatically into larger workflows while leveraging its built-in tools and system prompt. There are two primary patterns for using headless mode:1. Fanning out handles large migrations or analyses (e.g., analyzing sentiment in hundreds of logs or analyzing thousands of CSVs):
claude -p “migrate foo.py from React to Vue. When you are done, you MUST return the string OK if you succeeded, or FAIL if the task failed.” --allowedTools Edit Bash(git commit:*)2. Pipelining integrates Claude into existing data/processing pipelines:
claude -p “<your prompt>” --json | your_command, whereyour_commandis the next step of your processing pipelineFor both of these use cases, it can be helpful to use the
--verboseflag for debugging the Claude invocation. We generally recommend turning verbose mode off in production for cleaner output.What are your tips and best practices for working with Claude Code? Tag @AnthropicAI so we can see what you're building!
Acknowledgements
Written by Boris Cherny. This work draws upon best practices from across the broader Claude Code user community, whose creative approaches and workflows continue to inspire us. Special thanks also to Daisy Hollman, Ashwin Bhat, Cat Wu, Sid Bidasaria, Cal Rueb, Nodir Turakulov, Barry Zhang, Drew Hodun and many other Anthropic engineers whose valuable insights and practical experience with Claude Code helped shape these recommendations.