Claude Code Best PracticesとAgent SDKの公式ガイドまとめ

Anthropicが公開した2つの公式ドキュメントをまとめた:

前者はClaude Codeの実践的な使い方、後者はClaude Agent SDKでエージェントを構築する方法について書かれている。

Claude Code Best Practices

Claude Codeは低レベルで柔軟な設計になっており、特定のワークフローを強制しない。その分、使いこなすには学習が必要。このドキュメントではAnthropicの社内チームや外部エンジニアの知見をもとにしたベストプラクティスがまとめられている。

CLAUDE.mdでコンテキストを与える

プロジェクトルートにCLAUDE.mdを配置すると、Claudeが自動的に読み込む。記載すべき内容:

よく使うbashコマンド（ビルド、テスト、リントなど）
コアファイルやユーティリティ関数の場所
コードスタイルガイドライン
リポジトリ固有のルールやワークフロー

配置場所は複数選べる:

場所	用途
プロジェクトルート	基本（推奨）
親ディレクトリ	モノレポ対応
子ディレクトリ	サブプロジェクト固有の設定
ホームフォルダ	全セッション共通の設定

Anthropic社内では「IMPORTANT」「YOU MUST」といった強調表現を使って指示への従順性を高めている。

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

.claude/commands/フォルダにMarkdownファイルを配置すると、スラッシュコマンドとして使える。

.claude/commands/fix-github-issue.md

これで/project:fix-github-issue 1234のように呼び出せる。$ARGUMENTSプレースホルダでパラメータを受け取れる。チームで共有できるのでリポジトリにコミット推奨。

MCPでツールを拡張

Claude CodeはMCP（Model Context Protocol）に対応している。.mcp.jsonをリポジトリに含めれば、チーム全員が同じツールを使える。

{
  "mcpServers": {
    "puppeteer": {
      "command": "npx",
      "args": ["-y", "@anthropic-ai/mcp-puppeteer"]
    }
  }
}

トラブルシューティングには--mcp-debugフラグが便利。

推奨ワークフロー

探索→計画→実装→コミット

段階的に進めることで精度が上がる:

探索: 関連ファイルを読む（コード作成禁止と指示）
計画: 「think」「think hard」で拡張思考を有効化して計画を立てる
実装: ソリューションを実装して検証
コミット: 変更をコミット

複雑な問題ほど計画フェーズが重要。初期段階で計画をスキップするのがよくある失敗パターン。

テスト駆動開発（TDD）

検証可能な変更に最適:

入出力仕様に基づいてテストを作成（実装なし）
テスト実行で失敗を確認
テストをコミット
テストが通るまで実装と修正を繰り返す

ビジュアル反復

UIやデザイン実装に効果的:

Puppeteer MCPやスクリーンショットを活用
デザインモックを参照させる
コード実装→スクリーンショット確認→修正を繰り返す

2〜3回の反復で大幅に改善する。

プロンプトのコツ

具体的な指示ほど成功率が上がる:

# 弱い指示
foo.pyのテストを追加して

# 強い指示
foo.pyのテストを作成して。ログアウト状態のエッジケースに対応すること。モックは使わない。

画像も活用できる。macOSならCmd+Ctrl+Shift+4でスクリーンショットをクリップボードにコピーしてCtrl+Vで貼り付け。

コンテキスト管理

長時間セッションでは/clearで不要な会話履歴を削除。大規模タスクではMarkdownチェックリストで進行状況を追跡させると効果的。

ヘッドレスモード

-pフラグで対話なしで実行できる。CI/CD統合に便利。

claude -p "このコードをレビューして" --output-format stream-json

GitHub Actionsと組み合わせてイシューの自動分類やコードレビューに使える。

マルチインスタンス

複数のClaude Codeインスタンスを並列で動かせる。Git worktreeと組み合わせると効率的:

git worktree add ../project-feature-a feature-a
cd ../project-feature-a && claude

Claude Agent SDK

Claude Code SDKは「Claude Agent SDK」に改名された。コーディング以外の用途（調査、動画作成、メモ取りなど）にも広く使われるようになったため。

設計思想

「Claudeには毎日プログラマーが使うツールと同じものが必要」という考え方。ファイル検索、編集、実行、デバッグなど、プログラマーと同様のアクセス権をエージェントに与える。

エージェントループの構造

エージェントは以下のサイクルを繰り返す:

コンテキスト収集: 必要な情報を集める
アクション実行: ツールを使って作業
成果検証: 結果を確認
繰り返し: 必要に応じて1に戻る

コンテキスト収集の方法

方法	説明
ファイルシステム検索	`grep`や`tail`などでファイルから情報抽出
セマンティック検索	埋め込みベクトル技術（精度は低め）
サブエージェント	並列実行でコンテキストウィンドウを隔離
コンパクション	長時間実行時の会話履歴自動圧縮

アクション実行の手段

ツール定義: APIアクセスやデータベース操作
Bash/スクリプト: ファイル操作、PDF変換など
コード生成: PythonでExcel/PowerPoint/Word文書を自動生成
MCP統合: Slack、GitHub、Google Drive、Asanaなどとの連携

検証の仕組み

ルール定義: メールアドレス検証やリントチェック
ビジュアルフィードバック: HTMLメール生成時のスクリーンショット確認
LLM評価: 別モデルによる出力品質判定

活用例

ファイナンスエージェント: ポートフォリオ分析と投資評価
パーソナルアシスタント: スケジュール管理と旅行予約
カスタマーサポート: 複雑な問い合わせ処理
調査エージェント: 大量ドキュメントの分析

2つのドキュメントの違い

項目	Best Practices	Agent SDK
対象	Claude Codeユーザー	エージェント開発者
内容	使い方のコツ、ワークフロー	アーキテクチャ、設計原則
目的	日常のコーディング効率化	カスタムエージェント構築

Best Practicesは「Claude Codeをどう使うか」、Agent SDKは「Claude Codeの仕組みでエージェントをどう作るか」という位置づけ。