티스토리 뷰

Computer/AI

[Claude] Claude.md

HONGGG 2026. 4. 7. 04:28

Claude-Code 나만의 프로젝트를 이해하는 개발자로..

 

 

CLAUDE.md 개요

Claude Code는 매 세션마다 기억을 잃는다.

 

아무리 어제 훌륭한 대화를 했더라도, 오늘 새 세션을 열면 내 코드 스타일도, 프로젝트 구조도, 선호하는 도구도 모른다.

매번 같은 설명을 반복하는 것은 시간 낭비다.

 

CLAUDE.md는 이를 해결한다.

 

CLAUDE.md는 클로드가 세션 시작 시 자동으로 읽는 마크다운 파일로, 한 번 작성해두면 모든 대화에 자동 적용된다.

잘 쓴 CLAUDE.md 하나가 프롬프트 수십 줄보다 효과적이다.

 

 

핵심 원칙: 짧고, 구체적이고, 실행 가능하게

CLAUDE.md 작성에서 가장 중요한 원칙이 있다.

 

짧게 유지하라

 

100줄 이하가 이상적이다.

 

프론티어 사고 모델은 약 150~200개의 지침을 합리적으로 따를 수 있지만, 그 이상은 준수율이 급격히 떨어진다.

모든 것을 담으려 유혹을 참아야 한다.

 

구체적인 규칙을 작성하라

 

"pnpm 사용, npm 말고" 같은 구체적 규칙은 약 89%의 준수율을 보이는 반면, "깔끔한 코드를 작성하라" 같은 모호한 지침은 약 35%에 머문다.

 

제재는 대안과 함께

 

좋은 CLAUDE.md 파일들은 안전한 대안을 함께 제시한다는 것이다.

# 나쁜 예
- flag 파라미터 사용 금지

# 좋은 예
- flag 파라미터로 동작을 분기하지 말 것 — 함수를 분리

 

 

파일 계층 구조 이해하기

CLAUDE.md는 단일 파일이 아니라 계층 시스템이다.

나중에 로딩되는 파일이 더 높은 우선순위를 갖는다.

 

로딩 순서 (낮은 → 높은 우선순위)

 

순서 위치 용도
1 /etc/claude-code/CLAUDE.md 관리자 전역 정책 (오버라이드 불가)
2 ~/.claude/CLAUDE.md 개인 글로벌 설정
3 {프로젝트 루트}/CLAUDE.md 팀 공유 프로젝트 규칙
4 .claude/CLAUDE.md 프로젝트 규칙 (서브디렉토리 버전)
5 CLAUDE.local.md 개인 프로젝트 오버라이드 (gitignore 대상)

 

윈도우 경로 정리

 

  • 글로벌: C:\Users\{사용자명}\.claude\CLAUDE.md
  • 글로벌 규칙 폴더: C:\Users\{사용자명}\.claude\rules\*.md
  • 글로벌 설정: C:\Users\{사용자명}\.claude\settings.json

 

글로벌과 프로젝트를 섞지 마라

글로벌 파일에는 프로젝트와 무관한 개인 선호만, 프로젝트 파일에는 해당 프로젝트의 스택과 구조만 넣어야 한다.

이 두 가지가 섞이면 Claude가 매 작업마다 불필요한 컨텍스트를 짊어지게 된다.

 

 

글로벌 CLAUDE.md

글로벌 파일은 모든 프로젝트에 적용되는 나의 개발 원칙이다.

최상위 엔지니어들의 글로벌 파일에서 공통적으로 발견되는 항목들을 정리하면 다음과 같다.

 

언어 설정

 

간단하지만 매 세션마다 "한국어로 대답해줘"를 반복하지 않아도 된다.

- 대화와 설명은 한국어로 응답
- 코드 주석, 커밋 메시지, 변수명은 영어

 

 

코드 스타일 (범용)

 

여기서 핵심은 "모든 프로젝트에 적용되는가?"를 자문하는 것이다.

Unity 전용 규칙이나 특정 프레임워크 패턴은 여기에 넣지 않는다. 

- 엄격한 타이핑 — 함수 반환값, 변수, 컬렉션 모두 타입 명시
- 단일 책임 원칙 — 하나의 함수는 하나의 일만 수행
- 새 로직 작성 전 기존 코드에 동일 로직이 있는지 먼저 검색
- 매직 넘버 금지 — 상수로 정의하고 이름을 부여

 

에러 처리

 

- 에러를 조용히 무시하지 말 것 — 항상 명시적으로 처리
- 포괄적 catch-all 금지 — 구체적 에러 타입 사용
- 에러 메시지에 원인과 조치 방법 포함

 

작업 행동 규칙

 

이 부분이 코딩 품질에 가장 큰 영향을 미친다.

Claude의 가장 흔한 실수는 "너무 많은 것을 한꺼번에 바꾸는 것"이다. 이 규칙 하나만 넣어도 코드 품질이 체감될 만큼 달라진다.

- 실패하면: 멈추고 → 원인 설명 → 확인 후 진행
- 변경 전 영향 범위 파악 — "다른 곳에서 안 쓴다"는 추측 금지, grep으로 증명
- 되돌릴 수 없는 작업은 반드시 확인 요청
- 한 번에 너무 많이 바꾸지 말 것 — 작은 단위로 검증하며 진행

 

금지사항

 

- 추측으로 패키지 버전이나 API 시그니처 지정 금지 — 확인 후 사용
- 요청하지 않은 리팩토링 금지 — 현재 작업 범위에만 집중
- "깔끔하게 정리했습니다" 같은 모호한 보고 금지 — 무엇을 변경했는지 구체적으로 명시

 

 

프로젝트 CLAUDE.md

프로젝트 파일에는 세 가지를 넣는다: 무엇(WHAT), 왜(WHY), 어떻게(HOW).

 

WHAT — 기술 스택과 구조

 

## 프로젝트 개요
Unity 2022.3 LTS, URP 기반의 3D 액션 게임

## 디렉토리 구조
- Assets/Scripts/Core — 게임 루프, 매니저
- Assets/Scripts/Combat — 전투 시스템
- Assets/Scripts/UI — UI 관련
- Assets/Prefabs — 프리팹
- Assets/ScriptableObjects — 데이터 에셋

 

WHY — 아키텍처 결정 사항

 

## 아키텍처 결정
- 싱글톤 대신 ScriptableObject 기반 이벤트 시스템 사용
  → 테스트 용이성과 씬 간 의존성 제거 목적
- ECS는 사용하지 않음 → MonoBehaviour 기반 유지

 

HOW — 빌드, 테스트, 워크플로우

 

## 명령어
- 테스트: Unity Test Runner (EditMode + PlayMode)
- 빌드: File > Build Settings > Windows x64

## 코딩 규칙
- MonoBehaviour 상속 클래스는 PascalCase
- SerializeField는 private + [SerializeField]
- GetComponent는 Awake()에서 캐싱, Update()에서 호출 금지
- Update()에서 GC 할당 금지 (new, LINQ, string 연결 등)

 

 

워크플로우

/init으로 시작하고, 깎아내기

프로젝트 디렉토리에서 /init 명령을 실행하면 Claude가 프로젝트를 분석해 CLAUDE.md 초안을 만들어준다.

 

하지만 생성된 파일은 보통 불필요한 내용이 많으므로, 필요한 것만 남기고 삭제하는 방식이 효과적이다.

백지에서 쓰는 것보다 깎아내는 게 쉽다.

 

실수 기반으로 점진적 추가

처음부터 완벽한 파일을 만들려 하지 말자.

Claude가 반복적으로 실수하는 패턴을 발견할 때마다 한 줄씩 추가하는 것이 가장 효과적이다.

 

예를 들어 Claude가 자꾸 var를 이 한 줄을 추가하면 된다.

- var 사용 금지 — 명시적 타입 선언 사용

 

rules/ 디렉토리 활용

글로벌 CLAUDE.md가 길어질 것 같으면 ~/.claude/rules/ 폴더에 주제별 .md 파일로 분리할 수 있다.

~/.claude/
├── CLAUDE.md          ← 핵심 규칙 (30~50줄)
└── rules/
    ├── git.md         ← Git 관련 규칙
    ├── error.md       ← 에러 처리 규칙
    └── naming.md      ← 네이밍 규칙

 

컨텍스트 관리

CLAUDE.md에 넣은 모든 내용은 매 대화마다 컨텍스트 윈도우를 차지한다.

 

불필요한 내용이 많을수록 Claude가 실제 작업에 쓸 수 있는 공간이 줄어든다.

또한 관련 없는 지침이 많으면 Claude가 파일 전체를 무시할 확률도 높아진다.

 

설정 파일과 역할 분리

CLAUDE.md에 넣으면 안 되는 것들도 있다.

 

권한, 도구 허용, 모델 선택 같은 하드웨어적 설정은 settings.json에 넣어야 한다.

 

CLAUDE.md는 "어떻게 코딩할 것인가"에 대한 지침이고, settings.json은 "무엇을 허용할 것인가"에 대한 설정이다.

 

내용 예제 입력
"pnpm 사용, npm 말고" CLAUDE.md
"Bash 도구 허용" settings.json
"커밋 메시지는 영어" CLAUDE.md
"Co-Authored-By 제거" settings.json (attribution.commit: "")
"테스트 먼저 실행" CLAUDE.md
"모델은 sonnet 사용" settings.json

 

CLAUDE.md에 절대 넣지 말아야 할 것

  • API 키, 비밀번호, 토큰
    • CLAUDE.md는 컨텍스트에 로딩되므로 보안 위험
  • Claude가 이미 아는 것
    • 표준 문법, 일반적인 라이브러리 API 설명
  • 뻔한 지침
    • "깨끗한 코드 작성", "주석 추가" 같은 당연한 내용
  • 너무 긴 문서
    • 상세한 아키텍처 문서는 별도 파일에 두고 @로 참조

 

 

 

사용량 관리

Claude Code는 사용량 제한이 있다. /status에서 Usage 탭을 확인하면 세션과 주간 사용량을 볼 수 있다.

  • Current session
    • 현재 세션의 사용량. 매일 특정 시간에 리셋
  • Current week
    • 주간 전체 사용량. 매주 리셋
  • 세션이 100%가 되면 완전 차단이 아니라 속도 제한이 걸림
  • /extra-usage로 추가 사용량 활성화 가능]

 

컨텍스트 관리도 사용량에 영향을 미친다.

컨텍스트가 50%를 넘으면 /compact로 압축하고, 작업 전환 시에는 /clear로 리셋하는 습관을 들이자.

 

 

 

요약 체크리스트

  1. ~/.claude/CLAUDE.md에 개인 글로벌 규칙 작성 (50~100줄)
  2. 프로젝트 루트에서 /init 실행 후 불필요한 내용 삭제
  3. 사용하면서 Claude의 반복 실수를 발견할 때마다 한 줄씩 추가
  4. 파일이 길어지면 rules/ 디렉토리로 분리
  5. 주기적으로 검토하여 더 이상 필요 없는 규칙 제거

 

가장 효과적인 CLAUDE.md는 실제 마찰을 해결하는 파일이다.

이론적으로 완벽한 규칙집이 아니라, 내가 반복적으로 겪는 문제를 한 줄씩 해결해 나간 파일이 결국 가장 강력하다.

'Computer > AI' 카테고리의 다른 글

[AI] MCP(Model Context Protocol) - AI의 USB  (0) 2026.04.07
최근에 올라온 글
최근에 달린 댓글
«   2026/04   »
일 월 화 수 목 금 토
1 2 3 4
5 6 7 8 9 10 11
12 13 14 15 16 17 18
19 20 21 22 23 24 25
26 27 28 29 30
글 보관함