ADR とチーム — 意思決定プロセスの民主化

# RFC-003: AI推薦エンジンをマイクロサービスとして分離する
 
## メタデータ
- **著者**: シンジ・タカハシ
- **状態**: 議論中
- **フィードバック期限**: 2024年9月15日
- **関連ADR**: ADR-015（ECS vs EKS）
- **Slack**: #tech-architecture
 
---
 
## 背景
 
現在、商品推薦ロジックはRailsのメインアプリに含まれている:
```ruby
# app/services/recommendation_service.rb（現状）
class RecommendationService
  def recommend_for(user)
    # 単純なルールベース推薦（協調フィルタリングなし）
    user.viewed_products
        .map(&:similar_products)
        .flatten
        .uniq
        .first(10)
  end
end

// recommendation-service/main.go
package main
 
import (
    "encoding/json"
    "net/http"
    "strconv"
 
    "github.com/gin-gonic/gin"
)
 
type RecommendationRequest struct {
    UserID     int   `json:"user_id"`
    ViewedIDs  []int `json:"viewed_product_ids"`
    MaxResults int   `json:"max_results"`
}
 
type RecommendationResponse struct {
    ProductIDs  []int   `json:"product_ids"`
    Scores      []float64 `json:"scores"`
    ModelVersion string  `json:"model_version"`
}
 
func main() {
    r := gin.Default()
 
    r.POST("/recommendations", func(c *gin.Context) {
        var req RecommendationRequest
        if err := c.ShouldBindJSON(&req); err != nil {
            c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
            return
        }
 
        // 推薦ロジック（現在はルールベース、将来はML）
        recommended := getRecommendations(req.UserID, req.ViewedIDs, req.MaxResults)
 
        c.JSON(http.StatusOK, RecommendationResponse{
            ProductIDs:   recommended,
            Scores:       calculateScores(recommended, req.UserID),
            ModelVersion: "v1.0-rule-based",
        })
    })
 
    r.Run(":8080")
}

# Design Doc: AI推薦エンジンの実装設計
 
**ステータス**: 実装中
**ADR参照**: ADR-033 (docs/adr/033-recommendation-service.md)
**RFC参照**: RFC-003
 
## 概要
 
ADR-033で決定したPython FastAPIによる推薦サービスの実装設計。
このドキュメントはADRの「なぜ」に続く「どうやって」を説明する。
 
## APIインターフェース
 
### エンドポイント
POST /api/v1/recommendations
 
### リクエスト
```json
{
  "user_id": 12345,
  "viewed_product_ids": [100, 200, 300],
  "max_results": 10,
  "context": "homepage"
}

{
  "product_ids": [400, 500, 600],
  "scores": [0.95, 0.87, 0.82],
  "model_version": "v1.0",
  "processing_time_ms": 12
}

# recommendation_service/main.py
from fastapi import FastAPI, HTTPException
from pydantic import BaseModel
from typing import List, Optional
import numpy as np
import logging
 
app = FastAPI(title="Recommendation Service", version="1.0.0")
logger = logging.getLogger(__name__)
 
class RecommendationRequest(BaseModel):
    user_id: int
    viewed_product_ids: List[int]
    max_results: int = 10
    context: Optional[str] = "default"
 
class RecommendationResponse(BaseModel):
    product_ids: List[int]
    scores: List[float]
    model_version: str
    processing_time_ms: float
 
@app.post("/api/v1/recommendations", response_model=RecommendationResponse)
async def get_recommendations(request: RecommendationRequest):
    import time
    start = time.time()
 
    try:
        product_ids, scores = recommender.recommend(
            user_id=request.user_id,
            viewed_ids=request.viewed_product_ids,
            n=request.max_results
        )
 
        elapsed = (time.time() - start) * 1000
 
        return RecommendationResponse(
            product_ids=product_ids,
            scores=scores,
            model_version=recommender.model_version,
            processing_time_ms=round(elapsed, 2)
        )
    except Exception as e:
        logger.error(f"Recommendation error for user {request.user_id}: {e}")
        raise HTTPException(status_code=500, detail=str(e))
 
@app.get("/health")
async def health():
    return {"status": "ok", "model_loaded": recommender is not None}

# app/services/recommendation_client.rb
#
# AI推薦サービスへのHTTPクライアント
# 詳細: ADR-033 docs/adr/033-recommendation-service.md
#
class RecommendationClient
  BASE_URL = ENV.fetch("RECOMMENDATION_SERVICE_URL")
  TIMEOUT = 0.1  # 100ms タイムアウト（SLO要件）
 
  def self.recommend_for(user, max_results: 10)
    response = connection.post("/api/v1/recommendations") do |req|
      req.body = {
        user_id: user.id,
        viewed_product_ids: user.recently_viewed_product_ids,
        max_results: max_results
      }.to_json
      req.headers["Content-Type"] = "application/json"
    end
 
    JSON.parse(response.body)["product_ids"]
  rescue Faraday::TimeoutError
    # タイムアウト時はフォールバック（ルールベース推薦）
    Rails.logger.warn("Recommendation service timeout. Falling back to rule-based.")
    user.popular_products(limit: max_results).map(&:id)
  rescue => e
    Rails.logger.error("Recommendation service error: #{e.message}")
    []
  end
 
  private
 
  def self.connection
    @connection ||= Faraday.new(url: BASE_URL) do |conn|
      conn.options.timeout = TIMEOUT
      conn.adapter Faraday.default_adapter
    end
  end
end

# docs/adr/031-postgresql-connection-pooling.md
 
## Context セクションへのコメント
 
リョウ: 「GoodJobを使っていた背景（ADR-003）への参照があると、
なぜ今Sidekiqに変えるのかの対比が分かりやすくなると思います。
"以前はGoodJobを使っていた（ADR-003参照）。以下の理由でSidekiqに移行する"
という書き方はどうでしょう?」
 
---
 
## Consequences セクションへのコメント
 
マイ: 「Sidekiqはスレッドモデルなので、グローバル変数・クラス変数に
スレッドセーフでないコードがある場合に問題が出ます。
このリスクへの言及があると良いと思います。
実際、以前の別プロジェクトでこれにハマったことがあります」
 
---
 
## Decision セクションへのコメント
 
コウスケ: 「選ばなかった理由にGoodJob継続が入っていないのは意図的ですか?
『GoodJobで継続する』という選択肢の評価も書いてあると、
将来のGoodJoBへの回帰判断の際に役立つと思います」

# 新メンバーオンボーディングガイド（抜粋）
 
## Week 1: 読むべきドキュメント
 
### Day 1〜2: ADRを読む
`docs/adr/README.md` から始めて、以下の順番で読んでください:
 
1. ADR-001（なぜRailsか）
2. ADR-008（なぜPostgreSQLか）
3. ADR-012（認証方式）
4. ADR-015（インフラ設計の方針）
 
これを読むことで、このシステムがなぜこのアーキテクチャになっているかが
80%分かります。残り20%はコードを読みながら埋まっていきます。
 
### Day 3: コードを読む
ADRを読んだ後にコードを読むと、設計の意図が分かります。
分からないことはADRを見てください。それでも分からなければ聞いてください。

# ADRが必要かの判断基準（チームガイドライン）
 
**以下のいずれかに当てはまる場合はADRを書く:**
 
- 6ヶ月後の自分が「なぜこうなっているか」と疑問を持ちそう
- 他のエンジニアが変更する可能性があり、文脈がないと間違えそう
- 複数の選択肢を比較して選んだ
- 「触るな」とコメントしたいコードを書いた
- セキュリティ・パフォーマンスに影響する判断
- 外部依存（gem, AWS, 外部API）の選定
 
**ADR不要の判断:**
 
- バグ修正で設計の意図は変わっていない
- 命名・フォーマット等のコードスタイル変更
- テストケースの追加
- 変更の理由がコミットメッセージで十分に説明できる