AI 코딩 도구를 처음 붙인 팀이 가장 많이 하는 실수가 있다. 모델을 탓하는 것이다. "Cursor가 엉뚱한 컴포넌트를 만든다", "Claude Code가 우리 컨벤션을 무시한다"는 불만은 대부분 모델 문제가 아니다. 코드베이스 문제다.
dev.to에 올라온 두 편의 실전 글이 이 문제를 서로 다른 각도에서 정확히 짚는다. 하나는 AI 코딩 도구가 실제로 따르는 크로스플랫폼 템플릿 설계법이고, 다른 하나는 Claude Code 세션을 제대로 운영하는 습관 다섯 가지다. 겉으로는 별개 주제처럼 보이지만, 두 글이 가리키는 방향은 같다. AI가 잘 작동하는 환경은 저절로 만들어지지 않는다. 팀이 설계해야 한다.
AI가 실수하는 이유는 모델이 아니라 코드베이스다
첫 번째 글의 저자는 Claude Code, Cursor 등 주요 AI 코딩 도구가 낯선 코드베이스에서 반복적으로 저지르는 실패 유형 세 가지를 꼽는다. 존재하지 않는 유틸리티를 발명하는 것, 이미 있는 컨벤션을 무시하는 것, 스캐폴드 구조를 제품 구조로 착각하는 것. 세 가지 모두 원인이 동일하다. 모델이 처음 보는 코드베이스를 읽을 수 없기 때문이다.
해법으로 제시하는 원칙들은 단순하지만 실질적이다. 컴포넌트 하나는 파일 하나에 완결되어야 한다. useCreateProject라는 이름만 봐도 TanStack Query mutation 훅이라는 사실을 알 수 있어야 한다. 반복 패턴의 정답은 파일 시스템 어딘가에 실제로 존재해야 한다. 그리고 핵심—CLAUDE.md, .cursorrules, AGENTS.md는 선택이 아니라 필수다.
이 중에서 내가 가장 주목하는 건 "토큰 대신 디자인 토큰" 원칙이다. 헥스 컬러를 코드베이스 전체에서 금지하고 --destructive, --primary 같은 CSS 변수만 허용하면, AI가 "빨간색으로 바꿔줘"라는 요청을 받았을 때 임의의 헥스값을 발명하는 대신 토큰 파일을 읽거나 되묻는다. 코드베이스의 제약이 AI의 행동을 교정하는 것이다. ESLint 플러그인으로 헥스 리터럴 자체를 lint-out하면 AI가 틀린 코드를 생성해도 커밋 전에 막힌다. 규칙을 문서에 쓰는 것보다 코드로 강제하는 쪽이 훨씬 강하다.
CLAUDE.md는 스펙 문서가 아니라 교정 로그다
두 번째 글은 Claude Code를 1년 넘게 매일 쓴 개발자의 운영 습관을 다룬다. 그 중 팀 운영 관점에서 가장 중요한 통찰은 CLAUDE.md를 대하는 태도다. 대부분의 팀이 프로젝트 시작 때 CLAUDE.md를 한 번 작성하고 잊는다. 저자가 제안하는 방식은 반대다. AI가 반복 실수를 저지를 때마다 한 줄씩 추가하는 "교정 로그"로 운영하는 것이다.
"이 레포에서는 pnpm을 써라. package-lock.json을 생성하지 마라." "API 응답 키는 camelCase여야 한다." 각 규칙은 한 문장이고, 파일은 세션이 쌓일수록 유기적으로 자란다. 이렇게 만들어진 CLAUDE.md는 신입 팀원 온보딩 문서보다 훨씬 실질적인 컨텍스트가 된다. 팀이 실제로 겪은 실수의 역사이기 때문이다.
세션 관리 습관도 팀 단위로 생각하면 의미가 달라진다. 세션을 시작할 때 "Refactor auth module token validation logic"처럼 한 줄 요약으로 이름을 붙이는 것, 설계 결정이나 복잡한 디버깅 경로가 담긴 세션은 /export로 마크다운 문서화해두는 것—이 습관들이 개인 생산성을 넘어 팀의 의사결정 기록이 된다. 왜 그 구조로 짰는지, 왜 그 라이브러리를 선택했는지, 다음 달의 나와 팀원이 AI 세션 로그에서 꺼낼 수 있다면 온보딩 비용이 달라진다.
팀이 설계해야 할 것들
두 글을 종합하면 AI-First 코드베이스 설계의 체크리스트가 나온다. 파일 구조는 AI가 체인을 따라가지 않아도 컴포넌트 전체를 한 파일에서 읽을 수 있어야 한다. 네이밍은 파일을 열지 않아도 역할을 추론할 수 있을 만큼 의미를 담아야 한다. 패턴 파일은 머릿속이 아니라 파일 시스템 어딘가에 실제로 존재해야 한다. AI 설정 파일은 프로젝트에 기본 포함되어야 하고, 팀이 공동으로 유지보수해야 한다. 타입과 린트는 AI가 생성한 코드의 오류를 편집 시점에 잡아야 한다.
lessons.md 개념도 주목할 만하다. 첫 번째 글의 저자 팀은 비자명한 버그를 만날 때마다 증상, 원인, 해결책을 한 파일에 쌓는다. AI 에이전트가 같은 문제를 만나면 이 파일을 먼저 검색하도록 AGENTS.md에 명시한다. 같은 실수를 세 번 반복하는 일이 없어진다. 이건 AI만을 위한 문서가 아니다. 팀의 집단 기억이다.
AI 도구의 ROI는 코드베이스 가독성에서 나온다
현장에서 내가 반복적으로 확인하는 패턴이 있다. AI 코딩 도구를 도입했는데 생산성이 기대에 못 미친다고 느끼는 팀은, 대부분 AI 도구 설정에 집중하고 코드베이스 설계에는 손을 대지 않는다. 반대로 AI가 실제로 팀 속도를 바꾸는 경우를 보면, 코드베이스 자체가 AI가 읽기 좋은 형태로 되어 있다. 이름이 명확하고, 패턴이 일관되고, 컨텍스트 파일이 살아있다.
모델 성능은 계속 좋아진다. 하지만 컨텍스트 창이 아무리 늘어나도, 코드베이스가 AI에게 읽히지 않으면 AI는 계속 컨벤션을 발명한다. 지금 팀이 투자해야 할 곳은 더 좋은 모델 구독이 아니라 AI가 따를 수 있는 코드베이스를 만드는 일이다. 그리고 그 작업은 지금 당장 CLAUDE.md 한 줄 추가하는 것부터 시작된다.