Claude Code가 내 코드를 다 엎어버리기 전에 설정해야 할 3가지

Claude Code를 터미널에 띄워두면 개발 속도가 확실히 빨라집니다. 하지만 에이전트에게 너무 넓은 자유를 주면 엉뚱한 설정 파일을 건드려 빌드를 깨뜨리거나, 단 몇 분 만에 수십 달러의 API 비용을 태워버리곤 합니다. 도구의 자율성이 오히려 개발자의 관리 리소스를 갉아먹는 셈입니다. 소규모 팀이나 개인 프로젝트를 운영한다면 에이전트의 손발을 묶어두는 최소한의 안전장치가 필요합니다.

수정 범위를 특정 폴더로 격리하기

Claude Code는 기본적으로 프로젝트 전체에 대한 읽기/쓰기 권한을 가집니다. 하지만 에이전트가 .env 파일을 읽거나 루트의 복잡한 설정 파일을 마음대로 수정하게 두는 건 위험합니다. Anthropic의 권한 시스템은 거부(Deny) 규칙이 가장 강력하게 작동하므로, 이를 활용해 에이전트의 활동 반경을 물리적으로 제한해야 합니다.

1. 프로젝트 루트에 .clauderules 파일을 만듭니다.
2. Edit(/src/features/**/*.ts)처럼 정규 표현식을 써서 에이전트가 건드릴 수 있는 디렉토리를 화이트리스트로 묶으세요.
3. Deny(Read(./*.env)) 규칙을 추가해 민감한 정보 근처에는 아예 가지 못하게 막아야 합니다.

이렇게 설정하면 에이전트가 허용되지 않은 경로를 수정하려 할 때 시스템이 즉각 차단합니다. 엉뚱한 파일을 건드려서 발생하는 빌드 오류를 원천 봉쇄할 수 있습니다.

컨텍스트 윈도우 다이어트로 비용 절감하기

비용 폭탄은 대개 무분별한 파일 읽기에서 시작됩니다. node_modules나 package-lock.json 같은 거대 파일을 에이전트가 읽기 시작하면 토큰 수십만 개가 순식간에 사라집니다. Anthropic의 데이터에 따르면 제대로 된 .claudeignore 설정만으로도 API 지출의 40% 이상을 줄일 수 있습니다.

• .claudeignore 파일에 dist/, build/, node_modules/를 반드시 추가하세요.
• 구조 파악에는 필요하지만 수정할 일은 없는 대용량 json 파일도 목록에 넣어야 합니다.
• 에이전트에게 명령을 내릴 때 claude select [파일명]을 써서 필요한 파일만 딱 집어주는 습관을 들이세요.

최신 모델은 프롬프트 캐싱을 지원해서 캐시된 토큰은 신규 토큰보다 90% 저렴합니다. 작업 도중 /cost 명령어를 수시로 입력해 캐시 적중률을 확인하는 것만으로도 월말 영수증의 숫자가 달라집니다.

100줄 이상의 과잉 수정을 막는 검역 절차

에이전트가 한 번에 수백 줄의 코드를 리팩토링하게 두면 리뷰하기가 불가능해집니다. Claude Code의 훅(Hooks) 기능을 써서 변경 사항이 너무 크면 자동으로 승인을 거절하는 가드레일을 세워야 합니다.

.claude/hooks/check-diff-size.sh 스크립트를 하나 만드세요. git diff --stat 명령으로 변경된 라인 수를 체크해서 100줄이 넘어가면 exit 2를 뱉게 하면 됩니다. 에이전트가 대규모 수정을 시도할 때 강제로 멈춰 세우고 부분 커밋을 유도하는 방식입니다. 스크립트 마지막에 npm test를 넣어두면 테스트를 통과하지 못한 코드가 스테이징에 올라가는 일도 막을 수 있습니다.

에이전트 전용 브랜치 운영하기

인간과 AI가 같은 브랜치에서 섞여 작업하면 깃 히스토리는 순식간에 엉망이 됩니다. Stripe 같은 기술 기업들은 에이전트에게 무조건 전용 브랜치를 할당하고 PR(Pull Request) 과정을 거치게 합니다. 이 단순한 규칙이 배포 주기를 앞당기면서도 코드 퀄리티를 유지하는 비결입니다.

CLAUDE.md에 "작업 시작 전 반드시 agent/ 접두사가 붙은 브랜치를 생성하라"고 명시하세요. 에이전트가 작업을 마치면 gh pr create --draft를 실행해 초안 PR을 올리게 시키면 됩니다. 내가 직접 코드를 훑어보고 머지한 뒤 브랜치를 삭제하는 구조가 가장 안전합니다. 에이전트를 동료 개발자로 대우하되, 최종 결재권은 내가 쥐고 있다는 사실을 명확히 하는 셈입니다.