copy_tuner_client 1.2.0 → 1.2.1

data/skills/copy-tuner-to-locales-migrate-prefix/SKILL.md

@@ -0,0 +1,265 @@
+---
+name: copy-tuner-to-locales-migrate-prefix
+description: >-
+  copy_tuner（CopyTuner / copy_tuner_client）で集中管理している i18n データを、prefix（正規表現）単位で
+  Rails 標準の config/locales（YAML）管理へ段階移行するスキル。gem の local_first_key_regexp を使い、
+  1 回につき 1 prefix をローカルへ寄せて regexp に積み上げる。全 prefix 完了後の gem 撤去は
+  copy-tuner-to-locales-cleanup スキルで行う。
+disable-model-invocation: true
+---
+
+# copy_tuner → config/locales 段階移行スキル（prefix 単位）
+
+copy_tuner（`copy_tuner_client` gem）で集中管理している i18n データを、**prefix（正規表現）単位で**少しずつ
+Rails 標準の `config/locales` 配下の YAML 管理へ移していくためのワークフロー。**1 回の実行で 1 prefix だけ**
+移行し、これを繰り返す。全 prefix の移行が完了したら `copy-tuner-to-locales-cleanup` スキルで gem・CI・
+deploy・docs・MCP をまとめて撤去する。
+
+このスキルは**特定のリポジトリに依存しない**。project_id・ファイルパス・CI 構成はプロジェクトごとに異なるので、
+固有値を覚えるのではなく**毎サイクル、自分が編集する箇所（initializer の regexp・config/locales）を探索して
+見つけ直す**（手順 2）。種別ごとの典型例は `references/example-touchpoints.md` を参照。
+
+## なぜ prefix 単位で段階移行するのか
+
+一発で全 i18n をローカル化すると、移行漏れ（ローカル YAML に書き忘れたキー）が**一斉に未訳化**して事故になる。
+prefix 単位なら、移した範囲だけが影響を受け、移行漏れはその範囲の未訳として小さく顕在化する。安全な prefix から
+順に潰していける。
+
+### 前提となる gem 機能（local_first_key_regexp）
+
+[copy-tuner-ruby-client #110](https://github.com/SonicGarden/copy-tuner-ruby-client/pull/110) で追加された
+`local_first_key_regexp` を使う。挙動の要点（`references/local-first-regexp.md` に詳細）:
+
+- **locale を除いたキー**（`views.foo` 等）が regexp にマッチすると、`I18nBackend#lookup` は CopyTuner
+  キャッシュもアップロードキューも**一切見ず**、Rails 標準バックエンド（`I18n::Backend::Simple`）に委譲して
+  ローカル YAML だけを引く。これを**完全分離**と呼ぶ。
+- 完全分離なので、**マッチキーがローカル YAML に無ければ即 `nil`（未訳）**。CopyTuner へフォールバックしない。
+  これが「移行漏れを未訳として顕在化させる」仕組み。
+- マッチしないキーは従来どおり CopyTuner キャッシュ優先 → 無ければローカル、という動作のまま。
+- regexp は**単一**（配列非対応）。複数 prefix は `Regexp.union` で 1 本に積み上げる。
+
+gem を残したまま regexp に prefix を足していくだけなので、移行途中でも CopyTuner と config/locales が安全に
+共存する。
+
+## ワークフロー（1 サイクル = 1 prefix）
+
+### 1. gem 前提確認
+
+`local_first_key_regexp` が使えるバージョンの `copy_tuner_client` が入っているか確認する。
+
+```bash
+bin/rails runner 'p CopyTunerClient.configuration.respond_to?(:local_first_key_regexp)'
+```
+
+`true` でなければこのスキルは使えない。gem を PR #110 が入ったバージョンへ上げてから（`Gemfile` 更新 →
+`bundle update copy_tuner_client`）出直す。**バージョンアップはこのスキルの前提条件**であり、ここで止める。
+
+### 2. 編集対象の場所を確認（毎サイクル）
+
+このスキルが**実際に編集するのは次の箇所だけ**なので、毎サイクル開始時にこれらの場所を軽く確認する。
+grep 結果はセッションをまたいで残らない（複数セッションに分割して進める前提）ため、「初回に把握したはず」に
+頼らず毎回見つけ直す。`vendor/`・`tmp/`・`node_modules/`・`Gemfile.lock` は除外する。
+
+```bash
+# 毎サイクル触る: initializer の local_first_key_regexp と config/locales の採番慣習
+git grep -nI 'local_first_key_regexp' -- ':!vendor' ':!tmp' ':!node_modules'
+ls config/locales
+
+# 初回だけ触る（手順 9・10 用）: CI の export ステップと i18n 方針ドキュメント
+git grep -nI -e 'copy_tuner:export' -e 'CopyTuner' -- '.github/' 'doc/' 'CLAUDE.md'
+```
+
+- 手順 6・7 で毎回触る **initializer の `local_first_key_regexp`** の位置と、**`config/locales/`** の採番慣習
+  （例: `00_`・`10_`）を確認する。
+- 手順 9（CI の export ステップ削除）・手順 10（方針ドキュメントの中間状態更新）で**初回だけ**触る箇所も
+  ここで場所だけ押さえる。
+
+#### 2-1. （初回のみ）既存 locales を `0000_original_` プレフィックスへリネーム
+
+このスキルの分割方針（手順 6）は、**既存 `config/locales` をロード最先頭に固定し、移行で足すファイルを後ろに
+置いて Rails i18n の後勝ちで上書きする**ことを前提にする。そのため**初回サイクルの最初に一度だけ**、既存の
+locales ファイルを `0000_original_` プレフィックスへリネームする。
+
+```bash
+# 例（既存ファイル名に合わせて読み替える）:
+git mv config/locales/00_ja.yml         config/locales/0000_original_ja.yml
+git mv config/locales/00_devise.ja.yml  config/locales/0000_original_devise.ja.yml
+git mv config/locales/10_app.yml        config/locales/0000_original_app.yml
+```
+
+- **初回判定**: `ls config/locales` に `0000_original_` で始まるファイルが既にあれば、このリネームは済んでいる
+  のでスキップする（2 サイクル目以降は常にスキップ）。
+- `0000_` は数値プレフィックスで必ず最先頭ロードになる。以降 migrate で足すファイルは `0010_` 以降に置き
+  （手順 6）、ロード順で後勝ち＝オリジナルを上書きする。`Regexp.union` の積み上げ（手順 7）と合わせ、
+  「重複キーは export 側を正とする」を**手作業マージなしで構造的に保証**するのがこの固定の狙い。
+- このリネームは**ファイルの中身を一切変えない**（純粋にロード順を確定するだけ）。リネーム後に rspec を流し、
+  `translation missing` が**増えていない**ことだけ確認する。
+
+gem・CI の deploy ワークフロー・deploy フック・MCP 設定の**撤去**は `copy-tuner-to-locales-cleanup` の仕事で、
+cleanup は自前で touchpoint を grep し直す。**このスキルでそれらを棚卸し・編集する必要はない**。種別ごとの
+典型的な在処は `references/example-touchpoints.md` を参照。
+
+### 3. 残 prefix の把握
+
+全件を export して俯瞰し、移行済み（現在の `local_first_key_regexp` がマッチする）prefix と未移行 prefix を
+一覧化する。export は一時ファイルへ書く（`tmp/` 等の捨て場）。
+
+```bash
+bundle exec rake copy_tuner:export[tmp/copy_tuner_all.yml]
+```
+
+このタスクは内部で `CopyTunerClient.cache.sync` を呼び、サーバから最新を取得してから全 blurb を書き出す
+（全件取得の唯一確実な手段。詳細は `references/export-and-split.md`）。出力 YAML のトップセクションを眺めて、
+どの prefix が残っているかを確認する。
+
+### 4. 対象 prefix の選定
+
+残 prefix から **1 つ**選ぶ。影響が小さく構造が安定したものから始め、最後に大物（`views`）を回す:
+
+1. **gem 由来（最安全・先行）**: `devise` / `good_job` / `ice_cube` / `restrict_dependent_destroy` 等。
+   値が安定しアプリ実装に依存しにくい。
+2. **Rails 標準フォーマット**: `date` / `time` / `datetime` / `number` / `helpers` / `text`。
+   ただし**非表現値**（配列・シンボル・数値）の注意あり（手順 6）。
+3. **バリデーションメッセージ**: `activerecord.errors` / `activemodel.errors`。テストで検知しやすい。
+4. **モデル名・カラム名**: `activerecord.models` / `activerecord.attributes` / `activemodel.attributes` /
+   `activerecord.enums`。プロジェクトの i18n 方針で「新規キー登録の例外」とされていることが多い
+   （プロジェクトの i18n 方針ドキュメントでそう規定されていることが多い）。**全撤去がゴールなのでこの prefix も最終的に移行対象に含める**。
+   例外規定の撤廃は cleanup で行う。
+5. **画面テキスト（最大・最後）**: `views` / `text`。量が多く画面影響が大きいので最後に回し、画面確認の比重を
+   上げる。1 回が大きすぎるなら `views.<controller>.` の 2 階層目で更に刻んでよい（regexp を `\Aviews\.users\.`
+   のように書ける）。
+
+### 5. 不正キーの事前チェック（関門）
+
+export 済み YAML を config/locales に持ち込む前に、不正キーがないことを確認する。
+
+```bash
+bundle exec rake copy_tuner:detect_conflict_keys
+bundle exec rake copy_tuner:detect_html_incompatible_keys
+```
+
+- `detect_conflict_keys` … キー衝突。`foo` という値キーと `foo.bar` というネストキーが同居すると YAML へ
+  正しく展開できない。
+- `detect_html_incompatible_keys` … `html_escape` 有効環境で `.html` 慣習と矛盾する値など。
+
+これらのタスクは**全キー対象**で prefix 絞り込み引数は無い。**出力のうち今回の対象 prefix に該当する行だけ**を
+関門にする（対象外 prefix の不正キーは、その prefix を移す回まで保留してよい）。該当があれば**そのまま
+config/locales に持ち込むと壊れる**ので、一覧をユーザーに報告し、copy_tuner の管理画面側で修正してもらってから
+進む。（タスクが見つからない場合は `bundle exec rake -T copy_tuner` で確認。）
+
+### 6. 対象 prefix を config/locales へ配置（スクリプトで一気通貫）
+
+配置・移行漏れ検証・オリジナルからの削除は決定論的なので、手作業でなく `scripts/migrate_prefix.rb` を
+`bin/rails runner` で実行する。**1 本のスクリプトで配置 → 静的ガード → 移行漏れ検証 → オリジナル削除まで**
+一気通貫で行い、漏れが 1 件でもあれば**オリジナルを一切変更せず中断**する。
+
+```bash
+bin/rails runner .claude/skills/copy-tuner-to-locales-migrate-prefix/scripts/migrate_prefix.rb \
+  -- --prefix date --export tmp/copy_tuner_all.yml --out config/locales/0010_date.yml
+```
+
+- `--prefix` … 今回移行する prefix（ドット区切り。`date` / `activerecord.attributes` 等）。
+- `--export` … 手順 3 で出した全件 export YAML。
+- `--out` … 移行分の配置先。**オリジナル（`0000_original_*.yml`）より後にロードされる採番**（`0010_` 以降）。
+  採番慣習は手順 2 で確認したものに合わせる。
+- `--regexp` … 省略時は prefix から `/\A<prefix>\./` を自動生成（手順 7 の `local_first_key_regexp` と整合）。
+  2 階層目で刻む（`views.users` 等）ときだけ明示する。
+- `--locales` … 省略時は `I18n.available_locales`（`default_locale` を先頭）を対象 locale にする。`--locales ja,en`
+  のように明示すると上書きできる（fixture を使った検証用）。スクリプトは対象 locale すべてを横断して配置・
+  検証・削除する（単一ロケール運用でも、将来 locale を足しても自動追従する）。
+
+スクリプトの動作（詳細・設計判断は `references/export-and-split.md`）:
+
+配置・検証・削除は対象 locale（`--locales`／既定は `I18n.available_locales`）ごとに独立して行い、`--out` には
+全 locale のサブツリー（`ja:` / `en:` …）を書き出す。あるロケールに当該 prefix のキーが無ければ warn して
+そのロケールはスキップする。
+
+1. **配置**: オリジナル全ファイルから対象 prefix サブツリーを抽出し（ファイル名昇順＝ロード順で deep merge）、
+   export サブツリーを**その上に deep merge**（String blurb は export 勝ち）、最後に**オリジナル由来の非表現値
+   （配列・シンボル・数値・真偽値）を再適用**して `--out` へ書き出す（`deep_merge(deep_merge(orig, exp), non_blurb)`）。
+   「export を正とする」を満たしつつ、**非表現値は orig 値が必ず勝つ**（export 側に壊れた非表現値が出ても置換
+   されない。後述）。
+2. **静的ガード**: YAML ラウンドトリップ一致・`--out` が `config/locales` 配下の `.yml`（次回起動の i18n glob で
+   ロードされる場所）・全 leaf キーが regexp にマッチ、を確認（採番ミス・regexp 不一致・YAML 崩れの早期検出）。
+3. **移行漏れ検証**: オリジナル削除を**メモリ上でシミュレート**し、削除後ツリーを素の `I18n::Backend::Simple` に
+   載せて対象 prefix の全キーを実 lookup。`translation missing` になるキーがあれば漏れ。
+4. **ゲート**: 漏れゼロのときだけオリジナルから該当サブツリーを削除（空親も刈る）。漏れがあれば中断。
+
+**非表現値が必ず orig 値で残る**: copy_tuner は flat な文字列 blurb しか持てないため、配列・シンボル・数値・
+真偽値（`date.order` の `:year`、`date.*_names`、`number.*.precision`／`*.significant` 等）は export に出てこない
+／壊れて（文字列化して）出てくる可能性がある。スクリプトは export を上書きした**後に**、オリジナル由来の
+非表現値（非 String leaf）を再適用するので、**export 側に壊れた値が出ても orig の正値が置換勝ちする**。同じ
+prefix 内で `date.formats`（文字列・export 勝ち）と `date.order`（シンボル配列・orig 勝ち）が住み分く。現スキルが
+以前使っていた `0005_rails_non_blurb.yml` への別隔離は**不要**（このスクリプトに吸収済み）。
+
+> NOTE: 削除は手順 8 ではなく**このスクリプト内で**完結する（移行漏れ検証を通った場合のみ）。オリジナルを
+> 残したまま検証しても、オリジナルが漏れを埋めてしまい未訳検知が無意味になるため、検証と削除を同一スクリプトに
+> 束ねている。スクリプトが中断した場合は `--out` のファイルだけが残る（オリジナルは無傷）ので、原因を直して
+> 再実行するか `--out` を消してやり直す。
+
+### 7. local_first_key_regexp に prefix を追加
+
+initializer（`config/initializers/copy_tuner.rb` 等）の `CopyTunerClient.configure` ブロックで、
+`local_first_key_regexp` を `Regexp.union` で組み直し、今回の prefix を 1 本足す。
+
+```ruby
+config.local_first_key_regexp = Regexp.union(
+  /\Adevise\./,
+  /\Aice_cube\./,
+  /\Aviews\./,            # ← 今回追加した prefix
+)
+```
+
+**必ず `\A` でアンカーする**（`views` が `reviews` に部分マッチする事故を防ぐ。キーは locale 除去後なので
+`\A` 起点で良い）。詳細・なぜ単一 Regexp なのかは `references/local-first-regexp.md`。
+
+### 8. 検証（任意・ユーザー判断）
+
+手順 6 のスクリプトが**移行漏れ（削除後に未訳化するキー）がゼロであることを機械的に確認した上で削除**まで
+済ませている（メモリ上で削除をシミュレートし、素の `I18n::Backend::Simple` で対象 prefix の全キーを実 lookup）。
+そのためスキルとしての rspec/画面確認は**必須にしない**。すべて git 管理下なので、問題があれば戻せる。
+
+ただしスクリプト内の検証は**静的キー集合とロード経路**までしか見ない。次の**実行時コンテキスト依存**の範囲は
+カバーしないので、必要に応じてユーザー判断で確認する:
+
+- lazy lookup `t('.key')` … 実際の controller/view コンテキストでフルキーが決まる。
+- 動的キー `t("views.#{type}.title")` … 静的に列挙できないキー。
+- `_html` の表示崩れ・補間 `%{...}` … lookup 成功と表示の正しさは別。
+
+確認したい場合は rspec（`docker compose up -d db` → `bundle exec rspec`）や主要画面で `translation missing` が
+出ないか見る。i18n 参照パターンの確認例は `references/verification-per-prefix.md`。
+
+> NOTE: regexp 追加（手順 7）後にスクリプトの regexp 引数と `local_first_key_regexp` がずれていないか、
+> `bin/rails runner 'p CopyTunerClient.configuration.local_first_key?("<prefix>.foo")'` が `true`、隣接キー
+> （`reviews.*` 等）が `false` になることを確認しておくとよい。
+
+### 9. （初回のみ）CI の Export ステップを削除
+
+CI で copy_tuner を export しているステップ（テストワークフロー内で `bin/rake copy_tuner:export` を走らせる類）
+は、**テスト起動前にローカルキャッシュを温める保険**にすぎない。
+このステップを削除すると、test 環境は initializer 起動時の `cache.download`（CopyTuner サーバから都度取得）
+だけになり、**本番と同じ挙動**になる。未移行 prefix も引き続きサーバから解決できるので、移行途中に消しても安全。
+
+> WARNING: `config.disable_test_translation = true` は**入れない**こと。入れると test で CopyTuner DL が
+> 止まり、未移行 prefix が一斉に未訳化する。Export ステップ（保険）だけを消すのが正しい。
+
+### 10. ドキュメントの中間状態を更新
+
+i18n 方針ドキュメント（`doc/` 等）が「copy_tuner で管理／config/locales は使わない」のまま残ると、移行途中で
+他の作業者や AI が「新規キーを copy_tuner と locales のどちらに足すか」を誤判断する。**移行中であることと、
+現在ローカル化済みの prefix を明記する**。中間状態テンプレ文は `references/example-touchpoints.md` にある。
+prefix を増やすたびに、列挙も更新する。
+
+### 11. 残 prefix を報告
+
+移行済み prefix・残 prefix の一覧と、現在の `local_first_key_regexp` を報告して 1 サイクル終了。
+残 prefix があれば次サイクルでこのスキルを再実行する。全 prefix が移行済みになったら
+`copy-tuner-to-locales-cleanup` スキルへ進む。
+
+## 1 サイクル完了の目安
+
+- 手順 6 のスクリプトが**移行漏れゼロを確認して正常終了**し、`--out`（`0010_` 以降）に対象 prefix が配置され、
+  `0000_original_*.yml` から該当サブツリーが削除されている（非表現値は `--out` 側に保持済み）。
+- `local_first_key_regexp` に対象 prefix が `\A` アンカー付きで追加されている（手順 7）。
+- 中間状態ドキュメントの「ローカル化済み prefix」が更新されている（手順 10）。
+- （任意）rspec/画面で `translation missing` が出ないことをユーザー判断で確認（手順 8）。

data/skills/copy-tuner-to-locales-migrate-prefix/references/example-touchpoints.md

@@ -0,0 +1,126 @@
+# 典型的な touchpoint（種別ごと）
+
+copy_tuner（`copy_tuner_client` gem）を使う Rails アプリで、移行・撤去のときに触ることになる touchpoint を
+種別ごとに整理したもの。**探索クエリを投げるとこういう種類の結果が返る**というサンプルとして読む。値やパスは
+プロジェクトごとに違うので、これを暗記せず、各スキルの探索手順を必ず自分で走らせて発見すること
+（migrate は手順 2、cleanup は手順 1）。
+
+各 touchpoint に、どちらのスキルで触るかの印を付けた:
+
+- **[migrate]** = `copy-tuner-to-locales-migrate-prefix`（このスキル）で触る。prefix 移行のたびに編集。
+  migrate の手順 2 で見つけ直すのはこの印の箇所だけ。
+- **[cleanup]** = `copy-tuner-to-locales-cleanup`（全 prefix 完了後）で触る。gem・CI・deploy・docs・MCP 撤去。
+  撤去対象は cleanup の手順 1 で自前に grep し直す（migrate では棚卸ししない）。
+
+## copy_tuner の典型的な touchpoint（種別ごと）
+
+### gem 依存 — [cleanup]
+
+```ruby
+# Gemfile
+gem 'copy_tuner_client'                                              # 全環境
+gem 'copy_tuner_client-mcp', github: '<org>/copy_tuner_client-mcp',
+    require: false                                                    # development, test
+```
+
+> 段階移行の前提として、`copy_tuner_client` は **PR #110（local_first_key_regexp）入りバージョン**へ
+> 上げておく必要がある（migrate スキル手順 1 で確認）。
+
+### 初期化子 — [migrate]（local_first_key_regexp を積み上げる中心）
+
+`config/initializers/copy_tuner.rb`（パスはプロジェクトにより異なる）:
+
+```ruby
+CopyTunerClient.configure do |config|
+  config.api_key = Rails.application.credentials.fetch(:copytuner_api_key) { ENV.fetch('COPYTUNER_API_KEY', 'dummy') }
+  config.project_id = <プロジェクトの project_id>
+  config.host = '<copy_tuner サーバの host>'
+  config.html_escape = true
+  config.locales = [:ja]
+  config.ignored_keys = %w[]
+  # 移行のたびにここへ prefix を足していく:
+  # config.local_first_key_regexp = Regexp.union(/\Adevise\./, /\Aviews\./, ...)
+end
+```
+
+→ `html_escape`（true 運用か）・運用ロケール（単一か複数か）という前提が分割・非表現値の判断に効くので、
+実プロジェクトの initializer で確認する。initializer 全体の削除は [cleanup]。
+
+> NOTE: `migrate_prefix.rb` は対象 locale を `I18n.available_locales`（既定。`--locales` で上書き可）から
+> 取るので、運用ロケールが将来 `[:ja, :en]` 等に増えても引数なしで全ロケールを自動処理する（特定ロケール
+> 決め打ちではない）。
+
+### 既存 locales — [migrate]（先頭固定リネーム → prefix サブツリーを後ろへ配置 → オリジナルから削除）
+
+移行前の既存ファイル（初回サイクルの手順 2-1 で `0000_original_` へリネームする）。実ファイル名はプロジェクト
+ごとに異なるので `ls config/locales` で確認して読み替える。典型的には次のような種類が並ぶ:
+
+- Rails 標準（date/time/number/errors/helpers）の YAML
+- devise 等の gem 由来 YAML
+- アプリ固有の `activerecord.enums` / `activerecord.attributes` 等を持つ YAML
+
+→ オリジナルを `0000_original_` で先頭固定し、移行分は `0010_` 以降に置く。重複キーはロード順の**後勝ちで
+export 側が勝つ**（手作業マージ不要）。prefix を移行するたびにオリジナルから該当サブツリーを削除し、残存＝
+未移行 prefix の進捗マーカーにする（最終的にオリジナルが空＝全移行完了）。
+
+→ Rails 標準フォーマットの **配列**（`date.abbr_day_names` 等）・`date.order` の `:year` 等の**シンボル配列**・
+`number.*.precision` 等の**非表現値**は copy_tuner で表現できず export に出てこないため、`date`/`number` を移行
+する回では手順 6 のスクリプトがオリジナル抽出分をベースに export を上書き（`orig_sub.deep_merge(exp_sub)`）して
+移行分（`0010_` 以降）の中へ**非表現値ごと取り込む**。別ファイルへの隔離は不要（詳細は
+`references/export-and-split.md`）。
+
+### CI — [migrate]（Export ステップのみ初回で削除） / [cleanup]（残り）
+
+- **CI の翻訳 export ステップ**（テストワークフロー内で `bin/rake copy_tuner:export` を走らせる類）…
+  「翻訳 DL 失敗でテストがコケないように」の保険。**[migrate] の初回で削除**（test が本番同等の
+  `cache.download` 挙動になる）。`disable_test_translation` は入れない。
+- **copy_tuner 専用の deploy ワークフロー**（main push で翻訳をデプロイする専用ファイル）…
+  **[cleanup] で丸ごと削除**。
+- **AI エージェント用ワークフローの `mcp__copy-tuner__*` allowedTools 許可** … **[cleanup] で削除**。
+
+### deploy / 起動スクリプト — [cleanup]
+
+- **deploy フック** … production 起動時に `bundle exec rake copy_tuner:deploy` を実行するブロック。削除。
+- **コンテナ起動スクリプト** … 起動時に `rake copy_tuner:export` を走らせるフォールバック。**gem 撤去後は
+  このタスク自体が消えて起動が `Don't know how to build task` で落ちる**ため、必ず削除する。取りこぼし注意。
+
+### 環境設定 — [cleanup] で確認
+
+`config/environments/production.rb` の `config.i18n.fallbacks = true` 等。標準バックエンドでも有効なので確認のみ。
+
+### ドキュメント / スキル / MCP — [migrate]（中間状態更新） / [cleanup]（最終化・撤去）
+
+- **i18n 方針ドキュメント**（`CLAUDE.md`・`doc/` 配下等）… 「copy_tuner サーバで i18n データを管理 /
+  config/locales 配下は利用しない / 新規キー登録は基本禁止」等の記述。**[migrate] で中間状態に更新**、
+  **[cleanup] で最終化**。上記を参照している他のドキュメント（`CLAUDE.md` 等）も連動。
+- **copy_tuner MCP 操作スキル**（`.claude/skills/` 配下）… **[cleanup] で無効化/削除**。
+- **補助ドキュメント** … 「多言語対応: copy_tuner サーバで i18n データを管理」のような記述を持つコマンド定義等。
+  **[cleanup] で修正**。
+- **`README.md`** … CopyTuner プロジェクトへのリンク。**[cleanup] で削除/修正**。
+- **`.mcp.json`** … copy-tuner MCP server 接続設定。**[cleanup] で削除**。
+
+## 規模感
+
+copy_tuner 側のキー数・export YAML の行数はプロジェクト次第だが、export YAML のトップには Rails i18n 慣習どおりの
+セクションが並ぶ: `activemodel.attributes` / `activerecord.{attributes,enums,models,errors}` / `views` / `text` /
+`helpers` / `date`/`time`/`datetime`/`number` / `devise` / `good_job` / `ice_cube` /
+`restrict_dependent_destroy` 等。これらのトップセクションが prefix 移行の基本粒度。`views` が最大になりやすいので
+最後に回す。
+
+## i18n 方針ドキュメント中間状態テンプレ（[migrate] 手順 10 で使う）
+
+移行中はこのような記述に置き換える。`<列挙>` は現在 `local_first_key_regexp` にマッチしている prefix に
+更新する（prefix を増やすたびに更新）。
+
+```markdown
+### 国際化（i18n）
+
+- **copy_tuner から config/locales へ段階移行中**
+- 以下の prefix は config/locales 管理へ移行済み（`local_first_key_regexp` にマッチ）: `<列挙: devise, ice_cube, views, ...>`
+- 上記以外の prefix はまだ copy_tuner サーバで管理
+- **新規キーの追加先**: 移行済み prefix のキーは config/locales へ。未移行 prefix のキーは従来どおり copy_tuner へ
+- 複数形化対応は不要（日本語環境）
+```
+
+> [cleanup] で全 prefix 完了後、この中間記述は「config/locales 管理。copy_tuner 廃止。新規キーは
+> config/locales へ。複数形化不要」に最終化する（モデル名・カラム名の例外規定も撤廃）。

data/skills/copy-tuner-to-locales-migrate-prefix/references/export-and-split.md

@@ -0,0 +1,126 @@
+# export と prefix サブツリーの抜き出し・YAML 分割
+
+SKILL.md 手順 3・6 の詳細。
+
+## rake copy_tuner:export の挙動
+
+```bash
+bundle exec rake copy_tuner:export[出力先パス]
+```
+
+- 引数を省略するとデフォルトで `config/locales/copy_tuner.yml` に書き出す。**段階移行では全件を一時ファイルへ
+  出して俯瞰・抜き出しの元データにする**ため、`tmp/copy_tuner_all.yml` のような捨て場を明示指定する。
+- 内部で `CopyTunerClient.cache.sync` を呼び、copy_tuner サーバから最新 blurb を取得してから書き出す。
+  ローカルのポーラーキャッシュ任せにせず必ずこのタスクを使うのは、同期済み・全件であることを保証するため。
+- blurb が一件もキャッシュできないと `No blurbs have been cached.` で失敗する。その場合は API key
+  （credentials または `COPYTUNER_API_KEY`）と project_id の設定、ネットワーク到達性を確認する。
+- 出力は単一の YAML で、トップに copy_tuner に登録された全ロケールのキー（`ja:`、複数運用なら `en:` 等も）が
+  並び、その下に blurb のドット区切りキーがネストした Hash に展開された形になる。
+
+## 出力 YAML の構造（典型）
+
+トップレベルロケール（複数運用なら `ja:` / `en:` …）の下に、Rails の i18n 慣習どおりのセクションがフラットに
+並ぶ。実際のプロジェクトではおおむね次のようなセクションが現れる:
+
+```
+ja:   # 複数ロケール運用なら en: 等も同じ構造で並ぶ
+  activemodel:
+    attributes:        # Form オブジェクトの属性名
+  activerecord:
+    attributes:        # モデル属性名（CSV ヘッダ・フォームラベル等）
+    enums:             # enum 値の表示名
+    models:            # モデルの human 名
+    errors:            # カスタムバリデーションメッセージ
+  views:               # 画面テキスト・ヘルプ文
+  text:                # 汎用ボタンテキスト等
+  helpers:             # submit ラベル等
+  date: / time: / datetime: / number:   # Rails 標準フォーマット
+  devise:              # gem 由来
+  good_job: / ice_cube: / restrict_dependent_destroy:  # gem 由来
+```
+
+このトップセクションの単位が、SKILL.md 手順 4 の「対象 prefix」の基本粒度になる。
+
+## 対象 prefix のサブツリーだけを抜き出す（スクリプトが担う）
+
+段階移行では**今回の prefix のサブツリーだけ**を config/locales へ持ち込む（全件は持ち込まない）。この抽出・
+配置・検証・削除は SKILL.md 手順 6 の `scripts/migrate_prefix.rb` が決定論的に行う。スクリプトの内部処理:
+
+- 全件 export YAML（`tmp/copy_tuner_all.yml`）から対象 prefix（例 `views`）以下を、対象 locale（`--locales`／
+  既定は `I18n.available_locales`）すべてのロケールキー（`ja:`、複数運用なら `en:` 等）を保ったまま切り出す。
+  他の prefix（まだ移行しないもの）は持ち込まない（引き続き CopyTuner から引かれる）。
+- 抜き出した leaf キーが手順 7 で `local_first_key_regexp` に足す prefix（`--regexp`／既定 `/\A<prefix>\./`）と
+  **一致しているか**を静的ガードで自動確認する（regexp がマッチするのにローカルに無い＝未訳を防ぐ）。
+
+## 分割の方針（配置先ファイル）
+
+スクリプトの `--out` は、**オリジナル（`0000_original_*.yml`）より後にロードされる採番**（`0010_` 以降）の
+ファイルにする。SKILL.md 手順 2-1 で既存 locales を `0000_original_` に固定済みなので、移行分を後ろに置けば
+Rails i18n の後勝ちで**重複キーは自動的に export 側が勝つ**（手作業マージ不要）。
+
+分割の目安（1 prefix ＝ 1 ファイルにすると、どの prefix を移行済みか／regexp と config/locales の対応が追いやすい）:
+
+| ファイル例 | 入れるセクション |
+|---|---|
+| `0000_original_*.yml`（既存・先頭固定） | 未移行 prefix の残り（移行のたびに該当 prefix を削除していく） |
+| `0020_activerecord.yml` | `activerecord.attributes` / `activerecord.models` / `activerecord.errors` |
+| `0030_activemodel.yml` | `activemodel.attributes` / `activemodel.errors` |
+| `0040_views.yml` | `views` / `text` |
+| `0050_gems.yml` | good_job / ice_cube / restrict_dependent_destroy / devise 等 |
+
+> 採番は目安。ポイントは **`0000_original_`（先頭）＜ 移行分 `0010_` 以降** のロード順を保つこと。
+> これにより重複キーは **export 側を正とする**が構造的に保証される（次節）。非表現値（date/number の配列・
+> シンボル・数値）は別ファイルに隔離せず、スクリプトが移行分（`0010_` 以降）の中へ取り込む（後述）。
+
+## 既存 locales との重複は後勝ちで解決し、オリジナルから削除する
+
+抜き出したサブツリーに、すでにオリジナル（`0000_original_*.yml`）に存在するキー（Rails 標準・devise・
+アプリ固有 enum 等）が含まれることがある。**手作業でのマージはしない。** スクリプトとロード順で解決する:
+
+- スクリプトは `orig_sub.deep_merge(exp_sub)`（オリジナル抽出分をベースに export で上書き）で `--out` を作る。
+  葉が両方にあれば export が勝ち、**「export を正とする」を満たす**。さらに `0000_` 先頭・`0010_` 後ロードの
+  Rails 後勝ちでも二重に保証される。
+- 配置・移行漏れ検証を通った後、スクリプトが**移行した prefix のサブツリーをオリジナルから削除する**
+  （空親も刈る）。残存内容が「未移行 prefix」を表す進捗マーカーになり、重複定義も消えて YAML がクリーンに保たれる。
+
+## copy_tuner で表現できない値（非表現値）の引き継ぎ
+
+copy_tuner は flat な文字列 blurb しか持てないため、次の値は export に出てこない／文字列化されて壊れる:
+
+- **配列**: `date.abbr_day_names` / `day_names` / `month_names` / `abbr_month_names` 等
+- **シンボル配列**: `date.order`（`:year` / `:month` / `:day`）等
+- **数値・真偽値**: `number.*.precision`（整数）/ `significant` / `strip_insignificant_zeros`（真偽値）等
+- **ハッシュ値**: 上記のように構造を持つ Rails 標準フォーマット群
+
+これらは基本 export に出てこず**オリジナルにしか無い**が、**壊れた形（文字列化された値、過去に管理画面で手動
+登録された値、将来の gem の型変換結果）で export に出てくる可能性**もある。スクリプトは 3 段の deep merge で
+これを守る:
+
+1. `orig_sub` をベースに
+2. export を上書き（String blurb は export 勝ち）
+3. 最後に**オリジナル由来の非表現値（非 String leaf）だけ**を再適用（`select_non_blurb(orig_sub)`）
+
+これにより、export に壊れた非表現値が出ても **3 段目で orig の正値が置換勝ちする**（deep merge は配列・スカラを
+右辺で置換するので、最後に来た orig 値が export の壊れた値を上書きする）。**非表現値は orig 値で `--out` に残る**。
+別ファイル（旧 `0005_rails_non_blurb.yml`）への隔離は**不要**。
+
+> 原則の住み分け: 「重複キーは export を正とする」は **copy_tuner で表現可能な String blurb にのみ**成り立つ。
+> 非表現値はそもそも copy_tuner に正しく存在しえない（gem の `store_item` が `respond_to?(:to_str)` で非文字列を
+> 弾く）ので、orig を勝たせるのが常に正しい。同じ `date` prefix 内で `date.formats`（文字列・export 勝ち）と
+> `date.order`（シンボル配列・orig 勝ち）が排他的に住み分く。2 原則は衝突しない。
+
+> なぜ隔離が要らないか: 隔離方式は「export 由来ファイルに非表現値を混ぜると壊れる」ことを避ける狙いだったが、
+> スクリプトは 3 段マージ（orig ベース → export 上書き → 非表現値の再適用）で非表現値の喪失・上書きを構造的に
+> 防ぎ、`--out` 単一ファイルに収める。削除も「漏れゼロを実 lookup で確認してから」スクリプトが行うので、
+> 非表現値を巻き添えで失う事故（prefix を丸ごと消す手作業ミス）も起きない。
+
+> 参考: gem 側の型変換は [copy-tuner-ruby-client#104](https://github.com/SonicGarden/copy-tuner-ruby-client/pull/104)
+> で `*.precision` → integer、`*.significant` → boolean 等が補われる。ただし**配列・シンボルは対象外**。いずれに
+> せよ 3 段目の非表現値再適用で orig 値が勝つため、coerce された値・壊れた値どちらが export に出ても安全。
+
+## html_escape 由来の値の扱い
+
+copy_tuner を `html_escape = true` で運用していた場合、export された値には HTML エスケープ前提の文字列や
+`*_html` キー慣習が含まれることがある。Rails 標準の i18n も `*_html` サフィックスのキーは自動で
+`html_safe` 扱いにするため、基本はそのまま移せる。ただし SKILL.md 手順 5 の `detect_html_incompatible_keys`
+で警告が出たキーは、移行前に copy_tuner 側で整理しておくこと（そのまま持ち込むと表示が壊れる）。

data/skills/copy-tuner-to-locales-migrate-prefix/references/local-first-regexp.md

@@ -0,0 +1,72 @@
+# local_first_key_regexp の使い方
+
+SKILL.md 手順 7 の詳細。prefix 単位移行の核心となる gem オプション。
+
+## 何をするオプションか
+
+[copy-tuner-ruby-client #110](https://github.com/SonicGarden/copy-tuner-ruby-client/pull/110) で
+`Configuration#local_first_key_regexp` が追加された。`I18nBackend#lookup` は次のように動く:
+
+```ruby
+# locale を除いたキー（例: "views.foo.bar"）が regexp にマッチしたら…
+if local_first_key?(key_without_locale)
+  return super   # ← I18n::Backend::Simple に委譲。CopyTuner キャッシュもアップロードキューも触らない
+end
+# マッチしなければ従来どおり CopyTuner キャッシュ優先 → 無ければ super
+```
+
+判定は `key_without_locale.to_s.match?(local_first_key_regexp)` の単純マッチ。
+
+## 完全分離の意味
+
+マッチキーは **CopyTuner を一切参照しない**。つまり:
+
+- ローカル YAML に値があればそれを返す。
+- ローカル YAML に**無ければ即 `nil`（未訳）**。CopyTuner へフォールバックしない。
+- 空キーのアップロードキュー投入もしない（`Cache#[]=` の単一関門で抑止）。
+- CopyRay のオーバーレイマーカー（`<!--COPYRAY key-->`）も注入されない（編集できないキーを編集可能と誤認
+  させないため）。
+
+この「無ければ未訳」の挙動こそが、**移行漏れ（ローカルへ書き忘れたキー）を未訳として顕在化させる**仕組み。
+だから移行のたびに `translation missing` チェック（SKILL.md 手順 8）が効く。
+
+## regexp は単一・配列非対応
+
+`local_first_key_regexp` は単一の `Regexp` を取る（`attr_accessor`、デフォルト `nil`）。**配列は渡せない**。
+複数 prefix を移行済みにするには **1 本の正規表現に積み上げる**。`Regexp.union` を使うのが安全:
+
+```ruby
+config.local_first_key_regexp = Regexp.union(
+  /\Adevise\./,
+  /\Aice_cube\./,
+  /\Arestrict_dependent_destroy\./,
+  /\Aviews\./,
+)
+# => /(?-mix:\Adevise\.)|(?-mix:\Aice_cube\.)|.../ 相当
+```
+
+`Regexp.union` はメタ文字のエスケープを自動でやり、要素を OR でつなぐので、prefix を 1 行ずつ足すだけで済む。
+手書きの `/\A(devise|ice_cube|...)\./` でも等価だが、union のほうが追記時のミスが少ない。
+
+## `\A` アンカー必須
+
+各 prefix は **`\A` で先頭アンカー**する。キーは locale 除去後なので `\A` 起点でよい。
+
+- `\A` 無しの `/views\./` は `reviews.foo` の `views.` 部分にもマッチしてしまう（部分マッチ事故）。
+- `\Aviews\.` なら `views.` で始まるキーだけにマッチする。
+- `views` 配下を更に刻むなら `\Aviews\.users\.` のように 2 階層目までアンカーできる。
+
+ドット `.` は正規表現のメタ文字なので、prefix 区切りのドットは `\.` とエスケープする
+（`/\Aviews\./`。`Regexp.union` に文字列を渡す場合は自動エスケープされるが、Regexp リテラルを渡すときは自分で
+書く）。
+
+## deprecated な exclude_key_regexp との違い
+
+| | `local_first_key_regexp` | `exclude_key_regexp`（非推奨） |
+|---|---|---|
+| 対象キー | locale を**除いた**キー（`views.foo`） | locale を**含む**キー（`ja.views.foo`） |
+| 作用タイミング | lookup（読み込み）時 | upload（送信）時 |
+| 効果 | ローカル YAML を優先（完全分離） | サーバへのアップロードを抑止するだけ |
+
+`exclude_key_regexp` は PR #110 で非推奨化された（設定すると `ActiveSupport::Deprecation` 警告が出る）。
+移行では使わない。もし既存設定に `exclude_key_regexp` があれば、cleanup スキルで gem ごと撤去される。