CLAUDE.md 파일을 문서가 아닌 행동 계약으로 구조화하여 Claude Code 에이전트의 동작을 신뢰성 있게 제어하는 방법을 소개한다

Context

대부분의 개발자가 작성하는 CLAUDE.md 파일은 프로젝트 설명이 포함된 README 스타일로, 에이전트에게 프로젝트 정보를 전달하지만 행동 방식은 알려주지 않는다. 이 경우 CLAUDE.md가 없는 것과 동일한 결과를 초래한다.

Technical Solution

• CLAUDE.md 구성 시 문서화가 아닌 행동 계약 관점으로 접근한다. 프로젝트 기술보다 에이전트의 해야 할 일, 하지 말아야 할 일, 기본값으로 수행해야 할 일을 명시한다.
• 6개 섹션 구조를 적용한다. 프로젝트 정체성, 반드시 수행할 항목, 절대 하지 말아야 할 항목, 코드 스타일 규칙, 도구 권한 범위, 디렉토리 구조 및 패턴 순서로 구성한다.
• "절대 하지 말아야 할 항목" 섹션을 핵심 집중 영역으로 활용한다. 에이전트가 반복적으로 실수하는 패턴을 영구적으로 기록하여 미래 세션에서 재발을 방지한다.
• "반드시 수행할 항목"에서 추상적 지시 대신 구체적 실행 방법을 명시한다. "테스트를 작성하라"가 아닌 "새 함수는 Vitest를 사용하여 소스 파일과 같은 디렉토리의 .test.ts 파일에 happy-path 테스트와 error-case 테스트 각 1개 이상 포함해야 한다"로 작성한다.
• CLAUDE.md를 코드로 취급한다. git으로 버전 관리하고 PR 리뷰를 통해 변경 사항을 검토하며 하단부에 변경 로그를 유지한다.

Impact

구체적 행동 규칙 적용 시 에이전트가 추측에 의존하지 않고 일관된 결과를 생성한다.

Key Takeaway

추상적 지시는 에이전트가 추측하도록 하여 불일치한 결과를 초래하지만, 구체적 정책은 신뢰성 있게 따르므로 CLAUDE.md의 품질은 명시성의 정도에 따라 결정된다.