Claude Code에 로그인 폼의 로딩 상태를 추가해 달라고 요청했어요. 로딩 상태는 잘 동작해요. 그런데 버튼이 “Sign in” 대신 “Log in”으로 바뀌었고, 에러 메시지는 더 친절해졌고, 제목 하나는 갑자기 문장형 대소문자가 됐어요. 아무도 요청하지 않은 변경인데 테스트는 전부 통과하고, 누군가 diff를 한 단어씩 읽지 않는 한 그대로 배포돼요.
이 글은 AI 코딩 에이전트가 이미 승인된 카피를 아무도 모르게 바꿔 놓는 문제와, 이를 막는 워크플로를 다뤄요. 에이전트가 하드코딩하고 키도 없이 새로 만드는 문자열은 다른 문제예요. AI 코딩 도구가 하드코딩 문자열을 계속 추가하는 이유에서 다뤘어요. 제품 카피를 어디에 두어야 하느냐는 아키텍처 문제이고, 코드 중심 제품 카피에서 다뤘어요. 이 글은 사건 하나에 집중해요. 아무도 결정하지 않았는데 문구가 바뀌어 있던 월요일 아침이에요. globalize.now는 현지화가 내장된 코드 중심 카피 관리 시스템이고, 이런 사건이 이 시스템이 존재하는 이유 중 하나예요.
AI 코딩 에이전트는 왜 UI 문구를 고쳐 쓰나요?
AI 코딩 에이전트는 컴포넌트 안에 있는 문구가 그냥 텍스트로 보여서 고쳐 써요. 문구를 소스 로케일 파일의 키 뒤로 옮기면, 문구 변경이 다른 작업의 부수 효과가 아니라 명시적이고 리뷰할 수 있는 수정이 돼요.
컴포넌트 안에서 “Sign in”은 특별한 존재가 아니에요. JSX 속성에 들어 있는 문자열 리터럴일 뿐이고, className이나 테스트 ID와 구별되지 않아요. 에이전트는 주변 코드를 개선하는 게 좋은 행동인 수백만 건의 diff로 학습했고, 모델에게 레이블을 “더 명확하게” 바꾸는 일은 변수 이름을 바꾸는 일과 같은 동작이에요. 타입 오류도, 실패하는 테스트도, 문구에 붙은 담당자 표시도 없어요. 에이전트에게 문구를 고치는 일은 아무 비용이 들지 않아요.
그 변경은 리뷰에서도 살아남아요. 리뷰어는 로직을 읽기 때문이에요. 문구 변경은 로딩 상태를 다루는 정당한 diff 한가운데 섞여 있고, 컴파일되고, 렌더링되고, 스냅샷 테스트가 실패해도 보통은 스냅샷을 업데이트해 버려요. 그러면 새 문구가 승인된 것처럼 기록돼요.
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.
이제 솔직한 이야기예요. 규칙은 컨텍스트이고, 컨텍스트끼리는 경쟁해요. 긴 작업에서 이 지시는 수천 토큰의 코드 속 한 줄일 뿐이라 가끔 밀려요. 컴팩션에 밀리고, 규칙을 본 적 없는 서브 에이전트에 밀리고, 주변 파일의 강한 패턴에 밀려요. 더 나쁜 점은 규칙을 어긴 에이전트가 그 사실을 알리지 않는다는 거예요. 문구가 바뀌었다는 알림은 없고, 우연히 바뀌어 있는 diff만 남아요. 관례는 검증이 아니에요.
그러니 규칙 파일은 첫 번째 레이어일 뿐이고, 이것만 믿어서는 안 돼요.
문구 수정을 조용히 넘어가지 않고 눈에 보이게 하려면 어떻게 하나요?
사용자에게 보이는 모든 문자열을 컴포넌트에서 빼서 소스 로케일 파일의 키 뒤로 옮기세요. 그러면 문구를 바꾸려는 에이전트는 문구만을 위한 파일을 수정해야 해요.
규칙 파일이 하지 못하는 단계가 바로 이거예요. 원리는 단순해요. 컴포넌트가 “Sign in”을 다시 적는 대신 t('auth.signIn')을 참조하면 두 가지가 동시에 달라져요. 컴포넌트 diff에서 카피가 사라지니, 로딩 상태를 작업하는 에이전트는 그 자리에서 고쳐 쓸 문구가 없어요. 그리고 에이전트든 사람이든 모든 카피 변경이 한 파일에 모이니, 바뀐 줄이 곧 우리가 신경 쓰는 이벤트이고 주변의 잡음이 아니에요. 로케일 파일 diff는 몇 초면 훑어보고, 잘못 바뀐 문구는 한 줄만 되돌리면 돼요.
이게 무엇을 해주는지 정확히 말하면, 에이전트는 여전히 로케일 파일을 수정할 수 있어요. 문구를 건드릴 수 없게 만드는 것이 아니라, 건드리는 일이 부수 효과가 아니라 눈에 보이고 검토할 수 있는 행위가 되게 하는 거예요. diff에서 알게 되느냐, 고객에게서 알게 되느냐의 차이예요.
소스 오브 트루스를 (코드로 동기화되는 디자인 도구가 아니라) 코드베이스에 두어야 하는 이유는 핵심 글인 코드 중심 제품 카피에서 전부 다뤘어요. 이 글에는 한 가지 결과만 필요해요. 키로 관리하는 카피가 규칙 파일을 요청에서 검증 가능한 것으로 바꿔 준다는 점이에요.
리뷰 게이트는 어떤 모습인가요?
소스 로케일 파일의 diff는 모두 문구 변경으로 취급하고, 문구를 책임지는 사람에게 보내세요.
구체적으로는, 로케일 디렉터리를 CODEOWNERS에 넣어서 변경이 생기면 카피를 담당하는 사람에게 리뷰가 요청되게 하세요. PR 템플릿에는 “이 PR이 사용자에게 보이는 문구를 바꾸나요? 그게 이 작업의 목적이었나요?”라는 한 줄을 추가하세요. 에이전트가 요약에 변경한 키를 나열하도록 한 규칙 파일 요구 사항도 유지하세요. 에이전트가 따르면 리뷰는 즉시 끝나고, 따르지 않아도 CODEOWNERS 훅이 잡아내요.
작은 팀에서는 들리는 것보다 부담이 적어요. 로케일 diff는 짧고 쉬운 말로 읽혀요. “이 버튼 문구를 이제 Log in으로 바꿔야 할까?”는 5초면 결정할 수 있는 문제예요. 단, 그 질문이 실제로 담당자 앞에 놓여야 하고, 그게 바로 이 관문이 하는 일이에요.
에이전트가 이미 문구를 고쳐 놓았다면 어떻게 하나요?
먼저 승인된 문구를 복원하고, 문자열을 키로 관리해서 다음 수정이 diff로 드러나게 하세요.
피해를 찾는 일은 git 작업이에요. 영향받은 컴포넌트를 마지막으로 신뢰하는 커밋과 diff해서 문자열 리터럴만 읽으세요. 바뀐 부분은 복원하면 돼요. 어떤 문구가 승인된 것인지 확신할 수 없다면(버튼에는 “Log in”, 마케팅 페이지에는 “Sign in”이라고 되어 있는데 어느 쪽이 맞는지 기록한 산출물이 없다면), 이 사건이 만들어 내는 더 깊은 상태에 도달한 거예요. 카피 드리프트는 사용자에게 보이는 텍스트가 여러 화면과 시간에 걸쳐 승인된 소스에서 벗어나는 현상이고, 벗어날 기준이 되는 단일 소스 오브 트루스도 없는 상태예요. 이 용어의 정의와 원인, 그리고 이후에 미치는 영향은 별도의 글인 카피 드리프트란에서 다뤄요.
그다음 복원한 문자열을 키로 관리하세요. 에이전트가 건드린 문자열부터 시작해요. 이 문자열들이 위험 지대에 있다는 건 이미 증명됐으니까요.
현지화는 어디에 들어가나요?
조용한 문구 수정은 한 언어에서는 성가신 일이지만 열 개 언어에서는 문제가 돼요. 이전 문구에서 파생된 번역이 전부 낡았는데, 다시 번역하라고 알려 주는 건 아무것도 없으니까요.
여기서 에이전트 사건의 피해가 커져요. 바뀐 영어를 배포하면 독일어, 일본어, 스페인어는 여전히 예전 문구를 보여 줘요. 이제 화면끼리만이 아니라 언어끼리도 내용이 달라져요. 카탈로그가 서로 어긋나는 것은 그 자체로 별개의 실패 유형이고 해법도 따로 있어요. 번역 파일 동기화 문제에서 다뤘어요.
키로 관리하는 카피는 이 고리도 끊어요. 소스 문자열이 바뀌면 눈에 보이는 이벤트가 되고 번역이 거기에 매달려 있으니까요. 리터럴이 조용히 옮겨 가는 것과 달라요. globalize.now가 바로 이 설계예요. 카피는 코드베이스 안에서 키 뒤에 단일 소스로 있고, 현지화는 덧붙인 기능이 아니라 같은 작업의 일부예요. 저장소를 연결하면 모든 언어가 그 하나의 소스에서 만들어져요. AI 코딩 도구로 개발하는 팀이 이 문제를 가장 먼저 겪어서, 개발자와 AI 도구로 만드는 사람들을 위한 글을 쓰고 있어요.
다음에 에이전트가 컴포넌트를 건드릴 때, 바뀐 레이블이 결정으로 보일지 뜻밖의 일로 보일지가 중요해요. globalize.now는 연결한 저장소에서 사용자에게 보이는 문자열을 단일 소스로 관리하고, 그 하나의 문구에서 모든 언어를 파생해요.
globalize.now는 하드코딩된 앱 문구를 번역할 수 있는 로케일 파일로 바꾸고, 배포할 때마다 최신 상태로 유지해요.
globalize.now 무료로 시작하기