AI 코딩 에이전트는 분명 강력하다. 그런데 실제 프로덕션 코드베이스에서 쓰다 보면 반복적으로 마주치는 '찝찝한 순간'들이 있다. 아랍어 UI를 짰더니 레이아웃이 완전히 뒤집혀 있고, 공들여 작성한 CLAUDE.md를 에이전트가 무시한 것 같고, 멋지게 완성된 컴포넌트 안에 내가 원하지 않은 결정들이 조용히 녹아 있는 경험. 이 세 가지는 각각 별개의 불편처럼 느껴지지만, 사실 하나의 공통 원인에서 비롯된다. 에이전트는 명시적으로 알려주지 않으면 모른다.
맹점 1. AI는 RTL을 모른다—그리고 학습하지 않는다
dev.to에 올라온 RTLify 제작기는 히브리어·아랍어 사용자를 위한 제품을 만드는 개발자의 솔직한 고백에서 시작한다. AI에게 컴포넌트를 요청할 때마다 margin-left, ml-4, text-left 같은 물리적 CSS 클래스가 쏟아진다. RTL 환경에서 이 코드들은 레이아웃을 완전히 망가뜨린다. 더 심각한 건 AI가 이 실수를 반복한다는 것이다. 고쳐줘도 다음 대화에선 같은 패턴이 돌아온다. 이유는 단순하다. 현존하는 AI 모델들은 압도적으로 LTR(좌→우) 코드베이스로 학습되었고, RTL 컨텍스트에 대한 인식 자체가 부재한다.
문제는 단순히 방향 반전이 아니다. margin-inline-start 대신 margin-left를 쓰는 것, 숫자가 RTL 문장 안에서 뒤섞이는 BiDi 텍스트 문제, 방향성 아이콘(chevron-right)이 RTL에서도 그대로 오른쪽을 가리키는 것, Intl.NumberFormat 없이 통화 기호를 하드코딩하는 것—이 모든 실수가 패턴화되어 있다. RTLify가 제시한 해법은 흥미롭다. 에이전트에게 런타임에 계속 가르치려 하지 말고, 에디터가 대화를 시작하기 전에 읽는 규칙 파일(rtlify-rules.md)로 선제적으로 컨텍스트를 주입하는 것이다. npx rtlify-ai init 한 줄이 Claude Code, Cursor, Windsurf 등 주요 에디터에 8개 RTL 규칙을 심어 놓는다. 에이전트를 '재교육'하는 게 아니라, 매 대화의 시작점 자체를 바꾸는 전략이다.
맹점 2. CLAUDE.md를 썼는데 왜 무시하나
"완벽한 시스템 프롬프트를 20분 동안 작성했는데 Claude Code가 또 무시했다." dev.to의 Claude Code 설정 가이드는 이 경험에서 출발한다. 원인 진단은 명쾌하다. 대부분의 "에이전트가 안 듣는" 문제는 .claude/ 폴더 구조와 우선순위 체계를 이해하지 못한 데서 온다.
Claude Code는 CLAUDE.md를 여러 위치에서 읽고 병합한다. ~/.claude/CLAUDE.md(사용자 전역) → ./CLAUDE.md(프로젝트 루트) → ./.claude/CLAUDE.md → ./src/CLAUDE.md(서브디렉토리) 순으로 로드되며, 더 구체적인 파일이 상위를 오버라이드한다. 팀원과 다른 동작이 나오거나, 세션 중간에 수정한 규칙이 반영되지 않는 이유가 여기 있다. CLAUDE.md는 세션 시작 시점에 읽히므로, 수정 후엔 /clear로 새 세션을 열어야 한다.
내용의 문제도 크다. "클린 코드를 좋아합니다" 같은 추상적 설명은 에이전트에게 아무 지침도 주지 않는다. 효과적인 CLAUDE.md는 구체적이고 명령형이어야 한다. "named exports만 사용, default export 금지", "테스트는 Vitest, Jest 아님", "서버 컴포넌트 기본, 인터랙션 필요 시에만 use client" 처럼 AI가 틀릴 수 있는 지점을 정조준하는 규칙이어야 한다. 모노레포 환경에서는 패키지별 서브디렉토리에 CLAUDE.md를 분리해 두면, 프론트엔드 패키지에 백엔드 패턴이 섞이는 문제를 구조적으로 막을 수 있다. settings.json(팀 공유)과 settings.local.json(개인 오버라이드, .gitignore 필수)의 역할을 분리하는 것도 팀 협업에서 반드시 챙겨야 할 포인트다.
맹점 3. 에이전트는 모른다고 말하지 않는다
세 번째 맹점은 가장 교묘하다. dev.to의 'AI Answers Can Come with Silent Tech Debt'는 이를 "default fill-in"이라는 개념으로 정의한다. 프롬프트에 명시되지 않은 모든 결정을 AI가 자동으로 채워 넣는 현상이다. "React 파일 피커와 컬러 피커를 만들어줘, Python API URL은 변수로 빼줘"라는 단순한 요청에 Claude 4.6은 다중 파일 업로드, 드래그앤드롭, 프리셋 컬러, /upload 엔드포인트, files[] 요청 형태를 모두 스스로 결정해서 코드에 박아 넣었다. 겉으로는 완성도 있어 보이는 코드지만, 내부에는 내가 선택하지 않은 수십 가지 결정이 조용히 잠들어 있다.
이 글에서 제안하는 해법인 VDG 프로토콜은 AI에게 "모르는 건 모른다고 말하게" 강제하는 구조다. 동일한 프롬프트에 VDG 지침을 추가하자 Claude는 코드 대신 먼저 Verified(확인된 것) / Deduction(추론한 것) / Gap(불명확한 것)을 구분해서 출력했다. 엔드포인트 경로, 요청 형태, 인증 헤더, 응답 포맷이 Gap으로 명시되었고, 코드는 그 불확실성을 그대로 남겨 놓은 최소한의 형태로 생성됐다. 기능은 동일하지만 조용한 결정이 드러난 결정으로 바뀐다. 유지보수를 염두에 둔 프로덕션 코드를 작성한다면, 이 차이는 단순한 스타일 차이가 아니라 기술부채의 누적 방식 자체를 바꾼다.
시사점: 에이전트 제어는 '프롬프트 잘 쓰기'가 아니다
세 가지 맹점을 관통하는 공통 전략이 보인다. 런타임 교정이 아닌 사전 구조화다. RTLify는 대화마다 RTL 규칙을 일일이 주입하는 대신 에디터 설정 파일에 규칙을 심는다. Claude Code 설정 가이드는 그때그때 수정 요청하는 대신 CLAUDE.md 우선순위 체계를 제대로 설계하라고 말한다. VDG는 완성된 코드를 되돌리는 대신 AI가 가정을 채워 넣기 전에 Gap을 노출시킨다. 세 접근 모두 에이전트의 기본 동작 방향을 바꾸는 '업스트림 개입'이다.
반대로 말하면, 에이전트에게 계속 같은 실수를 고치게 하고 있다면 그건 도구의 문제가 아니라 설정 구조의 문제일 가능성이 높다. AI 코딩 에이전트를 잘 쓰는 것은 더 좋은 프롬프트를 즉흥적으로 작성하는 능력이 아니라, 에이전트가 작동하는 컨텍스트를 미리 설계하는 능력에 가깝다.
전망: '에이전트 설정 설계'가 새 역량이 된다
이 세 가지 문제가 동시에 주목받고 있다는 건 흥미롭다. AI 코딩 도구의 열기가 '일단 써보기' 단계를 지나 '어떻게 하면 믿고 쓸 수 있나' 단계로 이동하고 있다는 신호다. RTL 지원, 설정 우선순위, 암묵적 결정 노출—모두 에이전트를 프로덕션 환경에 실제로 적용하면서 부딪히는 현실 문제들이다.
앞으로 팀 단위 AI 도입이 가속화될수록 CLAUDE.md 같은 에이전트 설정 파일은 .eslintrc나 tsconfig.json처럼 코드베이스의 일급 시민이 될 것이다. RTLify의 접근처럼 '규칙의 패키지화'도 생태계로 발전할 여지가 있다. 국제화 규칙 세트, 접근성 규칙 세트, 팀 컨벤션 세트를 CLI 한 줄로 에이전트에 주입하는 방식은 충분히 표준화될 수 있다. 에이전트를 잘 '부리는' 것이 아니라 잘 '설계하는' 것—그게 다음 단계의 프론트엔드 개발자 역량이 되어가고 있다.