copy-tuner-ruby-client: Instructions file for Claude Code

CLAUDE.md

CopyTuner の Ruby クライアント gem。Rails アプリの I18n を CopyTuner サーバと同期する。

コマンド

• テスト: bundle exec rspec（単一ファイル: bundle exec rspec spec/copy_tuner_client/cache_spec.rb）
• 特定の Rails バージョンでテスト: BUNDLE_GEMFILE=gemfiles/8.0.gemfile bundle exec rspec
• Lint: bundle exec rubocop（sgcop を継承）
• フロントエンドビルド: pnpm build（開発: pnpm dev）
• フロントエンド Lint/Format: pnpm check（Biome）
• gem リリース: bundle exec rake build|install|release

Node.js / pnpm は mise（mise.toml）で管理。フロントエンドのツールチェーンは pnpm + Biome + Vite + TypeScript。

アーキテクチャ

Configuration#apply（lib/copy_tuner_client/configuration.rb）が全コンポーネントを組み立てる起点:

• Client — CopyTuner サーバ / S3 との HTTP 通信
• Cache — Mutex で保護された blurb ストア。Hash のように振る舞う。アップロードキューを管理
• I18nBackend — デフォルトの I18n backend を置き換える（I18n.backend = ...）。lookup で Cache を参照
• Poller / ProcessGuard — バックグラウンド同期スレッド
• Rack middleware RequestSync / CopyrayMiddleware — 開発環境でのリクエスト毎同期とオーバーレイ Rails 統合は engine.rb のイニシャライザ経由（ヘルパー/SimpleForm フック、アセット precompile）。

開発スタイル

• RED/TDD で進める: 実装前に必ず失敗するテストを書き、テストが RED になることを確認してから実装する
• 新機能・バグ修正ともに「テスト追加 → RED 確認 → 実装 → GREEN」のサイクルを守る
• テストを書かずに実装を先行させない
• コメントは WHY のみ日本語で書く: 識別子やコードから読み取れる WHAT は書かない （例外: RuboCop Style/Documentation 対応でクラス/モジュール直前に追加する一行の説明コメントは、名前だけでは把握しづらいクラスの役割を一目で示す目的のため、WHAT の説明も可）
• テストの describe / context / it の説明文は日本語で書く: 識別子（クラス名・メソッド名など）はそのまま

Gotchas

• フロントエンドは src/*.ts を編集する。app/assets/* は Vite のビルド成果物なので直接編集しない （vite.config.ts が src/main.ts → app/assets/javascripts/copytuner.js を出力）。
• local_first_key_regexp — locale を除いたキー対象・lookup 時に作用（ローカル YAML 優先）。 local_first キーのアップロード抑止は Cache#[]= に集約されている。
• poller スレッドの fork 対応は ForkHook（Process._fork に prepend）に集約する （fork の直前に Poller#stop で協調的に停止し、fork 後に親子の両方で張り直す。理由: fork 後の子に残る Thread オブジェクトの見え方（alive? / join の結果）はドキュメント化されていない CRuby の実装依存なので、 pid を記録して差分を見るような後始末には寄せない。子でも張り直すので、Puma の fork_worker のように worker が worker を fork する構成でもサーバ固有のフックなしで poller が立つ。 アプリケーションサーバごとのフック（ProcessGuard#register_*_hook）を増やす前にここで足りるか確認する）。 起動方法・モードごとにどのプロセスで poller が起動するかは docs/poller-startup.md に実測結果がある。
• Poller#poll は例外をスレッドの外へ漏らさない （Poller#stop は fork 経路から呼ばれ、Thread#join はスレッドの例外を再送出するため、漏らすと poller の失敗がアプリ側の fork を壊す）。
• アップロード抑止の新ルールは Cache#[]= に足す。I18nBackend の書き込み経路（lookup / default / store_item）ごとに個別ガードを足さない （理由: cache への書き込みは全経路が最終的に Cache#[]= を通る単一の関門。経路ごとにガードを足すと付け忘れの穴が生まれ、同じチェックが分散して保守負担になる。実際 local_first の抑止は当初 default 個別に足したが穴が残り、Cache#[]= への集約に作り直した）。