Claude CodeでBFF・API Gatewayを設計する——フロントエンドごとの最適化APIレイヤー

はじめに

API設計の方法論でも、マイクロサービス全体の設計でもない。「Webフロントエンドは5フィールド、モバイルは3フィールドだけ欲しい」——フロントエンドごとに異なるデータ要求を捌くBFFレイヤーをClaude Codeで自動設計する話だ。さらに記事後半では、Claude Code自体のLLMリクエストをAPI Gatewayで組織管理するという視点にも触れる。

マイクロサービス構成のバックエンドでは、フロントエンドが必要なデータを得るために複数のAPIを叩く（under-fetching）か、必要以上のデータを受け取る（over-fetching）問題が発生しやすい。BFF（Backend for Frontend）パターンはこの問題を「フロントエンドごとに最適化されたAPIレイヤー」で解決するアーキテクチャだ。Sam Newmanが提唱したこのパターンを、Claude Codeで実装する具体的な方法を見ていく。

ただし注意点として、BFFはフロントエンドの種類が複数あるか、フロントエンドとバックエンドのチームが分かれている場合に効果を発揮するアーキテクチャだ。チームが小さく（1〜3エンジニア）、フロントエンドが一種類しかない場合は過剰設計になることがある。

BFFパターンの設計——並列集約・部分障害対応・CLAUDE.mdで薄く保つ

BFFの基本的な構造はシンプルだ。フロントエンドの種類ごとに専用のバックエンドサービスを立て、各クライアントに最適化されたAPIを提供する。

[Web App]         [Mobile App]      [TV App]
     ↓                  ↓               ↓
[Web BFF]        [Mobile BFF]     [TV BFF]
     ↓ ↓ ↓           ↓ ↓            ↓ ↓
[UserSvc] [OrderSvc] [ProductSvc] ...（マイクロサービス群）

BFFの主要な責務は、複数サービスからのデータをN→1リクエストに束ねるデータ集約、over-fetchingを防ぐフィールド削減（モバイルは3フィールド、Webは8フィールド等）、各マイクロサービスが認証処理を持たなくて済む認証・認可の一元化、そしてRedisを使ったレスポンスキャッシュだ。

Claude Codeへの自然言語指示で、こうした要件を持つBFFを生成できる。

「Webフロントエンド向けのBFFを作って。
要件:
- UserService（/api/users）とOrderService（/api/orders）から並列でデータ取得
- ユーザー情報とその直近3件の注文を1レスポンスに集約
- Redisで2分キャッシュ
- 1サービスが落ちても部分的に返す（部分障害対応）」

部分障害対応は設計時から意識する必要がある。Promise.allは一つのサービスが失敗すると全体が失敗するが、Promise.allSettledなら片方が落ちても動き続ける。

const [user, orders] = await Promise.allSettled([
  userService.getUser(userId),
  orderService.getRecentOrders(userId, { limit: 3 })
]);

return {
  user: user.status === 'fulfilled' ? user.value : null,
  orders: orders.status === 'fulfilled' ? orders.value : [],
};

CLAUDE.mdに「BFFには集約・変換・認証のみ実施。ビジネスロジックはダウンストリームサービスへ」と定義しておくことが重要だ。BFFにビジネスロジックを書き始めると、BFFが第2のモノリスになるリスクがある。この制約をCLAUDE.mdで定義することで、Claude Codeが生成するBFFがその範囲に留まる。

マイクロサービス構成では、複数リポジトリにCLAUDE.mdを階層的に配置するパターンも有効だ。

root-repo/CLAUDE.md        # 全体アーキテクチャ規約・サービス間通信ルール
├── user-service/CLAUDE.md # UserService固有のAPI surface・主要概念
├── order-service/CLAUDE.md # OrderService固有の設計
└── web-bff/CLAUDE.md      # WebBFF固有のデータ集約・キャッシュ設定

ルートCLAUDE.mdにはサービス間の通信プロトコル・認証トークンの伝播方式・エラーレスポンス標準・Correlation IDの伝播ルールを定義する。Claude Codeの--add-dirフラグで複数のマイクロサービスリポジトリを同時にコンテキストに追加すれば、「UserServiceとOrderServiceのスキーマを理解した上でBFFを設計して」という横断的な指示が可能になる。

レート制限・認証ミドルウェア——CLAUDE.mdで仕様を定義して一貫実装

レート制限・認証・ロギングといったクロスカッティングコンサーンをCLAUDE.mdで定義することで、複数のBFF間で実装が一貫する。

# CLAUDE.md（API Gatewayポリシー）
## Rate Limiting Policy

### エンドポイント別レート制限
- POST /auth/login: 5 req/分（ブルートフォース対策）
- POST /auth/register: 3 req/時間
- POST /auth/forgot-password: 3 req/時間（メールキーで分類）
- GET /api/*: 100 req/分（認証済みユーザー）
- GET /api/*: 20 req/分（未認証）

### レート制限実装仕様
- アルゴリズム: Redis Sliding Window（Fixed Windowより推奨）
- 認証ユーザー: user_idでリミット
- 未認証ユーザー: IPアドレスでリミット
- 必須レスポンスヘッダ:
  - X-RateLimit-Limit
  - X-RateLimit-Remaining（負の値禁止）
  - X-RateLimit-Reset（Unix timestamp）
  - Retry-After（429レスポンス時のみ）

## Authentication Policy
- JWT検証はGateway層で一元化（各BFFはcontextからuser取得のみ）
- トークンローテーション: 15分アクセストークン / 7日リフレッシュトークン

Redis Sliding WindowをFixed Windowより推奨している点には理由がある。Fixed Windowは境界部でのバーストを許してしまう——例えば59秒目に100リクエスト、61秒目にさらに100リクエストを送れてしまう。Sliding Windowはこれを防ぐため、レート制限の品質が高い。CLAUDE.mdに「Sliding Window推奨」と定義することで、Claude Codeが毎回この実装を選択する。

JWT認証はGateway層で一元化し、各BFFはcontextからユーザー情報を取得するだけにする設計も重要だ。認証ロジックを各BFF・各マイクロサービスが個別に持つ構造は、JWTシークレットの管理箇所が増えてセキュリティリスクになる。CLAUDE.mdにこの原則を書くことで、Claude Codeが生成するコードが一貫した認証パターンに従う。

Kong AI Gateway——Claude CodeのLLMリクエストを組織で管理する

KongのAI GatewayはClaude CodeのLLMリクエストを中央化されたプロキシ経由にルーティングする（konghq.com）。「各開発者マシンにAPIキーを配布する」運用から、「組織単位で一元管理されたゲートウェイ経由でモデルにアクセスする」運用への移行を可能にする。

主要機能は実用的だ。Claude（Anthropic）・AWS Bedrock・Azure・Google Vertex・OpenAIを単一エンドポイントで統合するUniversal LLM API、開発者マシンやVCSからのAPIキー漏洩を防ぎキーローテーションを一元化するAPIキー管理、プロンプトトークン・完了トークン・総コストをdeveloper/team/project単位でレポートする使用追跡、そしてGoogle Drive・Jira・Slack等のMCPツールアクセスをゲートウェイで制御するMCPガバナンスが含まれる。

実運用での注目点は、開発者のワークフロー変更が不要な点だ（konghq.com）。Claude CodeはHTTP標準通信を使うため、環境変数のエンドポイントをKongに向けるだけで、Claude CodeがKong経由でAnthropicに接続する。開発者は意識することなくゲートウェイを通る。

プロバイダーの切り替えも設定変更だけで対応できる（developer.konghq.com）。Claude Code → Kong経由 → Anthropic/Bedrock/Azure/Vertexという流れで、コスト最適化・リージョン選択・フォールバック設定をKong側で管理できる。

EMの視点では、Kong AI GatewayはClaude Codeの「ガバナンス問題」を技術的に解決するアーキテクチャ選択だ。個人の開発マシンにAnthropicのAPIキーを配布するのはセキュリティリスクであり、コスト追跡もできない。ゲートウェイを経由させることで、どのチームがどのモデルをどれだけ使ったかを組織レベルで把握できるようになる。

まとめ

BFF・API Gatewayの設計をClaude Codeで自動化する出発点は、CLAUDE.mdに設計原則を定義することだ。「ビジネスロジックはダウンストリームへ」「Promise.allSettledで部分障害対応」「Sliding Window推奨」「JWT認証はGateway一元化」といった判断をCLAUDE.mdに書けば、以降はClaude Codeがその原則に従ってコードを生成する。コードレビューで同じ指摘を繰り返す必要がなくなる。

Kong AI Gatewayの視点は、Claude Codeを個人ツールから組織インフラとして運用するための設計だ。APIキー管理・コスト追跡・プロバイダー切り替えを組織レベルで管理するゲートウェイは、エンジニアリング組織がAIツールを本格導入するときに直面する運用課題に対する一つの解になる。

まず試すなら、CLAUDE.mdにレート制限仕様（エンドポイント別の値・アルゴリズム・必須ヘッダ）を5行で定義してからレート制限ミドルウェアの実装を依頼してみてほしい。その体験が、CLAUDE.mdがどれほどコード生成の精度を変えるかを実感する最初の一歩になる。

コメント

タイトルとURLをコピーしました