CLAUDE.md에는 무엇을 적어야 하나

“지난번처럼 해 줘.”

사람 사이에서는 꽤 잘 통하는 말입니다. 같은 팀에서 몇 달 일한 동료라면 지난번 보고서의 길이와 표 모양, 무엇을 빼야 하는지까지 떠올릴 수 있어요. 클로드 코드의 새 세션에서는 이런 기억을 대화에만 기대하면 결과가 흔들립니다.

바이브 코딩이 한 번의 멋진 요청으로 끝나지 않는 이유가 여기에 있습니다. 프로젝트가 여러 파일로 늘고 수정이 반복되면, 매번 다시 설명해야 하는 기준이 생겨요.

• 외부 전송 기능은 넣지 않는다.
• 데이터가 없는 상태와 0을 구분한다.
• 수정 뒤 테스트를 실행한다.
• 기존 링크와 합계가 깨지면 완료라고 보고하지 않는다.
• 한 번에 한 기능만 바꾼다.

이런 기준을 프로젝트 폴더의 CLAUDE.md에 남길 수 있습니다. 클로드 코드는 세션을 시작할 때 이 파일을 프로젝트 지침으로 읽습니다.

CLAUDE.md는 채팅 기록의 요약이 아닙니다. 다음 수정에서도 계속 지켜야 할 프로젝트의 작업 규칙입니다.

일반 규칙 파일과 CLAUDE.md의 차이

앞선 장에서 문서·업무용 규칙 파일을 사용했습니다. 목적, 입력, 금지 범위, 검증, 보관 위치를 적어 코워크나 일반 대화에 첨부할 수 있었어요.

CLAUDE.md는 같은 생각을 코드 프로젝트 안에 고정한 형태입니다. 프로젝트 루트에 두면 클로드 코드가 새 세션에서도 읽을 수 있어요. 빌드 방법, 테스트 명령, 파일 구조, 변경 원칙처럼 프로젝트 전체에 적용되는 내용을 적습니다.

두 문서는 역할이 조금 다릅니다.

CLAUDE.md가 있다고 규칙이 강제로 집행되는 것은 아닙니다. 클로드가 읽고 따르는 지침이므로 여전히 결과 검증이 필요해요. 반드시 실행돼야 하는 검사는 테스트 명령으로 따로 만들어야 합니다.

도구 홈 프로젝트에 넣을 규칙

다음 장에서 여러 파일로 구성된 ‘내 도구 홈’을 만듭니다. 프로젝트 폴더에는 일곱 도구의 결과와 재생성 요청문이 연결돼 있어요.

검증판의 CLAUDE.md에는 다음처럼 짧은 규칙을 두었습니다.

프로젝트 목적
앞선 일곱 결과와 재생성 요청문을 찾는 개인용 정적 웹 인덱스다.

유지 규칙
- 외부 전송, 로그인, 분석 추적 기능을 추가하지 않는다.
- data/tools.json의 7개 도구와 결과·요청문 링크 14개를 유지한다.
- 실시간 상태나 사용 점수를 임의로 만들지 않는다.
- 수정 후 node --test tests/tool-home.test.mjs를 실행한다.
- 기존 테스트가 실패하면 완료라고 보고하지 않는다.
- 한 번에 한 기능만 수정하고 변경 파일 목록을 보고한다.

이 문서에는 화면 색상이나 카드의 세부 설명을 모두 적지 않았습니다. 코드를 읽으면 알 수 있는 내용도 넣지 않았어요. 지우면 실수가 다시 생길 규칙만 남겼습니다.

공식 권장도 같은 방향입니다. CLAUDE.md는 짧고 사람이 읽을 수 있게 유지하고, 빌드·테스트 명령과 프로젝트 고유의 결정, 자주 생기는 실수를 중심으로 적는 편이 좋습니다. 길어질수록 중요한 지침이 묻힐 수 있어요.

첫 요청 — 프로젝트를 읽고 규칙을 요약하게 한다

새 Code 세션에서 곧바로 기능을 추가하지 않습니다.

“이 프로젝트를 수정하지 말고 구조를 먼저 읽어 주세요. CLAUDE.md에서 반드시 지킬 규칙, 실행할 테스트 명령, 데이터 파일의 도구 수와 링크 수를 요약하세요. 규칙끼리 충돌하거나 현재 파일 구조와 맞지 않는 부분이 있으면 실행 전에 알려 주세요.”

응답에서 다음을 확인합니다.

• 도구 7개.
• 결과와 요청문 링크 14개.
• 테스트 명령.
• 외부 전송과 근거 없는 상태 표시 금지.
• 한 번에 한 기능 수정.

하나라도 빠지면 기능 요청을 보내기 전에 CLAUDE.md의 위치와 내용을 다시 확인합니다.

터미널이나 명령 인터페이스를 사용하는 사람은 /context에서 프로젝트 지침이 실제로 로드됐는지 확인할 수 있습니다. 데스크톱 그래픽 화면에서는 세션이 읽은 프로젝트와 파일을 보고 규칙 요약을 먼저 받는 방식으로 확인해도 돼요.

규칙이 모호하면 행동도 흔들린다

첫 규칙을 다음처럼 썼다고 해 볼게요.

“사용하기 좋은 화면을 만들고 테스트하세요.”

자연스러운 문장이지만 판정하기 어렵습니다. ‘사용하기 좋은’의 기준이 없고, 어떤 테스트를 언제 실행할지도 불분명해요.

수정된 규칙은 행동과 실패 조건을 적습니다.

“검색 기능을 수정한 뒤 node --test tests/tool-home.test.mjs를 실행한다. 테스트가 한 개라도 실패하면 완료라고 보고하지 않고 실패한 항목과 변경 파일을 먼저 보고한다.”

좋은 규칙은 성격을 부탁하지 않습니다. 언제 무엇을 하고, 어떤 결과면 멈출지 말합니다.

대화 지시와 프로젝트 규칙이 충돌할 때

새 세션에서 이런 요청을 보낼 수 있습니다.

“테스트는 생략하고 검색 기능만 빨리 추가해 주세요.”

이 요청은 프로젝트 규칙과 충돌합니다. 이럴 때 클로드가 무조건 규칙을 이긴다고 기대해서는 안 돼요. 사용자가 스스로 충돌을 발견하고 요청을 고쳐야 합니다.

“검색 기능을 추가해 주세요. 변경 뒤 프로젝트 규칙에 적힌 테스트를 실행하고, 기존 14개 링크와 도구 7개가 유지되는지 확인하세요.”

프로젝트 지침은 사용자의 판단을 대신하는 보안 장치가 아닙니다. 잊기 쉬운 기준을 세션 앞에 다시 놓아 주는 장치예요.

규칙과 테스트를 분리한다

CLAUDE.md에는 “링크 14개를 유지한다”라고 적을 수 있습니다. 하지만 실제로 링크가 존재하는지는 테스트가 확인해야 해요.

검증판에는 다음 검사가 있습니다.

• 도구가 정확히 7개인가.
• ID가 중복되지 않았는가.
• 결과 링크와 요청문 링크 14개가 모두 존재하는가.
• 회의 검색이 회의록 보고서 한 개만 반환하는가.
• 업무 분류가 세 개를 반환하는가.
• 근거 없는 status와 score 필드가 없는가.

규칙은 무엇이 중요하다고 선언하고, 테스트는 현재 결과가 그 선언을 지키는지 확인합니다. 둘을 함께 사용해야 바이브 코딩이 느낌에서 제작 절차로 바뀝니다.

CLAUDE.md를 길게 만들지 않는 법

프로젝트를 고칠 때마다 새 규칙을 한 줄씩 추가하면 문서는 금방 비대해집니다. 모든 실패를 영구 규칙으로 만들 필요는 없어요.

다음 질문으로 걸러 냅니다.

1. 이 규칙이 프로젝트의 여러 수정에 계속 적용되는가.

2. 코드만 읽어서는 알기 어려운 결정인가.

3. 지우면 같은 실수가 다시 날 가능성이 큰가.

4. 자동 테스트로 옮기는 편이 더 정확하지 않은가.

5. 다른 규칙과 충돌하지 않는가.

특정 날짜의 테스트 자료나 개인 경로처럼 공유하면 안 되는 정보는 프로젝트 밖의 개인 지침 파일에 따로 둘 수 있습니다. 팀과 공유할 규칙과 나만 쓰는 설정을 구분해 두는 거예요. 개인 지침을 어디에 두는지는 도구 버전에 따라 달라질 수 있으니 현재 공식 문서에서 확인하세요.

규칙을 고치는 실제 흐름

기능 추가 뒤 기존 링크 검사가 누락됐다고 해 보겠습니다.

첫 번째 행동은 CLAUDE.md에 긴 반성문을 쓰는 것이 아닙니다.

1. 실패한 테스트를 확인합니다.

2. 빠진 검사를 테스트 파일에 추가합니다.

3. “기능 수정 뒤 테스트를 실행한다”는 규칙이 없다면 짧게 보탭니다.

4. 같은 기능을 다시 수정해 규칙과 테스트가 함께 작동하는지 봅니다.

5. 중복되거나 막연한 문장을 정리합니다.

규칙도 코드처럼 실패를 근거로 고칩니다.

규칙이 실제로 읽혔는지 기록한다

CLAUDE.md를 만들어 두는 것만으로는 규칙이 실제로 읽혔는지 알 수 없습니다. 새 Code 세션을 열 때 다음을 짧게 적어 두세요.

• 선택한 프로젝트 폴더.
• 세션 시작 직후 클로드가 요약한 규칙.
• 요약에서 빠지거나 지켜지지 않은 규칙.
• 첫 변경에서 실제로 수정된 파일 목록.
• 테스트 명령과 결과.
• 규칙을 한 줄 바꾼 뒤 행동이 달라졌는지.

마지막 항목이 가장 쓸모 있습니다. 규칙을 고쳤는데 결과가 그대로라면, 그 문장은 지침이 아니라 장식이었다는 뜻이에요. 그때는 규칙을 더 길게 쓰는 대신 테스트로 옮기는 편이 정확합니다.

책에 적힌 검사 항목과 숫자는 가상 프로젝트에서 확인한 기준값입니다. 계정과 앱 버전에 따라 응답 문구와 파일 선택은 달라질 수 있으니, 직접 확인한 값과 책의 기준값을 나누어 남기세요.

완성 기준

• 프로젝트 루트에 짧은 CLAUDE.md가 있다.
• 목적, 유지 규칙, 테스트 명령이 적혀 있다.
• 프로젝트를 읽으면 알 수 있는 장황한 설명은 넣지 않았다.
• 새 세션에서 규칙을 요약하게 해 로드 여부를 확인했다.
• 규칙에 적힌 검증을 실제 테스트가 확인한다.
• 대화 요청과 규칙이 충돌하면 사람이 요청을 고친다.
• 직접 확인한 값과 책의 기준값을 구분해 남긴다.

“지난번처럼”을 대화 기억에 맡기지 마세요. 다음 수정에서도 지켜야 할 기준은 프로젝트 폴더에 남겨야 합니다.