CLAUDE.md와 AGENTS.md 제대로 사용하기

AI 코딩 에이전트 쓸 때 프로젝트 루트에 CLAUDE.md나 AGENTS.md 같은 파일 두는 게 일반적이다. 클로드 코드를 쓰면 init 명령어로 이 파일을 자동 생성할 수도 있는데, 써 본 결과 이 방식은 오히려 독이 됐다.

불필요한 내용이 있으면 컨텍스트를 차지하고 토큰만 낭비하며 AI를 멍청하게 만든다. ETH Zurich 연구팀이 테스트한 결과를 보니, LLM이 자동 생성한 컨텍스트 파일은 작업 성공률을 2~3% 떨어뜨리고 비용은 20% 이상 증가시켰다. 이유는 단순하다. 자동 생성된 파일에는 에이전트가 코드를 읽으면 스스로 알 수 있는 정보가 대부분이기 때문이다.

docker-compose.yml이 있다는 사실, src 디렉토리 구조, 사용 중인 프레임워크 이름 같은 것은 에이전트가 grep 한 번이면 다 파악한다. 이걸 CLAUDE.md에 다 적어두면 컨텍스트 윈도우만 차지하고 토큰만 낭비할 뿐이다. 더 나쁜 건 앵커링 효과다. 문서에 레거시 패턴을 언급해 두면, 더 좋은 대안이 있어도 에이전트는 그 패턴에 고착된다.

그럼 꼭 필요한 내용은 뭘까. 에이전트가 코드를 읽어서는 절대 알 수 없는 정보여야 한다. 예를 들어 특정 모듈은 표준 방식이 아닌 커스텀 미들웨어를 쓴다든지, 테스트를 돌릴 때는 꼭 --no-cache 플래그를 붙여야 한다든지 하는 것이다. 이런 정보는 코드만 봐서는 알 수 없다. 도구를 문서에 언급하면 에이전트가 작업당 1.6~2.5회 사용하는데, 미문서화하면 0.05회 미만으로 떨어진다.

결국 init 명령어로 만들지 말고, 작업하면서 실수하는 부분을 추가해서 에이전트가 기억하도록 하는 방식이 최선인 것 같다. 에이전트가 반복해서 틀리는 부분을 그때그때 적어두는 거다. 이건 코드베이스가 불명확하다는 신호이므로, 나중에 근본 원인을 고치고 나면 그 줄은 삭제하면 된다.

CLAUDE.md는 영구 설정이 아니라 진단 도구로 봐야 한다. 에이전트가 신입 사원처럼 사무실 투어나 조직도가 필요한 게 아니다. 프롬프트를 다 입력하기도 전에 코드베이스 전체를 탐색할 수 있는 능력이 있는데, 필요한 건 지도가 아니라 지뢰의 위치다.