Claude Code 베스트 프랙티스: AI가 '이해하는' 지시서 작성 방법

Claude Code를 사용하면서 이런 생각을 해본 적 없으신가요?

"방금 고쳤던 것을 또 똑같이 하고 있다", "매번 프로젝트의 전제 조건을 설명하는 것이 귀찮다".

그 원인은 대개 CLAUDE.md 파일을 작성하지 않았거나, 혹은 작성 방식이 좋지 않기 때문입니다. 본문에서는 AI가 제대로 '이해할 수 있는' CLAUDE.md 작성 방법을 공식 사양에 따라 정리합니다.

---

CLAUDE.md는 매 세션 시작 시 자동으로 로드되는 지시서입니다. 위치에 따라 적용 범위(사용자 전체 / 프로젝트 / 로컬)가 달라집니다.

• 효과적인 팁은 3가지:
  200줄 이내 · 구체적으로 작성 · 모순되지 않게 유지 - 우선 /init으로 자동 생성한 후 발전시키는 것이 정석입니다.

• Claude Code는 사용하지만 CLAUDE.md는 아직 작성하지 않았다.

• 작성은 했지만, 효과를 체감하기 어렵다.

• copilot-instructions.md나 AGENTS.md와의 차이점을 모르겠다.

Claude Code는 매 세션을 **깨끗한 컨텍스트(context)**에서 시작합니다. 즉, 이전 대화 내용을 기억하지 못합니다. 따라서 세션 간에 유지하고 싶은 지시사항을 작성해 두는 것이 바로 CLAUDE.md입니다. 이 파일을 일반 Markdown으로 작성하면 Claude가 세션 시작 시 읽어 들입니다.

핵심은 이것이 **'강제 설정(mandatory setting)'이 아니라 '컨텍스트(context)'**라는 점입니다. Claude는 이를 읽고 따르려고 노력하지만, 절대적으로 강제되는 것은 아닙니다. 그렇기 때문에 '어떻게 전달되도록 작성하는가'가 중요합니다.

처음부터 작성할 필요는 없습니다. 프로젝트 루트에서 /init을 실행하면, Claude가 코드베이스를 분석하여 빌드 명령어, 테스트 방법, 규칙 등을 수집한 CLAUDE.md를 자동으로 생성해 줍니다.

/init

💡 이미 CLAUDE.md가 있는 경우에도 /init은 덮어쓰지 않고 '개선안'을 제안합니다. 안심하고 실행할 수 있습니다.

생성된 초안에 Claude가 스스로 알아차리기 어려운 정보(팀 고유의 규칙 등)를 추가해 나가는 것이 공식적인 권장 흐름입니다.

CLAUDE.md는 배치하는 위치에 따라 적용 범위가 달라집니다. 로드 순서는 '넓은 스코프 → 좁은 스코프'이며, 좁은 쪽이 나중에 읽힙니다.

스코프	위치	용도
사용자 전체	~/.claude/CLAUDE.md	모든 프로젝트에 공통되는 개인 설정
프로젝트	./CLAUDE.md 또는 ./.claude/CLAUDE.md	팀에서 공유하는 설정(git에 포함)
로컬	./CLAUDE.local.md	개인이 프로젝트에만 필요한 설정(.gitignore 권장)

팀과 공유하고 싶은 규칙은 ./CLAUDE.md, 자신만을 위한 sandbox URL이나 테스트 데이터는 CLAUDE.local.md와 같이 구분하여 사용하는 것이 좋습니다.

여기서부터가 본론입니다. 공식에서 제시하는 팁들을 실제 예시와 함께 다룹니다.

CLAUDE.md는 매번 컨텍스트 전체에 완전히 로드됩니다. 길수록 토큰을 많이 사용하고, 게다가 지시 준수율이 떨어집니다. 적정 기준은 파일당 200줄 이내입니다.

이것이 가장 효과적입니다. 모호한 지시는 지켜지지 않습니다.

# 나쁜 예 (모호)
- 코드를 깔끔하게 포맷팅한다
- 변경 사항은 테스트한다
...

'제대로 한다'가 아니라 '무엇을 어떻게 할지'까지 작성해야 합니다. 이 것만으로도 동작 방식이 달라집니다.

여러 개의 CLAUDE.md (루트, 서브 디렉토리, .claude/rules/)에서 지시사항이 충돌하면, Claude는 둘 중 하나를 임의로 선택합니다. 주기적으로 검토하여 오래되거나 모순되는 지시는 삭제해야 합니다.

지시사항이 늘어나면 분할할 수 있습니다.

@path 구문을 사용하여 다른 파일을 가져올 수 있습니다.

See @README for project overview and @package.json for available commands.
# Additional Instructions
- git workflow @docs/git-instructions.md

다만 주의할 점이 있습니다. @import은 '정리'에는 도움이 되지만, 컨텍스트 축소에는 도움이 되지 않습니다 (가져온 파일도 시작 시 전체적으로 로드되기 때문입니다).

정말로 컨텍스트를 절약하고 싶다면 .claude/rules/의 **경로 범위 규칙(path scope rule)**이 유효합니다. 특정 파일을 수정할 때만 로드되기 때문입니다.

---
paths:
- "src/api/**/*.ts"
...

이렇게 하면 API 파일을 건드릴 때만 이 규칙이 로드되고, 평소에는 컨텍스트를 소비하지 않습니다.

/memory

을 실행해서 그 CLAUDE.md가 실제로 읽히고 있는지 먼저 확인합니다. 목록에 나타나지 않으면 Claude는 애초에 보고 있지 않은 것입니다. 위치가 올바른지 체크해 주세요.

/memory

그래도 따르지 않는다면, 대개 '지시가 모호함' 또는 '다른 파일과 모순됨' 중 하나입니다.

Claude Code가 읽는 것은 CLAUDE.md이지 AGENTS.md가 아닙니다. 이미 AGENTS.md를 사용하고 있다면, CLAUDE.md에서 가져와서 두 가지를 병행할 수 있습니다.

@AGENTS.md
## Claude Code 고유
- `src/billing/` 하위의 변경은 plan mode를 사용

• /init으로 초안을 생성하고 - 위치에 따라 범위를 분리하여 사용하기
• 200단어 이내 · 구체적 · 모순 없음, 세 가지 원칙
• 늘어나면 @import 또는 .claude/rules/로 분할

CLAUDE.md를 다듬으면 다음에 필요한 것은 '이 지시서가 Claude뿐만 아니라 Codex나 다른 모델에서도 동일하게 시도하고 싶다'는 니즈입니다. 모델별로 동작을 비교하고 싶은 상황이죠.

그때 은근히 번거로운 것이, 모델별로 별도의 API 키나 엔드포인트를 관리하는 것입니다. 제 경우에는 여러 모델을 하나의 창구에 모을 수 있는 서드파티 API 게이트웨이(EvoLink 등)를 거쳐서, 같은 CLAUDE.md를 재사용하면서 모델만 전환하고 있습니다. 키 관리가 일원화되니 비교 검증이 훨씬 수월해집니다.

모델 전환에 대한 구체적인 설정은 다른 글로 자세히 쓸 예정입니다.

도입부의 '또 같은 것을 하고 있다', '매번 설명한다'와 같은 내용은 거의 CLAUDE.md로 해결됩니다.

핵심은 '강제 설정이 아니라 컨텍스트'라는 점을 이해하는 것입니다. 그래서 구체적으로 · 짧게 · 모순 없이 쓸수록 효과가 좋습니다. 일단 /init으로 초안을 만들고, /memory로 읽기 여부를 확인하며 키워나가면, Claude Code의 사용 경험이 한 단계 달라집니다.

참고 (공식 문서)