파일에 적어 두면 Claude Code가 다음에도 기억할까?

Claude Code와 강의 신청 페이지를 만들며 정원을 8명으로 정했다고 해보자. 그 결정을 파일에 적어 두었다면, 며칠 뒤 새 대화에서 신청 문구를 고칠 때도 Claude가 알아서 8명을 기준으로 작업할까?

다시 연 프로젝트 폴더에는 지난번에 만든 페이지와 강의 기획 문서가 그대로 있다. 그런데 대화창은 새로 시작했다. 정원을 또 설명하기에는 이미 적어 둔 문서가 아깝고, 설명하지 않자니 그 내용을 알고 작업할지 확신이 서지 않는다.

이 강의와 아래 파일 내용은 설명을 위한 가상의 예시다. 내 컴퓨터에 보관한 같은 프로젝트 폴더에서 Claude Code를 다시 여는 상황을 가정한다. 제품의 동작은 2026년 10월 5일 확인한 공식 문서를 기준으로 설명한다.

첫날에는 Claude와 대화하며 “한 사람씩 충분히 피드백하려면 정원은 8명이 좋겠다”라고 결정했다. 대화를 마치기 전에 “오늘 확정한 정원과 그 이유를 강의 기획 문서에 적어 줘”라고 부탁한다. Claude가 만든 course-plan.md를 열어 보니 정원과 이유가 적혀 있다. 이 파일을 앞으로 강의의 현재 결정을 확인할 문서로 삼는다.

course-plan.md라는 이름은 이 예시에서 고른 것이다. 끝의 .md는 제목과 목록 등을 간단한 기호로 표시하는 텍스트 문서 형식이다. 여기서 중요한 것은 파일 이름보다 실제 내용이다. 대화에서 정한 8명이 문서에도 들어갔는지 확인할 수 있다.

이제 남은 기록은 두 가지다. 하나는 왜 8명으로 정했는지 주고받은 대화이고, 다른 하나는 확정한 내용을 옮겨 적은 파일이다. Claude Code는 로컬에서 작업할 때 대화 기록도 저장한다. 하지만 새 대화를 시작하면 이전 대화 내용이 자동으로 들어오지는 않는다. 이전 대화를 이어 여는 것과 새 대화를 여는 것은 다르다.[1]

며칠 뒤 같은 폴더에서 새 대화를 시작해도 저장해 둔 기획 문서가 함께 지워지는 것은 아니다. 파일을 남겨 둔 덕분에 정원과 그 이유를 다시 확인할 수 있다. 다만 Claude가 이번 작업에서도 그 문서를 읽었는지는 아직 알 수 없다.

새 대화에서 “신청 안내를 좀 더 친근하게 고쳐 줘”라고만 요청했다고 하자. Claude가 신청 페이지를 읽고 문구를 고칠 수는 있다. 하지만 그 과정에서 강의 기획 문서까지 읽었을 것이라고 단정할 수는 없다. Claude Code는 요청에 따라 필요한 파일을 찾아 읽는 도구를 사용한다. 폴더에 접근할 수 있다는 사실이 모든 파일의 내용을 이미 읽었다는 뜻은 아니다.[1]

Claude가 지금 답하거나 작업할 때 참고하는 정보를 컨텍스트라고 부른다. 현재 대화와 읽어 온 파일 내용 등이 여기에 들어간다.[1] 기획 문서의 정원도 Claude가 그 문서를 읽으면 컨텍스트에 들어온다. 그러면 신청 문구를 고칠 때 그 내용을 참고할 수 있다.

이때 특별한 역할을 하는 파일이 CLAUDE.md다. Claude Code에 프로젝트의 작업 지침을 알려 주는 문서다. 기본 설정에서는 작업을 시작한 폴더의 CLAUDE.md를 새 대화가 시작될 때 불러온다.[2] 반면 예시의 course-plan.md는 보통의 자료 파일이다. 같은 폴더에 둔 것만으로 시작할 때 함께 불러오는 문서가 되지는 않는다.

따라서 기획 문서를 읽게 하는 방법이 필요하다. 지금 하는 요청에 “먼저 course-plan.md를 읽고 정원을 확인해 줘”라고 덧붙일 수 있다. CLAUDE.md에 “신청 페이지를 고치기 전에 강의 기획 문서를 읽는다”라는 지침을 남길 수도 있다.

다만 파일을 읽으라는 문장을 적는 것과 그 파일 내용을 자동으로 불러오는 것은 다르다. 시작할 때 기획 문서도 함께 불러오고 싶다면 CLAUDE.md에 @course-plan.md라고 적을 수도 있다.[2] 이 강의 예시에서는 이 표기 대신, 신청 페이지를 고칠 때 기획 문서를 읽도록 안내한다.

CLAUDE.md를 처음 알면 강의에 관한 내용을 모두 여기에 적고 싶어진다. 정원, 일정, 가격, 신청 문구 초안까지 한곳에 있으면 편할 것 같다. 그러나 페이지의 색상만 바꾸는 날에도 지난 문구 초안을 전부 읽을 필요는 없다. 공식 문서도 매번 필요한 지침을 짧고 일관되게 유지하라고 권한다.[2]

이 강의에서는 계속 유지할 작업 방식과 강의의 세부 결정을 나누는 편이 낫다. CLAUDE.md에는 문구를 쓰는 방식과 확인할 문서의 위치를 적는다. course-plan.md에는 현재 정원과 그 이유를 적는다. 두 파일의 내용은 다음 정도에서 시작할 수 있다.

신청 안내는 처음 오는 사람도 이해할 수 있는 짧은 문장으로 쓴다.
신청 페이지를 고치기 전에 course-plan.md에서 현재 결정을 확인한다.

# 강의의 현재 결정
- 정원: 8명
- 이유: 참가자 한 사람씩 충분히 피드백할 시간을 확보한다.

이렇게 나누면 정원이 바뀌었을 때 고칠 곳이 분명해진다. CLAUDE.md의 “기획 문서를 확인한다”는 안내는 유지할 수 있다. 정원은 기획 문서에서 바꾼다. 두 문서에 정원을 각각 적어 놓고 어느 쪽이 최신인지 다시 따지는 일을 줄일 수 있다.

Claude Code에는 Claude가 다음 대화를 위해 스스로 메모를 남기는 auto memory, 즉 자동 메모리도 있다. 사람의 선호나 교정한 내용 등을 기록하며, 매번 모든 내용을 저장하지는 않는다. 시작할 때는 메모의 짧은 색인을 불러오고 자세한 메모는 필요할 때 읽는다.[2]

자동 메모리에 “신청 안내는 짧게 쓴다”는 선호가 남으면 도움이 될 수 있다. 그렇다고 강의의 최신 정원을 그 메모에만 맡기지는 않는 편이 낫다. 이 예시에서는 현재 정원을 정하는 기준 문서가 course-plan.md다. 자동 메모리에 강의 이야기가 남아 있더라도 실제 신청 문구를 고칠 때는 그 문서를 다시 확인하도록 한다.

며칠 뒤 새 대화에서 신청 문구를 고치는 장면으로 돌아가 보자. “지난번 정원 기억하지?”라고 묻는 대신, “course-plan.md를 읽고 현재 정원을 먼저 알려 줘. 그 정원을 유지하면서 신청 안내를 친근하게 고쳐 줘”라고 요청할 수 있다. 이 요청은 Claude가 막연히 기억을 주장하기보다 확인할 파일을 읽도록 돕는다.

작업 중에는 해당 파일을 읽은 기록을 살핀다. Claude가 설명한 정원도 기획 문서의 8명과 대조한다. 마지막으로 수정된 페이지를 열어 정원 안내가 8명으로 유지되었는지 확인한다. 파일을 읽었더라도 결과에 잘못 반영할 수 있으므로 읽은 기록과 작업 결과를 함께 확인한다.

시작할 때 지침 파일이 들어왔는지 궁금하면 Claude Code의 입력창에서 /context를 사용할 수 있다. Memory files 항목에서 불러온 지침 파일을 확인한다. /memory는 지침이나 메모 파일을 찾아 열고 고칠 때 쓴다.[2] 이 목록을 확인했다고 강의 기획 문서까지 읽었거나 결과가 맞다고 판단하는 것은 아니다.

이후 강의 정원을 10명으로 늘리기로 했다고 하자. Claude에게 신청 페이지의 숫자만 바꾸도록 요청하면 화면은 맞더라도 기획 문서에는 8명이 남는다. 다음 대화에서 그 문서를 성실하게 읽을수록 오히려 옛 정원을 사용할 수 있다. 이번에는 기록을 안 읽어서 생기는 문제가 아니라, 읽은 기록이 오래되어 생기는 문제다.

정원이 바뀌면 course-plan.md의 현재 정원부터 10명으로 고친다. 정원을 늘릴 수 있게 된 이유도 실제 결정에 맞춰 수정한다. 이전의 8명을 기록으로 보존하려면 현재 결정과 구분해 지난 결정으로 표시한다. 신청 페이지에도 10명을 반영한 뒤 두 내용을 대조한다. 자동 메모리나 다른 지침에 8명이 현재 정원처럼 남아 있다면 그 기록도 바로잡는다.

CLAUDE.md에 지침을 적었다고 Claude가 언제나 그대로 따른다는 보장은 없다. 이 파일은 작업에 참고할 지침이지, 어기는 행동을 무조건 막는 장치는 아니다.[2]

파일에 적어 두면 다음에도 기억할까? 다시 읽을 기록은 남지만, 저장만으로 다음 작업에 쓰인다는 보장은 없다.

다음 대화에서는 Claude가 course-plan.md에서 정원 10명을 확인했는지 살피고, 실제 신청 페이지에도 10명이 반영됐는지 대조한다.

1. Anthropic, How Claude Code works
2. Anthropic, How Claude remembers your project