클로드 코드 서브에이전트 지속 메모리 설정법: 회차마다 똑똑해지는 AI 만들기

뭘 만들 수 있나요?

클로드 코드(Claude Code) 서브에이전트는 메인 대화와 분리된 자체 컨텍스트에서 특정 작업만 전담하는 보조 AI입니다. 여기에 지속 메모리(persistent memory)를 붙이면, 대화가 끝나도 학습한 내용이 디스크에 남아 다음 회차로 이어집니다.

그동안 서브에이전트의 한계는 명확했습니다. 세션이 끝나면 배운 것을 전부 잊었죠. 코드리뷰어에게 "우리 팀은 이런 컨벤션을 쓴다"고 매번 다시 알려줘야 했고, 디버깅 에이전트는 지난주에 잡은 함정을 이번 주에 또 밟았습니다. memory 필드 하나가 이 문제를 해결합니다. 서브에이전트가 코드베이스 패턴, 디버깅 인사이트, 아키텍처 결정 같은 지식을 스스로 쌓아 회차마다 더 똑똑해집니다.

준비물

• 클로드 코드(Claude Code) CLI 설치 및 실행 환경
• 서브에이전트를 저장할 .claude/agents/(프로젝트) 또는 ~/.claude/agents/(내 모든 프로젝트) 폴더
• 사전 지식: 마크다운, YAML frontmatter 개념 정도면 충분합니다

Step 1: 서브에이전트 파일 만들기

서브에이전트는 YAML frontmatter가 붙은 마크다운 파일 하나입니다. .claude/agents/ 폴더에 code-reviewer.md를 만들고, 상단 frontmatter에 이름과 설명, 그리고 이번 글의 핵심인 memory 필드를 넣습니다.

---
name: code-reviewer
description: 코드 품질과 베스트 프랙티스를 검토합니다
memory: project
---

당신은 코드리뷰어입니다. 코드를 검토하면서 발견한 패턴, 컨벤션,
반복되는 문제를 에이전트 메모리에 업데이트하세요.

frontmatter 아래 본문이 서브에이전트의 시스템 프롬프트가 됩니다. 여기에 "메모리를 어떻게 쓸지"를 직접 적어두는 것이 핵심입니다.

Step 2: 메모리 스코프 정하기

memory 값으로 지식이 얼마나 넓게 적용될지를 결정합니다. 세 가지 스코프가 있고, 각각 저장 위치가 다릅니다.

공식 문서가 권장하는 기본값은 project입니다. 서브에이전트가 쌓은 지식을 버전관리에 커밋하면 팀원 전체가 같은 "기억"을 공유하기 때문입니다. 한 사람이 발견한 함정을 나머지 팀도 물려받는 셈입니다.

Step 3: 메모리가 켜지면 자동으로 벌어지는 일

memory 필드를 넣기만 하면 클로드 코드가 세 가지를 자동으로 처리합니다.

• 서브에이전트의 시스템 프롬프트에 메모리 디렉터리 읽기·쓰기 지침이 삽입됩니다.
• 그 디렉터리의 MEMORY.md 파일에서 앞 200줄 또는 25KB 중 먼저 도달하는 만큼이 시스템 프롬프트에 함께 주입됩니다. 이 한도를 넘으면 서브에이전트가 스스로 MEMORY.md를 정리(curate)하라는 지침도 함께 받습니다.
• Read, Write, Edit 도구가 자동으로 활성화되어 서브에이전트가 자기 메모리 파일을 직접 관리할 수 있습니다.

즉 별도의 도구 설정 없이 memory 한 줄이면 "읽고·쓰고·정리하는" 메모리 루프가 완성됩니다.

Photo by Steve A Johnson on Unsplash

Step 4: 실전 활용 — "확인하고 저장하는" 루프

메모리를 실제로 살아 움직이게 하려면, 작업의 앞뒤로 두 번 지시하면 됩니다. 이 루프가 서브에이전트를 회차마다 성장시킵니다.

활용 1: 코드리뷰어에게 과거 패턴을 참조시키기

작업을 시작할 때 메모리부터 확인하도록 지시합니다.

이 PR을 리뷰해줘. 그리고 전에 봤던 패턴이 있는지 네 메모리를 먼저 확인해.

리뷰어는 MEMORY.md에 쌓인 "이 프로젝트는 이런 실수를 반복한다"는 기록을 근거로 검토합니다. 처음부터 컨벤션을 다시 설명할 필요가 없습니다.

활용 2: 작업 후 배운 것을 저장시키기

작업이 끝나면 학습 내용을 남기게 합니다.

다 끝났으면, 이번에 알게 된 걸 네 메모리에 저장해.

이 지시를 반복할수록 서브에이전트의 지식 베이스가 두꺼워지고, 리뷰·디버깅 품질이 함께 올라갑니다.

활용 3: 파일에 지시를 박아 스스로 관리하게 하기

매번 지시하기 번거롭다면, 서브에이전트 마크다운 본문에 메모리 관리 규칙을 직접 넣어둡니다.

코드경로, 패턴, 라이브러리 위치, 핵심 아키텍처 결정을 발견할 때마다
에이전트 메모리를 업데이트하세요. 이렇게 하면 대화가 바뀌어도 조직의
지식이 축적됩니다. 무엇을 찾았고 어디에 있는지 간결하게 기록하세요.

이제 서브에이전트가 요청 없이도 알아서 지식을 쌓습니다. 디버깅 에이전트라면 "이 버그는 이 파일의 이 함수에서 반복된다" 같은 노트를, 아키텍처 담당이라면 주요 설계 결정을 스스로 남깁니다.

결과

memory 필드 한 줄로 서브에이전트가 일회용 도우미에서 지식이 누적되는 전문가로 바뀝니다. project 스코프로 커밋해두면 팀 전체가 같은 메모리를 물려받아, 한 명이 학습한 내용이 조직의 자산이 됩니다.

주의할 점

• 서브에이전트끼리 메모리를 공유하지 않습니다. 각 서브에이전트는 독립된 컨텍스트에서 돌기 때문에, 한 에이전트의 도메인 지식이 다른 에이전트의 판단을 오염시키지 않도록 의도적으로 격리되어 있습니다. 코드리뷰어의 메모리와 디버거의 메모리는 별개입니다.
• 메인 대화의 자동 메모리(auto memory)는 서브에이전트로 전달되지 않습니다. 서브에이전트에 지속 기억을 주려면 반드시 memory 필드를 써야 합니다.
• MEMORY.md가 비대해지면 성능이 떨어집니다. 200줄/25KB 한도를 넘으면 서브에이전트가 정리 지침을 받지만, 정기적으로 사람이 한 번씩 다듬어주는 편이 안전합니다.

자주 묻는 질문

클로드 코드 서브에이전트 메모리는 어떻게 켜나요?

서브에이전트 마크다운 파일의 YAML frontmatter에 memory: project(또는 user, local) 한 줄을 추가하면 됩니다. 이것만으로 지속 메모리 디렉터리가 생성되고, Read·Write·Edit 도구가 자동 활성화됩니다.

user, project, local 스코프 중 뭘 골라야 하나요?

공식 문서 권장 기본값은 project입니다. 지식을 버전관리로 팀과 공유할 수 있기 때문입니다. 모든 프로젝트에서 공통으로 쓸 개인 지식이면 user, 팀 저장소에는 올리기 싫은 로컬 전용 지식이면 local을 선택합니다.

서브에이전트끼리 메모리를 공유할 수 있나요?

아니요. 각 서브에이전트는 독립된 컨텍스트 윈도우에서 동작하며 메모리도 격리됩니다. 이는 한 에이전트의 지식이 다른 에이전트의 판단을 오염시키는 것을 막기 위한 의도적 설계입니다.

메모리 내용이 너무 길어지면 어떻게 되나요?

MEMORY.md의 앞 200줄 또는 25KB 중 먼저 도달하는 만큼만 시스템 프롬프트에 주입됩니다. 한도를 넘으면 서브에이전트가 스스로 MEMORY.md를 정리하라는 지침을 함께 받습니다.

인사이트

이 기능의 진짜 의미는 "서브에이전트가 기억한다"가 아니라, AX(에이전트 경험) 설계의 무게중심이 프롬프트에서 메모리 축적으로 옮겨간다는 데 있습니다. 지금까지 우리는 좋은 서브에이전트를 만들려고 시스템 프롬프트를 정교하게 다듬는 데 집중했습니다. 하지만 프롬프트는 정적이라 한계가 분명합니다. 반면 project 메모리는 팀이 실제로 부딪힌 함정과 컨벤션을 시간에 따라 흡수하는 살아있는 문서라, 정교하게 쓴 프롬프트 열 줄보다 실전에서 쌓인 메모리 한 줄이 더 정확할 때가 많습니다.

특히 한국의 소규모 개발팀에게 이 기능은 "온보딩 문서의 자동화"로 읽힙니다. 신규 입사자에게 넘기는 팀 컨벤션 위키를, 사람이 아니라 코드리뷰어 서브에이전트가 매 PR마다 자동으로 갱신하는 그림입니다. .claude/agent-memory/를 저장소에 커밋하는 순간, 그 폴더 자체가 팀의 집단 지성이 축적되는 공용 뇌가 됩니다.

다만 격리 설계는 양날의 검입니다. 코드리뷰어와 디버거가 메모리를 나누지 않는다는 건, 두 에이전트가 사실상 같은 함정을 각자 다시 배워야 한다는 뜻이기도 합니다. 여러 서브에이전트가 공유해야 할 팀 공통 지식은 여전히 CLAUDE.md 같은 별도 채널에 두고, memory는 각 에이전트의 전문 영역 지식에 한정하는 이원 전략이 당분간 현실적인 운용법일 것입니다.

원문: Create custom subagents — Enable persistent memory (Claude Code Docs)