Claude Code를 처음 쓰는 팀이 가장 많이 저지르는 실수 두 가지가 있다. 하나는 CLAUDE.md를 팀 위키처럼 길게 쓰는 것, 다른 하나는 에이전트한테 '그냥 알아서 해'라고 맡기는 것. 최근 공개된 두 개의 현장 기록—FIFA 월드컵 데이터 파이프라인을 Claude Code와 함께 만든 세션 리포트(dev.to)와 CLAUDE.md를 처음부터 직접 세팅한 1주차 회고(velog)—은 이 두 실수의 실제 비용을 잘 보여준다.
CLAUDE.md는 읽는 대상이 AI다
velog의 개발자는 CLAUDE.md를 "코드 컨벤션 모아두는 문서"로 생각했다가, 직접 써보고 나서야 핵심을 깨달았다고 했다. 읽는 대상이 사람이 아니라 AI라는 것. 이게 왜 중요한가? 사람한테 쓰는 문서는 길수록 친절하다. AI한테 주는 지시문은 길수록 토큰을 낭비하고, 중요한 규칙을 노이즈 속에 묻어버린다. 같은 글자 수라도 사람을 위한 설명체와 AI를 위한 지시체는 구조가 완전히 달라야 한다.
실제로 이 개발자가 경험한 문제도 여기서 왔다. "AI가 생성한 코드는 반드시 설명할 수 있어야 한다"는 규칙을 CLAUDE.md에 넣었는데, 이건 AI한테 할 말이 아니라 사람한테 할 말이었다. 문서의 독자를 혼동하면 지시문이 아예 작동하지 않는다.
실전 세션이 보여준 개입의 타이밍
dev.to의 FIFA 파이프라인 세션은 훨씬 거칠고 실질적인 교훈을 담고 있다. 저자는 Claude Code와 함께 FIFA 공식 PDF 24개를 다운받아 개인별 스탯과 크로스하는 파이프라인을 만들었는데, 세션 내내 무엇이 에이전트 몫이고 무엇이 사람 몫인지를 명확히 기록했다.
에이전트가 잘 한 것: HTTP 000 에러의 원인을 nslookup으로 추적해 NXDOMAIN을 잡아낸 것, pdfplumber에서 'ff' 합자가 \x00으로 깨지는 것을 진단하고 토큰 카운트 기반 필터로 해결한 것, FotMob API가 /api/data/...로 마이그레이션됐다는 걸 스스로 발견한 것. 이런 작업들은 지시가 거의 없어도 에이전트가 독립적으로 수행했다.
에이전트가 못 한 것: 모듈 경계 설계. 저자가 "FotMob 클라이언트는 PDF와 절대 결합하지 마라"고 명시적으로 못 박지 않았다면, 에이전트는 기존 Wyscout 스크립트를 재사용했을 것이다. 두 포맷이 완전히 다른 구조인데도. 이 개입은 한 줄짜리 프롬프트였지만, 그게 없었다면 나중에 수습하는 데 몇 배의 비용이 들었을 것이다.
CLAUDE.md에 넣어야 할 것, 빼야 할 것
두 사례를 합치면 CLAUDE.md 설계 원칙이 꽤 선명하게 나온다.
넣어야 할 것: 모듈 경계 규칙("이 스크립트는 저 스크립트와 연결하지 마라"), 금지 패턴("외부 라이브러리보다 직접 작성한 클라이언트를 우선"), 네이밍 스키마("파일명은 M07-BRA-V-MAR.pdf 형식"), 데이터 소스 우선순위. 이것들은 에이전트가 스스로 판단하면 반드시 틀리는 것들이다.
빼야 할 것: 팀원한테 하는 말("코드를 이해한 뒤 머지하라"), 설명이 필요한 배경 이야기, 규칙의 이유. 이유는 사람 문서에 넣고, 지시만 CLAUDE.md에 넣어라. velog 개발자가 ESLint 규칙을 고를 때 기준으로 삼은 "설명 못 하면 안 넣는다"는 원칙을 CLAUDE.md에도 그대로 적용하면 된다. 설명이 필요한 규칙은 AI한테도 노이즈다.
결국 밀도의 문제다
Claude Code 세션에서 저자가 개입한 시점은 딱 두 종류였다. 에이전트가 잘못된 방향으로 가기 직전, 그리고 테스트할 데이터 소스의 선택지를 좁혀줄 때. 나머지는 다 에이전트 몫이었다. 이 구조를 만드는 게 CLAUDE.md의 역할이다. 문서가 모든 상황을 커버하려 들면 에이전트는 오히려 중요한 규칙을 놓친다. 짧고 밀도 높은 지시문이 긴 친절한 문서보다 낫다.
지금 팀의 CLAUDE.md가 500자가 넘는다면 한 번 다시 읽어볼 것. 그 중에서 AI한테 하는 말과 사람한테 하는 말을 분리하고, 사람한테 하는 말은 다 지워라. 남은 게 진짜 지시문이다.