Context Editing의 성능 효과는?

Anthropic 공식 발표에 따르면 84% 토큰 절감, Context Editing 단독 29% 성능 향상, Memory Tool 조합 시 39% 성능 향상을 달성했다.

AI/Claude

Claude 메모리 아키텍처 살펴보기 - CLAUDE.md, Memory Tool까지

안녕하세요! 갓대희 입니다. :- )

오늘은 "Claude의 메모리 아키텍처"에 대해 써보려고 한다.

이번 리뷰는 약간 복잡하고 어려운 내용을 다루게 되는 것 같다.

거기에 오랜만에 실습형이 아닌 이론적인 내용이다 ....
다음과 같은 기사(https://www.aitimes.com/news/articleView.html?idxno=204364)를 접하게 되어 관련 내용을 리뷰 하게 되었는데, 혹시 이제 막 AI를 접하시는 분들께선 보시다 욕할 수 있으니 과감히 뒤로가기를 클릭하시면 더 좋을 것 같다.

Claude가 세션 간에 컨텍스트를 잃어버리는 문제를 해결하는 메커니즘을 심층 분석한다.
CLAUDE.md를 통한 정적 메모리, Anthropic이 2025년 11월 26일 발표한 Long-running Agent 패턴, 그리고 2025년 9월 29일 발표된 Context Management API(Context Editing + Memory Tool)까지 통합적으로 다룬다.

Claude Code로 대규모 프로젝트를 진행해본 개발자라면 이런 경험이 있을 것이다. 어제 맥락을 충분히 설명했는데, 오늘 새 세션을 열었더니 Claude가 프로젝트에 대해 아무것도 모르는 것처럼 행동한다. 결국 같은 설명을 반복하거나, 어제 작업한 코드를 다시 설명해야 하는 상황이 발생한다.

이 문제는 단순히 불편함을 넘어 생산성에 직접적인 영향을 미친다. Anthropic도 이 문제를 인지하고 있었고, 여러 방향에서 해결책을 제시했다. 이 글에서는 Anthropic이 공식적으로 발표한 모든 메모리 관련 기능과 패턴을 심층 분석하고, 실제 프로젝트에서 어떻게 조합해서 사용할 수 있는지 정리했다.

왜 Claude는 잊어버리는가?

Claude를 포함한 모든 LLM은 컨텍스트 윈도우(Context Window)라는 근본적인 제약을 가지고 있다.

Context Window란?

한 줄 정의: Claude가 대화할 때 "기억하고 있을 수 있는 최대 텍스트 양"

쉬운 비유: 책상 위 공간이라고 생각하면 된다. 책상이 아무리 넓어도 무한정 책을 펼쳐놓을 수는 없다. Claude의 "책상"이 바로 컨텍스트 윈도우다.

여러분이 보낸 모든 메시지
Claude가 응답한 모든 내용
Claude가 읽은 코드 파일들
시스템 프롬프트와 CLAUDE.md 내용

이 모든 것이 "책상 위"에 함께 올라가야 한다. 책상이 가득 차면? 오래된 내용부터 밀려나거나, 새 세션을 시작하면 책상이 완전히 비워진다. 이것이 "Claude가 잊어버린다"고 느끼는 이유다.

토큰(Token)은 텍스트를 측정하는 단위다. 대략 영어 4글자 = 1토큰, 한글 1~2글자 = 1토큰 정도로 생각하면 된다. Claude Sonnet 4.5의 경우 기본 200K(20만) 토큰, API 베타를 통해 최대 1M(100만) 토큰까지 지원한다. 100만 토큰이면 대략 소설책 7~8권 분량이지만, 복잡한 프로젝트에서는 이것도 한계에 도달한다.

처음 이런 AI 이론을 접하시는 분들을 위해 .. 좀더 이해를 돕기 위해 간단한 예시를 만들어 보자.

예시1) 메모리 없는 채팅 에이전트

- AI 채팅 에이전트에게 메모리라는것을 안주게 되면 다음과 같이 바로 직전 대화 내용도 기억하지 못한다.

- 하기와 같이 메모리는 없고(빨간 테두리 영역이 비워져 있다.), GPT API를 통해 채팅모델처럼 연동해보았다.

- 첫번째 대화 시도 : 갓대희라고 밝히며 인사를 시도.

- 두번째 대화 시도 : 내가 누군지 물어보자. 방금 내가 말한것도 기억하지 못한다.

예시2) 아주 짧은 메모리 제공

- context 윈도우라는 개념을 데충 메모리라고 보고, 3번의 대화 까지는 기억하도록 매우 짧은 메모리를 쥐어줘보자.

- 대화를 처음부터 다시 시도해보자.

- 그리고 잠깐 동작 순서를 살펴보자.

1) 채팅 수신

2) 메모리 확인 : 현재는 비어있다.

3) ai agent와 통신하여 응답 결과를 받았다.

4) 사람(Human) 과 AI (Chat GPT) 의 내화내용을 저장하였다.

- 이제 이전과 동일하게 내가 누군지 물어보자. 이번엔 정확하게 기억하고 있다. 위에서 저장한 메모리를 통해 대화 내용을 찾아볼 수 있기 때문이다.

- 아무런 대화를 2~3개 더 진행해 보았다.

- 이후 다시 내가 누군지 물어보면 기억할까? context를 잃어버려 기억하지 못할 것이다.

이렇기 때문에 너무 많은 대화, 오래된 대화는 chat GPT, Gemini, Claude 등이 잃어버리고 마치 초기화 되는 것 처럼 보이는데, 이런 경우에 대해 "맥락을 잃어 버렸다", "context를 잃어버렸다"라는 말을 많이 사용하곤 한다. 위의 예시가 도움이 될지 모르겠다. 지금 내가 보여드린 예시는 숏텀 메모리에 가까운데, 일단 다시 하던 이야기를 이어 나가 보자.

💡 "Claude.ai에도 Memory 기능이 있지 않나요?"

맞다. Claude.ai(웹/데스크탑)에는 2025년 9월부터 Memory 기능이 있어 사용자가 명시적으로 저장한 정보를 세션 간에 기억할 수 있다. 하지만 이 기능은 수동적이다. 사용자가 "이것을 기억해"라고 요청해야 저장되며, 개발 프로젝트에서 발생하는 동적인 작업 상태(현재 디버깅 맥락, 코드 변경 이력, 아키텍처 결정 과정 등)를 자동으로 추적하지 못한다.

개발자와 Claude Code 사용자에게 더 큰 문제는 다음과 같다:

대규모 코드베이스: 200K~1M 토큰으로도 전체 프로젝트를 담기 어렵다.
동적 작업 상태: 코딩 세션의 맥락(무엇을 완료했고, 무엇이 남았는지)이 자동으로 다음 세션에 전달되지 않는다.
API 사용자: 기본적으로 세션 간 메모리가 없어 직접 구현해야 한다.

이 글에서 다루는 메모리 패턴들은 바로 이런 개발 워크플로우 특화 문제를 해결하기 위한 것이다.

Short-term vs Long-term 메모리 이해하기

AI 메모리 시스템을 이해하려면 두 가지 유형을 구분하는 것이 중요하다:

	Short-term Memory (단기 메모리, 작업 메모리)	Long-term Memory (장기 메모리, 영구 메모리)
정의	현재 대화에서만 유지되는 메모리	세션이 끝나도 지속되는 메모리
비유	화이트보드 - 회의 끝나면 지워짐	서류 캐비닛 - 오래 보관됨
저장 위치	컨텍스트 윈도우 (책상 위)	파일 시스템, 데이터베이스
수명	❌ 세션 종료 시 사라짐	✅ 어느정도 긴 수명 주기 또는 영구적으로 보존
예시	"방금 내가 보낸 코드", "이 대화에서 논의한 버그"	"프로젝트 규칙", "완료한 작업 목록", "사용자 선호도"

핵심 문제: 기본적으로 Claude는 Short-term Memory만 가지고 있다. 세션이 끝나면 모든 것을 잊어버린다. 아래에서 설명하는 CLAUDE.md, Long-running Agent 패턴, Memory Tool은 모두 Long-term Memory를 구현하기 위한 방법들이다.

Long-term Memory를 구현하는 세 가지 레이어

아래 세 가지 방법 모두 "세션이 끝나도 기억이 유지되는" Long-term Memory를 만드는 접근법이다:

정적 Long-term (CLAUDE.md): "내가 누구인지" - 프로젝트 설정, 팀 컨벤션, 워크플로우 등 사전에 정의된 지식. 세션 시작 시 자동 로드된다.
동적 Long-term (Long-running Agent): "내가 뭘 했는지" - 작업 진행 상황, 세션 간 상태. 파일 시스템 기반으로 자동 추적한다.
API Long-term (Context Management): "무엇을 영구 저장할지" - 도구 결과 자동 정리 + 메모리 파일로 영구 저장. 무한 워크플로우가 가능해진다.

정적 메모리: CLAUDE.md 완전 가이드

CLAUDE.md의 작동 원리

CLAUDE.md는 Claude Code가 시작될 때 자동으로 로드되는 마크다운 파일이다.

개발자 분들에게는 특히나 익숙할 것 이다.

CladeCode를 사용하면서 /init 을 많이 사용하실텐데 이때 생성되는 파일로도 익숙할 것 이다.

ex) 하기 글 참고 : [AI/Claude] - Claude Code CLI (1) - 기본 사용 방법 (클로드 코드 기초 - 기본 명령어 사용 방법)

Anthropic 공식 Best Practices 문서에 따르면, 이 파일은 "Claude의 프롬프트의 일부가 된다(Your CLAUDE.md files become part of Claude's prompts)".

핵심은 이것이 별도의 RAG(Retrieval-Augmented Generation) 시스템이 아니라, 시스템 프롬프트에 직접 주입된다.

Skywork AI의 분석에 따르면, "Anthropic은 복잡한 벡터 데이터베이스와 시맨틱 검색 대신 투명하고 파일 기반의 접근법을 선택했다."

RAG vs CLAUDE.md 차이점

RAG 방식: 벡터 DB에서 시맨틱 검색 → 관련 "청크"만 프롬프트에 주입
CLAUDE.md 방식: 전체 파일을 컨텍스트에 직접 로드 → 사용자가 직접 큐레이션

이 차이가 중요한 이유: CLAUDE.md가 커질수록 컨텍스트 윈도우를 더 많이 차지하므로, 파일 크기 관리가 필수다.

4단계 계층 구조

공식 문서에 따르면, CLAUDE.md는 4개의 계층으로 구성된다. 우선순위는 Enterprise > Project > User > Local 순이며, 상위 계층의 파일이 먼저 로드되고 더 높은 우선순위를 가진다. 충돌 시 상위 계층이 하위 계층을 덮어쓴다.

계층	경로	용도	Git 커밋
Enterprise	macOS: /Library/Application Support/ClaudeCode/CLAUDE.md Linux: /etc/claude-code/CLAUDE.md Windows: C:\ProgramData\ClaudeCode\CLAUDE.md	조직 전체 정책, 보안 가이드라인. MDM, Ansible 등으로 배포한다.	X
User	~/.claude/CLAUDE.md	개인 코딩 스타일, 선호 설정. 모든 프로젝트에 적용된다.	X
Project	./CLAUDE.md 또는 ./.claude/CLAUDE.md	프로젝트 컨벤션, 팀 워크플로우. 팀과 공유한다.	O
Local (deprecated)	./CLAUDE.local.md	개인적인 프로젝트 설정. @import 방식을 권장한다. ⚠️ git worktree 호환성 문제로 deprecated됨	X

Claude Code는 현재 작업 디렉토리(cwd)에서 시작해서 루트 디렉토리까지 상위로 재귀 탐색하면서 모든 CLAUDE.md 파일을 찾아 로드한다. 하위 디렉토리의 CLAUDE.md는 해당 파일에 접근할 때 on-demand로 로드된다.

모노레포에서의 활용 예시

  project/
  ├── CLAUDE.md                    # 루트 레벨 표준
  ├── packages/
  │   ├── frontend/
  │   │   └── CLAUDE.md            # 프론트엔드 전용 패턴
  │   ├── backend/
  │   │   └── CLAUDE.md            # API 컨벤션
  │   └── shared/
  │       └── CLAUDE.md            # 공유 유틸리티 문서
  
  # packages/frontend/ 에서 Claude 실행 시:
  # 1. /project/CLAUDE.md (부모) - 먼저 로드
  # 2. /project/packages/frontend/CLAUDE.md (현재) - 오버라이드
  # 3. 하위 디렉토리 - on-demand 로드

@import 문법으로 모듈화하기

CLAUDE.md 파일이 너무 커지면 컨텍스트 윈도우를 낭비하게 된다. 공식 문서에서는 @path/to/file.md 문법으로 외부 파일을 참조할 수 있다고 설명한다.

@import 사용 예시 (공식 문서 기반)

# 프로젝트 개요
  @README.md 참조
  @package.json에서 사용 가능한 npm 명령 확인
  
  # 추가 지시사항
  @docs/git-instructions.md
  
  # 개인 설정 (팀원별 - 레포에 커밋 안 됨)
  @~/.claude/my-project-instructions.md

@import 규칙

상대 경로와 절대 경로 모두 지원한다.
최대 5단계까지 재귀 import가 가능하다.
코드블록(`@file`) 내의 @는 import로 처리되지 않는다.
/memory 명령으로 현재 로드된 메모리 파일을 확인하고 편집할 수 있다. 기본 에디터에서 열어 내용을 수정하면 즉시 반영된다.

효과적인 CLAUDE.md 작성 원칙

HumanLayer 블로그의 연구 결과에 따르면, CLAUDE.md 작성 시 반드시 알아야 할 LLM의 지시 수용 한계가 있다.

무조건 여기에 많이 작성하는것도 답이 아니었다. 이 부분도 업무를 진행함에 따라 체화하는게 가장 좋을 것 같다.

지시 수 한계에 대한 연구 결과

프론티어 LLM은 약 150-200개의 지시를 일관되게 따를 수 있다.
Claude Code의 시스템 프롬프트에는 이미 ~50개의 지시가 포함되어 있다.
지시 수가 증가하면 모든 지시를 균등하게 무시하기 시작한다. (새 지시만 무시하는 게 아니다)
LLM은 프롬프트의 양 끝(맨 앞과 맨 뒤)에 있는 지시에 편향된다.

결론: CLAUDE.md는 가능한 최소한의 지시만 포함해야 하며, 모든 작업에 보편적으로 적용되는 것만 넣어야 한다.

또한 HumanLayer는 흥미로운 조언을 제시한다: "린터가 할 수 있는 일을 LLM에게 시키지 마라."

코드 스타일 가이드라인에 대한 권장사항

LLM은 린터/포매터보다 비싸고 느리다.
코드 스타일 규칙을 CLAUDE.md에 넣으면 컨텍스트 윈도우 낭비 + 성능 저하가 발생한다.
LLM은 in-context learner이므로 기존 코드 패턴을 자동으로 따르는 경향이 있다.
권장: Stop hook으로 포매터/린터 실행 설정, 스타일 규칙은 별도 슬래시 명령으로 분리하자.

Anthony Calzadilla의 황금률도 기억하자: "Claude를 위해 쓰는 것이지, 주니어 개발자를 온보딩하는 게 아니다."

Anthropic 공식 권장 작성법

구체적으로: "코드를 올바르게 포맷하세요"보다 "2칸 들여쓰기 사용"이 더 효과적이다.
짧은 선언적 불릿 포인트를 사용하자. (긴 서술적 문단은 피한다)
중복 제거: 폴더명이 components면 "컴포넌트를 포함" 설명은 불필요하다.
강조 표현 활용: "IMPORTANT", "YOU MUST" 등으로 준수율을 높일 수 있다.
Prompt Improver 활용: Anthropic은 내부적으로 CLAUDE.md를 Prompt Improver로 최적화한다.
# 키 활용: 세션 중 #를 눌러 지시사항을 즉시 CLAUDE.md에 추가할 수 있다.
정기적 검토: 프로젝트가 발전함에 따라 메모리를 업데이트하여 Claude가 항상 최신 정보를 사용하도록 유지하자.

/init 명령과 자동 생성

/init 명령을 실행하면 Claude가 프로젝트를 분석하고 CLAUDE.md를 자동 생성한다. 기존 파일이 있는 경우 코드베이스를 탐색하여 개선 사항을 제안한다.

// /init 실행 후 권장 작업

1. 생성된 파일을 검토하자 - Claude가 추론할 수 없는 워크플로우를 추가한다.
     (브랜치 명명 규칙, 배포 프로세스, 코드 리뷰 요구사항)
  
  2. 프로젝트에 적용되지 않는 일반적 가이드를 제거한다.
  
  3. 버전 관리에 커밋하여 팀원과 공유한다.
  
  4. 작업 중 반복하는 지시는 # 키로 즉시 추가한다.

ex) 내 AI 학습 프로젝트의 초창기(꽤나 오래전 이지만 단순 /init 을 통해 생성 되었던 CLAUDE.md 파일

# AI Learning & Practice Hub - 개발 원칙

이 워크스페이스는 여러 AI 관련 프로젝트를 포함하며, 공통 개발 원칙을 따릅니다.

## 프로젝트 구조

- **`slackBot/`**: Gemini 2.5 LLM Slack 봇 (AWS Lambda)
- **`notionToHtmlPrj/`**: Notion to HTML 변환 프로젝트
- **`tutorials/`**: Python 학습 자료 및 실습
- 각 프로젝트의 상세 내용은 개별 `README.md` 및 `CLAUDE.md` 참고

## 공통 개발 원칙

### 테스트 기반 개발 (TDD)
- **새로운 기능 구현 시**: 테스트를 먼저 작성한 후 구현
- **테스트 프레임워크**: pytest 사용
- **테스트 범위**: 핵심 로직에 대한 단위 테스트 필수

### Git 워크플로우
- **커밋 규칙**:
  - 테스트 통과 후 커밋
  - 변경한 파일만 선택적으로 add (`git add <specific-files>`)
  - 기능별 작은 단위로 커밋
- **브랜치 전략**:
  - Git Worktree를 활용한 멀티 브랜치 작업 지원 (상세: `WORKTREE_GUIDE.md`)
  - 직접 push 금지 → PR을 통한 코드 리뷰
- **커밋 메시지**: 명확하고 설명적인 메시지 작성 (예: "Add Slack event validation")

### 프론트엔드 검증
- **Playwright MCP 활용**: 프론트엔드 기능 구현 시 실시간 검증
- **브라우저 테스트**: 크로스 브라우저 호환성 확인
- **시각적 검증**: 스크린샷 및 비주얼 리그레션 테스트

### 문서화
- **CLAUDE.md 업데이트**: 중요 개발 환경 변화 시
  - 스크립트 변경
  - 패키지 관리자 변경
  - 데이터베이스 관리 방식 변경
  - 배포 프로세스 변경
- **README.md 유지**: 프로젝트 개요 및 설정 방법 최신 상태 유지
- **PRD 문서**: 새 기능 구현 전 PRD 작성 (템플릿: `prd.md`, `prdSample.md`)

### 코드 품질
- **에러 핸들링**: 모든 외부 API 호출에 재시도 로직 및 fallback 처리
- **로깅**: 적절한 로그 레벨 사용 (INFO 기본, ERROR 필수)
- **타입 힌트**: Python 프로젝트는 타입 힌트 사용 권장
- **린트/포매터**: 프로젝트별 설정 준수

### 환경 설정
- **Python 버전**: 3.12+ 권장
- **패키지 관리자**:
  - `slackBot/`: UV (고속 패키지 관리자)
  - `tutorials/`: venv + pip
- **환경 변수**: `.env.example` 제공 (실제 값은 `.env`에, Git 제외)
- **보안**: 민감 정보는 AWS Secrets Manager 또는 환경 변수로 관리

## 프로젝트별 가이드

각 프로젝트는 고유한 개발 환경과 워크플로우를 가집니다:

- **`slackBot/CLAUDE.md`**: AWS Lambda, Slack API 특화 가이드
- **`tutorials/`**: 학습 목적의 TDD 기반 실습
- **`notionToHtmlPrj/`**: Notion API 통합 가이드

상세 내용은 각 프로젝트의 문서를 참고하세요.

## MCP (Model Context Protocol) 활용

- **Context7**: 라이브러리 문서 조회
- **Sequential**: 복잡한 분석 및 디버깅
- **Magic**: UI 컴포넌트 생성
- **Playwright**: 브라우저 자동화 및 E2E 테스트
- **Linear**: 이슈 트래킹 및 프로젝트 관리
- **Notion**: 문서 관리 및 통합

MCP 연결 설정은 `.mcp.json` 및 `.claude/mcps/` 참고

## 참고 리소스

- **프로젝트 로드맵**: `roadmap.md`
- **작업 관리**: `task.json`, `linear-issues.json`
- **Git Worktree**: `WORKTREE_GUIDE.md`
- **PRD 템플릿**: `prd.md`, `prdSample.md`

템플릿 예시 : 개인 개발자용

~/.claude/CLAUDE.md (User 레벨)

# 개인 선호
  
  ## 언어/프레임워크
  - TypeScript strict mode
  - React with Next.js App Router
  - Tailwind CSS
  
  ## 코딩 규칙
  - 2-space 들여쓰기
  - named export 선호
  - 함수형 컴포넌트만
  
  ## 커밋 메시지
  - feat: 새 기능
  - fix: 버그 수정
  - refactor: 리팩토링
  
  ## 워크플로우
  - 코드 변경 후 항상 타입체크 실행
  - 전체 테스트 대신 단일 테스트 선호 (성능)

템플릿: 팀 프로젝트용

./CLAUDE.md (Project 레벨 - 간결 버전)

# E-Commerce Platform
  
  ## 명령어
  - pnpm dev: 개발 서버 (port 3000)
  - pnpm build: 프로덕션 빌드
  - pnpm test: Jest 테스트
  - pnpm lint: ESLint + Prettier
  
  ## 아키텍처
  - src/features: 기능별 모듈 (feature-sliced)
  - src/lib: 유틸리티
  - @docs/architecture.md 참조
  
  ## 브랜치
  - main: 프로덕션
  - feature/JIRA-XXX-설명
  
  ## 주의사항
  - 결제 코드 수정 시 시니어 리뷰 필수
  - API 키 하드코딩 금지

동적 메모리 : Long-running Agent 패턴

2025년 11월 26일, Anthropic은 "Effective harnesses for long-running agents"라는 엔지니어링 블로그를 통해 장시간 실행되는 에이전트의 메모리 문제 해결 방법을 발표했다. 이 패턴은 CLAUDE.md와는 다른 차원의 문제를 해결한다.

문제 정의: 심각한 실패 패턴

Anthropic은 이 문제를 명확히 정의했다: "장기 실행 에이전트의 핵심 과제는 이산적인 세션에서 작업해야 하며, 각 새 세션은 이전에 무슨 일이 있었는지 전혀 기억하지 못한 채 시작한다는 것이다."

Opus 4.5도 실패하는 케이스

"claude.ai 클론 만들기"와 같은 고수준 프롬프트를 주면, Opus 4.5조차도 여러 컨텍스트 윈도우에 걸쳐 프로덕션 품질의 웹앱을 만들지 못했다.

실패 패턴 1 - One-shot 시도:

한 번에 너무 많은 것을 시도한다.
구현 중간에 컨텍스트가 소진된다.
다음 세션이 반쯤 구현되고 문서화되지 않은 기능으로 시작된다.
에이전트가 무슨 일이 있었는지 추측하느라 시간을 낭비한다.

실패 패턴 2 - 조기 완료 선언:

일부 기능이 완성된 것을 보고
"작업 완료"라고 선언한다.
실제로는 미완성이다.

Anthropic은 compaction(컨텍스트 압축)만으로는 이 문제가 해결되지 않는다고 밝혔다. compaction은 이전 대화를 요약해주지만, "다음 에이전트에게 항상 완벽하게 명확한 지시를 전달하지 못한다."

2-fold 솔루션 심층 분석

Anthropic은 Claude Agent SDK가 여러 컨텍스트 윈도우에 걸쳐 효과적으로 작동하도록 2중 솔루션을 개발했다.

2-Agent 아키텍처 (공식 정의)

Initializer Agent (첫 번째 세션만)
- init.sh 스크립트: 개발 서버 실행 방법
- claude-progress.txt: 에이전트 작업 로그
- feature_list.json: 200+ 기능 목록, 모두 "failing" 상태
- 초기 git commit
Coding Agent (이후 모든 세션)
- pwd, git log, progress 파일 읽기로 상황 파악
- 한 번에 하나의 기능만 작업
- 작업 완료 후 git commit + progress 업데이트
- 환경을 깔끔한 상태로 유지 (main 브랜치 머지 가능 수준)

핵심 파일 1: feature_list.json

Anthropic은 기능 목록에 JSON 형식을 선택한 이유를 설명했다: "Claude는 Markdown 파일보다 JSON 파일의 구조를 더 잘 유지한다. 우리는 '테스트를 삭제하거나 수정하는 것은 용납되지 않는다'와 같은 강력한 표현의 지시와 함께 사용한다."

// feature_list.json 예시 (Anthropic 공식 블로그 발췌)

{
    "features": [
      {
        "category": "functional",
        "description": "New chat button creates a fresh conversation",
        "steps": [
          "Navigate to main interface",
          "Click the 'New Chat' button",
          "Verify a new conversation is created",
          "Check that chat area shows welcome state",
          "Verify conversation appears in sidebar"
        ],
        "passes": false
      }
    ]
  }

Anthropic은 Coding Agent에게 이 파일을 "passes 필드 상태 변경으로만 수정"하도록 프롬프팅한다고 밝혔다.

핵심 파일 2: claude-progress.txt

각 세션이 끝날 때마다 Coding Agent가 업데이트하는 진행 상황 로그다. Anthropic은 이 파일과 git 히스토리가 "에이전트가 새로운 컨텍스트 윈도우로 시작할 때 작업 상태를 빠르게 이해하는 방법"이라고 설명했다.

// claude-progress.txt 예시

# Progress Log
  
  ## Session 1 (2025-11-29 10:00)
  - Initialized project structure
  - Set up Next.js with TypeScript
  - Created feature_list.json with 156 features
  - All features marked as "failing"
  
  ## Session 2 (2025-11-29 14:30)
  - Implemented: New chat button functionality
  - Tested via Puppeteer: PASS
  - Updated feature_list.json (1/156 passing)
  - Known issue: Sidebar animation is choppy
  
  ## Session 3 (2025-11-29 18:00)
  - Fixed sidebar animation issue
  - Implemented: Send message and receive response
  - Tested via Puppeteer: PASS
  - Updated feature_list.json (2/156 passing)
  - Next priority: Conversation history persistence

세션 시작 프로토콜

Anthropic은 Coding Agent가 새 세션을 시작할 때 따르는 표준 절차를 공개했다.

// 세션 시작 시 Claude의 실제 동작 (Anthropic 블로그 발췌)

[Assistant] I'll start by getting my bearings and understanding 
  the current state of the project.
  
  [Tool Use] <bash - pwd>
  [Tool Use] <read - claude-progress.txt>
  [Tool Use] <read - feature_list.json>
  
  [Assistant] Let me check the git log to see recent work.
  
  [Tool Use] <bash - git log --oneline -20>
  
  [Assistant] Now let me check if there's an init.sh script 
  to restart the servers.
  
  <Starts the development server>
  
  [Assistant] Excellent! Now let me navigate to the application 
  and verify that fundamental features are still working.
  
  <Tests basic functionality via Puppeteer>
  
  [Assistant] The core features are working correctly. 
  Now let me review what needs to be implemented next.
  
  <Starts work on a new feature>

테스팅의 중요성: Puppeteer MCP

Anthropic이 발견한 또 다른 중요한 실패 패턴: Claude가 기능을 "완료"로 표시하면서도 실제로 end-to-end 테스트를 하지 않는 것이었다.

Anthropic의 해결책

"Claude에게 브라우저 자동화 도구를 사용하고 인간 사용자처럼 모든 테스트를 수행하도록 명시적으로 프롬프팅하자, 대부분 기능을 end-to-end로 잘 검증했다."

Puppeteer MCP를 통해 Claude는 스크린샷을 찍고, 버튼을 클릭하고, 상태 변화를 확인했다. 이를 통해 코드만 봐서는 발견할 수 없는 버그들을 잡아낼 수 있었다.

알려진 한계
"Claude는 Puppeteer MCP를 통해 브라우저 네이티브 alert 모달을 볼 수 없다. 이런 모달에 의존하는 기능들은 상대적으로 버그가 더 많이 남아있었다."

실패 패턴과 해결책 요약

문제	Initializer Agent	Coding Agent
프로젝트 조기 완료 선언	feature_list.json 생성 (모든 기능 "failing")	파일 읽고 하나씩 작업
버그/미문서화 상태	Git 초기화 + progress 파일	세션 시작 시 로그 확인, 종료 시 commit
기능 조기 완료 표시	테스트 단계 정의	Puppeteer로 실제 테스트 후에만 "passing"
앱 실행 방법 모름	init.sh 스크립트 생성	세션 시작 시 init.sh 읽기

Context Management API (2025년 9월)

2025년 9월 29일, Anthropic은 에이전트의 컨텍스트 관리를 위한 새로운 API 기능을 발표했다: Context Editing과 Memory Tool. (beta header는 context-management-2025-06-27로, 2025년 6월경 개발이 시작되었음을 알 수 있다.)

Context Editing: 오래된 도구 결과 자동 정리

공식 문서에 따르면, clear_tool_uses_20250919 전략은 "대화 컨텍스트가 설정된 임계값을 초과하면 도구 결과를 자동으로 정리"한다. 가장 오래된 도구 결과부터 시간순으로 제거하고, Claude에게 도구 결과가 제거되었음을 알리는 플레이스홀더 텍스트로 대체한다.

성능 결과 (Anthropic 공식 발표)

84% 토큰 절감: 100턴 웹 검색 평가에서 달성했다.
29% 성능 향상: Context Editing 단독 사용 시 나타났다.
39% 성능 향상: Memory Tool과 조합 시 달성했다.
컨텍스트 소진으로 실패했을 워크플로우를 성공적으로 완료할 수 있었다.

Context Editing API 사용 예시 (공식 문서)

response = client.beta.messages.create(
      model="claude-sonnet-4-5",
      max_tokens=4096,
      messages=[...],
      betas=["context-management-2025-06-27"],
      context_management={
          "edits": [
              {
                  "type": "clear_tool_uses_20250919",
                  "trigger": {
                      "type": "input_tokens",
                      "value": 100000  # 100K 토큰 임계값
                  },
                  "keep": {
                      "type": "tool_uses",
                      "value": 3  # 최근 3개 유지
                  }
              }
          ]
      }
  )

Memory Tool: 세션 간 영구 메모리

공식 문서에 따르면, Memory Tool은 "Claude가 메모리 파일 디렉토리를 통해 대화 간에 정보를 저장하고 검색할 수 있게 한다. Claude는 세션 간에 지속되는 파일을 생성, 읽기, 업데이트, 삭제할 수 있어, 모든 것을 컨텍스트 윈도우에 유지하지 않고도 시간이 지남에 따라 지식을 축적할 수 있다."

Memory Tool 명령어 (공식 문서)

// 파일 생성
  {
    "command": "create",
    "path": "/memories/notes.txt",
    "file_text": "Meeting notes:\n- Discussed timeline\n"
  }
  
  // 문자열 교체
  {
    "command": "str_replace",
    "path": "/memories/preferences.txt",
    "old_str": "Favorite color: blue",
    "new_str": "Favorite color: green"
  }
  
  // 특정 줄에 삽입
  {
    "command": "insert",
    "path": "/memories/todo.txt",
    "insert_line": 2,
    "insert_text": "- Review memory tool documentation\n"
  }

Context Editing + Memory Tool 조합

두 기능을 함께 사용하면 무한 워크플로우가 가능해진다. 공식 문서에서 설명하는 시나리오:

코드 리팩토링 프로젝트 예시

Claude가 많은 파일 수정 → 많은 도구 결과 생성
컨텍스트가 커져 임계값에 접근 → Claude가 자동으로 경고 수신
Claude가 지금까지 변경 사항을 메모리 파일에 요약 (예: /memories/refactoring_progress.xml)
Context Editing이 오래된 도구 결과 자동 정리
Claude는 메모리 파일을 참조하여 이미 완료된 변경 사항 확인
워크플로우가 무한정 계속될 수 있다

조합 사용 API 예시

response = client.beta.messages.create(
      model="claude-sonnet-4-5",
      max_tokens=4096,
      messages=[...],
      tools=[
          {
              "type": "memory_20250818",
              "name": "memory"
          },
          # 기타 도구들
      ],
      betas=["context-management-2025-06-27"],
      context_management={
          "edits": [
              {"type": "clear_tool_uses_20250919"}
          ]
      }
  )

권장 메모리 프로토콜

IMPORTANT: 다른 작업 전에 항상 메모리 디렉토리를 확인하라.
  
  MEMORY PROTOCOL:
  1. memory 도구의 view 명령으로 이전 진행 상황 확인
  2. (작업 수행)
  3. 진행하면서 상태/진행/생각을 메모리에 기록
  
  ASSUME INTERRUPTION: 컨텍스트 윈도우가 언제든 리셋될 수 있으므로,
  메모리 디렉토리에 기록하지 않은 진행 상황은 잃어버릴 위험이 있다.

메모리 시스템 통합 전략

세 가지 메모리 레이어(CLAUDE.md, Long-running Agent, Context Management)는 서로 다른 문제를 해결하지만, 함께 사용하면 시너지를 낸다.

통합 메모리 아키텍처

  ┌─────────────────────────────────────────────────────────┐
  │                    Claude 세션 시작                      │
  ├─────────────────────────────────────────────────────────┤
  │                                                         │
  │  1단계: 정적 메모리 자동 로드                            │
  │  ┌─────────────────────────────────────────────────┐   │
  │  │  CLAUDE.md 계층 로드 (Enterprise→User→Project)  │   │
  │  │  - 프로젝트 정체성                               │   │
  │  │  - 팀 컨벤션                                     │   │
  │  │  - 명령어와 워크플로우                           │   │
  │  └─────────────────────────────────────────────────┘   │
  │                         ↓                               │
  │  2단계: 동적 메모리 확인 (Long-running 패턴)            │
  │  ┌─────────────────────────────────────────────────┐   │
  │  │  pwd → git log → claude-progress.txt            │   │
  │  │  → feature_list.json → 기본 테스트              │   │
  │  └─────────────────────────────────────────────────┘   │
  │                         ↓                               │
  │  3단계: 작업 수행 + API 레벨 메모리 (선택적)            │
  │  ┌─────────────────────────────────────────────────┐   │
  │  │  Context Editing: 오래된 도구 결과 자동 정리     │   │
  │  │  Memory Tool: 세션 간 지식 영구 저장             │   │
  │  └─────────────────────────────────────────────────┘   │
  │                         ↓                               │
  │  4단계: 세션 종료 시 상태 저장                          │
  │  ┌─────────────────────────────────────────────────┐   │
  │  │  - git commit (설명적 메시지)                    │   │
  │  │  - claude-progress.txt 업데이트                  │   │
  │  │  - feature_list.json 상태 변경                   │   │
  │  └─────────────────────────────────────────────────┘   │
  └─────────────────────────────────────────────────────────┘

통합 CLAUDE.md 템플릿

Long-running Agent 패턴과 Context Management를 CLAUDE.md에 통합한 예시다.

CLAUDE.md (정적 + 동적 통합)

# AI Chat Application
  
  ## 명령어
  - ./init.sh: 개발 환경 시작
  - pnpm dev: 개발 서버
  - pnpm test: 테스트
  
  ## Long-running Agent 프로토콜
  
  ### 세션 시작 시 (MUST)
  1. pwd로 현재 위치 확인
  2. claude-progress.txt 읽기
  3. feature_list.json 읽기
  4. git log --oneline -10 확인
  5. ./init.sh 실행
  6. 기본 기능 테스트
  
  ### 작업 규칙 (IMPORTANT)
  - 한 번에 하나의 기능만 작업
  - 완료 후 Puppeteer로 end-to-end 테스트
  - 테스트 통과 후에만 "passes": true
  - 모든 변경은 git commit
  
  ### 세션 종료 전 (MUST)
  - claude-progress.txt 업데이트
  - 설명적 커밋 메시지 작성
  
  ### 절대 금지 (YOU MUST NOT)
  - feature_list.json의 테스트 삭제/수정
  - 테스트 없이 "완료" 선언
  - 여러 기능 동시 작업

실전 워크플로우 패턴

Anthropic 공식 Best Practices 문서에서 권장하는 워크플로우 패턴을 정리했다.

패턴 1: Explore → Plan → Code → Commit

탐색: 관련 파일을 읽되, 아직 코드는 작성하지 않는다. 복잡한 문제에는 서브에이전트 사용을 권장한다.
계획: "think" 단어로 extended thinking 모드를 트리거한다. 레벨: "think" < "think hard" < "think harder" < "ultrathink"
구현: 솔루션의 합리성 명시적 검증을 요청한다.
커밋: PR 생성, README/changelog 업데이트를 진행한다.

패턴 2: TDD 워크플로우

예상 입력/출력 기반 테스트를 작성한다. (TDD임을 명시하여 mock 구현 방지)
테스트를 실행하여 실패를 확인한다. (구현 코드 작성 금지 명시)
테스트를 커밋한다.
테스트 통과 코드를 작성한다. (테스트 수정 금지 지시)
서브에이전트로 overfitting 검증을 요청한다.
코드를 커밋한다.

패턴 3: Multi-Claude 워크플로우

Anthropic은 여러 Claude 인스턴스를 병렬로 실행하는 것을 강력히 권장한다.

Multi-Claude 패턴들

1. 코드 작성 + 검증 분리:

Claude A가 코드를 작성한다.
/clear 또는 새 터미널에서 Claude B를 시작한다.
Claude B가 Claude A의 작업을 리뷰한다.
Claude C가 코드와 리뷰 피드백 모두 읽고 수정한다.

2. Git Worktrees 활용:

git worktree add ../project-feature-a feature-a
각 worktree에서 별도 Claude를 실행한다.
같은 Git 히스토리를 공유하며, 독립적 파일 상태를 유지한다.
작업 완료 시: git worktree remove ../project-feature-a

3. 별도 스크래치패드 통신:

각 Claude에게 읽을 스크래치패드와 쓸 스크래치패드를 지정한다.
Claude 인스턴스 간 간접 통신이 가능해진다.

한계점과 미래

현재 한계점

알려진 한계

브라우저 네이티브 모달: Puppeteer MCP가 alert, confirm, prompt 모달을 인식하지 못한다.
CLAUDE.md 비대화: 파일이 커지면 성능 저하, "기억 희미해짐" 현상이 발생한다.
메모리 누수 위험: 2025년 8월 GitHub 이슈에서 120GB RAM 소비 버그가 보고되었다.
실시간 업데이트 불가: CLAUDE.md 수정 후 명시적으로 다시 읽어야 한다.
지시 수 한도: 150-200개 지시 초과 시 모든 지시를 균등하게 무시한다.

향후 발전 방향

Anthropic은 Long-running Agent 블로그에서 몇 가지 열린 질문을 제시했다:

단일 vs 멀티 에이전트: 범용 코딩 에이전트가 좋은지, 테스트/QA/정리 등 전문화된 에이전트들이 좋은지
도메인 일반화: 과학 연구, 금융 모델링 등 다른 분야에도 적용 가능한지
자동 메모리 관리: 에이전트가 스스로 어떤 정보를 기억하고 잊을지 결정하는 것

자주 묻는 질문 ❓

Q: CLAUDE.md에 코드 스타일 가이드를 넣어야 하나?

A: HumanLayer 연구에 따르면 권장하지 않는다. LLM은 린터보다 비싸고 느리며, in-context learner이므로 기존 코드 패턴을 자연스럽게 따른다. 대신 Stop hook으로 린터/포매터를 실행하고, 스타일 가이드는 필요시 슬래시 명령으로 별도 제공하는 것이 좋다.

Q: feature_list.json은 꼭 JSON이어야 하나?

A: Anthropic 실험 결과, Claude는 Markdown 파일보다 JSON 파일의 구조를 더 잘 유지한다. 특히 "테스트 항목 삭제 금지" 같은 규칙을 더 잘 따른다.

Q: Context Editing과 compaction의 차이는?

A: Compaction은 대화 히스토리를 요약으로 대체하는 SDK 기능이고, Context Editing은 도구 결과만 선택적으로 제거하는 서버 측 API 기능이다. 두 가지를 함께 사용할 수 있다.

Q: Extended Thinking 레벨은 어떻게 조절하나?

A: 프롬프트에 특정 단어를 포함하면 된다. "think"(~4K 토큰) < "think hard/megathink"(~10K 토큰) < "think harder/ultrathink"(~32K 토큰) 순으로 thinking budget이 증가한다. 단, 이 키워드는 Claude Code CLI에서만 작동하며, 웹 인터페이스나 API에서는 별도 설정이 필요하다.

Q: 세 가지 메모리 시스템을 모두 사용해야 하나?

A: 아니다. 프로젝트 복잡도에 따라 선택하면 된다. 단순한 프로젝트는 CLAUDE.md만으로 충분하고, 며칠 이상 걸리는 프로젝트는 Long-running 패턴을 추가하고, 매우 긴 워크플로우는 Context Management API를 활용한다.

마치며 : 체크리스트 예시

프로젝트 시작 전

☐ ~/.claude/CLAUDE.md에 개인 코딩 스타일 정의 (간결하게)
☐ 프로젝트 루트에 CLAUDE.md 생성 (/init 또는 수동)
☐ 150-200개 지시 한도 고려하여 최소한으로 작성
☐ 코드 스타일은 린터/포매터에 위임

장기 프로젝트의 경우

☐ Initializer Agent로 feature_list.json 생성
☐ claude-progress.txt 파일 생성
☐ init.sh 스크립트 작성
☐ CLAUDE.md에 Long-running 프로토콜 추가
☐ Puppeteer MCP 설정 (end-to-end 테스트용)

매 세션마다

☐ Claude가 progress 파일과 git log 읽었는지 확인
☐ 한 번에 하나의 기능만 작업
☐ 종료 전 git commit + progress 업데이트
☐ 필요시 /clear로 컨텍스트 리셋

API 레벨 (선택적)

☐ context-management-2025-06-27 베타 헤더 추가
☐ clear_tool_uses 전략 구성
☐ Memory Tool 활성화
☐ 메모리 프로토콜 프롬프트에 포함

참고 자료

Anthropic: Effective harnesses for long-running agents - Long-running Agent 패턴 공식 발표 (2025.11.26)
Anthropic: Claude Code Best Practices - 워크플로우 패턴 공식 가이드
Claude Docs: Manage Claude's memory - CLAUDE.md 공식 문서
Claude Code: 메모리 관리 (한국어) - CLAUDE.md 한국어 공식 문서
Claude Docs: Claude 4 Best Practices - 프롬프팅 가이드
Anthropic: Managing context on the Claude Developer Platform - Context Management 공식 발표 (2025.09.29)
Claude Platform: Context Editing - API 문서
Claude Docs: Memory Tool - 영구 메모리 API 문서
HumanLayer: Writing a good CLAUDE.md - 지시 수 한도 연구
GitHub: Anthropic Quickstarts - 코드 예시 레포지토리

Claude의 메모리 시스템은 아직 발전 중이다. CLAUDE.md를 통한 정적 메모리, Long-running Agent 패턴을 통한 동적 메모리, 그리고 Context Management API를 적절히 조합하면 현재 시점에서 가능한 최선의 "기억하는 AI 협업자"를 만들 수 있다.

핵심은 간결함이다. CLAUDE.md는 최소한으로 유지하고, 동적 상태는 파일 시스템에 기록하고, API 레벨에서 자동 정리와 영구 저장을 조합한다. 이 패턴들을 적용한 것과 안 한 것의 생산성 차이는 분명히 체감될 것이다.

저작자표시 비영리 변경금지 (새창열림)

'AI > Claude' 카테고리의 다른 글

Claude Code Desktop : 터미널 없이 AI 코딩 에이전트 사용하기 (3)	2025.11.27
Claude for Excel 리뷰 : AI가 엑셀을 직접 분석하고 수정하는 시대 (1)	2025.11.27
Claude Opus 4.5 리뷰 - 에이전트 시대의 시작(SWE-bench 1위, 76% 토큰 절감, 역대 최강 안전성, 사용량 정책 변경 정 (4)	2025.11.25
Claude Code Web - 설치 없이 브라우저만으로 코드 자동화, 병렬 작업 해보기 (0)	2025.10.24
클로드 스킬(Claude Skills) 사용방법 - Docs,Pptx,Xlsx 스킬 활용 + Custom Skill 등록 해보기 (3)	2025.10.23

Contents