Claude Code를 쓰다 보면 어느 순간 Claude가 이상하게 움직인다. 아까 하지 말라고 했던 파일을 건드리거나, 작업 범위를 스스로 넓히거나, 검증 없이 작업 완료를 선언한다. 모델이 나빠진 게 아니다. 컨텍스트가 무너진 것이다
이 글은 Claude Code의 Context Harness를 설계하는 세 가지 핵심 패턴을 다룬다. CLAUDE.md 구조화, 세션 오염 제어, Worktree 격리다
CLAUDE.md – 메모장이 아니라 프로젝트 법
CLAUDE.md를 Claude가 기억하는 메모장 정도로 쓰면 효과가 절반 이하다. 이 파일은 Claude Code가 세션 시작 시 전체를 로드하는 Context Harness 파일이다. 공식 문서는 CLAUDE.md를 “팀원들과 Source control을 통해 공유할 수 있는 프로젝트 메모리”로 정의한다
실무 설계 기준은 하나다. 팀이 반복해서 설명해야 하는 것을 전부 이 파일에 넣는다. 아키텍처 경계, 코딩 컨벤션, 테스트 명령, 건드리면 안 되는 파일 목록이 여기에 들어간다
3-레이어 메모리 계층
CLAUDE.md는 세 개의 레이어로 운영된다
Enterprise CLAUDE.md → 조직 보안 정책, 회사 표준 ~/.claude/CLAUDE.md → 개인 선호, 자주 쓰는 명령 <project>/CLAUDE.md → 팀 공통 아키텍처 규칙, 코딩 컨벤션 <project>/CLAUDE.local.md → 개인 실험, 공유하면 안 되는 로컬 메모
우선순위는 아래로 갈수록 높다. 더 구체적인 파일이 덜 구체적인 파일을 덮어쓴다
짧을수록 잘 따른다
공식 문서는 “CLAUDE.md는 짧을수록 더 잘 따르는 경향이 있다”고 명시한다. 실제 연구에서도 200줄을 넘기면 준수율이 저하된다. 핵심 규칙만 남기고, 멀티스텝 절차나 특정 경로에서만 유효한 규칙은 별도 파일로 분리한다
실전 CLAUDE.md 구조 예시
## Architecture Rules - Domain logic은 /src/domain 에만 작성한다 - Controller에서 직접 DB 접근 금지 ## Test Commands - 단위 테스트: `npm test` - 빌드 검증: `npm run build` ## Forbidden Files - .env 파일은 읽지 않는다 - .github/workflows/* 는 수정하지 않는다
Guidance와 Enforcement의 구분
CLAUDE.md의 금지 규칙은 가이던스다. Claude가 이해하고 따르지만, 간혹 무시할 수 있다. 절대로 차단해야 하는 파일은 settings.json의 permissions.deny로 설정해야 한다
{
"permissions": {
"deny": [
"Read(.env*)",
"Write(.github/workflows/*)"
]
}
}
CLAUDE.md는 판단 기준을 제공하고, settings.json은 실제 차단을 실행한다. 두 도구의 역할을 분리해서 써야 한다
세션 오염 – /clear와 /compact
대화가 길어질수록 컨텍스트에 잡음이 쌓인다. 공식 문서는 이를 “context rot”으로 부른다. 모델이 이전에 시도했다 실패한 접근법을 다시 꺼내거나, 수정된 파일의 이전 상태를 참조하거나, 초기 제약 조건을 잊어버리는 현상이다
세션 오염은 보통 100~200k 토큰 수준에서 눈에 띄기 시작한다. 공식 문서는 컨텍스트가 95% 차면 자동 compact를 트리거하지만, 이 시점에서는 이미 모델 품질이 저하된 상태다. 선제적으로 관리해야 한다
/clear – 작업 단위를 끊는다
/clear는 대화 히스토리를 초기화한다. 이전 작업 맥락이 다음 작업에 섞이는 것을 막는 가장 확실한 방법이다
작업 A 완료 → /clear → 작업 B 시작
공식 블로그는 “새 작업을 시작할 때 새 세션도 함께 시작하는 것이 기본 원칙”이라고 명시한다. 단, /clear 이후에도 CLAUDE.md는 자동으로 재로드된다. CLAUDE.md에 규칙을 고정해 둔 이유가 여기에 있다
/compact – 긴 작업의 압축
/compact는 대화를 요약으로 교체한다. 작업이 아직 끝나지 않았고 맥락 일부를 유지해야 할 때 쓴다. 그냥 /compact만 치면 안 된다. 무엇을 남길지 지시해야 한다
/compact 변경한 파일 목록, 실행한 커맨드, 남은 태스크를 요약에 포함해줘
압축 대상을 명시하지 않으면 중요한 맥락이 빠진다. 공식 문서는 “주요 결정, 최근 코드 변경, 작업 방향이 요약에 살아남아야 한다”고 설명한다
대화 규칙을 파일로 승격한다
대화 중에 확정된 금지 사항이나 설계 결정은 CLAUDE.md나 .clauderules로 옮겨야 한다. 대화 속 규칙은 /compact 과정에서 사라질 수 있다. 파일에 기록된 규칙은 다음 세션에서도 자동으로 로드된다
대화 속 규칙 → 휘발성 CLAUDE.md의 규칙 → 세션 지속성
컨텍스트 재설계 – 엉뚱한 수정이 나올 때
Claude가 버그 하나 고쳐달라고 했는데 관련 없는 파일까지 건드리는 상황은 모델 문제가 아니다. 지시 범위가 넓고, 금지 범위가 없고, 완료 기준이 없을 때 일어난다. 이미 잘못된 방향으로 간 세션에 설명을 계속 덧붙이는 것은 역효과다. 오염된 컨텍스트 위에 쌓는 지시도 같이 희석된다. 먼저 방향을 끊고, 좁은 범위의 새 지시로 시작한다
효과적인 컨텍스트 재설계는 네 가지를 명시한다
목표: 로그인 버튼 클릭 시 /login으로 이동해야 한다 재현: 클릭해도 아무 동작 없음 수정 가능 범위: src/components/layout/sidebar.tsx 수정 금지 범위: .env, .github/workflows/* 유지 조건: 버튼 위치와 디자인은 변경하지 않는다 검증: npm run build → npm test 완료 기준: 변경 파일 목록, 수정 내용, 검증 결과를 보고한다
범위가 큰 작업은 처음부터 수정시키지 않는다. 먼저 계획만 요청한다
지금 수정하지 말고, 어떤 파일을 왜 먼저 읽을 것인지 계획만 제시해줘
이 단계가 실패 비용을 줄인다. 범위가 두 개 이상의 디렉토리로 넓어질 때, 인프라·workflow 파일이 근처에 있을 때, 이미 한 번 엉뚱한 방향으로 간 세션일 때 반드시 적용한다
Worktree 병렬 격리
같은 디렉터리에서 Claude 세션을 여러 개 열면 대화는 분리되지만 파일 시스템은 공유된다. 세션 A가 수정한 파일을 세션 B가 모르고 다시 수정한다. diff가 섞이고 테스트 소유권도 불명확해진다. Worktree는 파일 시스템과 브랜치를 함께 격리한다. Claude Code v2.1.50부터 --worktree 플래그를 지원한다
# 터미널 1 claude --worktree feature-auth # 터미널 2 claude --worktree bugfix-payments
각 Worktree는 .claude/worktrees/ 아래에 독립 디렉토리를 가지고, 독립 브랜치에서 시작한다
격리 계층의 구분
대화 격리 → 별도 Claude 세션 (각자의 대화 히스토리) 파일 시스템 격리 → Worktree (독립 디렉토리, 독립 브랜치) 메모리 격리 → CLAUDE.local.md (Worktree별 분리 가능)
주의할 점이 있다. Auto memory는 Worktree별로 격리되지 않는다. 공식 문서는 “같은 Git 저장소의 모든 Worktree와 서브 디렉토리가 하나의 Auto memory 디렉토리를 공유한다”고 명시한다. Worktree를 만들었다고 해서 Claude의 학습된 선호까지 분리되는 것은 아니다
충돌 해결 순서
Worktree를 머지할 때 충돌이 생기면 바로 수정시키지 않는다. 기계적으로 한쪽을 덮어쓸 위험이 있다
1. 충돌 원인 분석: 양쪽 변경이 같은 영역을 어떻게 다르게 수정했는지 설명해줘 2. 병합 계획 제시: 두 변경을 어떻게 합칠지 계획을 먼저 보여줘 3. 계획 승인 후 수정 4. 관련 테스트 실행
.env, .env.local (application.yaml) 같은 gitignore된 파일은 Worktree에 자동 복사되지 않는다. 프로젝트 루트에 .worktreeinclude 파일을 만들어 복사 대상을 지정한다
.env .env.local
CLAUDE.md로 규칙을 고정하고, /clear와 /compact로 세션을 제어하고, Worktree로 파일 시스템을 격리하는 것이 Claude Code Context Harness 설계의 전부다
출처 – 인프런 [Claude Code Harness Engineering 클로드코드 심화 CLI 하네스 엔지니어링 실무]