AI에게 맡긴 규칙, 지침 파일과 훅 중 어디에 적을까
AI와 일하기6분 분량
코딩 AI에게 프로젝트 규칙을 알려 주는 지침 파일(CLAUDE.md)의 특징과 한계, 반드시 지켜야 할 규칙을 훅으로 옮기는 기준을 공식 문서를 바탕으로 정리했습니다.
코딩 AI를 쓰다 보면 같은 설명을 세션마다 반복하게 됩니다. 테스트는 어떤 명령으로 돌리는지, 들여쓰기는 몇 칸인지 같은 내용입니다. 이 글에서는 이런 설명을 파일로 적어 두는 지침 파일이 무엇인지, 그리고 지침 파일에 적어도 지켜지지 않을 때 규칙을 어디로 옮겨야 하는지를 정리합니다. 내용은 Claude Code 공식 문서를 확인한 것이고, 제가 직접 측정한 결과는 아닙니다.
지침 파일이 하는 일
Claude Code는 세션을 시작할 때마다 대화 내용이 비어 있는 상태로 출발합니다. 어제 알려 준 규칙을 오늘은 모릅니다. 이 간격을 메우는 방법 중 하나가 프로젝트 폴더에 CLAUDE.md 파일을 두는 것입니다. 이 파일은 세션이 시작될 때 읽혀서 AI가 참고하는 배경 지식이 됩니다.
파일은 범위에 따라 여러 곳에 둘 수 있습니다. 문서에 따르면 프로젝트 전체에 적용할 내용은 프로젝트 폴더의 CLAUDE.md에, 내 컴퓨터의 모든 프로젝트에 적용할 취향은 사용자 폴더의 ~/.claude/CLAUDE.md에, 팀과 공유하지 않을 개인 설정은 CLAUDE.local.md에 둡니다. 개인용 파일은 .gitignore에 넣어 저장소에 올라가지 않게 하라고 안내합니다.
처음 만들 때는 /init 명령이 도움이 됩니다. 코드를 살펴보고 빌드 명령, 테스트 방법, 관례를 정리한 초안을 만들어 줍니다. 문서는 여기서 멈추지 말고 AI가 코드만 봐서는 알아내기 어려운 내용을 직접 더하라고 권합니다.
잘 적는 요령
공식 문서가 강조하는 점은 크게 세 가지입니다.
첫째는 구체성입니다. "코드를 깔끔하게 써라"보다 "TypeScript는 들여쓰기 2칸"처럼 확인할 수 있는 문장이 더 잘 지켜진다고 설명합니다. 앞서 프롬프트에 넣을 세 가지에서 다룬 원칙과 같은 방향입니다.
둘째는 길이입니다. 문서는 파일 하나를 200줄 안쪽으로 두라고 권합니다. 길어질수록 컨텍스트를 더 차지하고 지시가 잘 지켜지지 않는다고 합니다. 일부 폴더에만 필요한 규칙은 .claude/rules/ 폴더에 파일로 나누고, 적용할 경로를 지정해 두면 해당 파일을 다룰 때만 불러옵니다. 여기서 주의할 점이 있습니다. 다른 파일을 가져오는 @경로 가져오기는 파일을 정리하는 데는 좋지만 컨텍스트 비용을 줄여 주지는 않습니다. 가져온 파일도 함께 읽히기 때문입니다.
셋째는 일관성입니다. 두 지시가 서로 부딪히면 AI가 임의로 하나를 고를 수 있다고 문서는 경고합니다. 하위 폴더의 CLAUDE.md나 규칙 파일까지 포함해서 오래된 지시와 충돌하는 지시를 주기적으로 지우라는 안내입니다. 점검을 돕는 /doctor prompt-audit 명령도 소개합니다. 없는 파일을 가리키는 지시나 서로 모순되는 파일을 찾아 수정안을 보여 주고, 사용자가 요청하기 전에는 파일을 바꾸지 않습니다.

지침 파일은 강제가 아니다
여기서부터가 이 글의 핵심입니다. 문서는 지침 파일을 "강제되는 설정이 아니라 컨텍스트"라고 분명히 적습니다. AI는 이 내용을 읽고 따르려고 하지만, 지시가 적용되지 않는다고 판단하면 따르지 않을 수도 있습니다. 모범 사례 문서에도 "타입 검사를 끝내기 전에 항상 실행하라"는 줄은 대부분 지켜지지만 매번 지켜지는 것은 아니라는 취지의 설명이 있습니다.
그렇다고 해서 꼭, 반드시, IMPORTANT를 계속 덧붙이는 것은 해결책이 아닙니다. 문서는 그렇게 해도 무시되는 줄이라면 파일이 너무 길어져서 묻혔거나, 애초에 예외가 없어야 하는 규칙이어서 다른 곳에 있어야 한다고 설명합니다.
비유하면 지침 파일은 새로 온 동료에게 건네는 업무 인수인계 문서입니다. 잘 쓰면 동료가 대부분 따르지만, 문서를 읽은 동료가 상황을 보고 다르게 판단할 여지가 남아 있습니다. 반면 훅은 출입문의 잠금장치에 가깝습니다. 동료가 기억하든 말든 조건에 맞으면 작동합니다.
꼭 지켜야 할 규칙은 훅으로
훅은 AI가 작업하는 흐름의 정해진 지점에서 내가 만든 명령을 실행하는 장치입니다. 도구를 쓰기 전후, AI가 응답을 끝내려는 순간, 세션을 시작할 때 같은 지점이 있습니다. 실행하는 쪽이 AI가 아니라 Claude Code 프로그램이므로 AI가 규칙을 기억하는지와 상관없이 실행됩니다.
문서가 드는 예는 두 가지입니다. 하나는 Edit나 Write로 파일을 고친 뒤마다 포맷터를 돌리는 PostToolUse 훅입니다. 다른 하나는 AI가 응답을 끝내려 할 때 타입 검사를 실행하고, 실패하면 종료 코드 2로 막아서 AI가 오류를 보고 계속 작업하게 하는 Stop 훅입니다. 막은 이유는 표준 오류 출력으로 AI에게 전달됩니다.
설정은 .claude/settings.json에 적습니다. 구조는 대략 이런 모양입니다. 아래는 형태를 보여 주는 예시이고, 실제 키 이름과 필드는 사용하는 버전의 문서를 확인해서 맞추셔야 합니다.
{
"hooks": {
"Stop": [
{ "hooks": [ { "type": "command", "command": "npx tsc --noEmit 1>&2" } ] }
]
}
}
몇 가지 한계도 알아 두어야 합니다. 문서에 따르면 훅이 연속으로 여덟 번 응답을 막으면 Claude Code가 다음 차단을 무시하고 턴을 끝냅니다. 이 상한은 환경 변수로 조정할 수 있습니다. 또 prompt나 agent 형식의 훅은 다른 모델이 판단하기 때문에 결정적이지 않습니다. 확실하게 강제하려면 command나 http 형식을 쓰라는 설명입니다. 반대로 단순한 취향까지 훅으로 만들면 오히려 번거로워지므로, 그런 것은 훅을 지우고 AI의 판단에 맡기라고 합니다.
나눠 쓰는 기준
정리하면 이렇습니다. 질문은 "이 규칙에 예외가 있어도 되는가"입니다.
- 예외가 있어도 되는 관례나 선호, 배경 설명은 지침 파일에 적습니다. 파일은 짧고 구체적으로, 서로 충돌하지 않게 관리합니다.
- 어겨지면 곤란한 규칙은 훅이나 권한 설정의 거부 규칙으로 옮깁니다. 특정 파일을 읽지 못하게 하거나 위험한 명령을 막는 일이 여기에 속합니다.
- 일부 상황에서만 필요한 긴 절차는 스킬처럼 필요할 때만 불러오는 방식이 낫다고 문서는 안내합니다.

마치며
지침 파일에 규칙을 적는 일은 시작점으로 좋지만, 그것만으로 모든 것이 지켜진다고 기대하면 곤란합니다. 같은 줄을 몇 번이나 강조하고 있다면, 그 규칙이 정말 예외 없는 규칙인지 먼저 따져 보고 그렇다면 훅으로 옮기는 편이 맞다는 것이 문서의 방향입니다. 설정 방법과 필드는 버전에 따라 달라질 수 있으니 적용 전에 아래 공식 문서를 확인해 보시기 바랍니다.
참고한 자료
- #AI 코딩
- #Claude Code
- #CLAUDE.md
- #훅
- #프롬프트