"AI한테 매번 같은 말 반복하고 있지 않나요?"
팀원들에게 AI-First 마인드를 심어줘야 한다고 매일 외치지만, 정작 가장 큰 병목은 의외로 단순한 곳에 있습니다. Claude Code에 "pnpm 써" "Conventional Commits 형식으로" "typecheck 먼저 돌려"를 매 세션마다 반복하는 것. 컨텍스트 윈도를 잡아먹고, 흐름을 끊고, 결국 "그냥 내가 직접 할게" 모드로 돌아가게 만드는 마찰입니다. AWS 기술 블로그에 올라온 CLAUDE.md 실전 가이드(dev.to/aws)가 정확히 이 문제를 겨냥합니다.
세 계층 구조: 개인 → 프로젝트 → 로컬 오버라이드
CLAUDE.md의 핵심은 세 계층 파일 시스템입니다. ~/.claude/CLAUDE.md에는 "TypeScript strict 모드 필수", "함수형 패턴 선호" 같은 개인 스타일을, 프로젝트 루트 ./CLAUDE.md에는 빌드 커맨드·아키텍처 결정·Git 워크플로우 같은 팀 컨벤션을, 그리고 .gitignore 대상인 ./CLAUDE.local.md에는 개인별 단축키나 "설명 생략, 이 코드베이스 잘 알아" 같은 로컬 오버라이드를 넣습니다. 세 파일은 자동으로 합쳐지고, 더 구체적인 지시가 우선합니다.
이걸 AI-First 팀 리빌딩 관점에서 보면, 프로젝트 CLAUDE.md가 곧 '살아 있는 팀 컨벤션 문서'가 되는 셈입니다. 새 팀원이 합류하면 README 대신 CLAUDE.md를 먼저 읽으라고 하면 됩니다 — 사실 Claude가 대신 읽어주니까, 온보딩 첫날부터 팀 스타일에 맞는 코드가 나옵니다. /init 명령어 한 줄이면 기존 코드베이스를 분석해 초안까지 자동 생성해 주니, 도입 장벽도 거의 없습니다.
700개 도구를 혼자 만든 비밀: 스키마가 곧 UI
이 패턴이 극단까지 확장되면 어떤 일이 벌어지는지, utils.live 사례(dev.to/kranthi_kumarmuppala)가 보여줍니다. 한 명의 개발자가 Claude Code만으로 734개 브라우저 기반 개발자 도구를 구축했습니다. 비결은 defineTool()이라는 단일 추상화입니다. Zod 스키마로 입력·출력·옵션을 정의하면, 빌드 타임에 JSON Schema로 변환되어 UI 폼이 자동 생성되고, 실행 시에는 입력 검증·타임아웃·사이즈 제한이 자동 적용됩니다. 도구 하나당 UI 코드는 0줄입니다.
AI한테 물어보니까 이런 패턴이 나오더라고요 — 스키마 하나 정의하면 나머지는 전부 추론. 이건 곧 "AI가 생성해 준 걸 기반으로 우리가 다듬으면" 모델의 교과서적 사례입니다. Claude Code가 defineTool() 패턴을 이해하고 있으니, 새 도구 추가는 "JSON-to-YAML 변환기 만들어줘"라는 프롬프트 한 줄로 끝납니다. 결과물은 Next.js 정적 생성으로 약 7,800개 페이지가 되어 Cloudflare Pages에서 월 $0으로 서빙됩니다.
배포 판단을 자동화하면 팀이 더 중요한 일에 집중합니다
코드 작성만 AI-First로 바꾸면 절반입니다. 배포 의사결정도 자동화해야 파이프라인 전체가 AI-First가 됩니다. qualityhub-cli(dev.to/younes_bentlili)는 테스트 결과와 커버리지를 파싱해 0~100 리스크 스코어를 산출하고, PROCEED / CAUTION / BLOCK 세 단계 판정을 내립니다. 히스토리를 로컬 JSON에 저장해 커밋 간 회귀를 자동 비교하고, CI에서 BLOCK이면 exit code 1로 파이프라인을 멈춥니다.
"이거 자동화하면 우리가 더 중요한 일에 집중할 수 있어요"라는 말이 정확히 여기에 해당합니다. 스프린트마다 엑셀에 커버리지 수치를 수동 취합하던 팀이, 2초짜리 CLI 한 줄로 회귀 탐지와 배포 판단을 자동화할 수 있습니다. 서버도, 계정도, API 키도 필요 없습니다.
Claude Sonnet 4.6: AI-First 워크플로우의 엔진이 업그레이드됐다
이 모든 워크플로우의 엔진인 Claude 모델 자체도 진화했습니다. Anthropic이 공개한 Claude Sonnet 4.6은 코드 작성·수정 효율에서 이전 Sonnet 4.5 대비 70%, Opus 4.5 대비 59% 높은 사용자 선호도를 기록했습니다(디지털데일리). 100만 토큰 컨텍스트 윈도, 환각·중복 생성 감소, 프롬프트 인젝션 저항력 향상 — 그러면서 가격은 Sonnet 4.5와 동일합니다. 이전에는 Opus급 모델에서만 가능했던 복잡한 코딩·사무 작업을 중간급 모델이 처리한다는 건, AI-First 워크플로우의 비용 효율이 한 단계 올라갔다는 뜻입니다.
시사점: CLAUDE.md는 기술이 아니라 문화 장치다
기획 단계부터 AI를 끼면 훨씬 효율적이에요 — 하지만 그 전에 AI가 우리 팀의 맥락을 알아야 합니다. CLAUDE.md는 단순한 설정 파일이 아니라, 팀 컨벤션을 AI가 소비할 수 있는 형태로 코드화하는 문화적 계약입니다. 이 파일을 git에 커밋하는 순간, 모든 팀원의 Claude가 동일한 컨벤션으로 작동합니다. 코드 리뷰에서 "pnpm 써야지" 같은 지적이 사라지고, AI가 생성한 코드의 일관성이 올라갑니다.
실전 적용 순서를 정리하면 이렇습니다: (1) 프로젝트 CLAUDE.md에 빌드 커맨드·네이밍 컨벤션·Known Gotchas를 정리하고 git 커밋, (2) 반복 패턴은 defineTool() 같은 스키마 기반 추상화로 AI의 생성 품질을 구조적으로 보장, (3) 배포 판단은 qualityhub-cli 같은 자동화 게이트로 인간의 "감"을 수치화, (4) Sonnet 4.6의 확장된 컨텍스트 윈도로 더 큰 코드베이스를 한 세션에 처리. 이 네 조각이 맞물리면, AI는 도구가 아니라 팀의 컨벤션을 내재화한 동료가 됩니다.