'AI한테 시켰더니 엉뚱한 코드가 나왔다'는 불평은 이제 흔한 이야기가 됐다. Next.js 14 App Router 프로젝트에서 pages/ 디렉토리를 생성하고, 이미 Drizzle로 마이그레이션한 코드베이스에 Prisma를 들고 오는 AI를 탓하기 전에, 한 가지를 먼저 짚어야 한다. AI가 틀린 게 아니라, 도구에게 프로젝트를 설명하지 않은 것이다.
실제로 dev.to에 공유된 Instruction File 패턴 아티클은 이 문제를 '컨텍스트 설계'의 관점으로 정확히 짚는다. Claude Code의 CLAUDE.md, Cursor의 .cursorrules, GitHub Copilot의 .github/copilot-instructions.md—이름은 달라도 역할은 하나다. AI가 훈련 데이터의 평균값이 아니라, 이 프로젝트의 규칙으로 코드를 생성하게 만드는 장치다. 네이밍 컨벤션, 금지된 패턴(Anti-Patterns), 프레임워크 버전까지 명시하는 5가지 패턴 중 특히 주목할 건 두 가지다. 첫째는 역할 정의(Role Definition)—'시니어 백엔드 엔지니어로서 6개월 뒤 주니어도 이해할 코드를 써라'는 지시가 pipe()와 chain()으로 가득한 함수형 코드 대신, 명시적 에러 핸들링을 갖춘 가독성 높은 함수를 만들어낸다. 둘째는 버전 명시와 NOT 패턴—Drizzle (NOT Prisma — we migrated in Q3)처럼 이유까지 함께 적는 방식이 AI의 '오래된 기억'을 효과적으로 덮어쓴다. Instruction File은 단순한 프롬프트 템플릿이 아니라, 코드베이스의 살아있는 문서다.
컨텍스트를 아무리 잘 설계해도, 생성된 코드가 사용자 앞에서 느리게 동작한다면 의미가 없다. AI가 쏟아내는 React 코드가 실제로 Core Web Vitals를 통과하는지는 별개의 문제다. dev.to의 React 성능 최적화 아티클이 정확히 이 지점을 다룬다. CRA나 Vite 기반의 CSR(Client-Side Rendering) 앱은 구조적으로 LCP에 불리하다. 브라우저가 HTML을 받아도 <div id="root"></div> 하나뿐이라, JS 번들을 다운로드하고 파싱하고 실행한 뒤에야 사용자가 화면을 볼 수 있다. AI가 CSR 앱을 뚝딱 만들어주는 속도감 뒤에 숨어있는 성능 부채다.
해법은 측정에서 시작한다. web-vitals 패키지로 LCP·CLS·INP를 직접 수집하고, 프로덕션 환경에서 분석 엔드포인트로 전송하는 파이프라인을 갖추는 것이 먼저다. 그 다음 처방은 문제 유형별로 명확하다. LCP가 느리다면 React.lazy로 코드 스플리팅, 히어로 이미지 preload, WebP 포맷 전환, 그리고 근본적으로는 Next.js SSR로의 이동이 정답이다. CLS는 이미지와 동적 컨텐츠에 항상 크기를 명시하고 스켈레톤으로 공간을 예약하면 대부분 해결된다. INP는 메인 스레드 부하가 핵심—useMemo로 연산을 캐싱하고, useTransition으로 무거운 업데이트를 저우선순위로 전환하며, 1만 개짜리 리스트는 react-window로 가상화해야 한다. AI가 만들어준 코드는 '동작하는 코드'이지, '최적화된 코드'가 아니다. 성능을 AI에 위임하기 전에 개발자가 측정 루프를 직접 소유해야 한다는 뜻이다.
컨텍스트도 설계하고, 성능도 챙겼다. 그런데 AI 도구 자체가 예고 없이 동작을 바꾼다면? 이것이 세 번째 이야기다. GeekNews에 소개된 'Claude Code A/B 테스트 비판' 글은 AI 코딩 도구 생태계의 가장 불편한 진실을 건드린다. Anthropic이 Claude Code의 plan mode 동작을 사용자 고지 없이 A/B 테스트했고, 일부 사용자는 계획이 40줄로 제한되고 맥락 섹션이 제거된 버전을 받았다. 해당 사용자는 월 200달러를 지불하는 전문 사용자였다.
흥미로운 건 Anthropic 엔지니어가 HN 댓글에서 직접 해명했다는 점이다. 요지는 이렇다: 3.x 시리즈용 plan-mode 프롬프트를 4.x 모델에서도 간소화할 수 있는지 실험했고, 계획을 짧게 해도 rate-limit 영향이 없어 실험을 종료했다고. 기술적으로는 타당한 설명이다. 하지만 이 해명이 오히려 문제의 본질을 드러낸다. AI 도구를 둘러싼 신뢰 계약은 코드 품질만으로 구성되지 않는다. 도구가 지금 어떤 버전의 동작을 하고 있는지, 실험군에 포함돼 있는지, 내가 경험하는 결과가 실험의 산물인지 아닌지—이 모든 것이 투명해야 전문 도구로서 신뢰받을 수 있다.
세 가지 이야기는 결국 하나의 구조로 수렴한다. AI 코딩 도구를 잘 쓰는 것은 세 층위의 설계 문제다. 첫째, Instruction File로 컨텍스트 레이어를 설계한다—AI가 훈련 데이터의 평균이 아닌 우리 프로젝트의 규칙을 따르게 만드는 것. 둘째, Core Web Vitals로 결과물 레이어를 측정한다—AI가 생성한 코드가 실제 사용자 경험을 만족하는지 검증하는 것. 셋째, 도구의 동작 투명성을 신뢰 레이어로 요구한다—내가 사용하는 도구가 지금 어떻게 동작하는지 알 권리를 행사하는 것.
앞으로 AI 코딩 도구 시장은 이 신뢰 레이어를 얼마나 잘 설계하느냐로 차별화될 가능성이 높다. 실험을 하되 opt-in으로, 변경을 하되 changelog로, 제한을 두되 사용자 설정으로—이것이 전문 도구가 지켜야 할 최소한의 계약이다. 동시에 개발자 입장에서는 CLAUDE.md 하나 없이 AI 도구에 프로젝트를 통째로 위임하거나, Lighthouse 점수를 확인하지 않고 AI 생성 코드를 배포하거나, 도구의 동작 변화를 인지하지 못한 채 결과물의 품질 저하를 자기 탓으로 돌리는 패턴을 경계해야 한다. 프롬프트를 잘 쓰는 것보다, 도구가 어떻게 동작하는지 이해하고 그 위에 워크플로우를 설계하는 능력이 AI 시대 프론트엔드 개발자의 진짜 역량이다.