crawler

クローラースキル

Playwriter による調査 -> CDP の証拠取得 -> ドキュメント作成 -> コード生成

<output_language>

ユーザー向けの成果物、保存したアーティファクト、レポート、計画、生成したドキュメント、要約、引き継ぎメモ、コミット／メッセージの下書き、検証メモは、英語で書かれたこの標準スキルファイルとは異なる場合でも、既定ではすべて韓国語にしてください。

ソースコードの識別子、CLI コマンド、ファイルパス、スキーマのキー、JSON／YAML のフィールド名、API 名、パッケージ名、固有名詞、引用したソースの抜粋は、必要な言語または元の言語のままにしてください。

ユーザーが明示的に別の言語を指定した場合、既存の対象アーティファクトの一貫性を保つために別の言語を維持する必要がある場合、または機械可読な契約に正確な英語のトークンが必要な場合に限り、別の言語を使用してください。ローカライズ済みのテンプレートや参考資料（例：*.ko.md や *.ko.json）がある場合は、ユーザー向けアーティファクトにはそちらを優先してください。

</output_language>

• クローラーコードを生成する前に、ウェブサイトを調査します。
• API、認証、セレクター、ネットワーク、ボット対策、手法選択に関する証拠を収集します。
• 再開可能なクロール状態を .hypercore/crawler/<ACTION>.json に、サイトのアーティファクトを .hypercore/crawler/[site]/ に保存します。
• 調査で得られた証拠によって手法の妥当性が確認できた後にのみ、クローラーコードを生成します。

<routing_rule>

再利用可能なクロールのフロー、サイト抽出計画、クロール用の API リバースエンジニアリング、または分析に基づくクローラーコードには、crawler を使用してください。

汎用的なブラウザー自動化、単発のページ操作、クロールの成果物を伴わないドキュメントの書き換えには使用しないでください。単発の簡易な抽出では、依頼が再利用可能なクロール設計に発展しない限り、軽量な方法を使用してください。

</routing_rule>

<instruction_contract>

フィールド	契約
意図	ウェブサイト／API の調査後、証拠に基づくクローラー計画とコードを作成します。
発動条件	再利用可能なクロール、スクレイピング、サイト全体の抽出、クロール戦略、API リバースエンジニアリング、認証／ネットワークの証拠収集、またはクローラーコードの生成。
範囲	調査、手法の選択、証拠アーティファクト、永続的なアクション状態、および妥当性が確認できた場合のクローラーコード生成を担当します。
優先順位	ユーザー／プロジェクトの指示はこのスキルより優先されます。ブラウザー／ネットワーク／CDP で観測した証拠とローカルのアーティファクトは、証拠として扱います。
証拠	Playwriter、Chrome DevTools／CDP、ネットワークの概要、セレクターの確認、ボット対策の調査結果、アーティファクトファイルを使用します。
ツール	必要な場合に限り、ブラウザー／CDP ツールとローカルファイルへの書き込みを使用します。認証情報、ボット対策の回避、本番環境、危険なスクレイピングについては事前に確認してください。
出力	韓国語で調査結果を示し、.hypercore/crawler/ のアーティファクトを作成します。クローラーコードは、証拠によって裏付けられた場合にのみ生成します。
検証	手法の選択、アーティファクト、セレクター／API 呼び出し、生成したコードを、収集した証拠と照合して検証します。
停止条件	クロール手法の妥当性が確認され、アーティファクトが書き込まれ、安全な場合にのみコードが生成されるか、阻害要因が記録された時点で停止します。

</instruction_contract>

<activation_examples>

該当する例：

• 「このショップの商品カードをスクレイピングしてください。まず API を調査してから、クローラーを生成してください。」
• 「このログイン済みダッシュボードがデータを読み込む方法を調べ、Cookie とヘッダーを記録してください。」
• 「Cloudflare で保護されたこのサイトを分析し、最も安全なクロール方法を提案してください。」

該当しない例：

• 「このサイトを開いて、登録フローを進めてください。」
• 「このクロール手順書を読みやすく書き換えてください。」

境界の例：

• 「今すぐ、この公開ページから価格を3つ取得してください。」ユーザーが再利用可能なクローラーやサイト全体の戦略を求めない限り、軽量な抽出方法を優先してください。

</activation_examples>

---

<trigger_conditions>

トリガー	アクション
再利用可能なクロール、スクレイピング、またはサイト全体からの抽出	直ちに実行
クロールのためのサイト調査または API のリバースエンジニアリング	調査と API インターセプトを開始
単一ページからの一度限りの抽出	境界ケースとして扱い、再利用可能なクロール作業が求められていない限り、ワークフローを軽量に保つ
アンチボットの回避、または Cloudflare の影響が大きい対象	リスクチェックとアンチディテクトのガイダンスから開始

</trigger_conditions>

---

<support_file_read_order>

サポートファイルは次の順に読みます。

1. クロールやコードに関する判断を行う前に、pre-crawl-checklist.md を確認します。
2. セッション制御、ページ操作、視覚的な調査、またはセレクターの検証が必要な場合は、playwriter-commands.md を使用します（Playwright MCP = 操作）。
3. ライブネットワークリクエスト、コンソールエラー、パフォーマンストレース、Lighthouse 監査、またはメモリスナップショットについて、Chrome DevTools のファーストパーティの精度が必要な場合は、chrome-devtools-mcp.md を使用します（Chrome DevTools MCP = デバッグ）。
4. Playwriter のスナップショット全体を使うよりもトークンコストを抑えて、ネットワーク、Cookie、トークン、ストレージ、またはレート制限に関する構造化された証拠が必要な場合は、cdp-capture.md を使用します。
5. Playwriter／chrome-devtools-mcp／CDP の証拠を API.md、NETWORK.md、および生の証拠ファイルにまとめる場合は、network-crawling.md を使用します。
6. DOM 抽出がまだ選択肢にある場合は、selector-strategies.md を使用します。
7. ページネーション、認証、遅延読み込み、またはリトライがアプローチに影響する場合は、crawling-patterns.md を使用します。
8. 対象でブロック、CAPTCHA、Cloudflare、または明示的なアンチディテクト要件が確認された場合は、anti-bot-checklist.md を使用します。
9. 実行に .hypercore/crawler/<ACTION>.json の永続的な状態ファイルが必要な場合は、action-manifest.md を使用します。
10. .hypercore/crawler/[site]/ の成果物を作成する場合は、document-templates.md を使用します。
11. 手法の選定と調査証拠の記録が済んでから、code-templates.md を使用します。

</support_file_read_order>

---

<mandatory_reasoning>

必須の構造化推論

• クロールの設計、抽出戦略、またはコード生成に関する判断を行う前に、必ず内部で構造化された推論を行います。
• 主要な各フェーズ（調査、手法の選定、実装計画）で、構造化された推論を行います。
• 外部の推論 MCP は必要ありません。ローカルで推論するにはタスクが不明瞭すぎる場合は、構造化された計画なしに続行せず、妨げとなっている点を報告して中止します。

</mandatory_reasoning>

---

<execution_defaults>

• コード生成、セレクターの確定、または認証に関する想定の前に、調査を行います。
• Playwriter を使ってユーザーに表示されるフローを再現し、その後、構造化されたネットワーク／認証証拠の取得には CDP を優先します。
• CDP またはフォールバックのブラウザネットワーク証拠から安定したエンドポイントと管理可能な認証が確認できる場合は、API を利用するクローラーを優先します。
• 大規模な DOM スナップショットやアクセシビリティスナップショットは必要な場合に限り使用します。デフォルトの取得対象ではなく、構造の確認やセレクターの検証に使用します。
• CDP のアタッチに失敗した場合は、その制約を ANALYSIS.md に記録し、フォールバックの証拠がなお十分な場合に限って Playwriter によるインターセプトを使用します。
• 法的制約、繰り返し発生する 403/429/503、CAPTCHA、または強いアンチボットの兆候により自動化が危険な場合は、中止して妨げとなっている点を報告します。
• 手法、認証情報、レート制限への対応状況が記録されるまでは、CRAWLER.ts の作成を約束しないでください。

</execution_defaults>

---

| フェーズ | タスク | コマンド／方法 | |-------|------|--------| | **1. セッション** | セッションを作成してページを開く | `playwriter session new` | | **2. 調査** | Playwriter でページのフローを再現する | `accessibilitySnapshot`、`screenshotWithAccessibilityLabels` | | **3. 取得** | `chrome-devtools-mcp`（推奨）または CDP の代替手段で、ネットワーク／認証／パフォーマンスの証拠を収集する | `list_network_requests`、`list_console_messages`、`performance_start_trace`、CDP の `Network.*`、`Storage.*`、`Runtime.evaluate` — [chrome-devtools-mcp.md](rules/chrome-devtools-mcp.md) と [cdp-capture.md](rules/cdp-capture.md) を参照 | | **4. 分析** | API 優先か DOM 優先かを判断する | [network-crawling.md](rules/network-crawling.md)、[selector-strategies.md](rules/selector-strategies.md) | | **5. ドキュメント化** | 調査結果を `.hypercore/crawler/[site]/` に保存する | 書き込む | | **6. コード** | クローラーの実装を生成する | [code-templates.md](rules/code-templates.md) |

---

<method_selection>

条件	方法	備考
CDP または代替ブラウザネットワークの証拠で API が見つかり、認証がシンプル	fetch / httpx	最速
API に Cookie／トークンが必要	fetch + Cookie	有効期限の処理が必要
API に Cloudflare／DataDome／JA3 フィンガープリントが関係する	curl_cffi（Chrome を偽装）	TLS／JA3 を復元します。住宅用プロキシと組み合わせてください
調査／ライブネットワーク＋パフォーマンスの証拠	chrome-devtools-mcp	ファーストパーティの CDP 精度（ネットワーク、コンソール、パフォーマンストレース、Lighthouse）— chrome-devtools-mcp.md を参照
ページ操作／ログイン／遅延読み込みのトリガー	playwriter	「ページに必要な操作を実行させる」
強力なボット対策（Cloudflare、DataDome）	Patchright または rebrowser-patches	Chromium にパッチを適用／Runtime.Enable の漏えいにパッチを適用 — anti-bot-checklist.md を参照
Chromium 固有のフィンガープリント	Camoufox	Firefox ベースのステルスフォーク
API なし（SSR）かつボット対策なし	Playwright DOM	直接解析します

</method_selection>

---

<output_structure>

ACTION.json には、意図、現在のステータス、取得モード、ブロッカー、出力先、次のステップを保持します。.hypercore/crawler/[site-name]/ には、そのサイトの詳細な証拠、分析、生成されたコードを保持します。

成果物の最低要件：

• 再利用可能なクローラー作業、ブロックされた作業、または再開可能な作業では、.hypercore/crawler/<ACTION>.json が必須です。
• 再利用可能なクローラー作業では、常に ANALYSIS.md が必須です。
• DOM 抽出を使用する場合、またはフォールバック手段として保持する場合は、SELECTORS.md が必須です。
• API の調査を試みた場合は、API.md が必須です。見つかったエンドポイント、または利用可能な API がなかったことを記録してください。
• Cookie、トークン、ヘッダー、レート制限、ボット検出シグナルが方法に影響する場合は、NETWORK.md が必須です。
• CDP で取得できる場合は、raw/network-summary.json、raw/auth-signals.json、raw/endpoint-candidates.json を推奨します。これらは人が読めるドキュメントの代わりではなく、その根拠として使用してください。
• CRAWLER.ts が必須となるのは、調査の証拠を記録し、選択した方法を正当化した後に限ります。

最初の操作コマンドは playwriter-commands.md に記載されています。CDP の証拠取得については cdp-capture.md を参照してください。永続的なアクション状態のルールは action-manifest.md を参照してください。コアの内容は、方法の選択、出力のゲート、停止条件に集中させてください。

テンプレート： document-templates.md

</output_structure>

---

<blocked_outcomes>

ブロックされた実行、または安全でない実行の場合：

• ブロッカー、停止のきっかけとなった証拠、および最も安全な次のステップを記載した ANALYSIS.md を作成します
• 認証の兆候、ブロック応答、またはボット対策の調査結果が判断に影響した場合は、NETWORK.md を作成します
• 実行がブロックされた場合でも、停止を監査できるよう、利用可能な生の証拠ファイルをすべて書き出します
• ブロックされた状態に合わせて、ACTION.json の status、capture_mode、ブロッカー、および出力ポインターを更新します
• ブロッカーが解消されるか、手法を安全に自動化できるようになるまで、CRAWLER.ts は含めません

</blocked_outcomes>

---

✅ Playwriter session created
✅ `ACTION.json` created when the run is reusable, blocked, or resumable
✅ Structure analyzed with limited Playwriter snapshots
✅ CDP capture attempted for network/auth evidence
✅ raw evidence files recorded when CDP capture is available, or the fallback limitation documented when it is not
✅ Selector extraction validated
✅ Findings documented under .hypercore/crawler/
✅ Crawler code generated
✅ Structured reasoning notes recorded for major phases
✅ legal, rate-limit, and bot-detection blockers documented before scaling
✅ blocked runs reported explicitly when crawler code is unsafe or premature
✅ `ACTION.json` status and `site_dir` match the actual run outputs
✅ completed runs leave `ACTION.json.next_step` empty or terminal and point outputs at final files

---

カテゴリ	禁止事項
分析	構造を分析せずにセレクターを推測する
アプローチ	API を確認せず、DOM のみのフローを使用する
ドキュメント	分析結果の記録を省略する
ネットワーク	レート制限を無視する

---

# User: /crawler crawl products from https://shop.example.com

# 1. Create durable action context
# .hypercore/crawler/extract-products.json

# 2. Session
playwriter session new  # => 1
playwriter -s 1 -e "state.page = await context.newPage(); await state.page.goto('https://shop.example.com/products')"

# 3. Structure analysis
playwriter -s 1 -e "console.log(await accessibilitySnapshot({ page: state.page }))"
# => list "Products" [ref=e5]: listitem [ref=e6]: link "Product A" [ref=e7]

# 4. CDP capture
playwriter -s 1 -e $'
const client = await state.page.context().newCDPSession(state.page);
await client.send("Network.enable");
state.cdpHits = [];
client.on("Network.responseReceived", (event) => {
  if (event.response.url.includes("/api/")) state.cdpHits.push(event.response.url);
});
'
playwriter -s 1 -e "await state.page.evaluate(() => window.scrollTo(0, 9999))"
playwriter -s 1 -e "console.log(state.cdpHits)"
# => ["/api/products?page=2"]

# 5. Update extract-products.json -> status=running, capture_mode=cdp
# 6. Documentation -> .hypercore/crawler/shop-example-com/ + raw/network-summary.json
# 7. Generate API-based crawler