Developer Experience — 開発者体験を科学する

# app/middleware/ttfc_tracker.rb
class TtfcTracker
  def initialize(app)
    @app = app
  end
 
  def call(env)
    request = ActionDispatch::Request.new(env)
    status, headers, response = @app.call(env)
 
    # APIエンドポイントのみ追跡
    if api_request?(request) && status.between?(200, 299)
      track_first_call(request, status)
    end
 
    [status, headers, response]
  end
 
  private
 
  def api_request?(request)
    request.path.start_with?("/api/v1/")
  end
 
  def track_first_call(request, status)
    api_key = request.headers["X-API-Key"]
    return unless api_key
 
    developer = Developer.find_by(api_key: api_key)
    return unless developer
    return if developer.first_call_at.present? # すでに記録済み
 
    ttfc_seconds = Time.current - developer.signed_up_at
    developer.update!(
      first_call_at: Time.current,
      ttfc_seconds: ttfc_seconds.to_i,
      first_call_endpoint: request.path,
      first_call_status: status
    )
 
    # 分析用イベントを発火
    DxMetricsService.record_ttfc(
      developer_id: developer.id,
      ttfc_seconds: ttfc_seconds.to_i,
      endpoint: request.path,
      sdk_version: request.headers["X-SDK-Version"]
    )
 
    Rails.logger.info(
      "[TTFC] developer=#{developer.id} " \
      "ttfc=#{ttfc_seconds.to_i}s " \
      "endpoint=#{request.path}"
    )
  end
end

# config/application.rb
module ArclightApi
  class Application < Rails::Application
    config.middleware.use TtfcTracker
  end
end

# app/services/dx_metrics_service.rb
class DxMetricsService
  # TTFC（初回APIコール到達時間）を記録
  def self.record_ttfc(developer_id:, ttfc_seconds:, endpoint:, sdk_version: nil)
    DxMetric.create!(
      developer_id: developer_id,
      metric_type: "ttfc",
      value_seconds: ttfc_seconds,
      metadata: {
        endpoint: endpoint,
        sdk_version: sdk_version
      }
    )
 
    # アラート: TTFCが1時間を超えた場合はFDEに通知
    if ttfc_seconds > 3600
      notify_fde_team(
        developer_id: developer_id,
        message: "TTFCが#{ttfc_seconds / 60}分です。オンボーディングに問題がある可能性があります"
      )
    end
  end
 
  # 週次DXレポートを生成
  def self.weekly_report
    metrics = DxMetric.where(metric_type: "ttfc", created_at: 1.week.ago..)
    values = metrics.pluck(:value_seconds)
 
    {
      total_new_developers: metrics.count,
      median_ttfc_seconds: median(values),
      under_30min_rate: metrics.where("value_seconds < ?", 1800).count.to_f / [metrics.count, 1].max
    }
  end
 
  private_class_method def self.notify_fde_team(developer_id:, message:)
    SlackNotifier.post(channel: "#fde-alerts", text: "DXアラート｜開発者: #{developer_id}｜#{message}")
  end
end

# app/services/dora_metrics_collector.rb
class DoraMetricsCollector
  # デプロイ記録
  def self.record_deployment(version:, deployed_by:, environment: "production")
    Deployment.create!(
      version: version, deployed_by: deployed_by,
      environment: environment, deployed_at: Time.current
    )
  end
 
  # 変更障害率（デプロイのうち障害を起こした割合）
  def self.change_failure_rate(period: 30.days)
    deploys = Deployment.where(deployed_at: period.ago..)
    return 0.0 if deploys.count.zero?
 
    (deploys.where(caused_incident: true).count.to_f / deploys.count * 100).round(1)
  end
 
  # MTTR（平均復旧時間）
  def self.mean_time_to_recovery(period: 30.days)
    incidents = Incident.resolved.where(created_at: period.ago..)
    return 0 if incidents.empty?
 
    incidents.sum { |i| (i.resolved_at - i.created_at).to_i } / incidents.count
  end
end

# app/services/devex_survey.rb
class DevexSurvey
  QUESTIONS = {
    feedback_loops: [
      { id: "fl_1", text: "CIの実行結果を待つ時間は適切ですか？", scale: 1..5 },
      { id: "fl_2", text: "APIの動作確認は素早くできますか？", scale: 1..5 },
      { id: "fl_3", text: "エラーメッセージから原因を特定できますか？", scale: 1..5 }
    ],
    cognitive_load: [
      { id: "cl_1", text: "ドキュメントは最新で正確ですか？", scale: 1..5 },
      { id: "cl_2", text: "SDKのAPIは直感的に理解できますか？", scale: 1..5 },
      { id: "cl_3", text: "初めて使う機能でも迷わず実装できますか？", scale: 1..5 }
    ],
    flow_state: [
      { id: "fs_1", text: "集中作業の時間を十分確保できていますか？", scale: 1..5 },
      { id: "fs_2", text: "必要な情報にすぐアクセスできますか？", scale: 1..5 },
      { id: "fs_3", text: "作業の中断は少ないですか？", scale: 1..5 }
    ]
  }.freeze
 
  # DXI（Developer Experience Index）を算出
  def self.calculate_dxi(responses)
    dimension_scores = QUESTIONS.keys.map do |dimension|
      question_ids = QUESTIONS[dimension].map { |q| q[:id] }
      answers = responses.select { |r| question_ids.include?(r[:question_id]) }
 
      next 0 if answers.empty?
 
      avg = answers.sum { |a| a[:score] }.to_f / answers.size
      [dimension, avg]
    end.to_h
 
    # 3次元の加重平均でDXIを算出（各次元を100点満点に変換）
    total = dimension_scores.values.sum { |v| (v / 5.0) * 100 }
    dxi = (total / dimension_scores.size).round(1)
 
    {
      dxi: dxi,
      dimensions: dimension_scores,
      survey_date: Time.current
    }
  end
end

# 悪い例 — 前提条件が不明で、そのままでは動かない
# client = ArclightAI::Client.new
# response = client.analyze(data)
# puts response.result
 
# 良い例 — 環境変数の設定から結果の確認まで完結
# 1. 環境変数を設定
# export ARCLIGHT_API_KEY="your-api-key-here"
 
# 2. Gemfileに追加
# gem "arclight_ai", "~> 2.0"
 
# 3. 実行可能なコード
require "arclight_ai"
 
client = ArclightAI::Client.new(
  api_key: ENV.fetch("ARCLIGHT_API_KEY")
)
 
# テキスト分析を実行
response = client.analyze(
  text: "このプロダクトは素晴らしい品質です",
  model: "sentiment-v2",
  language: "ja"
)
 
# 結果を確認
puts "感情スコア: #{response.sentiment_score}"
puts "信頼度: #{response.confidence}"
puts "ラベル: #{response.label}"
# => 感情スコア: 0.92
# => 信頼度: 0.87
# => ラベル: positive

# app/middleware/dx_friendly_errors.rb
class DxFriendlyErrors
  ERROR_GUIDES = {
    "authentication_failed" => {
      message: "APIキーが無効または期限切れです",
      hint: "ダッシュボードでAPIキーを確認してください",
      docs_url: "https://docs.arclight.ai/auth/api-keys",
      status: 401
    },
    "rate_limit_exceeded" => {
      message: "レート制限に到達しました",
      hint: "現在のプランでは1分あたり60リクエストが上限です。" \
            "プランのアップグレードで上限を引き上げられます",
      docs_url: "https://docs.arclight.ai/rate-limits",
      status: 429
    },
    "invalid_model" => {
      message: "指定されたモデルが見つかりません",
      hint: "利用可能なモデル一覧: sentiment-v2, ner-v3, summarize-v1",
      docs_url: "https://docs.arclight.ai/models",
      status: 400
    }
  }.freeze
 
  def initialize(app)
    @app = app
  end
 
  def call(env)
    status, headers, response = @app.call(env)
 
    if status >= 400 && api_request?(env)
      error_code = extract_error_code(response)
 
      if (guide = ERROR_GUIDES[error_code])
        enhanced = {
          error: { code: error_code, message: guide[:message],
                   hint: guide[:hint], docs: guide[:docs_url] }
        }
        return [guide[:status], headers, [JSON.generate(enhanced)]]
      end
    end
 
    [status, headers, response]
  end
end

# Gemfileに追加
# gem "aws-xray-sdk", "~> 0.16"
 
# config/initializers/xray.rb
require "aws-xray-sdk"
 
XRay.recorder.configure(
  sampling: true,
  name: "arclight-api",
  daemon_address: "127.0.0.1:2000",
  context_missing: "LOG_ERROR",
  plugins: [:ec2, :ecs]
)
 
# config/application.rb
config.middleware.use XRay::Rack::Middleware

# app/controllers/api/v1/analysis_controller.rb
class Api::V1::AnalysisController < Api::BaseController
  def create
    XRay.recorder.capture("analysis.validate") do
      validate_params!
    end
 
    result = XRay.recorder.capture("analysis.process") do |subsegment|
      subsegment.annotations[:model] = params[:model]
      subsegment.annotations[:developer_id] = current_developer.id
 
      AnalysisService.run(
        text: params[:text],
        model: params[:model],
        language: params[:language]
      )
    end
 
    XRay.recorder.capture("analysis.format_response") do
      render json: {
        sentiment_score: result.score,
        confidence: result.confidence,
        label: result.label,
        processing_time_ms: result.processing_time_ms
      }
    end
  end
 
  private
 
  def validate_params!
    raise Api::ValidationError, "textは必須です" if params[:text].blank?
    raise Api::ValidationError, "modelは必須です" if params[:model].blank?
 
    unless AnalysisService::AVAILABLE_MODELS.include?(params[:model])
      raise Api::ValidationError,
            "無効なモデル: #{params[:model]}。" \
            "利用可能: #{AnalysisService::AVAILABLE_MODELS.join(', ')}"
    end
  end
end

# app/services/dx_dashboard_service.rb
class DxDashboardService
  def self.summary(period: 30.days)
    {
      ttfc: ttfc_summary(period),
      dora: dora_summary(period),
      dxi: latest_dxi,
      developer_health: developer_health(period)
    }
  end
 
  def self.ttfc_summary(period)
    metrics = DxMetric.where(metric_type: "ttfc", created_at: period.ago..)
    values = metrics.pluck(:value_seconds)
 
    {
      median_minutes: (median(values) / 60.0).round(1),
      under_30min_rate: safe_rate(metrics.where("value_seconds < ?", 1800).count, metrics.count)
    }
  end
 
  def self.dora_summary(period)
    {
      deploy_frequency: Deployment.where(deployed_at: period.ago..).count,
      change_failure_rate: DoraMetricsCollector.change_failure_rate(period: period),
      mttr_minutes: (DoraMetricsCollector.mean_time_to_recovery(period: period) / 60.0).round(1)
    }
  end
 
  def self.developer_health(period)
    developers = Developer.where(signed_up_at: period.ago..)
    active = developers.joins(:api_calls)
                       .where(api_calls: { created_at: 7.days.ago.. })
                       .distinct
 
    { total_new: developers.count, active: active.count,
      activation_rate: safe_rate(active.count, developers.count) }
  end
end