8장. 프로젝트 기억과 설정
필수 이 단계를 따라가려면 꼭 읽으세요.한 줄 요약: 매번 말하기 귀찮은 규칙은
CLAUDE.md에 적습니다. 꼭 지켜야 하는 규칙은settings.json의 거부 규칙으로 만듭니다.
이 장의 화면은 2026년 11월 6일 리눅스에서 Claude Code 2.1.318로 실행한 결과입니다.
6장에서 봤듯이 새 세션은 지난 대화를 모릅니다. 그래서 "회의록은 표로 써 줘"를 매번 다시 말하게 됩니다. 이 장에서는 그 말을 파일에 적어 둡니다.
CLAUDE.md에 무엇을 쓰나
CLAUDE.md 는 내가 쓰는 지속 지침입니다. 프로젝트 폴더에 두면 그 폴더에서 claude를 켤 때 불려 옵니다.[1] 새로 온 동료에게 주는 업무 메모라고 생각하면 쉽습니다.
쓰는 기준은 간단합니다. Claude가 파일을 읽어도 알 수 없는 것만 적습니다.[2] 답을 쓰는 언어, 회의록의 절 구성, 결과를 저장할 폴더가 그렇습니다.
쓰지 않을 것도 있습니다.
- 폴더 구조 설명. Claude가 직접 읽어 봅니다.[2:1]
- 여러 단계로 된 절차. 이런 것은 9장의 스킬(절차를 적어 두고 이름으로 불러 쓰는 파일)이 맞습니다.[3]
- 비밀번호나 인증 정보
길이는 파일당 200줄 아래를 목표로 하세요.[1:1] 대문자나 "반드시!!"를 쌓을 필요도 없습니다. 강조를 쌓으면 오히려 규칙을 과하게 적용하기 쉽습니다.[2:2]
아쉬운 예: 회의록을 꼭!! 깔끔하게 잘 정리할 것!!
나은 예: 회의록은 결정 사항, 할 일, 다음 회의 세 절로만 쓴다.나은 예는 맞았는지 틀렸는지 확인할 수 있습니다. "깔끔하게"는 확인할 방법이 없습니다.
확인 퀴즈
`CLAUDE.md`에 적기 가장 알맞은 내용은 무엇일까요?
CLAUDE.md 만들고 확인하기
실습용 규칙입니다(파일로 보기: 8장-CLAUDE.md.txt). /exit로 나와 터미널에서 연습 폴더로 이동합니다. 맥과 리눅스는 아래를 통째로 붙여 넣습니다. notes 폴더도 함께 만듭니다.
mkdir notes
cat > CLAUDE.md <<'EOF'
# 모퉁이 카페 메모 정리 규칙
- 답은 한국어로 쓴다.
- 회의록은 결정 사항, 할 일, 다음 회의 세 절로만 쓴다.
- 할 일은 표로 쓴다. 열은 담당, 할 일, 기한이다.
- 메모에 없는 내용은 지어내지 않는다.
- 정리한 파일은 notes 폴더에 저장한다.
EOF붙여 넣은 뒤 아직 실행되지 않았으면 Enter를 한 번 더 누르세요. 아무것도 안 나오면 성공입니다. ls로 CLAUDE.md와 notes가 생겼는지 보세요.
Windows PowerShell은 mkdir notes 뒤에 notepad CLAUDE.md로 메모장을 엽니다. cat으로 시작하는 줄과 EOF 줄은 빼고 그 사이만 넣습니다. 새 파일을 만들지 물으면 예를 누르고, Ctrl + S로 저장하고 닫습니다. 이 방법은 실행해 보지 않았습니다.
새 세션이 규칙을 아는지 터미널에서 확인합니다. 이번에는 claude -p를 씁니다. -p를 붙이면 대화 창이 열리지 않습니다. 질문 하나에 답만 터미널에 찍고 바로 끝납니다. 잠깐 확인할 때 편합니다. 자세한 내용은 10장에서 다룹니다.
claude -p "이 폴더의 회의록 규칙이 뭐야? 세 줄로 답해 줘."1. 회의록은 결정 사항, 할 일, 다음 회의 세 절로만 쓰고, 메모에 없는 내용은 지어내지 않습니다.
2. 할 일은 담당, 할 일, 기한 열이 있는 표로 씁니다.
3. 답은 한국어로 쓰고, 정리한 파일은 notes 폴더에 저장합니다.대화에서 말한 적 없는 규칙을 답했습니다. 파일이 불려 왔다는 뜻입니다. 모든 프로젝트에 쓸 내 습관은 ~/.claude/CLAUDE.md에 둡니다.[1:2]
지금 실습에서는 CLAUDE.md를 직접 쓰면 됩니다. 자동으로 초안을 만드는 /init 명령도 있지만 지금은 쓰지 않습니다.
/init은 언제 쓰나요? (눌러서 펼치기)
/init은 CLAUDE.md 초안을 자동으로 만드는 명령입니다. 다만 코드를 분석해서 빌드 명령, 테스트 방법, 프로젝트 관례를 찾아 적습니다.[4] 우리 메모 폴더에는 그런 것이 없으니 직접 쓰는 편이 쉽습니다. 이 가이드에서도 실행해 보지 않았습니다. 나중에 코드 프로젝트를 다룰 때 써 보세요.
확인 퀴즈
회의 메모만 있는 폴더에서 `CLAUDE.md`를 만들려고 합니다. 이 가이드가 권하는 방법은 무엇일까요?
/memory와 자동 메모리
세션 안에서 /memory를 치면 지침 파일 목록이 나옵니다.[5]
❯ Auto-memory true
❯ Project instructions Checked in at ./CLAUDE.md
User instructions Saved in ~/.claude/CLAUDE.md
Open auto-memory folder첫 줄의 자동 메모리(Auto memory)는 Claude가 내 교정과 선호를 보고 스스로 적는 메모입니다. CLAUDE.md는 내가 쓰고, 자동 메모리는 Claude가 씁니다. 로컬 세션에서는 기본으로 켜져 있습니다.[5:1]
프로젝트마다 ~/.claude/projects/<project>/memory/ 폴더에 저장됩니다. 평범한 마크다운 파일이라 언제든 고치거나 지울 수 있습니다. 끄고 싶으면 /memory 안의 토글을 씁니다.[5:2]
"기억해 줘"라고 말하면 자동 메모리에 저장합니다.[5:3] 다만 이 폴더에서 언제나 지켜야 할 규칙이라면 CLAUDE.md에 직접 적으세요. 내가 쓴 글이라 무엇이 적혔는지 분명합니다.
확인 퀴즈
자동 메모리와 `CLAUDE.md`의 차이로 맞는 것은 무엇일까요?
settings.json 세 위치
settings.json 은 Claude Code의 동작을 바꾸는 설정 파일입니다.[6] 내용은 JSON 형식으로 씁니다. JSON은 칸 이름과 값을 정해진 모양으로 적은 글자입니다. 7장에서 만든 거부 규칙이 여기 들어 있습니다. 놓는 곳은 세 군데입니다.[6:1]
| 파일 | 적용 범위 |
|---|---|
~/.claude/settings.json | 내 컴퓨터의 모든 프로젝트 |
.claude/settings.json | 이 폴더에서 일하는 모두 |
.claude/settings.local.json | 나만, 이 프로젝트에서만 |
같은 설정이 여러 곳에 있으면 표에서 범위가 좁은 쪽이 이깁니다.[6:2][7] 예를 들어 첫째 줄 파일과 셋째 줄 파일이 서로 다르게 정했다면 셋째 줄(나만, 이 프로젝트에서만)이 이깁니다.
거부 규칙은 예외입니다. 어느 단계에서든 거부된 도구는 다른 단계가 허용할 수 없습니다.[8]
- 저장하면 실행 중인 세션에도 대부분 재시작 없이 반영됩니다.[6:3]
- 어떤 파일이 불렸는지는
/status의 Setting sources 줄에서 봅니다.[6:4] - 끝 쉼표와 주석은 쓸 수 없습니다.[9] 손으로 고친 뒤 안 먹히면 쉼표부터 보세요.
틀린 예: { "deny": ["Read(./비밀/**)"], }
맞는 예: { "deny": ["Read(./비밀/**)"] }틀린 예는 ] 뒤에 쉼표가 남아 있습니다.
확인 퀴즈
나만, 이 프로젝트에서만 쓰는 설정을 두고 싶습니다. 어떤 파일이 맞을까요?
.claude 폴더 구조
Claude Code는 프로젝트 폴더와 내 홈 폴더의 ~/.claude에서 지침, 설정, 메모리를 읽습니다.[10] 이름이 점으로 시작하는 폴더는 평소에 숨겨져 있습니다. ls -a(PowerShell은 ls -Force)로 볼 수 있습니다.
~/hello-ai-연습/터미널/ 이 프로젝트
├── CLAUDE.md 공유 지침
├── CLAUDE.local.md 나만 쓰는 지침
└── .claude/
├── settings.json 공유 설정
├── settings.local.json 나만 쓰는 설정
├── skills/ 이 프로젝트의 스킬
└── agents/ 이 프로젝트의 서브에이전트
~/.claude/ 내 모든 프로젝트
├── CLAUDE.md, settings.json 개인 지침과 설정
├── skills/, agents/ 개인 스킬과 서브에이전트
└── projects/ 대화 기록과 자동 메모리skills/와 agents/는 9장에서 배웁니다. 스킬은 이름으로 불러 쓰는 작업 설명서이고, 서브에이전트는 곁일을 따로 맡는 도우미입니다. 지금은 이런 폴더가 있다는 것만 알면 됩니다.
다 외울 필요는 없습니다. 대부분은 CLAUDE.md와 settings.json만 고치면 됩니다.[10:1]
확인 퀴즈
`.claude` 폴더가 복잡해 보입니다. 처음에 주로 고치게 되는 것은 무엇일까요?
말로 하는 규칙과 강제되는 규칙
이 장에서 가장 중요한 절입니다. 아래 두 줄은 비슷해 보이지만 힘이 다릅니다.
CLAUDE.md 에 적기: 비밀 폴더는 읽지 않는다.
settings.json 에 적기: "deny": ["Read(./비밀/**)"]CLAUDE.md의 말은 Claude가 무엇을 시도할지에 영향을 줍니다. 하지만 Claude Code가 무엇을 허용할지는 바꾸지 못합니다. 권한 규칙은 모델이 아니라 Claude Code 프로그램이 강제합니다.[8:1] 회사로 치면 CLAUDE.md는 업무 안내문이고 권한 규칙은 출입문의 잠금장치입니다.
그래서 정말 중요한 일은 거부 규칙에 두세요.[2:3] 이렇게 나눠 보세요.
- 틀려도 다시 고치면 되는 일(말투, 형식)은
CLAUDE.md. - 틀리면 곤란한 일(비밀 파일 읽기)은 거부 규칙.
- 매번 꼭 일어나야 하는 일은 11장의 훅(정해진 순간마다 Claude Code가 자동으로 돌리는 명령).[11]
확인 퀴즈
`CLAUDE.md`에 "비밀 폴더는 읽지 않는다"라고 적은 것과 거부 규칙을 만든 것은 어떻게 다를까요?
직접 해 보기
- 터미널에서 위의
CLAUDE.md와notes폴더를 만들고claude -p로 규칙을 물어봅니다. claude를 켜고 "@inbox/회의-2026-10-27-주간회의.txt 이 메모를 회의록으로 정리해 줘."라고 부탁합니다. 표를 쓰라고 말하지 않았는데 표가 나오나요? 파일이notes에 저장됐나요?/memory와/status를 열어 보고 Esc로 닫습니다./exit로 나와 터미널에서ls -a(PowerShell은ls -Force)로.claude폴더를 찾습니다.
스스로 물어보세요. 새 세션이 규칙을 지켰나? 내 규칙 중 말로 두면 곤란한 것이 있나?
정리
CLAUDE.md에는 Claude가 읽어서 알 수 없는 것만, 확인할 수 있게 쓴다./init은 코드 폴더 기준이다. 메모 폴더는 직접 쓰는 편이 쉽다.- 자동 메모리는 Claude가 쓰고,
/memory에서 보고 끈다. settings.json은 세 위치가 있고 범위가 좁은 쪽이 이긴다. 거부는 어느 위치에서든 이긴다.- 말로 한 규칙은 시도를 바꾸고, 권한 규칙은 허용을 바꾼다.
용어 정리
| 용어 | 읽는 법 | 한 줄 뜻 |
|---|---|---|
| CLAUDE.md | 클로드 엠디 | 내가 쓰는 지속 지침 파일 |
| Auto memory | 오토 메모리 | Claude가 스스로 적는 메모 |
| settings.json | 세팅스 제이슨 | 동작을 바꾸는 설정 파일 |
이 장을 다 읽었나요?
기록은 이 브라우저에만 저장됩니다. 진행 현황은 전체 목차에서 볼 수 있어요.
다음 장: 9장. 스킬과 확장
참고 자료 (11개)
Claude Code 공식 문서, 「How Claude remembers your project」. "CLAUDE.md files: instructions you write to give Claude persistent context." / "Claude Code loads
CLAUDE.mdandCLAUDE.local.mdfrom your current working directory and every directory above it." / "target under 200 lines per CLAUDE.md file." / "Personal preferences for all projects" code.claude.com (확인일 2026-11-06) ↩︎Claude Code 공식 문서, 「Best practices for Claude Code」. "Only write down what Claude can't find by reading the repo, or what it would otherwise spend time rediscovering every session." / "Claude reads the repo itself. Only write down what isn't in there." / "Current ones follow a plainly worded line, and piling on emphasis mostly makes Claude over-apply the rule." / "anything that matters belongs in a deny rule." code.claude.com (확인일 2026-11-06) ↩︎
Claude Code 공식 문서, 「Extend Claude with skills」. "Create a skill when you keep pasting the same instructions, checklist, or multi-step procedure into chat, or when a section of CLAUDE.md has grown into a procedure rather than a fact." code.claude.com (확인일 2026-11-06) ↩︎
Claude Code 공식 문서, 「How Claude remembers your project」. "Run
/initto generate a starting CLAUDE.md automatically." / "Claude analyzes your codebase and creates a file with build commands, test instructions, and project conventions it discovers." code.claude.com (확인일 2026-11-06) ↩︎Claude Code 공식 문서, 「How Claude remembers your project」. "The
/memorycommand lists your CLAUDE.md, CLAUDE.local.md, and other memory file locations across user and project scopes." / "Auto memory: notes Claude writes itself based on your corrections and preferences" / "Auto memory is on by default in local sessions." / "Each project gets its own memory directory at~/.claude/projects/<project>/memory/." / "Auto memory files are plain markdown you can edit or delete at any time." / "To toggle it, open/memoryin a session and use the auto memory toggle" / "Claude saves it to auto memory." code.claude.com (확인일 2026-11-06) ↩︎Claude Code 공식 문서, 「Settings files and precedence」. "Settings are the JSON keys that change how Claude Code behaves" / "You, in every project on this machine" / "Everyone working in the folder that contains it. In a git repository, commit it so teammates get it" / "You, in this one project only." / "When the same key appears in more than one place, Claude Code uses the value from the highest level that sets it." / "Settings precedence, highest first: managed settings, command line, project local, shared project, user." / "Claude Code watches your settings files and reloads them when they change, so it applies most edits to the running session without a restart" / "Run
/statusinside Claude Code to see which settings sources are active." code.claude.com (확인일 2026-11-06) ↩︎회사 컴퓨터라면 관리자가 정한 설정(managed settings)이 이 셋보다 먼저입니다. 근거는 같은 문서의 "Settings precedence, highest first: managed settings, command line, project local, shared project, user."입니다. code.claude.com (확인일 2026-11-06) ↩︎
Claude Code 공식 문서, 「Configure permissions」. "If a tool is denied at any level, no other level can allow it." / "Instructions in your prompt or
CLAUDE.mdshape what Claude tries to do, but they don't change what Claude Code allows." / "Permission rules are enforced by Claude Code, not by the model." code.claude.com (확인일 2026-11-06) ↩︎Claude Code 공식 문서, 「Automate actions with hooks」. "Verify your JSON is valid: trailing commas and comments aren't allowed" code.claude.com (확인일 2026-11-06) ↩︎
Claude Code 공식 문서, 「Explore the .claude directory」. "Claude Code reads instructions, settings, skills, subagents, and memory from your project directory and from
~/.claudein your home directory." / "Most users only editCLAUDE.mdandsettings.json." code.claude.com (확인일 2026-11-06) ↩︎Claude Code 공식 문서, 「Output styles」. "For something that has to happen every time, such as formatting after each edit or blocking a command, use a hook." code.claude.com (확인일 2026-11-06) ↩︎