여러 저장소에서 컨텍스트 손실 없이 Claude Code 실행

출처: Dev.to

원본은 claudeguide.io/claude-code-workflow-multi-repo 에서 처음 공개되었습니다.
여러 코드베이스(API, 대시보드, 공유 라이브러리 등)를 동시에 작업할 때 Claude Code와 관련된 진짜 문제는 도구가 아니라 어떤 대화가 어느 프로젝트에 해당하는지 기억하지 못한다는 점입니다. 이 글은 6주간 매일 사용한 뒤, 32GB RAM을 장착한 Mac mini M4에서 실제로 동작하는 워크플로우를 문서화합니다. Claude Code가 할 수 있는 전체 기능을 보고 싶다면 Claude Code 완전 가이드를 참고하세요.

• 하나의 Claude Code 세션 = 하나의 레포지토리. 절대 섞지 마세요.
• 각 레포지토리 루트에 프로젝트 전용 CLAUDE.md 파일을 두어 컨텍스트를 고정합니다.
• 레포지토리를 초월한 영구적인 사실은 ~/.claude/CLAUDE.md(사용자 전역) 에 저장합니다.
• 레포지토리 간 리팩터링이 필요할 때는, 각 레포지토리마다 Explore 서브에이전트를 띄우는 세 번째 “오케스트레이터” 세션을 사용합니다.
• 컨텍스트가 무거운 작업을 시작하기 전마다 /remember 혹은 /checkpoint 로 체크포인트를 찍어 둡니다.

흔히 하는 실수

첫 번째 직관은 하나의 Claude Code 창을 열고 cd 로 프로젝트를 오가며 작업하는 것입니다. 하지만 이는 세 가지 구체적인 이유 때문에 실패합니다.

1. 파일 캐시 충돌 – Claude Code는 열어본 파일을 추적합니다. 세션 도중 디렉터리를 바꾸면 오래된 경로 가정이 남아 오류가 발생합니다.
2. 시스템 프롬프트 희석 – 각 레포지토리의 CLAUDE.md는 시작 시에만 로드됩니다. 이후에 전환하면 해당 가이드가 다시 적용되지 않습니다.
3. 대화 오염 – 하나의 대화에 Repo A와 Repo B가 섞이면, A에서 내린 결정이 B 구현에 누출됩니다.

아래 표는 3레포 프로젝트에서 2주간 A/B 테스트한 결과를 보여줍니다.

레포당 하나의 세션을 사용하는 방식은 토큰 사용량을 57% 절감하고, 재작업을 4배 줄였습니다.

CLAUDE.md (레포 전용)

# CLAUDE.md — api-service
- Node 20, TypeScript 5.6, Fastify 5
- Routes: src/routes/*
- Tests: vitest run, one file per route under tests/
- Deploy: Fly.io via `fly deploy` (staging auto on main push)
- Secrets: .env.local (dev) / Fly secrets (prod)

200줄 이하 로 유지하세요. 내용은 다음을 답해야 합니다: 레포가 무엇인지, 사용 스택, 코드 위치, 테스트 존재 여부, 배포 경로. 미래지향적인 내용은 금지하고, 현재 사실만 적습니다.

~/.claude/CLAUDE.md (전역)

This is your shared preamble. Useful entries:
Your preferred commit message style
Tools you have globally (tsx, pnpm, bun)
Platform oddities (Mac mini M4, Apple Silicon specifics)
Recurring project names and what they mean

100줄 이하 로 유지합니다. 너무 길면 작업 메모리에서 무시되거나 밀려납니다.

실전 팁

• 터미널 탭, iTerm 분할 창, 혹은 Warp 워크플로 – 레포당 하나의 Claude Code 프로세스를 실행합니다. 동시에 1‑3개 정도만 띄우는 것이 좋습니다. Mac mini M4 32GB 환경에서는 세 개 세션이 6‑8 GB 정도의 메모리를 차지합니다.
• 레포를 초월하는 변경(예: “API 엔드포인트 이름을 바꾸고 세 프론트엔드 모두에서 호출을 업데이트”)이 필요하면, 중립 디렉터리에서 네 번째 세션을 열고 Agent 도구를 이용해 각 레포에 Explore 서브에이전트를 배포합니다. 결과를 모아 레포별 세션에 전달해 구현합니다.
• 각 세션은 독립된 대화를 가집니다. 프로젝트 디렉터리 안의 .remember/ 폴더는 해당 레포 내 세션 간에 컨텍스트를 지속하지만, 서로 다른 세션 간에는 실시간 컨텍스트를 공유하지 않습니다.
• Claude Desktop 은 아이디어 회의와 글쓰기용, Claude Code 는 파일 시스템을 다루는 작업에 최적화되었습니다. 서로 간섭하지 않으니 상황에 맞게 선택하세요.
• Worktree 를 활용하면 “오케스트레이터” 패턴을 안전하게 구현할 수 있습니다. 메인 체크아웃은 활성 개발에, 별도 worktree는 에이전트가 충돌 없이 탐색하도록 사용합니다. 자세한 설정 방법은 Worktree Isolation in Claude Code 를 참고하세요.
• 메모리 한계: Mac mini M4 32GB 기준으로 세 개의 풀 세션이 6‑8 GB 정도를 사용합니다. 네 개·다섯 개를 동시에 띄우면 다른 도구와 메모리를 경쟁하게 됩니다. 실무에서는 동시 세션을 세 개 로 제한하고, 네 번째는 짧은 오케스트레이션 작업에만 잠시 열어두세요.

우리 팀 경험

• 초기 2주 동안 단일 세션 + 심볼릭 링크 방식을 사용했을 때, 토큰 사용량이 2.3배 증가했고, Claude가 캐시한 파일 경로가 cd 로 바뀐 후에도 남아 파일 경로 오류가 빈번했습니다. 별도 세션으로 전환한 뒤 단 하루 만에 두 문제를 모두 해결했습니다.
• 모든 측정값은 macOS 15.4 를 실행 중인 Mac mini M4 32GB(2026‑04‑04~04‑18)에서 기록한 로그 기반이며, 대상 레포는 Fastify 기반 API, Next.js 15 대시보드, TypeScript 공유 라이브러리였습니다. 원본 로그 샘플은 요청 시 제공합니다.

---

이 글은 claudeguide.io 에서 진행하는 Claude Code 워크플로우 시리즈의 일부입니다. 공시: 이 사이트는 Biz AI 자체 투자 프로젝트의 일환이며, 우리가 만든 SaaS(claudecosts.app) 가 제품 인덱스에 링크돼 있지만 본 글에서는 홍보하지 않습니다.

Claude Code 파워 프롬프트 300

• 300개의 검증된 프롬프트(사용 사례별 정리)
• 복사·붙여넣기만 하면 바로 사용 가능
• 40개의 슬래시 커맨드 템플릿(토큰 최적화 버전)
• 직접 가져올 수 있는 JSONL 파일 제공
• 실제 프로덕션 세션에서 테스트 완료

→ Claude Code 파워 프롬프트 300 구매하기 — $29
30일 환불 보장, 즉시 다운로드.