CLAUDE.local.md란? Claude Code에서 나만의 프로젝트 규칙 저장하는 방법

“Claude Code에게 코딩을 시키는데, 팀원이 만든 규칙은 그대로 쓰고 제 취향만 따로 저장할 수 없나요?” AI 코딩 도구를 여러 사람이 함께 쓰면 이런 고민이 생깁니다. 팀 전체에 필요한 규칙이 있는 반면, 각자 사용하는 테스트 주소나 작업 습관은 다를 수 있기 때문입니다. 이때 알아두면 좋은 이름이 CLAUDE.local.md입니다. 이 파일은 Claude Code에서 ‘이 프로젝트를 작업할 때 나만 참고하고 싶은 지침’을 적는 Markdown 문서입니다. 원래 팀이 쓰는 규칙을 전부 복사할 필요 없이, 내 컴퓨터의 프로젝트 폴더에 개인 설정을 더할 수 있습니다. 다만 꼭 알아둘 점이 있습니다. 파일 이름에 local이 들어간다고 비밀이 자동으로 보호되는 것은 아닙니다. 이번 글에서는 CLAUDE.local.md의 역할, CLAUDE.md와 차이, 작성 예시, Git에 올리지 않도록 설정하는 방법, 적용 여부와 보안 점검까지 차례로 살펴봅니다.

CLAUDE.local.md란 · 핵심 흐름CLAUDE.local.md란의 주요 개념과 확인 순서를 네 단계로 정리한 자체 제작 도식.CLAUDE.local.md란 · 핵심 흐름1개인 규칙CLAUDE.local.md에 선호를저장합니다2팀 규칙공유용 CLAUDE.md와 구분합니다3파일 보호Git 제외와 저장 위치를점검합니다4동작 확인도구가 지침을 읽었는지 살핍니다설명용 요약 도식입니다. 최신 기능과 이용 조건은 본문 및 공식 문서에서 확인하세요.EMFLS AI · 자체 도식
자체 제작 개념도 · EMFLS AI

이 글의 순서

1. CLAUDE.local.md란? 한 문장 정의

CLAUDE.local.md는 Claude Code가 프로젝트에서 읽는 개인용 지침 파일입니다. 예를 들어 한 팀이 홈페이지를 만들고 있다고 가정하겠습니다. 팀 전체 규칙은 다음과 같을 수 있습니다.

  • “중요한 코드를 바꾸기 전에 테스트 항목을 확인한다.”
  • “파일과 함수의 이름은 팀 규칙에 맞춘다.” 반면 나는 다음과 같은 개인 취향이 있을 수 있습니다.
  • “작업 설명은 한국어로 작성해 줘.”
  • “내 로컬 미리보기는 포트 3000을 먼저 고려해 줘.”
  • “오류를 설명할 때 초보자용 단계별 점검표도 작성해 줘.” 이럴 때 공통 규칙은 CLAUDE.md, 나만의 프로젝트별 취향은 CLAUDE.local.md에 적는 방식이 유용합니다. 이름의 .local은 나의 작업 환경에서 별도로 다룰 파일이라는 의미로 이해하면 됩니다. 파일을 만들었다고 팀원에게 자동으로 전송되거나 공동 설정으로 적용되는 것은 아닙니다.

2. CLAUDE.md와 CLAUDE.local.md는 무엇이 다른가요?

구분 주로 사용하는 대상 예시 내용
./CLAUDE.md 같은 프로젝트를 함께 쓰는 팀원 코딩 규칙, 테스트 명령, 프로젝트 구조
./CLAUDE.local.md 이 프로젝트를 작업하는 나 개인 내 설명 언어, 개인 로컬 환경, 연습용 데이터
~/.claude/CLAUDE.md 내 컴퓨터의 모든 프로젝트 전 프로젝트에 적용할 일반적인 개인 취향

여기서 ./는 현재 프로젝트 폴더를 나타내고, ~는 일반적으로 사용자의 홈 폴더를 가리킵니다. 중요한 것은 ‘누구에게, 어느 프로젝트에서 적용할지’를 나누는 일입니다. 모든 개인 취향을 팀 공통 파일에 넣으면 동료에게 필요 없는 정보가 공유될 수 있습니다.

3. 파일은 어디에 만들면 되나요?

가상의 프로젝트 폴더를 다음과 같이 생각해 보세요.

my-first-website/
├── index.html
├── CLAUDE.md
├── CLAUDE.local.md
└── .gitignore

위 그림에서 CLAUDE.md와 CLAUDE.local.md는 같은 프로젝트 최상위 폴더에 놓인 별개의 파일입니다. 파일 이름의 대문자·마침표를 정확히 구분해야 합니다. 예를 들어 CLAUDE.local.md.txt로 저장하면 의도한 파일과 다릅니다. Claude Code의 최신 공식 메모리 문서는 시작한 작업 디렉터리와 그 상위 폴더에서 관련 메모리 파일을 찾으며, 하위 폴더의 파일은 파일에 접근할 때 읽을 수 있다고 설명합니다. 처음에는 복잡한 계층 구조보다 프로젝트 최상위에 하나만 만들어 보는 편이 이해하기 쉽습니다.

4. 어떤 내용을 적는 것이 좋을까요?

아래는 연습용 예시입니다. 컴퓨터의 실제 경로나 사용자 정보를 넣지 않았습니다.


- 작업 설명은 한국어로 작성해 줘.
- 로컬 미리보기 포트는 3000을 우선 고려해 줘.
- 코드를 수정하기 전 변경할 파일을 먼저 알려 줘.
- 테스트용 고객 이름은 가상의 인물만 사용해 줘.
- 오류가 발생하면 원인과 확인 방법을 구분해 설명해 줘.

이처럼 구체적이고 검증할 수 있는 문장을 적으면 좋습니다. “코드를 완벽하게 만들어 줘”라는 추상적인 지침보다 “변경할 파일과 예상 영향부터 목록으로 보여 줘”라는 요청이 더 확인하기 쉽기 때문입니다. 반대로 로그인 비밀번호, API 키, 회사 내부 고객 데이터 같은 내용을 지침 파일에 넣는 것은 피해야 합니다.

5. 만드는 방법은 꼭 터미널을 써야 하나요?

아닙니다. 텍스트 파일을 만들고 저장할 수 있는 편집기면 됩니다.

  1. 작업 중인 프로젝트 폴더를 엽니다.
  2. 이름을 정확히 CLAUDE.local.md로 지정해 새 텍스트 파일을 만듭니다.
  3. 위 예시에서 필요한 문장만 복사합니다.
  4. 파일을 저장합니다.
  5. Claude Code가 새 내용을 읽었는지 /context 등의 확인 방법으로 점검합니다. 일부 설치 환경에서는 /memory 명령으로 관련 메모리 파일을 열어 편집하는 기능도 제공합니다. 다만 이 글의 핵심은 파일 자체의 역할입니다. 메뉴 이름이나 화면 배치는 Claude Code 버전에 따라 달라질 수 있습니다.

파일이 제대로 읽혔는지 확인하려면?

Claude Code에서 /context를 실행해 Memory files에 관련 파일이 표시되는지 확인하는 것이 공식 안내 중 하나입니다. 단순히 AI가 “규칙을 이해했습니다”라고 답한 것보다 어떤 지침 파일을 실제 로드했는지 확인하는 편이 정확합니다. 다만 파일을 읽었다고 해서 모든 행동이 반드시 지시대로 실행된다는 뜻은 아닙니다.

6. 다른 팀원에게 공유하지 않으려면 .gitignore를 확인하세요

여기서 중요한 설정 하나가 등장합니다. GitHub에 파일을 올리는 프로젝트라면 .gitignore라는 파일에서 Git이 새로 추적하지 않을 항목을 지정할 수 있습니다. 프로젝트 최상위의 .gitignore에 다음 한 줄을 넣는 예시가 있습니다.

/CLAUDE.local.md

이 설정은 프로젝트 루트에 있는 같은 이름의 파일을 Git이 새로 추적하지 않도록 할 때 사용합니다. 그러나 매우 중요한 예외가 있습니다. 이미 Git이 추적 중이거나 과거에 커밋된 CLAUDE.local.md는 .gitignore에 추가한다고 과거 기록에서 사라지지 않습니다. 공개 저장소에 파일을 이미 올렸다면 추적 상태와 Git 기록을 별도로 살펴봐야 합니다. 과거에 암호를 올렸다면 단순 삭제 대신 비밀키 폐기·재발급 같은 유출 대응도 필요합니다.

7. .gitignore가 있으면 파일이 완전히 비밀이 되나요?

아닙니다. 이는 가장 조심해야 할 오해입니다. .gitignore는 Git의 추적·추가 행동에 관한 설정이지, 암호화하거나 다른 프로그램의 접근을 차단하는 보안 기능이 아닙니다. 예를 들어 CLAUDE.local.md에 개인 비밀번호를 적는다면 다음 문제가 여전히 남습니다.

  • 같은 컴퓨터에서 파일을 읽을 권한이 있는 프로그램이나 사람이 볼 수 있습니다.
  • Claude Code가 파일을 읽으면 지침 내용이 AI 요청 맥락으로 사용될 수 있습니다. 서비스의 데이터 처리 정책을 별도로 확인해야 합니다.
  • 이미 올린 Git 기록에는 내용이 남아 있을 수 있습니다.
  • 공유 폴더나 자동 백업, 화면 공유를 통해 다른 곳에 노출될 수 있습니다. 따라서 이 파일에는 ‘선호와 작업 기준’을 적고 ‘비밀정보’는 적지 않는 것을 기본 원칙으로 삼으세요.

8. 다른 컴퓨터나 Git worktree에서도 자동으로 보이나요?

반드시 그렇지 않습니다. 예를 들어 컴퓨터 A에서 Git에 포함하지 않은 CLAUDE.local.md 파일은 컴퓨터 B가 같은 GitHub 저장소를 복제했다고 자동으로 생기지 않습니다. 하나의 저장소에서 여러 작업 트리(worktree)를 사용하더라도 각 작업 폴더의 무시된 개인 파일이 자동으로 공유되는 것은 아닙니다. Anthropic 공식 문서는 여러 worktree에서 개인 지침을 공유하고 싶다면 홈 폴더에 별도 지침 파일을 만들고 프로젝트의 CLAUDE.md에서 @경로로 가져오는 방법도 설명합니다. 다만 팀 공통 파일에 개인 절대경로를 적으면 다른 팀원에게는 적용되지 않을 수 있고, 외부 파일 가져오기는 승인 요청이 생길 수 있습니다. 처음에는 프로젝트별 파일부터 이해하는 편이 좋습니다.

9. 팀 규칙과 개인 규칙이 충돌하면 어떻게 되나요?

예를 들어 팀 파일은 “모든 오류 설명은 영어로”라고 하고, 개인 파일은 “모든 설명을 한국어로”라고 지시한다고 가정해 보겠습니다. 최신 공식 문서는 같은 폴더에서 CLAUDE.local.md가 CLAUDE.md 뒤에 컨텍스트에 들어갈 수 있음을 설명합니다. 하지만 나중에 읽는 개인 파일이 팀 규칙을 반드시 강제로 덮어쓴다고 보장하는 것은 아닙니다. 지침 문서는 Claude가 답변할 때 참고하는 문맥이고, 실제 행동에 대한 강제 정책은 별도의 권한 시스템에서 관리되기 때문입니다. 규칙이 충돌한다면 우선 파일들을 사람이 읽고 서로 양립하도록 고치는 것이 가장 확실합니다.

10. ‘수정하지 마’라고 적으면 파일 수정이 100% 막히나요?

아닙니다. 지침에 “승인 없이 파일을 고치지 마”라고 적는 것은 좋은 행동 요청일 수 있으나 보안 장벽이나 강제 차단 기능은 아닙니다. Claude Code 공식 문서는 메모리 파일을 지침용 컨텍스트로 설명하고, 반드시 막아야 할 작업은 권한 설정이나 훅 등 실제 실행 단계에서 통제되는 기능을 사용하라고 안내합니다. 중요한 프로젝트라면 개인 지침에만 의존하지 말고 다음을 확인하세요.

  • 실제 편집·명령 실행 권한과 승인 방식을 확인했는가?
  • 중요한 변경 전에 백업·버전 관리 기준을 마련했는가?
  • AI가 작업한 뒤 파일 차이와 테스트 결과를 직접 확인했는가? 이 글은 실제 권한 설정을 바꾸거나 차단이 작동하는지 시험하지 않았습니다.

11. 자주 하는 실수 다섯 가지

실수 왜 문제일까요? 확인할 것
CLAUDE.local.md.txt로 저장 의도한 파일 이름과 다름 확장자 숨김 설정·실제 파일명
Git에 이미 올린 뒤 .gitignore 추가 기존 추적/이력은 남음 Git 추적 상태·비밀 유출 여부
비밀번호 기록 지침 파일은 비밀 저장소가 아님 비밀 제거·별도 보안 관리
개인 지침이 팀 규칙을 반드시 이긴다고 가정 지침 충돌 시 결과 불확실 규칙을 읽고 충돌 해소
파일만 만들고 적용을 확인하지 않음 실제 로딩 범위·버전 차이 가능 /context Memory files 확인

12. ChatGPT나 다른 AI 코딩 도구도 이 파일을 읽나요?

CLAUDE.local.md라는 이름은 Claude Code 문서에서 설명하는 파일 형식입니다. 다른 AI 코딩 도구가 같은 파일을 자동으로 발견해 읽는다고 가정해서는 안 됩니다. 예를 들어 일부 도구는 AGENTS.md 등 서로 다른 프로젝트 지침 파일을 사용합니다. 여러 AI 코딩 도구를 함께 이용한다면 각 프로그램이 어떤 지침 파일을 읽는지 최신 공식 문서에서 별도로 확인하세요. 이름이 비슷하다고 동기화와 적용 범위까지 자동으로 같아지는 것은 아닙니다.

Claude Code의 기본 Project instructions 설정이 claude-md-or-agents-md일 때는 현재 프로젝트 폴더나 상위 폴더에 CLAUDE.md, .claude/CLAUDE.md, CLAUDE.local.md 중 하나가 있으면 그 경로의 AGENTS.md를 기본적으로 함께 읽지 않습니다. 두 파일을 모두 읽게 하려면 지원 버전의 /config에서 claude-md-and-agents-md를 선택할 수 있습니다. 사용 중인 버전에서 실제로 불러온 파일은 /context로 확인하세요. Anthropic Claude Code 공식 문서

13. 그대로 복사해 쓰는 안전한 요청 예시

다음 문장은 Claude Code에게 계획과 적용 여부를 먼저 설명하도록 요청하는 교육용 프롬프트입니다.

  • 프로젝트별로만 필요한 선호인가? 모든 프로젝트에 필요한 선호라면 사용자 범위 지침을 검토합니다.
  • 팀이 모두 알아야 할 내용인가? 그렇다면 공유 CLAUDE.md 쪽이 더 적합할 수 있습니다.
  • 개인 정보나 비밀 키는 없는가? 비밀이 있다면 지침 파일에서 제외합니다.
  • Git 추적 방지가 필요한가? .gitignore를 점검하고 과거 커밋은 별도로 확인합니다.
  • 실제로 읽혔는가? Claude Code의 /context에서 파일 로드 여부를 확인합니다.
  • 충돌하는 팀 규칙은 없는가? 공통 지침과 함께 읽고 정리합니다.
  • 절대 금지할 행동은 없는가? 메모리 지침 대신 실제 권한 시스템으로 통제합니다. 설정을 복잡하게 만드는 것보다 개인 선호를 3~5줄부터 시작해 실제로 도움이 되는지 확인하는 편이 초보자에게 좋습니다.

나는 Claude Code를 처음 쓰는 사람이야. 지금 프로젝트에서 팀 공통 CLAUDE.md는 유지하고, 개인 선호만 CLAUDE.local.md로 관리하고 싶어. 현재 어떤 메모리 파일을 읽는지 먼저 알려 주고, 개인 지침 파일의 권장 위치·예시 내용·.gitignore 필요 여부를 설명해 줘. API 키나 비밀번호는 파일에 넣지 마. 파일 생성이나 Git 변경은 내가 승인하기 전에는 실행하지 말고, 필요한 수정 후보를 먼저 보여 줘. 좋은 점은 현재 상태 확인 → 설명 → 검토 → 승인의 순서를 요청했다는 것입니다. 실제 도구의 실행 권한 정책과 별개인 자연어 지시이므로, 안전이 중요할 때는 권한 설정도 함께 확인해야 합니다.

14. 처음 시작하는 사람을 위한 점검표

자주 묻는 질문(FAQ)

Q1. CLAUDE.local.md는 무료 프로그램인가요?

아닙니다. Claude Code가 읽는 지침 파일 이름입니다. 파일 자체가 별도 프로그램이나 유료 상품을 뜻하지 않습니다.

Q2. CLAUDE.md가 없어도 사용할 수 있나요?

공식 문서는 로컬 지침을 별도 파일로 취급합니다. 다만 프로젝트 구조·설정에 따라 실제 로드 여부를 확인하고, 문제가 있으면 현재 공식 문서에서 지원 조건을 살펴보세요.

Q3. 개인 파일 내용이 팀원에게 자동으로 공유되나요?

자동으로 공유되지는 않습니다. 그러나 사용자가 Git에 커밋하거나 클라우드 동기화 폴더에 넣는 등 별도 공유 행위를 하면 내용이 전달될 수 있습니다.

Q4. .gitignore에 적으면 이미 올라간 파일도 사라지나요?

아닙니다. 기존 추적 파일과 과거 Git 이력은 별도로 검토해야 합니다.

Q5. 개인 지침에 API 키를 저장해도 되나요?

권장하지 않습니다. .gitignore는 암호화나 비밀 접근 차단 기능이 아닙니다.

Q6. 매번 새 대화를 시작할 때 파일 내용을 붙여넣어야 하나요?

Claude Code는 지원되는 메모리 파일을 세션 시작 시 읽도록 설계됐습니다. 실제 적용은 /context의 Memory files로 확인하는 것이 좋습니다.

Q7. CLAUDE.local.md를 수정하면 현재 대화에도 즉시 적용되나요?

파일 읽기·재로드 시점은 사용 버전과 작업 맥락에 따라 달라질 수 있습니다. 현재 세션 로딩 상태를 확인하고 필요한 경우 공식 안내에 따라 새 세션에서 재확인하세요.

Q8. 여러 Git worktree를 쓰면 개인 파일도 따라오나요?

Git에 포함하지 않은 로컬 파일은 자동으로 다른 worktree에 복사되지 않습니다. 여러 환경에서 공유하려면 별도 개인 파일 가져오기 등의 설계를 검토해야 합니다.

Q9. CLAUDE.local.md는 예전에 폐지된 기능이 아닌가요?

과거 일부 문서에는 다른 방식으로 대체하라는 안내가 있었지만, 2026년 10월 확인한 현재 공식 Claude Code 메모리 문서는 개인 프로젝트 지침 파일로 설명합니다. 실제 사용 전에는 현재 설치 버전과 최신 문서의 지원 여부를 재확인하세요.

Q10. ‘파일 수정 금지’라고 쓰면 완전 안전한가요?

아닙니다. AI에게 전달되는 지침이며, 강제 차단에는 실제 권한 설정과 도구 통제가 필요합니다.

마무리: 팀 규칙은 함께, 개인 선호는 별도로

CLAUDE.local.md는 Claude Code 프로젝트에서 나만의 작업 방식과 설명 취향을 적어 두는 지침 파일입니다. 팀 규칙을 바꾸지 않으면서 내 환경에 맞게 도움을 받을 수 있지만, Git에서 무시하는 것과 비밀을 보호하는 것은 전혀 다릅니다. 처음에는 민감하지 않은 개인 선호 3줄만 적고, .gitignore와 실제 파일 로드 여부를 확인해 보세요.

함께 읽으면 좋은 글