파일 이름을 꼭 CLAUDE.md 로 해야 하나요?

클로드 코드는 CLAUDE.md 를 읽습니다. 여러 AI 도구가 함께 쓰는 이름으로 AGENTS.md 도 있고, 도구에 따라 둘 다 읽기도 합니다. 만들 때 AI에게 물어보면 지금 쓰는 도구에 맞는 이름으로 만들어줍니다.

여기 적으면 100% 지켜지나요?

아닙니다. 강한 힌트일 뿐 강제 규칙이 아닙니다. 반드시 막아야 하는 것은 문서가 아니라 도구 설정으로 막아야 합니다.

짧을수록 좋습니다. 이 파일은 매 대화마다 자리를 차지하고, 길면 AI가 중요한 줄을 놓칩니다. 40줄 안쪽을 권합니다.

절대 안 됩니다. 이 파일은 보통 팀 전체에 공유되고, AI가 읽어서 대화에 그대로 옮길 수도 있습니다. 그건 환경변수의 자리입니다.

2화에서 대화를 비우는 법을 배웠습니다. 그런데 비우고 나면 이런 일이 생겨요.

새 대화 → AI가 설명을 영어로 씀 → "한국어로 써줘" → 수정
새 대화 → AI가 설명을 영어로 씀 → "한국어로 써줘" → 수정   (무한 반복)

대화 안에서 고쳐주는 건 그 대화에서만 유효합니다. 비우면 같이 사라져요. 그래서 오래 갈 규칙은 파일에 적어야 합니다.

프로젝트 폴더에 마크다운 파일(제목·목록 정도만 쓰는 아주 단순한 텍스트 파일)을 하나 두면, AI가 대화를 시작할 때마다 그걸 먼저 읽습니다.

새 직원이 올 때마다 "우리 팀은 이 도구를 쓰고, 화면은 이렇게 맞추고"를 말로 반복하지 않고 문서 하나를 건네주는 것과 같아요. 자세한 건 에이전트 메모리 파일에 정리해뒀습니다.

[설명서 없음]  새 대화 → 아무것도 모르는 상태에서 시작
[설명서 있음]  새 대화 → 파일 자동 로드 → 규칙을 알고 시작

코드를 보면 알 수 있는 건 적지 마세요. 폴더 구조나 파일 목록은 AI가 직접 보면 됩니다. 적어야 할 건 코드에 안 드러나는 것들이에요.

적을 것	예
코드만 봐선 알 수 없는 규칙	"새 화면을 만들면 휴대폰 크기에서도 꼭 확인할 것"
예전에 해봤다가 실패한 방법	"이 방식으로 만들었다가 갈아엎었음 — 다시 제안하지 말 것"
실행 방법	"만든 페이지는 `index.html` 을 브라우저로 열어서 확인한다"
건드리면 안 되는 것	"`legacy/` 폴더는 옛날 코드라 수정 금지"

두 번째가 특히 값집니다. 실패한 시도를 안 적어두면 AI가 몇 번이고 같은 걸 다시 제안합니다.

처음부터 손으로 쓸 필요 없습니다. /init 을 치면 AI가 프로젝트를 훑어서 초안을 만들어줘요.

그다음부터는 일하다가 같은 지적을 두 번 하게 되는 순간 한 줄씩 추가하는 게 가장 현실적인 관리법입니다.

/memory 를 치면 어느 설명서를 열지 물어봅니다.

1. User memory      ← 내 컴퓨터의 모든 프로젝트에 적용
2. Project memory   ← 지금 이 프로젝트에만  ← 이걸 고르세요

Project memory 를 고르면 이 프로젝트의 CLAUDE.md 가 열립니다. 거기에 한 줄 적고 저장하면 끝이에요. 6화에서 팀과 나눠 쓰는 것도 이쪽입니다.

미리 완벽한 문서를 만들려고 하지 마세요. 겪은 것만 적는 게 훨씬 잘 작동합니다.

claude-test 폴더에서 합니다.

cd ~/claude-test
claude

1. 설명서를 만듭니다.

/init

만들어진 내용을 한 번 읽어보세요. 너무 길면 이렇게 줄이면 됩니다.

방금 만든 설명서에서 코드를 보면 알 수 있는 내용은 빼줘. 전체 30줄 안쪽으로 줄여줘

2. 규칙을 하나 추가합니다. /memory 를 치고 Project memory 를 고르면 설명서가 열려요. 맨 아래에 이 한 줄을 적고 저장합니다.

- 모든 설명과 주석은 한국어로 쓴다

3. /clear 로 대화를 비웁니다. 아무것도 모르는 상태로 만드는 거예요.

4. 비운 상태에서 이렇게 시켜봅니다.

@index.html 에 간단한 설명 주석을 몇 개 넣어줘

5. 주석이 한국어로 나오면 성공입니다. 나는 이번 대화에서 그런 말을 한 적이 없는데도요 — 설명서를 읽고 시작했기 때문입니다.

다음 화에서는 나만의 커맨드 만들기를 다룹니다. 매번 길게 타이핑하는 지시가 있다면, 그걸 /오늘정리 같은 커맨드 하나로 줄일 수 있습니다.