[JA] テクニカルガイド: Claude Code のコンセプト

目次

はじめに

Claude Code — プロンプト、スキル、サブエージェント、エージェント、およびエージェントチーム Anthropic公式ドキュメントに基づくテクニカルガイド

情報源：Claude Code Features · Agent Skills · Subagents · Agent Teams

Claude Codeにおける5つの異なる概念

これは複雑さの直線的な階層ではありません。これらはそれぞれ異なる目的を持つツールであり、組み合わせることができます。

Prompt / Skill / Subagent / Agent (session) / Agent Teams

• プロンプト (Prompt): エージェントへの指示、コンテキスト、またはツールを含むメッセージ。あらゆるインタラクションの基本単位です。
• スキル (Skill): 再利用可能な知識をカプセル化した SKILL.md ファイルを含むディレクトリ。Claudeはこれを自動的に、または /slash-command を介してロードします。
• サブエージェント (Subagent): メインエージェントによって Agent ツールを介して呼び出される、独自のコンテキスト、システムプロンプト、ツール、権限を持つClaudeインスタンス。
• エージェントセッション (Agent session): インタラクティブモードまたはヘッドレスモードのClaude Code。ツールにアクセスでき、CLAUDE.md を読み取り、サブエージェントに委任することができます。これがメインセッションです。
• エージェントチーム (Agent Teams): 調整された複数のClaude Codeセッション。チームリーダーと複数のチームメンバーからなり、それぞれが独自のコンテキストを持ちます。明示的なアクティベーションが必要です。

プロンプト — エージェントへの指示

“プロンプトは単なる簡単な質問ではありません。ツールがあるかないかにかかわらず、また単純か複雑かにかかわらず、あなたがClaudeに与えるあらゆる指示です。”

プロンプトは、Claude Codeがあらゆるインタラクションで受け取る入力です。インタラクティブな会話を開始したり、ヘッドレスなタスクを実行したり（claude -p "..."）、システムプロンプト、プロジェクトコンテキスト、アクティブなツールを備えた複雑なエージェントシステムの基盤として機能したりします。

公式ドキュメントによると： Agent SDKはデフォルトで最小限のシステムプロンプトを使用します。すべてのツールと動作を備えた完全なClaude Codeのシステムプロンプトを含めるには、systemPrompt: { type: "preset", preset: "claude_code" } を指定します。CLAUDE.md ファイルは追加のプロジェクトコンテキストとしてロードされます。

プロンプトに焦点を当てるべき場合：

• 制限されたタスクまたは直接的な会話
• -p を使用したヘッドレススクリプティング
• SDKのシステムプロンプト構成
• エージェントフローの入り口

例：

• claude -p "src/auth.tsのauthenticate関数をリファクタリングして" — ヘッドレスなクイックタスク
• すべてのツールにアクセスできるClaude Codeとのインタラクティブな会話
• カスタムシステムプロンプトと構成されたツールを持つSDKエージェントへの入力
• すべてのプロジェクトプロンプトに注入される永続的なコンテキストとして機能する CLAUDE.md

スキル — 専門的で再利用可能な機能

“スキルとは、タスクが関連する際にClaudeが自動的に参照する、またはあなたがスラッシュコマンドで呼び出す専門的なプレーブックのようなものです。”

以前のガイドからの訂正： スキルは CLAUDE.md 内には存在しません。これらは .claude/skills/skill-name/（プロジェクト）または ~/.claude/skills/skill-name/（ユーザー）にある、SKILL.md ファイルを含むディレクトリです。

公式ドキュメントによると、スキルは不必要にコンテキストを消費しないように段階的にロードされる3種類のコンテンツを含むディレクトリです：

1. レベル1 — メタデータ（常にロードされる）: YAMLフロントマター：name と description。わずか約100トークン。Claudeはその存在といつ使用すべきかを知っています。
2. レベル2 — 指示（アクティブ化されたとき）: SKILL.md の本体：ワークフロー、ベストプラクティス。スキルがアクティブ化されたときにbash経由でロードされます。5kトークン未満。
3. レベル3 — リソースとコード（オンデマンド）: 実行可能なスクリプト、テンプレート、ドキュメント。Claudeは必要な場合にのみこれらを読み取ります。実用的なサイズ制限はありません。

スラッシュコマンドとの違い： 組み込みのスラッシュコマンド（/clear、/compact）には固定のロジックがあります。スキルは以前は「コマンド」（.claude/commands/）と呼ばれていたファイルが .claude/skills/ に進化したもので、追加機能（フロントマターの制御、添付されたスクリプト、!`command` による動的なコンテキスト注入）を備えています。

いつ使用すべきか：

• 会話間で再利用可能なドメイン知識
• チームの規則（コードスタイル、PRのパターン）
• Claudeが自動的に開始すべきワークフロー
• 指示付きのスクリプトのバンドル
• Claude.aiおよびAPIで利用可能

サブエージェント — 独自のコンテキストを持つ専門のミニアシスタント

“サブエージェントは、メインエージェントによって特定のタスクのために召喚される専門家です。独自のコンテキストで独立して機能し、結果のみを返します。”

サブエージェントは、独自のシステムプロンプト、構成されたツール、権限、およびコンテキストウィンドウを持つClaudeインスタンスです。メインエージェントは Agent ツール（以前の Task）を介してそれらを呼び出します。.claude/agents/ または ~/.claude/agents/ にYAMLフロントマターを持つMarkdownファイルとして定義されます。

公式ドキュメントによる重要なポイント： サブエージェントは会話のコンテキストを継承しません — 親エージェントが呼び出しのプロンプトに明示的に含めたもののみを受け取ります。サブエージェントが他のサブエージェントを呼び出すことはできません。 ネストされた委任が必要な場合は、スキルを使用するか、メインの会話からサブエージェントをチェーンしてください。

メインの会話ではなくサブエージェントを使用すべき場合：

• タスクがメインコンテキストに入れたくない冗長な出力を生成する場合
• 特定のツールを制限したい場合（読み取り専用のサブエージェント）
• 作業が自己完結しており、要約を返すことができる場合
• 独立した並行操作

レイテンシー： サブエージェントは空のコンテキストで開始され、必要なコンテキストを収集するのに時間がかかる場合があります。すでに会話内にあるものに関する素早い質問には、代わりに /btw を使用してください。

エージェント（セッション） — メインの Claude Code セッション

“Claude Codeセッションは完全なエージェントです。推論し、行動し、結果を観察し、目標が完了するまで繰り返します。”

Claude Codeをインタラクティブに、または claude --agent name で起動すると、ツールへのフルアクセス、自律的な推論ループ、サブエージェントに委任する機能を備えたエージェントが開始されます。ここでは、複雑な外部の自律エージェント（openclawなど）ではなく、.claude/agents/ で構成されメインセッションとして機能するClaudeエージェントを明示的に指します。

公式ドキュメントによると： claude --agent subagent-name を使用すると、メインセッションは /agents からそのファイルのシステムプロンプト、ツール、およびモデルを採用します。CLAUDE.md を使用すると、プロジェクトコンテキストが注入されます。エージェンティックループにはネイティブツール（Bash、Read、Write、Edit、WebSearch）が含まれており、サブエージェントに委任できます。
追加のメモ: ランタイムセッションとSDKの両方が**Hooks（フック）**を完全にサポートしており、.claude/settings.json で構成して主要なアクションを傍受できます（破壊的なBashコマンドを条件付きで追跡またはブロックするなど）。

これが適切なアプローチである場合：

• 連鎖的な決定を伴う複雑な複数ステップの目標
• 反復：エラー -> 分析 -> 修正 -> 検証
• ファイルシステムとターミナルへのフルアクセス
• やり取りや反復的な洗練が必要なタスク
• コンテキストを共有する複数のフェーズ（計画 -> 実装 -> テスト）

エージェントチーム — 直接コミュニケーションを伴う調整されたセッション

“Claude Codeチーム：チームリーダーが調整し、チームメンバーが並行して作業し、互いに直接話すことができ、それぞれが独自のコンテキストを持ちます。”

公式ドキュメントによると： エージェントチームは実験的であり、デフォルトでは無効になっています。設定または環境変数で CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 が必要です。Claude Code v2.1.32以降が必要です。

サブエージェントとの決定的な違い：チームメンバーは互いに（リーダーを介さずに）直接通信する完全に独立したセッションです。彼らはタスクリストとメールボックスシステムを共有します。ユーザーも任意のチームメンバーと直接話すことができます。

最適な使用例（公式ドキュメントによる）：

• 調査とレビュー：複数の視点を並行して
• 各チームメンバーが自分の領域を「所有」する新しいモジュールや機能
• 競合する仮説を並行して検証するデバッグ
• フロントエンド＋バックエンド＋テストにまたがる変更を同時に行う場合

重要 — エージェントチームを使用すべきではない場合： 順次的なタスク、同じファイルへの編集、高度に依存した作業。これらの場合、サブエージェントまたは単一セッションの方が効率的です。コストはチームメンバーごとに比例して増加します。

比較表

デシジョンツリー

スキルとサブエージェントのどちらを使うべきか？ 公式ドキュメントにはこうあります：メインコンテキストでの再利用可能なプロンプト/ワークフローにはスキルを使用し、コンテキストの分離と制限されたツールにはサブエージェントを使用します。

1. Claudeがプロジェクトを越えて自動的にロードすべき再利用可能な知識ですか？
   • はい -> ~/.claude/skills/ 内のスキル
2. このチームが共有すべき特定のワークフローまたは規則ですか？
   • はい -> .claude/skills/ 内のスキル
3. タスクがメインコンテキストに入れたくない冗長な出力を生成するか、制限されたツールが必要ですか？
   • はい -> サブエージェント
4. 反復、複数のステップ、システムへのフルアクセスが必要ですか？
   • はい -> エージェント（セッション）
5. ワーカーが上司に報告するだけでなく、直接通信する必要がありますか？
   • はい -> エージェントチーム（並行性が真の価値を追加する場合）

ゴールデンルール

• スキル vs サブエージェント: メインコンテキストでのワークフローにはスキルを使用し、コンテキストの分離にはサブエージェントを使用します。
• サブエージェント vs エージェントチーム: 報告を返す集中型のワーカーにはサブエージェントを使用します。複雑なコラボレーションにはエージェントチームを使用します。
• シンプルに始める: 素早い質問には、サブエージェントの代わりに /btw を使用します。
• エージェントチーム: 3〜5人のチームメンバーがスイートスポットです。

推奨コース (Anthropic Academy)

これらの高度なエージェンティックツールを完全に習得するために、Anthropicの公式アカデミーでは、anthropic.skilljar.com にて、これらの概念にマッピングされた以下の専門的なリソースを提供しています。

• Claude Code 101: 基本的な探索的エージェントループ（探索 -> 計画 -> コード作成 -> コミット）、デフォルトのターミナルワークフロー、および CLAUDE.md によるオーケストレーションを理解します。
• Agent Skills入門: 効果的な「スキル」を構築、構成、共有する方法に関する実践的なトレーニング。コード/Markdownの指示をカプセル化して、コードスタイルとアーキテクチャの規則を適用する方法を学びます。
• Subagents入門: 完全に隔離されたエージェントにタスクを委任する正確なタイミングと方法を学びます。これにより、メインセッションでのコンテキストの肥大化を防ぎ、並行推論の出力を改善します。