目次を表示する

共通基盤の設計軸 2026 ─ 抽象・責務・非機能要件を設計する 15 章

利用者の認知負荷を下げる ─ Golden Path / SDK / Self-service

利用者の認知負荷を下げる ─ Golden Path / SDK / Self-service

ここまで「作る側」の話だった。最後に「使われる側」── 利用者の体験を扱う。共通基盤がどんなに技術的に優れていても、使いにくければ使われない。

Team Topologies の中心命題：

Platform は stream-aligned team の cognitive load を下げるためにある。

逆に言えば、利用者の認知負荷を上げるなら platform である意味がない。

Golden Path ─「敷かれたレール」

Golden Path とは

Spotify が広めた概念：

新しいサービスを作るときの opinionated で supported な道。「これに従えば 30 分で本番デプロイまで行ける」というレール。

graph LR
  Start[新サービス作成] --> Path[Golden Path]
  Path --> CI[CI 設定済み]
  Path --> CD[CD 設定済み]
  Path --> Mon[監視設定済み]
  Path --> Log[ログ設定済み]
  Path --> Auth[認証設定済み]
  Path --> Deploy[本番デプロイ]

  Note1[全部 30 分で完了]

  style Path fill:#e1f5ff
  style Deploy fill:#e1ffe1

これがあることで利用者は：

  • 「どの言語で書けばいい？」「Recommended は TypeScript」
  • 「ログはどう取る？」「OpenTelemetry が組み込み済み」
  • 「監視は？」「Datadog dashboard が自動生成」
  • 「デプロイは？」「platform deploy 一発」

判断疲れ が大きく削減される。

Backstage の Software Template

Backstage は Spotify が OSS 化した IDP（Internal Developer Portal）。Golden Path を YAML で記述 できる：

# template.yaml
apiVersion: scaffolder.backstage.io/v1beta3
kind: Template
metadata:
  name: nodejs-microservice
  title: Node.js Microservice
spec:
  parameters:
    - title: Service Info
      properties:
        service_name:
          type: string
        owner:
          type: string
  steps:
    - id: fetch-base
      action: fetch:template
      input:
        url: ./skeleton
        values:
          name: ${{ parameters.service_name }}
    - id: publish
      action: publish:github
    - id: register
      action: catalog:register

これで：

  • Git repo 自動作成
  • CI/CD 自動セットアップ
  • Backstage への登録
  • 監視 / ログ設定

を YAML 1 枚で標準化 できる。

Spotify Portal

商用版の Spotify Portal は Backstage に追加機能を載せたもの。自前で Backstage を構築しないなら Portal、カスタマイズしたいなら Backstage 自前 という選択肢がある。

SDK ─ 利用者が書くコードを最小化

API は HTTP で呼べるが、SDK を提供することで認知負荷を劇的に下げられる。

SDK が引き受ける責務

責務内容
認証Token の自動更新、refresh
Retry5xx に exponential backoff + jitter
IdempotencyUUIDv4 を自動生成
Rate limit 対応429 で自動 wait
エラー型HTTP エラーを言語固有の例外に
ログ・トレース呼び出しごとに span 作成
設定環境変数 / IAM 自動検出

良い SDK の例

// 利用者が書くコード
const client = new NotifyClient({ apiKey: process.env.NOTIFY_API_KEY });

const result = await client.send({
  to: '[email protected]',
  subject: 'Welcome',
  body: '...',
});

// この 1 行の裏で:
// - 認証ヘッダー付与
// - Idempotency-Key 自動生成
// - Retry on 5xx
// - 429 は automatic backoff
// - Trace context 伝播
// - structured log 出力

利用者は ビジネスロジックだけに集中できる。

SDK 設計の罠

罠対策
Magic すぎるlog level で内部動作が見える
Lock-in が強い”raw API も提供”
言語追従が遅いgRPC + 自動生成、または OpenAPI
互換性違反semver 厳守、SDK の version policy

多言語対応

社内利用なら 2-3 言語 で十分（TypeScript / Go / Python など）。外部公開（Stripe / Twilio）なら 10+ 言語。

OpenAPI / Smithy / gRPC + 自動生成で多言語対応のコストを下げる。

Self-Service Portal

利用者が 基盤チームに頼まずに 自分で完結できる仕組み。

自分で完結できるべきもの

操作Self-Service？
API key 発行✅
サービス登録✅（Backstage 等）
ログ閲覧✅
メトリクス閲覧✅
アラート設定✅
課金プラン変更✅
Quota 申請⚠️ 申請 + 自動承認
Tenant 削除⚠️ 申請 + 確認
物理 isolation 切替❌ 基盤チーム介入

ほとんどの操作は Self-service にする。基盤チームが手動で介入する操作は最小化する。

Self-Service の Trade-off

Self-service: 利用者が早く動ける / 基盤チームの負担減
            : 誤操作のリスク / セキュリティ要件で制限

危険な操作は 承認フロー を挟む（automated approval も含む）。

Documentation の階層

利用者ごとに必要な情報が違う。

階層

種類対象内容
Quickstart初心者5 分で動かす
Tutorial中級1 時間でひと通り学ぶ
Guide上級パターン別の how-to
Reference全員API 仕様の正典
Concept全員なぜそう設計したかの背景
Runbook運用トラブル時の対応

Diátaxis Framework という命名で広まった分類。4 種類（Tutorial / How-to / Reference / Explanation） で documentation を整理。

“Cookbook” の効果

利用者の 典型的な使い方 を Cookbook として提供：

## Recipe: ユーザー登録時に Welcome メール送信

```typescript
import { NotifyClient } from '@platform/notify';
import { OnUserRegistered } from '@platform/events';

@OnUserRegistered()
export class WelcomeMailer {
  async handle(event) {
    const client = new NotifyClient();
    await client.send({
      to: event.user.email,
      template: 'welcome',
      variables: { name: event.user.name },
    });
  }
}

利用者は **コピペで動かして** から、必要に応じて理解を深める。これは Pit of Success の体験を作る効果が大きい。

## Onboarding と First Win

新しい利用者が **最初の "win"** に到達する時間が、その基盤の使われ方を決める。

### Time-to-First-Win の指標
  • ドキュメントを開く: 0 min
  • アカウント作成: 2 min
  • API key 取得: 5 min
  • 最初の API 呼び出し成功: 10 min
  • 自分のコードに組み込み: 30 min
  • 本番デプロイ: 1 day

「**5 分で最初の API call が成功する**」を目標にする。**この時間が遅いと利用者は離脱する**。

### Stripe の有名な体験
  1. signup.stripe.com で登録
  2. Dashboard で test API key を取得
  3. ドキュメント TOP に curl コマンド
  4. ターミナルでコピペ実行
  5. 1 件目の charge が成功！

**全 step が 5 分以内**。これが Stripe の「**Developer-friendly**」と呼ばれる理由の核心。

## "プラットフォームを売る" 視点

社内基盤でも **「使われない」基盤になる** ことがある。これは技術問題ではなく**マーケティング**問題：

```mermaid
graph TB
  T[技術的に良い] --> Use{使われる?}
  T --> Promo[プロモーション] --> Use
  T --> Onboard[オンボーディング] --> Use
  T --> Support[サポート] --> Use

  Use -->|Yes| Win[基盤が成功]
  Use -->|No| Fail[作って終わり]

  style Win fill:#e1ffe1
  style Fail fill:#ffe1e1

社内基盤チームは マーケター でもある必要がある。Demo / Tech talk / Slack channel / Office hour で 継続的に存在感を示す。

認知負荷のチェックリスト

graph TB
  Q1[Golden Path 整備] --> Q2[SDK 提供]
  Q2 --> Q3[Self-service Portal]
  Q3 --> Q4[Documentation 階層]
  Q4 --> Q5[Cookbook]
  Q5 --> Q6[Time-to-First-Win 計測]
  Q6 --> Q7[継続的プロモーション]
  Q7 --> OK[使われる基盤]

  style OK fill:#e1ffe1

この章の要点

  • Platform の本懐は 利用者の認知負荷を下げる こと（Team Topologies）
  • Golden Path：opinionated + supported なレール、Backstage の Software Template で実装
  • SDK が引き受ける責務：認証 / Retry / Idempotency / Rate limit / エラー型 / ログ
  • Self-Service Portal でほとんどの操作を利用者完結に
  • Documentation は階層化（Diátaxis）、Cookbook で典型的な使い方を提示
  • Time-to-First-Win 5 分以内を目標
  • 社内基盤でもマーケティングが必要

次章への問いかけ

利用者体験は整えた。だが、この設計を担うのは誰か？

次章で 組織と境界 ── Conway’s Law、Team Topologies、Platform-as-a-Product。