Claude Code의 공식 베스트 프랙티스는 모델의 진화나 기능 추가에 맞춰 업데이트되고 있습니다.
약 3개월 만에 다시 읽어보니, 이전과 비교하여 권장되는 사용법이나 사고방식이 크게 바뀌었습니다.
특히 인상적이었던 변화는 **'인간이 세밀하게 관리하는 것'에서 'Claude에게 판단을 맡기고, 반드시 지켜야 할 규칙만 시스템으로 강제하는 방식'**이라는 방향성입니다.
이전에는 컨텍스트 관리나 작업 절차의 고안이 중요하게 다루어졌지만, 현재는 Claude 스스로가 처리할 수 있는 범위가 넓어졌습니다.
이번 글에서는 공식 베스트 프랙티스 중 특히 중요하다고 느낀 3가지 포인트와 이전과의 변화를 정리합니다.
※2026년 11월 1일 기준으로 확인한 내용을 바탕으로 합니다.
이번에 특히 중요하다고 느낀 것은 다음 3가지입니다.
| 포인트 | 요점 | 이전과의 차이 |
|---|
| ① CLAUDE.md를 간결하게 유지하기 | Claude가 파악할 수 없는 정보를 작성 | 기본 방침은 지속 |
| ... | | |
| 각각 설명드리겠습니다. | | |
Claude Code는 리포지토리 내의 코드나 파일 구성을 스스로 조사할 수 있습니다.
따라서 코드를 읽으면 알 수 있는 정보까지 CLAUDE.md에 기재할 필요는 없습니다.
또한, CLAUDE.md는 세션 시작 시 로드되기 때문에 길어질수록 불필요한 정보가 늘어나고 중요한 지시 사항이 묻히기 쉽습니다.
CLAUDE.md에는 Claude가 스스로 파악할 수 없는 정보를 중심으로 기재하는 것이 중요합니다.
기본적으로 다음과 같이 정리합니다.
| 작성하고 싶은 정보 | 판단 |
|---|
| 프로젝트 고유의 설계 방침/규칙 | 작성함 |
| ... | |
| 판단에 어려움이 있다면, 다음 2가지를 고려해 보세요. | |
- Claude는 코드를 읽으면 그 정보를 찾을 수 있는가?
- Claude는 실제로 그 정보를 찾아보려고 시도하는가?
두 가지 모두 '예'라면, 기본적으로 기재할 필요가 없습니다.
참고로, 긴 매뉴얼 같은 것은 CLAUDE.md에 몰아넣기보다는 필요한 때만 로드되는 Skills 등으로 분리하는 방법도 있습니다.
/doctor를 실행하면 Claude Code의 환경이나 설정을 진단할 수 있습니다.
CLAUDE.md에 대해서도 코드에서 파악 가능한 정보 삭제를 제안해 줍니다.
또한, /doctor prompt-audit에서는 구형 모델을 위한 지시나 존재하지 않는 파일에 대한 참조, 모순된 지시 등을 확인할 수 있습니다.
기존의 CLAUDE.md를 검토할 때 유용합니다.
이전부터 CLAUDE.md를 간결하게 유지하는 것은 중요했습니다.
이번 문서에서는 한 단계 더 나아가 **'리포지토리만 읽으면 알 수 있는 것은 작성하지 않는다'**는 사고방식이 강조되고 있습니다.
Claude의 코드 이해 능력이 향상됨에 따라, 인간이 사전에 설명할 필요가 줄어들고 있다는 느낌을 받았습니다.
Claude가 '작업 완료'라고 답변하더라도 실제로 올바르게 작동한다고 보장할 수는 없습니다.
예를 들어, 코드를 수정했더라도 다음과 같은 문제가 남아있을 가능성이 있습니다.
- 빌드가 실패함
- 테스트가 통과하지 않음
- 화면이 제대로 표시되지 않음
- 인프라 변경 내용이 예상과 다름
검증 수단이 없다면, 이러한 것들을 인간이 확인해야 합니다.
여기서 중요해지는 것이 Claude 스스로가 '구현 → 검증 → 수정'을 반복할 수 있는 메커니즘입니다.
Claude가 실행할 수 있는 테스트나 체크를 준비합니다.
예를 들어, 다음과 같은 방법이 있습니다.
| 검증 수단 | 내용 |
|---|
| Lint・타입 체크 | 코딩 규약이나 타입의 일관성을 확인 |
| Playwright MCP | 브라우저 조작을 통해 화면이나 동작을 확인 |
terraform plan | 인프라 변경 예정 사항을 확인 |
/verify | 앱을 빌드하고 실행하여 작동 여부를 확인 |
/code-review | 다른 서브 에이전트의 리뷰 |
예를 들어, Claude에게 다음과 같이 요청합니다.
기능 구현 후에 테스트를 실행하고, 실패하면 수정해 주세요. 마지막에 테스트 결과를 보고해 주세요.
더 나아가, 테스트나 타입 체크를 반드시 실시하게 하고 싶다면, 후술할 Stop 훅 등을 이용해 제어할 수 있습니다.
중요한 것은 단순히 '테스트해 달라'고 지시하는 것이 아니라, Claude가 실행할 수 있는 검증 수단과, 완료를 판단하는 기준을 마련하는 것입니다.
이러한 사고방식은 이전부터 중요하게 여겨져 왔으며, 기본적인 방향성에는 큰 변화가 없습니다.
하지만 Claude에게 맡기는 작업이 늘어날수록, 결과를 자동으로 검증할 수 있는 메커니즘의 중요성은 높아진다고 느꼈습니다.
예를 들어, CLAUDE.md에 다음과 같이 기재했다고 가정해 보겠습니다.
terraform apply는 절대로 실행하지 말 것.
Claude는 통상적으로 이 지침을 따릅니다.
하지만, 프롬프트나 CLAUDE.md에 의한 지시가 반드시 지켜진다는 보장은 없습니다.
이는 지시를 어떻게 해석하고 실행할지가 AI 모델의 판단에 의존하기 때문입니다.
공식 문서에서는 다음 두 가지를 명확히 구분하고 있습니다.
| 종류 | 메커니즘 | 특징 |
|---|
| 비결정론적 (Non-deterministic) | 프롬프트, CLAUDE.md 등 | AI가 판단하므로 반드시 지켜질 것이라는 보장은 없음 |
| 결정론적 (Deterministic) | Hooks, 거부 규칙 등 | Claude Code 측의 메커니즘으로 적용됨 |
즉, '지켜주었으면 하는 규칙'과 '절대적으로 지키게 해야 하는 규칙'은 분리해서 생각할 필요가 있다는 것입니다.
주로 다음 세 가지 메커니즘을 사용합니다.
Hooks는 Claude Code 처리의 특정 타이밍에 사전에 설정한 처리를 실행하는 메커니즘입니다.
| Hook | 활용 예시 |
|---|
PreToolUse | 특정 파일에 대한 편집을 차단 |
PostToolUse | 파일 편집 후 자동 포맷팅 수행 |
Stop | 테스트나 타입 체크 실패 시 작업 종료를 차단 |
예를 들어, 파일을 수정할 때마다 포매터(formatter)를 실행하는 등의 제어가 가능합니다.
Claude에게 '반드시 포맷해 줘'라고 요청하는 것이 아니라, Claude의 판단과는 독립적으로 실행할 수 있습니다.
참고로, Hooks 중에는 AI 모델의 판단을 이용하는 종류도 있습니다. 엄격한 제어가 필요한 경우에는 커맨드 기반의 Hook 등을 적절히 활용해야 합니다.
Permissions(권한 규칙)를 이용하면 Claude가 실행하거나 읽을 수 있는 작업을 제어할 수 있습니다.
예를 들어, 다음과 같은 설정이 가능합니다.
.env 파일의 읽기를 금지하는 것 -
terraform apply 커맨드 실행을 금지하는 것 -
git push 실행 전에 인간의 승인을 요구하는 것
주요 규칙은 다음 세 가지입니다.
| 규칙 | 동작 |
|---|
allow | 작업을 허용함 |
ask | 실행 전에 승인을 요구함 |
deny | 작업을 거부함 |
다만, 권한 규칙은 설정된 툴 호출에 대해서만 적용되기 때문에 모든 우회 경로를 자동으로 막을 수는 없습니다.
운영 환경(Production Environment)에 영향을 주는 작업은 실행 환경이나 클라우드 측의 권한까지 포함하여 제어하는 것이 중요합니다.
샌드박스(Sandbox)를 이용하면 Claude가 실행하는 셸 커맨드에 대해 OS 레벨에서 파일 시스템이나 네트워크 접근 제한을 걸 수 있습니다.
Permissions만으로는 막기 어려운 접근 경로에 대해서도 추가적인 방어막이 됩니다.
참고로, 일반적인 샌드박스 설정에서는 제한된 작업에 대해 샌드박스 외부에서의 재실행을 요구할 수 있는 경우가 있습니다.
더 엄격한 제어가 필요하다면 strict 모드 등의 설정을 검토합니다.
특히 운영 환경이나 기밀 정보를 다루는 경우에는 Claude Code의 설정뿐만 아니라 OS, 네트워크, 클라우드 측의 권한을 조합하는 것이 중요합니다.
제가 약 3개월 전에 확인했을 때와 비교하여 이번에 특히 변화를 느낀 부분입니다.
현재 문서에서는 AI의 판단에 맡기는 부분과 메커니즘으로 강제하는 부분을 구분해서 사용하는 방법이 명확하게 설명되어 있습니다.
Claude의 판단 능력이 향상되면서, 평소 작업은 맡기되 정말 중요한 제약만 강제한다는 사고방식이 더욱 중요하게 다루어지는 것 같습니다.
여기까지 소개한 3가지 포인트 외에도 Claude Code 전체 사용법에서도 변화가 보입니다.
특히 큰 변화는 사람이 세밀하게 관리하던 작업을 Claude 스스로에게 맡기는 방향으로 바뀌고 있다는 점입니다.
과거: 인간의 승인 및 관리를 중시
- 커맨드 실행 시 인간이 승인함
- 작업 절차나 제약을 세세하게 지정함
현재: 기본적인 조작은 Claude에게 맡김
- 대화형 터미널이나 VS Code에서는 Auto mode가 기본값임
- 다른 분류기 모델(classifier model)이 작업을 체크함
- 위험도가 높다고 판단된 작업은 차단됨
Auto mode 덕분에 일상적인 커맨드를 매번 승인할 필요가 없어지면서, 작업 진행이 수월해졌습니다.
다만, 자동 모드(Auto mode)가 절대적인 안전장치는 아닙니다.
반드시 금지하고 싶은 작업은 자동 모드의 판단에 의존하지 않고, 거부 규칙(Refusal Rules)이나 Hooks 등을 통해 제어해야 합니다.
이전: 인간이 적극적으로 관리하는 방식
- 컨텍스트 창(Context Window)의 제약을 인지하고 사용한다.
- 서브 에이전트(Sub-agent)를 사용하여 컨텍스트를 절약한다.
- Plan 모드나 컨텍스트 압축 기능을 활용한다.
현재: Claude 자체에 의한 관리가 중심
- 컨텍스트 창의 크기가 커졌다.
- 긴 대화는 자동으로 압축된다.
- 필요에 따라 Claude 자신이 서브 에이전트에게 위임(Delegate)한다.
과거만큼 인간이 컨텍스트를 세밀하게 관리할 필요는 없어졌습니다.
다만, 관련 없는 작업을 같은 세션에서 계속 진행하면 불필요한 컨텍스트가 쌓여 비용이나 답변 품질에 영향을 줄 수 있습니다.
따라서 작업을 전환할 때 /clear 명령어를 사용하는 것은 현재도 유효합니다.
공식 문서에는 '하지 않아도 되는 것'이라는 항목도 추가되었습니다.
과거의 노하우 중 일부는 현재 모델에서는 필요성이 낮아졌습니다.
| 과거 권장 사항 | 현재의 사고방식 |
|---|
| 컨텍스트를 적극적으로 관리한다 | 자동 압축에 맡긴다. 작업 간의 /clear는 계속 유효하다 |
| ... | |
| 과거에는 효과적이었던 기법이라도, 모델 성능 향상으로 인해 필요성이 감소하고 있음을 알 수 있습니다. | |
한 번 익힌 베스트 프랙티스를 계속 사용하기보다는, 최신 모델이나 기능에 맞춰 재검토하는 것이 중요합니다.
이번 베스트 프랙티스는 AI가 한 장의 이미지로 표현해 주었습니다.
핵심은 Claude에게 자유롭게 작업을 맡기되, 넘어서는 안 될 경계만 시스템으로 제어하는 것입니다.
모든 작업을 인간이 세밀하게 지시하고 승인할 필요 없이, Claude의 능력을 활용하면서 안전성을 확보한다는 현재의 사고방식을 나타냅니다.
약 3개월 만에 Claude Code 공식 베스트 프랙티스를 다시 읽어보았는데, 권장되는 사용법이나 생각이 크게 바뀌어 놀랐습니다.
이번에 특히 중요하다고 느낀 점은 다음 세 가지입니다.
- CLAUDE.md는 간결하게 유지하기
Claude가 코드만으로는 파악할 수 없는 정보를 중심으로 전달한다.
- 검증 가능한 시스템 제공하기
Claude 자신이 작업 결과를 확인하고, 문제가 있을 경우 수정할 수 있도록 한다.
- 반드시 지켜야 할 규칙은 강제하기
AI의 판단에만 의존하지 않고, Hooks나 권한 규칙 등으로 제어한다.
그리고 이번 변화를 한마디로 표현하자면,
'인간이 Claude의 작업을 세밀하게 관리하는 것'에서 'Claude에게 맡길 수 있는 환경과 시스템을 인간이 구축하는 것'으로의 변화라고 느꼈습니다.
Claude Code의 베스트 프랙티스는 모델의 진화나 기능 추가에 맞춰 앞으로도 계속 변해갈 것입니다.
이번 기사 역시 몇 달 후에는 오래된 정보가 될 수도 있습니다.
계속해서 공식 문서를 확인하며, 자신만의 사용법도 업데이트해 나가고 싶습니다.
※Claude Code 베스트 프랙티스 화면 오른쪽 상단의 '페이지 복사'에서 MD를 복사하세요.
Claude Code 베스트 프랙티스 2026년 11월 1일 버전
전체 문서 인덱스는 다음에서 가져가세요: https://code.claude.com/docs/llms.txt
이 파일을 사용하여 더 깊이 탐색하기 전에 사용 가능한 모든 페이지를 발견하세요.
Claude Code를 더욱 활용하기 위해, Claude에게 보이지 않는 것을 알려주고 실행할 수 있는 검증(Check)을 부여하며, 예외를 허용하지 않는 규칙을 강제합니다.
Claude Code는 대부분의 경우, 새로운 세션에서 처음에 보내는 간단한 프롬프트만으로 사용자 측 설정 없이 올바르게 작동하도록 만들어졌습니다. 예를 들면:
- 각 명령어를 순차적으로 승인할 필요가 없도록 안전하게 실행되므로, 새 터미널 및 VS Code 세션은 자동 모드(auto mode)로 시작합니다. 이 모드에서는 위험한 작업은 실행 전에 분류기(Classifier)가 검토합니다.
- 독립적인 작업을 병렬로 진행하면서 메인 대화를 집중된 상태로 유지하기 위해, Claude는 서브 에이전트에게 위임하고 필요한 경우에만 확인을 요청합니다.
- 사용자가 관리하지 않아도 긴 세션을 계속할 수 있도록, 컨텍스트 창이 가득 차기 전에 대화가 자동으로 압축됩니다.
이 페이지에서는 기본 설정만으로는 불충분할 때 무엇을 해야 하는지 설명합니다. 이는 일반적으로 Claude가 코드만으로는 파악할 수 없는 지식, 규칙, 제약 사항이 프로젝트에 존재할 때 발생합니다:
- 누군가의 머릿속에만 존재하는 배포 절차
- 절대 읽어서는 안 되는 파일
- 무언가를 완료로 간주하기 전에 반드시 통과해야 하는 검사 단계
- 넘겨서는 안 될 예산
어떤 기본 설정도 프로젝트에 대한 이러한 지식을 알 수는 없습니다. 따라서 여기서 사용자가 약간의 설정을 진행하는 것이 효과를 발휘합니다.
세션이 기대대로 진행되지 않는 경우, 원인은 거의 항상 다음 중 하나입니다:
- Claude가 예상과 다르게 결과물을 만들었거나 매번 세션을 시작할 때 같은 사실을 재발견해야 하는 경우. 리포지토리를 읽어도 얻을 수 없는 정보가 부족합니다. 'Claude에게 보이지 않는 것을 전달하기'를 참조하십시오.
- Claude가 완료했다고 했지만 실제로는 완전히 끝나지 않은 경우. 일반적으로 자신의 작업을 확인할 수단이 없었기 때문입니다. 'Claude에게 실행 가능한 검사 기능을 부여하기'를 참조하십시오.
- 이 리포지토리에서 절대 발생해서는 안 되는 일을 Claude가 하거나 반드시 수행해야 할 절차를 건너뛴 경우. 프롬프트만으로는 그 어느 것도 보장할 수 없습니다. '예외를 허용하지 않는 규칙 강제하기'를 참조하십시오.
- Claude가 올바르게 마무리했지만, 작업에 비해 너무 많은 시간, 토큰, 권한 프롬프트를 소모한 경우. '기본 설정 변경하기'를 참조하십시오.
Claude를 무인으로 실행할 때는 동일한 4가지 포인트를 무인 실행에 적용하며, 더 이상 필요하지 않은 조언도 현재 모델을 기준으로 정리했습니다.
[!NOTE]
팀 전체의 설정은 다른 페이지에 있습니다: 조직용 Claude Code 설정하기.
Claude Code에 부여하는 지시는 모두 다음 중 하나입니다:
- 비결정론적(Non-deterministic): 사용자가 지시를 작성하고, Claude(모델)가 이를 읽습니다. 프롬프트,
CLAUDE.md, 스킬 등이 여기에 해당합니다. 모델은 이 정보를 어떻게 처리할지 스스로 판단합니다. 일반적으로 명령을 따르지만, 현재 모델은 많은 컨텍스트가 없어도 의도를 잘 이해하지만, 지시를 따른다는 보장은 없습니다. 실행하지 않거나 다른 행동을 할 수도 있습니다.
- 결정론적(Deterministic): 사용자가 지시를 설정하면, Claude Code(하네스)는 이를 반드시 실행해야 합니다. 훅(Hook), 거부 규칙(Rejection Rule), 관리 설정 등이 여기에 해당합니다. 모델이 무엇을 하겠다고 판단하든 상관없이, Claude Code는 매번 이를 적용합니다.
Claude Code의 대부분 기능은 두 가지 형태를 모두 가지고 있습니다:
| 비결정론적 (Claude가 판단) | 결정론적 (Claude Code가 강제) |
|---|
무엇을 할지: 프롬프트, CLAUDE.md, Claude가 스스로 사용하는 스킬 | 훅 및 사용자가 시작할 수 있는 스킬 |
| 무엇에 접근 가능한지: auto 모드 분류기 | 거부 규칙, strict 모드 사일로(Sandbox), 관리 설정 |
언제 완료로 할지: 증거 요구, /goal, /code-review | 테스트, 타입 체크, Stop 훅, CI |
| 얼마나 비용을 소모할지: effort 레벨, Claude 자체 페이스 | -p와 함께 사용하는 --max-turns 또는 --max-budget-usd, 설정된 지출 상한선 |
최종 판단은 누가 내리는 것이 좋은가: Claude에 의한 작업 내용 요약 | 브랜치 보호(Branch Protection), 병합 승인자(Merge Approver)
대부분의 경우, 판단을 Claude에게 맡기는 것이 바람직합니다. 거의 모든 가이드라인에는 예외가 있으며, 현재 모델은 눈앞의 코드를 읽고 해당 가이드라인이 상황에 맞는지 판단하는 데 능숙합니다. 실제 코드를 마주한 Claude가 사전에 작성된 규칙보다 더 잘 판단할 때가 많습니다.
결정론적 방식은 모델의 판단과 관계없이 특정 일이 반드시 일어나거나(또는 절대 일어나지 않도록) 하고 싶을 때를 위한 것입니다. 거창할 필요는 없습니다. 프로덕션 배포나 타인의 작업을 덮어쓰는 force push와 같은 중대한 일은 auto 모드가 이미 차단하고 있습니다. 보통은 자신의 프로젝트 고유의 것이며, 아무리 니치한 것이어도 괜찮습니다:
생성된 클라이언트가 절대 수정하지 않는 곳이 있습니다. 파일을 생성한 후에는 반드시 라이선스 헤더 스크립트를 실행해야 합니다.
이러한 내용은 모두 CLAUDE.md에 작성하거나 프롬프트에 한 줄 적어 넣을 수 있으며, Claude는 거의 매번 이에 따를 것입니다. 하지만 아무리 강한 어조로 작성해도 특정 턴에서 그 지침을 따를지 여부는 전적으로 Claude의 판단에 맡겨진 상태입니다.
[!TIP]
CLAUDE.md의 한 줄에 강조 표시를 계속 추가했는데도 Claude가 놓친다면, 해당 줄은 '훅(hook)'으로 지정해야 한다는 신호일 수 있습니다. 그 반대도 마찬가지입니다. 단순히 취향에 불과한 내용에 훅을 설정했다면, 그것을 삭제하고 Claude에게 판단을 맡기세요.
[!TIP]
Claude가 리포지토리에서 찾지 못하거나, 그렇지 않으면 매 세션마다 재발견하는 데 시간을 소비해야 하는 정보만 기록하세요.
Claude는 모든 작업을 코드 읽기부터 시작하며, 현재 모델은 이 부분에 매우 능숙합니다. 파일 구성, 규칙, 테스트 프레임워크, 기존 컴포넌트의 작성 방식 등을 찾아내며, 대개 사용자가 설명하는 것보다 빠르게 파악합니다. 즉, Claude를 위해 기록하고 싶어지는 대부분의 내용은 이미 Claude가 알고 있는 것입니다.
찾기 어려운 정보는 다음과 같습니다:
- 팀이 회의에서 결정한 내용
- 한 사람의 머릿속에만 존재하는 배포 절차
- 통합 테스트(Integration Test)에 필요한 환경 변수
또한, 리포지토리에는 존재하지만 찾는 데 몇 분이 걸리는 정보도 있으며, Claude는 매 세션 시작 시마다 그 조사를 다시 해야 합니다.
Claude를 위해 무언가를 기록하기 전의 좋은 테스트:
- 코드를 읽으면 이것을 찾을 수 있는가?
- 실제로 찾아보려고 노력하는가?
둘 다 '예'라면, 적지 않는 것이 좋습니다.
구체적인 프롬프트가 유용한 이유도 같은 맥락입니다. Claude가 아직 가지고 있지 않은 정보를 제공하기 때문입니다. 파일 이름을 언급하고 증상을 설명하며, '수정된' 상태가 어떤 모습이어야 하는지를 처음에 알려주면, 대개 나중에 수정할 노력을 한 번 절약할 수 있습니다.
적절한 접근 방식이 두 가지일 경우 선호도를 명시하는 것도 마찬가지입니다. Claude는 그것을 코드에서 읽어낼 수 없기 때문에, 어느 쪽을 선택해야 할지에 집착이 있다면 처음에 알려주세요.
| 이렇게 하지 말고 | 이렇게 하라 |
|---|
| "로그인 버그를 수정해줘" | "세션 타임아웃 후 로그인이 실패한다는 사용자 보고가 있다. src/auth/의 토큰 갱신을 확인하고, 문제를 재현하는 실패 테스트를 작성한 다음 수정해줘" |
| "캘린더 위젯을 추가해줘" | "HotDogWidget.php 패턴에 따라 월을 선택할 수 있고 연 단위로 페이지 이동이 가능한 캘린더 위젯을 만들어줘. 새로운 라이브러리는 사용하지 마." |
Claude가 필요한 것을 이미 가지고 있다면, 설명하기보다는 그것을 전달하세요:
- 파일:
@ 와 경로를 입력하면 메시지에 파일 내용을 포함할 수 있습니다. - 이미지: 디자인이나 오류의 스크린샷을 프롬프트에 붙여넣습니다.
- 명령어 출력:
cat error.log | claude -p "what's going on here" 와 같이 셸에서 파이프를 통해 전달합니다.
think step by step나 be thorough 같은 구절은 키워드가 아니라 일반 프롬프트 텍스트입니다. Claude가 얼마나 깊게 생각할지 제어하는 주요 수단은 'effort(노력)' 레벨이며, 모델과 effort를 변경하여 설명합니다. 이러한 표현들로도 effort 설정 범위 내에서 Claude를 약간 부추길 수는 있지만, 설정을 초과해서 끌어올리지는 못합니다.
여전히 유용한 구절 중 하나는 be ambitious입니다. Claude는 사용자가 어디까지 기대하는지 알 수 없기 때문에, 요청을 소극적으로 해석하여 그것을 충족시키는 최소한의 결과물을 만들려는 경향이 있습니다. 엣지 케이스(edge case)에 대응하고 자연스러운 후속 작업까지 포함한 풍부한 버전이 필요하다면, 그렇게 전달하세요:
build the settings page from the mockup. be ambitious: empty and error states, the save flow wired up, keyboard navigation, not just the layout
이는 깊이 생각하는 것이 아니라, 사용자만이 알고 있는 범위를 Claude에게 전달하는 것입니다.
또한, 특정 무언가를 수정하는 것이 아니라 탐색하고 있을 때는 what would you improve in this file?와 같은 모호한 프롬프트도 전혀 문제가 없습니다. 진행하면서 수정 횟수는 조금 늘어나지만, 그것이 트레이드오프입니다.
무엇을 원하는지 아직 명확하지 않을 때는, 프롬프트를 보내기 전에 모든 것을 준비해 둘 필요가 없습니다. 대신 Claude에게 인터뷰를 요청하세요:
I want to add rate limiting to the public API but haven't thought it through yet. Interview me until you could write the spec, then write it to SPEC.md.
Claude는 아직 결정되지 않은 부분에 대해 객관식 질문을 반환합니다. 사용자 단위 제한인지 키 단위 제한인지, 상한 초과 요청을 어떻게 처리할지, 무엇이 범위 외(out of scope)인지 등입니다. 답변이 사양으로 정리될 때까지 질문을 계속합니다.
SPEC.md가 완성되면, 이를 기반으로 구축하기 위한 새로운 세션을 시작합니다. 이렇게 하면 깨끗한 컨텍스트와 문서화된 완료 정의로부터 작업을 시작할 수 있습니다. 이 파일은 나중에 Claude에게 실행 가능한 체크를 제공하여 리뷰어가 참조하게 할 수도 있습니다.
Claude Code는 모든 세션에 CLAUDE.md를 로드합니다. 즉, 거기에 쓰인 모든 줄은 관련 여부와 관계없이 모든 작업에서 Claude의 주의력을 조금씩 소모시킵니다. 그렇기 때문에 이 파일에는 Claude가 코드 자체만으로는 파악할 수 없는 내용만을 넣어두는 것이 가장 효과적입니다:
- 이 리포지토리에서 작업을 확인하는 방법: 정확한 테스트, 타입 체크(type check), lint 명령어와 단일 테스트 파일을 실행하는 방법
- 코드가 오해를 불러일으킬 수 있는 부분: 여기저기 있지만 새로운 코드에서는 따라 해서는 안 될 오래된 패턴이나, 사용되지 않는 것처럼 보이지만 실제로는 사용되는 디렉토리
- 리포지토리에 없는 결정 사항: 팀이 어떤 에러 헬퍼(error helper)로 결정했는지, 배포 메커니즘, 무엇에 마이그레이션 리뷰가 필요한지
- 이미 2번 수정해야 했던 내용
이 테스트를 통과하는 CLAUDE.md는 간결하게 유지됩니다:
# Commands
- Install: pnpm install
- Run one test file: pnpm vitest run path/to/file.test.ts
...
세션 내에서 /context를 실행하면 Claude가 파일을 읽었는지 확인할 수 있습니다.
타입 체크 라인은 명령어만 포함되어 있다는 점에 주목하세요. Claude는 작업하는 동안 자신의 작업을 확인할 수 있도록, 명령어를 알고 있어야 합니다. Claude가 종료되기 전에 타입 체크 통과를 Claude Code에 강제하고 싶다면, Stop 훅(hook)이 필요합니다. 이 파일에 Always typecheck before you finish와 같은 줄을 작성해도 대부분 작동하지만, 매번은 아닙니다.
파일을 처음부터 쓸 필요는 없습니다:
/init는 코드베이스로부터 초기 버전을 생성합니다. 그 이후의 작업은 주로 줄을 삭감하는 것입니다. 메모 가이드에서는 200줄 미만으로 유지할 것을 권장합니다. -/doctor는 Claude가 코드에서 이미 파악할 수 있는 내용에 대해 삭제를 제안합니다. -/doctor prompt-audit는 구형 모델용으로 작성된 지침, 존재하지 않게 된 파일을 가리키는 지침, 서로 모순되는 지침을 지적합니다.
개인적인 선호도는 CLAUDE.md가 아니라 CLAUDE.local.md에 작성하고, 해당 파일을 .gitignore에 추가하여 리포지토리에 포함되지 않도록 합니다.
[!NOTE]
CLAUDE.md에 쓰여진 줄을 Claude가 계속 무시하는 경우, IMPORTANT를 추가해도 아마 해결되지 않을 것입니다. 파일이 너무 길어져서 그 줄이 묻혀버린 경우이거나, 그 줄이 예외를 허용하지 않는 규칙인 경우일 수 있으며, 후자의 경우에는 훅(hook)으로 처리해야 합니다.
특정 규칙이 코드베이스의 일부에서만 의미를 갖는 경우, paths: 필터와 함께 .claude/rules/에 배치하면 Claude가 실제로 해당 부분에서 작업할 때만 로드됩니다. 예를 들어, 이 .claude/rules/api.md는 src/api/ 하위 디렉터리의 TypeScript 파일에 대해 로드됩니다:
---
paths:
- "src/api/**/*.ts"
...
더 고성능의 모델은 엔지니어링에 대해 더 많이 알고 있지만, 자신들의 팀이 어떻게 릴리스를 수행하는지, 인시던트 핸드북(incident runbook)에 무엇이 적혀 있는지, API 문서를 어떻게 작성해야 하는지에 대해서는 알지 못합니다. 이러한 지식은 스킬(skills)에 넣을 수 있습니다. 스킬이란 .claude/skills/<name>/SKILL.md에 저장된 절차나 팀의 지식을 의미합니다.
이러한 종류의 정보에 대해 스킬은 CLAUDE.md보다 컨텍스트 부담이 적습니다. Claude가 스스로 시작할 수 있는 스킬인 경우, Claude는 모든 세션에서 이름과 설명을 보지만, 파일 전체를 읽는 것은 작업(task)으로 필요할 때만 이루어집니다. 스킬에 넣은 긴 릴리스 절차는 CLAUDE.md...
