에이전트는 무엇을 기억하나 — 컨텍스트의 한계
공용 기억을 설계하려면 먼저 에이전트의 “기억”이 어떻게 생겼는지 알아야 합니다. 에이전트가 아는 것은 지금 펼쳐 놓은 글, 곧 컨텍스트뿐입니다. 이 장에서는 컨텍스트의 한도와 약점, 그리고 그 약점을 피하는 세 가지 방법(압축 · 메모 · 필요할 때 불러오기)을 차례로 보고, 이것이 이 가이드의 “다섯 층” 구조로 어떻게 이어지는지 정리합니다.
컨텍스트 창 — 에이전트가 한 번에 펼쳐 보는 책상
Anthropic 의 컨텍스트 엔지니어링 글은 컨텍스트를 “모델이 답을 만들 때 함께 들어가는 토큰(AI 가 읽고 쓰는 글의 양을 세는 단위)의 묶음”이라고 정의합니다. 쉽게 말해 에이전트가 지금 책상 위에 펼쳐 둔 모든 글입니다. 컨텍스트 창(context window — 그 책상의 넓이, 한 번에 담을 수 있는 글의 한도)을 넘는 글은 올려놓을 수 없습니다.
책상 위에는 사람이 쓴 프롬프트(에이전트에게 보내는 지시문)만 있는 것이 아닙니다. 원문은 에이전트가 관리해야 할 컨텍스트로 시스템 지시, 도구, MCP, 외부 데이터, 대화 기록을 듭니다. 에이전트가 “생각 → 도구 사용 → 결과 확인”을 여러 차례 되풀이하며 일할수록 다음 차례에 쓸 만한 글이 계속 생기고, 무엇을 책상에 올릴지 매번 다시 골라야 합니다. 원문은 이 고르는 일을 컨텍스트 엔지니어링이라고 부르며, 좋은 문구를 찾는 프롬프트 작성의 다음 단계라고 설명합니다.
| 사실 | 원문이 말하는 것 | 공용 기억에 주는 뜻 |
|---|---|---|
| 새 세션 = 빈 책상 | Claude Code 의 모든 세션은 새 컨텍스트 창에서 시작 | 남기고 싶은 것은 파일로 적어야 다음 세션이 봅니다 |
| 요청마다 전체 전송 | 요청할 때마다 대화 전체를 보냄. 관계없는 일 세 개가 쌓인 세션은 네 번째 일의 매 차례에 셋을 다시 읽음 | 책상에 쌓인 글은 쓸 때마다 비용이 듭니다 |
| 창은 넓어짐 | 요즘 모델 대부분은 100만 토큰 창, 한도 가까이에서 자동 압축 — 창이 모자라는 일은 드묾 | 문제는 “모자람”보다 “흐려짐”과 “비용”입니다(다음 소절) |
컨텍스트 썩음 — 많이 넣을수록 흐려집니다
책상이 넓으면 무엇이든 다 올려 두면 될 것 같지만, 원문은 반대로 말합니다. 건초 더미에서 바늘 찾기 같은 시험에서 드러난 현상으로, 컨텍스트 창 안의 토큰이 늘어날수록 그 안의 정보를 정확히 떠올리는 힘이 떨어집니다. 원문은 이를 컨텍스트 썩음(context rot)이라 부르고, 정도의 차이는 있어도 모든 모델에서 나타난다고 적습니다.
원문은 사람의 작업 기억에 빗대어 언어 모델에도 주의력 예산(attention budget — 많은 글을 읽을 때 쓰는 집중력의 한도)이 있다고 말합니다. 새 토큰은 하나하나 이 예산을 조금씩 씁니다. 그래서 컨텍스트는 “쓸수록 효과가 줄어드는 한정된 자원”으로 다뤄야 합니다.
결론은 한 문장입니다. 좋은 컨텍스트란 원하는 결과가 나올 가능성을 가장 높이는, 꼭 필요한 정보만 담은 가장 작은 글 묶음입니다(원문 표현은 “신호가 강한 토큰의 가장 작은 묶음”). 공용 기억에 옮기면 “모두에게 항상 읽히는 파일은 짧고 알차게” 써야 한다는 뜻입니다.
지침 파일에 미치는 영향
Claude Code 메모리 문서는 CLAUDE.md 를 파일당 200줄 아래로 권합니다. 길수록 컨텍스트를 더 쓰고 지침을 덜 따르기 때문입니다.
강조보다 짧게
모범 사례 문서: 긴 파일 속에서 한 줄이 묻힌다면 강조를 더할 일이 아니라 파일을 줄일 일입니다. 꼭 지켜야 할 규칙은 훅이나 거부 규칙으로.
일과 일 사이 정리
창이 넓어진 지금도 /clear(지금 대화를 비우고 새로 시작하는 명령) 로 관계없는 일 사이를 끊는 것은 여전히 할 만합니다. 집중된 컨텍스트가 더 나은 답을, 더 적은 비용으로 줍니다.
구조화된 메모 — 책상 밖 노트에 적고, 다시 펼쳐 읽기
두 번째 방법이 구조화된 메모(structured note-taking — 에이전트가 컨텍스트 창 바깥 파일에 메모를 남기고 나중에 다시 읽어 들이는 것)입니다. 원문은 이를 “에이전트의 기억(agentic memory)”이라고도 부릅니다. 적은 노력으로 오래가는 기억을 만드는 방법으로, Claude Code 가 할 일 목록을 만드는 것이나 직접 만든 에이전트가 NOTES.md 파일을 관리하는 것이 그 예입니다.
원문은 코딩이 아닌 예로 포켓몬 게임을 하는 Claude를 듭니다. 이 에이전트는 수천 단계에 걸쳐 “1번 도로에서 1,234걸음째 훈련 중, 피카츄가 목표 10레벨 중 8레벨 올랐다” 같은 기록을 정확히 이어 갑니다. 메모 구조를 따로 알려 주지 않았는데도 탐험한 곳의 지도, 달성한 일, 상대별로 잘 통한 공격 같은 전략 메모를 스스로 남겼습니다. 컨텍스트가 초기화된 뒤에는 자기 메모를 읽고 몇 시간짜리 훈련과 던전 탐험을 이어 갔습니다.
| 원문에 있는 메모 장치 | 누가 쓰나 | 언제 다시 읽히나 | 장 |
|---|---|---|---|
| CLAUDE.md (지침 파일) | 사람 | 매 세션 시작 때 | 3장 |
| 자동 메모리 | Claude | 매 세션 시작 때 (처음 200줄 또는 25KB) | 5장 |
메모리 도구 /memories | Claude (저장은 그 에이전트를 만든 개발자의 프로그램이 맡음) | 켜 두면 작업을 시작하기 전에 메모리 디렉터리를 자동으로 확인 | 5장 |
NOTES.md · claude-progress.txt | 에이전트 | 시작할 때 읽도록 지시해 둠 | 7장 |
- 에이전트가 아는 것은 지금 컨텍스트 창(책상)에 올라온 글뿐이고, 새 세션은 빈 책상에서 시작합니다.
- 글이 많을수록 정확히 떠올리는 힘이 완만하게 떨어집니다(컨텍스트 썩음). 좋은 컨텍스트는 “꼭 필요한 정보만 담은 가장 작은 묶음”입니다.
- 긴 일에는 압축(요약해 이어 가기), 구조화된 메모(창 밖 파일에 적고 다시 읽기), 서브에이전트(요약만 돌려받기)를 일의 성격에 맞게 씁니다.
- 자료는 미리 다 넣지 말고 경로·이름 같은 표시만 두고 필요할 때 찾게 합니다. Claude Code 는 CLAUDE.md 만 먼저 넣는 혼합형입니다.
- 이 원리로 공용 기억을 다섯 층(항상 읽힘 · 필요할 때 · 스스로 쌓음 · 인수인계 · 바깥 연결)으로 나눕니다.
이 장의 나머지 소절과 🔧 세부는 완전 가이드 1장에 있습니다.
세컨드 브레인 설계 — CODE 와 PARA 를 에이전트용으로
1장에서 “어느 층에 둘까”를 정했다면, 이 장은 “무엇을, 어떤 모양으로 둘까”를 정합니다. 사람의 세컨드 브레인(배운 것을 뇌 바깥 한곳에 모아 둔 디지털 지식 창고)을 만드는 방법으로 널리 쓰이는 Forte Labs 의 CODE(네 단계)와 PARA(네 칸 정리법)를 먼저 원문대로 살펴보고, 이를 에이전트 팀의 공용 기억에 옮기는 방법을 제안합니다. 핵심은 두 가지입니다. 모든 정보를 팀의 목표와 프로젝트에 묶어 정리하고, 모든 메모를 다음 에이전트가 바로 쓸 수 있게 적는 것입니다.
CODE — 세컨드 브레인을 만들고 쓰는 네 단계
Forte Labs 의 티아고 포르테는 세컨드 브레인을 만드는 방법을 CODE 네 단계로 정리합니다. Capture(모으기) · Organize(정리하기) · Distill(추리기) · Express(표현하기)입니다. 원문은 이것이 세컨드 브레인을 만드는 단계이자 이후 계속 함께 일하는 단계라고 말합니다. 직업이나 메모 도구에 상관없이 쓸 수 있고, 누구나 이미 어떤 형태로든 하고 있는 일이라고도 덧붙입니다.
| 단계 | 원문의 뜻 (사람용) | 에이전트 팀으로 옮기면 (이 가이드의 제안) |
|---|---|---|
| 모으기 | 정말 중요한 것만, 마음에 와닿는 것만 한곳에 모음 | 저장소(파일과 변경 이력을 함께 보관하는 프로젝트 폴더)·자료를 읽어서는 알 수 없는 결정·절차만 공용 기억에 적음 |
| 정리하기 | 주제가 아니라 “실행에 쓸모”로 정리 — PARA | 폴더를 팀의 프로젝트·영역 기준으로 나눠, 에이전트가 이름과 자리로 찾게 함 |
| 추리기 | 핵심만 남긴 짧은 요약을 겹겹이 | 항상 읽히는 층은 요약만, 세부는 필요할 때 읽는 파일로 |
| 표현하기 | 쌓은 지식으로 실제 결과물을 만들고 나눔 | 세션마다 결과물 하나를 끝내고, 그 결과를 다시 공용 기억에 남김 |
PARA — 주제가 아니라 “실행”으로 나누는 네 칸
정리하기 단계에서 원문이 쓰는 방법이 PARA 입니다. 원문은 삶의 모든 정보가 단 네 칸에 들어간다고 말합니다.
Projects · 프로젝트
어떤 목표를 두고 하는 짧은 기간의 일. 예: 웹페이지 디자인 끝내기, 연구 보고서 쓰기.
Areas · 영역
시간을 두고 계속 챙기는 책임. 예: 마케팅, 인사, 건강, 재정. 끝나는 날이 없습니다.
Resources · 자원
앞으로 쓸모 있을지 모르는 관심 주제. 예: 그래픽 디자인, 사진, 습관 만들기.
Archives · 보관
앞의 세 칸에서 더는 활발하지 않은 것. 끝냈거나 멈춘 프로젝트, 관심이 식은 자원.
핵심 원칙은 “실행 가능성으로 정리하라”입니다. 학교에서 배운 대로 “마케팅”, “심리학” 같은 넓은 주제로 나누면, 바쁜 날 필요한 정보 하나를 찾느라 큰 칸을 뒤져야 합니다. 원문은 대신 지금 맡고 있는 프로젝트와 목표를 기준으로 정리하라고 합니다. 디자인 프로젝트를 시작하면 그에 필요한 메모·문서·자료가 한자리에 모여 있어야 한다는 것입니다.
에이전트에게도 이 정리법이 잘 맞는 이유는 1장에서 본 “필요할 때 불러오기”에 있습니다. 컨텍스트 엔지니어링 글은 폴더 구조·이름 규칙·날짜가 에이전트에게 “이 정보를 언제 어떻게 쓸지” 알려 주는 신호라고 말합니다. 프로젝트별로 나뉜 폴더는 에이전트가 지금 맡은 일에 필요한 파일만 골라 읽게 해 줍니다. 또 Claude Code 는 하위 폴더에 있는 CLAUDE.md(매 세션 읽히는, 사람이 쓴 지침 파일) 를 시작 때 읽지 않고, Claude 가 그 폴더의 파일을 읽거나 고칠 때 불러옵니다. 그래서 프로젝트마다 짧은 안내를 붙여 둘 수 있습니다.
team-brain/ ← 공용 기억 폴더 (예시 이름)
├── CLAUDE.md ← 항상 읽힘. 팀 목표 문서를 @GOAL.md 로 불러옴
├── GOAL.md ← 팀 목표 (예시 이름, 아래 「팀 목표 문서」)
├── inbox.md ← 일단 적어 두는 곳 (예시 이름)
├── projects/ ← 진행 중 프로젝트 (예시 이름)
│ └── q4-report/
│ ├── CLAUDE.md ← 이 폴더 파일을 만질 때 불러옴
│ └── NOTES.md ← 진행 메모
├── areas/ ← 계속 맡는 영역 (예시 이름)
├── resources/ ← 참고 자료 (예시 이름)
└── archive/ ← 끝난 것 (예시 이름)
CLAUDE.md · NOTES.md 는 원문에 있는 이름이고, 나머지는 예시입니다. 개인 팀과 회사 팀은 이 폴더를 각각 따로 둡니다(9장).
팀 목표 문서 — 모두가 같은 목표를 보게 하는 한 장
이 가이드가 답하려는 질문의 절반은 “모든 에이전트가 같은 목표를 갖게 하려면?”입니다. PARA 원문이 그 실마리를 줍니다. 원문의 핵심 원칙은 정보를 “지금 약속한 프로젝트와 목표”에 따라 정리하라는 것이고, 프로젝트는 처음부터 “어떤 목표를 두고 하는 일”로 정의됩니다. 또 원문은 영역만 늘어놓은 목록으로는 지금의 노력을 장기 목표에 잇지 못한다고 경고합니다. 목표가 적혀 있고, 그 목표에 묶인 프로젝트 목록이 눈앞에 있어야 진행이 보인다는 것입니다.
GOAL.md)을 만들고, 프로젝트 지침 파일 CLAUDE.md 에서 @GOAL.md 로 불러옵니다. 아래 사실 두 가지를 조합한 방법입니다.
- CLAUDE.md 는
@경로문법으로 다른 파일을 불러올 수 있고, 불러온 파일은 펼쳐져 그 CLAUDE.md 와 함께 컨텍스트에 들어갑니다(Claude Code 메모리 문서). - 에이전트 팀(리더 하나와 팀원 여럿이 함께 일하는 Claude Code 실험 기능)의 팀원은 생길 때 CLAUDE.md 를 읽고, 서브에이전트(맡긴 일을 자기 컨텍스트에서 하고 결과만 돌려주는 도우미)도 기본 제공 Explore·Plan 등 일부를 빼면 CLAUDE.md 를 읽습니다(에이전트 팀 · 서브에이전트 문서).
목표 문서에 무엇을 적을지는 원문의 원칙에서 끌어옵니다. 목표(무엇을 이루려 하나), 그 목표에 묶인 끝이 있는 프로젝트들, 끝났다고 말할 기준, 그리고 저장소를 읽어서는 알 수 없는 결정입니다. 아래 양식은 이 가이드가 만든 예시입니다.
# 팀 목표 (2026 4분기)
분기 보고서를 매주 자동으로 초안까지 만든다.
## 진행 중 프로젝트 — 끝이 있는 일만
- 보고서 양식 확정 → projects/q4-report/
- 데이터 수집 절차 정리 → 스킬로 옮길 예정
## 끝났다고 말할 기준
- 초안이 양식의 모든 칸을 채우고, 숫자마다 출처 링크가 있다
## 하지 않을 것
- 외부 메일 보내기 (사람이 직접)
## 정한 것 (저장소엔 없는 결정)
- 2026-11-03 회의: 보고서는 한국어로만
카파시의 LLM 위키 — AI 가 쓰고 고치는 지식 창고
지금까지는 사람의 세컨드 브레인 정리법을 에이전트용으로 옮겼습니다. 반대로 정리하는 일 자체를 AI 에게 맡기는 방법도 있습니다. 안드레 카파시(Andrej Karpathy)가 공개한 「LLM Wiki」 글이 말하는 LLM 위키(AI 가 원문을 읽고 마크다운 위키를 직접 쓰고 고쳐 가는 지식 창고 방식)입니다. 원문은 스스로를 “아이디어 파일”이라고 소개합니다. 자기 에이전트(원문 예: OpenAI Codex, Claude Code, OpenCode / Pi)에 그대로 붙여 넣도록 만든 글로, 큰 생각만 전하고 세부는 에이전트가 사용자와 함께 만들어 간다는 것입니다.
RAG 와 무엇이 다른가. 원문은 흔한 방식부터 짚습니다. 파일을 올려 두면 AI 가 질문을 받을 때마다 관련 조각을 찾아 답을 만드는 RAG(질문할 때마다 자료 더미에서 관련 부분을 찾아 답에 붙이는 방식, 8장)입니다. NotebookLM, ChatGPT 파일 올리기, 대부분의 RAG 시스템이 이렇게 동작한다고 원문은 말합니다. 이 방식도 되긴 하지만 AI 가 질문마다 지식을 처음부터 다시 찾아냅니다. 문서 다섯 개를 엮어야 하는 미묘한 질문이면 매번 조각을 찾아 다시 맞춰야 하고, 아무것도 쌓이지 않습니다.
LLM 위키에서는 새 원문이 들어오면 AI 가 나중에 찾으려고 색인만 해 두지 않습니다. 읽고 핵심을 뽑아 이미 있는 위키에 엮어 넣습니다. 관련된 쪽을 고치고, 주제 요약을 다시 쓰고, 새 자료가 옛 주장과 어긋나는 곳을 표시합니다. 지식을 한 번 정리해 두고 계속 최신으로 유지하는 것이지, 질문마다 다시 끌어내는 것이 아닙니다.
“the wiki is a persistent, compounding artifact.”
뜻: 위키는 사라지지 않고, 쓸수록 불어나는 결과물입니다. 서로 잇는 링크는 이미 있고, 모순은 이미 표시돼 있으며, 종합은 지금까지 읽은 모든 것을 반영합니다.
세 층. 원문은 구조를 세 층으로 나눕니다. 맨 아래 원문(raw sources)은 직접 골라 모은 글·논문·그림·데이터 파일입니다. 고치지 않는 기준 자료라서 AI 는 읽기만 하고 절대 바꾸지 않습니다. 가운데 위키(the wiki)는 AI 가 만든 마크다운 파일 폴더입니다. 요약, 대상별 쪽, 개념 쪽, 비교, 개요, 종합이 들어가며 이 층은 AI 가 전부 맡습니다 — 사람은 읽고, AI 가 씁니다. 그리고 스키마(the schema)는 위키의 구조·약속·작업 순서를 AI 에게 알려 주는 문서로, 원문 예는 Claude Code 의 CLAUDE.md, Codex 의 AGENTS.md 입니다.
세 작업 — 넣기 · 묻기 · 점검. 위키는 세 가지 일로 굴러갑니다. 아래 단계를 눌러 보세요.
두 특별 파일 — index.md 와 log.md. 위키가 커져도 AI(와 사람)가 길을 잃지 않게 두 파일을 둡니다. 쓰임이 다릅니다.
index.md — 내용 목차
위키의 모든 쪽을 링크 · 한 줄 요약(필요하면 날짜·원문 수)과 함께 갈래별로 적은 목록입니다. AI 는 넣기 때마다 고치고, 질문을 받으면 목차부터 읽고 관련 쪽으로 들어갑니다. 원문은 이것이 중간 규모(원문 약 100개, 위키 수백 쪽)에서 놀랄 만큼 잘 되며, 임베딩 기반 RAG(글을 숫자로 바꿔 비슷한 조각을 찾는 검색 장치)를 따로 갖추지 않아도 된다고 합니다.
log.md — 시간순 일지
넣기 · 묻기 · 점검이 언제 있었는지 덧붙이기만 하는 기록입니다. 위키가 어떻게 자라 왔는지 보여 주고, AI 가 최근에 무엇을 했는지 알게 해 줍니다. 원문 팁: 항목마다 같은 머리말로 시작하면 간단한 명령으로 읽을 수 있습니다.
## [2026-04-02] ingest | Article Title
원문 예시 그대로입니다. 그러면 grep "^## \[" log.md | tail -5 로 최근 다섯 항목을 볼 수 있습니다.
사람의 일과 AI 의 일. 원문은 위키를 사람이 직접 쓰는 일은 없다(또는 드물다)고 말합니다. 원문 저자는 한쪽에 AI 에이전트, 다른 쪽에 Obsidian(마크다운 메모 앱)을 띄워 두고, AI 가 대화에 따라 고친 결과를 실시간으로 훑어본다고 합니다. 그 비유가 “Obsidian is the IDE; the LLM is the programmer; the wiki is the codebase.”(뜻: Obsidian 은 작업 화면, AI 는 프로그래머, 위키는 코드입니다)입니다.
| 누가 | 맡는 일 (원문) |
|---|---|
| 사람 | 원문 고르기, 분석 방향 잡기, 좋은 질문 하기, 그 모든 것이 무슨 뜻인지 생각하기 |
| AI | 나머지 전부 — 요약, 상호 링크, 제자리에 넣기, 장부 정리 같은 잡일 |
왜 잘 되나. 원문은 지식 창고 관리에서 지루한 것은 읽거나 생각하는 일이 아니라 장부 정리라고 말합니다. 상호 링크 고치기, 요약을 최신으로 두기, 새 자료가 옛 주장과 어긋날 때 표시하기, 수십 쪽에 걸친 일관성 지키기입니다. 사람은 관리 부담이 가치보다 빨리 커져서 위키를 버리지만, AI 는 지루해하지 않고 링크 고치기를 잊지 않으며 한 번에 15개 파일을 고칠 수 있습니다. 원문은 이 생각이 배니바 부시의 메멕스(Memex, 1945 — 문서 사이에 연결 길을 낸 개인 지식 창고 구상)와 닮았고, 부시가 풀지 못한 “누가 관리하나”를 AI 가 맡는다고 덧붙입니다.
쓰임새. 원문이 드는 예입니다.
개인
목표·건강·심리·자기 계발을 일기·글·팟캐스트 메모로 쌓아, 나에 대한 정리된 그림을 만듭니다.
연구
몇 주·몇 달 한 주제를 파고들며 논문·글·보고서를 읽고, 생각(가설)을 키워 가는 위키를 만듭니다.
책 읽기
장마다 넣으며 인물·주제·줄거리 쪽을 만들어, 다 읽을 즈음 동반 위키가 생깁니다(원문 비유: 팬들이 몇 년간 만든 Tolkien Gateway 같은 위키).
회사 · 팀
Slack 대화, 회의록, 프로젝트 문서, 고객 통화로 채우고 AI 가 관리하는 사내 위키. 사람이 고친 내용을 검토하는 방식도 가능하다고 원문은 말합니다. 팀 누구도 하기 싫어하는 관리를 AI 가 하니 위키가 최신으로 남습니다.
이 밖에 경쟁 분석, 실사, 여행 계획, 강의 메모, 취미 탐구처럼 시간을 두고 지식을 모으며 흩어지지 않게 정리하고 싶은 모든 일에 쓸 수 있다고 원문은 말합니다.
아래 대응은 원문에 없는 이 가이드의 연결 방법입니다. 원문 층은 받아 둔 자료, 스키마는 지침 파일(3장), 위키는 PARA 와 함께 쓰는 팀 지식 창고, log.md 는 인수인계 노트(7장), 점검은 정기 점검(9장)에 대응합니다. 에이전트 팀이라면 여러 팀원이 같은 위키를 읽고, 쓰기는 한 명(또는 리더)이 맡기를 권합니다. 같은 파일을 여럿이 고치면 덮어쓰기 쉽기 때문입니다(6장).
- CODE(모으기 · 정리하기 · 추리기 · 표현하기)는 세컨드 브레인을 만들고 쓰는 네 단계입니다. 에이전트 팀에서는 “다시 찾을 수 없는 것만 모으고, 목표에 묶어 정리하고, 짧은 층과 긴 층으로 추리고, 세션마다 결과물을 남기는” 흐름이 됩니다.
- PARA 는 정보를 프로젝트 · 영역 · 자원 · 보관 네 칸으로, 주제가 아니라 실행 기준으로 나눕니다. 폴더 구조와 이름은 에이전트가 필요한 파일을 찾는 신호가 됩니다.
- 이 가이드는 팀 목표 문서(예시 이름
GOAL.md)를 짧게 쓰고 CLAUDE.md 에서@GOAL.md로 불러오기를 권합니다. 팀원과 다음 세션이 시작 때 함께 읽습니다. 다만 맥락일 뿐 강제는 아닙니다. - “미래의 나를 위한 메모”는 “다음 에이전트를 위한 메모”가 됩니다. 용어 풀이 · 멈춘 자리 · 관련 링크를 남깁니다.
- 개인 팀과 회사 팀의 공용 기억은 따로 두고, 오가는 길만 정해 둡니다.
- 카파시의 LLM 위키는 AI 가 원문을 읽어 위키를 쓰고 고치며 쌓아 갑니다. 원문 · 위키 · 스키마 세 층, 넣기 · 묻기 · 점검 세 작업.
이 장의 나머지 소절과 🔧 세부는 완전 가이드 2장에 있습니다.
항상 읽히는 층 — CLAUDE.md 와 AGENTS.md
팀 안의 모든 에이전트가 같은 목표와 맥락으로 일하게 만드는 가장 기본 도구는 지침 파일입니다. 사람이 써 두면 에이전트가 세션을 시작할 때마다 읽습니다. 이 장은 지침 파일을 어디에 두고, 어떻게 짧고 분명하게 쓰고, 안 읽힐 때 무엇을 확인하는지 다룹니다.
지침 파일이란 — 팀 전원이 매번 읽는 공용 기억
무엇인가 — Claude Code(Anthropic 이 만든, 글로 지시하면 파일을 읽고 고치고 명령을 실행하는 AI 에이전트 도구)의 세션은 늘 빈 컨텍스트 창에서 시작합니다. 컨텍스트(에이전트가 한 번에 보고 있는 글 전체)가 비어 있으니 어제 대화에서 정한 것을 오늘의 에이전트는 모릅니다. 원문은 세션을 넘어 지식을 이어 주는 장치를 두 가지로 설명합니다.
| CLAUDE.md (지침 파일) | 자동 메모리 (auto memory) | |
|---|---|---|
| 누가 쓰나 | 나(사람) | Claude 가 스스로 |
| 무엇이 들어가나 | 지시와 규칙 | 배운 점과 패턴 |
| 범위 | 프로젝트·사용자·조직 | 저장소마다(워크트리(같은 저장소를 여러 폴더에 펼친 작업용 복사본)끼리 공유) |
| 언제 읽히나 | 모든 세션 | 모든 세션(처음 200줄 또는 25KB 까지) |
| 쓰는 곳 | 작업 규칙, 일하는 순서, 프로젝트 구조 | 내 선호, 내가 바로잡아 준 것, 코드만 봐선 알 수 없는 사정 |
이 장은 왼쪽, 사람이 쓰는 지침 파일만 다룹니다. 자동 메모리는 5장에서 봅니다. 지침 파일은 마크다운(# 제목, - 목록처럼 간단한 기호로 꾸미는 글 형식)으로 쓴 보통 글 파일이고, Claude 는 매 세션 시작 때 이 파일을 읽습니다.
왜 "팀의 공용 기억"인가 — 에이전트 팀실험 기능에서도 같은 일이 일어납니다. 원문은 이렇게 적습니다.
뜻: 팀원은 만들어질 때 보통 세션과 같은 프로젝트 맥락 — CLAUDE.md, MCP 서버, 스킬 — 을 불러옵니다. 그리고 리더의 대화 기록은 넘어가지 않고, 리더가 준 생성 지시문(spawn prompt — 리더가 팀원을 만들 때 주는 첫 지시)만 받습니다.
주의할 점 — 강제 설정이 아니라 맥락 — 원문은 Claude 가 지침 파일을 "강제되는 설정이 아니라 맥락(context, not enforced configuration)"으로 다룬다고 분명히 적습니다. Claude 는 읽고 따르려 하지만 반드시 지킨다는 보장은 없습니다. 지시가 구체적이고 짧을수록 더 꾸준히 따릅니다.
permissions.deny)으로 겁니다. 이것들은 Claude 가 무엇을 판단하든 Claude Code 가 매번 적용합니다. 자세한 구분은 9장에서 다룹니다.범위 4종 — 누구와 나눌지에 따라 둘 곳이 다르다
무엇인가 — CLAUDE.md 는 한 곳에만 두는 파일이 아닙니다. 놓는 위치에 따라 범위(scope — 그 지침이 누구에게, 어느 프로젝트에 적용되는가)가 달라집니다. 원문의 표를 넓은 범위부터 좁은 범위 순으로 옮깁니다. 이 순서가 곧 읽히는 순서입니다.
| 범위 | 위치 | 무엇을 적나 (원문 예) | 누구와 공유 |
|---|---|---|---|
| 조직 Managed policy | macOS /Library/Application Support/ClaudeCode/CLAUDE.mdLinux·WSL /etc/claude-code/CLAUDE.mdWindows C:\Program Files\ClaudeCode\CLAUDE.md | 회사 코딩 기준, 보안 정책, 규정 준수 요구 | 조직의 모든 사용자 (IT·DevOps(개발·운영 담당 부서) 가 관리) |
| 사용자 User | ~/.claude/CLAUDE.md | 내 코드 스타일 선호, 개인 도구 단축 방법 | 나만 (모든 프로젝트) |
| 프로젝트 Project | ./CLAUDE.md 또는 ./.claude/CLAUDE.md | 프로젝트 구조, 작업 기준, 자주 하는 작업 순서 | 팀원 (버전 관리로 공유) |
| 로컬 Local | ./CLAUDE.local.md (.gitignore 에 추가) | 내 테스트용 주소, 내가 쓰는 시험 데이터 | 나만 (이 프로젝트만) |
~ 는 내 컴퓨터의 홈 폴더를 뜻합니다. "버전 관리로 공유"는 git(파일의 변경 이력을 기록하고 여러 사람이 함께 고치게 해 주는 도구) 저장소(프로젝트 파일과 그 이력이 담긴 폴더)에 파일을 올려 팀원도 같은 파일을 받는다는 뜻이고, .gitignore 는 "이 파일은 올리지 마"라고 적는 목록입니다.
개인 팀·회사 팀과 어떻게 이어지나 — 원문의 범위를 요청하신 두 팀에 맞춰 보면 아래처럼 나눌 수 있습니다. 어느 팀이든 팀 전원이 같은 목표를 갖게 하는 자리는 프로젝트 범위입니다. 팀원 에이전트가 시작할 때 불러오는 것이 바로 그 프로젝트의 맥락이기 때문입니다.
- 사용자 범위(
~/.claude/CLAUDE.md): 어떤 일을 하든 같은 내 선호 — 말투, 결과물 형식, 자주 쓰는 도구. - 프로젝트 범위: 개인 일 하나마다 폴더(저장소)를 만들고 그 폴더의
CLAUDE.md에 그 일의 목표와 규칙을 적습니다. 그 폴더에서 띄운 에이전트 팀은 모두 이 파일을 읽습니다. - 로컬 범위: 그 폴더 안에서도 남과 나누지 않을 메모(개인 주소, 시험용 데이터).
- 조직 범위: 회사가 정한 공통 기준. 관리자가 배포하며 개인이 뺄 수 없습니다(아래 「큰 팀」).
- 프로젝트 범위: 업무 저장소에 커밋한
CLAUDE.md— 동료와 동료의 에이전트까지 같은 목표·규칙을 읽습니다. - 사용자·로컬 범위: 회사 저장소에 올리면 안 되는 내 선호는 여기에. 개인 일의 지침이 회사 일에 섞이지 않도록 사용자 범위에는 "모든 일에 공통인 것"만 둡니다.
개인 팀과 회사 팀의 경계·보안은 9장에서 더 자세히 다룹니다.
잘 쓰는 법 — 짧고 구체적으로
언제 한 줄을 더하나 — 원문은 CLAUDE.md 를 "안 적으면 또 설명해야 할 것을 적어 두는 곳"이라고 말하고, 다음 네 경우에 더하라고 합니다.
Claude 가 같은 실수를 두 번째로 했을 때
코드 검토에서 이 프로젝트라면 알았어야 할 것이 걸렸을 때
지난 세션에 쳤던 정정·설명을 이번에도 치고 있을 때
새로 온 사람도 같은 맥락이 있어야 일할 수 있을 때
무엇을 적고 무엇을 다른 곳에 두나 — CLAUDE.md 는 매 세션 모든 일에 실리므로, 그 안의 한 줄 한 줄이 관련 없는 일에서도 Claude 의 주의를 조금씩 가져갑니다. 그래서 "매 세션 필요한 사실"만 남기고 나머지는 알맞은 곳으로 보냅니다.
구체적으로 쓰기 — 지침은 맥락일 뿐 강제가 아니므로, 확인할 수 있을 만큼 구체적으로 써야 잘 따릅니다. 원문 예를 옮깁니다.
| 흐릿한 지시 | 구체적인 지시 |
|---|---|
| Format code properly (코드를 잘 정리해) | Use 2-space indentation (들여쓰기는 공백 2칸) |
| Test your changes (바꾼 걸 시험해 봐) | Run npm test before committing(커밋 전에 npm test 실행) |
| Keep files organized (파일을 잘 정리해 둬) | API handlers live in src/api/handlers/(API 처리 코드는 src/api/handlers/ 에) |
짧고 정돈되게, 서로 부딪치지 않게 — 원문의 세 기준입니다.
- 크기: 파일당 200줄 아래를 목표로 합니다. 길수록 컨텍스트를 더 쓰고 지키는 정도가 떨어집니다.
- 구조: 관련 지시를 마크다운 제목과 목록으로 묶습니다. 빽빽한 문단보다 따르기 쉽습니다.
- 일관성: 두 지시가 서로 어긋나면 Claude 는 아무거나 하나를 고를 수 있습니다. 하위 폴더 지침과
.claude/rules/까지 가끔 훑어 낡은 것·충돌하는 것을 지웁니다.
# Commands - Install: pnpm install - Run one test file: pnpm vitest run path/to/file.test.ts - Typecheck: pnpm tsc --noEmit # Conventions - Use the error helpers in src/lib/errors.ts, never throw raw strings - src/legacy/ is still live but don't copy its patterns into new code # Gotchas - Integration tests need DATABASE_URL set, see .env.example
뜻: 명령(설치, 테스트 파일 하나 실행, 타입 검사) / 약속(오류는 src/lib/errors.ts 의 도우미로, src/legacy/ 는 아직 쓰이지만 그 방식을 새 코드에 따라 하지 말 것) / 함정(통합 테스트에는 DATABASE_URL 설정이 필요). 원문은 CLAUDE.md 에 코드만 봐서는 알 수 없는 것 — 확인 명령, 헷갈리게 생긴 곳, 저장소에 안 적힌 결정, 두 번 이상 바로잡은 것 — 만 두라고 합니다.
/init 을 실행하면 Claude 가 프로젝트를 살펴보고 빌드 명령·테스트 방법·약속을 담은 첫 CLAUDE.md 를 만들어 줍니다(이미 있으면 덮어쓰지 않고 고칠 점을 제안). 그다음 일은 대부분 줄을 지우는 것입니다. 따라 하기는 활용편 2.- 세션은 늘 빈 컨텍스트로 시작합니다. 사람이 쓴 지침 파일(CLAUDE.md)은 매 세션 시작 때 읽히고, 에이전트 팀의 팀원도 만들어질 때 프로젝트의 CLAUDE.md·MCP 서버·스킬을 불러옵니다 — 그래서 팀 전원의 공용 기억이 됩니다.
- 지침은 강제 설정이 아니라 맥락입니다. 반드시 막아야 할 것은 훅·권한 규칙·관리 설정으로 겁니다.
- 범위 4종: 조직(관리자 배포) · 사용자
~/.claude/CLAUDE.md(나만, 모든 프로젝트) · 프로젝트./CLAUDE.md(팀이 git 으로 공유) · 로컬./CLAUDE.local.md(나만, 이 프로젝트). 팀 전원이 같은 목표를 읽게 하는 자리는 프로젝트 범위입니다. - 찾은 파일은 덮어쓰지 않고 넓은 범위 → 좁은 범위, 위 폴더 → 작업 폴더 순으로 이어 붙습니다. 하위 폴더 지침은 그 폴더를 만질 때 읽힙니다.
- 잘 쓰기: 같은 정정을 두 번 하면 한 줄 더하기 · 확인할 수 있게 구체적으로 · 파일당 200줄 아래 · 충돌 정리. 일부 파일용은
.claude/rules/(paths), 여러 단계 절차는 스킬로. @경로가져오기는 정리에 좋지만 컨텍스트는 줄이지 않습니다. AGENTS.md 는 여러 도구가 함께 읽는 오픈 형식이며, CLAUDE.md 가 있으면@AGENTS.md로 가져옵니다.- 안 따를 때:
/context all로 읽혔는지 → 위치 → 구체성·충돌 → 훅이 맞는지./memory로 고치고,/doctor로 덜어 낼 것을 찾습니다.
이 장의 나머지 소절과 🔧 세부는 완전 가이드 3장에 있습니다.
필요할 때 읽히는 층 — 스킬
3장의 지침 파일은 매 세션 처음부터 읽힙니다. 그런데 팀의 배포 순서, 장애 대응 절차, 보고서 쓰는 법처럼 길지만 가끔 필요한 지식까지 거기에 넣으면 모든 일이 무거워집니다. 이런 것을 폴더로 묶어 필요할 때만 꺼내 읽히는 장치가 스킬입니다.
스킬이란 — 필요할 때만 펼치는 절차서
무엇인가 — 스킬(Skill — 절차나 지식을 SKILL.md 파일이 든 폴더로 묶어, 필요할 때만 불러오는 것)은 Claude 가 할 수 있는 일을 넓혀 줍니다. SKILL.md 에 지시를 적어 두면 Claude 가 그것을 자기 도구함에 넣고, 관련 있는 일이 오면 스스로 꺼내 쓰거나 내가 /스킬-이름 으로 바로 부릅니다.
왜 필요한가 — 원문은 이렇게 설명합니다. 더 뛰어난 모델은 공학 지식은 더 많이 알지만, 우리 팀이 출시를 어떻게 하는지, 장애 대응 문서에 무엇이 적혀 있는지, API 문서를 어떤 모양으로 쓰길 원하는지는 모릅니다. 그런 지식을 스킬에 담습니다. 그리고 CLAUDE.md 와 달리 스킬의 본문은 쓸 때만 읽히므로, 긴 참고 자료도 필요해지기 전까지는 컨텍스트(에이전트가 한 번에 보고 있는 글 전체)를 거의 쓰지 않습니다.
release 스킬의 본문 전체가 들어옵니다. 스킬 이름은 원문 예와 이 가이드의 예시를 섞은 것입니다.알아 둘 것
- 예전 "사용자 정의 명령"은 스킬로 합쳐졌습니다.
.claude/commands/deploy.md파일과.claude/skills/deploy/SKILL.md스킬은 둘 다/deploy를 만들고 똑같이 동작합니다. 스킬은 여기에 보조 파일 폴더, 누가 부를지 정하는 설정, Claude 가 알아서 불러오는 기능을 더합니다. - 여러 AI 도구가 함께 쓰는 표준: Claude Code 스킬은 Agent Skills 오픈 표준을 따르고, 그 위에 몇 가지 기능을 더했습니다.
- 처음부터 들어 있는 스킬:
/doctor,/code-review,/batch,/debug,/loop,/claude-api같은 내장 스킬(bundled skills)이 있고, 내가 만든 스킬과 같은 방법으로 부릅니다.
언제 무엇에 — CLAUDE.md · 규칙 · 스킬 · 훅
스킬을 만들 때 — 원문이 꼽는 신호는 두 가지입니다. ① 같은 지시·체크리스트·여러 단계 절차를 채팅에 계속 붙여 넣고 있을 때, ② CLAUDE.md 의 한 부분이 "사실"이 아니라 "절차"로 커졌을 때입니다.
paths 규칙은 맞는 파일을 만진 뒤부터, 스킬은 평소엔 얇은 설명만 있다가 필요해진 순간 본문이 들어옵니다. 훅은 컨텍스트가 아니라 Claude Code 가 정해진 순간마다 직접 실행합니다.| 적고 싶은 것 | 둘 곳 | 이유 (원문) |
|---|---|---|
| 모든 세션에 필요한 사실 — 확인 명령, 약속, 폴더 구조, "항상 X" | CLAUDE.md | 매 세션 읽혀야 하는 것만 둔다 |
| 일부 폴더·파일에만 해당하는 규칙 | .claude/rules/ (paths) | 맞는 파일을 다룰 때만 읽힌다 |
| 여러 단계 절차, 팀 고유의 방법, 긴 참고 자료 | 스킬 | 본문은 쓸 때만 읽혀 관련 없는 일을 무겁게 하지 않는다 |
| 예외 없이 지켜야 하는 것 | 훅 · 권한 규칙 | Claude 의 판단과 상관없이 매번 적용된다 |
팀에게 왜 중요한가 — 에이전트 팀실험 기능의 팀원은 만들어질 때 CLAUDE.md·MCP 서버와 함께 스킬도 불러옵니다(원문 agent-teams). 그래서 프로젝트에 스킬을 두면 리더와 팀원이 같은 절차서를 펼쳐 일하게 됩니다.
- 스킬은 절차·지식을
SKILL.md가 든 폴더로 묶은 것입니다. 평소 컨텍스트에는 이름과 설명만 있고, 본문은 쓸 때만 읽힙니다 — 매 세션 전부 읽히는 CLAUDE.md 와 다른 점입니다. - 같은 지시·체크리스트·여러 단계 절차를 계속 붙여 넣거나, CLAUDE.md 의 한 부분이 절차로 커졌다면 스킬로 옮깁니다. 매 세션 필요한 사실은 CLAUDE.md, 일부 파일용은 규칙, 반드시 지킬 것은 훅.
- 만들기: 폴더 +
SKILL.md(앞머리description+ 본문 지시). 짧게, 500줄 아래, 긴 자료는 보조 파일로. - 둘 곳: 기업 · 개인
~/.claude/skills/· 프로젝트.claude/skills/(커밋하면 팀 공유) · 플러그인. 같은 이름이면 기업 > 개인 > 프로젝트. - 부르기: 메시지 맨 앞
/이름으로 직접, 또는 Claude 가 설명을 보고 자동으로. 되돌리기 어려운 일은disable-model-invocation: true로 나만 부르게. - 에이전트 팀의 팀원도 만들어질 때 프로젝트·사용자 스킬을 불러오므로, 팀 공용 절차는 프로젝트 스킬로 두면 모두가 같은 방법으로 일합니다.
- 안 불리면 설명의 단어부터 고칩니다. 중간에 잊으면 계속 지킬 지시로 고쳐 쓰거나 다시 부르고, 꼭 지킬 것은 훅으로.
이 장의 나머지 소절과 🔧 세부는 완전 가이드 4장에 있습니다.
스스로 쌓는 기억 — 자동 메모리 · 메모리 도구
3장의 지침 파일은 사람이 쓰는 기억입니다. 이 장은 반대로 에이전트가 스스로 적는 기억을 다룹니다. Claude Code 의 자동 메모리, 역할마다 따로 두는 서브에이전트 기억, 그리고 개발자가 자기 에이전트를 만들 때 쓰는 Claude API 메모리 도구까지 — 팀의 세컨드 브레인에 "일하면서 배운 것"이 쌓이는 길을 살펴봅니다.
자동 메모리 — Claude 가 스스로 적는 메모
Claude Code 의 모든 세션은 빈 컨텍스트(에이전트가 한 번에 보고 있는 글 전체) 창으로 시작합니다. 원문은 세션을 넘어 지식을 이어 주는 장치를 두 가지로 설명합니다 — 사람이 쓰는 CLAUDE.md 와 Claude 가 쓰는 자동 메모리입니다. 두 장치 모두 대화가 시작될 때마다 읽힙니다.
| CLAUDE.md (지침 파일) | 자동 메모리 | |
|---|---|---|
| 누가 쓰나 | 나(사람) | Claude |
| 무엇이 들어가나 | 지시와 규칙 | 배운 것과 패턴 |
| 범위 | 프로젝트·사용자·조직 | 저장소마다 하나, 워크트리(같은 저장소를 여러 폴더에 펼쳐 둔 작업용 복사본)끼리 공유 |
| 언제 읽히나 | 매 세션 | 매 세션 (처음 200줄 또는 25KB 까지) |
| 어디에 쓰나 | 코딩 규칙, 작업 순서, 프로젝트 구조 | 내 선호, 내가 Claude 에게 한 교정, 코드만 봐서는 알 수 없는 프로젝트 사정 |
무엇을 적고, 무엇을 건너뛰나
Claude 는 일하면서 네 종류의 메모를 남기고, 메모 파일 머리말(frontmatter — 파일 맨 위 --- 사이에 적는 설정 칸)의 type 칸에 종류를 적습니다.
user · 사람
나의 역할, 전문 분야, 일하는 방식의 선호.
feedback · 교정
내가 Claude 에게 바로잡아 준 것, "그 방법 좋다"고 확인해 준 접근.
project · 진행 상황
진행 중인 일, 마감, 결정 — 코드나 git 기록에서 알 수 없는 것.
reference · 찾을 곳
프로젝트 밖 정보가 있는 곳 — 이슈 트래커, 대시보드 등.
반대로 코드에서 알아낼 수 있는 것(구조, 파일 경로, 디버깅(오류를 찾아 고치는 일)해서 고친 내용)과 CLAUDE.md 에 이미 적힌 것은 건너뜁니다. 또 매 세션 무언가를 적지는 않습니다 — "다음 대화에서 쓸모가 있을까"를 기준으로 적을지 정합니다. 화면에 Saved 2 memories Recalled 2 memories 같은 알림이 뜨면 지금 기억을 쓰거나 읽고 있다는 뜻입니다.
기억 점검·편집 — /memory
자동 메모리 파일은 평범한 마크다운(Markdown — #·- 같은 기호로 제목·목록을 표시하는 글 형식) 파일이라 언제든 직접 열어 고치거나 지울 수 있습니다. 세션 안에서 /memory 를 실행하면 기억 파일을 한곳에서 둘러보고 엽니다.
원문이 설명하는 /memory 의 기능은 다음과 같습니다.
- 사용자·프로젝트 범위의 CLAUDE.md, CLAUDE.local.md, 그 밖의 기억 파일 위치를 보여 줍니다. 아직 없는 사용자·프로젝트 CLAUDE.md 도 목록에 나오고, 고르면 새로 만든 뒤 엽니다.
- 자동 메모리를 켜고 끄는 스위치, 자동 메모리 폴더를 여는 항목이 있습니다.
- 파일을 고르면 편집기로 열립니다. VS Code 같은 창 편집기는 따로 열려 세션을 계속 쓸 수 있고, Vim 같은 터미널 편집기는 닫을 때까지 터미널을 차지합니다.
"기억해" vs "CLAUDE.md 에 적어"
| 이렇게 말하면 | 저장되는 곳 |
|---|---|
| "always use pnpm, not npm" 뜻: 항상 npm 말고 pnpm 을 써 "remember that the API tests require a local Redis instance" 뜻: API 테스트에는 로컬 Redis 가 필요하다는 걸 기억해 | 자동 메모리 (Claude 가 적음) |
| "add this to CLAUDE.md" 뜻: 이걸 CLAUDE.md 에 추가해 — 또는 /memory 로 직접 편집 | CLAUDE.md (지침 파일) |
/memory→ 자동 메모리 폴더를 열어MEMORY.md색인을 읽습니다.- 팀 전체가 알아야 할 내용이 개인 기억에 숨어 있으면 지침 파일로 옮깁니다("add this to CLAUDE.md").
- 틀렸거나 낡은 메모는 지웁니다. 파일의
modified시각이 판단에 도움이 됩니다.
/memory 에서 자동 메모리 폴더를 골라 둘러보기 — 을 제시합니다.
Claude API 메모리 도구 — 파일로 기억하는 내 에이전트
여기까지는 Claude Code 안의 기능이었습니다. 메모리 도구(memory tool)는 개발자가 Claude API(프로그램이 Claude 를 직접 부르는 연결 창구)로 자기 에이전트를 만들 때 붙이는 도구입니다. Claude 가 기억 파일 폴더에 파일을 만들고·읽고·고치고·지워, 대화가 끝나도 남는 지식을 쌓습니다. 모든 것을 컨텍스트 창에 넣어 두지 않아도 됩니다.
이 소절은 개발자용입니다. Claude Code 나 Claude 프로젝트만 쓴다면 “직접 만든 에이전트도 파일 폴더로 기억을 이어 간다”는 것만 알고 보안으로 넘어가도 됩니다.
메모리 도구는 클라이언트 쪽(client-side)에서 돌아갑니다. Claude 는 "이 파일 보여 줘", "이 파일 만들어 줘" 하고 요청만 하고, 그 요청을 실제 저장소에서 실행해 결과를 돌려주는 것은 내 애플리케이션입니다. 그래서 데이터를 어디에·어떻게 둘지 내가 정합니다. /memories 는 앞머리 경로일 뿐이고, 내 처리기(handler — 요청을 받아 실제로 실행하는 코드)가 이를 사용자별 폴더나 데이터베이스 키 같은 실제 저장소에 연결합니다.
/memories 폴더 안으로 제한해야 합니다.한 번의 흐름 — 고객 문의 답장 예
1. 사용자 요청 — "Help me respond to this customer service ticket." 뜻: 이 고객 문의에 답장하도록 도와줘.
2. Claude 가 기억 폴더부터 확인 — 메모리 도구가 켜져 있으면 Claude 는 일을 시작하기 전에 자동으로 기억 폴더를 봅니다.
{ "type": "tool_use", "name": "memory",
"input": { "command": "view", "path": "/memories" } }3. 내 앱이 폴더 내용을 돌려줌 — /memories/customer_service_guidelines.xml, /memories/refund_policies.xml 두 파일이 있다고 알려 줍니다.
4. 필요한 파일을 읽음 — view 로 응대 지침 파일을 열어 "고객을 이름으로 부를 것", "공감하는 말투" 같은 내용을 확인합니다.
{ "command": "view", "path": "/memories/customer_service_guidelines.xml" }5. 기억을 바탕으로 답함 — "Based on your customer service guidelines, I can help you craft a response…" 뜻: 저장된 응대 지침에 따라 답장 작성을 돕겠습니다.
시작하기 — 두 단계
- 요청에 도구 추가요청의
tools에{"type": "memory_20250818", "name": "memory"}를 넣는 것이 설정의 전부입니다. 이름은 반드시memory, 입력 형식은 따로 정의하지 않습니다. - 처리기 구현메모리 명령마다 클라이언트 쪽 처리기를 만듭니다.
/memories밖의 경로는 반드시 거절해야 하므로 아래 보안을 먼저 읽습니다.
도구를 넣으면 API 가 시스템 프롬프트에 "무엇보다 먼저 기억 폴더를 보라, 진행하면서 상태·진행·생각을 기억에 적어라"는 지시를 자동으로 덧붙입니다. 그 안의 한 줄이 이 도구의 정신을 잘 보여 줍니다 — "ASSUME INTERRUPTION"(뜻: 중단될 것을 가정하라 — 컨텍스트 창은 언제든 초기화될 수 있으니, 기억 폴더에 적지 않은 진행은 잃을 수 있다).
압축과 함께 쓰기
압축(compaction — 대화가 길어지면 오래된 부분을 요약해 줄이는 것)은 컨텍스트를 작게 유지하고, 메모리는 요약을 거쳐도 반드시 살아남아야 할 정보를 지킵니다. 원문은 오래 도는 에이전트에 둘 다 쓰기를 권합니다.
여러 세션에 걸친 일
첫 세션이 진행 기록·기능 목록을 먼저 만들고, 이후 세션은 그것을 읽고 시작하며, 끝날 때 갱신하는 패턴이 있습니다. 자세한 내용은 7장 인수인계 노트에서 다룹니다.
- 자동 메모리는 Claude 가 스스로 적는 메모(사람·교정·진행 상황·찾을 곳 네 종류)입니다. 지침 파일(사람이 씀)과 구분합니다.
- 저장소마다
~/.claude/projects/<project>/memory/하나 — 워크트리끼리 공유, 이 컴퓨터에만 있음. 시작 때MEMORY.md처음 200줄 또는 25KB 만 읽고, 주제 파일은 필요할 때 읽습니다. /memory로 기억 파일을 보고·고치고·자동 메모리를 켜고 끕니다. "기억해"는 자동 메모리로, "CLAUDE.md 에 추가해"는 지침 파일로 갑니다.- 서브에이전트는 메인의 자동 메모리를 받지 않습니다. 역할 파일에
memory: project(권장 기본)·user·local을 적으면 역할마다 자기 기억이 생깁니다. - Claude API 메모리 도구는
/memories파일 폴더로 대화를 넘어 기억합니다. Claude 는 요청만, 실행·저장은 내 애플리케이션이 합니다. - 보안: 비밀 정보 거르기, 크기 한도, 오래된 기억 지우기,
/memories밖 경로 막기. 기억은 강제 설정이 아니라 맥락이라, 꼭 막을 것은 훅으로.
이 장의 나머지 소절과 🔧 세부는 완전 가이드 5장에 있습니다.
팀 꾸리기 — 서브에이전트와 에이전트 팀
이제 여러 에이전트를 한 팀으로 묶을 차례입니다. 역할을 파일 하나로 정의하고, 그 역할을 서브에이전트나 팀원으로 불러 씁니다. 이 장의 핵심 질문은 "새로 생긴 팀원은 무엇을 알고 시작하나"입니다 — 그 답이 왜 팀에 세컨드 브레인이 필요한지를 보여 줍니다.
역할 정의 — 한 번 쓰고 여러 번 쓰기
역할 정의 파일은 .claude/agents/<이름>.md 같은 마크다운 파일입니다. 맨 위 --- 사이 머리말에 이름·설명·도구 같은 설정을 적고, 그 아래 본문이 그 역할의 시스템 프롬프트(에이전트에게 맨 먼저 주어지는 기본 지시문)가 됩니다. 꼭 필요한 칸은 name(이름)과 description(언제 이 역할에게 맡길지)뿐입니다.
---
name: code-reviewer
description: Reviews code for quality and best practices
tools: Read, Glob, Grep
model: sonnet
---
You are a code reviewer. When invoked, analyze the code and provide
specific, actionable feedback on quality, security, and best practices.
뜻: 이름 code-reviewer, "코드 품질·모범 관행을 검토함", 쓸 도구는 읽기·찾기(Read, Glob, Grep)만, 모델은 sonnet. 본문 — "너는 코드 검토자다. 불려 오면 코드를 분석해 품질·보안·모범 관행에 대해 구체적이고 실행할 수 있는 의견을 줘라."
어디에 두나 — 누가 쓸 수 있는가
파일을 둔 위치가 "누가 이 역할을 쓸 수 있는지"를 정합니다. 같은 이름이 여러 곳에 있으면 우선순위가 높은 쪽이 이깁니다.
| 위치 | 범위 | 우선순위 |
|---|---|---|
| 관리 설정(managed settings) | 조직 전체 — 관리자가 배포 | 1 (가장 높음) |
--agents 실행 옵션 | 이번 세션만(디스크에 저장 안 됨) | 2 |
.claude/agents/ | 이 프로젝트 — 저장소에 올려 팀이 함께 씀 | 3 |
~/.claude/agents/ | 내 모든 프로젝트 — 개인용 | 4 |
플러그인의 agents/ | 플러그인을 켠 곳 | 5 (가장 낮음) |
.claude/agents/)을 버전 관리에 올려 팀이 함께 쓰고 고치라고 권합니다. 그래서 회사 팀의 역할(예시 이름: reviewer, researcher)은 회사 저장소의 .claude/agents/ 에, 내 개인 업무에서만 쓰는 역할은 ~/.claude/agents/ 에 두면 범위가 자연스럽게 나뉩니다. 범위 전반은 9장에서 다룹니다.
에이전트 팀 — 리더와 팀원 실험 기능
에이전트 팀은 Claude Code 세션 여럿을 한 팀으로 움직이는 기능입니다. 세션 하나가 리더(team lead)가 되어 일을 나누고 맡기고 결과를 모읍니다. 팀원(teammate)은 각자 자기 컨텍스트 창에서 따로 일하면서 서로 직접 메시지를 주고받습니다. 나도 리더를 거치지 않고 어느 팀원에게나 바로 말할 수 있습니다. 원문은 이 기능이 실험 기능이며 기본으로 꺼져 있다고 밝힙니다.
언제 쓰나
원문은 나란히 탐색하는 것이 실제로 가치를 더할 때 가장 효과적이라고 합니다. 가장 강한 쓰임은 넷입니다 — 여럿이 다른 측면을 조사하고 서로의 결과를 따져 보는 조사·검토, 각자 다른 조각을 맡는 새 모듈·기능, 서로 다른 가설을 동시에 시험하는 디버깅, 화면·서버·테스트를 각각 맡는 여러 층에 걸친 변경. 반대로 순서대로 해야 하는 일, 같은 파일을 고치는 일, 서로 얽힌 일이 많으면 한 세션이나 서브에이전트가 낫습니다. 팀은 조율에 드는 수고가 있고, 한 세션보다 토큰을 훨씬 많이 씁니다.
시작하기 — 말로 부탁하기
기능을 켠 뒤, 할 일과 원하는 팀원을 자연어로 설명하면 Claude 가 팀원을 만들고 조율합니다.
I'm designing a CLI tool that helps developers track TODO comments across
their codebase. Spawn three teammates to explore this from different angles:
one on UX, one on technical architecture, one playing devil's advocate.
뜻: 코드 속 TODO 주석을 추적하는 CLI 도구를 설계하고 있어. 팀원 셋을 만들어 다른 각도에서 살펴봐 — 하나는 사용 경험, 하나는 기술 구조, 하나는 일부러 반대 의견을 내는 역할.
작업은 대기·진행 중·완료 세 상태이고, 다른 작업에 기대는 작업은 앞 작업이 끝날 때까지 막힘으로 보입니다. 리더가 직접 배정하거나, 팀원이 일을 끝낸 뒤 배정 안 된·막히지 않은 다음 작업을 스스로 집어 갑니다(동시에 집지 않도록 파일 잠금을 씀). 팀원을 끝낼 때는 이름으로 부탁합니다 — "Ask the researcher teammate to shut down"(뜻: researcher 팀원에게 종료하라고 해).
팀원이 시작 때 받는 것 — 그래서 세컨드 브레인이 필요합니다
이 가이드가 답하려는 질문 — "팀 안의 모든 에이전트가 같은 목표와 맥락을 갖게 하려면?" — 의 열쇠가 이 소절입니다. 원문은 팀원이 만들어질 때 받는 것을 분명히 적어 둡니다.
팀원이 받는 것
- 일반 세션과 같은 프로젝트 맥락 — CLAUDE.md, MCP 서버, 스킬
- 리더가 준 생성 지시문
- 리더가 정해 준 이름 — 누구에게나 이름으로 메시지 가능
팀원이 받지 못하는 것
- 리더의 대화 기록 — 리더가 나와 나눈 이야기, 이미 읽은 파일
- (서브에이전트의 경우) 메인 대화의 자동 메모리, 이미 부른 스킬, 출력 스타일 — 대신 CLAUDE.md 와 Claude 가 쓴 위임 메시지를 받습니다
리더와 오래 이야기해 정한 목표도, 팀원에게는 파일에 적혀 있거나 생성 지시문에 들어 있지 않으면 없는 것입니다. 원문 사실(팀원은 CLAUDE.md·MCP·스킬을 읽는다)을 뒤집어 보면, 팀 전체가 공유해야 할 목표·용어·결정은 모두가 시작 때 읽는 파일에 두면 된다는 뜻이 됩니다. 이것이 이 가이드가 말하는 세컨드 브레인 — 팀이 함께 읽고 쓰는 공용 기억 파일 묶음 — 입니다.
- 항상 알아야 할 것(팀 목표 한 단락, 지켜야 할 규칙, 용어): 프로젝트 CLAUDE.md 또는 그 CLAUDE.md 가 가져오는 파일(예시 이름
GOAL.md) — 3장. - 필요할 때 꺼낼 것(절차, 참고 지식): 스킬 — 4장.
- 이번 일에만 필요한 것(맡은 파일, 마감, 출력 형식): 생성 지시문 — 다음 소절.
vendor/ 폴더는 무시").
- 역할 정의 파일(
.claude/agents/<이름>.md, 필수 칸은name·description)을 한 번 쓰면 서브에이전트로도, 에이전트 팀의 팀원으로도 씁니다. 프로젝트 폴더에 두면 팀이 함께,~/.claude/agents/에 두면 나만 씁니다. - 서브에이전트는 자기 컨텍스트에서 일하고 요약만 돌려줍니다 — 긴 출력 격리, 나란히 조사, 차례로 잇기.
- 에이전트 팀실험 기능은 리더 1 + 팀원 여럿이 공유 작업 목록과 메시지로 협업합니다. 토큰을 훨씬 많이 쓰므로 나란히 탐색이 가치 있는 일에.
- 팀원이 시작 때 받는 것은 CLAUDE.md·MCP 서버·스킬 + 생성 지시문뿐, 리더의 대화 기록은 넘어가지 않습니다. 그래서 팀 목표·맥락은 대화가 아니라 모두가 읽는 파일(세컨드 브레인)에 둡니다.
- 생성 지시문에는 목표·출력 형식·도구와 출처·작업 경계를 넣습니다. 팀원마다 다른 파일을 맡깁니다.
- 팀은 대부분 3~5명으로 시작하고, 팀원당 작업 5~6개. 패턴은 가장 단순한 것부터.
- 한계: 이어 열면 팀원이 안 돌아옴, 세션당 팀 하나, 팀 안의 팀 없음, 리더 고정. 팀원은 내 대신 권한을 승인할 수 없습니다.
이 장의 나머지 소절과 🔧 세부는 완전 가이드 6장에 있습니다.
이어 달리기 — 인수인계 노트와 긴 작업
몇 시간, 며칠짜리 일은 한 세션 안에 끝나지 않습니다. 새 세션은 앞 세션이 한 일을 전혀 모른 채 시작합니다. 이 장은 다음 세션·다른 에이전트가 바통을 이어받을 수 있게 인수인계 노트를 남기는 방법을 다룹니다. 세컨드 브레인에서 "지금 어디까지 왔나"를 맡는 층입니다.
긴 작업의 문제 — 새 세션은 앞 일을 모른다
에이전트는 세션(에이전트를 한 번 켜서 끌 때까지의 작업 한 판) 단위로 일하고, 새 세션은 앞 세션의 기억 없이 시작합니다. 컨텍스트 창(에이전트가 한 번에 담을 수 있는 글의 한도)에는 한도가 있고, 복잡한 일은 창 하나 안에 끝나지 않습니다. 그래서 세션과 세션 사이에 다리가 필요합니다.
압축만으로는 부족했다
Claude Agent SDK(Anthropic 이 만든, 에이전트를 직접 만들 때 쓰는 도구 모음)에는 압축(compaction — 대화가 길어지면 앞부분을 요약해 창을 비우는 기능, 1장)이 있습니다. 이론상 그러면 끝없이 일할 수 있을 것 같지만, 원문 실험에서는 "claude.ai 를 똑같이 만들어 줘" 같은 큰 지시 하나만으로는 제품 수준의 웹 앱을 완성하지 못했습니다. 압축이 다음 에이전트에게 늘 완벽하게 분명한 지시를 넘겨주지는 않기 때문입니다.
실패 1 — 한 번에 다 하려 함
앱 전체를 한 번에 만들려다 구현 도중 컨텍스트가 바닥납니다. 다음 세션은 반쯤 만들어지고 기록도 없는 기능을 물려받아, 무슨 일이 있었는지 추측하고 기본 동작을 되살리는 데 시간을 씁니다.
실패 2 — 너무 일찍 "다 했다"
일이 꽤 진행된 뒤, 새 세션이 둘러보고 진척이 있는 것을 보고는 일이 끝났다고 선언해 버립니다. 남은 일이 무엇인지 알려 주는 목록이 없어서입니다.
원문은 이 문제를 둘로 나눕니다. ① 처음에 모든 기능의 토대가 될 환경을 준비해 한 단계씩 일하게 만들고, ② 매 세션이 목표를 향해 조금씩 나아가되 끝날 때는 깨끗한 상태로 두게 하는 것입니다. "깨끗한 상태"란 큰 버그가 없고 정리·기록이 되어 있어, 다음 사람이 엉뚱한 뒷정리 없이 바로 새 일을 시작할 수 있는 상태를 말합니다.
진행 기록 파일과 git — 다음 사람을 위한 메모
원문의 해결책은 두 가지 역할입니다. 맨 처음 세션만 다른 지시를 받아 환경을 준비하고, 그 뒤의 모든 세션은 조금씩 일하고 기록을 남깁니다. 원문 각주에 따르면 둘은 첫 지시만 다를 뿐, 시스템 프롬프트·도구·하네스(에이전트를 감싸 도구 사용과 반복 실행을 맡는 틀)는 똑같습니다.
| 남기는 것 | 하는 일 |
|---|---|
claude-progress.txt | 에이전트들이 한 일을 적어 두는 기록 파일. 각 세션이 끝날 때 진행 요약을 씁니다. |
| git 기록 | git(파일이 어떻게 바뀌었는지 이력을 저장하는 도구)에 설명이 붙은 커밋(변경 묶음 하나를 이력에 저장하는 일)을 남깁니다. 잘못된 변경을 되돌리고 잘 돌아가던 상태로 돌아갈 수 있습니다. |
feature_list.json | 해야 할 기능 전체 목록과 각 기능의 통과 여부(다음 소절). |
init.sh | 개발 서버(만든 앱을 내 컴퓨터에서 미리 띄워 보는 프로그램)를 켜는 스크립트. 다음 세션이 "앱을 어떻게 실행하지?"를 헤매지 않게 합니다. |
원문의 핵심 통찰은 새 컨텍스트 창으로 시작한 에이전트가 작업 상태를 빨리 파악하게 하는 것이었고, 그것을 claude-progress.txt 와 git 기록이 해냈습니다. 원문은 이 방법을 "유능한 엔지니어가 매일 하는 일"에서 가져왔다고 말합니다 — 퇴근 전에 커밋하고 메모를 남기는 습관입니다. 덕분에 에이전트가 무슨 일이 있었는지 추측하며 시간을 버리지 않게 되었습니다.
# claude-progress.txt (예시 양식 — 원문에 정해진 양식 없음)
2026-11-10 세션 3
- 한 일: 3번 기능(로그인 화면) 끝, 브라우저로 직접 확인함 → feature_list 통과로 바꿈
- 커밋: "로그인 화면 추가"
- 다음: 4번 기능(비밀번호 찾기). 서버는 ./init.sh 로 켬
- 주의: 테스트 계정은 CLAUDE.local.md 에 있음
세션 시작 루틴 — 매번 같은 순서로 상태 파악
준비물이 갖춰지면, 모든 코딩 에이전트는 일을 시작하기 전에 정해진 순서로 "현재 위치"부터 확인하라는 지시를 받습니다. 아주 기본적인 단계도 있지만 그래도 도움이 됩니다. 원문은 이 덕분에 매 세션 "코드를 어떻게 시험하지?"를 알아내는 데 드는 토큰(AI 가 읽고 쓰는 글의 양을 세는 단위 — 비용·속도의 기준)을 아낀다고 말합니다.
1. 지금 어느 폴더인지 확인
pwd(지금 있는 폴더 위치를 보여 주는 명령)를 실행합니다. 원문 지시: "이 폴더 안의 파일만 고칠 수 있다."
2. 진행 기록과 git 로그 읽기
claude-progress.txt 와 git 기록(git log --oneline -20 — 최근 커밋 20개를 한 줄씩)을 읽어 최근에 무엇을 했는지 따라잡습니다.
3. 기능 목록에서 하나 고르기
feature_list.json 을 읽고 아직 안 된 것 중 가장 우선순위가 높은 기능 하나를 고릅니다.
4. 앱을 켜고 기본 동작부터 시험
init.sh 로 개발 서버를 켜고, 새 기능에 손대기 전에 기본 end-to-end 시험(사용자처럼 처음부터 끝까지 실제로 써 보는 시험)을 돌립니다. claude.ai 복제 예에서는 늘 새 채팅을 열고 메시지를 보내 답을 받아 봤습니다. 앱이 망가진 채 남겨져 있었다면 바로 고칩니다 — 그대로 새 기능을 시작하면 문제가 더 커지기 때문입니다.
5. 기능 하나 → 끝날 때 커밋과 기록
고른 기능 하나를 만들고 직접 시험한 뒤에만 통과로 바꿉니다. 세션을 끝낼 때 git 커밋과 진행 기록 갱신을 남깁니다. 이것이 다음 세션의 1~2단계가 읽을 노트가 됩니다.
원문은 실제 세션 첫머리가 대체로 이렇게 흘러간다고 보여 줍니다(아래 화면 흉내는 원문 대화를 옮기고 뜻을 단 것입니다).
[Assistant] I'll start by getting my bearings and understanding the current state of the project.
뜻: 먼저 현재 위치와 프로젝트 상태부터 파악하겠습니다.
[Tool Use] <bash - pwd> · <read - claude-progress.txt> · <read - feature_list.json>
뜻: 폴더 확인 → 진행 기록 읽기 → 기능 목록 읽기
[Tool Use] <bash - git log --oneline -20>
뜻: 최근 작업 기록 보기
[Assistant] Now let me check if there's an init.sh script to restart the servers.
뜻: 서버를 다시 켤 init.sh 가 있는지 보고 개발 서버를 켭니다.
[Assistant] … verify that some fundamental features are still working.
뜻: 기본 기능이 아직 잘 되는지 확인한 뒤 → 다음 기능 작업 시작
CLAUDE.md(3장)에 "세션을 시작하면 진행 기록과 git 로그를 먼저 읽는다" 같은 짧은 줄을 두면 같은 효과를 노릴 수 있습니다. 다만 지침 파일은 강제 설정이 아니라 맥락이므로, 반드시 지켜야 하는 확인은 9장 「반드시 막을 것」의 방법을 씁니다.서브에이전트 결과는 파일로 — "전화 게임" 줄이기
여러 에이전트가 함께 일할 때도 인수인계가 생깁니다. 서브에이전트(메인 에이전트가 맡긴 일을 자기 컨텍스트에서 하고 결과만 돌려주는 도우미, 6장)가 찾아낸 것을 지휘 에이전트(일을 나누고 모으는 역할)에게 말로 전하고, 지휘 에이전트가 다시 정리해 전하면 — 말이 건너갈 때마다 내용이 조금씩 빠집니다. 원문(Anthropic 멀티 에이전트 연구 시스템)은 이것을 "전화 게임"(귓속말 전달 놀이)이라고 부릅니다.
결과는 파일로
서브에이전트가 도구로 결과를 바깥 저장소(파일)에 저장하고, 지휘 에이전트에게는 가벼운 참조만 돌려줍니다. 여러 단계를 거치며 정보가 새는 것을 막고, 큰 결과를 대화 기록으로 복사하는 토큰도 줄입니다. 코드·보고서·데이터 시각화처럼 모양이 정해진 결과물에 특히 잘 맞습니다.
계획은 메모리에
원문의 지휘 연구 에이전트는 먼저 접근 방법을 생각한 뒤 계획을 메모리에 저장합니다. 컨텍스트 창이 200,000 토큰을 넘으면 잘려 나가므로, 계획만은 꼭 남겨 두려는 것입니다.
단계가 끝나면 요약해 보관
대화가 수백 턴(주고받기 한 번)에 이르면, 끝난 작업 단계를 요약해 바깥 메모리에 저장하고 다음 일로 넘어갑니다. 한도가 다가오면 깨끗한 컨텍스트의 새 서브에이전트를 띄우고 신중하게 인수인계해 흐름을 잇습니다.
outputs/)은 이 가이드의 예시 이름입니다. 에이전트 팀이라면 두 팀원이 같은 파일을 고치면 덮어쓰기가 생기므로, 원문(agent-teams)대로 팀원마다 맡는 파일을 나눕니다.- 새 세션은 앞 세션을 기억하지 못합니다. 압축만으로는 부족하고, 파일로 남긴 인수인계 노트가 세션 사이의 다리입니다.
- 첫 세션은 진행 기록(
claude-progress.txt)·기능 목록(feature_list.json)·init.sh·첫 git 커밋을 준비합니다. - 기능 목록은 전부 "실패"로 시작하고, 통과 여부 칸만 바꾸며, 끝까지 확인한 뒤에만 통과로 바꿉니다.
- 매 세션: 폴더 확인 → 기록·git 로그 읽기 → 기능 하나 고르기 → 앱을 켜고 기본 시험 → 일 → 커밋과 기록 갱신.
- 메모리 도구도 같은 패턴(첫 세션 준비 → 매 세션 읽기 → 끝날 때 갱신)이며, "언제든 끊긴다고 가정하라"가 핵심입니다.
- 여러 에이전트는 결과를 파일로 남기고 경로만 주고받아 "전화 게임"의 손실을 줄입니다.
이 장의 나머지 소절과 🔧 세부는 완전 가이드 7장에 있습니다.
바깥 지식 잇기 — MCP 와 Claude 프로젝트
팀의 지식은 폴더 안 파일에만 있지 않습니다. 일정표·문서 도구·이슈 관리·데이터베이스에도 흩어져 있지요. 이 장은 에이전트가 그런 바깥 도구를 직접 읽고 쓰게 잇는 표준 MCP와, 코딩을 하지 않는 팀이 지식·지침을 한곳에 묶어 함께 쓰는 Claude 프로젝트를 다룹니다.
MCP 란 — AI 앱용 USB-C 포트
MCP(Model Context Protocol — AI 앱을 외부 도구·데이터에 잇는 표준 연결 방식)는 AI 애플리케이션을 바깥 시스템에 연결하는 오픈소스 표준입니다. Claude 나 ChatGPT 같은 AI 앱이 MCP 로 데이터(로컬 파일·데이터베이스), 도구(검색 엔진·계산기), 워크플로(일의 정해진 순서 — 원문 예: 전문 프롬프트)에 연결해 필요한 정보에 닿고 일을 해낼 수 있습니다.
MCP 로 할 수 있는 일 (원문 예)
개인 비서
에이전트가 내 Google Calendar 와 Notion 에 접근해 더 개인화된 AI 비서가 됩니다.
디자인 → 앱
Claude Code 가 Figma 디자인을 보고 웹 앱 전체를 만들 수 있습니다.
회사 데이터
사내 챗봇이 조직의 여러 데이터베이스에 연결해, 사용자가 대화로 데이터를 분석합니다.
이슈 → 작업
Claude Code 에 "JIRA 이슈 ENG-4521 의 기능을 구현하고 GitHub 에 PR 을 만들어 줘"처럼 맡깁니다. (JIRA 는 업무 이슈 관리 도구, PR 은 코드 변경을 검토받는 요청)
누구에게 좋은가 (원문)
| 입장 | MCP 가 주는 것 |
|---|---|
| 개발자 | AI 앱·에이전트를 만들거나 연동할 때 개발 시간과 복잡도가 줄어듦 |
| AI 앱·에이전트 | 데이터 원천·도구·앱의 생태계에 닿아 할 수 있는 일이 늘어남 |
| 최종 사용자 | 내 데이터에 접근하고, 필요하면 나 대신 행동하는 더 유능한 AI 앱 |
언제 연결하나. Claude Code 문서의 기준은 간단합니다: 이슈 관리 도구나 모니터링 화면 같은 다른 도구의 내용을 채팅에 복사해 붙이고 있다면 그 도구의 서버를 연결할 때입니다. 연결하면 Claude 가 내가 붙여 넣은 조각이 아니라 그 시스템을 직접 읽고 다룹니다.
MCP 서버를 둘 범위 — 나만 · 이 프로젝트 팀 · 내 모든 프로젝트
Claude Code 에서 MCP 서버는 세 가지 범위(scope — 그 설정이 어디까지 적용되고 누구와 나눠지는지) 중 하나에 둡니다. 범위가 정하는 것은 두 가지입니다: 어느 프로젝트에서 켜지나, 그리고 팀과 나눠지나.
| 범위 | 켜지는 곳 | 팀과 공유 | 저장 위치 | 쓰기 좋은 곳(원문) |
|---|---|---|---|---|
| 로컬 (local, 기본값) | 지금 프로젝트만 | 아니오 | ~/.claude.json | 개인 개발용 서버, 실험 설정, 버전 관리에 넣고 싶지 않은 비밀 정보가 든 서버 |
| 프로젝트 (project) | 지금 프로젝트만 | 예 — 버전 관리로 | 프로젝트 맨 위 폴더의 .mcp.json | 팀이 함께 쓰는 도구·서비스 |
| 사용자 (user) | 내 모든 프로젝트 | 아니오 | ~/.claude.json | 여러 프로젝트에서 자주 쓰는 개인 도구 |
.mcp.json)가 기본 짝입니다.겹칠 때의 순서. 같은 서버가 여러 곳에 정의되어 있으면 Claude Code 는 한 번만 연결하고, 가장 우선순위가 높은 곳의 정의 전체를 씁니다(범위끼리 칸을 섞지 않음). 순서는 로컬 → 프로젝트 → 사용자 → 플러그인이 준 서버 → claude.ai 커넥터이고, 조직이 관리 설정(managedMcpServers)으로 제공한 서버는 이 모두보다 위입니다.
~/.claude.json 에 저장되고, 일반 로컬 설정은 프로젝트 폴더의 .claude/settings.local.json 에 있습니다.Claude 프로젝트 — 코딩 안 하는 팀의 공용 지식 공간
터미널이나 저장소를 쓰지 않는 팀이라면 claude.ai 의 프로젝트가 세컨드 브레인 역할을 합니다. 프로젝트는 자기만의 대화 기록과 지식 창고를 가진 독립된 작업 공간입니다. 프로젝트마다 문서를 올리고, 맥락을 주고, 그 주제에 집중한 대화를 Claude 와 나눕니다. 무료 계정을 포함한 모든 사용자가 쓸 수 있고, 무료 사용자는 프로젝트를 최대 5개까지 만듭니다.
프로젝트 지식
관련 문서·글·코드·파일을 프로젝트의 지식 창고에 올리면, Claude 가 그 프로젝트 안의 각 대화에서 맥락과 배경을 이해하는 데 씁니다.
프로젝트 지침
프로젝트마다 지침을 정해 답을 맞춥니다. 예: 더 격식 있는 말투로, 또는 특정 역할·업계의 관점에서 답하게.
팀과 공유하기 (Team · Enterprise 요금제만)
| 항목 | 내용 |
|---|---|
| 권한 — Can view(보기) | 프로젝트 내용·지식·지침을 보고 프로젝트 안에서 대화할 수 있지만 고칠 수는 없음 |
| 권한 — Can edit(편집) | 지침과 지식을 고치고, 멤버를 추가·삭제하고, 멤버 설정을 바꾸고, 함께 기여 |
| 공유 방법 | 이메일로 특정 팀원에게 / 이메일 목록으로 여러 명 한꺼번에 / 조직 전체에 (만들 때나 나중에) |
| 찾기·알림 | 남이 공유한 프로젝트는 Shared with me(나와 공유됨) 탭에서 찾고, 공유되면 이메일 알림 |
| 관리 | 만든 사람은 권한을 바꾸거나 접근을 뺄 수 있음. 여러 멤버가 같은 프로젝트에 문서를 보태고 대화를 만들며 함께 일함 |
- MCP 는 AI 앱을 데이터·도구·워크플로에 잇는 오픈 표준, "AI 앱용 USB-C 포트"입니다. 다른 도구 내용을 채팅에 복사하고 있다면 연결할 때입니다.
- Claude Code 의 MCP 범위: 로컬(나·이 프로젝트, 기본값) · 프로젝트(
.mcp.json, 버전 관리로 팀 공유) · 사용자(나·모든 프로젝트). - 회사 팀은
.mcp.json을 커밋해 모두 같은 도구를 쓰고, 팀원은 처음 쓸 때 승인합니다. 에이전트 팀원도 같은 MCP 서버를 불러옵니다. - 서버는 믿을 수 있는지 먼저 확인합니다(프롬프트 주입 위험).
- 코딩 안 하는 팀은 Claude 프로젝트: 프로젝트 지식 + 프로젝트 지침 + 대화. Team·Enterprise 에서 Can view / Can edit 로 공유합니다.
- 지식이 한도에 다가오면 유료 요금제의 프로젝트는 RAG 로 자동 전환해 최대 10배까지 담습니다.
이 장의 나머지 소절과 🔧 세부는 완전 가이드 8장에 있습니다.
개인 팀과 회사 팀 — 범위 · 보안 · 관리
이 가이드가 처음에 던진 질문으로 돌아옵니다: 개인 일을 하는 에이전트 팀과 회사 일을 하는 에이전트 팀을 따로 꾸리되, 각 팀 안에서는 모든 에이전트가 같은 목표와 맥락을 갖게 하려면? 열쇠는 앞 장들의 파일을 어느 범위에 두느냐입니다. 그리고 반드시 지켜야 할 규칙·비밀 정보·오래된 기억을 어떻게 관리하는지도 다룹니다.
개인 팀과 회사 팀을 어떻게 나누나 — 범위로 나눈다
Claude Code 의 지침 파일·스킬·역할 정의·MCP 서버·설정은 모두 어디에 저장하느냐에 따라 적용 범위(scope — 그 파일이 어느 프로젝트에서 읽히고 누구와 나눠지는지)가 정해집니다. 원문의 범위는 넷입니다.
아래 표는 앞 장들에서 본 것을 범위별로 모은 것입니다(경로는 원문 그대로).
| 범위 | 지침 파일 (3장) | 스킬 (4장) | 역할 정의 · 서브에이전트 메모리 (5·6장) | MCP (8장) | 함께 쓰는 사람 |
|---|---|---|---|---|---|
| 조직 | 관리형 CLAUDE.md (예: macOS /Library/Application Support/ClaudeCode/CLAUDE.md) | 관리 설정 폴더의 .claude/skills/ | 관리 설정으로 배포한 역할(우선순위 1) | 관리 설정으로 제공(managedMcpServers) | 조직의 모든 사용자 |
| 사용자 | ~/.claude/CLAUDE.md · ~/.claude/rules/ | ~/.claude/skills/ | ~/.claude/agents/ · ~/.claude/agent-memory/<이름>/ | 사용자 범위(~/.claude.json) | 나만 (모든 프로젝트) |
| 프로젝트 | ./CLAUDE.md · ./.claude/CLAUDE.md · .claude/rules/ · AGENTS.md | .claude/skills/ | .claude/agents/ · .claude/agent-memory/<이름>/ | 프로젝트 범위(.mcp.json) | 버전 관리로 팀원 모두 |
| 로컬 | ./CLAUDE.local.md (.gitignore 에 추가) | — | .claude/agent-memory-local/<이름>/ | 로컬 범위(~/.claude.json, 기본값) | 나만 (이 프로젝트) |
~/.claude/projects/<project>/memory/)이고 그 컴퓨터에만 있습니다. 같은 저장소의 워크트리(한 저장소를 여러 작업 폴더로 동시에 펼친 것)끼리는 나눠 쓰지만, 다른 컴퓨터나 클라우드 환경과는 공유되지 않습니다. 팀이 함께 봐야 할 사실은 자동 메모리가 아니라 저장소의 파일에 적습니다.~/.claude/)는 원문대로 "내 모든 프로젝트"에 읽히므로, 회사 저장소에서 일할 때도 읽힙니다. 그래서 사용자 범위에는 어디서 읽혀도 괜찮은 공통 선호만 두고, 개인 팀의 목표·개인 일정 같은 것은 개인용 폴더의 프로젝트 지침에 둡니다.개인 팀 구성 예 — 사용자 범위 + 개인용 폴더
개인 일을 하는 에이전트 팀의 세컨드 브레인을 이 가이드는 이렇게 꾸리기를 제안합니다. 폴더 이름 my-brain/(활용편과 같은 예시), 파일 이름 GOAL.md 와 PARA 폴더 이름은 이 가이드의 예시 이름이고, 나머지 경로(~/.claude/…, CLAUDE.md, .claude/agents/, claude-progress.txt 등)는 원문 이름입니다.
1. 사용자 범위에 공통 선호
~/.claude/CLAUDE.md 는 원문 기준 "모든 프로젝트에 쓰이는 개인 선호"(코드 스타일 선호, 개인 도구 단축 등) 자리입니다. 주제별로 나누려면 ~/.claude/rules/ 에 preferences.md·workflows.md 처럼 둡니다. 원문은 사용자 규칙이 프로젝트 규칙보다 먼저 읽히고, 둘이 충돌하면 어느 쪽을 따를지 모르니 일관되게 유지하라고 합니다.
2. 개인용 폴더 하나를 개인 팀의 본부로
폴더 하나를 만들고 그 안 CLAUDE.md 에 개인 팀의 목표 파일을 @GOAL.md 처럼 불러오게(import) 적습니다. 불러온 파일은 그 CLAUDE.md 와 함께 컨텍스트에 들어갑니다. 지식 창고는 PARA(2장)로 정리합니다.
3. 역할을 정의하고 팀을 띄우기
개인 팀의 역할(예: 조사 담당, 일정 정리 담당)을 그 폴더의 .claude/agents/ 에 두거나, 여러 개인 폴더에서 쓰려면 ~/.claude/agents/ 에 둡니다. 에이전트 팀의 팀원은 만들어질 때 일반 세션과 같은 CLAUDE.md·MCP 서버·스킬을 불러오므로, 그 폴더에서 띄운 팀원 모두가 같은 목표를 읽습니다. 리더의 대화 기록은 넘어가지 않으니, 생성 지시문(spawn prompt — 리더가 팀원을 만들 때 주는 첫 지시)에 그 일만의 맥락을 담습니다(6장).
4. 바깥 도구는 사용자·로컬 범위 MCP
개인 일정·메모 앱처럼 나만 쓰는 도구는 MCP 사용자 범위(모든 프로젝트) 또는 로컬 범위(이 폴더만)에 둡니다. 원문은 버전 관리에 넣고 싶지 않은 비밀 정보가 든 서버에 로컬 범위를 권합니다.
5. 긴 일은 인수인계 노트로
며칠 걸리는 개인 프로젝트는 진행 기록 파일과 할 일 목록을 두고, 세션을 시작할 때 읽게 합니다(7장).
회사 팀 구성 예 — 회사 저장소 + 조직 범위
회사 일을 하는 팀은 세컨드 브레인을 모두가 받는 곳, 즉 회사 저장소(프로젝트 범위)에 둡니다. 원문은 프로젝트 지침을 "버전 관리로 팀원과 공유하는 지침"(프로젝트 구조, 코딩 표준, 공통 작업 방식)이라고 설명합니다. 아래 구성은 이 가이드의 제안이고, 경로와 기능은 원문 그대로입니다.
조직 층
관리형 CLAUDE.md 는 그 컴퓨터의 모든 사용자에게, 어느 저장소에서든 적용됩니다. 개발자가 claudeMdExcludes 로 다른 지침 파일은 뺄 수 있어도 이것은 못 뺍니다. 원문 예: 회사 코딩 표준, 보안 정책, 규정 준수 요구.
회사 저장소 층
팀 지침·규칙·스킬·역할 정의를 저장소에 커밋해 함께 고칩니다. 원문은 프로젝트 역할 정의(.claude/agents/)를 버전 관리에 넣어 팀이 함께 쓰고 다듬으라고, 서브에이전트 메모리는 project 범위를 기본으로 권합니다.
나의 로컬 층
CLAUDE.local.md 는 이 프로젝트에서 나만 쓰는 선호(내 샌드박스(마음껏 시험해도 되는 따로 떼어 둔 환경) 주소, 즐겨 쓰는 테스트 데이터) 자리입니다. .gitignore 에 넣어 커밋되지 않게 합니다.
코딩 안 하는 팀
Claude 프로젝트 하나를 팀의 공용 공간으로 두고, Team·Enterprise 요금제에서 Can view / Can edit 권한으로 공유합니다(8장).
- 회사 저장소
CLAUDE.md맨 위에 팀 목표 한 단락(또는 목표 파일을@로 불러오기). 원문 권장대로 파일당 200줄 아래로 짧게. - 여러 도구(Claude Code 외)를 함께 쓴다면
AGENTS.md를 기준 문서로 두는 방법(3장). - 공용 도구는
.mcp.json, 공용 절차는.claude/skills/, 역할은.claude/agents/로 — 모두 커밋. - 반드시 지켜야 할 것은 지침이 아니라
.claude/settings.json의 권한 규칙·훅으로(다음 소절).
반드시 지킬 규칙은 강제 장치로 — 지침은 맥락일 뿐
원문이 여러 번 강조하는 사실입니다: Claude 는 CLAUDE.md 와 자동 메모리를 맥락으로 다루지, 강제 설정으로 다루지 않습니다. 거의 언제나 따르지만, 아무리 세게 적어도 그 줄을 이번에 따를지는 결국 Claude 의 판단입니다. 그래서 Claude Code 문서는 지시를 두 종류로 나눕니다.
| 장치 | 무엇을 하나 (원문) | 예 |
|---|---|---|
| 훅(hook — Claude 의 작업 흐름 중 정해진 순간에 내 명령을 자동 실행하는 장치) | 도구 사용 전후, Claude 가 멈추려 할 때, 세션 시작 때 등에 실행. 진짜 강제는 command·http 훅으로(prompt·agent 훅은 다른 모델이 판단하므로 강제가 아님) | 파일을 고칠 때마다 서식 정리 실행, migrations/ 폴더 수정 막기 |
| 권한 규칙 | 무엇을 실행·읽기·가져오기 할 수 있는지 정함. deny 규칙은 자동 모드·bypassPermissions 를 포함한 모든 권한 모드에서 유지 | .env 읽기 막기 |
| 샌드박스 | 운영체제 수준에서 셸 명령의 파일·네트워크 접근을 가둠(/sandbox) | 보안 관련이면 권한 규칙과 함께 |
| 관리 설정 | 조직이 배포. 어떤 개인 설정 파일도 덮어쓸 수 없어 보안팀 정책의 유일한 자리 | 특정 도구·명령·경로 막기, 로그인 방식 제한 |
에이전트 팀의 권한 — 팀원은 내 대신 승인할 수 없다
- 새 팀원은 리더의 권한 모드로 시작합니다(
bypassPermissions포함). 만들 때 팀원마다 다른 모드를 줄 수 없습니다 — 리더를 위험한 모드로 띄우면 팀원도 같다는 뜻입니다. - 권한 요청이 너무 자주 리더에게 올라오면, 팀원을 띄우기 전에 자주 쓰는 작업을 권한 설정에서 미리 허용해 둡니다.
- 팀의 품질 관문은 훅으로:
TeammateIdle(팀원이 쉬려 할 때),TaskCreated(작업이 만들어질 때),TaskCompleted(작업이 완료 표시될 때). 훅 명령이 종료 코드 2(명령이 끝나며 돌려주는 숫자 — 2는 “막음” 신호)로 끝나면 그 동작을 막고 되돌려 보낼 수 있습니다.
- 범위는 넷: 조직(관리형, 모든 사용자) · 사용자(
~/.claude/, 나·모든 프로젝트) · 프로젝트(저장소, 버전 관리로 팀) · 로컬(CLAUDE.local.md, 나·이 프로젝트). 넓은 범위부터 읽힙니다. - 이 가이드의 제안: 개인 팀 = 사용자 범위 + 개인용 폴더, 회사 팀 = 회사 저장소 + 조직 범위, 회사 일 속 나만의 메모 = 로컬. 사용자 범위는 회사 저장소에서도 읽히니 공통 선호만.
- 에이전트 팀의 팀원은 CLAUDE.md·MCP 서버·스킬을 불러오므로, 같은 폴더(저장소)에서 띄우면 같은 맥락을 갖습니다.
- 지침 파일은 맥락일 뿐입니다. 예외가 없어야 할 규칙은 훅·권한 deny·관리 설정으로, 그리고 강제 목록은 작게.
- 팀원은 내 대신 승인할 수 없고, 리더의 권한 모드로 시작합니다. 메모리·MCP 설정에 비밀 정보를 두지 않습니다.
- 쌓기 → 점검(
/doctor prompt-audit) → 정리(200줄 아래, 충돌 없애기) → 보관(끝난 것은 Archives)을 되풀이합니다.
이 장의 나머지 소절과 🔧 세부는 완전 가이드 9장에 있습니다.