AI 코딩 에이전트 효율 높이는 'CLAUDE.md' 작성법 공개...지시사항 줄이고 보편성 높여야

[한국정보기술신문] AI 코딩 에이전트의 성능을 최적화하는 핵심 문서 작성법이 공개됐다. 미국 AI 개발 플랫폼 휴먼레이어는 25일 공식 블로그를 통해 클로드 코드 등 AI 코딩 도구에서 사용하는 CLAUDE.md 파일의 효과적인 작성 방법을 제시했다.

CLAUDE.md는 AI 코딩 에이전트가 프로젝트에 참여할 때 기본적으로 읽어들이는 가이드 문서다. 대형언어모델(LLM)은 세션마다 상태를 유지하지 않기 때문에 매번 코드베이스에 대한 정보를 새로 제공받아야 한다. CLAUDE.md는 이러한 온보딩 과정을 자동화하는 유일한 수단이다.

휴먼레이어는 이번 가이드에서 LLM의 명령어 처리 한계를 구체적으로 제시했다. 최신 사고형 LLM도 150개에서 200개의 명령어만 일관되게 처리할 수 있으며, 작은 모델은 더 적은 수의 명령어만 처리 가능하다는 것이다. 클로드 코드의 시스템 프롬프트만으로도 이미 약 50개의 명령어가 사용되고 있어 사용자가 추가할 수 있는 여유분은 제한적이다.

휴먼레이어는 CLAUDE.md 파일에 모든 가능한 명령어를 담으려는 시도를 경계했다. 명령어 수가 증가할수록 LLM의 명령 수행 품질이 균등하게 감소한다는 연구 결과를 인용하며, 보편적으로 적용 가능한 최소한의 명령어만 포함해야 한다고 강조했다.

클로드 코드는 시스템적으로 CLAUDE.md 내용의 관련성을 판단해 현재 작업과 무관하다고 판단되면 해당 내용을 무시하도록 설계됐다. 이는 많은 사용자가 특정 상황에만 적용되는 임시 해결책을 CLAUDE.md에 계속 추가하면서 발생한 성능 저하를 방지하기 위한 조치다.

대규모 프로젝트에서 간결한 CLAUDE.md를 유지하는 방법으로 점진적 공개 원칙이 제시됐다. 프로젝트 빌드, 테스트 실행, 코드 규칙 등 작업별 세부 지침을 별도 마크다운 파일로 분리하고, CLAUDE.md에는 이들 파일의 목록과 간단한 설명만 포함하는 방식이다.

휴먼레이어는 자사의 CLAUDE.md 파일이 60줄 미만으로 구성돼 있으며, 일반적으로 300줄 이하를 권장한다고 밝혔다. 파일 내에는 코드 스니펫 대신 특정 파일과 줄 번호를 참조하도록 해 정보의 최신성을 유지해야 한다고 덧붙였다.

특히 주목할 점은 코드 스타일 가이드라인을 CLAUDE.md에 포함하지 말라는 권고다. LLM은 린터나 포매터에 비해 느리고 비용이 높으며, LLM은 기존 코드 패턴을 학습해 자연스럽게 따라하는 능력이 있기 때문이다.

대신 클로드 코드의 스톱 훅 기능을 활용해 자동으로 포매터와 린터를 실행하고, 오류가 있을 때만 AI에게 수정을 요청하는 방식을 제안했다. 구현과 포매팅을 분리하면 두 작업 모두에서 더 나은 결과를 얻을 수 있다는 설명이다.

휴먼레이어는 CLAUDE.md 파일의 자동 생성 기능 사용도 피해야 한다고 강조했다. 이 파일은 모든 세션에 영향을 미치는 가장 높은 레버리지 포인트이므로, 각 줄을 신중하게 작성해야 한다는 이유에서다.

이번 가이드는 클로드 코드뿐 아니라 오픈코드 기반의 다른 AI 코딩 도구에서 사용하는 AGENTS.md 파일에도 동일하게 적용될 수 있다. 휴먼레이어는 컨텍스트 엔지니어링 모범 사례에 기반한 이번 권고사항이 AI 코딩 에이전트의 실질적인 성능 향상으로 이어질 것으로 기대했다.