CLAUDE.md가 AI 코딩시 참조

요즘 AI 코딩 좀 써봤다면 한 번쯤 이런 말 들었지. “레포 루트에 CLAUDE.md 없으면 에이전트 제대로 못 써요.”

근데 최근 연구랑 현업 실험을 보면 결론이 꽤 다르게 나와.
열심히 만든 컨텍스트 파일이 오히려 성능을 깎고 비용만 올리는 경우가 많다는 것.

 

왜 다들 CLAUDE.md에 집착하게 됐나

에이전트 도구들 쓰다 보면 자연스럽게 “레포별 규칙 파일”을 만들게 되지~
/init 한 번 치면 레포 구조 읽어서 요약 파일도 자동으로 만들어주고, 템플릿도 넘쳐나고. 문제는 최신 연구 결과가 이 흐름에 찬물을 끼얹었다는 점.

• LLM이 자동 생성한 컨텍스트 파일 → 성능 평균 하락, 비용 크게 증가
• 사람이 직접 작성한 파일 → 성능 소폭 개선, 하지만 비용 상승은 그대로

핵심 메시지 한 줄로 정리하면 이거다. 모델을 도우려 하지 말고, 방해부터 하지 말자.

 

핵심 연구 한 줄 요약

arXiv에 공개된 Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents? https://arxiv.org/abs/2602.11988 실험 방식이 아래와 같아.

1. 컨텍스트 파일 없이 에이전트 실행
2. LLM이 자동 생성한 파일 붙여서 실행
3. 개발자가 직접 쓴 파일 붙여서 실행 → 실제 GitHub 이슈 해결 성능 비교

자동 생성 컨텍스트의 현실, 결론부터 말하면 “좋아지긴 하는데 가성비는 별로” 상태.

• 성능 ↓
• 추론 스텝 ↑
• 토큰 비용 ↑
• 탐색 효율 개선 거의 없음

사람이 만든 컨텍스트의 현실

• 성능은 조금 나아짐
• 대신 비용과 복잡도도 같이 증가

 

 

왜 이런 일이 벌어질까

1) 에이전트는 파일을 무시하지 않는다. 너무 잘 따른다

컨텍스트에 특정 도구를 강조해 두면, 실제로 필요 없는데도 그걸 더 자주 사용한다고해. 문제는 순종성이 아니라 “불필요한 순종”?

2) 중복 정보가 대부분

폴더 구조, 사용 스택, 테스트 위치… 이런 건 에이전트가 이미 코드에서 직접 찾기 때문에 불필요해.

요약 문서를 또 읽게 만들면 → 토큰만 더 쓰고 판단은 더 느려지고... 

3) 잘못된 상위 규칙이 된다

컨텍스트 파일은 사용자 프롬프트보다 위에 있는 규칙처럼 작동해. 한 번 잘못 써두면 계속 그 방향으로 행동하지~

 

흥미로운 비교: “스킬”은 효과가 있었다

다른 연구에서는 결과가 달랐다고 해.

• 절차 중심의 작은 작업 가이드(스킬) 제공 → 성능 크게 향상
• 레포 전체 요약 문서 → 효과 거의 없음

차이는 딱 하나야. 정보 설명 vs 행동 지침. 아직까지는 AI는 개요보다 “어떻게 할지”가 필요해 보여.

 

실전에서 바로 써먹는 운영 전략

1) 컨텍스트 최소화가 기본 전략

• 테스트 실패 메시지 명확하게
• 스크립트 명명 일관성 유지
• 타입/린터 에러 강제
• 모듈 경계 명확히

좋은 피드백 시스템이 최고의 컨텍스트다. 개인적으로, 너무 거창한 것보다 작게 시작하면서 진행하는게... 마치 AI가 전시스템을 바로 개선한다는 생각은 버리고..

2) Agent MD는 “실패 패턴 교정용”으로만 사용

올바른 작성 순서.

1. 컨텍스트 없이 먼저 실행
2. 반복적으로 틀리는 지점 관찰
3. 그 실패만 정확히 겨냥한 규칙 추가
4. 효과 없으면 삭제

3) 작은 스킬 단위로 쪼개기

거대한 CLAUDE.md 하나 대신 여러개의 스킬(MD)로 운영.

현재 작업에 필요한 것만 로드. 작고 집중된 가이드가 가장 효과적이다.

4) 컨텍스트를 “계측 도구”로 활용

꽤 유용한 방법 하나. 에이전트에게 이렇게 지시한다. 막히는 지점이 있으면 이유를 기록하라. 그 로그를 보면 바로 드러난다.

• 구조 문제
• 테스트 부족
• 모호한 설계
• 잘못된 제약

문서를 고치지 말고 시스템을 고친다.