あなたはClaude Codeにサインインフォームへローディング状態を追加するよう依頼しました。ローディング状態は正しく動いています。しかしボタンの文言はいつの間にか「Sign in」から「Log in」に変わり、エラーメッセージはより親しみやすい表現になり、ある見出しは突然センテンスケースになっていました。誰もそんなことは頼んでいません。それでもすべてのテストは通過し、誰かが差分を一語一句読まない限り、そのままリリースされてしまいます。
この記事で扱うのは、承認済みの既存コピーがAIコーディングエージェントにいつの間にか言い換えられてしまうという特定の問題と、それを防ぐワークフローです。エージェントがハードコードかつキーなしで新規に作る文字列は別の問題で、AIコーディングツールがハードコード文字列を追加し続ける理由で扱っています。プロダクトコピーを一般にどこに置くべきかはアーキテクチャの問いで、コードネイティブなプロダクトコピーで扱っています。この記事は、あくまでインシデントそのものに絞ります。月曜の朝、文言が変わっていたのに、変えようと決めた人は誰もいなかった、という出来事です。globalize.nowはローカライズ機能を内蔵したコードネイティブなコピー管理システムで、このインシデントはその誕生理由のひとつです。
なぜAIコーディングエージェントはUIコピーを書き換えてしまうのか?
AIコーディングエージェントがUIコピーを書き換えてしまうのは、コンポーネント内に文章がそのまま存在しているように見えるからです。そのコピーがソースロケールファイル内でキーの裏側に置かれるようになれば、変更は他のタスクの副作用ではなく、明示的でレビュー可能な編集になります。
コンポーネントの中では、「Sign in」に特別な地位はありません。JSX属性の中の単なる文字列リテラルであり、classNameやtest idと区別がつきません。エージェントは、近くのコードを改善することが良い振る舞いとされる何百万もの差分で学習されており、モデルにとってラベルを「わかりやすく」することは、変数名を変更することと同じ行為なのです。そこには待ち構える型エラーもなく、失敗するテストもなく、言葉に所有者の注釈もありません。書き換えはエージェントにとって何のコストもかかりません。
変更はレビューもすり抜けます。理由は同じです。レビュアーが読むのはロジックだからです。文言の変更は、正当にローディング状態を扱っている差分の真ん中に紛れ込み、コンパイルも通り、レンダリングもされます。スナップショットテストが失敗しても、定石どおりスナップショットを更新するだけで、新しい文言があたかも承認済みであるかのように記録されてしまいます。
AGENTS.mdのようなルールファイルは、実際にそれを止められるのか?
エージェント用のルールファイルは頻度を下げますが、UIコピーを書き換え不能にするわけではありません。編集を可視化するのはアーキテクチャの役割です。
それでもルールファイルは用意しておきましょう。最も手軽なレイヤーで、30秒かける価値があるくらいにはよく効きます。以下のブロックは、AGENTS.md、CLAUDE.md、そしてCursorのルール(.cursorrulesまたは.cursor/rules/)で使えます。
## UI copy policy: do not modify user-facing text
- Never change user-visible strings (button labels, headings, empty states,
error messages, tooltips, placeholder text) unless the task explicitly
asks for a copy change.
- User-visible text lives in the source locale file (e.g. locales/en.json).
Reference it by key. Never inline a new user-facing string in a component.
- If a task needs new user-facing text, add a key to the source locale file,
reference it, and list the new key in your summary for copy review.
- Any diff to the source locale file is a copy change. Call it out
separately: it needs its own approval, apart from code review.
ここからは正直な話です。ルールはコンテキストにすぎず、コンテキストは競合します。長いタスクでは、その指示は何千トークンものコードの中の1行にすぎず、負けることがあります。コンパクションに消されたり、指示を一度も見ていないサブエージェントに無視されたり、周囲のファイルに強く根付いたパターンに引きずられたりするのです。さらに厄介なことに、ルールを破ったエージェントはそれを知らせてくれません。文言が変わったという通知は届かず、結果としてたまたま変わっていた差分が残るだけです。規約はチェックではありません。
だからこそルールファイルは第一層であり、それ単体で信頼すべきではない層でもあるのです。
コピーの編集を、静かなものではなく目に見える形にするにはどうすればよいか?
すべてのユーザー向け文字列をコンポーネントの外へ移し、ソースロケールファイル内のキーの裏側に置きましょう。そうすれば、文言を変えたいエージェントは、文言そのものが唯一の目的であるファイルを編集せざるを得なくなります。
ここが、ルールファイルでは担えないステップです。仕組みは単純です。コンポーネントが「Sign in」を直書きせずt('auth.signIn')を参照するようになると、2つのことが同時に変わります。まず、コンポーネントの差分にコピーが含まれなくなるので、ローディング状態を実装しているエージェントが、その場で書き換えられる文言がそもそもなくなります。そして、エージェントによる変更も人間による変更も、すべてのコピー変更が1つのファイルに集まり、変更された行こそが注目すべきイベントになります。ノイズに埋もれることはありません。ロケールファイルの差分は数秒で確認でき、望ましくない言い換えの取り消しも1行で済みます。
これで何が得られるのかを正確に言うと、エージェントがロケールファイルを編集できることに変わりはありません。ポイントは、文言に触れられなくなることではなく、触れることが副作用ではなくなり、読み取れてレビューできる行為になることです。差分で気づくのか、お客様からの指摘で気づくのか。その違いを生むのがこれです。
(デザインツールから同期するのではなく)コードベースを信頼できる唯一の情報源にすべき理由を詳しく論じたピラー記事が、コードネイティブなプロダクトコピーです。この記事で必要なのはその帰結のひとつだけです。キー化されたコピーは、ルールファイルを「お願い」から「検証できるもの」へと変えます。
レビューゲートとは具体的にどのようなものか?
ソースロケールファイルへのあらゆる差分をコピーの変更として扱い、文言の責任者にルーティングしましょう。
具体的には、ロケールのディレクトリをCODEOWNERSに登録し、そこに変更が入ったらコピーの担当者がレビュアーとして自動でアサインされるようにします。PRテンプレートには「このPRはユーザー向けの文言を変更していますか?それはタスクの目的でしたか?」という1行を加えます。さらに、エージェントが要約に変更したキーを列挙するというルールファイルの要件も維持します。守られていればレビューは一瞬で終わり、守られていなくてもCODEOWNERSのフックが拾ってくれます。
小規模なチームなら、これは聞こえるほど重くありません。ロケールの差分は短く、平易な言葉で読めます。「このボタンは今後Log inにしますか?」という判断は5秒で下せます。ただし、その問いが実際に担当者の目の前に届くことが前提で、それこそがこのゲートの役割のすべてです。
もしすでにエージェントがコピーを書き換えてしまっていたら?
まず承認済みの文言を復元し、その後で文字列をキー化して、次の書き換えが差分として現れるようにしましょう。
被害の洗い出しはgitの作業です。影響を受けたコンポーネントを、信頼できる最後のコミットと比較し、文字列リテラルだけを読みます。変わってしまった部分は元に戻してください。もし、どの文言が承認済みだったのか自信を持って言えない場合(ボタンは「Log in」、マーケティングページは「Sign in」で、どちらが正しいかを記録した成果物がない)、このインシデントが引き起こすより深刻な状態に陥っています。コピードリフトとは、ユーザーに見えるテキストが、承認済みのソースから、画面をまたぎ時間とともに乖離していく状態のことです。しかも、乖離する先となる信頼できる唯一の情報源自体が存在しません。この用語の意味、原因、下流への影響については、別の記事コピードリフトとはで解説しています。
次に、復元した文字列をキー化しましょう。まずはエージェントが手を加えた文字列から始めます。それらこそ、明らかに火線上にある文字列だからです。
ローカライゼーションはどこに関わってくるのか?
静かな書き換えは、1つの言語ではちょっとした迷惑事ですが、10の言語ではリスクになります。古い文言から派生したすべての翻訳が今や古くなり、誰も再翻訳が必要だと教えてくれないのです。
ここで、エージェントのインシデントはさらに深刻化します。言い換えられた英語をリリースすると、ドイツ語、日本語、スペイン語は古い文言のままです。今や画面間だけでなく、言語間でも表示が食い違うことになります。カタログの同期ずれはそれ自体が独立した障害パターンで、対処法も別にあります。詳しくは翻訳ファイルの同期ずれをご覧ください。
キー化されたコピーは、このループも閉じてくれます。ソース文字列の変更は目に見えるイベントになり、翻訳はそれに紐づくからです。いつの間にか動いてしまったリテラルとは違います。globalize.nowの設計思想はまさにここにあります。コピードリフトを防ぐため、コピーはコードベースの中でキーを介して一元管理され、ローカライズは後付けではなく同じ操作の延長です。リポジトリを接続すれば、すべての言語がその1つのソースから派生します。AIコーディングツールで開発しているチームはこの問題に最も早く直面します。だからこそ私たちは、開発者の方々や、AIツールで開発している方々に向けて発信しています。
次にエージェントがあなたのコンポーネントに手を加えるとき、問われるのは、変更されたラベルが「意思決定」として現れるか、それとも「不意打ち」として現れるかです。globalize.nowは、あなたが接続するリポジトリ内でユーザー向け文字列を単一の情報源として管理し、その一つのコピーからすべての言語を導き出します。
globalize.nowは、ハードコードされたアプリ内テキストを翻訳可能なロケールファイルに変換し、リリースのたびに自動で最新の状態を保ちます。
globalize.nowを無料で試す