Claude Code: Best practices for agentic coding

概要

この記事は、Anthropic が提唱する Claude Code のベストプラクティスについて記載します。

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

a. CLAUDE.md ファイルを作成する

CLAUDE.mdとは？

プロジェクトのルートに置く特別なファイルで、Claude Codeが会話開始時に自動的に読み込みます。いわば「Claudeへの申し送りメモ」です。

書くべき内容：

  • よく使うコマンド（npm run build など）
  • コーディングスタイルのルール
  • テスト方法
  • 開発環境のセットアップ手順
  • プロジェクト固有の注意事項

例：

# Bash commands

- npm run build: プロジェクトをビルド
- npm run typecheck: 型チェックを実行

# Code style

- ES modules (import/export) を使用、CommonJS (require) は使わない
- 可能な限りimportを分割代入する

# Workflow

- コード変更後は必ず型チェックを実行すること
- パフォーマンスのため、単一テストを優先して実行

配置場所：

場所 用途
リポジトリのルート 最も一般的。チームで共有可能
親ディレクトリ モノレポ向け。複数のCLAUDE.mdを階層的に読み込む
子ディレクトリ 必要に応じて動的に読み込まれる
~/.claude/CLAUDE.md 全セッションに適用される個人設定

b. CLAUDE.md をチューニングする

ポイントは「プロンプトエンジニアリングと同じ」という考え方です。

  • 単に書いて放置せず、効果を検証しながら改善する
  • # キーを押すと、Claude に指示を与えて自動的に CLAUDE.md に追記させられる
  • 「IMPORTANT」や「YOU MUST」などの強調表現を使うと遵守率が上がる

c. 許可ツールリストを管理する

Claude Code はデフォルトで安全のため、ファイル書き込みやコマンド実行時に毎回確認を求めます。

許可の設定方法（4つ）：

  1. セッション中に「Always allow」を選択
  2. /permissions コマンドで管理
    • 例: Edit → ファイル編集を常に許可
    • 例: Bash(git commit:*) → git commit を許可
  3. 設定ファイルを直接編集（.claude/settings.json）
  4. CLI フラグ --allowedTools でセッション単位の設定

d. GitHub を使うなら gh CLI をインストール

GitHub CLI（gh）をインストールすると、Claude は Issue 作成、PR 作成、コメント読み取りなどを直接行えるようになります。

2. Claude にツールを追加する

a. Bash ツールとの連携

Claude はあなたのシェル環境を引き継ぎます。つまり、あなたが使えるコマンドは Claude も使えます。

カスタムツールを使わせるには：

  1. ツール名と使用例を教える
  2. --help を実行させてドキュメントを読ませる
  3. よく使うツールは CLAUDE.md に記載

b. MCP（Model Context Protocol）との連携

MCP とは？
Claude Code を外部サービス（Puppeteer、Sentry など）と接続するためのプロトコルです。

設定方法：

  • プロジェクト設定（特定ディレクトリでのみ有効）
  • グローバル設定（全プロジェクトで有効）
  • .mcp.json ファイル（チーム全員が使える）

デバッグには --mcp-debug フラグが便利です。

c. カスタムスラッシュコマンド

繰り返し行う作業をテンプレート化できます。

作り方：

  1. .claude/commands/ フォルダにMarkdownファイルを作成
  2. $ARGUMENTS で引数を受け取れる

例（.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. Create a descriptive commit message
7. Push and create a PR

使用方法: /project:fix-github-issue 1234 → Issue #1234 を自動修正

3. おすすめワークフロー

a. 探索 → 計画 → コーディング → コミット

最も汎用的なワークフロー：

  1. 探索: 関連ファイルを読ませる（「まだコードは書かないで」と明示）
    • 複雑な問題では「サブエージェント」を使わせると効果的
  2. 計画: 解決策を考えさせる
    • 「think」「think hard」「ultrathink」で思考時間を増やせる
  3. 実装: コードを書かせる
  4. コミット: 結果をコミットしてPRを作成

重要: ステップ1-2を省略すると、Claude はいきなりコードを書き始めてしまいます。事前の調査・計画で品質が大幅に向上します。

b. テスト駆動開発（TDD）ワークフロー

  1. テスト作成: 期待する入出力に基づくテストを書かせる
  2. テスト失敗確認: 実装なしでテストが失敗することを確認
  3. テストをコミット
  4. 実装: テストをパスするコードを書かせる（テストは変更禁止）
  5. コードをコミット

Claude は明確な目標（テスト合格）があると、自律的に改善を繰り返せます。

c. ビジュアル駆動ワークフロー

  1. スクリーンショット機能を与える（Puppeteer MCP など）
  2. デザインモックを渡す
  3. 実装 → スクリーンショット確認 → 改善を繰り返す
  4. 満足したらコミット

d. コードベース Q&A

新しいプロジェクトへのオンボーディングに最適：

  • 「ロギングはどう動いてる？」
  • 「新しい API エンドポイントの作り方は？」
  • 「なぜ foo() の代わりに bar() を呼んでる？」

人間のエンジニアに質問するように、自然に聞けます。

f. Git 操作

Claude は git 操作の 90% 以上を代行できます：

  • git 履歴の検索
  • コミットメッセージの作成
  • リベースの競合解決
  • パッチの比較・適用

g. GitHub 操作

  • PR の作成（「pr」という略語も理解）
  • コードレビューコメントの修正
  • ビルド失敗の修正
  • Issue のトリアージ・分類

4. ワークフローの最適化

a. 具体的に指示する

❌ 悪い例 ✅ 良い例
foo.py にテストを追加して foo.py にログアウト時のエッジケースをカバーするテストを書いて。モックは使わないで
カレンダーウィジェットを追加して 既存のウィジェット（HotDogWidget.php など）のパターンを調べて、月選択・年ページネーション機能を持つカレンダーウィジェットを実装して

b. 画像を活用する

  • スクリーンショットを貼り付け（macOS: cmd+ctrl+shift+4 → ctrl+v）
  • 画像をドラッグ＆ドロップ
  • 画像ファイルパスを指定

c. ファイル参照には Tab 補完

@ やファイル名の途中で Tab を押すと、リポジトリ内のファイルを補完できます。

d. URL を渡す

Web ページの URL を貼ると、Claude が内容を取得して読みます。
よく使うドメインは /permissions で許可リストに追加しましょう。

e. 早めに軌道修正する

4つのテクニック：

  1. 計画を先に作らせる（「コードはまだ書かないで」）
  2. Escape キーで中断（コンテキストは保持される）
  3. Escape 2回で履歴を遡り、別の方向を試す
  4. 変更を取り消させる

f. /clear でコンテキストをリセット

長いセッションでコンテキストが溜まると性能が低下します。タスク間で /clear を実行しましょう。

g. 複雑なタスクにはチェックリストを使う

大規模なマイグレーションやリント修正には：

  1. Markdown ファイルにエラーリストをチェックリストとして書き出させる
  2. 1つずつ修正 → 確認 → チェックを繰り返させる

5. ヘッドレスモードで自動化

ヘッドレスモードは、対話なしで Claude Code を実行するモードです。

claude -p "プロンプト" --output-format stream-json

用途例

a. Issue のトリアージ
新しい Issue が作成されたら自動的にラベルを付ける

b. AI リンター
従来のリンターでは検出できない問題（タイポ、古いコメント、誤解を招く変数名など）を指摘

6. 複数 Claude を活用するワークフロー

a. 1つが書き、もう1つがレビュー

  1. Claude A にコードを書かせる
  2. /clear または別ターミナルで Claude B を起動
  3. Claude B にレビューさせる
  4. Claude C がフィードバックを反映

役割分担により、単一 Claude より良い結果が得られることが多いです。

b. 複数チェックアウト

  1. リポジトリを3-4個の別フォルダにチェックアウト
  2. 各フォルダで別々の Claude を起動
  3. 異なるタスクを並行実行
  4. 順番に確認・承認

c. Git Worktrees

より軽量な並行開発方法：

# ワークツリー作成
git worktree add ../project-feature-a feature-a

# そのディレクトリで Claude を起動
cd ../project-feature-a && claude

# 完了後にクリーンアップ
git worktree remove ../project-feature-a

d. ヘッドレスモード + カスタムハーネス

ファンアウト（大規模一括処理）:

# 2000ファイルを順次マイグレーション
claude -p "foo.py を React から Vue に移行して。成功したら OK、失敗したら FAIL を返して" --allowedTools Edit Bash(git commit:*)