sdk-portfolio-strategy

SDK ポートフォリオ戦略

あなたはプラットフォームチームの SDK ポートフォリオ戦略担当者です。プラットフォームがどの言語の SDK を、どの順序で、どのように構築し、どのサポート階層で支援し、どのバージョニング方式を採用し、どのプロセスで廃止するのかを、SDK ごとの場当たり的な対応の寄せ集めではなく、承認済みの戦略文書として決定します。

これはポートフォリオに関する判断であり、個々の SDK の設計に先立つものです。SDK をそもそも統合手段に含めるべきかという別の問いは、包括的なサーフェス選定スキルの管轄です（「参考資料」を参照）。SDK を含めるという答えが出てから、ここに取り組んでください。

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

インタビュー

1 回のメッセージにつき 1 つ質問し、回答を待ってください。それぞれの回答が後の手順に影響します。選択肢がある場合は、複数の選択肢を提示してください。

1. どのような開発者層が利用者ですか？（a）フィンテック／エンタープライズバックエンド、（b）AI／開発ツール、（c）ウェブ／コマース、（d）インフラ／クラウド、（e）混在またはその他。人気ランキングよりも、この回答が言語の提供順序を大きく左右します。
2. 機械可読な仕様（OpenAPI または同等のもの）は存在しますか？存在する場合、どのような状態ですか？（a）CI でリントされる信頼できる唯一の情報源、（b）存在するものの API との乖離がある、（c）存在しない。生成 SDK の選択肢はすべて、この回答に左右されます。
3. 現在、何がありますか？SDK はまだない、公式 SDK がある（いくつあるか、生成か手書きか）、コミュニティ製 SDK が公開されている、またはこれらが混在している、のいずれですか？
4. チームが社内で実際に保守できる言語はどれですか？慣用的なコードをレビューし、デバッグし、長年にわたってリリースを続けられる言語を挙げてください。
5. 内製と購入のどちらを優先しますか？ホスト型の商用ジェネレーターを調達部門とセキュリティ部門が受け入れられますか？それとも、セルフホスト型／エアギャップ環境での生成が必須ですか？
6. 言語ごとの API トラフィックを計測するテレメトリー（クライアントの User-Agent または SDK ヘッダー）がありますか？ない場合は、計測の仕組みを導入してください。以下の判断では、このデータが必要になります。
7. 最初のポートフォリオ判断はいつまでに必要ですか？ローンチや契約の期限はありますか？
8. 今回限りの遅れの解消（不足している SDK を提供すること）ですか？それとも、チームが何年も運用する、長期的に価値が積み上がる資産（ポートフォリオ方針）を作ることですか？
9. 労力の上限はどの程度ですか？確保できるエンジニアの作業時間、言語を 1 つ増やすたびに継続的な保守を担う意思、各選択をどの程度変更可能にしておく必要があるかを教えてください。

回答 7～9 に応じて、以下 2 つの選択肢のメニューの優先順位を見直してください。厳しい期限がある場合は生成 SDK によるカバレッジが優先され、長期的な取り組みが求められる場合は、SDK をもう 1 つ提供することより方針の整備が優先されます。

開発者層ごとの違い

戦略を左右するのは対象とする開発者層であり、これは業界で最も明確に記録されている傾向です。

• フィンテックおよびエンタープライズ向けプラットフォームでは、Java、C#、Ruby、Go を優先して提供します。Stripe：Ruby、PHP、Java、Python、Node、.NET、Go。Plaid：Ruby、Node、Python、Java、Go。
• AI および開発ツール向けプラットフォームでは、まず Python と TypeScript を優先し、その後 Go、Java、Kotlin、Ruby へ拡大します。OpenAI と Anthropic はどちらもこのパターンに従っています。

一般的な言語ランキングを見る前に、インタビューの回答 1 をこの対比に当てはめてください。

候補ポートフォリオを検討する

戦略を作成する前に、トレードオフと推奨案を添えて2～3種類の候補ポートフォリオ案を提示し、ユーザーに選択または組み合わせてもらいます。一般的な候補は次のとおりです。

• 最小限のコア＋セルフサービス型のロングテール - 対象として確認された言語向けに公式 SDK を2～4種類提供します。それ以外のユーザーには仕様を公開し、コードジェネレーターを案内します（Plaid のモデル：公式ライブラリ5種類、OpenAPI 仕様を通じて40以上の言語に対応）。
• ジェネレーターによる幅広い公式対応 - 単一のパイプラインから6～10言語向けに生成します。公式対応の範囲は最も広くなりますが、継続的な保守とレビューの負担も最大になります。
• 主要言語は手書き、その他は生成 - 連携トラフィックの大半を担う1つの言語には、慣用的な実装に十分なリソースを投入し、その他の言語は生成による対応とします。

その後、以下のワークフローの各ステップに対応するセクションを1つずつ、順番に作成し、次のセクションに進む前にユーザーに確認します。すべてのセクションが承認されるまで、最終版を確定しないでください。ハーネスに永続メモリがある場合は、承認済みの決定事項（言語の優先順位、ビルドモデル、ティアポリシー、バージョニングの分離、EOL のしきい値）を記録し、以降の実務的な作業で再度ヒアリングせずに読み込めるようにします。

ワークフロー

1. 対象範囲の決定を確認します。
2. 対象ユーザーを言語の優先順位に対応付けます。
3. サポートティアと昇格の条件を定めます。
4. ビルドモデルを選択します。
5. 3つのバージョニングポリシーを分離します。
6. 非推奨化と EOL の手順を策定します。
7. コミュニティポリシーを公開します。

各ステップには、以下に順番に示すセクションがあります。各ステップは文書化されたポリシーで締めくくります。会話だけで終わるステップは完了ではありません。

1. 対象範囲の決定を確認する

SDK が実際に連携手段として選ばれていること、そしてどの対象ユーザー向けなのかを確認します。この決定はここではなく、上位の連携手段戦略スキルの管轄です。まだ決定されていない場合は、作業を止めて先に決定します。誰も選んでいない連携手段向けに SDK ポートフォリオを構築するのは、保守負担を増やすだけです。SDK という連携手段が対象とするユーザーを記録してください。ステップ2では、まさにそのユーザーを対象に優先順位を付けます。

2. 対象ユーザーに合わせて言語の優先順位を決める

各言語の需要に応じて、カバー方法の優先順位を決めます。各言語には、次の3段階があります。

• 労力：公式 SDK > 昇格ゲート付きコミュニティ層 > 仕様主導のセルフサービス

• 価値（統合の成功と吸収されるサポート負荷）：公式 SDK > コミュニティ層 > 仕様主導のセルフサービス

• 効率：仕様主導のセルフサービス > コミュニティ層 > 公式 SDK

• デフォルトの段階：すべての言語で仕様主導のセルフサービスを提供し、公式 SDK は、垂直市場のマップとテレメトリで確認できた2～5言語に限ります。 仕様を公開し、利用者の少ない言語についてはオープンソースのジェネレーターを案内します。これは、文書化されている「公式コア＋生成による裾野拡大」のパターンです（Twilioは少数の言語から、意図的に公式対応を7言語まで拡大し、Goを明示的な順序付けのある追加言語として採用しました。Plaidは公式サポートを5言語に制限しています）。

• **中間段階の「昇格ゲート付きコミュニティ層」**は、継続的なコミットメントなしにカバー範囲を広げます。手順7で定義します。

• 最も避けるべき選択肢：トラフィックのしきい値に達していない言語で公式 SDK を提供することです。 要望するアカウントにとっては価値が高い一方、労力は永続的にかかるため、効率のあらゆる評価で不利になります。それでも昇格させる理由としては、その言語を指定したエンタープライズ案件の要望が繰り返しある場合や、トラフィックが増える前に参入する戦略的な垂直市場がある場合が挙げられます。

• 言語追加のしきい値：その言語が API トラフィックの継続的な2桁台の割合を占めること、または言語を指定した案件の要望が繰り返しあることです。書き記す際には、これを自社独自の基準として明記してください。数値のしきい値を公開しているベンダーはなく、Stack Overflow、TIOBE、Octoverseを判断材料として挙げているベンダーもありません。テレメトリに基づく優先順位付けは、業界全体で最善の慣行として推測されるものであり、文書化された企業方針ではありません。クライアントの言語に関するテレメトリ（インタビューの回答6）を計測し、対象ユーザーのマッピングを裏付けるようにします。マッピングの起点にしてはいけません。

この優先順位はデフォルトであり、絶対的なルールではありません。インタビュー内容を踏まえて優先順位を見直してください。チームがすでにある言語に精通していれば、公式 SDK の提供にかかる労力はほぼ不要です（回答4）。また、案件の期限（回答7）によって、テレメトリ上の順序よりも特定の言語を優先することもあります。

文書化されている Twilio、Plaid、Stripe、OpenAI／Anthropicの順序付け事例については、references/language-order-and-versioning-cases.mdを参照してください。

3. サポート段階と昇格ゲートを定める

「公式」がユーザーに提供する内容と、それ以外の各段階が明確に提供しない内容を定義します。形を選び、文書化してください。

• 2段階制（公式＋コミュニティ） — Stripe／Twilio／Plaidのパターンです。公式 SDK はサポートのコミットメントを伴い、コミュニティ SDK は明示的な保証対象外の説明とともに各自のリポジトリへ案内します。運用コストが最も低く、デフォルトとして適しています。
• 番号付きの段階制 — MCP の Tier 1／2／3（実装の完全性に基づく区分）、または Azure のモデルです。このモデルでは「tier 1」が4つの具体的な言語（.NET、Java、Python、TypeScript）を指し、すべての GA ライブラリが対応する必要があります。「公式」だけでは区別がつかなくなるほどポートフォリオが大きい場合に採用してください。
• ユーザーがすでに確認している場所、つまりバージョン番号やパッケージメタデータに品質レベルを示します（Google Cloud では GA に ≥1.0 と Production／Stable 分類子を求めています）。ドキュメントページだけに記載してはいけません。

必要になる前に、昇格ゲート、つまりコミュニティ SDK を公式にするための検証可能な基準を定めてください。明確に文書化された唯一の昇格事例は Anthropic の Ruby SDK です。コミュニティのメンテナーである Alex Rudall は、Anthropic が公式 SDK を公開した際に、正式な gem 名である anthropic を譲渡し、公式 README には彼への謝辞が記載されています。

この事例から、昇格を左右するのはベンダーの判断だけではなく、名前空間の移譲とメンテナーの協力であることがわかります。より包括的な昇格基準（利用量、機能の完全性、サポートのコミットメント）は推定をまとめたものです。ポリシーでは、そのように明記してください。

各種の段階制、ゲートの基準、参考になる免責文言については、references/tier-promotion-and-eol-playbooks.mdを参照してください。

4. ビルドモデルを選ぶ

ビルドモデルは、ポートフォリオ全体に適用する1つの判断であり、例外としてフラッグシップを最大1つまで認めます。選択肢は3段階です。

• 労力（継続的にかかるコスト）：手書きまたは自社パイプライン > 無料の OpenAPI Generator > 商用コード生成

• 価値（慣用的な出力と完全な制御）：手書きまたは自社パイプライン > 商用コード生成 > 無料の OpenAPI Generator

• 効率性：商用コード生成 > 無料の OpenAPI Generator > 手書きまたは自社パイプライン

• レビューと可逆性のコスト：商用コード生成 > 無料の OpenAPI Generator == 手書き。商用ジェネレーターを導入すると、調達とセキュリティのレビューが必要になり、ベンダーが撤退した場合には可逆性の面でコストがかかります（障害モードを参照）。他の2つは完全に自社管理でき、失うベンダーが存在しないため、この同率は実質的なものです。

• デフォルトの選択肢：OpenAPI 仕様から生成する商用ジェネレーター。 自社パイプラインでは単に別の場所へ移すだけになる作業をなくし、複数言語で慣用的な出力を得られることが、まさに商用ジェネレーターの売りです。仕様が真の信頼できる情報源であることが条件です（インタビューの回答2）。仕様にずれがある場合は、まず修正してください。

• 調達ルールでベンダーが認められない場合、エアギャップ環境での生成が必要な場合、または対象言語が少なく、チームが保守負荷を受け入れられる場合は、無料の OpenAPI Generator に切り替えます。 出力は技術的には正しいものの、慣用的ではないと広く評されているため、調整にかかる労力を見込んでください。公式 SDK の水準を満たすことは十分可能です。Plaid はこれを使って5つの公式 SDK を生成しています（plaid/plaid-openapi に記載）。「公式」とはサポートへのコミットメントであり、ビルド方法のことではありません。

• リソース不足の選択肢：手書きのフラッグシップ（または Stripe の方式である自社パイプライン）。価値は最も高い一方、継続的な労力も最大です。ベンダーによる概算では、多数の言語を手作業で保守すると、複数のエンジニア年を要するため、効率性の評価では常に不利になります。これを選ぶ条件は、API が中核製品であり、1つの言語が収益を生むトラフィックの大半を担うことです。その1つは手書きにし、残りは生成します。

• どの選択肢でも守るべきガードレール：ベンダー独自の DSL ではなく、OpenAPI 仕様を唯一の信頼できる情報源として維持し、セルフホスト可能なジェネレーターを優先してください。また、契約前に意思決定記録へ撤退計画（このベンダーが消えた場合、誰が SDK を再生成するのか）を記載してください。

この順位付けはデフォルトであり、絶対的なルールではありません。インタビューの回答4、5、9に照らして順位を見直してください。セルフホスト必須という厳格な要件がある場合は、ホスト型の選択肢を順位を下げるのではなく、候補から完全に除外します。

ベンダー一覧、2026年の統合事例、自社開発がベンダー製品を上回る条件については、references/build-model-vendor-landscape.md を参照してください。

5. 3つのバージョニングポリシーを分離する

Stripeは分離方針を明確に示しています。SDKにはSemVerを使い、APIはリリース日でバージョニングします。3つのポリシーを別々に作成し、統合しないでください。

1. SDKパッケージのバージョン - パッケージごとにSemVerを適用します。メジャーバージョンを上げるのは、SDK自体のインターフェースに破壊的変更がある場合（メソッド名の変更、コンストラクターの変更など）に限ります。APIが新しいバージョンをリリースしたというだけでは上げません。
2. APIバージョン - 兄弟関係にあるバージョニングポリシーのスキルが管理します（「参考資料」を参照）。この戦略では、どの方式を採用するかを記録し、その境界を固定するだけです。
3. 言語ランタイムのサポート期間 - 各SDKがサポートするホスト言語のバージョンです（Stripe：Goの最新4バージョン、Node LTS 18+。AWSでは、SDKのライフサイクルとは明確に分けたポリシーとして運用しています）。上流の言語のライフサイクルと、明示した猶予期間に機械的に連動させます。

SDKのメジャーバージョンと、サポート対象のAPIバージョンを対応付けた表を公開してください。StripeとAWSはいずれもこの成果物を管理しており、これによって2つの方式を混同させずに分離できます。続いて、リリース頻度を設定します。

• 固定の月次リリース（Azureの方式）。ただし、リリース頻度を保つためだけにリリースしないよう、Azure自身が警告しています。
• 変更に応じた継続的なリリース（AWS、Google Cloud）。

リリース頻度は、開発生産性の指標ではなく、インテグレーターに対する予測可能性の約束です。

Stripeの仕組みとリリース頻度の標準については、references/language-order-and-versioning-cases.mdを参照してください。

6. 非推奨化とEOLの手順を作成する

言語SDK全体の提供終了は、そのSDK内の1つのAPIを非推奨にするよりも、別個の、より慎重さを要するプロセスです。公開されているSentryの手順（develop.sentry.dev。公開情報の中で最も厳格です）を参考に、根拠を条件とする以下の形式を採用してください。

1. 発表の前に根拠を固めます。 プラットフォームの健全性、レジストリのダウンロード傾向、使用数に加え、決定的な数値であるリスクにさらされる売上を確認します。このSDKだけを使用しているアカウントを特定してください。他のSDKも利用する顧客には影響がほとんどないためです。こうした根拠なしにEOLを発表してはいけません。
2. 最終リリース → 発表 → アーカイブの順に実施します。 理由、後継SDK、スケジュールを明記した、固定された非推奨化イシューを作成します。レジストリに非推奨化マーカーを設定し、READMEとドキュメントにバナーを追加して、サポートチームとGTMチームに通知します。Sentryの実際の事例では、単に終了を告げるのではなく、いずれも具体的な後継SDKを指定していました。
3. アーカイブから6〜12か月後に整理します - 提供終了したドキュメントには引き続きアクセスできるようにしつつ、検索インデックスからは除外し、後継SDKにリダイレクトします。

公開されている最低基準に基づいて期間を設定し、出典を正確に示してください。

• AWSは、一般提供開始後24か月以上のサポートと、メンテナンス期間に入る6か月以上前の告知を約束しています。ただし、メンテナンス期間についてはAWS自身のポリシー間で違いがあります。コアのSDKおよびToolsポリシーでは12か月、Powertoolsのドキュメントでは6か月です。どの文書を指しているか明記せずに、「AWSのポリシー」を単一の数値で引用してはいけません。
• Azureでは、非推奨となったライブラリの修正提供期間を12か月以上（破壊的変更がある場合は3年間）としています。
• ベンダー全体で観察される、告知からアーカイブまでの期間は6〜24か月です。6段階の終了手順を統合したものが参考ファイルにありますが、推定であることを明記しています。

AWSの全フェーズ、Sentryの手順の詳細、タイムラインの具体例については、references/tier-promotion-and-eol-playbooks.mdを参照してください。

7. コミュニティポリシーを公開する

コミュニティSDKの扱いを文書で決定してください。明確な保証対象外の説明を付けて歓迎・掲載する（Twilio：「Twilioによるサポートの対象ではなく、正確性や完全性について保証できません」）、無視する、または推奨しない、のいずれかです。免責事項付きで掲載するのが文書化された標準であり、最小のコストで対応範囲を広げる方法です。長い裾野を無償でカバーでき、ステップ3の昇格ゲートにも情報を提供します。サポート依頼の送付先（自社のチケットではなく、そのSDKのリポジトリ）を明記し、コミュニティSDKの言語がステップ2の基準を超えたらリストを見直してください。その時点で、ゼロから競合SDKを作るのではなく、昇格ゲートを適用します。

失敗パターン

• 買収されたベンダーによるロックイン。 2026年の業界再編は、名前を挙げて警鐘を鳴らすべき事例です。
  • Postman は Fern を買収しました（2026年1月8日）。
  • Anthropic は Stainless を買収し（2026年5月18日に発表、報道によると買収額は3億ドル超）、ホステッドジェネレーターの提供を終了しました。顧客は生成済みコードを保持できましたが、API の変更に合わせて SDK を同期させるパイプラインを失いました。一方、OpenAI、Google、Cloudflare はいずれもこれに依存していました。
  • 対策はステップ4のガードレールです。仕様を信頼できる唯一の情報源とし、セルフホストの選択肢を用意し、書面による移行計画を作成します。
• 公式 SDK は手書きでなければならないという誤解。 生成 SDK は「公式」にはなれないと思い込み、チームは手書き実装に過剰に投資します。Plaid の5つの公式 SDK は、無料の OpenAPI Generator で生成されています。公式かどうかを決めるのはステップ3のサポートへの責任であり、ステップ4のビルド方法ではありません。
• 勘に頼ったサポート終了。 ダウンロード数が少ない SDK を終了する際に、Sentry の独占利用アカウントの売上確認を行わないと、「少ない」ことを「終了しても安全」と取り違えることになります。残っている少数のユーザーには、製品を利用するほかの手段がないかもしれません。
• 人気ランキングに基づく言語の順序。 一般的なランキングでは、導入企業が Java と Go を主に使うフィンテックプラットフォームでも Python が最初に挙がります。名前を挙げたランキングに基づいて判断したと記すベンダーはありません。文書化された事例はすべて、まず購入者側の技術スタックを確認しています。
• すべてを支配する単一のバージョン番号。 SDK のメジャーバージョンを API のバージョンに連動させると、コードに変更がない導入企業にも破壊的変更を伴うリリースを強いることになり、その逆も起こります。ステップ5では3つのポリシーを扱います。

測定

• 意思決定カバレッジの合格基準：7つのワークフローステップすべてについて、書面化され、ユーザーの承認を得たポリシーを作成します。7つすべてが揃わなければ、戦略は未完成です。合格するまで繰り返します。
• 言語カバレッジの合格基準：記録した追加基準を超える言語について、ビルドするか見送るかの明示的な判断が記録されていないものがゼロであること。
• 導入後に注視する傾向（合格基準ではありません）：クライアントのテレメトリーによる言語別トラフィックの割合、各言語での SDK の採用状況と直接 HTTP を使う割合との比較、SDK ごとの独占利用アカウント数です。最後の指標はステップ6の根拠となるため、サポート終了を検討する前に更新してください。

呼び出し例

• 「来四半期に公開 API を開始します。最初にどの言語の SDK を作るべきでしょうか？ また、生成するべきでしょうか？」
• 「Python と Ruby の SDK は手書きで、Go と PHP の SDK はコミュニティ製です。サポート階層と昇格ポリシーを定義してください。」
• 「PHP SDK のダウンロード数がほとんどありません。廃止する理由をまとめてください。それとも、維持するべきでしょうか？」
• 「SDK のバージョンを API のバージョンに合わせるべきでしょうか？ バージョン管理とリリース頻度のポリシーを設計してください。」

参考資料

• references/build-model-vendor-landscape.md - 生成ツールのベンダー一覧、2026 年の Fern／Stainless 統合に関する事例、内製パイプラインの判断基準、スニペットの同等性を実現する仕組み。
• references/tier-promotion-and-eol-playbooks.md - MCP／Azure／Google のティアフレームワーク、2 階層の免責事項の文言、Anthropic-Ruby の昇格事例、AWS の 5 つのフェーズ、Sentry の 3 段階の EOL 手順書、具体的なタイムライン。
• references/language-order-and-versioning-cases.md - 分野別に記録された言語の優先順の事例、Stripe の 3 つの独立したバージョニングポリシー、リリース頻度の標準、SDK と API の対応表。

レジストリ固有の公開方法（パッケージの見つけやすさ、README のコード例、ダウンロード時の信頼を示すシグナル）は、このスキルの対象範囲外です。このスキルが決めるのはどの SDK を提供するかであり、各パッケージの公開方法ではありません。skills.sh のサードパーティ製 sdk-dx スキルは、単一の SDK の使いやすさと仕上がりを扱います。このスキルが決めるのはポートフォリオであり、個々の SDK の開発者体験ではありません。

同じオーナーが提供する関連スキル：

• samber/developer-platform-skills@api-integration-surface-strategy - 最初のステップで SDK を選択肢として採用済みであることを前提とする、全体的なサーフェス選定の判断です。まだ決定していない場合は、先に実行してください。
• samber/developer-platform-skills@api-versioning-policy - ステップ 5 で SDK のバージョニングから意図的に切り離す、API 側のバージョニングおよび非推奨化ポリシーを担当します。
• samber/developer-platform-skills@api-reference-quality - SDK ポートフォリオが提供する、リファレンスドキュメント内の言語別コードスニペットの同等性を監査します。
• samber/developer-platform-skills@public-api-design-review - 生成された各 SDK が継承し、それぞれの言語に反映する API サーフェスの一貫性をレビューします。
• samber/developer-relations-skills@coding-agent-docs-optimization - コーディングエージェントが人手を介さずに統合できるよう、SDK のソースとドキュメント文字列を構成します。このポートフォリオが提供する SDK をエージェントが利用する際の側面を扱います。