ADR とは何か — 意思決定を記録する文化

# ADR-001: [タイトル]
 
## Status（ステータス）
Proposed | Accepted | Deprecated | Superseded by ADR-XXX
 
## Context（コンテキスト）
この決定が必要になった背景と、直面していた問題を書く。
技術的な状況、ビジネス上の要件、チームの制約など。
 
## Decision（決定）
どう決めたか。能動態で書く。
「〜にする」「〜を採用する」
 
## Consequences（結果・影響）
この決定によってどうなるか。
メリットとデメリット、将来への影響を正直に書く。

# ADR-001: Ruby on Railsをメインフレームワークとして採用する
 
## Status
Accepted
 
## Context
2022年3月、新規Webアプリケーションのフレームワーク選定が必要になった。
チームの技術スタック:
- バックエンドエンジニア: 5名（Ruby経験者3名、Python経験者2名）
- プロダクトのコア: CRUD操作が多いB2B SaaS
- 優先事項: 開発速度、採用市場でのエンジニア確保
 
検討したフレームワーク:
- Ruby on Rails 7.x
- FastAPI (Python)
- Laravel (PHP)
 
## Decision
Ruby on Rails 7.xを採用する。
 
理由:
1. チームの過半数(3/5)がRuby経験者であり、学習コストが最小
2. ActiveRecordによるDB操作の簡素化が、CRUD中心のSaaSに適合
3. Convention over Configurationにより、小チームでも一貫したコードベースを維持しやすい
4. Hotwireの登場によりフロントエンド負荷を減らせる
5. 採用市場でRubyエンジニアが確保しやすい（東京圏で判断）
 
FastAPIを選ばなかった理由:
- Python経験者は2名のみ。3名の再学習コストが高い
- ORM(SQLAlchemy)の設定が複雑でCRUD中心SaaSには過剰
 
Laravelを選ばなかった理由:
- PHP経験者がチームにいない
- 採用時のPHPエンジニア確保が難しいと判断
 
## Consequences
良い影響:
- 既存エンジニアが即戦力として機能
- Rails wayに従うことでコードレビューのコストが下がる
- scaffold, migration等のツールで開発速度が上がる
 
悪い影響・リスク:
- PythonエンジニアはRubyの学習期間(1-2ヶ月)が必要
- スレッドモデルではないため、大量の同時接続には注意が必要
- Python製の機械学習ライブラリを組み込む場合はAPI経由での連携が必要
 
再評価のトリガー:
- チームの組成が大きく変わった場合
- パフォーマンス要件がRailsのキャパシティを超えた場合

# このコードを変更する前に、必ずADR-023を読むこと
# docs/adr/023-payment-retry-logic.md
#
# 要点: RETRY_INTERVALが指数バックオフでなく固定値な理由は
# 決済APIプロバイダーのSLAが30秒インターバルの再試行を推奨しているため
class PaymentService
  MAX_RETRY = 3
  RETRY_INTERVAL = [1, 5, 30].freeze
 
  def charge_with_retry(amount, card_token)
    RETRY_INTERVAL.each_with_index do |wait, attempt|
      result = stripe_charge(amount, card_token)
      return result if result.success?
 
      Rails.logger.warn("Payment attempt #{attempt + 1} failed: #{result.error}")
      sleep(wait) unless attempt == MAX_RETRY - 1
    end
 
    raise PaymentFailedError, "#{MAX_RETRY}回の試行後も失敗"
  end
 
  private
 
  def stripe_charge(amount, card_token)
    Stripe::Charge.create(
      amount: amount,
      currency: "jpy",
      source: card_token
    )
  rescue Stripe::CardError => e
    OpenStruct.new(success?: false, error: e.message)
  end
end

# チームSlackの会話（ADR前）
マイ: 「今度の機能、どのgemを使う？」
リョウ: 「kaminariかwill_paginate？」
コウスケ: 「どっちが良かったっけ」
マイ: 「前も同じ話したよね。またゼロから調べる？」
# 30分の議論の末、以前と同じ結論に達する
 
# チームSlackの会話（ADR後）
マイ: 「今度の機能、ページネーションどうする？」
リョウ: 「ADR-021にkaminari選んだ理由が書いてある。継続でいい？」
コウスケ: 「条件変わってないね。kaminariで行こう」
# 3分で完了

# ADR-023のStatus更新
 
## Status
Superseded by ADR-045
 
ADR-023でResqueを採用したが、ADR-045でSidekiqに移行する。
移行の理由は ADR-045 を参照。
 
移行タイムライン: 2024年Q2
移行担当: リョウ

# ADR-021: ページネーションにKaminariを使う
 
## Status
Accepted
 
## Context
一覧ページのページネーション実装が必要。will_paginateとKaminariが候補。
 
## Decision
Kaminariを採用する。チームの過去プロジェクトでの使用実績があり、
Railsの新バージョンへの対応が継続的に行われているため。
また will_paginate は Rails 7 との互換性に不安がある。
 
## Consequences
チームの学習コストがゼロ。will_paginateへの移行は基本的に不要。
将来的に100万件を超えるページネーションが必要になった場合は
cursor-based paginationへの移行を検討する。

# app/jobs/send_welcome_email_job.rb
#
# バックグラウンドジョブの方式選定については ADR-007 を参照:
# docs/adr/007-background-job-library.md
#
class SendWelcomeEmailJob < ApplicationJob
  queue_as :default
 
  # リトライ設定: ADR-007のConsequences節に根拠が記載されている
  retry_on Net::SMTPError, wait: :polynomially_longer, attempts: 3
  discard_on ActiveJob::DeserializationError
 
  def perform(user_id)
    user = User.find(user_id)
    UserMailer.welcome(user).deliver_now
  end
end

# app/models/user.rb
#
# JWT認証の設計については ADR-012 を参照:
# docs/adr/012-jwt-refresh-token-auth.md
#
class User < ApplicationRecord
  has_secure_password
  has_many :refresh_tokens, dependent: :destroy
 
  # plan_typeのlegacy扱いについてはADR-001のContextを参照
  LEGACY_PLAN_TYPES = %w[legacy_v1 enterprise_old].freeze
 
  def legacy_plan?
    LEGACY_PLAN_TYPES.include?(plan_type)
  end
end

# config/initializers/cache_store.rb
# キャッシュストアの選定: ADR-002 参照
# docs/adr/002-redis-cache.md
# 選定理由: ElastiCache Redisを採用（Memcachedではなく）
Rails.application.configure do
  config.cache_store = :redis_cache_store, {
    url: ENV.fetch("REDIS_URL"),
    expires_in: 15.minutes
  }
end

# app/controllers/api/v1/base_controller.rb
# JWT認証の設計: ADR-012 参照
# docs/adr/012-jwt-refresh-token-auth.md
# 注意: アクセストークンはhttpOnly Cookie推奨（localStorageは禁止）
class Api::V1::BaseController < ApplicationController
  before_action :authenticate_via_jwt!
 
  private
 
  def authenticate_via_jwt!
    token = request.headers["Authorization"]&.split(" ")&.last
    # 実装の詳細はJwtServiceを参照
    payload = JwtService.decode(token)
    @current_user = User.find(payload[:user_id])
  rescue AuthError => e
    render json: { error: e.message }, status: :unauthorized
  end
end

# ADR-001: MySQL 5.7を採用している（遡及的記録）
 
## Status
Accepted（ただしADR-008で置き換えの議論中）
 
## Context
（当時の詳細は不明。以下は現在分かっている範囲）
2021年頃、データベース選定が行われた。
当時の担当者は既に退職しており、詳細な判断経緯は不明。
現在のコードベースからの推測: CRUD中心のシンプルなスキーマが多いため、
MySQLの標準的な機能で十分だったと思われる。
 
## Decision
MySQL 5.7を採用した。
 
## Consequences
（現時点での評価）
- 現在の要件（CRUD中心のSaaS）には十分に対応できている
- 位置情報機能の追加要件（ADR-008参照）ではPostGISの優位性が明らか
- MySQL 5.7はEOLが近づいており、バージョンアップまたは移行が必要
 
## 注記
このADRは遡及的に作成されたものであり、当時の判断者・判断根拠が
完全には復元できていない。より詳細な経緯を知っている方はコメントで補足を。