Claude Code를 팀에 붙이기로 결정한 뒤 가장 먼저 마주치는 질문이 있다. "가이드라인을 얼마나 써줘야 하나?" CLAUDE.md를 두껍게 써야 할까, 아니면 모델이 알아서 할 테니 최소한만 줘도 될까. 이 질문에 실제로 실험으로 답한 사람이 있다. 브라질 개발자 Alberto Souza는 dev.to에 동일한 백로그를 네 가지 가이드라인 구성으로 구현한 결과를 공개했다. 결론부터 말하면 생각보다 훨씬 덜 직관적이다.
실험 설계는 단순하다. Hotmart 체크아웃 구현 태스크 10개를 동일하게 주고, 가이드라인 구성만 달리한 네 버전의 Claude Code(Opus 4.7)를 돌렸다. ① 가이드라인 없음, ② CLAUDE.md만 제공, ③ CLAUDE.md + 코드 리뷰 스킬, ④ CLAUDE.md + 도메인·컨트롤러·로그 등 역할별로 세분화된 다중 리뷰 에이전트. 코드 품질은 CodeScene의 Code Health 지표로 평가했다.
결과가 예상을 깬다. Code Health 점수는 가이드라인 없음 9.93, CLAUDE.md만 9.93, 리뷰 스킬 추가 시 소폭 하락, 다중 에이전트 구성 9.85로 나왔다. 정교하게 설계한 슈퍼 가이드라인이 오히려 점수를 낮추고, 아무 가이드도 없던 버전과 CLAUDE.md 하나짜리 버전이 동점을 기록했다. Alberto의 가설은 명확하다. 메서드 크기, 결합도, 응집도 같은 보편적 코드 품질 원칙은 이미 모델이 충분히 학습했다. 이 영역에서 추가 가이드라인은 노이즈에 가깝다.
그렇다고 가이드라인이 무의미하다는 뜻은 아니다. 차이는 다른 곳에서 나왔다. 가이드라인 없이 생성된 코드는 컨트롤러를 어댑터로 취급하고 AccountsService에 로직을 몰아넣는 패턴을 따랐다. CLAUDE.md가 있는 버전은 컨트롤러 자체가 유스케이스의 진입점이 되었다. 생성자 주입 강제, null 반환 금지 같은 팀 고유의 컨벤션도 가이드가 있을 때만 일관되게 반영됐다. 보편적 품질 지표에서는 차이가 없지만, 팀이 유지보수해야 할 아키텍처 패턴과 도메인 언어는 가이드라인 없이는 복원되지 않았다.
이 실험에서 더 흥미로운 시사점은 '누가 쓰는가'와 결합할 때 나온다. 국내 게임 매체 인벤에 코딩을 전혀 모르는 문과생 기자가 Claude로 디펜스 게임을 완성한 과정이 공개됐다. 4개월 전 러버블로 실패했던 같은 사람이다. 차이를 만든 건 AI 도구 교체가 아니었다. 세 가지 프로세스 변화였다. 먼저 게임 기획서를 Claude에게 만들게 한 다음 그걸 개발 입력으로 썼고, 그래픽보다 로직을 먼저 완성했으며, 코딩은 Claude, 그래픽은 Gemini로 역할을 분리해 PM처럼 조율했다.
이 두 사례를 AI-First 팀 온보딩 설계 관점에서 겹쳐 보면 하나의 원칙이 보인다. 가이드라인의 효과는 '얼마나 많이 쓰는가'보다 '어떤 레이어를 다루는가'에 달려 있다. 모델이 이미 잘 아는 보편적 품질 원칙을 설명하는 데 토큰을 쓰는 건 낭비다. 반면 팀 고유의 아키텍처 결정, 도메인 언어, 컨벤션처럼 인터넷에 없는 맥락은 반드시 명시적으로 주입해야 한다. 비개발자 사례가 증명하듯, 프로세스 구조(기획서 → 로직 → 그래픽)가 먼저 잡히면 가이드라인의 밀도보다 효과가 크다.
팀 리빌딩 관점에서 직접적인 함의를 세 가지로 정리한다. 첫째, CLAUDE.md는 '팀이 AI 없이도 지켜온 컨벤션'을 담는 문서로 설계하라. 보편 원칙 설명은 덜어내도 된다. 둘째, 온보딩 가이드라인은 역할 분리 프로세스와 함께 설계해야 한다. 기획 → 로직 → 그래픽처럼 단계를 명시하지 않으면 비개발자는 물론 신규 팀원도 첫 번째 카피바라를 반복한다. 셋째, 다중 에이전트 리뷰 구성은 복잡도 증가 대비 품질 향상이 크지 않을 수 있다. Alberto의 실험에서 가장 정교한 구성이 가장 낮은 점수를 기록했다는 점은 충분히 경계해야 할 데이터다.
한 가지 한계도 짚어야 한다. Alberto의 실험은 그린필드 10개 태스크라는 제한된 조건이다. 코드 품질 문제의 대부분은 시스템이 노화되고 팀원이 교체되면서 누적 맥락이 소실될 때 나타난다. 가이드라인 효과의 진짜 검증은 6개월 후, 다른 팀원이 같은 코드베이스를 이어받았을 때다. Alberto 본인도 다음 실험 주제로 이를 예고했다. 전망은 이렇다. 단기 품질 지표에서 가이드라인의 차별화 효과는 작다. 하지만 팀 컨벤션 지속성과 비개발자 포함 온보딩 속도에서는 구조화된 프로세스가 핵심 변수가 된다. AI-First 팀이 설계해야 할 것은 가이드라인의 분량이 아니라, 어떤 맥락을 언제 주입할 것인지의 레이어 구분이다.