증상: Claude Code가 요청하지 않은 파일까지 수정한다면, CLAUDE.md와 권한 설정이 서로 다른 역할을 한다는 점부터 확인하세요. Claude 공식 문서는 프로젝트 지침과 권한 설정을 별도로 설명합니다.
빠른 해법: 변경 범위, 사전 계획, 최소 수정, 검증 보고를 CLAUDE.md에 구체적으로 적고 실제 변경은 diff와 권한 설정으로 확인하세요.
이 글은 Claude Code가 작업 범위를 넘는 문제를 줄이고 싶은 개발자, 팀의 CLAUDE.md 규칙을 정하려는 기술 책임자, Andrej Karpathy Skills를 프로젝트 작업 방식에 적용하려는 엔지니어를 위한 내용입니다.
CLAUDE.md로 Claude Code의 변경 범위를 제한하는 기준
CLAUDE.md는 프로젝트에 적용할 지침을 제공해 Claude Code가 작업할 때 참고하도록 합니다. 공식 문서는 이를 프로젝트 메모리의 한 종류로 다룹니다. 다만 지침을 적었다고 해서 파일 접근이 기술적으로 차단되거나, 모든 지시가 언제나 정확히 지켜진다고 보장되는 것은 아닙니다. 권한 문서는 파일 변경 등 도구 사용 권한을 별도로 다룹니다.
따라서 두 수단을 혼동하지 않는 것이 출발점입니다.
| 선택지 | 주로 하는 일 | 언제 선택할까 |
|---|---|---|
| CLAUDE.md | 프로젝트 맥락과 작업 규칙을 전달합니다. 프로젝트 메모리 안내를 참고해 프로젝트 지침으로 관리하세요. | 작업 범위, 코드 스타일, 검증 절차를 일관되게 안내할 때 |
| 권한 설정 | 파일 변경이나 도구 사용에 관한 접근을 제어합니다. 공식 권한 안내에서 필요한 설정을 확인하세요. | 지침으로 요청하는 데 그치지 않고 접근을 제한해야 할 때 |
| 코드 리뷰와 버전 관리 | 실제 변경 내용을 검토하고 추적합니다. | 지침 준수 여부와 최종 결과를 확인할 때 |
이번 글의 네 가지 규칙은 Claude 공식 보장이나 Andrej Karpathy의 직접 인용이 아니라, 프로젝트에 맞게 작성할 수 있는 실무 제안입니다. Claude Code의 권한 기능은 공식 권한 안내에서 따로 확인하고, 지침과 접근 제어를 함께 운용하세요.
Andrej Karpathy Skills를 프로젝트 지침과 구분하기
Andrej Karpathy의 관련 발언은 원문 게시물에서 확인할 수 있고, 이를 바탕으로 한 프로젝트는 공개 저장소에 정리돼 있습니다. 이를 Claude Code의 공식 규칙이나 Karpathy가 직접 제안한 CLAUDE.md 템플릿으로 단정해서는 안 됩니다. 제목의 Skills와 여기서 소개하는 네 가지 규칙은 같은 설정 기능을 뜻하지 않습니다.
Claude Code의 Skills 역시 CLAUDE.md와 구별되는 기능입니다. Claude 공식 Skills 문서를 살펴보고, 사용하려는 기능의 역할을 확인하세요. 핵심은 이름을 그대로 옮기는 것이 아니라 현재 코드베이스, 작업 권한, 검증 방법에 맞춰 지침을 다시 쓰는 것입니다.
첫 번째 규칙: 수정할 파일과 작업 경계를 지정하기
막연히 “필요한 부분을 고쳐 주세요”라고 쓰면 무엇이 필요한지 해석하는 범위가 넓어집니다. 목표와 허용 파일을 먼저 정하고, 범위 밖의 문제를 발견했을 때 처리 방법도 적어 두세요.
- 이번 요청의 목표를 해결하는 데 필요한 파일만 수정합니다.
- 허용된 파일 밖의 변경이나 무관한 설정 수정은 하지 않습니다.
- 추가 파일 수정이 필요하면 이유와 대상 파일을 먼저 설명하고 확인을 요청합니다.
- 요청과 관련 없는 리팩터링은 수행하지 않습니다.
파일 이름을 확정할 수 없는 작업이라면 허용 디렉터리나 수정 금지 영역을 적을 수 있습니다. 다만 실제 접근을 막는 장치가 필요하다면 CLAUDE.md 문구에만 의존하지 마세요. Claude Code 권한 설정을 별도로 검토해야 합니다.
두 번째 규칙: 코드 변경 전에 계획을 확인하기
계획을 먼저 말하게 하면 요청을 어떻게 이해했는지, 어느 파일을 바꿀지, 결과를 무엇으로 확인할지 변경 전에 점검할 수 있습니다. 계획 자체가 올바른 구현을 보장하지는 않지만, 범위가 어긋난 채 곧바로 수정하는 일을 발견할 기회를 줍니다.
예를 들어 오류 메시지를 다루는 작은 수정이라면, 우선 원인으로 이해한 내용과 수정할 위치, 사용할 검증 방법을 설명하게 합니다. 계획에 요청되지 않은 설정 파일이나 추가 모듈이 들어 있다면 실행 전에 확인을 받으세요. 범위가 분명하고 계획을 승인한 뒤에만 수정을 진행하도록 CLAUDE.md에 적을 수 있습니다.
세 번째 규칙: 필요한 만큼만 바꾸기
AI의 무분별한 코드 수정을 줄이려면 “최소 변경”을 구체적인 행동으로 정의해야 합니다. 기존 구조와 코딩 스타일을 따르고, 요청을 해결하는 데 필요하지 않은 의존성 교체나 아키텍처 변경은 하지 않도록 합니다. 그렇다고 필요한 오류 수정이나 요청에 포함된 관련 변경까지 생략하라는 뜻은 아닙니다.
작업 전후에 다음 항목을 대조하세요.
- 변경된 파일이 처음 정한 허용 범위 안에 있나요?
- diff에 요청과 관계없는 정리나 이름 변경이 끼어 있나요?
- 새 파일이나 설정 변경이 필요했다면 이유를 설명하고 확인받았나요?
최소 diff는 품질 기준이 아니라 범위 점검 방법입니다. 필요한 수정이 빠졌다면 이유를 확인하고 보완해야 합니다.
자주 생기는 범위와 검증 질문
지정한 파일만 수정하도록 쓸 수 있나요? CLAUDE.md에는 허용 파일을 명시하고, 그 밖의 수정이 필요하면 먼저 확인하라고 쓸 수 있습니다. 이는 작업 지침이지 접근 차단은 아닙니다. 파일 변경을 강제로 제한해야 할 때는 권한 설정을 함께 검토하고, 완료 뒤 실제 변경 파일을 확인하세요.
어떤 규칙이 무관한 코드 변경을 줄이나요? 요청에 필요한 변경만 허용하고, 기존 구조와 스타일을 따르며, 무관한 리팩터링과 의존성 교체를 금지한다고 구체화하세요. 범위가 불명확하면 먼저 질문하고, 계획에 새 파일이 포함되면 수정 전에 승인을 요청하도록 합니다. 프로젝트별 예외도 함께 적어야 규칙의 해석이 흔들리지 않습니다.
확인받지 않은 수정 자체를 막을 수 있나요? CLAUDE.md만으로는 보장할 수 없습니다. 지침은 행동을 안내하지만 권한 통제를 대신하지 않습니다. 위험한 변경을 실제로 제한하려면 권한 설정을 적용 가능한 방식으로 구성하고, 버전 관리와 검토 절차를 유지하세요.
검증 보고에는 무엇을 포함해야 하나요? 프로젝트에서 실제로 사용하는 테스트, 빌드, 정적 검사 가운데 해당 변경에 적용할 수 있는 절차를 실행하도록 요구하세요. 실행한 항목과 결과, 실행하지 못한 항목과 이유를 나눠 보고하게 합니다. 프로젝트의 설정을 확인하지 않은 상태에서 특정 명령을 지시하지 말고, 실행하지 않은 검사를 통과했다고 표현하지 않도록 명시하세요.
네 번째 규칙: 결과를 검증하고 실제 실행 내용을 보고하기
CLAUDE.md에는 프로젝트가 이미 사용하는 테스트와 빌드 절차를 기준으로 검증하라고 적으세요. 적용 가능한 검사를 실행한 뒤 실제 결과를 보고하고, 실행하지 못한 항목은 이유를 밝히도록 합니다. 프로젝트에 없는 명령을 만들어 실행하게 하거나, 실행하지 않은 검사를 통과했다고 말하게 해서는 안 됩니다.
Claude Code의 변경을 확인하는 작업 방식은 공식 모범 사례 문서도 참고할 수 있습니다. 다만 어떤 검사가 맞는지는 프로젝트의 실제 구성에서 확인해야 합니다.
- 변경 내용에 맞는 프로젝트의 기존 검증 절차를 실행합니다.
- 실행한 검사와 실제 결과를 구분해 보고합니다.
- 실행하지 못한 검사는 항목과 이유를 밝힙니다.
- 실행하지 않은 검사를 통과했다고 보고하지 않습니다.
작은 작업으로 규칙을 시험하고 CLAUDE.md를 다듬기
한 번에 여러 영역을 고치는 큰 요청보다 범위가 분명한 작은 작업으로 규칙을 확인하세요. 프로젝트에서 실행하는 테스트나 검사 방법은 저장소의 설정과 팀 절차를 먼저 확인한 뒤 선택합니다.
- 파일 범위와 완료 조건이 분명한 작업 하나를 고릅니다.
- Claude Code가 변경 전에 목표, 수정 위치, 검증 방법을 계획하도록 합니다.
- 계획과 실제 변경 파일을 비교하고, 추가 파일이 생겼다면 사전 확인을 받았는지 살핍니다.
- diff에서 불필요한 수정과 필요한 변경의 누락을 함께 점검합니다.
- 실제 실행된 검증과 결과를 확인한 뒤, 모호하거나 서로 충돌하는 CLAUDE.md 규칙을 고칩니다.
이 과정은 CLAUDE.md가 모든 잘못된 수정을 막는지 시험하는 절차가 아닙니다. 규칙이 팀의 작업을 더 예측 가능하게 안내하는지 확인하는 점검입니다. 검토와 버전 관리, 필요한 권한 설정을 계속 병행해야 합니다.
현재 작업 환경이 공유 장비이거나 임시 검증용 환경이 필요하다면, 설정을 직접 관리하는 부담과 별도 환경을 마련하는 비용을 비교해 보세요. 기존 환경에서 작업하면 사용 중인 시스템의 자원을 함께 고려해야 하고, 원격 환경을 쓰면 프로젝트가 기대하는 운영 환경과 맞는지 확인해야 합니다. 원격 Mac 환경의 연결과 지원 조건을 살펴보려면 Mac 지원 안내도 확인할 수 있습니다. 이런 조건에서 잠깐 사용할 Mac 개발 환경이 필요하다면 Kvmkit 맥 미니 대여를 검토할 수 있습니다. 장기간 고정된 작업에 계속 투입하거나 물리 장비 연결이 필요한 경우에는 직접 보유한 장비가 더 적합할 수 있습니다. 우선 기존 CLAUDE.md를 점검하고 작은 작업으로 규칙을 시험한 뒤, 별도 Mac 환경이 필요한 경우에만 대여를 비교하세요.
자주 묻는 질문
CLAUDE.md에 지정한 파일만 수정하도록 적으면 다른 파일은 건드리지 않나요?
CLAUDE.md는 프로젝트 지침을 전달하는 수단이지 파일 접근을 차단하는 권한 설정은 아닙니다. 지정 파일만 수정하라고 명시하면 작업 범위를 이해시키는 데 도움이 되지만, 실제 차단이 필요하면 Claude Code의 권한 설정을 별도로 검토해야 합니다. 작업 후 변경 파일 목록과 diff도 확인하세요.
Claude Code가 코드를 크게 바꾸지 않게 하려면 어떤 규칙을 적어야 하나요?
요청을 해결하는 데 필요한 변경만 하도록 하고, 무관한 리팩터링이나 의존성 교체는 하지 말라고 적으세요. 허용된 파일과 디렉터리, 추가 수정이 필요할 때 확인을 요청하는 조건도 함께 정합니다. 규칙은 프로젝트의 기존 구조와 작업 방식에 맞춰 구체적으로 작성해야 합니다.
CLAUDE.md만으로 확인받지 않은 코드 수정을 막을 수 있나요?
아니요. 지침은 작업 방식을 유도하지만 보안 경계처럼 행동을 강제로 차단한다고 볼 수 없습니다. 승인 전 실행이나 파일 변경을 실제로 제한해야 한다면 권한 설정을 확인하고, 변경 사항은 버전 관리와 코드 리뷰로 점검하세요. 두 방식을 서로 대체재로 취급하지 않는 것이 중요합니다.
Claude Code가 수정한 코드의 테스트 결과를 CLAUDE.md에 어떻게 요구하나요?
프로젝트에서 실제 사용하는 테스트나 빌드 절차를 기준으로, 적용 가능한 검증을 실행하고 결과를 보고하라고 적으세요. 실행한 명령과 통과·실패 여부, 실행하지 못한 항목과 이유를 구분하도록 요청하면 됩니다. 프로젝트에 근거가 없는 명령을 지어내거나 실행하지 않은 검사를 통과했다고 보고하지 않도록 명시하세요.