AI 코딩 에이전트가 엉뚱한 모듈을 건드리거나, 아키텍처 컨벤션을 무시하거나, 이유를 알 수 없는 추상화를 만들어낼 때—흔히 모델 탓을 한다. 그런데 실제로 더 자주 틀리는 건 에이전트에게 넘겨주는 맥락 설계다. dev.to에 올라온 'The Perfect CLAUDE.md' 글은 이 지점을 정확히 짚는다. 대부분의 CLAUDE.md가 조용히 실패하는 이유는 모델 능력의 한계가 아니라, 운영적 모호성(operational ambiguity) 때문이라는 것이다.
맥락은 많을수록 좋은 게 아니다
Anthopic과 Stanford의 장문 컨텍스트 평가 연구에 따르면, 200K 토큰 이상을 처리할 수 있는 모델조차 지시가 반복되거나 구조가 불명확할 때 '주의 희석(attention dilution)' 현상이 나타난다. 즉, 더 많은 정보를 넣는다고 정확도가 오르지 않는다. 오히려 떨어진다.
실제로 나타나는 실패 패턴은 네 가지로 수렴한다. 서로 모순되는 지시(instruction collision), 규칙 과적재(context flooding), 에이전트가 무엇을 수정해도 되는지 모르는 경계 부재, 그리고 영속적 지식과 임시 태스크 메모가 뒤섞이는 메모리 혼재다. 좋은 CLAUDE.md는 이 네 가지를 구조적으로 분리함으로써 해결한다.
프롬프트가 아니라 운영 설계서로 접근하라
핵심 개념 전환은 여기에 있다. CLAUDE.md를 '프롬프트 도우미'로 쓰던 시대는 지났다. 현대 코딩 에이전트는 저장소 탐색, 의존성 분석, 파일 수정, 테스트 실행, 반복 계획까지 수행하는 자율 시스템이다. 이 시스템에게 넘기는 파일은 자연어 프롬프트가 아니라 실행 명세(execution specification)—내부 RFC에 가까운 문서—여야 한다.
실용적인 구조는 여섯 가지 운영 질문에 즉시 답할 수 있어야 한다: 이 저장소는 무엇인가, 코드는 어떻게 구성되어 있는가, 어떤 아키텍처 제약이 존재하는가, 에이전트가 사용할 수 있는 도구는 무엇인가, 절대 수정해선 안 되는 것은 무엇인가, 세션 간 추론은 어떻게 유지되는가. 이 여섯 가지에 명확히 답하지 못하는 CLAUDE.md는 에이전트의 신뢰성을 빠르게 무너뜨린다.
구체적인 구조 설계: 레이어드 명세
실전에서 검증된 CLAUDE.md 구조는 크게 여섯 섹션으로 나뉜다. 저장소 정체성(Repository Identity)—목적, 기술 스택, 핵심 제약—, 디렉토리 구조, 코딩 표준, 도구 권한(허용/금지 목록), 메모리 전략, 그리고 실행 기대치(코드 작성 전 체크리스트)다.
특히 '도구 권한' 섹션이 자주 빠진다. 에이전트가 인프라 배포나 마이그레이션 삭제 같은 고위험 작업을 실행할 수 있는지 없는지를 명시하지 않으면, 에이전트는 암묵적으로 허용 범위를 스스로 추론하려 한다. 이 추론이 틀렸을 때의 결과는 조용히 끔찍하다.
메모리 전략도 마찬가지다. 도메인 용어, 서비스 경계, API 보장 같은 영속 메모리와 현재 스프린트 태스크, 디버깅 아티팩트 같은 임시 메모리는 반드시 분리해야 한다. 두 가지를 섞어두면 오래된 디버깅 메모가 아키텍처 원칙인 것처럼 미래 코드에 영향을 미치는 '컨텍스트 화석화(context fossilization)' 현상이 발생한다.
솔로 개발자의 실전이 증명하는 것
추상적인 이론이 아니라는 걸 보여주는 사례가 있다. dev.to에 올라온 솔로 개발자의 6주 빌드 경험담—21개 AI 도구 페이지를 혼자 만들며 배운 것들—은 다른 각도에서 같은 진실을 가리킨다. 스택 선택보다 체크리스트가 훨씬 강력했다. 페이지 2 이후 100항목짜리 체크리스트를 작성하자 3~21번째 페이지는 각각 절반의 시간이 걸렸고 배포 후 버그율은 거의 0에 수렴했다.
AI 에이전트에게 넘기는 CLAUDE.md도 이 체크리스트와 본질이 같다. '운영 설계서'란 결국, 반복 실행에서 일관성을 보장하는 구조화된 제약의 집합이다. 에이전트든 인간 개발자든 명확한 실행 경계가 있을 때 더 빠르고 더 안정적으로 움직인다.
React SPA SEO 경험이 알려주는 설계 우선순위
또 다른 실전 데이터도 시사하는 바가 있다. React SPA로 12주간 Google 랭킹에 도전한 개발자의 리포트는—806번 노출에 클릭 1번—'렌더링 파이프라인을 나중에 추가하려 했더니 코드가 너무 많아져서 옮길 수 없었다'는 후회로 끝난다. 필요하기 전에 설계해야 했다는 것이다.
CLAUDE.md도 동일한 원칙이 적용된다. 에이전트가 이상한 코드를 만들어낸 다음에 CLAUDE.md를 정비하는 건, SPA가 이미 배포된 후에 SSR을 고려하는 것과 같다. 에이전트를 프로젝트에 투입하기 전, 설계 첫날부터 실행 명세를 만드는 것이 맞다.
지금 당장 적용할 수 있는 CLAUDE.md 작성 원칙
실용적으로 정리하면 세 가지다.
첫째, 동기부여 문장을 지워라. "클린하고 유지보수 가능한 코드를 작성하라"는 에이전트에게 아무 정보도 주지 않는다. 대신 "모든 비동기 워크플로우는 멱등(idempotent)해야 한다. 재시도 실행이 예상되기 때문이다"처럼 구현 결정을 바꾸는 지시만 남겨라.
둘째, 폴더 구조를 일관되게 유지하라. 에이전트는 인간 개발자처럼 시간이 지나며 멘탈 맵을 쌓지 않는다. 인증 로직이 다섯 개 폴더에 흩어져 있으면 어떤 프롬프트 엔지니어링도 그 엔트로피를 보상하지 못한다.
셋째, CLAUDE.md는 최소화하고 안정적으로 유지하라. 임시 태스크 지시는 태스크 범위 파일로 외부화하고, CLAUDE.md에는 세션이 바뀌어도 변하지 않는 영속적 운영 원칙만 남겨라.
맥락 설계가 곧 에이전트 품질이다
결국 AI 코딩 에이전트의 신뢰성은 모델 버전보다 맥락 설계에 더 많이 달려 있다. CLAUDE.md를 '어딘가 있는 문서'가 아니라 에이전트가 실행되는 환경의 구성 파일로 다루는 순간, 에이전트의 행동은 예측 가능해진다. 빠르게 만드는 것과 제대로 설계하는 것은 양립할 수 있다—단, 설계가 먼저여야 한다.