[AI] Claude Code : 컨텍스트 관리 & 워크플로우 전략

📌 개요

 

 

Claude Code는 200k 컨텍스트 윈도우를 제공합니다.

넉넉해 보이지만 코드 파일, MCP 도구, 대화 히스토리까지 포함하면 금방 차버립니다.

결국 컨텍스트를 얼마나 효율적으로 관리하느냐가 Claude Code 활용의 핵심입니다.

 

이번 포스트에서는 컨텍스트를 최적화하는 관리 기법과 실전 워크플로우 전략을 정리라겠습니다.

 

 

 

 

---

📌 세컨드 브레인 구축 : MEMORY.md

 

 

Claude Code는 세션을 저장하지 않으며, 매번 새 세션을 열면 이전 대화는 사라집니다.

 

이전 포스트에서 다뤘던 CLAUDE.md는 프로젝트 규칙과 지침을 업데이트하면 될 것이라고 생각하지만,

매 세션마다 원하는 지침을 수동으로 업데이트하는 것은 관리 측면에서 비효율적입니다.

 

그래서 최근 엔트로픽에서 /memory 명령어를 활용한 자동 메모리 시스템을 배포했습니다.

이제 Claude가 작업 중 스스로 학습한 내용을 MEMORY.md 파일로 기록합니다.

 

MEMORY.md 파일은 매 세션 시작 시 자동으로 로드됩니다.

 

 

 

CLAUDE.md vs MEMORY.md 역할 분리

구분	CLAUDE.md	MEMORY.md
작성 주체	개발자 (수동)	Claude (자동)
용도	프로젝트 규칙, 코딩 컨벤션	학습된 패턴, 디버깅 인사이트
공유 범위	Git 커밋으로 팀 공유	로컬 머신 전용
관리 방식	직접 편집	Claude가 자동 갱신

정리하면, 팀원과 공유해야 하는 규칙은 CLAUDE.md에, 개인 작업 히스토리는 MEMORY.md에 맡기는 구조가 이상적입니다.

 

 

 

 

/memory 명령어를 입력하면 MEMORY.md 파일을 확인할 수 있으며, 위치는 프로젝트 루트가 아닌, 유저 홈 디렉토리 루트에 존재합니다.

 

참고로 여러분이 직접 MEMORY.md 파일을 설계하실 필요는 없습니다. Claude Code가 자동으로 관리하기 때문에 오히려 문제가 될 수 있습니다. 대신, 여러분은 /memory 명령어를 통해 MEMORY.md 파일에서 잘못된 부분을 정리하거나 지침을 추가하는 정도로 관리하시면 됩니다. 여러분이 직접 설계하고 집중해야 할 부분은 CLAUDE.md 파일입니다.

 

※ 참고로 MEMORY.md 파일은 200줄, 또는 25KB까지만 세션에 로드됩니다. 

 

 

 

 

 

---

📌  계층적 컨텍스트 관리

 

 

 

하나의 CLAUDE.md에 모든 내용을 기재하면 파일이 비대해지고, 컨텍스트 윈도우를 불필요하게 소비하게 됩니다. 핵심 원칙은 CLAUDE.md에는 규칙과 참조만 두고, 상세 내용은 별도 md 파일로 분리하는 것입니다.

 

# CLAUDE.md (간결하게 유지)

## 프로젝트 규칙
- Unity 2022.3 LTS, URP 사용
- MonoBehaviour 필드는 [SerializeField] private 사용

## 참조 문서
- 아키텍처: @docs/architecture.md
- 코딩 컨벤션: @docs/conventions.md
- API 설계: @docs/api-guide.md

 

 

 

이렇게 모듈식으로 분리하면 Claude가 필요한 지침만 그때마다 참조하게 됩니다.

컨텍스트 비대화를 방지하면서도 정확한 지침을 전달할 수 있습니다.

 

 

 

 

 

---

📌  토큰 최적화 전략

 

1. 세션 분리

시스템 하나를 한 세션에 모두 처리하려 하지 않도록 합니다.

기능 별로 쪼개서 여러 세션으로 나누는 것이 토큰 최적화에 유리합니다.

 

예를 들어, 다음과 같이 독립적인 기능으로 세션을 나눕니다.

• 로그인 기능 → 세션 1
• 대시보드 UI → 세션 2
• API 연동 → 세션 3

 

2. MCP 토큰 모니터링

 

MCP 서버는 토큰을 많이 사용합니다. 연결된 MCP 서버가 많을수록 매 요청마다 컨텍스트에 포함되죠.

불필요한 MCP는 반드시 비활성화하고, 자주 쓰는 기능만 골라서 커스텀 MCP를 제작해 사용하는 것이 좋다.

 

※ 추후에 커스텀 MCP 제작에 대해 살펴보도록 하겠습니다.

 

 

3. Mermaid 아키텍처 정리

 

# docs/architecture.md

```mermaid
graph TD
    A[GameManager] --> B[UIManager]
    A --> C[NetworkManager]
    B --> D[LoginUI]
    B --> E[LobbyUI]
    C --> F[PhotonService]
```

 

 

CLAUDE.md에 Mermaid 다이어그램으로 프로젝트 구조를 정리하면, Claude가 전체 아키텍처를 한눈에 파악할 수 있습니다.

 

 

4. 무거운 데이터는 스크립트로 처리

 

 

 

게임 개발을 하다보면 퍼널 데이터를 추출하여 분석해 개선하곤 합니다.

하지만 만약 10만 행 CSV를 세션에서 모두 처리한다면 컨텍스트가 초과할 것입니다.

 

그래서 CSV, JSON 같은 대량 데이터를 컨텍스트에 직접 넣지 않습니다.

Python 같은 스크립트로 데이터를 분석한 후 결과 요약만 컨텍스트에 반영하도록 지시합니다.

 

 

 

 

 

---

📌  실전 워크플로우

 

1. Plan Mode로 시작 (+ md 파일로 계획 수립)

 

Claude Code에서 가장 중요한 습관입니다. Plan Mode(Shift+Tab)를 통해 정확한 실행 계획을 먼저 수립하고, 승인 후 구현에 들어가는 것이 컨텍스트 최적화와 구현 품질 모두에 유리합니다.

 

일부에서는 Plan Mode가 세션 채팅에서만 유효하다고 판단해, PLAN.md 파일에 직접 계획을 기록하고 수정하는 방식을 추천하기도 한다. 이 방법은 세션이 바뀌어도 계획이 md 파일로 남기 때문에 영구적으로 보관할 수 있다는 장점이 있습니다.

 

 

2. TDD 기반 코딩

 

기능을 구현하고 커밋하기 전에 테스트를 먼저 작성하고 통과 여부를 확인합니다.이 습관은 추후 디버깅을 훨씬 용이하게 만들어줍니다. Claude에게 테스트 코드 작성을 요청하면 기존 테스트 패턴을 분석해 일관된 스타일로 생성해줍니다.

 

 

3. 에러 메시지를 그대로 전달

Claude는 스택 추적 분석 능력이 뛰어납니다. 에러를 요약하거나 재해석하지 말고, 콘솔 에러 메시지를 그대로 복사해서 전달하는 것이 가장 효과적이다.

 

 

4. TODO.md 활용

프로젝트 루트에 TODO.md를 만들어 Claude에게 Task를 추적하게 만듭니다.

개발자도 자신의 작업을 체크할 수 있고, Claude도 작업 흐름을 인지하며 진행할 수 있습니다.

# TODO.md

## 오늘 할 일
- [x] 로그인 API 연동
- [ ] 대시보드 레이아웃 구현
- [ ] 에러 핸들링 추가

## 내일 할 일
- [ ] 유닛 테스트 작성
- [ ] 코드 리뷰 반영

 

 

실전 워크플로우

1. 할 일을 TODO.md에 작성
2. Claude에게 TODO.md를 참조해 첫 번째 항목부터 구현 시작
3. Agent Teams로 여러 작업 병렬 처리 가능
4. 세션 종료 시 TODO.md 업데이트 요청

 

 

 

 

---

📌  마무리

 

이번 포스트에서는 Claude Code의 컨텍스트 관리와 워크플로우 전략에 대해 알아봤습니다.

 

핵심 요약

• MEMORY.md로 자동 메모리 시스템 활용
• CLAUDE.md는 규칙과 참조만, 상세 내용은 별도 파일로 모듈화
• 기능 별 세션 분리 + 불필요한 MCP 비활성화로 토큰 최적화
• Plan Mode 선행 → TDD 기반 코딩 → TODO.md로 Task 추적

컨텍스트 관리는 Claude Code를 사용하기 위한 필수 역량입니다. 체계적으로 관리할수록 Claude의 응답 품질은 올라가고, 토큰 낭비는 줄일 수 있습니다.

 

지금까지 포스트를 읽어주셔서 감사합니다.