Claude Code는 빈손으로 시작하지 않습니다: 세션 앞의 7겹 컨텍스트

Claude Code를 켜고 첫 문장을 입력하면 대화가 그 순간 시작되는 것처럼 보입니다. 실제 작업은 이미 그 전에 반쯤 정해져 있습니다. 어떤 폴더에서 실행했는지에 따라 결과가 달라집니다. 루트와 하위 폴더의 CLAUDE.md도 영향을 줍니다. 개인 설정과 프로젝트 설정도 결과를 바꿉니다. 훅도 같은 프롬프트를 다르게 만듭니다.

이 차이를 모르면 AI 코딩은 운에 가까워집니다. 어제는 테스트를 잘 돌리던 세션이 오늘은 엉뚱한 패키지 매니저를 쓰고, 한 프로젝트에서는 커밋까지 해주던 에이전트가 다른 프로젝트에서는 같은 파일을 계속 다시 읽습니다. 모델이 갑자기 나빠진 것이 아니라 시작할 때 읽은 세계가 달랐을 가능성이 큽니다.

Anthropic 문서는 CLAUDE.md와 auto memory가 매 세션에 로드된다고 설명합니다. 설정 문서는 user와 project scope를 다룹니다. local과 managed scope도 계층적으로 병합됩니다. 훅 문서는 도구 호출 전후에 명령을 허용하거나 막고, 추가 컨텍스트를 주입할 수 있다고 말합니다. 이 글은 그 조각들을 운영자 관점에서 7겹으로 다시 정리한 것입니다.

핵심 정리

1. 01Claude Code 세션의 품질은 첫 프롬프트보다 먼저 로드되는 파일과 설정에 크게 좌우됩니다.
2. 02컨텍스트 엔지니어링은 긴 설명을 매번 치는 기술이 아니라, 세션 시작 전에 읽힐 자료의 위치와 우선순위를 설계하는 일입니다.
3. 03공유 규칙과 개인 규칙, 프로젝트 설정과 로컬 설정, 훅과 메모리는 서로 다른 역할을 맡아야 충돌이 줄어듭니다.
4. 047겹 구조를 알면 세션이 왜 말을 안 듣는지, 어떤 파일을 고쳐야 다음 세션부터 나아지는지 추적할 수 있습니다.

용어 정리

CLAUDE.md

프로젝트나 디렉터리 단위로 Claude Code가 읽는 지시 파일입니다. 코딩 규칙, 아키텍처, 검증 절차를 담습니다.

memory

Auto memory

Claude가 작업하며 저장한 학습 내용입니다. 공식 문서 기준으로 프로젝트별 메모리 폴더의 MEMORY.md 일부가 세션 시작 때 읽힙니다.

memory

Settings scope

사용자, 프로젝트, 로컬, 관리 정책처럼 설정이 적용되는 범위입니다. 권한, 플러그인, 기본 모드 같은 동작을 바꿉니다.

config

Hook

프롬프트 제출, 도구 호출, 권한 요청 같은 생명주기 지점에 실행되는 명령입니다. 모델 판단과 별개로 강제 규칙을 걸 수 있습니다.

guardrail

첫 번째 겹: 현재 작업 디렉터리

Claude Code는 어디에서 켜졌는지부터 봅니다. 같은 레포라도 루트에서 시작했는지, web/ 아래에서 시작했는지에 따라 로드되는 지시와 작업 맥락이 달라질 수 있습니다. 공식 메모리 문서는 현재 작업 디렉터리에서 위로 올라가며 CLAUDE.md와 CLAUDE.local.md를 찾는다고 설명합니다.

이 말은 세션 시작 위치가 컨텍스트의 첫 번째 선택이라는 뜻입니다. 루트에서 켜면 브랜드와 배포 규칙이 한꺼번에 들어올 수 있습니다. 워커와 웹 전체 규칙도 같이 들어옵니다. 특정 앱 폴더에서 켜면 그 하위 도메인에 가까운 지시가 뒤쪽에 붙습니다. 뒤쪽에 읽힌 지시는 같은 레벨의 이전 지시보다 더 최근 문맥처럼 작동할 가능성이 큽니다.

작은 팀에서 자주 생기는 문제는 여기서 시작합니다. "이 레포에서 하던 방식"이라고 생각했는데 세션은 다른 폴더에서 출발해 다른 규칙을 읽고 있습니다. 먼저 확인해야 할 것은 모델 이름이 아니라 cwd입니다. 세션이 바라보는 세계의 입구가 맞아야 그다음 지시도 의미가 있습니다.

두 번째 겹: 공유 프로젝트 지시

프로젝트 루트의 CLAUDE.md는 팀이 합의한 장기 규칙을 담기 좋습니다. 빌드 명령과 금지할 파일이 여기에 들어갑니다. 아키텍처 경계와 테스트 기준처럼 매번 반복 설명하면 안 되는 내용도 이 겹에 맞습니다. Anthropic 문서는 CLAUDE.md를 세션 시작 때 읽는 프로젝트 메모리로 설명합니다.

중요한 것은 이 파일을 잡다한 일기장으로 쓰지 않는 것입니다. 너무 많은 내용이 들어가면 모델은 읽지만 잘 따르지 못합니다. 공식 문서도 파일이 길수록 준수율이 떨어질 수 있고, 경로별 규칙이나 분리된 파일을 쓰는 편이 낫다고 경고합니다. 컨텍스트는 많이 넣는다고 강해지는 것이 아니라, 자주 쓰는 결정을 잘 앞에 세울 때 강해집니다.

나는 CLAUDE.md를 "팀의 헌법"에 가깝게 보는 편이 좋다고 생각합니다. 바뀌면 모든 세션의 행동이 바뀌어야 하는 규칙만 넣습니다. 특정 기능의 임시 메모나 내 개인 선호는 다른 겹으로 내려야 합니다. 그래야 새 세션이 시작될 때 늘 같은 뼈대를 읽습니다.

세 번째 겹: 개인 프로젝트 지시

CLAUDE.local.md는 같은 프로젝트 안에서도 사람마다 다른 정보를 넣는 자리입니다. 로컬 샌드박스 URL, 개인 테스트 데이터, 아직 팀에 공유하지 않은 작업 메모처럼 커밋하면 안 되는 내용이 여기에 맞습니다. 공식 문서는 이 파일을 프로젝트 루트에 두고 gitignore에 넣으라고 설명합니다.

이 겹은 편하지만 위험합니다. 개인 지시가 공유 지시를 조용히 덮어쓰는 것처럼 느껴질 수 있기 때문입니다. 문서상으로는 파일들이 덮어쓰기보다 이어 붙는 방식에 가깝습니다. 실제 모델 입장에서는 뒤에 나온 강한 문장이 더 눈에 띕니다. 이 때문에 개인 파일에는 "내가 편하려고 넣은 참고"와 "모든 작업에서 지켜야 하는 규칙"을 섞지 않는 편이 좋습니다.

좋은 사용법은 로컬 실행 정보에 집중하는 것입니다. 예를 들어 "이 머신에서는 PowerShell을 쓴다", "로컬 dev 서버는 3001번 포트를 쓴다", "테스트 계정은 이 이름을 사용한다" 정도면 충분합니다. 반대로 보안, 배포, 데이터 모델 같은 팀 규칙은 공유 파일로 올려야 다음 사람의 세션도 같은 기준으로 움직입니다.

네 번째 겹: 하위 디렉터리 규칙과 rules

큰 레포에서는 루트 규칙만으로 부족합니다. 프론트엔드와 워커는 금지사항이 다릅니다. 문서와 디자인 자산도 다른 기준을 가집니다. Claude Code는 하위 디렉터리의 CLAUDE.md와 rules를 파일을 읽는 시점에 추가로 발견할 수 있습니다. 공식 문서는 하위 디렉터리 지시가 필요할 때 로드된다고 설명합니다.

이 구조는 monorepo에서 특히 중요합니다. 루트에는 공통 규칙을, web/에는 Next.js와 스타일 규칙을, worker/에는 Cloudflare와 D1 규칙을 둘 수 있습니다. 모델은 모든 규칙을 처음부터 다 읽지 않아도 됩니다. 해당 폴더를 건드릴 때 더 가까운 지시를 받습니다.

다만 하위 규칙은 디버깅을 어렵게 만들기도 합니다. 세션 초반에는 보이지 않던 지시가 특정 파일을 읽은 뒤 들어오기 때문입니다. 어떤 순간부터 모델 행동이 바뀌었다면, 방금 읽은 하위 폴더에 지시 파일이 있는지 확인해야 합니다. 컨텍스트 엔지니어링은 지시를 넣는 일만이 아니라, 언제 들어오는지도 관리하는 일입니다.

다섯 번째 겹: 설정 파일과 권한

지시 파일이 "무엇을 해야 하는가"를 말한다면 settings는 "무엇을 할 수 있는가"를 정합니다. 공식 설정 문서는 사용자 설정 ~/.claude/settings.json, 프로젝트 설정 .claude/settings.json, 로컬 설정 .claude/settings.local.json을 구분합니다. 관리 정책까지 있으면 조직 수준의 제한도 걸립니다.

이 겹은 글보다 조용하지만 영향이 큽니다. 어떤 도구가 허용되는지, 기본 permission mode가 무엇인지, 플러그인이 켜져 있는지, auto memory가 켜져 있는지가 여기서 정해질 수 있습니다. 같은 CLAUDE.md를 읽어도 권한 설정이 다르면 한 세션은 테스트를 실행하고, 다른 세션은 매번 승인을 기다립니다.

이 때문에 "왜 이 세션은 못 하지?"라는 질문에는 설정을 같이 봐야 합니다. 지시 파일에는 테스트를 돌리라고 되어 있는데 settings가 명령 실행을 제한하면 루프가 끊깁니다. 반대로 너무 넓은 권한을 주면 위험한 명령이 쉽게 지나갑니다. 컨텍스트의 품질은 정보량과 권한 경계가 함께 맞을 때 올라갑니다.

여섯 번째 겹: 훅과 강제 검증

Claude Code 훅은 모델에게 "잘 지켜줘"라고 부탁하는 지시와 다릅니다. 훅은 특정 이벤트에서 실제 명령을 실행합니다. 공식 훅 문서는 PreToolUse가 도구 호출 직전에 실행된다고 설명합니다. 이 훅은 허용과 거부를 결정할 수 있습니다. 필요하면 질문이나 연기도 선택합니다. 필요하면 도구 입력을 바꾸거나 추가 컨텍스트도 붙일 수 있습니다.

이 겹은 규칙을 운영으로 바꾸는 자리입니다. "삭제 명령 조심"이라고 CLAUDE.md에 적는 것보다, rm -rf를 감지해 막는 훅이 더 강합니다. "커밋 전 테스트"라고 말하는 것보다, 커밋 명령 전에 테스트가 없으면 차단하는 훅이 더 확실합니다. 모델의 의지와 별개로 경계가 실행됩니다.

다만 훅을 많이 넣으면 세션이 무거워집니다. 매 도구 호출마다 외부 검증이 붙으면 속도가 떨어지고, 잘못 만든 훅은 정상 작업까지 막습니다. 이 때문에 훅은 모든 규칙을 넣는 곳이 아니라 실패 비용이 큰 규칙을 넣는 곳이어야 합니다. 삭제와 배포가 우선입니다. secret 노출과 데이터베이스 쓰기도 한 번 틀리면 비쌉니다.

일곱 번째 겹: 자동 메모리와 이전 세션의 흔적

마지막 겹은 auto memory입니다. 공식 문서는 프로젝트별 메모리 디렉터리의 MEMORY.md 첫 200줄 또는 25KB가 세션 시작 때 로드된다고 설명합니다. 여기에 빌드 명령, 디버깅 패턴, 반복 선호가 쌓입니다. 사용자가 매번 적지 않아도 Claude가 일부를 기억하는 구조입니다.

이 겹은 편리하지만 역시 관리가 필요합니다. 오래된 테스트 명령, 폐기된 배포 절차, 더 이상 맞지 않는 API 경로가 메모리에 남으면 다음 세션이 과거를 현재로 착각합니다. 자동 메모리는 마법의 기억이 아니라 관리해야 하는 파일입니다. /memory로 무엇이 들어갔는지 보는 습관이 필요합니다.

여기까지 오면 세션 시작은 더 이상 한 줄 프롬프트가 아닙니다. 현재 폴더와 공유 지시가 먼저 세션의 성격을 정합니다. 개인 지시와 하위 규칙도 뒤이어 붙습니다. 설정, 훅, 자동 메모리는 실행 가능한 경계를 만듭니다. 프롬프트는 그 위에 올라가는 마지막 요청입니다. 컨텍스트 엔지니어링은 말을 잘 쓰는 기술이 아니라, 세션이 읽고 시작할 운영체제를 만드는 일입니다.