2장. CLAUDE.md - 프로젝트 지침의 핵심

CLAUDE.md는 에이전트에게 업무 맥락과 지켜야 할 경계를 전달하는 프로젝트 지침이다. 길고 포괄적인 선언보다, 실제 작업에서 확인할 수 있는 규칙이 유용하다. 정확한 파일 위치와 우선순위는 실행 전 현재 공식 문서에서 확인한다.

좋은 지침의 구성

프로젝트 목적
사용 기술과 실행·테스트 명령
수정 가능한 경로와 건드리면 안 되는 경로
완료 기준과 검토 방법
비밀값·고객 정보·외부 동작의 금지 또는 승인 기준
변경 전후에 남길 근거

예시

# 프로젝트 지침

- 목적: 공개 강의 페이지를 정확하고 접근 가능하게 유지한다.
- 변경 전: 해당 페이지, 관련 콘텐츠, 기존 테스트 방법을 먼저 읽는다.
- 완료 기준: 링크·문구·모바일 화면을 확인하고 빌드가 통과한다.
- 금지: 비밀값 추가, 고객 데이터 반입, 승인 없는 배포·삭제·외부 발송.
- 보고: 변경 파일, 검증 결과, 아직 확인하지 못한 항목을 분리해 적는다.

관리 원칙

구분	권장 방식
팀 공통 기준	저장소에서 버전 관리하고 코드 리뷰한다.
개인 환경	별도 로컬 설정으로 관리하며 커밋하지 않는다.
비밀값	지침 파일이 아니라 안전한 환경변수·비밀 관리 도구에 둔다.
예외	언제·누가·왜 허용했는지 기록하고 정기적으로 제거한다.

점검 질문

• 새 팀원이 이 파일만 읽고 테스트 방법과 금지 범위를 알 수 있는가?
• 규칙이 실제 저장소 구조·배포 흐름과 일치하는가?
• 모호한 ‘조심해서’ 대신 확인할 파일·명령·승인자가 적혀 있는가?
• 오래된 모델명, 패키지, 경로, 일정, 고객 정보가 남아 있지 않은가?

지침은 한 번 작성하고 끝나는 문서가 아니다. 오류, 새 도구, 배포 절차 변경이 생기면 실제 사례를 반영해 작고 명확하게 갱신한다.