프로젝트에 맞게 길들이기 — CLAUDE.md와 컨텍스트 관리

• 확인 시점: 2026-08-31 — 이 회차의 제품 사실(명령 이름·화면 표기·동작·수치)을 이 날짜에 Claude Code 공식 문서에서 확인했습니다. 화면이 다르게 보이면 공식 문서를 우선합니다.

1. 들어가며

세션은 매번 빈 컨텍스트 창으로 시작한다. 이 사실이 반복되는 작업에는 불편함을 남긴다. 새로운 세션을 열 때마다 Claude가 이전까지 배운 맥락을 알지 못하기 때문이다. 같은 실수를 두 번 저지르면 정정을 하고, 코드 스타일이 어긋나면 다시 설명을 덧붙인다. 3회에서 익힌 일상 작업이 손에 익자, 이제 그 반복의 소모성 자체가 문제가 된다. 세션이 끊길 때마다 같은 지시를 다시 입력해야 하는 부담은 점점 커진다. 이는 개발자가 아니더라도 프로젝트 구조를 공유해야 할 때 공통으로 겪는 현상이다.

새로운 창을 열고 커서가 깜빡이자 습관처럼 폴더 구조를 다시 설명하듯 타이핑을 시작했다. "문서 파일은 docs 폴더에, 이미지 파일은 assets 폴더에 넣어라."라는 문장을 입력하고 엔터키를 누른 지 삼 초도 되지 않아 대화 상자가 다시 뜨자, 이번엔 데이터베이스 연결 설정 값을 추가로 적었다. 같은 세션 내에서 세 번의 설명이 이어졌고, 이튿날 새벽에 열람한 기록에서는 동일한 내용이 네 번째로 반복되어 있었다. 키보드 위에 손을 올려둔 채 잠시 멈추는 순간, 기계는 잊고 사람은 기억하는 이 비효율성을 더 이상 용납하지 않기로 결심했다. 그 반복은 피로감으로 남았으나 해결책을 모색해야 할 필요성은 분명해졌다.

파일 이름이나 위치처럼 딱딱한 규칙을 외우기 전에, 그 규칙이 필요한 순간을 상상해 보자. 주말에 퇴근하며 수정한 설정을 월요일 아침 다시 입력한다. 팀원이 새로 합류해 같은 질문을 반복해서 던진다. Claude가 이미 지시받은 형식을 무시하고 임의로 코드를 포맷한다. 이런 상황에서 매번 수동으로 맥락을 전달하는 것은 비효율적이다. 사람은 기억하지만 기계는 잊기 때문이다. 이때 CLAUDE.md 파일과 자동 메모리 기능이 등장한다. 사람이 작성하는 CLAUDE.md는 프로젝트 규칙이나 조직 정책을 담고, Claude가 스스로 배우는 자동 메모리는 저장소 단위의 패턴을 기록한다.

이 회차에서는 프로젝트 규칙을 파일에 적어 두고 그것이 실제로 응답을 바꾸는지 확인해본다.

2. 개념

CLAUDE.md가 무엇인가

CLAUDE.md는 사람이 직접 작성하는 지시 파일이다. Claude Code는 매 세션 시작 시 이 파일을 읽는다. 이는 강제 설정이 아니라 컨텍스트 제공에 불과하다. 지시를 적어 둬도 Claude가 반드시 따른다는 보장은 없다. 따라서 Claude의 행동을 완전히 통제할 수 없다는 점을 인식해야 한다. 반면, 반드시 막아야 하는 일이 있다면 CLAUDE.md보다는 훅을 사용한다. 시스템 프롬프트가 아닌 사용자 메시지 영역에 전달되므로 엄격한 준수는 기대하지 않는다. 따라서 이 파일은 Claude에게 맥락을 알려주는 참고 자료로 이해하는 것이 정확하다.

어디에 두는가

이 표는 네 가지 범위의 파일 위치와 용도를 정리한 것이다. 관리형 정책과 사용자 범위는 전역에 적용되며, 프로젝트 범위는 팀이 버전 관리를 통해 공유한다. 로컬 범위는 개인 전용이며 .gitignore로 제외된다. 이번 회차에서는 실제 협업에 쓰이는 프로젝트 범위를 다룬다.

어떻게 읽히는가

여러 CLAUDE.md 파일은 서로 덮어쓰지 않고 이어 붙인다. 로드 순서는 파일시스템 루트에서 작업 디렉터리 방향으로 흐른다. 예를 들어 foo/bar/ 에서 실행하면 foo/bar/CLAUDE.md 와 foo/CLAUDE.md 를 읽는다. 컨텍스트에는 foo/CLAUDE.md 가 먼저 오고 foo/bar/CLAUDE.md 가 나중에 온다. 즉, 실행한 곳에 가까운 지시가 나중에 읽힌다. 같은 디렉터리 내에서는 CLAUDE.local.md가 CLAUDE.md 뒤에 붙는다. 하위 디렉터리의 파일은 Claude가 해당 디렉터리의 파일을 직접 읽을 때 로드된다.

자동 메모리와 무엇이 다른가

CLAUDE.md는 사람이 작성하는 반면, 자동 메모리는 Claude가 생성한다. 전자는 명시된 지시와 규칙을 담고, 후자는 배운 내용과 패턴을 저장한다. 하지만 두 장치 모두 매 세션 시작 시 컨텍스트에 로드된다. 따라서 둘 다 세션을 넘어 지속되는 지식의 원천이 된다. 이 차이를 인지하면 각 장치를 적절한 용도로 분담할 수 있다.

왜 짧게 써야 하는가

CLAUDE.md는 200줄 이하를 목표로 작성해야 한다. 파일이 길어질수록 컨텍스트를 더 차지하게 되고, 결과적으로 지시 준수도가 떨어진다. 특히 파일 크기가 4 MiB를 넘으면 Claude는 해당 파일을 통째로 건너뛴다. 따라서 불필요한 내용은 과감히 삭제하고 핵심 규칙만 남기는 것이 중요하다. 지시는 구체적으로 쓴다. "코드를 깔끔히 포맷하라" 대신 "들여쓰기는 공백 2칸"과 같이 적는다. "테스트해라" 대신 "고친 뒤에는 tests.html 을 열어 전부 통과하는지 확인한다"로 구체화한다. "파일을 정리해라" 대신 "이미지 파일은 assets 폴더에 둔다"고 명시한다. 두 규칙이 서로 모순되면 Claude가 임의로 하나를 고른다. 그러므로 주기적으로 훑어 낡거나 충돌하는 지시를 지워 일관성을 유지해야 한다.

컨텍스트 창이 무엇이고 왜 관리해야 하는가

컨텍스트 창은 모델이 새 답을 만들 때 되돌아보고 참조할 수 있는 텍스트의 양이다. 학습에 쓴 방대한 데이터와는 다르다. 이 개념은 모델의 작업 기억에 해당한다.

토큰은 모델이 글을 다루는 가장 작은 단위다. 단어일 수도 있고 단어 조각일 수도 있으며 문자일 수도 있다. Claude에서 토큰 하나는 영문 약 3.5자에 해당한다. 이 비율은 언어에 따라 달라진다. 한국어의 경우 밝혀진 환산 값이 없으므로 숫자를 추정하지 않는다.

세션을 열면 사용자가 한 글자도 치기 전에 시스템 프롬프트, 자동 메모리, 환경 정보, 도구 목록, 그리고 CLAUDE.md가 이미 들어가 있다. 학습자가 입력한 말은 그 안에서 작은 부분을 차지한다.

Claude가 파일을 읽을 때마다, 도구가 결과를 낼 때마다, 질문을 이어갈 때마다 창 내용은 늘어난다. 앞의 것은 지워지지 않고 남는다. 쌓인 텍스트는 계속 증가한다.

CLAUDE.md를 짧게 쓰는 이유는 파일이 길면 그만큼 컨텍스트 창을 차지하기 때문이다. 창이 빠듯해지면 지시 준수도가 떨어진다. 앞서 말한 200줄 목표가 여기에서 나온다. 세션이 길어졌을 때의 구체적인 대처는 4장에서 직접 해 본다.

3. 따라하기

1단계 — 실습 저장소를 가져온다

공통 저장소에서 시작하면 누구나 동일한 코드베이스를 기준으로 학습한다. 또한 학습자는 프로젝트 초기 상태를 바로 확인할 수 있어 환경 설정에 시간을 낭비하지 않는다.

터미널을 열고 다음 세 명령을 순서대로 실행해 저장소를 가져온다. 클론 후 시작 브랜치로 이동하면 5호 실습이 준비된다.

git clone https://github.com/chojiyejyeAppDev/do-it-now
cd do-it-now
git switch start/ledger-ep05

터미널 사용에 익숙하지 않다면 Claude Code에게 직접 브랜치 전환을 요청해도 된다. 대화창에서 "start/ledger-ep05 브랜치로 옮겨 줘"라고 입력하면 Claude Code가 필요한 git 명령을 대신 실행해준다.

준비 완료 후 index.html 파일을 브라우저로 열면 가계부 화면이 나타난다. 이 브랜치에는 CLAUDE.md 파일이 아직 존재하지 않는다. 학습자가 이번에 처음으로 이 파일을 작성한다.

2단계 — 규칙을 적기 전에 먼저 시켜 본다

규칙을 등록하기 전과 후의 결과를 비교하려면 기준선이 필요하다. 미리 규칙을 써둔 다음 테스트를 하면 초기 상태를 알 수 없어 차이점을 확인하지 못한다. 지금 Claude Code가 내놓은 답변이 나중에 변경된 결과와 대비되는 근거 자료가 된다.

Claude Code에게 "월별 평균 지출을 구하는 함수를 추가해 줘"라고 지시한다. 이 문장을 그대로 복사해 메모장에 저장하거나 별도로 기록해둔다. 규칙을 적은 뒤에 똑같은 지시를 다시 보낼 것이기 때문이다. 동일한 프롬프트만 사용할 때 규칙의 영향력만을 분리해 관찰할 수 있다.

받은 결과 코드를 검토하며 다음 세 가지 사실을 기록해 둔다. 첫째, 새로운 함수를 어느 파일 안에 넣었는지 확인한다. 둘째, 금액 데이터를 화면에 출력할 때 어떤 형식을 적용했는지 살펴본다. 셋째, 코드 내 주석이 한국어인지 영어인지 파악한다. 이때 좋고 나쁘다고 판단하지 않고 객관적 사실만 적어둔다.

이 단계에서 얻은 결과가 좋은지 나쁜지는 아직 결론내릴 수 없다. 3단계에서 저장소의 기존 코드와 견주어 볼 때 비로소 그 차이가 드러난다.

3단계 — 저장소가 이미 지키고 있는 규칙을 찾아낸다

이 저장소의 코드는 몇 가지 규칙을 일관되게 지키고 있다. 그러나 이 규칙들은 어디에도 문서로 적혀 있지 않다. 새로 합류한 사람도 Claude도 이 규칙을 알 길이 없다. 적혀 있지 않은 규칙은 지켜지지 않는다. 학습자는 먼저 이 숨겨진 규칙들을 찾아내야 한다.

기존 코드를 열어 보면 규칙을 찾을 수 있다. 직접 읽기 어려우면 Claude Code에게 물어봐도 된다. 금액을 화면에 내보내는 방식이 일관돼 있는지 물어볼 수 있다. 주석이 무슨 언어로 쓰여 있는지 확인할 수 있다. 통계 함수가 어디에 모여 있는지를 물어도 된다.

금액 출력은 반드시 formatWon() 을 거친다. 기존 코드에서 화폐 단위 표시가 이 함수를 통해 통일되어 있음을 관찰할 수 있다.

주석은 한국어로 쓴다. 파일 내 설명문이 영어가 아닌 한국어로 작성되어 있음을 확인할 수 있다.

새 통계 함수는 src/stats.js 에 둔다. 관련 로직이 이 파일에 집중되어 있어 새로운 기능도 여기에 추가해야 함을 알 수 있다.

2단계에서 적어둔 결과를 위 세 규칙과 견준다. 어느 파일에 넣었는지, 금액을 어떻게 내보냈는지, 주석이 무슨 언어인지 확인한다. 어긋난 것이 있으면 그것이 규칙이 적혀 있지 않아서 생긴 차이이다.

⚠️ 결과가 세 규칙을 이미 지키고 있을 수도 있다. 그것도 정상이다. Claude가 주변 코드를 보고 스스로 맞춘 것이다. 그럴 때는 "왜 formatWon() 을 썼어?"라고 물어본다. 답이 주변 코드를 보고 맞췄다는 취지라면, 규칙이 명시돼 있지 않아 매번 운에 맡기고 있다는 뜻이다. 실패한 실습이 아니다.

4단계 — CLAUDE.md를 만들고 규칙 세 개를 적는다

프로젝트 루트에 CLAUDE.md 파일을 만든다. ./.claude/CLAUDE.md 경로에도 같은 프로젝트 범위의 설정을 둘 수 있으나, 보통 루트에 둔다. 파일 탐색이 직관적이며, 다른 학습자가 저장소를 가져왔을 때 바로 눈에 띈다는 장점이 있다.

Claude Code 대화창에 /init 명령을 입력한다. Claude는 현재 코드베이스를 분석하고 적절한 초안을 생성해 준다. 파일이 이미 존재한다면 덮어쓰지 않고 내용 보정을 제안한다.

규칙은 구체적으로 적어야 한다. 모호한 지시라면 Claude가 스스로 판단해 해석의 여지를 남기므로, 확인 가능한 문장을 사용해야 한다. "금액을 보기 좋게 표시하라"와 같은 지시는 주관적이지만, "금액을 화면에 내보낼 때는 반드시 formatWon() 함수를 거친다"는 명확한 기준이 된다.

다음과 같이 마크다운 헤더로 절을 나누고 세 가지 규칙을 기록한다.

# 가계부 프로젝트 규칙
 
## 금액 표시
- 모든 금액 출력은 반드시 formatWon() 함수를 거친다.
 
## 주석 언어
- 코드 주석은 한국어로 작성한다.
 
## 파일 위치
- 새로운 통계 관련 함수는 src/stats.js 파일에 추가한다.

두 규칙이 서로 모순되면 Claude가 임의로 하나만 선택하여 적용한다. 따라서 지시사항끼리 충돌하지 않도록 주기적으로 검토해야 한다.

5단계 — 파일이 실제로 읽혔는지 확인한다

세션은 매번 빈 컨텍스트 창에서 시작하므로 지금 열려 있는 세션은 파일을 만들기 전 상태이다. 방금 만든 CLAUDE.md를 Claude에게 인식시키려면 파일을 저장한 뒤 세션을 새로 열어야 한다.

파일을 저장하고 새 세션을 시작한다.

/context 명령을 실행해 Memory files 목록에 CLAUDE.md가 올라왔는지 본다. 목록에 파일이 포함되어 있으면 CLAUDE.md가 성공적으로 읽혔음을 의미한다.

목록에 CLAUDE.md가 없으면 파일이 로드되는 위치에 있는지 확인한다. 프로젝트 루트 디렉터리나 ./.claude/ 폴더 안에 파일이 제대로 저장되어 있어야 한다.

로드를 확인하는 것과 응답이 달라졌는지 확인하는 것은 다른 일이며 뒤엣것은 4장에서 한다.

4. 확인 — 규칙이 응답을 바꿨는가

6단계 — 똑같은 지시를 다시 한다

CLAUDE.md를 만든 것만으로는 작업이 끝나지 않는다. 그 파일의 내용은 시스템 프롬프트가 아니라 그 뒤에 전달되는 사용자 메시지로 처리되기 때문에 엄격한 준수가 보장되지 않는다. 파일은 강제 설정이 아니라 컨텍스트일 뿐이다. 따라서 등록되었다는 사실보다 응답이 달라졌는지 확인해야 한다.

먼저 새 세션인지 확인한다. 3장 5단계에서 /context로 확인했던 그 세션을 사용하면 된다. 만약 다른 세션이라면 새로 열고 다시 확인한다.

지시 문장은 한 글자도 바꾸지 않는다. 3장 2단계에서 적어 둔 "월별 평균 지출을 구하는 함수를 추가해 줘"를 그대로 복사해서 붙인다. 문장을 고치면 결과가 달라진 원인이 규칙 때문인지 질문의 변경 때문인지 구분할 수 없기 때문이다.

앞서 살펴본 세 가지 요소에 집중한다. 코드를 어느 파일에 넣었는지, 금액은 어떻게 내보내는지, 주석은 무슨 언어로 작성되었는지를 본다. 이번에도 좋고 나쁨을 판단하지 않고 사실만 기록한다.

7단계 — 두 결과를 나란히 적는다

눈으로 보고 넘기면 기억에 남지 않는다. 이 표가 이 회차 학습 목표의 달성 근거가 된다.

셋 중 하나라도 규칙 쪽으로 옮겨 갔으면 확인된 것이다. 예를 들어 앞에서는 금액을 그냥 문자열로 붙였는데 뒤에서는 formatWon()을 거쳤다면 그것이 차이다.

앞뒤가 같아도 실패가 아니다. 규칙을 적기 전에도 이미 지켜져 있었을 수 있다. Claude가 주변 코드를 보고 맞춘 경우다. 그때는 표의 그 줄에 "앞뒤 같음 — 주변 코드에서 추론"이라고 적으면 된다. 적어 두지 않으면 다음에도 운에 맡기게 된다. 이것이 이 실습의 결론이다.

8단계 — 세션을 한 번 정리해 본다

대화가 길어질수록 컨텍스트 창이 차고, 창이 빠듯해지면 지시 준수도가 떨어진다. 지금까지 실습을 따라오다 보니 이미 상당히 쌓여 있을 것이다. 2장에서 컨텍스트 창이 계속 찬다고만 언급했고, 이제 직접 대처 방법을 살펴본다.

Claude Code 대화창에 /compact 를 입력한다. 이 명령은 대화를 구조화된 요약으로 대체한다. 화면에 "Conversation compacted"가 표시되며, 요약하는 과정 자체는 터미널에 나타나지 않는다.

컨텍스트가 성능에 영향을 주기 시작할 때 또는 긴 새 작업을 시작하기 전에 쓴다.

실행 전후로 화면이 어떻게 달라졌는지 한 문장으로 적어 둔다. 이것이 이 단계의 과제다.

/compact 뒤에도 CLAUDE.md는 다시 읽혀 세션에 돌아온다. 시스템 프롬프트와 메모리도 마찬가지다. /context를 다시 실행해 Memory files에 CLAUDE.md가 여전히 있는지 확인한다.

그러나 대화 중에만 말한 지시는 사라진다. 요약에 뭉개지거나 남지 않는다. 따라서 파일에 적어 둔 것과 말로만 한 것의 차이가 여기서 눈에 보인다. 첫 장에서 매번 다시 설명해야 한다고 했던 문제의 답이 이것이다.

아무것도 달라지지 않았을 때

CLAUDE.md를 고쳤는데도 반응이 없다면 /context 명령을 실행한다. 출력되는 Memory files 목록에 수정한 파일 이름이 실려 있는지 확인한다. 목록에 해당 파일이 없으면 Claude는 그 파일을 보지 못한 것이다.

파일의 물리적 위치를 다시 살펴본다. 프로젝트 루트 디렉터리에 있거나 ./.claude/ 폴더 안에 있어야 제대로 로드된다. 이 두 곳 어디에도 없으면 Claude는 그 파일을 무시한다.

지시의 표현을 더 구체적으로 다듬는다. 확인할 수 있는 명확한 문장으로 바꾼다. "깔끔히 정렬해라" 같은 모호한 말은 들여쓰기 규칙이나 파일 구조처럼 검증 가능한 지시로 대체해야 한다.

파일 안에 서로 어긋나는 지시가 있는지 훑어본다. 두 규칙이 충돌하면 Claude가 임의로 하나를 고른다. 일관성을 해치는 내용을 찾아서 삭제하거나 통일한다.

특정 시점에 반드시 실행돼야 하는 일이 있다면 CLAUDE.md에는 적지 않는다. 그런 작업은 훅으로 구현해야 한다. 훅의 상세 설명은 이 회차 범위 밖이므로 여기서는 구분선까지만 그린다.

5. 실습 과제 — 자기 규칙 하나를 만들어 제출한다

과제

CLAUDE.md에 학습자 자신의 규칙을 한 개 추가하고, 그 규칙이 Claude의 응답을 실제로 바꿨는지 확인한 뒤, Pull Request로 결과를 제출한다. 제출물에는 수정된 CLAUDE.md 파일과 4장에서 작성했던 전후 비교 표가 포함되어야 한다. 이 비교 표를 Pull Request 본문에 직접 붙여서 검토자가 한눈에 결과를 확인할 수 있게 만든다.

제출한 Pull Request는 단순히 쌓아두는 것이 아니라 검토를 받는다. 리뷰 담당자가 제출된 규칙의 명확성과 응답 변화의 유의미성을 점검하고 회신을 보낸다.

어떤 규칙을 고를 것인가

CLAUDE.md에 적을 규칙은 일상적인 작업 흐름에서 발견되는 네 가지 신호를 통해 선별한다. 첫 번째 신호는 Claude가 동일한 실수를 두 번째로 반복할 때이다. 예를 들어 매번 날짜 형식을 YYYY-MM-DD 대신 MM/DD/YYYY로 잘못 출력한다면, "날짜 출력 시 ISO 8601 형식을 사용한다"는 규칙으로 이를 차단할 수 있다.

두 번째 신호는 코드 리뷰에서 Claude가 이미 알고 있어야 했던 지식이나 관례를 지적받았을 때이다. 예를 들어 변수 명명 방식을 camelCase 대신 snake_case로 고치는 코멘트가 자주 붙는다면, "변수명은 항상 snake_case로 작성한다"는 규칙을 등록하여 불필요한 수정 사항을 줄일 수 있다.

세 번째 신호는 과거 세션에서 이미 한 번 정정을 요청했던 내용을 현재 세션에서 다시 똑같이 정정해야 할 때이다. 예를 들어 이전 세션에서 에러 로그에 타임스탬프를 추가하라고 명령했으나 새 세션에서 또 잊어버린 경우, "모든 에러 로그에 ISO 8601 타임스탬프를 포함한다"는 규칙을 추가하면 된다.

네 번째 신호는 새로 합류한 팀원이라면 동일한 맥락이나 배경 지식을 필요로 할 만한 내용일 때이다. 예를 들어 특정 비즈니스 로직의 가정 조건이 코드 주석으로만 남아 있다면, "주문 상태 변경 시 재고 차감 전 유효성 검사를 수행한다"는 규칙을 CLAUDE.md에 명시하여 지식의 단절을 방지할 수 있다.

선택한 규칙은 구체적으로 작성해야 한다. 모호한 지시어 대신 확인 가능한 문장으로 작성하는 것이 핵심이다. "코드를 깔끔하게 정리하라"는 표현은 피하고, "금액을 화면에 내보낼 때는 반드시 formatWon() 을 거친다" 처럼 기계적으로 검증할 수 있는 서술로 바꾸는 것이 좋다.

추가하려는 규칙이 여러 단계로 구성된 절차이거나 코드베이스의 일부 디렉터리에만 해당되는 내용이라면 CLAUDE.md에 적지 않는다. 그러한 경우 스킬 또는 경로 한정 규칙으로 분류해야 한다. 따라서 과제로 적합한 규칙은 프로젝트 전체에 걸쳐 적용되며 한 줄로 표현될 수 있는 명확한 지시여야 한다.

제출 절차

작업할 브랜치를 만든다. 시작점은 start/ledger-ep05 브랜치이며, 아래 명령을 참고하여 새 브랜치를 생성한다. 이 명령의 my-ep05 부분에 자기 이름을 넣으면 된다.

git switch -c my-ep05 origin/start/ledger-ep05

CLAUDE.md 파일을 열고 새로 만든 규칙을 추가한 후 저장한다. 기존 세 가지 규칙 옆에 네 번째 규칙을 정리된 형식으로 덧붙인다.

4장에서 사용했던 방법대로 Claude Code와 상호작용하여 전후 응답의 차이를 확인한다. 관찰된 결과를 표로 채워 기록한다.

변경 사항을 커밋하고 생성한 브랜치로 푸시한다. 로컬 저장소에 있는 변경분을 원격 저장소의 해당 브랜치로 업로드하는 과정이다.

GitHub에서 Pull Request를 생성한다. PR 본문에는 왜 해당 규칙을 추가했는지에 대한 의도와, 전후 응답의 차이를 보여주는 비교 표를 포함한다. 학습자는 자신의 fork 또는 로컬 clone 환경에서 이 모든 작업을 수행하며, 원본 저장소는 읽기 전용으로만 참조한다.

제출 전에 점검할 것

• /context 명령 실행 시 Memory files 목록에 CLAUDE.md가 실제로 로드되었는지 확인했다.
• 추가한 규칙이 "코드를 깔끔히 하라"와 같이 추상적이지 않고, "금액은 formatWon() 을 거친다" 처럼 구체적으로 서술되어 있다.
• 새로 추가한 규칙이 기존에 등록된 세 가지 규칙과 모순되지 않는지 검토했다.
• 저장소 내 파일명이나 디렉터리명에 한글을 사용하지 않았는지 확인했다. 경로명은 영문, 파일 내용만 한국어로 작성하는 규칙을 따랐다.
• 4장의 양식을 따라 전후 응답 비교 표를 충실히 채웠다.
• 컨텍스트 창과 토큰이 무엇인지 자기 문장으로 두세 문장으로 적어 보았고, /compact 실행 전후의 화면 변화를 한 문장으로 남겼다.

막혔을 때

규칙 등록 후에도 Claude의 응답이 예상대로 변하지 않으면 4장의 점검 순서로 돌아가야 한다. 먼저 /context 명령으로 파일이 컨텍스트에 포함되었는지, 그다음 파일 위치와 구체성, 모순 여부를 차례로 확인한다.

저장소에는 정답 예시를 담은 answers 브랜치가 존재한다. 먼저 스스로 문제를 해결해 본 후에 참고용으로 이 브랜치를 열어볼 수 있다. 규칙이 과도하게 늘어 파일 길이가 늘어나면 /doctor 명령을 실행하여 덜어낼 내용을 제안받는다. 공식 문서는 CLAUDE.md의 길이를 200줄 이하로 유지하는 것을 목표로 하며, 너무 긴 파일은 지시 준수도를 낮추기 때문이다.

6. 정리하며

이번 회차에서 한 일

반복되는 설명의 부담을 줄이기 위해 프로젝트 규칙을 파일로 남기는 방법을 익혔다. CLAUDE.md가 세션 시작 시 어떻게 로드되고 적용되는지 이해한 뒤, 실습 저장소에서 직접 규칙을 등록하고 응답의 변화를 확인했다.

세션은 매번 빈 컨텍스트로 시작하지만, 파일에 적어 둔 것은 다음 세션으로 건너간다. 대화 창 안에만 남았던 지시는 세션 종료와 함께 사라지지만, CLAUDE.md에 기록된 내용은 지속적으로 읽히며 일관된 행동을 유도한다. 이 차이를 명확히 구분하는 것이 컨텍스트 관리의 첫걸음이다.

계속 쓰려면 — 습관 셋

같은 정정을 두 번 치면 그때 규칙으로 남긴다. 처음부터 완벽한 가이드라인을 작성하려 하면 오히려 부담이 되지만, 반복되는 오류나 요청은 규칙으로 적을 때가 됐다는 신호이므로 즉시 파일에 기록한다.

주기적으로 파일을 훑어 낡거나 충돌하는 지시를 지운다. 상충되는 두 규칙이 공존하면 Claude가 임의로 하나를 선택하게 되어 의도하지 않은 동작이 발생할 수 있으므로, 규칙 간 일관성은 유지해야 한다.

파일이 길어지면 덜어내어 200줄 이하로 관리한다. 파일 크기가 커질수록 컨텍스트 사용량이 증가하고 지시 준수도가 떨어지므로, /doctor 명령을 활용해 코드베이스에서 유추할 수 있는 내용은 제거하는 등 정기적인 정리가 필요하다.

다음 회차

다음은 최신편이며 설정과 컨텍스트 관점의 최신 소식 다이제스트를 다룬다. 구체적인 기능 이름이나 소식 목록은 발행 시점에 확정되므로, 현재 단계에서는 내용을 예측하지 않는다.

발행 시점의 변경 사항 중 자기 프로젝트에 반영할 항목을 골라, 이번 회차에서 작성한 CLAUDE.md의 수정안으로 옮겨 적는다. 이번에 만든 파일이 다음 회차 업데이트의 기반이 된다.