클로드 코드 설정 팁 3가지: 반복 설명·권한 관리·검사 자동화

클로드 코드 설정은 세 단계로 잡으면 정리가 쉽습니다. 반복해서 설명하던 내용은 CLAUDE.md에 저장하고, 실행 권한은 settings.json에서 관리하고, 반복 검사는 훅으로 연결해요. CLAUDE.md는 작업 원칙을 전달하고, 권한 설정은 도구 실행을 허용하거나 막고, 훅은 정해진 시점에 무언가를 자동으로 실행합니다.

같은 '테스트 실행'이라도 어디에 넣느냐에 따라 맡는 일이 달라집니다. 언제 어떤 테스트를 돌릴지는 CLAUDE.md에 적어요. 그 명령을 승인 없이 실행해도 되는지는 권한 설정에서 정하고, 검사를 실행할 시점은 훅에 연결합니다. 저는 작업 규칙부터 보시길 권합니다. 무엇을 실행할지가 정해져야 어디까지 허용할지, 무엇을 자동화할지도 구체적으로 정할 수 있기 때문입니다.

1. CLAUDE.md에는 무엇을 적어야 할까

CLAUDE.md에는 실제로 쓰는 빌드·테스트 명령과 프로젝트 고유의 제약을 남깁니다. 시작은 /init으로 초안을 만드는 것이 편해요. 다만 초안에 적힌 명령이 프로젝트에서 실제로 쓰는 명령과 맞는지는 직접 확인하고 규칙을 다듬어야 합니다. 초안에 내용을 계속 덧붙이기보다, 작업할 때마다 다시 설명하던 내용부터 추려 넣는 편이 낫습니다.

흔히 하는 실수는 "꼼꼼히 테스트해 주세요" 같은 당부를 적는 것입니다. 이런 문장으로는 테스트를 했는지 안 했는지 판단하기 어렵습니다. 정확한 테스트 명령과 어떤 변경 뒤에 실행할지를 함께 적어 두면 결과를 확인하기가 훨씬 쉬워져요. 프로젝트 고유의 제약도 마찬가지로, 무엇을 지켜야 하는지가 구체적으로 읽히게 써야 합니다.

분량보다 먼저 볼 것은 필요한 규칙을 쉽게 찾을 수 있느냐입니다.

공식 문서에 나오는 파일당 200줄 미만은 작성 권장량입니다. 그보다 길면 읽지 않는다는 제한으로 오해하는 경우가 있는데, 그런 뜻은 아니에요. 중복된 지침을 줄이고 실제 작업에 필요한 내용을 앞에 두세요. 작성 방식은 공식 메모리 문서에서 확인할 수 있습니다. 한 가지 짚어 두면, 자연어로 금지 사항을 적는 것과 도구의 실행 권한을 제한하는 것은 서로 다른 일입니다. 실제로 막아야 하는 작업은 다음 단계의 권한 설정에서 다룹니다.

2. 권한 설정은 어느 파일에 넣어야 할까

권한 값을 바꾸기 전에 이 설정이 누구에게 적용돼야 하는지부터 정하세요. 개인에게만 필요한 설정을 공유 파일에 넣거나, 반대로 개인 파일에 저장해 놓고 동료에게도 적용됐다고 착각하기 쉽습니다. 파일 위치에 따라 적용 범위는 이렇게 나뉩니다.

• ~/.claude/settings.json: 해당 기기의 개인 공통 설정
• .claude/settings.json: 프로젝트의 팀 공유 설정
• .claude/settings.local.json: 프로젝트별 개인 설정

팀과 공유할 설정은 저장소에 커밋해야 동료에게 전달됩니다. 프로젝트 개인용 파일을 직접 만들었다면 .gitignore에 등록돼 있는지도 확인해 두세요. 동료와 동작이 다를 때 설정값부터 비교하는 경우가 많습니다. 하지만 파일 위치와 공유 여부를 먼저 살펴보는 편이 원인을 더 빨리 좁혀 줍니다.

위치를 정했다면 /permissions에서 현재 규칙과 각 규칙의 출처 파일을 확인합니다. 그다음 자주 쓰는 명령에 한정해 허용 범위를 정해요. allow는 수동 승인 없이 허용하고, ask는 확인을 요청하며, deny는 실행을 차단합니다. 승인 요청을 줄이고 싶다면 반복해서 쓰는 작업부터 구체적으로 허용하는 것이 좋습니다.

가장 헷갈리는 부분은 평가 순서입니다. 권한은 deny → ask → allow 순으로 평가되므로, 넓은 차단 규칙을 좁은 허용 규칙으로 덮을 수 없어요. 테스트 명령을 허용했는데도 막힌다면 그 명령을 포함하는 차단 규칙이 있는지부터 찾아보세요. 세부 설정은 공식 권한 문서를 기준으로 맞추면 됩니다.

3. 훅으로 검사를 자동화할 때 무엇을 확인할까

훅은 도구 실행 전후처럼 정해진 이벤트에 자동 동작을 연결하는 기능입니다. 작업 규칙과 권한이 정리됐다면, 반복 검사 가운데 어떤 작업을 어느 시점에 실행할지 고를 차례예요. 이때 검사 명령만 볼 것이 아니라 실행 대상과 실패했을 때의 처리까지 함께 정해야 합니다.

예를 들어 PostToolUse에서 Edit|Write를 대상으로 지정하면, 해당 편집 도구가 성공적으로 실행된 뒤에 검사를 붙일 수 있습니다. 여기서 놓치기 쉬운 점이 있습니다. 이 설정은 Bash 명령이나 외부 프로세스가 일으킨 파일 변경까지 감지하지는 않아요. 평소 파일이 수정되는 경로가 훅의 대상에 들어 있는지 확인해야 검사가 빠지는 일을 줄일 수 있습니다.

PostToolUse는 이미 끝난 도구 실행을 되돌리거나 미리 막는 용도로 쓰는 이벤트가 아닙니다. 실행 전에 제어해야 한다면 PreToolUse를 검토하세요. 두 이벤트의 차이와 설정 방식은 공식 훅 문서에 정리돼 있습니다.

마지막으로, 훅이 실행됐다는 것과 검사가 통과했다는 것은 별개의 사실입니다. 검사가 실패했을 때 그 결과가 어떻게 전달되고 이후 작업에서 어떻게 처리되는지까지 확인해 두어야 반복 검사 자동화가 실제로 도움이 됩니다.