メむンコンテンツぞスキップ
芋出し画像

Codex × browser-to-api Skillsの培底解説 プロンプトでwebサむトが、そのたた API 仕様曞にできる GPT-5.5 Claude Code OpenClaw Antigravity Codex Obsidian Cursor Windsurf Hermes Agent Cowork Mythos Skills NVIDIA Agent Skill オヌケストレヌション

    こんにちは。クドクラです
    今回は、CodexOpenAI のコヌディング゚ヌゞェントず、Browserbase が公開した `browser-to-api` ずいう Skill を組み合わせる手法に぀いお解説しおいきたす。
    OpenAI CEO サム・アルトマンもAPIの䟡倀に぀いお觊れおいたしたが
    この蚘事は、`browser-to-api` を、API ドキュメント生成を䞀床も觊ったこずがない人でも理解できる平易さで解説する入門蚘事である。同時に、Codexや Claude Code でも構わないから、このスキルをどう呌び出しお「ブラりザ操䜜だけで未公開 API の仕様曞を䜜る」のかを、最短ルヌトで瀺す。

    画像

    これ、AI゚ヌゞェント開発が䞀段倉わるや぀。
    サム・アルトマンCEOもAPIの䟡倀に觊れおいたけど、
    これは倩才すぎる。
    OpenAI Codex GPT-5.5+ /browser-to-api Skillsを䜿うず、
    APIがないWebサむトでも、1プロンプトでAPI化できたす。
    AIが自動で解析するのは、

    ・ブラりザのネットワヌク通信  pic.twitter.com/4GoNJgBGoe

    — Claude Code AI駆動開発 OpenClawクドクラ (@KudouCraft) May 16, 2026

    browser-to-api↓

    メンバヌシップ蚘事↓

    人気蚘事↓


    1. 抂芁

    本皿では、次のような読者を想定しおいる。

    • 公開ドキュメントのない Web サヌビスから、自前で SDK を䜜りたい開発者

    • スクレむピングではなく、内郚 API を正面から叩いお自動化したい人

    • Codex や Claude Code を「ブラりザのスクリプト動䜜」ず組み合わせお運甚したい人

    • 既存の Postman/Swagger 運甚に疲れた、API 仕様曞のメンテナンス担圓者

    読み終えた時点で、以䞋が明確になっおいるはずだ。

    • `browser-to-api` がどんなツヌルで、䜕を出力するか

    • なぜ「ブラりザのリプレむ」が、ドキュメントの代替になりうるのか

    • Codex から `browser-trace` → `browser-to-api` の 2 段ロケットを動かす具䜓的手順

    • どこに萜ずし穎があり、どこで人間が手を入れるべきか

    難しい甚語は極力避け、比喩 ず 具䜓䟋 を倚めに入れた。先に曞いおおくず、本皿の䞻圹は「ブラりザの通信ログを、OpenAPI 3.1 の仕様曞に倉換するスキル」である。Codex は、そのスキルを呌ぶ䟿利な手であっお、䞻圹ではない点を最初に断っおおく。


    2. browser-to-api ずは䜕か — 3 ぀の比喩で理解する

    `browser-to-api` を䞀蚀で説明するのは難しいので、3 ぀の比喩で順に理解しおいく。

    2-1. 比喩 1: 「ブラりザ操䜜の同時通蚳」

    あなたが普段やっおいるブラりザ操䜜は、裏偎で倧量の HTTP リク゚ストを発生させおいる。`browser-to-api` は、その HTTP のやりずりを暪で聞きながら、人間に読める仕様曞OpenAPI 3.1に翻蚳しおいく同時通蚳者 である。

    ブラりザで「商品ペヌゞを開く」「コメントを曞く」「ログむンする」ず操䜜するたび、通蚳者はそれを「`GET /products/{id}`」「`POST /comments`」「`POST /auth/login`」ずいう構造化された行に曞き起こしおくれる。重芁なのは、通蚳者は 「聞こえた音」しか曞き起こせない ずいう制玄だ。あなたが觊らなかった機胜の API は、氞遠に翻蚳されない。だから「䜕を觊るか」が、ドキュメントの目次そのものになる。

    2-2. 比喩 2: 「䜿った道だけ曞き蟌たれる地図」

    このスキルが䜜る仕様曞は、察象サむトの党 API ではなく、あなたがブラりザで実際に通った道だけを描いた地図 である。歩いおいない裏道は地図に茉らない。

    逆に蚀えば、「ログむンしおから泚文確定たで」を 1 回通せば、その動線䞊にある API は地図化される。地図の粟床は、あなたの操䜜の網矅性に比䟋する。ここが倧きな違いである。

    この性質は、長所ず短所の䞡面を持぀。長所は、本圓に䜿われおいる API だけが残る こず。未䜿甚のレガシヌ API はノむズにならない。短所は、゚ッゞケヌスの動線を螏み忘れるず、地図に穎があくこず。週次で動線セットを芋盎す運甚が、結局のずころ䞀番安定する。

    2-3. 比喩 3: 「ネットワヌク録画機 + 自動線集マン」

    姉効スキル `browser-trace` が録画機で、ブラりザのネットワヌク通信を JSONL に録り溜める。`browser-to-api` はその録画玠材を受け取り、ノむズ陀去、テンプレ化、スキヌマ掚論、ドキュメント敎圢 たでを党郚自動でやっおくれる線集マンである。

    ひずこずで蚀えば、`browser-to-api` は「ブラりザを䜿った 30 分の䜜業を、未来の自分や同僚のために、OpenAPI ず HTML レポヌトず Fetch クラむアントに倉換しおくれる装眮」である。


    3. 他の API 発芋ツヌルずの違い

    API 仕様曞を䜜る方法は他にもある。代衚的なものず䞊べお比范する。

    | 芳点 | browser-to-api | mitmproxy + 手曞き | Swagger 手動執筆 | HAR ファむル解析 |
    | --- | --- | --- | --- | --- |
    | 入力 | CDP トレヌス | プロキシログ | 仕様の頭の䞭 | HAR JSON |
    | 出力 | OpenAPI 3.1 + HTML + Fetch クラむアント | テキストログ | OpenAPI | テキスト |
    | 孊習コスト | 䜎いコマンド 2 本 | 䞭蚌明曞蚭定が芁る | 高曞匏を芚える | äž­ |
    | スキヌマ掚論 | 自動 | なし | 手動 | 限定的 |
    | ノむズ陀去 | 自動 60〜80% | なし | — | なし |
    | Codex 連携 | 公匏 Skill ずしお呌べる | スクリプト芁 | — | スクリプト芁 |

    mitmproxy は匷力だが、ブラりザに自己眲名蚌明曞を信頌させる初期蚭定が地味に重い。HAR は䟿利だが、レスポンス本䜓が萜ちおいるこずが倚く、スキヌマ掚論には匱い。Swagger 手曞きは「最初は楜だが、API が増えるず远い切れない」兞型䟋である。

    `browser-to-api` の決定的な違いは、「ブラりザを普通に䜿うだけで、ドキュメントが副産物ずしお手に入る」 こずだ。蚌明曞も曞匏も意識しなくおいい。ここが倧きな違いである。


    4. Postman ずの違いを培底解説

    API ずいえば Postman、ずいうむメヌゞは根匷い。だが、Postman ず `browser-to-api` は、䌌おいるようで、決定的に違う 1 点 がある。

    Postman は「人間が API を 1 本ず぀手で投げ、その郜床コレクションに保存しおいく」発想のツヌルである。出発点は「人間の手による打鍵」だ。

    䞀方 `browser-to-api` は、「人間はブラりザを䜿うだけ。API はサむト偎が勝手に叩いおくれる」ずいう発想に立぀。出発点は「サむトが内郚で発行する通信」である。

    | 芳点 | browser-to-api | Postman |
    | --- | --- | --- |
    | 操䜜䞻䜓 | ブラりザサむト偎 | 人間コレクション線集者 |
    | 取りこがし | 操䜜した動線は基本拟う | 入力し忘れた API は氞遠に空癜 |
    | ドリフト远埓 | 再キャプチャで自動曎新 | コレクション偎の手動曎新が必芁 |
    | GraphQL | operationName で自動分解 | 1 リク゚スト = 1 ゚ントリ |
    | 出力フォヌマット | OpenAPI 3.1暙準 | Postman 独自 JSON |

    ぀たり、Postman は 「API を運甚するためのワヌクベンチ」、`browser-to-api` は 「API を発芋するための芳枬装眮」 である。䞡者は競合ではなく補完関係にある。発芋は `browser-to-api`、運甚は Postman、ずいう分業が珟実的だ。


    5. なぜ codex × browser-to-api が生たれたのか — 背景を知る

    近幎、Codex や Claude Code のようなコヌディング゚ヌゞェントが急速に普及した。これらは「コヌドを曞く」「テストを動かす」たでは埗意になったが、「ドキュメント化されおいない倖郚サヌビスを叩く」 ずころで、なお詰たるこずが倚かった。

    たずえば「この瀟内ツヌルの未公開 API を叩くスクリプトを曞いお」ず頌たれた゚ヌゞェントは、兞型的には次のように詰む。

    • 仕様曞がない → 掚枬でフィヌルド名を捏造する

    • ヘッダの芁件が䞍明 → 認蚌なしで叩いお 401 を济びる

    • リク゚スト圢匏が䞍明 → 䜕床も詊行錯誀しお時間ず料金を浪費する

    これを解決する玠盎な方法が、「先にブラりザでサむトを觊り、その通信ログを゚ヌゞェントに枡す」 こずだ。だが、生の CDP ログは人間にも゚ヌゞェントにも読みづらい。だから、ログを構造化しお、OpenAPI 仕様曞たで敎圢する䞭間レむダが芁る。

    `browser-to-api` は、たさにその䞭間レむダずしお生たれた。Codex はその仕様曞を読んで、「もう掚枬しないで枈む」 状態でクラむアントコヌドを曞ける。ここで倧事なのは、゚ヌゞェントの粟床は 入力ドキュメントの質に比䟋する ずいう単玔な事実である。

    別の蚀い方をすれば、゚ヌゞェント時代の開発は「LLM の頭の良さ」より「LLM に枡すコンテキストの質」で勝負が決たる局面が増えた。`browser-to-api` は、そのコンテキストを 芳枬から自動生成する 装眮であり、人間がドキュメントを曞く時間を半日単䜍で削っおくれる。Codex × browser-to-api ずいう組み合わせが泚目されおいるのは、たさにこの「コンテキスト䟛絊の自動化」が゚ヌゞェント運甚の急所だからである。


    6. むンストヌル — 最短 5 分で完了

    導入は驚くほど短い。前提は Node 18 以䞊だけだ。npm 䟝存もない暙準ラむブラリのみで動く。

    1. Codex CLI たたは Claude Code をむンストヌルする。

    2. むンストヌル先の `skills/browser-to-api/` に `SKILL.md` ず `scripts/discover.mjs` が入っおいるこずを確認する。

    3. ブラりザ自動操䜜系の Skill`browser` たたは `browserbase-cli`も入れおおく。手動でブラりザを開く運甚でも構わない。

    4. ゚ヌゞェント偎から `browse network on` ず `discover.mjs` を呌べるこずを確認する。

    泚: `browser-to-api` は トラフィックを取埗しないスキル である。先に `browser-trace` 系で CDP ネットワヌクデヌタをキャプチャしおおく必芁がある。順番を間違えるず「入力が空です」ず怒られる。

    ひずこずで蚀えば、むンストヌルは 2 行で枈む。難所は無い。

    なお、Codex を CLI ずしお利甚する堎合は、`codex` コマンドの蚭定で skills のディレクトリを認識させる必芁がある。Claude Code の堎合は `.claude/skills/` 配䞋に展開されおいれば自動で読たれる。゚ヌゞェントによっおは Skill の抂念名が異なるが、いずれの堎合も「`discover.mjs` ぞの Node 実行暩がある」状態を䜜れば動く、ずいう単玔な芁件である。


    7. browser-to-api の 4 ぀の柱 — 仕組みを理解する

    このスキルの内郚は、4 ぀の工皋で動いおいる。順番に抌さえれば、出力ファむルが「なぜそうなるか」が分かる。

    7-1. 柱 1: ペアリングrequestId による結合

    CDP は「リク゚スト発生むベント」ず「レスポンス完了むベント」を別々のレコヌドずしお吐き出す。`discover.mjs` はたず `requestId` をキヌに、䞡者をペアにする。これで初めお「`POST /api/x` に察しお 200 が返り、本文はこのスキヌマ」ずいう単䜍ができる。

    `browser-trace` の出力は `requests.jsonl` ず `responses.jsonl` の 2 本立おで、それぞれが時系列で䞊ぶ。ペアリングは単玔な join に芋えるが、実際には タむムアりト・キャンセル・リトラむ によっお片偎だけが欠けるケヌスが頻発する。`discover.mjs` は欠けたレコヌドを安党に捚お、確実なペアだけを残す。これにより、埌段のスキヌマ掚論が壊れた入力で誀動䜜するリスクを抑えおいる。

    7-2. 柱 2: テンプレ化パスの倉数化

    `/users/12345/orders/abcdef` のような URL は、人間が芋れば「`/users/{userId}/orders/{orderId}`」ず曞き盎したくなる。`discover.mjs` は、数倀・UUID・16 進文字列 などのパタヌンを発芋的に怜出し、自動でテンプレ化する。

    耇数サンプルで同じ䜍眮に異なる倀が来た堎合、倉数ずしお確定する。1 サンプルしかない堎合は固定パスのたたにする。曖昧なケヌスは `confidence.json` にフラグが立぀。

    䟋えるなら、地図の道に「12345」「67890」ず曞かれた家が䞊んでいるずき、「ここは䜏所欄である」ず気づいお `{houseId}` ず眮き換える䜜業だ。䞀方、「事務所」「資料宀」のような 意味を持぀単語 はテンプレ化されず、固定パスずしお残る。境界刀定は完党ではないため、`/api/orders/draft` のように 数倀に芋えるが定数 な倀が倉数化されおしたう事故は起こりうる。`confidence.json` の倀が䜎いパスは、最終的に人間がレビュヌするのが安党である。

    7-3. 柱 3: スキヌマ掚論JSON Schema の誘導

    リク゚スト本䜓・レスポンス本䜓の JSON を芋お、型・必須・列挙倀 を掚論する。たずえば党サンプルで `status` が `"open"` か `"closed"` しか出おこなければ、列挙倀ずしお曞き出す。

    ただし、これは 誘導的掚論 であっお、契玄的保蚌ではない。「芳枬䞊はそうだった」ずいうだけで、API 提䟛偎が将来別の倀を返さない保蚌はない。ここで倧事なのはこの限界を読者が誀解しないこずだ。

    7-4. 柱 4: ノむズ陀去ず分解

    トラッキングピクセル、フィンガヌプリント、ボット防埡、HTML レンダリングなど、API 仕様曞に含めおも無意味な通信 を自動で陀去する。経隓的には 60〜80% のトラフィックがここで萜ちる。

    加えお、GraphQL や JSON-RPC のような マルチプレックス型 の゚ンドポむントは、`operationName` ごずに別パスずしお分解する。1 本の `/graphql` が、結果的に 12 個の操䜜ずしお地図化される、ずいった具合である。

    分解の刀定材料は、リク゚スト本䜓の `operationName`・`method`・`action`、ク゚リパラメヌタの `opname`・`op` などである。これにより、`POST /graphql` ずいう芋かけ䞊 1 本の゚ンドポむントが、`getUser` `getOrders` `submitReview` ずいった意味のある操䜜名で䞊ぶ。Codex から芋れば、1 ぀の巚倧な箱より、ラベル付きの匕き出しが 12 個ある方が 圧倒的に扱いやすい。

    ひずこずで蚀えば、4 本の柱は 結合 → 倉数化 → 型付け → 敎理 ずいう盎線的な凊理である。


    8. 最初のセットアップ — 初日にやるべきこず

    導入盎埌にやるべきこずは倚くない。次の 5 ぀を 30 分でこなせば、初日は十分である。

    1. 察象サむトを 1 ぀だけ決める。最初は自分が所有しおいるサヌビス、たたは芏玄䞊問題ないサヌビスに限定する。

    2. Codex を起動し、`browser-trace` を呌んで `.o11y/run-001/` を䜜る。

    3. ブラりザで察象サむトを 5 分間、い぀もの動線で操䜜する。

    4. 終了埌、`browse network on` で取埗した body ディレクトリを `.o11y/run-001/cdp/network/bodies/` に 明瀺的にコピヌ する。

    5. Codex に「`discover.mjs --run .o11y/run-001` を実行しお」ず頌み、生成された `index.html` をブラりザで開く。

    泚: body ディレクトリは「セッション共有」のため、別の `browse network on` 実行で䞊曞きされる可胜性がある。run 完了前に必ず自前ディレクトリぞコピヌする癖を持぀。

    ここで倧事なのは、初日は「動くこずを確かめる」だけに集䞭する点だ。地図の網矅性や粟床を远うのは、2 日目以降で十分である。最初の `index.html` が開けた瞬間、`browser-to-api` が解決する課題のスケヌル感が䜓感できるはずだ。


    9. 日垞での䜿い方 — 7 ぀の定番シナリオ

    導入埌、`browser-to-api` を毎日のように呌ぶ兞型シナリオを 7 ぀に敎理した。

    9-1. シナリオ 1: 未公開 API の SDK を䜜る

    • 状況: ある SaaS の公開 API はあるが、Web UI でしか叩けない䟿利な内郚 API がある。

    • 入力: 30 分のブラりザ操䜜 + `discover.mjs` 実行。

    • 結果: `openapi.yaml` ず `client.mjs` が手に入り、Codex に「これを TypeScript SDK に曞き盎しお」ず頌める。

    䟋: ダッシュボヌドの゚クスポヌト機胜が UI 経由でしか動かないが、`POST /internal/export` を叩いおいるこずが地図化できれば、cron でバックアップを自動取埗できる。SDK 化たでを Codex が䞀気通貫でやっおくれるため、人間は「動線を螏む」だけで枈む。

    9-2. シナリオ 2: 競合分析

    • 状況: 競合サヌビスがどんなフィヌルドを内郚で保持しおいるかを芳枬したい。

    • 入力: 競合サむトで通垞のナヌザ操䜜を行いトレヌスを取る。

    • 結果: スキヌマから、競合が「ナヌザ属性ずしお䜕を持っおいるか」を掚枬できる。利甚芏玄に泚意しお䜿うこず。

    9-3. シナリオ 3: 移行プロゞェクトの仕様化

    • 状況: 叀いシステムからのリプレヌスで、珟行 API のドキュメントが倱われおいる。

    • 入力: 珟行サむトで䞻芁動線を 1 呚ず぀操䜜。

    • 結果: 「珟状を衚す OpenAPI」が生たれ、リプレヌス先の蚭蚈議論の土台になる。

    䟋: 10 幎もののレガシヌ瀟内システムに、匕退間近の担圓者しか知らない API が眠っおいる。`browser-to-api` で 1 日かけお䞻芁動線をなぞれば、その日のうちに「珟行仕様の写真」が手に入る。仕様凍結のための䞀次資料ずしお、これ以䞊ない速床である。

    9-4. シナリオ 4: バグ報告に添える蚌拠

    • 状況: フロントから 500 ゚ラヌが頻発する。どのリク゚ストが原因か特定したい。

    • 入力: 再珟操䜜を 1 回行い、`report.md` を確認。

    • 結果: 倱敗゚ンドポむントが信頌床メトリクス付きで可芖化され、バック゚ンド担圓に枡せる。

    9-5. シナリオ 5: モンキヌテスト甚フィクスチャ生成

    • 状況: テストで叩く API レスポンスのモックを倧量に欲しい。

    • 入力: 既存トレヌスの `samples/` ディレクトリ。

    • 結果: サニタむズ枈みのサンプル JSON を、そのたたモックサヌバに流し蟌める。

    9-6. シナリオ 6: GraphQL 仕様の逆匕き

    • 状況: 公開スキヌマのない GraphQL ゚ンドポむントを叩く必芁がある。

    • 入力: ブラりザで察象画面を 1 呚。

    • 結果: `operationName` 単䜍で分解された OpenAPI が手に入り、Codex がク゚リを生成できる。

    9-7. シナリオ 7: 教育甚ドキュメント

    • 状況: 新人にサヌビスの党䜓像を芋せたい。

    • 入力: 䞻芁ナヌスケヌスのブラりザ操䜜。

    • 結果: 自己完結型 `index.html` を枡すだけで、新人が゚ンドポむントの森を歩ける。

    `index.html` はサヌバ䞍芁・䟝存れロで動くため、Slack に添付するだけで配垃できる。新人は、曞籍を読むのず同じ感芚で゚ンドポむント䞀芧ず挙動を眺めるこずができる。これは叀兞的な API ガむドより 「実物に近い」 ずいう点で優れおいる。なぜなら、それは芳枬倀で䜜られおいるからだ。

    ひずこずで蚀えば、`browser-to-api` の甚途は 「觊った操䜜の事埌ドキュメント化」 に尜きる。


    10. スキルを育おる — 自分だけの API 地図にする

    `browser-to-api` の出力は、初回からは完璧ではない。地図は䜿うほど粟床が䞊がるずいう前提で付き合うずよい。

    粟床を䞊げる手段は 3 ぀ある。第䞀に キャプチャの網矅性 を䞊げる。日次・週次でブラりザ操䜜のセットを再実行し、未螏の゚ンドポむントを朰す。第二に `--min-samples` を 2 以䞊に蚭定する。1 サンプルだけの゚ンドポむントは曖昧さが高いので、信頌性重芖時はサンプル数で足切りする。

    第䞉に `--origins` フィルタ を掻甚する。ノむズが倚いサむトでは、察象ホストだけに絞るこずで `report.md` の芋通しが劇的に良くなる。䟋えるなら、ズヌムむン機胜のあるカメラのようなもので、被写䜓だけを残すこずで党䜓が読みやすくなる。

    ここで倧事なのは、最初から完璧を狙わない こずだ。`confidence.json` が䜎い箇所を毎週 1 〜 2 件ず぀手で盎しおいけば、3 ヶ月埌には立掟な仕様曞が出来䞊がる。


    11. メモリを掻かす — 長く䜿うほど賢くなる仕組み

    Codex 偎のメモリ機胜ず組み合わせるず、`browser-to-api` は孊習する地図に化ける。䟋えば、`x-observed-auth` 拡匵で「このサむトは Bearer トヌクンを Authorization ヘッダで䜿う」ず蚘録したら、その情報を Codex 偎のメモリに保存しおおく。

    次回、同じサむトを操䜜する際、Codex は「あ、ここは Bearer 認蚌だ」ず先回りでヘッダ蚭定を提案しおくる。人間が同じ説明を繰り返さなくお枈む ずいう、地味だが効く効率化だ。

    ぀たり、`browser-to-api` が出した䞀過性の発芋を、Codex のメモリが氞続化する。䞡者の圹割は「芳枬短期」ず「蚘憶長期」ず敎理できる。


    12. ゲヌトりェむを䜿いこなす — どこからでも呌び出す

    Codex は CLI だけでなく、IDE 拡匵、Web UI、Slack 連携など耇数のフロント゚ンドから呌べる。`browser-to-api` も同じ思想で、どの入口から呌んでも、同じ run ディレクトリを参照する 蚭蚈になっおいる。

    ぀たり、CLI でキャプチャ、Web で discover.mjs 実行、Slack 通知でレポヌトリンクを共有、ずいう分業が成立する。run ディレクトリ`.o11y/<run>/`は、チヌムで共有可胜なポヌタブルな単䜍だず考えるずよい。

    ひずこずで蚀えば、`browser-to-api` の出力は 「持ち運べる API 仕様曞」 である。


    13. 音声入力マルチフロント゚ンド — 「話しかけるだけ」の未来

    Codex の音声入力を䜿えば、ブラりザを操䜜しながら口頭で「いたの通信を、`run-checkout` ずいう名前で蚘録しお」ず指瀺できる。手はマりスずキヌボヌドに塞がっおいおもいい。

    これは现かい話に芋えお、実は重芁である。なぜなら、API 発芋のための「ブラりザ操䜜」は、䞡手がふさがった状態で行われるこずが倚いからだ。録画ボタンを物理的に抌し続ける旧来の発想から、音声で開始・停止できる発想 に移るず、運甚負荷が䞀段䞋がる。

    たた、Codex はタヌミナル・IDE・Web の各フロント゚ンドからアクセス可胜だが、`browser-to-api` の出力は `.o11y/<run>/` 配䞋にたずたっおいるため、どの入口からでも同じ run を参照できる 。今日 CLI で取ったトレヌスを、明日 IDE で開く、ずいうこずが摩擊なく行える。


    14. サブ゚ヌゞェントで䞊列凊理 — 3 倍速のリサヌチ

    Codex には、サブ゚ヌゞェントを呌び出しお䞊列に䜜業させる仕組みがある。これず `browser-to-api` を組み合わせるず、調査が䞀気に立䜓的になる。

    䟋えば、メむンの Codex に「`browser-to-api` の出力レポヌトを読んで、未認蚌で叩ける゚ンドポむントを列挙しお」ず頌み、別のサブ゚ヌゞェントには「`openapi.yaml` から TypeScript の型定矩を生成しお」ず頌む。読みず曞きを䞊列に走らせる こずで、調査時間は 3 倍速になる。

    ここで倧事なのは、サブ゚ヌゞェントを䜿うずき、出力ファむルぞの 曞き蟌み暩 をどこに集玄するかを決めおおくこずだ。䞊列のサブ゚ヌゞェントが同じファむルを曞きに行くず、䞊曞きで壊れる。読み専門ず曞き専門を分けるのが安党である。

    具䜓的な圹割分担の䟋を挙げる。゚ヌゞェント A は `report.md` を読んで゚ンドポむントを列挙する。゚ヌゞェント B は `openapi.yaml` を読んで TypeScript の型を曞く。゚ヌゞェント C は `samples/` を読んでテスト甚のフィクスチャを生成する。3 者の出力先は独立しおいるため衝突しない。Codex のオヌケストレヌタは、最埌にこれらを 1 本のプルリク゚ストに束ねるだけでよい。芳枬から PR たでが、深倜の数時間で 1 呚する。


    15. スケゞュヌラ — 「寝おる間に働く AI」

    `browser-to-api` は、定期的なキャプチャず組み合わせるず真䟡を発揮する。Codex のスケゞュヌラ機胜たたは cronで、毎日深倜 3 時に䞻芁動線を 1 回回し、`discover.mjs` を走らせお、`report.md` の差分を Slack に流す、ずいう運甚が組める。

    API は静かに倉わる。フィヌルドが远加され、フィヌルドが消え、゚ンドポむントがリネヌムされる。これらの 静かな倉化を、寝おいる間に怜知する のが、このセットアップである。䟋えるなら、倜䞭に巡回しおくれる譊備員のようなものだ。

    実装ずしおは、cron で 4 時に `browser-trace` を起動し、4 時 30 分に `discover.mjs` を走らせ、4 時 35 分に `git diff openapi.yaml` を取り、倉化があれば Slack 通知する、ずいう構成が定番である。差分が空の日は䜕も起きない。差分が出た日だけ、朝のうちに人間が確認する。通知駆動の運甚 に切り替わるこずで、人間の認知負荷は劇的に䞋がる。

    泚: スケゞュヌル実行する堎合は、察象サむトの利甚芏玄ずレヌト制限を必ず確認するこず。


    16. MCP でツヌルを増やす — 無限の拡匵性

    Model Context Protocol (MCP) を䜿うず、Codex から倖郚ツヌルを 远加の Skill ずしお 呌べる。これず `browser-to-api` を組み合わせるず、できるこずが䞀気に広がる。

    䟋えば、`browser-to-api` の出力 `openapi.yaml` を、MCP 経由で Stoplight や Redoc に流しお 公開可胜な HTML ドキュメント に敎える。あるいは、`samples/` ディレクトリを MCP 経由で Postman に流しお、コレクションぞ倉換する。

    加えお、Codex は MCP 経由で GitHub・Linear・Slack にも接続できる。`browser-to-api` の差分怜出ず組み合わせれば、「フィヌルドが枛った」「新芏゚ンドポむントが珟れた」ずいうむベントを、自動で Issue 起祚するこずすら可胜になる。芳枬 → 敎圢 → 通知 → 起祚 → 修正、ずいうルヌプが、人手をほずんど介さずに回るようになる。

    ひずこずで蚀えば、`browser-to-api` は 「OpenAPI を䞭継点に据えた、API 呚蟺ツヌルチェヌンのハブ」 ずしお機胜する。


    17. セキュリティず萜ずし穎

    䟿利なツヌルほど、萜ずし穎は深い。`browser-to-api` を実運甚する前に、以䞋を必ず確認しおほしい。

    第䞀に、察象サむトの利甚芏玄 である。スクレむピング・自動アクセスを犁じおいる堎合、`browser-trace` の実行も問題になりうる。「自分が所有するサヌビス」たたは「明瀺的に蚱諟がある範囲」に限定する。

    第二に、機密情報の挏れ である。トレヌスには Cookie・Authorization ヘッダ・本文䞭のメヌルアドレス・トヌクンが含たれる。出力を共有する前に、`--redact` オプションでセンシティブな倀をマスクする。

    第䞉に、スキヌマ掚論の過信 である。芳枬䞊 `string` だったフィヌルドが、本番では皀に `null` を返すかもしれない。`confidence.json` の倀が䜎いものは、必ず人間がレビュヌする。

    第四に、body ディレクトリの䞊曞き事故 である。前述の通り、`browse network on` の出力先はセッション共有である。run 完了前にコピヌを取らないず、別のキャプチャに䞊曞きされる。

    第五に、法的・倫理的境界 である。芳枬は匷力だが、サヌドパヌティの認蚌が必芁な領域で、本来のナヌザではない人間が芳枬するこずは、たず芏玄違反ずなる可胜性が高い。「自分のアカりントで自分のデヌタを芳枬する」運甚に留めるのが基本である。

    䞀床、共有甚にディスクごずアップロヌドしおから「セッショントヌクンが平文で入っおいた」ず気付くず、深倜に冷や汗をかくこずになる。前段でサニタむズする運甚を、最初から組み蟌むこず。

    ここで倧事なのは、`browser-to-api` の出力は 「秘密が混じった原皿」 であり、「公開しおよい枅曞」ではない ずいう認識である。


    18. 1 週間ロヌドマップ — 初心者向け

    導入から定垞運甚たでの 1 週間モデルを瀺す。

    1. 1 日目: むンストヌルずサンプル実行。`index.html` がブラりザで開けるずころたで。

    2. 2 日目: 自分のサヌビスで 1 シナリオをキャプチャ。`report.md` を読み、ノむズ陀去の効きを確認。

    3. 3 日目: `--origins` ず `--exclude` の調敎。地図の S/N 比を䞊げる。

    4. 4 日目: `--redact` の蚭定。共有可胜な状態に敎える。

    5. 5 日目: `client.mjs` を読み、Codex に「TypeScript 化しお」ず頌む。

    6. 6 日目: `confidence.json` の䜎い箇所を 5 件、人間が手で修正。

    7. 7 日目: 翌週からのスケゞュヌル実行を蚭蚈。差分通知を Slack に飛ばす蚭定たでを完了させる。

    ひずこずで蚀えば、1 週間で「芳枬 → 敎圢 → 共有 → 自動化」たでを䞀筆曞きで終える。詰たったら 1 日戻る、で問題ない。


    19. よくある倱敗パタヌンず察凊

    定垞運甚に入るず、ほが党員が同じ眠を螏む。代衚的な 6 ぀を挙げる。

    • 眠 1: レスポンス本䜓が空

      • 原因: `browse network on` を䜿っおいない。CDP ファむアホヌスは本文を運ばない。

      • 察凊: `browse network on` を必ずセットで䜿う。

    • 眠 2: テンプレ化されない数倀 ID

      • 原因: サンプルが 1 件しかなく、倉数か固定倀か刀別䞍胜。

      • 察凊: 同じ動線を 2 回以䞊回す、たたは `--min-samples 2` を指定する。

    • 眠 3: GraphQL が 1 本にたずめられる

      • 原因: 叀い `discover.mjs` を䜿っおいる。

      • 察凊: 最新版に曎新し、`operationName` 分解が有効になっおいるか確認する。

    • 眠 4: トラッキングがノむズで残る

      • 原因: フィルタ蟞曞に未登録のドメむンが含たれおいる。

      • 察凊: `--exclude` で正芏衚珟を远加するか、`--origins` で察象を絞る。

    • 眠 5: 認蚌ヘッダが拟われない

      • 原因: `browse network on` がヘッダの䞀郚を切っおいるケヌス。

      • 察凊: ブラりザの開発者ツヌルで実倀を確認し、`x-observed-auth` の倀を必芁なら手で補正する。

    • 眠 6: 出力 HTML が他人に開けない

      • 原因: ロヌカル絶察パスを参照しおいる。

      • 察凊: `index.html` は自己完結型に出力されるが、`samples/` を䞀緒にコピヌするこず。

    • 眠 7: 同じ URL のメ゜ッド違いがマヌゞされる

      • 原因: `GET /resource` ず `DELETE /resource` を 1 ぀の定矩ずしお扱っおしたうケヌス。

      • 察凊: 最新の `discover.mjs` はメ゜ッドごずに分割するが、叀い版では `--stage path` の䞭間出力を手で芋お確認する。

    • 眠 8: 認蚌ありの API が「芳枬䞊 401」ず蚘録される

      • 原因: トヌクン切れ・別タブのログアりトの圱響。

      • 察凊: トレヌス取埗前に必ずログむン状態を確認し、長時間動線では途䞭で再認蚌する。

    ぀たり、倱敗のほずんどは 「キャプチャ偎の蚭定䞍足」 に起因する。`discover.mjs` 自䜓は玠盎に動く。だからこそ、運甚䞊の劎力の 8 割は 「いかに綺麗な録音を取るか」 に泚がれるこずになる。地味だが、ここに王道はない。


    20. 䞊玚者ぞの道 — その先にある䞖界

    ここたでの内容を䞀通り䜿いこなせるようになったら、次のステヌゞが芋えおくる。

    1 ぀目は、カスタム ステヌゞ の導入である。`--stage` フラグで「ペアリングだけ」「テンプレ化だけ」を走らせ、その䞭間産物 `intermediate/` を自前ツヌルで加工しおから次のステヌゞに流す。瀟内固有のフィルタや、独自のスキヌマ拡匵を差し蟌める。

    2 ぀目は、契玄テストぞの転甚 である。`openapi.yaml` をスキヌマレゞストリに登録し、CI 䞊で本番の API レスポンスを照合する。芳枬 → 仕様 → 怜蚌 のルヌプが閉じる。

    3 ぀目は、マルチサむト統合 である。耇数サむトのトレヌスを統合し、共通のドメむン䟋: 認蚌、決枈のスキヌマを暪䞊びで比范する。業界暙準の玠案を䜜る土台になる。

    4 ぀目は、スキヌマ差分の SLA 化 である。週次の出力 `openapi.yaml` を git にコミットし、差分を PR で扱う。フィヌルドが消えた・型が倉わったずいった倉曎が、自然ず人間の目に觊れる。サヌドパヌティ API のドリフト を、゚ラヌ発生前に気づく仕組みになる。

    5 ぀目は、Codex プロンプトぞの盎接埋め蟌み である。`openapi.yaml` を Codex のシステムプロンプトに添えるず、゚ヌゞェントは「正しい゚ンドポむント・正しい匕数名」でしかコヌドを曞かなくなる。プロンプト゚ンゞニアリングが、芳枬デヌタの遞別䜜業に倉わる。

    ひずこずで蚀えば、`browser-to-api` は 「芳枬装眮」 から 「蚭蚈ず怜蚌のハブ」 ぞず圹割が拡匵しおいく。


    21. 甚語解説集

    • browser-to-api: Browserbase が公開しおいる Skill のひず぀。`browser-trace` の出力を入力にしお、OpenAPI 3.1 仕様曞を生成する。

    • browser-trace: Chrome DevTools ProtocolCDPを䜿っお、ブラりザのネットワヌク通信を JSONL で蚘録する姉効 Skill。

    • CDP: Chrome DevTools Protocol。Chromium 系ブラりザに察し、倖郚から操䜜・芳枬を行うための公匏プロトコル。

    • OpenAPI 3.1: REST API の仕様を蚘述する業界暙準フォヌマット。Swagger の埌継。

    • discover.mjs: `browser-to-api` の本䜓スクリプト。Node 暙準ラむブラリのみで動く。

    • requestId: CDP がリク゚ストずレスポンスを玐付けるための識別子。

    • operationName: GraphQL リク゚ストで、どの操䜜を呌ぶかを瀺すフィヌルド名。`browser-to-api` の自動分解の鍵ずなる。

    • confidence.json: 各゚ンドポむントの掚論信頌床を JSON で瀺した出力。䜎い倀は人間レビュヌ察象。

    • samples: 芳枬したリク゚スト・レスポンスのサニタむズ枈み䟋。`samples/` ディレクトリに栌玍される。

    • `browse network on`: ブラりザ系 Skill のコマンドで、レスポンス本䜓をディスクに保存する。CDP の本文欠萜を補う。

    • `--redact`: センシティブ情報をマスクするフラグ。共有前に必ず䜿う。

    • `--origins`: 察象オリゞンを絞るフラグ。ノむズが倚い時に重宝する。

    • `--min-samples`: テンプレ化やスキヌマ掚論に最䜎限必芁なサンプル数。信頌性重芖で 2 以䞊を掚奚。

    • `x-observed-auth`: OpenAPI 拡匵のひず぀。芳枬䞊の認蚌方匏を蚘録するが、圢匏保蚌ではない。

    • MCP: Model Context Protocol。Codex や Claude Code から倖郚ツヌルを呌ぶ暙準プロトコル。


    • JSONL: 1 行 1 JSON 圢匏のファむル。CDP のむベントログは倧量・远蚘型のためこの圢匏で保存される。

    • `.o11y/<run>/`: `browser-trace` ず `browser-to-api` が共有する䜜業ディレクトリの芏玄。observability の略。

    • Skill: Codex / Claude Code 系゚ヌゞェントの拡匵単䜍。`SKILL.md` ず関連スクリプトで構成され、远加でツヌルチェヌンを増やせる。


    22. コマンドチヌトシヌト

    # Skill むンストヌル初回のみ
    npx skills add https://github.com/browserbase/skills --skill browser-trace
    npx skills add https://github.com/browserbase/skills --skill browser-to-api
    
    # トレヌス取埗ブラりザ操䜜を行う前に実行
    browse network on
    # ここで実際にブラりザで察象サむトを操䜜する
    
    # run ディレクトリぞ body を明瀺的にコピヌ
    cp -r /tmp/browse-network-bodies .o11y/run-001/cdp/network/bodies/
    
    # OpenAPI 仕様曞の生成最小コマンド
    node skills/browser-to-api/scripts/discover.mjs --run .o11y/run-001
    
    # 出力先を倉える
    node skills/browser-to-api/scripts/discover.mjs --run .o11y/run-001 --out artifacts/api-spec
    
    # 察象オリゞンを絞る
    node skills/browser-to-api/scripts/discover.mjs --run .o11y/run-001 --origins https://example.com
    
    # ノむズ系 URL を陀倖
    node skills/browser-to-api/scripts/discover.mjs --run .o11y/run-001 --exclude "/track|/pixel|/beacon"
    
    # サンプル数で足切り
    node skills/browser-to-api/scripts/discover.mjs --run .o11y/run-001 --min-samples 2
    
    # センシティブ情報のマスク
    node skills/browser-to-api/scripts/discover.mjs --run .o11y/run-001 --redact
    
    # 出力 HTML をブラりザで開くmacOS / Linux / Windows
    open .o11y/run-001/api-spec/index.html
    xdg-open .o11y/run-001/api-spec/index.html
    start .o11y/run-001/api-spec/index.html

    以䞊が、`codex × browser-to-api` を最短で䜿いこなすための教科曞である。明日の朝、い぀ものブラりザを開く前に、`browse network on` を 1 回぀ぶやくずころから始めおみおほしい。地図は、その日から自動的に生たれ始める。

    最埌にもうひずこず。地図は、それを描くためではなく、「次の旅をどこぞ向けるか」を考えるために ある。`browser-to-api` が日々の API 芳枬を肩代わりしおくれるこずで、あなた自身は「次にどんな自動化を䜜るか」ずいう、本来の創造的な仕事に時間を割けるようになる。それこそが、`codex × browser-to-api` ずいう組み合わせが提瀺しおいる未来である。

    おすすめ蚘事↓

    たずめ

    `browser-to-api` は、単なるドキュメント生成ツヌルではなく、あなたず䞀緒に成長するパヌトナヌ である。むンストヌル盎埌は他のツヌルず倧差ないが、1 週間䜿うず自分の察象サむトの癖を芚え、1 ヶ月䜿うずスキヌマの揺らぎが芋え、3 ヶ月䜿うず 手攟せない存圚 になっおいる。

    そしお、Codexや Claude Codeず組み合わせた瞬間、このパヌトナヌは「黙っお働く同僚」に化ける。あなたがブラりザで觊る、゚ヌゞェントが仕様曞を読む、SDK が自動で生たれる、ずいう流れが日垞になる。

    ここたでで匷調しおおきたいのは、`browser-to-api` は 「魔法」ではなく「䞁寧な芳枬装眮」 だずいうこずだ。芳枬した範囲しか地図化されないし、芳枬したものが正しい保蚌もない。だからこそ、人間の圹割は「䜕を觊るか」ず「最終的な信頌床の刀定」に集䞭しおいく。逆に蚀えば、゚ヌゞェント時代に人間が担うべき仕事は、「動線を蚭蚈し、芳枬結果を承認する」 こずに収斂しおいく、ずも蚀える。

    最埌に、本皿で孊べる 10 項目を敎理しおおく。

    1. `browser-to-api` は、ブラりザの CDP トレヌスから OpenAPI 3.1 を䜜るツヌルである。

    2. キャプチャ圹は `browser-trace`、敎圢圹は `browser-to-api`、ずいう 2 段ロケットである。

    3. 出力は `openapi.yaml` / `client.mjs` / `index.html` / `report.md` / `confidence.json` / `samples/` である。

    4. パステンプレ化は数倀・UUID・16 進倀を発芋的に怜出する。

    5. GraphQL は `operationName` で自動分解される。

    6. ノむズ陀去で 60〜80% のトラフィックが萜ちる。

    7. スキヌマ掚論は誘導的であり、契玄的保蚌ではない。

    8. レスポンス本䜓は `browse network on` がないず取れない。

    9. body ディレクトリは run 完了前に明瀺的にコピヌする。

    10. `--redact` でセンシティブ情報を必ずマスクする。

    今日のうちに詊しおみおほしいのは、自分の所有する Web サヌビスで 1 回キャプチャを取り、`index.html` を開いおみるこずだ。10 分埌に「地図」が手に入る感芚を、たず䞀床味わっおほしい。

    • STEP 1: この蚘事ぞの「スキ♡」

    • STEP 2: noteで「クドクラ KudouCraft」をフォロヌ

    • STEP 3: XTwitterでの拡散

    メンバヌシップ蚘事も曎新しおいくので芋おくれたら嬉しいです

    皆さんの感想や「こんな䜿い方しおるよ」ずいう報告、
    お埅ちしおいたす
    最埌たで読んで頂きありがずうございたす
    それではたた次回の蚘事でお䌚いしたしょう。

     
     
    KudouCraft AI駆動開発で未経隓から䞊玚者たで生成AI掻甚 質が良い完成品のある自動化をコンセプトに 最新AI゚ヌゞェントの情報をお届け これであなたもAIを䜿いなす偎に。

    あなたぞのおすすめ