dig

Dig

Apify MCP サーバーでの作業を調査、計画、仕様策定するための柔軟なスキルです。ソースファイルは編集しないでください — このスキルは理解と計画のみを目的としています。

Step 0: 引数を解析し、意図を判断する

$ARGUMENTS には、ユーザーのリクエストと、任意のリポジトリパスの上書きが含まれます。

フラグ（任意）：

フラグ	デフォルト	用途
--sdk	../typescript-sdk	MCP SDK のソースリポジトリパス
--ext-apps	../ext-apps	MCP Apps SDK のソースリポジトリパス
--internal	../apify-mcp-server-internal	内部サーバーのリポジトリパス

フラグに一致しないものはすべて、ユーザーのリクエストです。

ソースリポジトリの解決順序：フラグのパス → デフォルトの兄弟パス → node_modules/（コンパイル済み型のみ） → GitHub URL（最後の手段）。使用する前に、必ずパスが存在することを確認してください。

意図を判断する

ユーザーの自然言語から意図を推測してください。モードは3つあります。

意図	実施内容	例
調査	コードを読み、調査結果を説明し、質問に回答する	「ツールの命名方法は」「ウィジェットのコードを見て」「なぜ動かないのか」「X を変更したら何が壊れるか」
計画	計画モードに入り、アプローチを設計し、影響を評価する	「リソースリンクの実装を計画して」「メタデータのリファクタリング方法を検討して」「簡素化の方法を設計して」
仕様策定	計画を立て、GitHub イシューを作成する	「X のイシューを書いて」「Y の仕様を作成して」「リソースリンクの仕様を策定して」

ルール：

• デフォルトは調査です。判断に迷う場合は、対応を控えめにしてください。ユーザーはいつでも追加で依頼できます。
• 計画と仕様策定の場合のみ、計画モードに入ってください。
• 仕様策定の場合のみ、GitHub イシューを作成してください。

Step 1: 調査

関連するソースファイルを読み、調査結果を説明してください。これは、すべての意図に共通する基本ステップです。

実施内容：

1. このリポジトリ内の関連ソースファイルを読む
2. 参考として、類似する既存機能を確認する
3. ユーザーの質問に関係する場合に限り、内部リポジトリ、MCP SDK／仕様、または MCP Apps SDK／仕様を確認する
4. 関連するオープンイシューに気づいた場合は、さりげなく言及してください。ただし、関連性がない限り、イシューを探し回らないでください

意図が「調査」の場合は、ここで終了してください。

ステップ 2：計画（Plan のみ、Spec は含めない）

EnterPlanMode ツールを使用してから、アプローチを設計し、1 つに決めてください。依頼内容が本当に曖昧な場合（例：既存の 2 つの設定項目に該当する場合）は、最初に選択肢を示して質問してください。それ以外の場合は、最も妥当な設計を選び、選択肢を列挙するのではなく、その設計に決めてください。

最初に調査してください：

1. リポジトリ内部への影響を評価します（利用可能であれば ../apify-mcp-server-internal を確認します）
2. 機能がプロトコルの動作に関わる場合は、MCP の仕様／SDK を確認します
3. ウィジェットやインタラクティブ UI に関わる場合は、MCP Apps の仕様／SDK を確認します
4. 役立つ場合は mcpc @stdio tools-call を使って現在の動作を調べます（pnpm run build が必要です）
5. リポジトリの規約ドキュメントを読み、それに従ってください。独自に作り直さないでください

規約はこの文書ではなく、リポジトリ内にあります。 命名、検証、テストの配置、公／内部の分離に関するルールは AGENTS.md、CONTRIBUTING.md、DEVELOPMENT.md に記載されています。これらを読んでください。設計は最小限にし、追加する前に再利用や調整を検討してください。

設計の出力 — 必須セクション。 他の人が実装できる計画にするため、次の内容を記述してください。

1. アプローチ — 選んだ設計と、受け入れた主なトレードオフを数文で説明します。
2. 変更するファイル — 作成または変更する各ファイルについて、変更内容を 1 行で記載します（パス＋変更内容。行番号は不要です）。
3. インターフェース — 追加または変更する主要な関数／型のシグネチャ（名前、パラメーター、戻り値）を記載し、実装者とレビュー担当者が契約を把握できるようにします。
4. テスト戦略（判定基準） — 証明に使う単体／統合テスト、その配置場所、および各テストで検証する内容を記載します。これをもとに完了を判断します。暗黙のままにしないでください。
5. リスクと影響 — エッジケースと apify-mcp-server-internal への影響を記載します。
6. データフロー — 自明でない場合のみ記載します：入口 → 変換 → 出力。

セクション 2～4 は具体的に記載してください（実際のファイル、シグネチャ、テストを示し、「TBD」や「エラー処理を追加」のような記述は避けてください）。セクション 1、5、6 は簡潔にします。この構成はPlan向けです。Explore と Spec は簡潔にしてください。

依頼の意図が Plan であれば、ここで停止してください。 ExitPlanMode でプランモードを終了します。

ステップ 3：Spec（Spec のみ）

GitHub issue を作成します。まず ExitPlanMode でプランモードを終了してください。

既存の issue を確認する

重複や関連する issue を検索します。

gh issue list -R apify/apify-mcp-server --search "<keywords>" --json number,title,state
gh issue list -R apify/ai-team --search "<keywords>" --json number,title,state
gh issue list -R apify/apify-mcp-server-internal --search "<keywords>" --json number,title,state

一致する issue がある場合は、新規作成せず gh issue edit で更新してください。

issue を作成する

実装フェーズごとに issue を 1 件作成します。 1 フェーズは PR サイズの作業単位（変更行数約 50～200 行）です。各 issue は単独で実装できるようにします。

リポジトリの feature_spec.yml テンプレートを使用してください。必須なのは Problem と Proposed solution のフィールドのみです。Plan と Alternatives considered は、本当に役立つ場合にだけ記載してください。無駄な記述や水増しはせず、要点を簡潔にまとめます。

## Problem
[Concrete evidence: error messages, user reports, issue links. Not "users are confused" — instead "3 users reported X in #channel".]

## Proposed solution
[Short. Reference existing code paths. List files inline if needed.]

## Plan
- [ ] Step 1
- [ ] Step 2

## Alternatives considered
[Only if you actually evaluated other approaches.]

スタイル（Explore の説明と Spec の issue）：

• 飾り気のない平易な表現にします。無駄な記述は避けてください。CLAUDE.md § Communication style を参照してください
• 空になる、または一般論にしかならないセクションは省略します
• 100 行ではなく、10～30 行にまとめます
• 説明文より具体的な手順を優先します

（Plan の設計は上記の必須セクションの構成に従います。各セクションは簡潔にしつつ、行数に合わせるためにファイル、インターフェース、テスト戦略を省略しないでください。）

提示前にセルフレビューしてください：

• 設計は最小限ですか？範囲をさらに絞れますか？
• 既存のパターンを再利用していますか、それとも独自に作り直していますか？
• 新しいコードを追加するのではなく、既存コードを調整できますか？
• 先にリファクタリングが必要ですか？必要な場合は、別の issue にしてください

作成前に、issue の内容をユーザーに提示してレビューしてもらいます。t-ai ラベルを付けて gh issue create を使用してください。

利用可能なリソース

リソース	パス / URL	用途
パブリックリポジトリ	. (this repo root)	メインのコードベース — ツール、ウィジェット、テスト
内部リポジトリ	../apify-mcp-server-internal (if available)	ホストされているサーバー — 変更の影響を評価
MCP SDK（型）	node_modules/@modelcontextprotocol/sdk	プロトコルの型、サーバー／クライアント API（コンパイル済みのみ）
MCP SDK（ソース）	../typescript-sdk (if available)	例、テスト、完全なソース — GitHub より高速
MCP 仕様	https://modelcontextprotocol.io/specification/2025-11-25	プロトコルレベルの機能
MCP Apps SDK（型）	node_modules/@modelcontextprotocol/ext-apps	MCP Apps の型、React フック、サーバーヘルパー（コンパイル済みのみ）
MCP Apps SDK（ソース）	../ext-apps (if available)	例、テスト、仕様、完全なソース — GitHub より高速
MCP Apps 仕様	https://github.com/modelcontextprotocol/ext-apps/blob/main/specification/2026-01-26/apps.mdx	MCP Apps 拡張仕様
開発サーバー（UI なし）	http://localhost:3001/ / tools: mcp__apify-dev__*	ウィジェットなしでツールをテスト
開発サーバー（UI あり）	http://localhost:3001/?ui=true / tools: mcp__apify-dev-ui__*	ウィジェットをレンダリングしてツールをテスト
mcpc stdio	mcpc @stdio tools-call ... (requires pnpm run build)	ツールをテスト — 実行中のサーバーは不要