CLAUDE.md 도입으로 AI 에이전트의 프로젝트 컨텍스트 이해도 향상시킴

Context

AI 코딩 에이전트가 매 세션마다 동일한 프로젝트 설명을 반복해야 하는 비효율 문제가 존재함. 컨텍스트 윈도우 크기 증가(200K→2M tokens)에도 불구하고 실제 Bottleneck은 컨텍스트 품질임.

Technical Solution

• CLAUDE.md: 프로젝트 컨벤션, 아키텍처 결정, 도구 선호도를 2KB 파일로 압축 표현함
• Project Identity 섹션: 스택, 주요 모듈 구조를 기계가 파싱 가능한 형태로 정의함
• Conventions 섹션: snake_case 사용 규칙, TypeScript strict mode, Zod 검증 선호 등 코드 작성 규범을 명시함
• Gotchas 섹션: 레거시 결제 모듈 수정 금지, /api/v1 엔드포인트 비사용 등 팀 내부 지식(Slack history, 시니어 개발자 머릿속)을 문서화함

Impact

모든 후속 프롬프트에서 토큰 절약됨. 리팩토링 시 컨벤션 자동 준수됨.

Key Takeaway

더 똑똑한 모델보다 더 나은 설정이 에이전트 성능을 결정함. 작은 모델+잘 설정된 에이전트가 큰 모델+잘못 설정된 에이전트보다 항상 우수한 결과를 만듦.

documentation as configuration 패턴은 개발 생산성의 새로운 핵심 요소임.