Claude Code가 프로젝트마다 같은 실수를 반복하거나, 중요한 제약을 모른 채 코드를 바꾼다면 무엇부터 손봐야 할까요? 먼저 프로젝트에 꼭 필요한 정보를 CLAUDE.md에 적고, 실행으로 확인할 수 있는 규칙은 테스트와 권한 설정으로 뒷받침하는 것이 좋습니다. 지침은 행동의 방향을 제시하지만 모든 행동을 강제로 막는 보안 장치는 아닙니다.
CLAUDE.md는 프로젝트의 작업 설명서입니다
CLAUDE.md는 개발자가 작성하는 지속적인 지침 파일입니다. 프로젝트의 빌드·테스트 명령, 자주 놓치는 제약, 코드 구조처럼 매번 대화에서 반복하기 어려운 내용을 담습니다. 반면 자동 메모리는 Claude가 대화에서 배운 선호나 교정 사항을 기록하는 별도의 기능입니다. 공식 메모리 문서는 두 정보를 모두 모델에 전달되는 맥락으로 설명하며, 지침 준수가 보장되지는 않는다고 밝힙니다.
예를 들어 테스트 명령을 몰라 검증을 빠뜨리는 문제가 반복된다면, 장황한 철학보다 실제 실행할 명령과 실패 시 보고 기준을 적는 편이 유용합니다. 아래는 가상의 프로젝트 예시이므로 실제 명령으로 바꿔야 합니다.
# 프로젝트 작업 기준
- 변경 전 관련 코드를 읽고 기존 동작을 확인한다.
- 프런트엔드 수정 후 `npm run test`를 실행한다.
- 실행할 수 없는 검사는 완료라고 쓰지 말고 이유를 보고한다.
- 요구사항에 중대한 위험이 있으면 근거와 대안을 설명한다.
프로젝트 공통 지침과 폴더별 규칙은 어떻게 나눌까요?
팀 전체가 공유할 내용은 프로젝트의 CLAUDE.md에 두고, 개인적인 선호는 사용자 범위 지침에 둘 수 있습니다. 특정 영역에만 적용되는 규칙은 .claude/rules/ 파일에 paths 조건을 지정할 수 있습니다. 조건 없이 파일을 넣으면 폴더 이름만으로 해당 영역에 자동 한정되는 것은 아닙니다. 사용 중인 버전과 설정에 따라 로드 범위를 공식 문서에서 확인하세요.
---
paths:
- "src/api/**/*.ts"
---
# API 변경 기준
- 입력 검증과 오류 응답을 기존 패턴과 비교한다.
- 관련 테스트를 실행하고 실패 여부를 보고한다.
파일을 나누는 목적은 규칙을 적절한 작업에 맞게 전달하고 관리하기 쉽게 만드는 것입니다. 원문에서 제시한 ‘지침 150~200개가 한계’나 ‘규칙 파일이 도구 실행마다 무조건 재주입돼 비용이 몇 배로 증가한다’는 수치는 보편적으로 확인할 근거가 부족합니다. 실제 비용은 모델, 지침 크기, 캐시와 작업 방식에 따라 따로 측정해야 합니다.
좋은 대안을 제안하게 하려면
원문은 에이전트가 지시를 그대로 따르기만 하지 않고 더 나은 방법을 말하게 하자는 문제의식을 담고 있습니다. 다만 모든 작은 작업마다 의견을 묻도록 하면 진행이 끊길 수 있습니다. 다음처럼 언제 제안하고 언제 계속할지 함께 적어 보세요.
요구사항에 기존 데이터 손실이나 호환성 문제가 예상되면 근거와 대안을 알려 주세요.
사소하고 되돌릴 수 있는 선택은 프로젝트의 기존 방식에 맞춰 진행하고,
검증 결과와 남은 불확실성을 마지막에 설명해 주세요.
이 문구도 제안이 실제로 나올 것을 보장하지는 않습니다. 같은 작업을 새 세션에서 여러 번 실행해 지침을 읽었는지, 필요한 검증을 수행했는지 비교하고 모호한 규칙을 고치는 것이 중요합니다.
훅과 권한 설정은 언제 필요할까요?
비밀 파일 접근 제한이나 필수 검증처럼 빠지면 곤란한 조건은 자연어 지시만으로 맡기기 어렵습니다. Claude Code의 훅은 정해진 이벤트에서 명령을 실행하거나 특정 도구 사용을 차단할 수 있습니다. 권한 규칙, 샌드박스, CI 검사도 목적에 따라 함께 사용합니다. 공식 훅 가이드와 실무 권장 사항을 참고하세요.
다만 훅은 설정된 이벤트와 범위에서 작동합니다. 잘못된 경로 패턴, 설정 오류, 권한과 실행 환경의 차이가 남을 수 있으므로 ‘훅을 설정하면 100% 안전하다’고 볼 수 없습니다. 보호하려는 파일로 실제 차단 시험을 하고, 정상 작업은 허용되는지와 CI·운영 환경에서도 같은 정책이 적용되는지 확인해야 합니다.
시작하기 전 점검할 것
1. 최근 반복된 실수 하나를 고르고 Claude가 알 수 없었던 정보를 적습니다. 2. 공통 지침을 짧고 구체적으로 작성합니다. 영역별 규칙에는 필요한 경우 경로 조건을 설정합니다. 3. 지침이 반영됐는지 새 세션에서 같은 작업으로 확인합니다. 4. 반드시 막아야 하는 행동은 권한·훅·샌드박스 등 적합한 통제로 시험합니다. 5. 지침이 길어지면 실제로 유용한 항목과 오래된 항목을 정기적으로 검토합니다.
자주 묻는 질문
CLAUDE.md만 있으면 AI의 코드 변경을 믿어도 되나요?
아닙니다. 지침은 코딩 방향을 알려 주는 맥락입니다. 변경 결과를 테스트하고 사람이 검토해야 합니다. 검증 경계를 더 자세히 보려면 AI 코드 리뷰와 사람의 검증 기준을 함께 읽어 보세요.
자동 메모리와 CLAUDE.md는 같은 파일인가요?
아닙니다. 하나는 사용자가 작성하는 지침이고 다른 하나는 Claude가 학습한 내용을 기록하는 메모리입니다. 저장 위치와 적용 설정은 환경에 따라 확인해야 합니다.
규칙을 많이 쓰면 반드시 성능이 떨어지나요?
고정된 개수만으로 판단할 근거는 없습니다. 중복되거나 모순된 지침은 관리가 어렵고 맥락을 차지하므로, 실제 작업에 필요한지와 동작을 확인하며 정리하세요.
참고 자료: Claude Code 메모리와 지침, 훅 사용 가이드, Claude Code 실무 권장 사항. 확인일: 2026년 11월 6일.
다음 한 걸음
내 환경에서 막힌 부분은 실행 단계와 함께 질문해 주세요. 바꿔 만든 결과도 함께 나눌 수 있습니다.