옵시디언 세컨드브레인 만들기 (5) — CLAUDE.md 설계

 

 CLAUDE.md는 세션마다 통째로 읽히는 파일이라, 무엇을 적느냐보다 무엇을 빼느냐가 결과를 정한다. 공식 문서가 제시하는 기준과 실제로 무엇을 담는지, 그리고 옵시디언에 적용했을 때 필자의 볼트에서는 어떻게 만들었는지를 정리한다.

 

 태그를 허브 문서로 바꾸면서 CLAUDE.md라는 걸 처음 알게 됐다. 정확한 지침과 규칙이 필요하다고 판단되었기에 나의 vault 폴더 구조와 손대지 않을 영역, 새 노트 작성 규칙을 담아 작성하기 시작한다.

---

 CLAUDE.md란

 Claude Code가 세션을 시작할 때마다 자동으로 읽는 마크다운 파일이다. 세션은 매번 빈 컨텍스트에서 시작하므로, 매번 다시 설명하기 귀찮은 맥락을 여기 적어두면 그다음부터는 설명하지 않아도 된다는 강점이 있다.

 

 해당 문서의 성격을 정확히 알아두는 게 중요한데, 공식 문서는 CLAUDE.md를 강제 설정이 아니라 맥락(context)이라고 명시하고 있다. 시스템 프롬프트의 일부가 아니라 시스템 프롬프트 뒤에 붙는 사용자 메시지로 전달되며, 따라서 지시가 지켜진다는 보장은 없다. (예외 없이 매번 일어나야 하는 일이라면 CLAUDE.md가 아니라 훅(hook)으로 만들어야 한다.)

 

참고로 메모리는 두 종류로 나뉜다.

-	CLAUDE.md	auto memory
쓰는 주체	사람	Claude
담기는 것	지시와 규칙	학습한 것과 패턴
로드	매 세션 전량	매 세션 (MEMORY.md 처음 200줄 또는 25KB)

 

로드되는 위치와 순서

 파일을 어디 두느냐에 따라 적용 범위가 달라진다. 아래는 로드되는 순서이며, 전부 이어붙여진다.

범위	위치	용도
조직 정책	/Library/Application Support/ClaudeCode/CLAUDE.md (macOS) <br>/etc/claude-code/CLAUDE.md (Linux)	회사 공통 규칙
사용자	~/.claude/CLAUDE.md	모든 프로젝트에 적용될 개인 선호
프로젝트	./CLAUDE.md 또는 ./.claude/CLAUDE.md	팀이 공유하는 프로젝트 규칙
로컬 개인	./CLAUDE.local.md	개인용. .gitignore 대상
하위 디렉터리	subdir/CLAUDE.md	그 경로의 파일을 실제로 읽을 때만 로드

 작업 디렉터리와 그 위의 모든 상위 디렉터리에서 파일을 찾아 루트에서 아래로 이어붙인다. 즉, 작업 디렉터리에 가까운 지침이 나중에 읽힌다. 하위 디렉터리의 CLAUDE.md만 예외로, 시작 시점이 아니라 해당 파일을 열 때 붙는다.

 

 전부 이어붙여진다는 점 때문에 생기는 함정은, 두 곳의 지침이 서로 어긋나면 Claude는 둘 중 하나를 임의로 고른다는 것이다. 때문에 공식 문서에서는 주기적으로 파일들을 훑어 모순을 제거하기를 권하고 있다.

 

Claude.md 내용을 추가하는 시점

공식 문서가 제시하는 네 가지 신호다. 이 순간이 왔을 때 한 줄씩 늘리는 방식을 권장하고 있다.

• Claude가 같은 실수를 두 번째로 할 때
• 코드 리뷰에서 Claude가 알고 있었어야 할 게 걸렸을 때
• 지난 세션에 했던 정정을 이번 세션에도 또 타이핑하고 있을 때
• 새 팀원이 들어와도 똑같이 설명해야 할 맥락일 때

 반대로 여러 단계짜리 절차이거나 프로젝트의 일부에만 해당하는 것은 여기 넣지 않는다. 전자는 스킬로, 후자는 경로 scope 규칙으로 옮기는 것을 권고한다.

 

Claude.md에 넣을 것과 뺄 것

작성한 내용이 파일에 남을 자격을 얻으려면 세 질문을 통과해야 한다.

1. 사실인가

2. 안정적인가

3. 코드나 파일을 읽어서는 알 수 없는가

넣기	빼기
추측할 수 없는 개인적인 명령어·빌드 방법	읽으면 바로 알 수 있는 모든 것
기본값과 다른 명명·frontmatter 규칙	이미 알려진 표준 마크다운 문법, 옵시디언 기본 동작
새 자료가 들어왔을 때의 판단 순서	폴더 트리와 문서 개수
프로젝트 고유의 구조 결정과 그 이유	긴 설명, 지침 문서의 규칙 본문 (→ 링크로 대체)
응답 방식 (계획 먼저, 작업 후 요약)	"정리를 잘해라" 같은 막연한 말

 왼쪽 칸의 공통점은 사람이 저장소를 한 시간 들여다봐도 알아낼 수 없는 정보라는 것이다. 

 

 다만 이 기준은 절대적인 규칙표가 아니라 관찰에 가깝다. "안정적인가"는 추상적이기 때문에 상황마다 다르고, 구조 자체를 이제 막 정립해나가는 시기에는 동일한 항목이 왼쪽과 오른쪽을 오갈 수도 있다.

 

작성 기준 네 가지

공식 문서가 제시하는 작성 지침이다.

• 분량 — 파일당 200줄 이내를 목표로 한다. 길어질수록 컨텍스트를 더 먹고 지시 이행률이 떨어진다. 4MiB를 넘으면 파일 전체를 건너뛴다.
• 구조 — 헤더와 불릿으로 묶는다. 빽빽한 산문(줄글)보다 정돈된 섹션이 잘 지켜진다. 사람이 문서를 훑는 방식과 같다.
• 구체성 — 검증 가능한 수준으로 쓴다.

올바른 예시	이렇게 말고
"새 노트에는 `date`를 넣는다"	"본문에 날짜도 적기"
"문서끼리의 참조는 [[위키링크]]로만 쓴다"	"링크 걸"
"블로그 원고는 [지정 폴더]에 둔다"	"파일을 잘 정리해줘"

• 일관성 — 서로 어긋나는 규칙이 두 곳에 있으면 임의로 하나가 선택되므로, 주기적으로 훑어보며 낡거나 충돌하는 지시를 제거해야한다.

---

일반적인 구성

 코드 저장소에서 CLAUDE.md에 흔히 들어가는 항목은 대체로 정해져 있다. /init 명령이 저장소를 분석해 자동으로 만들어주는 초안도 이 범위 내에서 생성된다고 한다.

• 프로젝트 한 줄 소개와 기술 스택
• 빌드·테스트·실행 명령어
• 코드 스타일과 명명 규칙
• 아키텍처 결정과 디렉터리 역할
• 저장소 관례 (브랜치 전략, 커밋·PR 규칙)
• 개발 환경 특이사항
• 흔한 함정

 쉽게 말해 "새로 온 사람에게 첫날 설명해줄 것"의 목록에 가깝다. /init은 코드를 읽어 알 수 있는 부분을 채워주므로, 사람이 덧붙여야 하는 건 코드를 읽어서는 나오지 않는 부분(ex. 금지사항)이다.

 

내 Obsidian Vault의 구성

 코드가 아닌 노트를 다루는 볼트이기에 위 표준 구성을 그대로 쓸 수 없었다.

"명령어" 자리를 "새 자료가 들어왔을 때의 판단 규칙"으로 바꾸는 식으로 변형했고, 정리하고 나니 CLAUDE.md는 처음 세션을 시작할 때의 관문과 같은 느낌이 됐다. 현재 볼트의 Claude.md 파일에 있는 건 아래 네 가지 이다:

섹션	내용
작업 전에 읽을 것	어떤 작업에 어떤 지침 문서를 먼저 읽어야 하는지 정리한 표
하지 않는 것 (금지 사항)	지우거나 옮기면 복구가 어려운 영역
Claude 응답 방식	계획 먼저 제시, 작업 후 요약 남기기 등
알 수 없는 (내멋대로의) 폴더 구조 결정	ex) 200_Work가 왜 300_Areas 하위가 아닌지

 규칙 본문은 전부 별도 지침 문서로 옮겼고, 위키링크를 걸어 연결시켰다.

판단 기준은 하나였는데, 이 줄을 지우면 실수를 하게 될까? 아니면 지운다.

 

 한 가지 덧붙인 점은: 지침 문서들은 (내가 알기 편하기 위해) 위키링크로 걸려 있을 뿐 자동으로 열리지 않으므로, 해당 작업들을 해야한다면 시작 전에 직접 읽기를 명시해뒀다.

---

Claude.md 분량을 줄이는 방법

 @import는 줄여주지 않는다. 파일이 길어지면 @경로로 쪼개면 될 것 같지만, import된 파일은 그것을 참조하는 CLAUDE.md와 함께 시작 시점에 그대로 펼쳐져 로드된다. 따라서 보기에는 짧아져도 비용은 그대로다.

 

 실제로 로드량을 줄이는 방법은 다음 네 가지다.

수단	로드 시점
스킬 (.claude/skills/)	호출할 때만
경로 스코프 규칙 (.claude/rules/에 paths: 지정)	해당 경로의 파일을 다룰 때만
하위 디렉터리 CLAUDE.md	그 하위 파일을 읽을 때만
삭제	—

 부수적인 수단으로는, 블록 단위 HTML 주석(<!-- -->)은 컨텍스트에 주입되기 전에 제거되기 때문에 관리 메모는 여기 적으면 토큰을 쓰지 않는다. 필자의 CLAUDE.md 맨 아래에도 유지 원칙과 같은 것을 주석으로 적어뒀다.

 

Anti-Pattern

• 상세 문서나 긴 설명을 통째로 복붙 → 링크로 대체
• "정리를 잘해라" 같은 검증 불가능한 선언 → 삭제
• 규칙 본문을 지침 문서와 CLAUDE.md 양쪽에 두기 → 어긋나면 임의로 하나가 선택된다
• 이미 알아서 잘하는 것에 대한 규칙 → 삭제하거나 훅으로 강제
• 실제와 다른 이상적인 상태를 서술하기 → 낡은 지침 그대로 다음 세션이 돌아간다

---

CLAUDE.md 내용을 대폭 줄였으니, 이제 빼낸 규칙들로 상세 지침 문서를 만들어보자.

→ 다음편 [옵시디언 세컨드브레인 만들기 (6) 운영 지침 자동화]

 

참고 자료

• Anthropic, How Claude remembers your project — 로드 위치와 순서, 추가 시점, 작성 기준, @import 동작, HTML 주석 처리
• Anthropic, Best practices for Claude Code — 넣을 것과 뺄 것
• Anthropic, Explore the context window — CLAUDE.md가 시작 컨텍스트에서 차지하는 자리
• Anthropic, Extend Claude with skills — on-demend 로드
• Nafiul Hasan, CLAUDE.md Best Practices (What Belongs in It), Prompt Architects