| name | claude-agent-sdk |
| description | Claude Agent SDK（Python / TypeScript）を使った機能実装の設計をサポートするスキル。
ヒアリング型ワークフローでユーザーの要件を明確化し、
公式ドキュメントに基づいた最適なアーキテクチャと実装パターンを提案する。
Trigger:
Agent SDK, claude_agent_sdk, claude-agent-sdk, ClaudeAgentOptions, ClaudeSDKClient,
Agent SDKで, エージェントSDK, エージェントを作りたい, agent-sdkを使って,
query(), createSdkMcpServer, サブエージェント構成, agent architecture
|
| allowed-tools | ["Read","Glob","Grep","AskUserQuestion","Task"] |
Claude Agent SDK 設計サポート
概要
Claude Agent SDK（Python / TypeScript）を使った機能実装の設計をサポートするスキル。
ヒアリング型ワークフローでユーザーの要件を明確化し、公式ドキュメントに基づいた最適なアーキテクチャと実装パターンを提案する。
設計原則
| 原則 | 説明 |
|---|
| Hearing First | まずヒアリングで要件を明確化してから設計提案 |
| Use Case Driven | 公式デモの実装パターンを基にした具体的なユースケース提案 |
| Progressive Disclosure | 必要なリファレンスのみを読み込み |
| Both Languages | Python / TypeScript 両方の実装パターンを提示 |
| Design-Oriented | コード生成ではなく設計判断を支援 |
ワークフロー
Phase 1: 要件ヒアリング
→ agents/interview-requirements.md を読み込み
→ AskUserQuestion で要件を明確化
→ references/use-cases-index.md を読み込み、近いユースケース番号を特定
↓
Phase 2: ユースケース詳細 & リファレンス参照
→ Phase 1 で特定したユースケース番号の examples/0X-*.md を読み込み
→ 組合せ設計時は examples/common-patterns.md も読み込み
→ ヒアリング結果に基づき必要な references/ を追加読み込み
↓
Phase 3: 設計提案
→ examples/ のアーキテクチャ図・コード例を土台に設計提案
Phase 1: 要件ヒアリング
- agents/interview-requirements.md を読み込み、ヒアリング項目を把握する
- references/use-cases-index.md を読み込み、ユースケースカタログを把握する
- AskUserQuestion で以下を確認する:
- 目的: 何を作りたいか（エージェントの用途）
- 機能: 必要な機能（ツール、MCP、サブエージェント等）
- 言語: Python or TypeScript
- I/O: ストリーミング / シングル / 構造化出力
- セッション: ワンショット / 継続 / フォーク
- デプロイ: ローカル / コンテナ / クラウド
- セキュリティ: 権限モード、サンドボックス
- コスト: トークン制限、最適化要件
- ヒアリング結果を use-cases-index.md の選定ガイドと照合し、該当ユースケース番号（#1〜#7）を特定してユーザーに提示する
Phase 2: ユースケース詳細 & リファレンス参照
Phase 1 で特定したユースケース番号に基づき、以下の順で読み込む:
Step 1: ユースケース詳細を読み込む（必須）
Phase 1 で特定した番号に対応するファイルを読み込む:
複数ユースケースを組み合わせる場合は、該当する複数ファイル + references/examples/common-patterns.md を読み込む。
Step 2: 基礎リファレンスを読み込む（必須）
Step 3: 追加リファレンスを読み込む（該当時のみ）
ヒアリング結果に基づき、必要なリファレンスのみを追加で読み込む:
| トピック | リファレンス | 読み込み条件 |
|---|
| サブエージェント・ツール・MCP | references/agent-architecture/index.md | カスタムツール・MCP使用時（→詳細: subagents, mcp, custom-tools, plugins-and-skills） |
| ストリーミング・構造化出力 | references/io-and-streaming/index.md | I/Oモード選択時（→詳細: streaming-output, structured-output, approval-and-input） |
| 権限・フック・設定 | references/system-configuration/index.md | 権限・フック設計時（→詳細: hooks, commands-and-todo, checkpoints） |
| デプロイ・セキュリティ | references/deployment-and-operations.md | 本番デプロイ・セキュリティ設計時 |
| API詳細 | references/sdk-reference/index.md | API仕様確認時（→詳細: python-api, typescript-api, common-options, hooks-api, tools-api） |
Phase 3: 設計提案
Phase 2 で読み込んだ examples/ のアーキテクチャ図・コード例を土台に、以下の形式で提案する:
## 設計提案
### 参考ユースケース
- ベースパターン: #X（examples/0X-*.md のタイトル）
- 追加パターン: #Y（該当する場合）
- 参照元: examples/0X-*.md のアーキテクチャ図・実装ポイント
### アーキテクチャ概要
[examples/0X-*.md のアーキテクチャ図をベースに、ユーザー要件に合わせてカスタマイズした構成図・説明]
### 推奨構成
- 言語: Python / TypeScript
- 入力モード: ストリーミング / シングル
- 権限モード: default / acceptEdits / bypassPermissions
- セッション: ワンショット / 継続 / フォーク
- デプロイ: パターン名
### 実装ステップ
1. [examples/0X-*.md の実装ポイントを参考に具体的なステップを記述]
2. ...
### コード例（Python / TypeScript）
[examples/0X-*.md のコード例をベースに、ユーザー要件に合わせて調整したコードを提示]
[複数パターン組合せ時は common-patterns.md のコード例も活用]
クイックリファレンス
Agent SDK 比較表
| 特徴 | Python | TypeScript |
|---|
| パッケージ | claude-agent-sdk | @anthropic-ai/claude-agent-sdk |
| メイン関数 | query() | query() |
| オプション型 | ClaudeAgentOptions | ClaudeAgentOptions |
| 永続セッション | ClaudeSDKClient | - |
| スキーマ検証 | Pydantic | Zod |
| V2 API | - | unstable_v2_prompt() |
権限モード早見表
| モード | ファイル操作 | Bash | 全ツール |
|---|
| default | 承認要求 | 承認要求 | 承認要求 |
| acceptEdits | 自動承認 | 承認要求 | 承認要求 |
| bypassPermissions | 自動承認 | 自動承認 | 自動承認 |
| plan | 実行不可 | 実行不可 | 実行不可 |
入力モード比較
| 機能 | ストリーミング | シングル |
|---|
| 画像アップロード | 可 | 不可 |
| メッセージキュー | 可 | 不可 |
| フック | 可 | 不可 |
| リアルタイムフィードバック | 可 | 不可 |
| シンプルさ | - | 可 |
デプロイパターン
| パターン | 説明 | 適用場面 |
|---|
| エフェメラル | リクエスト毎にコンテナ | API/Webhook |
| 長時間実行 | 永続プロセス | 常駐サービス |
| ハイブリッド | 用途に応じて切替 | 大規模システム |
| シングルコンテナ | 1コンテナ内で実行 | 開発・テスト |
ベストプラクティス
| すべきこと | 避けるべきこと |
|---|
| ストリーミング入力を使う（本番） | シングルモードを本番で使う |
| 最小権限の原則で権限モード選択 | bypassPermissionsを無条件で使う |
| フックで危険なコマンドを制御 | 権限チェックなしでBash実行 |
| セッションIDを保存して再開可能に | 毎回新規セッションを作成 |
| maxTurnsでコスト制限 | トークン使用量を監視しない |
| カスタムツールにZod/Pydanticスキーマ | 型なしのツール定義 |
