AI가 Switch 컴포넌트를 뚝딱 만들어줬다, 그래서 뭐가 문제인가
Claude에게 Switch 컴포넌트 스펙과 variables.css를 던져줬더니, CVA variants·Radix Primitives·forwardRef·controlled/uncontrolled 패턴이 모두 연결된 코드가 돌아왔다. dev.to에 소개된 7onic의 사례다. 본인 표현대로 "내가 처음 짰을 것보다 나았다." 오후에 바로 배포했다.
그 경험이 42개 컴포넌트로 이어졌다. Radix + CVA + forwardRef + named export라는 고정 패턴 위에서, 컴포넌트 스펙과 토큰 파일을 컨텍스트로 넣으면 Claude는 읽고 이해하고 바로 배포할 수 있는 수준의 코드를 10~20% 수정만으로 뽑아냈다. 디자인 시스템 구축에 AI를 쓴다는 게 '가능한 일'이 아니라 '실제로 작동하는 일'임을 증명한 사례다.
진짜 문제는 코드 품질이 아니었다
그런데 3월에서 4월로 넘어가면서 상황이 달라졌다. Claude가 뭔가를 '완료했다'고 보고했는데, 실제로는 완료되지 않은 일이 세 번 연속 발생했다. 코드 자체는 여전히 좋았다. 문제는 완료 보고의 신뢰성이었다.
v0.3.0 릴리즈 당일—22개 compound 컴포넌트를 named export로 전환하는 브레이킹 체인지 작업 중—Claude는 세 번의 검증 완료를 자신 있게 보고했다. 세 번 모두 틀렸다. 한 번은 서브에이전트 결과를 직접 확인 없이 인용했고, 한 번은 구조적 정확성이 아닌 텍스트 출현 횟수를 셌으며, 한 번은 "컴파일 통과"를 "렌더 출력 일치"로 혼동했다. 그 어떤 보고에서도 자신 있는 응답과 틀린 응답을 구분할 수 있는 신호가 없었다.
이게 핵심이다. AI는 틀릴 때도 맞을 때와 똑같이 확신에 차 있다. 코드 생성은 컨텍스트를 잘 구성하면 신뢰할 수 있지만, 검증과 완료 보고는 다른 레이어의 문제다.
컨텍스트 설계: AI에게 내 코드베이스를 가르치는 법
컴포넌트 품질이 좋았던 이유도 설명이 필요하다. Claude는 당신의 코드베이스를 모른다. 커스텀 토큰 변수, 특정 컴포넌트 패턴, 네이밍 컨벤션—이 중 어느 것도 학습 데이터에 없다. 7onic은 이를 해결하기 위해 llms.txt를 6종 제작했다. 라이브러리 개요용 루트 파일부터, 토큰 패키지 전용, CLI 레퍼런스 전용, 그리고 CLI로 소스를 로컬에 복사했을 때 달라지는 import 경로 전용까지. 작은 디테일처럼 보이지만, 이 경로 하나가 틀리면 AI가 생성하는 코드 예시 전체가 쓸모없어진다.
CLAUDE.md는 그 위에 얹히는 운영 매뉴얼이다. 코딩 규칙, 절대 제약, 반복 워크플로우용 스킬 파일, 세션 간 유지할 사실들—예컨대 "public repo 커밋에 Co-Authored-By를 붙이지 말 것"처럼 MIT 라이선스 소유권 기록에 영향을 주는 규칙까지. AI 워크플로우에서 컨텍스트 설계는 선택이 아니라 필수 인프라다.
세 가지 게이트: AI를 믿되 검증을 구조화하라
세 번의 잘못된 완료 보고 이후 7onic이 만든 것은 '더 나은 프롬프트'가 아니었다. 구조적 방어막이었다.
첫 번째는 어휘 금지. CLAUDE.md에 "완료