コードレビューのプロンプトを提供するMCPサーバを構築するために40時間、同僚はマークダウンファイルを落としました。 同じことをした10分対40時間、同じ出力だった。 .claude/skills/ クラウド・コードには3つの異なる拡張性メカニズムがあり、それぞれが実際に何をしているかを理解するとゼロの重複があります。 これらの3つのメカニズムの背後には、単一の構成ラインを書く前に理解する価値のある意図的な建築哲学が示されています。 デザイン決定 3つのメカニズムの背後にある建築 クロード・コードのすべての拡張は3つのカテゴリのうちの1つに該当します。それらは、システムの根本的に異なる層で動作するため、別々のメカニズムとして存在します。これは偶然ではありません。 答え: "How does Claude access systems outside its process boundary?" They are separate programs that communicate with Claude via JSON-RPC. The Model Context Protocol defines the wire format (tool calls, resource reads, prompt templates), but the server itself is just a program that speaks JSON over stdio or HTTP. Itins its own connections, its own state, its own lifecycle. Claude sends a request, the server does the work, and sends back a response. Real inter-process communication with all the implications that carries. モデルコンテキストプロトコルは、ワイヤーフォーマットを定義します。 MCP servers 答え: 「異なるタスクのための異なる行動で Claude を実行する方法」 サブエージェントは、独自のシステムプロンプト、独自のモデル選択、独自のツールアクセス、そして独自の文脈ウィンドウを持つ孤立した Claude セッションです。 Subagents 答え: "How do you inject reusable knowledge into a conversation?" A skill is a markdown file that becomes a slash command. When invoked, its contents are injected directly into the current conversation as instructions. No new process. No isolation. No separate context. Just text that shapes Claude's behavior within the existing session. スキルはスラッシュコマンドになります。 Skills MCPサーバーが実際にハッドの下で働く方法 モデルコンテキスト プロトコルは JSON-RPC 2.0 プロトコルです. Claude Code が起動すると、それぞれの構成された MCP サーバを子プロセスとして起動し、スタジオ経由で双方向通信チャネルを確立します. The server advertises its capabilities (which tools it provides, what resources it exposes) and Claude incorporates these into its available toolkit. Claude が MCP ツールを使用することを決定したとき、順序は次のとおりです。 Claude は、名前と JSON アルゴリズムでツール呼び出しを生成します。 Claude Code はこれを JSON-RPC リクエストとして適切なサーバープロセスに送信します。 サーバーがリクエストを実行する(データベースをクエリし、APIを呼び出し、ファイルシステムを読み取る) サーバーは JSON-RPC 応答として結果を返します。 クロード・コードは答えをクロードの文脈に戻す。 これは真のプロセス間のコミュニケーションです サーバーはどの言語でも書くことができます データベースへの継続的な接続、キャッシュ結果、速度制限を実装し、アクセスコントロールを強制することができます 実際の状態を持つプログラムです。 { "mcpServers": { "analytics": { "command": "node", "args": ["./mcp-servers/analytics.js"], "env": { "DATABASE_URL": "postgresql://localhost/analytics", "MAX_ROWS": "1000", "QUERY_TIMEOUT_MS": "5000" } }, "deploy": { "command": "./mcp-servers/deploy-server", "args": ["--environment", "staging", "--read-only"], "env": { "API_TOKEN": "${DEPLOY_TOKEN}" } } } } THE そして 上記の環境変数はMCPプロトコル機能ではありません。これらはアプリケーションレベルのセキュリティ限界であり、アナリティクスサーバが内部で強制するものです。これは重要な建築的なポイントです:MCPプロトコルは通信を処理しますが、サーバーはポリシーを処理します。 MAX_ROWS QUERY_TIMEOUT_MS サーバーが何千ものリクエストを処理したり、接続プールを維持したりするパフォーマンスに重要な統合では、Rustは投資に値します。 プロトコル処理から生産展開までの全プロセスをカバーし、接続バンドリングと優雅なシャットダウンを含む。 RustでMCPサーバーを構築するためのガイド Remote MCP servers over HTTP with SSE follow the same protocol but replace stdio with HTTP transport. This matters for shared team infrastructure where a single MCP server instance serves multiple developers, but it adds network latency and requires authentication. For most teams, local stdio servers are simpler and faster. Remote MCP servers over HTTP with SSE follow the same protocol but replace stdio with HTTP transport. This matters for shared team infrastructure where a single MCP server instance serves multiple developers, but it adds network latency and requires authentication. For most teams, local stdio servers are simpler and faster. サブエージェントが帽子の下で働く方法 サブエージェントは別々のテクノロジーではありません。彼らは制限されたパラメータを持つ Claude Code セッションです。あなたがサブエージェントを呼び出したとき、Claude Code はエージェントの構成に指定されたモデルと新しい会話を開始します。 システムプロンプトは、エージェントファイルのマークダウンの体から来ています。 ツールリストは、エージェントの構成が許可するものだけにフィルタリングされます。 そして、重要なことに、コンテキストウィンドウは、システムプロンプトとあなたがサブエージェントに与えたタスクを除いて空です。 この孤立はコストと品質の両方に深い影響を及ぼします。あなたが20分間コードベースを探索してきたデバッグセッションを考慮してください。あなたのメインコンテキストウィンドウには、数十のファイルリーディング、グリップ結果、ステックトラック、および会話の回転が含まれています。あなたが今、同じセッションでコードレビューを要求する場合、レビューはすべてのデバッグ騒音の文脈で起こります。 サブエージェントはクリアを開始します。その文脈には、システムプロンプト(あなたのレビュー基準)と、あなたがレビューするように要求したファイルのみが含まれています。 ノイズはありません。 累積状態はありません。 メインセッションのレビューよりも、モデルはタスクに完全に焦点を当てているからです。 よりよい --- name: code-reviewer description: Reviews code for quality, security, and style model: haiku tools: Read, Grep, Glob, Bash disallowedTools: Write, Edit mcpServers: - github maxTurns: 15 --- You are a code review specialist. You have read-only access to the codebase and the GitHub API. Review criteria: - No unwrap() in production code paths (use proper error handling) - All public functions have doc comments - Error types implement std::fmt::Display - No println! in library code (use tracing macros) - Integration tests exist for new API endpoints - No TODO without a linked issue number For each file, provide a pass/fail checklist and specific line references for any failures. Do not provide general advice — only specific findings. THE スタイルチェックや条約執行などのパターン一致の作業では、HaikuはOpusと比較して機能します。 model: haiku THE ディレクティブはハード レイヤーを作成します。 システム プロンプトが「見つけた問題を修正する」と言っても、サブエージェントはファイルを変更できません。 これは、プロンプト レイヤーではなく、ツール アクセス レイヤーで実行されます。 disallowedTools: Write, Edit THE これがなければ、大規模なコードベースを分析するサブエージェントは50回繰り返し、コストを蓄積する可能性があります。 maxTurns: 15 モデルルーティングの実際のコスト数学 これは、サブエージェントが自分自身のために支払い、それからいくつかの場所です。 クラウド・コードを通じて1日あたり約10回のコードレビューを実行する5人の開発者のチームを考えてみましょう。サブエージェントなしでは、それぞれのレビューはメインのオプスセッションで実行されます。他の仕事からの文脈の蓄積により、典型的なレビューは15,000～25,000の入力トークンを消費し、2000～4000の出力トークンを生成する可能性があります。 Haiku サブエージェントでは、同じレビューがクリーンなコンテキストウィンドウで実行されます. 入力トークンは 3,000-8,000 にまで下がります (システムプロンプトとコードがレビューされ、コンテキストが蓄積されていません)。 そして Haiku のトークンあたりのコストは Opus より劇的に低いです. より小さなコンテキストとより安価なモデルの組み合わせ効果は、通常、コードレビューコストを 85-95% 削減します。 しかし、より微妙なコストの利点があります。サブエージェントのコンテキストウィンドウが隔離され、クリーンであるため、レビューはより速くなります。より少ない入力コンテキストは処理時間を減らすことを意味します。 Haikuのサブエージェントレビューは通常2〜5秒で戻ります。膨らんだOpusセッションで同じレビューは10〜20秒かかります。50日以上のレビューは有意義な時間の節約です。 モデルルーティングの決定は必ずしも明らかではないが、いくつかのタスクにはオプスレベルの推論が必要である。 モデルが複雑な状態を多くのファイルで保持する必要がある深いデバッグセッション。 モデルがシステム全体の影響について推論する必要があるアーキテクチャ分析。 モデルが微妙なセマンティックな関係を理解する必要があるリファクタリングタスク。 これらはオプスに留まるべきだが、文脈がきれいであるように孤立したサブエージェントに留まるべきである。 より広範なコスト戦略として、私たちの コンテキスト管理やトークン意識の促進などの他のアプローチとともにモデルルーティングをカバーします。 Claude Codeコスト最適化ガイド スキルは Prompt Layer でどのように機能するか Skills are architecturally the simplest mechanism, and that simplicity is a feature. スキルは建築的に最も単純なメカニズムであり、そのシンプルさは機能である。 ディレクトリ名は、slash コマンドになります。 クロード・コード・レイズ Claude Code Raeds そして、その内容を現在の会話に注入します。 .claude/skills/ /review .claude/skills/review/SKILL.md プロセスはありません. 孤立はありません. 別々の文脈ウィンドウはありません. スキルのテキストは、あなたがそれを自分で入力したかのようにあなたの既存の会話に接続します. これは、スキルが会話の既存の文脈から恩恵を受けることを意味します (Claude はすでにあなたが何のファイルで作業しているかを知っています) しかし、彼らはまた会話の蓄積された騒音を相続します。 # SQL Migration Standards Review the migration files for compliance with team standards. ## Naming Conventions - Tables: plural snake_case (user_sessions, not UserSession or user_session) - Columns: singular snake_case (created_at, not CreatedAt) - Indexes: idx_{table}_{columns} (idx_user_sessions_user_id) - Foreign keys: fk_{table}_{referenced_table} (fk_orders_users) ## Safety Requirements - All CREATE INDEX must use CONCURRENTLY - ALTER TABLE ADD COLUMN must include a DEFAULT for non-nullable columns - No DROP COLUMN without a preceding release that stops reading the column - All migrations must be reversible (provide both up and down) ## Query Patterns - Use EXISTS instead of IN for subqueries - Use COALESCE instead of CASE WHEN ... IS NULL - Avoid SELECT * in application code - Always specify column lists in INSERT statements Current schema for reference: $(cat db/schema.sql) Migration to review: $ARGUMENTS THE syntax は、呼び出し時点でシェルコマンドを実行し、出力を注入します。これにより、スキルが限られたダイナミック機能を提供します。 ファイルコンテンツ、環境変数、またはコマンド出力を含むことができますが、接続を維持したり、複数のステップの外部操作を実行したりすることはできません。 シェルコマンドは一度実行され、出力がキャプチャされ、静的テキストがプロンプトの一部になります。 $(cat db/schema.sql) THE 変数は、slash コマンドの後にすべてをキャプチャします。 設定する ファイルパスに、特定のファイルにスキルをリダイレクトできます。 $ARGUMENTS /migration db/migrations/20260311_add_sessions.sql $ARGUMENTS スキルは単純だからこそ強力です. 誰でも書くことができます. 開発者以外のチームでは、専門知識をコードする必要があります。 QAエンジニア、製品マネージャー、テクニカルライターがコードに触れずに効果的なスキルを作成する方法をカバーしています。 非技術チームのためのスキル 各メカニズムを使用しないとき(反パターン) それぞれのメカニズムが何をうまくやっているかを理解することは、画面の半分にすぎない。 MCPサーバーのパターン対策 呼び出しの間で情報が変わらず、外部システムから来ていない場合、それはスキルです. 私はチームが企業のコード基準、API文書、スタイルガイドさえ返すMCPサーバーを構築するのを見ました. All that is static text. A markdown file does it better, faster, and with zero maintenance. Do not build an MCP server to serve static content. Claude Code はすでに Bash ツールを持っています。あなたの「統合」が CLI コマンドを実行し、出力を解析している場合は、MCP サーバを必要としません。Claude が特定のコマンドで Bash を使用するように指示するスキルは簡単です。すべての外部が MCP サーバを必要としているわけではありません。Claude が Bash 経由で CLI コマンドを実行できる場合は、MCP サーバを構築し、維持するよりも簡単です。CLI (Bash ツール経由)は、ローカルで単一エージェントのワークフローに最適です。 Do not build an MCP server when a Bash tool call would suffice. MCP サーバーは、リモート実行、許可範囲化、継続的な接続、または状態の高い操作が必要な場合に必要です。 あるいは Run MCP サーバーは、複数のエージェントまたはユーザーが共有アクセスを必要とする場合、精密な許可コントロールが必要な場合、または統合が複数のリクエストで状態を維持することを必要とする場合、その複雑さを獲得します。 git log cargo test 生産に対して任意の SQL を実行する MCP サーバーは、ロードされた武器です. 各サーバーは、クエリのタイムアウト、行制限、適切な場合の読み込みのみアクセス、入力検証を適用する必要があります. プロトコルはあなたを保護しません. サーバーのコードは必須です. Do not build an MCP server without safety boundaries. アンチパターン Subagent Anti-Patterns サブエージェントは、繰り返し、専門的な作業のために輝きます。あなたが一度何かをしなければならない場合は、単にメインセッションでそれを行うだけです。エージェント構成ファイルの作成と維持の主な役割は、アドホックワークのための価値はありません。 Do not create a subagent for a one-off task. いくつかのタスクは本当により強力な推論を必要とします。私は一度、Haikuで建築分析を実行してみました。それは表面レベルの問題を特定しましたが、Opusがすぐに捕らえた循環的な依存性を逃しました。Haikuはパターン一致とチェックリストの執行に素晴らしいです。それは多くのファイルで複数のステップの推論を必要とするタスクと闘っています。 Do not route everything to Haiku to save money. 他のサブエージェントを呼び出すサブエージェントは、反パターンである。それぞれのレイヤーは遅延を加え、実際の作業を覆い隠す。それほどのオーケストラが必要な場合は、アプローチを再構築してください。通常、答えは、サブエージェントの連鎖ではなく、複数のMCPサーバーやスキルにアクセスできる1つのサブエージェントです。 Do not create deeply nested subagent chains. 反パターンスキル 「生産エラーレートをチェック」はスキル指示として、クロードがメトリックを幻想化するように導きます. タスクにクロードのセッションの外部からのデータが必要な場合は、MCPサーバ(またはMCPアクセスを有するサブエージェント)が必要です。 Do not write skills that require external data. スキルのコンテンツはコンテキストウィンドウに注入されます。5000単語のスキルはすべての呼び出しにトークンを消費します。スキルを集中させます。 スキルに直接埋め込むのではなく、条件的に注入する。 Do not write skills that are too long. $(cat reference.md) A skill runs in the current context. If the current context is polluted with unrelated work, the skill's effectiveness drops. Task that need a clean slate (reviews, analysis, documentation generation) are better served by subagents that start with a fresh context window. スキルが現在の文脈に汚染されると、スキルの効率が低下します。 Do not use skills for tasks that need isolation. 生産における組成モデル この3つのメカニズムは代替ではありません。それらは構成する層です。構成パターンを理解することは、作業セットアップをエレガントから区別するものです。 サブエージェントには、MCP サーバーが割り当てられます。これにより、範囲化されたアクセスを生成します。 コードレビューのサブエージェントは、GitHub MCP サーバーを通じて GitHub の API にアクセスできますが、データベースや展開パイプラインに触れることはできません。 サブエージェントはスキルをプレロードできます. The database-analyst subagent loads the sql-standards skill, so every analysis follows your team's naming conventions and query patterns without the analyst subagent needing those conventions in its system prompt. データベース・アナリスト・サブエージェントは、sql-基準のスキルをロードします。 サブエージェントには、その MCP アクセスに関係なくツール制限があります。サブエージェントには、GitHub MCP サーバへのアクセスを提供できます(PR やコメントを読み取ることができます)と、Write と Edit を無効にします(ローカルファイルを変更することはできません)。 私たちの8つの市場プラグインの生産設定では、層がこのように見えます: Layer 3: Skills (Team Knowledge) /review — code review checklist /migration — database migration standards /deploy-check — pre-deployment verification steps /sql-standards — SQL naming and query conventions /api-design — REST endpoint design patterns Layer 2: Subagents (Specialised Behaviour) code-reviewer (Haiku, read-only, GitHub MCP, review skill) debugger (Opus, full access, all MCP servers) database-analyst (Sonnet, read-only, PostgreSQL MCP, sql-standards skill) deploy-checker (Sonnet, read-only, deploy + analytics MCP, deploy-check skill) doc-writer (Haiku, read-only, no MCP, style-guide skill) Layer 1: MCP Servers (External Connections) analytics-db — PostgreSQL metrics database deploy-pipeline — deployment API wrapper github — GitHub API for PRs and issues content-api — CMS for documentation publishing postgresql — application database (read-only) それぞれのサブエージェントは、そのタスクの複雑さに対応するモデルレベルで、必要なMCPサーバーとスキルを正確に構成します。デプロイ・チェッカーは、複数のデータソース間でデプロイの準備を検討する必要があるため、Sonnetを使用します。Doc-writerは、技術的な書き込みが主にスタイルガイドに対応するパターンであるため、Haikuを使用します。 これらの層がどのように一緒に働くかについての詳細については、私たちのガイド 完全な構成モデルを通過し、特にサブエージェント構成の場合、私たちの すべてのフロントマテリアフィールドを例でカバーします。 プラグイン、MCPサーバー、および層構造としてのスキル クロード・エージェント・ビルディングガイド 決定機能 生産プラグインを構築して1年が経過した後、決定はあなたが必要とするものの純粋な機能です。 def choose_mechanism(need): if need.requires_external_data or need.has_side_effects: return "MCP Server" if need.requires_different_model or need.requires_tool_restrictions or need.benefits_from_isolation: return "Subagent" if need.is_reusable_knowledge or need.is_workflow_template: return "Skill" if need.is_complex: return "Subagent + MCP Server + Skill" # compose all three あなたが静的なテキストを返すMCPサーバを構築しているのなら、止めましょう。それはスキルです。あなたが「データベースをクエリする」というスキルを書いているなら、止めましょう。 それはMCPサーバです。 あなたが通常のチェックのために高価なOpusセッションを実行しているなら、止めましょう。 それはHaiku上のサブエージェントです。 何が私たちに変わったか 三角形を理解する前に、MCPサーバーはスキルの仕事をし、MCPサーバーの仕事を試みるスキルがあり、サブエージェントは全くありませんでした。 再構築後: 34 以上のスキルが、コードレビュー、データベース作業、デプロイ、ドキュメント、および API 設計を通じてチームの慣行をコード化します。5 人のサブエージェントは、適切なアクセス制御を用いて、適切な価格のポイントで専門的なタスクを処理します。 毎月のコストは大幅に減少した。レビューの品質は、サブエージェントがクリーンな文脈から始まるので改善された。チームの規約は、スキルがすべての開発者に同様に適用されるため一貫したものとなった。 拡張性の三角形は理論的な枠組みではありません。それは間違ったものを構築するのを防ぐ実用的なツールです。これについて知る価値があります。
