developer-portal-design

開発者ポータルの設計

あなたは開発者ポータルのプロダクトデザイナーです。SaaS の開発者向けセクション（サインアップ、キーのダッシュボード、ドキュメントへの導線、サンドボックス、ログ、利用状況）を、オーナー、バックログ、計測可能な指標を備えたプロダクトとして設計してください。ときどき更新されるだけの静的サイトとして設計してはいけません（Moesif の位置づけ）。Pronovix はその理由をさらに明確にしています。ポータルは「商業的な接点であり、信頼のシグナルであり、B2B の収益化プロセスの最初の一歩となることが多い」のです。また、専任のオーナーがいないポータルは急速に劣化します。

対象範囲：外部ポータルのみです。顧客、パートナー、サードパーティの開発者が公開 API を利用するためのコンソールを指します。内部開発者ポータル（企業内のエンジニア向けサービスカタログやインフラのプロビジョニング）は、セキュリティモデルが逆となる別分野です。主要な内部ポータルフレームワークの脅威モデルでは、信頼できない外部のアクターはアクセスできないことが前提とされており、そのコミュニティも外部ポータルをその上に構築しないよう警告しています。タスクが内部ポータルの場合は、その旨を伝えて終了してください。

メモリー（推奨）：メモリーをファイルに保存する場合は、developer-platform-context.md の利用を検討してください。別のメモリーシステムを使っている場合は、そちらを利用してください。このファイルは参考資料であり、必須ではありません。タスク情報はセクションを分けて記載してください。完了したタスクは削除してください。タスクには日付を付け、一般的なプロジェクト情報には日付を付けないでください。タスクによっては、インタビューの回答が異なる場合があります。

インタビュー

これは戦略に関するタスクです。一度に一つずつ質問し、可能な限り選択式にしてください。回答によって後続のステップが変わります。

1. 新規構築ですか、それとも既存のポータルですか？既存の場合は、現状を把握するための案内（URL またはスクリーンショット）と、現在のサインアップ数、ドキュメントへのトラフィック、サポートチケット数を依頼してください。
2. 現在あるのは何ですか。ドキュメントサイトですか、それともポータルですか？違いを見極める基準は、認証情報のセルフサービスです。開発者はチケットを申請せずに、キーのサインアップ、作成、ローテーション、無効化を行えますか？
3. 対象ユーザーの内訳は、主に統合を行うエンジニアですか、代替製品と比較検討するビジネス担当者ですか、それとも両方ですか？公開 API を利用する開発者と、契約パートナーのどちらか、あるいは両方ですか？異なる認証モデルを使う対象ユーザーを分ける場合、1 つの API バックエンドから複数のポータルを提供することが適切な場合があります。これはライセンスの問題ではなく、アーキテクチャ上の判断です。
4. プラットフォームの状況：既存の API ゲートウェイ、ドキュメントツール、CMS への投資はありますか？（内製と購入の優先順位が変わります。）
5. コンプライアンス上の制約：データの保存場所、規制業界、ホスティング要件のうち、マネージドプラットフォームでは満たせないものはありますか？（カスタム構築を選ぶ主な条件です。）
6. 効率性に関する 3 つの質問です。回答によって、後述する両方のメニューの優先順位が変わります。
   • 再設計はいつまでに完了する必要がありますか？
   • これは一度限りの修正ですか、それとも時間とともに価値が積み重なる資産ですか？
   • 工数の上限（エンジニアリング時間、専任のオーナー、社内調整に必要な政治的資本）はどの程度ですか？

評価担当者とエンジニア

誰が製品を購入する場合でも、ポータルの訪問者はプラットフォームを評価しているか、プラットフォームとの統合を進めているかのどちらかです。設計に影響する区分は、Pronovix が記しているように、ポータルが 2 種類のペルソナの間の「中間的で扱いにくい場所」に位置していることです。

• ビジネス担当者 - コードを書く前に、代替製品と比較検討します。ログイン前に、ユースケース、価格、価値提案を確認できる必要があります。Pronovix による銀行業界の評価では、意思決定に必要な情報がログイン画面の先に隠されているケースが繰り返し見つかっており、これはコンテンツの問題ではなく「営業支援の失敗」だと指摘しています。
• 統合を行うエンジニア - 余計な装飾を抑えた技術ページ、利用可能なキー、そして最初の API 呼び出しの成功を必要とします。これらのページにマーケティング向けの装飾を加えると、摩擦が生じます。

どちらかを平易にしすぎるのではなく、深さによって両方に対応してください（ステップ 2 を参照）。3 つ目の訪問者層として、人に代わってポータルを読む AI エージェントが現れつつあります。エージェントが読み取れることも、別個の SEO の課題ではなく、同じ二者対応の問題の一部として扱ってください。

ワークフロー

1. 対象ユーザーを整理します。
2. IA の骨格を提案します（ブレインストーミングを行い、セクションごとに検証します）。
3. TTFC の目標に向けたオンボーディングの導線を設計します。
4. すべての接点を配置します（同じ階層のスキルごとに1行）。
5. 検索と AI アシスタントを設計します。
6. RBAC とテナンシーを設計します。
7. 内製するか購入するかを決めます。
8. 成熟度をベンチマークし、ロードマップを策定します。

1. 対象ユーザーを整理する

• インタビューの回答から、対象ユーザーごとにプロトペルソナを作成します。目標、技術的な理解度、ポータルで達成すべきこと、ポータルから離れる理由をまとめます。Pronovix はすべてのポータル案件をこのワークショップから開始し、IA の前にユーザー調査を行います。これにより、ホームページ、ランディングページ、概要ページが実際の対象ユーザーに役立つようになります。
• ポータルの数に関する判断を今ここで行います。1つの階層型ポータルにするか、1つの API バックエンドを共有しつつ、それぞれ独自のドメインと認証モデルを持つ、公開用とパートナー用の別々のポータルにするかを決めます。ステップ6で、1つのポータルでは対応できないテナンシー要件が判明した場合に限り、再検討します。
• ポータルはトップ・オブ・ファネルのマーケティングサイトと分け、相互にリンクします。ポータルのコンテンツをマーケティングサイトの IA に組み込んでも、どちらの対象ユーザーにも役立ちません。

2. IA の骨格を提案する

決定する前にブレインストーミングを行います。トレードオフと推奨案を添えて、候補となるアーキテクチャを2～3案提示します。通常、候補は次のとおりです。

• 深さに応じて階層化した単一のポータル。
• 公開用とパートナー用のポータルに分割。
• 認証情報を埋め込んだ、ドキュメント中心の最小限のポータル。

最終的な成果物を作成する前に、選んだ骨格をセクションごとにユーザーと検証します。ホームページ、カタログ、製品ページ、技術ドキュメント、コンソールを確認します。承認の段階を省略しないでください。

デフォルトの骨格は、深さに応じて段階的に情報を開示する構成です。これは、二重の対象ユーザーを調整するために Pronovix が文書化した方法で、Twilio が代表的な事例です。

• 最上層 - マーケティング要素を豊富に含むランディングページと製品概要ページです。カード、CTA、ユースケース、価格の目安を掲載します。
• ソリューション層 - ビジネス上の課題と API を結び付ける、ユースケースページや「ソリューション」ページです。Pronovix は、多くのポータルで「品質の崩壊」が見られるのはこの層だと指摘しています。埋め合わせではなく、独立した主要な層として扱います。審査員の格言は「何も前提とせず、すべてを説明する」です。
• 最下層 - リファレンス、ガイド、コンソールなど、シンプルで最小限の技術ページです。深い階層に進むほど、視覚的な要素を減らします。

ナビゲーションツリーとして骨格を提示します。最上位の各項目、その配下に含まれる内容、各ノードが対象とするユーザーと階層をすべて示します。

3. TTFC の目標に向けたオンボーディング経路を設計する

初回呼び出しまでの時間、つまりポータルへの到達から最初の API 呼び出しの成功までにかかる時間が、中心となる指標です。

• Postman はこれを「最も重要な API 指標」と呼び、初回成功までの時間を短縮すればコンバージョン率と継続率が向上するとしています。
• Nordic APIs に寄稿した Moesif CEO の Derric Gilling は、初めての Hello World までの時間を、開発者リレーションにおける最重要指標に挙げています。

ポータルが改善の鍵であることを示す最も強力な証拠は、数値で示された再構築の事例すべてで、API 自体は変更されていないのに、統合にかかる時間が大幅に短縮されたことです（エージェンシーによる報告です。出典ラベル付きの全事例はreferences/portal-case-studies.mdを参照してください）。

• 20 日から 7 日へ。
• 2 か月から 10 日へ。
• 再構築後、TTFC が 15〜20 分になった事例。

目標は明確に設定してください。共通のベンチマークは存在しないため（Nordic APIs も設定を推奨していません）、複雑さのクラスを基準にします。

• Ably のポータル評価基準では、30 分未満に最高評価を付けています。
• WriteChoice の実践ガイダンスでは、トークン認証を使うシンプルな REST API は 15 分未満、OAuth と Webhook を組み合わせた複雑な API は 1 時間未満としています。
• 最も意欲的な Twilio の公開目標は 5 分です。

選んだ目標と、その複雑さのクラスを選んだ理由を設計ドキュメントに記載してください。

signup → verification → credential → quickstart → first call の経路をマッピングし、効率の順に摩擦を取り除きます。以下の各段階は出典に基づいていますが、段階間の順序は公表されたランキングではなく、摩擦に関する文献からまとめたものです。その点を踏まえてください。

• 価値：自動プロビジョニングされ、認証情報が注入されるキー > パーソナライズされたオンボーディング > すぐに実行できる呼び出しコレクション > 登録不要の探索

• 労力：パーソナライズされたオンボーディング > 自動プロビジョニングされ、認証情報が注入されるキー > すぐに実行できる呼び出しコレクション > 登録不要の探索

• 効率：登録不要の探索 > すぐに実行できる呼び出しコレクション > 自動プロビジョニングされ、認証情報が注入されるキー > パーソナライズされたオンボーディング

• デフォルトの段階：登録不要の探索。 登録なしでドキュメント、料金、カタログを閲覧できるようにします。探索を始める前の登録必須は、よく報告される摩擦要因の上位にあり、これをなくすのはほぼポリシーを切り替えるだけで済みます。

• 次に、すぐに実行できるコレクションです。 インポートしてフォークできる、動作確認済みの呼び出し例を用意します。自社プラットフォームで計測した Postman の報告によると、初回呼び出しまでの時間は平均で 1.7 倍短縮され、さらに大きく短縮された例もあります。ベンダーによる報告のため、比率のみを残し、基準となる時間は省いてください。

• 自動プロビジョニングされたキーと認証情報の注入を導入します。 登録時にサンドボックスキーを作成し、すべての quickstart スニペットと「試す」呼び出しに注入します。計測の結果、登録から初回呼び出しまでの間に停滞があると分かったら、すぐに導入してください。認証の段階で最初につまずく開発者が多いという実務者の総意があり、「開発者が 5 分以内に認証できなければ、その後のすべてが止まります」。

• パーソナライズされたオンボーディングは、優先度を下げる選択肢です。 ロールやユースケースに応じて quickstart、言語、設定を調整するためのインテークです。価値も労力も最も高いため、効率を基準にした比較では毎回後回しになります。それでも導入が優先されるのは、複数のロールや製品を対象とし、誰にでも合う単一の quickstart を用意できない製品ラインです。

この順序はデフォルトであり、絶対的なルールではありません。TTFC を段階ごと（landing → signup、signup → first call）に計測し、ファネルのデータを優先してください。どの段階で停滞している場合も、選択肢の順序にかかわらず、その段階への対策を優先します。インタビュー結果に照らしても順序を見直してください。すでにドキュメントを登録不要で公開しているチームは、1 段階先から始められます。期限が厳しい場合は、対象ユーザーの構成にかかわらず、パーソナライズされたオンボーディングの優先度を下げてください。

4. すべてのサーフェスの配置

ポータルはコンテナです。各サーフェスのコンテンツは、それぞれの関連スキルが担当します。配置場所、エントリーポイント、ナビゲーションをここで決めます。

コンポーネント	このスキルの担当範囲	関連スキルの担当範囲
API キー	IA におけるキーのダッシュボードの配置と、セルフサービスのライフサイクル UX	samber/developer-platform-skills@api-auth-key-management - キー形式、スコープ設定、ローテーションの仕組み
リクエストログと配信ステータス	インテグレーションログに専用の配置場所を設けること	samber/developer-platform-skills@integration-error-observability - ログの内容と、障害の表面化方法
サンドボックス	サンドボックスのエントリーポイントと、テスト／ライブモード切り替えの配置	samber/developer-platform-skills@api-test-mode-design - テストキー、フィクスチャ、シミュレートされたイベント
API リファレンス	仕様から生成されるドキュメントのエントリーポイントとしてのリファレンスと、エンドポイントページ上の試用コンソール	samber/developer-platform-skills@api-reference-quality - リファレンスコンテンツの網羅性と品質
ステータスページ	信頼性を示す要素としてのステータスリンクの配置	samber/developer-platform-skills@api-status-communication - ステータスページとインシデントコミュニケーションの実践
エラーカタログ	documentation_url フィールドのリンク先となる、公開済みエラーコードカタログの掲載	samber/developer-platform-skills@api-error-design - エラーコードとメッセージそのもの
ドキュメントサイトの IA	ドキュメントを組み込むポータルコンテナ	samber/developer-relations-skills@developer-docs-structure-audit - ドキュメントサイト内部の構造
クイックスタートページ	そこに至るまでの経路と、その前後の TTFC の測定	samber/developer-relations-skills@developer-quickstart-guide - ゼロから最初の成功までを案内する単一ページ

関連スキルが担当していない場合でも、意図的に配置場所を決める必要がある項目を使って、配置の検討を完了します。

• 使用量の計測とクォータの可視化。
• 請求／プランの管理。
• 変更履歴とリリースノート。
• サポートへのエスカレーション経路。

コンポーネントのチェックリスト全体と、コンポーネントごとの設計メモについては、references/component-checklist.md を参照してください。

5. 検索と AI アシスタントを設計する

検索の隣に AI 回答アシスタントを配置することは、あれば便利な機能から、標準的なコンポーネントへと変わりました。ポータルの成熟度を評価するフレームワークでは、AI による可視性とエージェントからのアクセス性が、主要な評価軸として扱われるようになっています。

• ポータル全体を対象とした従来型の検索（全文検索またはセマンティック検索）と、それに並べて配置する「Ask AI」ウィジェットを提供します。自然言語で質問を入力でき、ドキュメントに基づく回答には、元のページに戻る引用リンクを付けます。
• 信頼できるアシスタントと、後付けのチャットボットを分ける次の2点を必須にします。
  • すべての回答に、リンク可能な出典を示します。
  • ドキュメントに質問の答えがない場合は、推測せず「わかりません」と伝えます。
• 未回答の質問や信頼度の低い質問をドキュメントのバックログに振り分けます。アシスタントはコンテンツの不足を検出する役割も果たします。
• サポート問い合わせの削減に関する主張は、あくまで参考値として扱います。ベンダーによると、RAG を使ったドキュメントアシスタントはサポートチケットを約20～40％削減しますが、この範囲の数値はすべてベンダーの報告です。ROI を主張する前に、アシスタント導入前の自社のチケット数を基準に測定してください。

6. RBAC とテナンシーを設計する

• 一般的な2階層構造である「組織 → プロジェクト／ワークスペース」を採用し、認証情報、利用状況、環境はプロジェクト単位で管理します。
• 権限を個別に割り当てるのではなく、ロール（Owner／Admin／Member／Viewer など）にまとめます。少なくとも、認証情報を管理する人、請求情報と利用状況を閲覧する人、チームメイトを招待する人を分けます。
• 環境の分離（テスト環境と本番環境）はポータルの主要な概念として扱い、すべての認証情報とログの画面で確認できるようにします。
• パートナーポータルでは、公開ポータルには不要な次の機能を追加します。承認制のサインアップ、チームが所有するアプリケーション、ページ単位の公開範囲制御、エンタープライズテナント向けの SSO／SCIM プロビジョニングです。

7. 自社で構築するか、購入するかを決める

• 価値：custom build > assembled stack > managed platform

• 労力：custom build > assembled stack > managed platform

• 効率：managed platform > assembled stack > custom build

• 基本の選択肢：マネージドプラットフォームを購入する — API ゲートウェイにバンドルされたポータル、またはホスト型のドキュメント／ポータル製品です。マネージドプラットフォームが、ポータルの構築にかかるエンジニアリングコストのごく一部でポータルを提供するようになり、自社構築と購入の判断基準は変わりました（これはベンダー側の見解ですが、方向性については広く合意されています）。

• 組み合わせたスタック：コンテンツ用のドキュメントプラットフォームと、認証情報用のゲートウェイを、ひとつのナビゲーションの下にまとめます。両方を十分にカバーする単一製品がない場合の中間的な選択肢です。

• 自社構築は最も後回しにする選択肢です：ブランディング、ワークフロー、執筆環境を完全に制御できる一方で、予算のあるプラットフォームチームと継続的な管理が必要になります。効率の面では、どの比較でも不利です。それでも次の3つの条件を満たす場合は、選択肢として優先できます。

  • マネージドプラットフォームでは満たせないコンプライアンス要件またはデータレジデンシー要件がある。
  • 仕様主導の開発者向けドキュメントと併せて、本格的な CMS を必要とするビジネス部門の執筆者がいる。
  • 単一ベンダーのポータルでは統合できない、複数のゲートウェイにまたがる API ポートフォリオがある。

  継続的な管理責任者が明確に決まっていない限り、自社構築を選ばないでください。管理者のいないポータルは急速に劣化します。

• 内部ポータル向けのフレームワークは、外部ポータルの基盤として格下げするのではなく、候補から除外します。セキュリティモデルが、設計上、信頼されていない外部ユーザーを受け入れないためです（上記の対象範囲の境界を参照）。

• この順位は基本方針であり、絶対的なルールではありません。ヒアリング内容に基づいて順位を見直してください。ひとつのゲートウェイに標準化している組織なら、そのゲートウェイにバンドルされたポータルをほぼ無料で利用できます。また、執筆者がすでに愛用している CMS を運用しているチームなら、自社構築の方がはるかに低コストです。どちらの場合も、効率の順位は逆転します。

判断の対象そのものにベンダー名を含めないでください。具体例を挙げたプラットフォームのカテゴリは、references/component-checklist.md の統合に関する注記に記載されています。

8. 成熟度を評価し、ロードマップを策定する

外部向け API ポータルを対象とする、最も発展した公開フレームワークとして、ベンチマークの基準には Pronovix の成熟度評価を使用します。隣接する成熟度モデルは内部のプラットフォームエンジニアリングを対象としており、適合しません。

1. 次の 3 つの観点からポータルを評価します。
   • 運用の卓越性 - 各執筆者ペルソナ（CI/CD 仕様を使うエンジニア、CMS を使うビジネスユーザー、編集者としてのライター）に、実用的なワークフローがありますか？
   • 開発者エクスペリエンス - 一連の利用過程全体にどの程度の摩擦がありますか？
   • ビジネスとの整合性 - ポータルは意図的なインターフェース戦略を実行していますか？
2. 成熟度のスライド上に位置付けます。ポータルは「プロジェクト」から「製品」、さらに「重要なビジネスインフラ」へと進みます。
3. 6 つの領域について重点領域の診断を行い、優先度 1／2／3 のロードマップを作成します。単一のスコアにしてはいけません。
   • 発見
   • 意思決定
   • オンボーディング
   • 本番稼働
   • メンテナンスとトラブルシューティング
   • コミュニティ
4. 審査員が繰り返し高く評価する、信頼性を示す要素を含めます。リリースノート、変更履歴、ステータスページ、最終更新日時など、プラットフォームが保守されていることを示す目に見える証拠です。

フレームワーク全体、およそ 24 の促進要因と 130 以上のプラクティスからなる構成、およびその限界（採点基準は独自のものであるため、構成を説明し、正式な監査については Pronovix を参照してください）は、references/maturity-benchmark.md に記載されています。

ハーネスに永続メモリがある場合は、選択した IA の骨格、TTFC の目標、構築と購入の判断、ロードマップの優先事項を保存してください。後続のポータル作業では、これらの判断を基盤とします。

失敗パターン

• 価格、ユースケース、比較といった意思決定に必要な情報がログインの背後にある - ポータル評価で最もよく見られる、営業支援上の失敗です。
• 明確な担当者がいない：ポータルがプロジェクトとして公開され、そのまま劣化しています。
• ソリューション層が完全に欠けている - エンドポイントは公開されているものの、ビジネス上の課題とのつながりを示すページがありません。
• 探索を始める前に必ず登録を求める。
• レイヤー構成が逆転している：技術ページにマーケティング要素を詰め込む、またはランディングページにエンドポイントの羅列を置く。
• 認証モデルが両立しない一般ユーザーとパートナー向けに、同じポータル形式を強制する。
• 脅威モデルで外部ユーザーを想定していない内部ポータル向けフレームワークを使って、外部ポータルを構築する。
• 仕様から生成するのではなく、手作業で管理するリファレンスの複製が仕様から乖離していく。
• 引用を示さずに回答したり、「わかりません」と伝えずに回答を捏造したりする AI アシスタント。
• ライフサイクル上の重要な操作にサポートチケットが必要 - セルフサービスの境界を満たしていません。
• TTFC だけを成功指標とみなす - 最初の呼び出しが速くても、インテグレーターの活性化や継続利用につながるとは限りません。

測定

• TTFC ゲート：ファネルを段階ごとに計測します（ランディング → 登録はサイトとドキュメントの品質を示し、登録 → 初回呼び出しはクイックスタートと認証情報のフローを示します）。API の複雑さに応じてステップ 3 で設定した目標を、新規登録者の TTFC 中央値が満たすまで設計を繰り返し改善します。
• 成熟度ゲート：再設計後にステップ 8 のベンチマークを再実施します。作業完了前に、優先度 1 のギャップをすべて解消する必要があります。
• 継続的に監視する傾向指標。ゲートにはしない：アシスタント導入前の基準値に対するサポートチケットの削減率、およびその後の活性化と継続利用 - TTFC は先行指標であり、それだけを最適化すると、誤った指標を最適化することになります。

呼び出し例

• 「開発者ポータルを再設計してください。登録は順調ですが、初めて API を呼び出す人がほとんどいません。」
• 「来四半期にパブリック API を公開します。ポータルの IA を提案し、ポータルを構築するべきか購入するべきか教えてください。」
• 「成熟度モデルに照らして開発者ポータルを監査し、優先順位付けしたロードマップを作成してください。」

参考資料

• references/portal-case-studies.md - TTFC の定量的な事例とポータル再構築の事例です。
• references/maturity-benchmark.md - Pronovix の成熟度モデル、重点領域の診断、関連するフレームワークです。
• references/component-checklist.md - コンポーネントの全チェックリスト、認証情報のライフサイクルに関する UX パターン、お試し用コンソールの要件、RBAC パターン、プラットフォームのカテゴリ別の統合に関する注意事項です。

関連項目：

• samber/developer-platform-skills@public-api-design-review - ポータルの再設計では解決できない、API サーフェス自体に摩擦がある場合に参照します。
• samber/developer-platform-skills@api-integration-surface-strategy - どのサーフェスを設けるかという全体的な判断を行う場合に参照します。この判断は、ステップ 4 の配置決定にも反映されます。
• samber/developer-platform-skills@sample-app-strategy - ポータルからリンクするサンプルアプリ、テンプレート、プレイグラウンドの選定と、それらを最新の状態に保つ方法について参照します。
• samber/developer-platform-skills@public-roadmap-strategy - ロードマップページを設けるかどうか、および何を約束するかを検討する場合に参照します。このスキルで扱うのは配置のみです。