https://kafkafinancialgroup.hatenablog.com/entry/2025/04/20/105324

Anthropic が提供する claude-code は、エージェント的なコーディングを実現するためのコマンドラインツールです1 13。このツールは、開発者が Claude をよりネイティブにコーディングワークフローに統合できるように、研究プロジェクトとして開発されました1。意図的に低レベルで特定のワークフローを強制しない設計により、柔軟性、カスタマイズ性、スクリプト可能性、安全性を備えた強力なツールとなっています1。

以下に、Anthropic 社内チームや外部の開発者が様々なコードベース、言語、環境で claude-code を使用して効果的であると証明された一般的なパターンとベストプラクティスを紹介します1 8。これらは普遍的に適用できるものではなく、あくまで出発点として、各自で実験し最適な方法を見つけることが推奨されています1。

セットアップのカスタマイズ

claude-code は、プロンプトに自動的にコンテキストを取り込むエージェント的なコーディングアシスタントです1。このコンテキスト収集は時間とトークンを消費しますが、環境を調整することで最適化できます1。

CLAUDE.md ファイルの活用
CLAUDE.md は、claude-code が会話開始時に自動的にコンテキストに取り込む特別なファイルです1。プロジェクト固有の情報（共通のbashコマンド、コアファイル、コードスタイルガイドライン、テスト手順、リポジトリの作法、開発環境設定など）を記述するのに理想的です1。

作成と配置: リポジトリのルートや claude コマンドを実行するディレクトリに CLAUDE.md (git管理推奨) または CLAUDE.local.md (.gitignore推奨) を配置します1。親ディレクトリや子ディレクトリ、ホームフォルダ (~/.claude/CLAUDE.md) にも配置でき、それぞれコンテキストに取り込まれます1。/init コマンドで自動生成も可能です1 4。
調整: CLAUDE.md の内容はプロンプトの一部となるため、頻繁に使用されるプロンプトと同様に洗練させる必要があります1 2。効果を確認しながら実験し、モデルからの最適な指示追従を引き出す内容に調整します1 2。# キーを押すか手動で編集し、変更をコミットしてチームメンバーと共有することが推奨されます1 2。強調（"IMPORTANT", "YOU MUST"）を加えることも有効です1 2。

許可ツールの管理
デフォルトでは、claude-code はシステムを変更する可能性のあるアクション（ファイル書き込み、多くのbashコマンド、MCPツールなど）に対して許可を求めます1 2。これは安全性を優先するための意図的な設計です1 2。以下の方法で許可リストをカスタマイズできます1 2:

セッション中にプロンプトが表示された際に「常に許可」を選択する1 2。
claude-code 起動後に /allowed-tools コマンドを使用する（例: /allowed-tools Edit でファイル編集を常に許可）1 2。
設定ファイル (.claude/settings.json または ~/.claude.json) を手動で編集する1 2。
--allowedTools CLI フラグでセッション固有の権限を設定する1 2。

GitHub CLI (gh) のインストール
GitHub を使用している場合、gh CLI をインストールすると、Claude が GitHub と連携して Issue の作成、プルリクエストのオープン、コメントの読み取りなどを行えるようになります1 2。gh がなくても、GitHub API や MCP サーバーがインストールされていれば、それらを使用できます1 2。

Claude へのツール提供

Claude はシェル環境にアクセスでき、自分で使うのと同じように便利なスクリプトや関数を Claude のために構築できます1。また、MCP や REST API を介してより複雑なツールも活用できます1。

Bash ツールの活用
Claude はユーザーの bash 環境を継承し、すべてのツールにアクセスできます1。unix ツールや gh のような一般的なユーティリティは知っていますが、カスタム bash ツールについては指示が必要です1。ツール名と使用例を伝えたり、--help を実行させたり、CLAUDE.md に頻繁に使用するツールを文書化したりします1。

MCP (Model Context Protocol) の利用
claude-code は MCP サーバー兼クライアントとして機能します1 4。クライアントとして、複数の MCP サーバーに接続し、そのツールにアクセスできます1。設定はプロジェクト設定、グローバル設定、またはリポジトリにチェックインされた .mcp.json ファイルで行えます1。これにより、リポジトリで作業するすべてのエンジニアが、例えば Puppeteer や Sentry サーバーをすぐに利用できるようになります1。--mcp-debug フラグは設定問題の特定に役立ちます1。

カスタムスラッシュコマンド
繰り返しのワークフロー（デバッグループ、ログ分析など）のために、プロンプトテンプレートを .claude/commands フォルダ内の Markdown ファイルに保存します1。これらは / を入力するとスラッシュコマンドメニューから利用可能になります1。これらのコマンドを git にチェックインしてチームで共有できます1。カスタムスラッシュコマンドには、コマンド呼び出しからパラメータを渡すための特別なキーワード $ARGUMENTS を含めることができます1。
例えば、.claude/commands/fix-github-issue.md に以下の内容を記述すると、/project:fix-github-issue 1234 のように GitHub Issue #1234 を修正するコマンドとして利用できます1。

text

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 フォルダに追加することで、すべてのセッションで利用可能になります1。

一般的なワークフロー例

claude-code は特定のワークフローを強制しないため、柔軟な使い方が可能です1 2。以下はコミュニティで成功しているパターンです1 2 11。

探索、計画、コーディング、コミット
多くの問題に適した汎用的なワークフローです1 2。

探索: Claude に関連ファイル、画像、URL を読むように依頼します（コードはまだ書かないように指示）1 2。複雑な問題では、サブエージェントを使って詳細を確認させることを検討します1 2。
計画: 特定の問題へのアプローチ計画を立てさせます1 2。思考時間を増やすために「think」という単語を使うことを推奨します（"think" < "think hard" < "think harder" < "ultrathink" の順に思考予算が増加）1 2 3。計画が妥当であれば、ドキュメントや GitHub Issue に記録しておくと、後で戻るのに役立ちます1 2。
コーディング: 計画に基づきコードを実装させます1 2。実装中に解決策の妥当性を検証するよう依頼するのも良い方法です1 2。
コミット: 結果をコミットし、プルリクエストを作成させます1 2。必要に応じて README や変更ログの更新も依頼します1 2。

最初の探索と計画のステップは、より深い思考が必要な問題のパフォーマンスを大幅に向上させるために重要です1 2。

テスト駆動開発 (TDD)
単体テスト、統合テスト、E2E テストで容易に検証可能な変更に適したワークフローです1 2。

期待される入出力ペアに基づいてテストを書くよう依頼します1 2。TDD であることを明示し、モック実装を避けるように指示します1 2。
テストを実行し、失敗することを確認させます（実装コードはまだ書かないよう指示）1 2。
満足のいくテストができたらコミットさせます1 2。
テストを修正せずに、テストに合格するコードを書くよう依頼します1 2。すべてのテストが合格するまで反復させます1 2。独立したサブエージェントに実装がテストに過剰適合していないか検証させることも有効です1 2。
満足のいく変更ができたらコードをコミットさせます1 2。

ビジュアルターゲットを活用した反復
テストと同様に、視覚的な目標を提供することも有効です1。

ブラウザのスクリーンショットを撮る方法を提供します（例: Puppeteer MCP サーバー、手動コピー＆ペースト）1。
視覚的なモック（画像）を提供します（コピー＆ペースト、ドラッグ＆ドロップ、ファイルパス指定）1。
デザインをコードで実装し、結果のスクリーンショットを撮り、モックと一致するまで反復させます1。
満足したらコミットさせます1。

安全な YOLO モード
claude --dangerously-skip-permissions を使用すると、すべての許可チェックをバイパスし、Claude が中断なく作業を完了できます1。リントエラーの修正やボイラープレートコードの生成などに適しています1。リスクを最小限に抑えるため、インターネットアクセスのないコンテナ内で使用することが推奨されます1。

コードベースに関する Q&A
新しいコードベースの学習や探索に使用します1。ペアプログラミングで他のエンジニアに尋ねるような質問（「ロギングはどう機能するか？」「新しい API エンドポイントの作り方は？」など）を Claude に尋ねることができます1 4。Claude はコードベースを探索して回答します1。特別なプロンプティングは不要です1。

Git 操作の委任
多くの Git 操作（履歴検索、コミットメッセージ作成、複雑な操作（revert, rebase conflict 解消など））を Claude に任せることができます1。

GitHub 操作の委任
プルリクエストの作成（"pr" という略語も理解）、コードレビューコメントの修正、失敗したビルドやリンター警告の修正、オープンな GitHub Issue の分類とトリアージなどが可能です1。

Jupyter ノートブックとの連携
Jupyter ノートブックの読み書き、出力（画像を含む）の解釈が可能です1。VS Code で claude-code と .ipynb ファイルを並べて開くワークフローが推奨されます1。ノートブックの整理や美的改善を依頼することもできます1。

ワークフローの最適化

以下の提案はすべてのワークフローに適用されます1。

指示の具体性: より具体的な指示は、特に最初の試行での成功率を大幅に向上させます1。
画像の活用: スクリーンショットのペースト、画像のドラッグ＆ドロップ、ファイルパスの提供により、Claude は画像や図を効果的に利用できます1 7 15。UI 開発のデザインモックや、分析・デバッグ用の視覚的なチャートに特に有効です1。
ファイルや URL の明示: タブ補完を使ってファイルやフォルダを素早く参照させたり1、特定の URL をペーストして読み込ませたりします1。同じドメインへの許可プロンプトを避けるには /allowed-tools を使用します1。
早期の軌道修正: アクティブな協力者として Claude のアプローチを導くことで、より良い結果が得られます1。計画の確認、Escape キーでの中断、Escape キーのダブルタップでの履歴編集、変更の取り消し要求などが有効です1 14。
コンテキスト管理 (/clear): 長いセッションでは、/clear コマンドを頻繁に使用してコンテキストウィンドウをリセットし、パフォーマンス低下や注意散漫を防ぎます1。
チェックリスト/スクラッチパッド: 大規模なタスク（コード移行、多数のリントエラー修正など）では、Markdown ファイルや GitHub Issue をチェックリスト兼作業用スクラッチパッドとして使用させるとパフォーマンスが向上します1。
Claude へのデータ入力: プロンプトへの直接コピー＆ペースト、パイプ入力 (cat foo.txt | claude)、bash コマンドや MCP ツールでのデータ取得指示、ファイル読み込みや URL フェッチ指示など、複数の方法を組み合わせます1。

ヘッドレスモードによる自動化

claude-code には、CI、プリコミットフック、ビルドスクリプトなどの非対話的なコンテキストで使用するためのヘッドレスモードが含まれています1。-p フラグとプロンプトで有効にし、ストリーミング JSON 出力には --output-format stream-json を使用します1。

Issue の自動トリアージ: GitHub イベント（新しい Issue 作成など）によってトリガーされる自動化に使用できます1。
リンターとしての利用: 従来のリンティングツールが検出できない主観的なコードレビュー（タイポ、古いコメント、誤解を招く名前など）を提供できます1。

マルチ Claude ワークフロー

複数の Claude インスタンスを並行して実行することで、さらに強力なアプリケーションが可能になります1。

コード作成と検証の分離: 一方の Claude がコードを書き、もう一方がレビューまたはテストを行います1。コンテキストを分離することで、より良い結果が得られることがあります1。
複数チェックアウトによる並列作業: 複数の独立したタスクを同時に進めるために、リポジトリを別々のフォルダに 3〜4 回チェックアウトし、それぞれで Claude を起動します1。
Git Worktrees の活用: 複数の独立したタスクに対して、複数チェックアウトよりも軽量な代替手段です1 11。同じリポジトリから複数のブランチを別々のディレクトリにチェックアウトでき、それぞれが独立した作業ディレクトリを持ちながら、Git 履歴を共有します1。これにより、複数の Claude セッションを同時に実行し、プロジェクトの異なる部分で独立したタスクに集中させることができます1。
ヘッドレスモードとカスタムハーネス: claude -p (ヘッドレスモード) を使用して、claude-code をプログラム的に大規模なワークフローに統合します1。「ファンアウト」（大規模な移行や分析）や「パイプライン化」（既存のデータ/処理パイプラインへの統合）といったパターンがあります1。

これらのベストプラクティスは、claude-code を効果的に活用するための出発点となります1。詳細については、公式ドキュメント (claude.ai/code) を参照してください1。

Citations:

Perplexity の Eliot より: pplx.ai/share