에이전트 팀 모두가
같은 목표와 맥락으로 일하게 하는 공용 기억
이 가이드는 한 가지 질문에 답합니다. “개인 일을 하는 에이전트 팀, 회사 일을 하는 에이전트 팀을 따로 꾸리되, 팀 안의 모든 에이전트가 같은 목표와 맥락을 갖게 하려면 무엇을 어떻게 준비하나?” 답은 팀이 함께 읽고 쓰는 세컨드 브레인, 곧 에이전트들이 일을 시작할 때마다 읽고, 일하면서 고쳐 쓰는 공용 기억 파일 묶음입니다.
문제 — 에이전트는 어제를 기억하지 못하고, 팀원은 리더의 대화를 모릅니다
사람으로 이루어진 팀은 회의록이 없어도 어느 정도 굴러갑니다. 각자 머릿속에 어제 회의, 지난주 결정, 팀장의 말버릇이 남아 있기 때문입니다. 에이전트 팀은 다릅니다. 원문은 두 가지 사실을 분명히 적고 있습니다.
① 세션마다 처음부터 시작합니다. Claude Code 문서는 “모든 세션은 새 컨텍스트 창에서 시작한다”고 적습니다. 컨텍스트(에이전트가 한 번에 보고 있는 글 전체)가 비어 있으니, 어제 함께 정한 것도 오늘은 모릅니다. 긴 작업에 관한 Anthropic 글은 이를 교대 근무 비유로 설명합니다. 새로 온 기술자가 앞 근무조의 일을 하나도 기억하지 못하는 소프트웨어 팀을 떠올려 보라는 것입니다.
② 팀원은 리더의 대화를 물려받지 않습니다. 에이전트 팀(리더 하나와 팀원 여럿이 함께 일하는 Claude Code 기능) 문서에 따르면, 팀원은 생겨날 때 보통 세션과 같은 프로젝트 맥락(CLAUDE.md · MCP 서버 · 스킬)을 읽고, 리더에게서 생성 지시문(spawn prompt — 리더가 팀원을 만들 때 주는 첫 지시)을 받습니다. 그러나 리더의 대화 기록은 넘어가지 않습니다. 서브에이전트(맡긴 일을 자기 컨텍스트에서 하고 결과만 돌려주는 도우미)도 마찬가지로 내 대화 기록을 보지 못하고, 맡길 때 쓴 지시문에서 출발합니다.
| 새로 시작하는 에이전트가 | 받는 것 | 받지 못하는 것 |
|---|---|---|
| 다음 세션 | 지침 파일(CLAUDE.md 등), 자동 메모리, 열어 보는 파일 | 지난 세션의 대화·생각 과정 |
| 에이전트 팀의 팀원 | CLAUDE.md · MCP 서버 · 스킬 + 생성 지시문 | 리더의 대화 기록 |
| 서브에이전트 | 자기 지시문 + 맡긴 일 설명 + CLAUDE.md(기본 제공 Explore·Plan 은 빼고 시작) | 내 대화 기록, 이미 읽은 파일, 이미 불러온 스킬 |
결국 파일에 적어 두지 않은 목표와 맥락은 팀에 퍼지지 않습니다. Claude Code 모범 사례 문서도 세션이 기대와 다르게 흘러가는 첫 번째 이유로 “저장소를 읽어서는 알 수 없는 정보가 빠졌거나, 같은 사실을 매 세션 다시 찾아야 하는 경우”를 꼽습니다. 회의에서 정한 결정, 한 사람 머릿속에만 있는 배포 절차 같은 것들입니다.
원문 그대로 — 무엇이 넘어가고 무엇이 안 넘어가나
- Claude Code 메모리 문서: “Each Claude Code session begins with a fresh context window.” 세션을 넘어 지식을 옮기는 장치는 두 가지 — 사람이 쓰는 CLAUDE.md 파일과 Claude 가 스스로 쓰는 자동 메모리.
- 에이전트 팀 문서(Context and communication): “When spawned, a teammate loads the same project context as a regular session: CLAUDE.md, MCP servers, and skills. … A teammate also receives the spawn prompt from the lead. The lead's conversation history does not carry over.”
- 서브에이전트 문서(What loads at startup): 서브에이전트는 새로 격리된 컨텍스트 창에서 시작하며 대화 기록·이미 불러온 스킬·이미 읽은 파일을 보지 못합니다. 예외는 포크(fork)로, 부모 대화를 물려받습니다. 기본 제공 Explore·Plan 은 CLAUDE.md 없이 시작하고, 정의 파일에
omitClaudeMd를 둔 서브에이전트도 그렇습니다.
생각 — 기억을 머릿속이 아니라, 모두가 펼쳐 보는 파일에 둡니다
세컨드 브레인(Second Brain)은 원래 사람을 위한 말입니다. 이 말을 널리 알린 Forte Labs 의 티아고 포르테는 “우리 뇌는 생각을 떠올리는 곳이지, 보관하는 곳이 아니다”라고 말합니다. 그래서 배운 것과 그 출처를 뇌 바깥의 한곳에 모아 둔 디지털 창고를 만들자고 합니다. 이것이 세컨드 브레인의 원뜻입니다. 위키백과는 이런 활동을 개인 지식 관리(PKM — 한 사람이 지식을 모으고, 분류하고, 저장하고, 찾고, 나누는 과정)라고 부릅니다.
이 가이드는 이 말을 넓혀 씁니다. 여기서 세컨드 브레인은 에이전트 팀이 함께 읽고 쓰는 공용 기억(파일 묶음)입니다. 사람 한 명의 메모장이 아니라, 리더·팀원·다음 세션이 모두 같은 곳을 보는 팀 노트입니다. 원뜻과 넓힌 뜻을 섞지 않도록 이후 장에서는 원래 개념을 말할 때 “Forte Labs 의 세컨드 브레인”이라고 출처를 붙입니다.
이 넓힌 뜻은 억지가 아닙니다. Anthropic 의 컨텍스트 엔지니어링 글은 에이전트가 정보를 다루는 좋은 방식을 사람의 기억법에 빗댑니다. 사람은 자료 전체를 외우지 않고, 파일 시스템·받은편지함·책갈피 같은 바깥 정리 체계를 두고 필요할 때 꺼내 봅니다. 에이전트도 파일 경로 같은 가벼운 “찾아가는 표시”만 들고 있다가 필요할 때 읽어 오는 편이 낫다는 것입니다. 사람의 세컨드 브레인을 잘 짜는 원칙이 에이전트의 공용 기억에도 그대로 통하는 이유입니다(2장).
한 장 그림 — 공용 기억을 가운데 두고 두 팀이 읽고 씁니다
아래 그림이 이 가이드 전체의 지도입니다. 가운데 공용 기억은 다섯 층으로 나뉩니다. 층을 나누는 기준은 “언제 에이전트의 컨텍스트에 들어오나”입니다. 컨텍스트는 한도가 있고 많이 넣을수록 흐려지므로(1장), 무엇이든 항상 넣지 않고 꼭 필요한 것만 항상 읽히게 합니다.
층마다 “언제 읽히나”와 “누가 쓰나”가 다릅니다. 이 표의 사실은 모두 원문 기준이며, 자세한 내용은 표 오른쪽 장에서 다룹니다.
| 층 | 무엇 | 언제 컨텍스트에 들어오나 | 누가 쓰나 | 장 |
|---|---|---|---|---|
| ① 항상 읽힘 | CLAUDE.md · AGENTS.md 같은 지침 파일 | 매 세션 시작 때. 팀원·서브에이전트도 대부분 읽음 | 사람 | 3장 |
| ② 필요할 때 | 스킬(절차·지식을 폴더로 묶어 필요할 때만 불러오는 것), 주제별 자료 폴더 | 스킬 본문은 쓸 때만. 자료는 에이전트가 찾아 읽을 때만 | 사람 | 4장 · 2장 |
| ③ 스스로 쌓음 | 자동 메모리 · 메모리 도구 | 자동 메모리는 매 세션 시작 때 처음 200줄 또는 25KB 까지 | Claude | 5장 |
| ④ 인수인계 | 진행 기록(claude-progress.txt 등) · 기능 목록 | 새 세션이 시작하며 읽도록 지시해 둠 | 에이전트(사람이 양식을 정함) | 7장 |
| ⑤ 바깥 연결 | MCP(AI 앱을 외부 도구·데이터에 잇는 표준 연결 방식) · Claude 프로젝트 지식 | 도구를 부르거나 자료를 찾을 때 | 사람이 연결 | 8장 |
~/.claude/CLAUDE.md 는 “나만, 모든 프로젝트에”, 프로젝트 범위 ./CLAUDE.md 는 버전 관리로 “팀과 함께”, 조직 범위(managed policy)는 IT 가 관리해 “조직 전원에게” 적용됩니다. 이 가이드는 개인 팀은 사용자 범위와 개인 폴더에, 회사 팀은 회사 저장소의 프로젝트 범위와 조직 범위에 공용 기억을 두기를 권합니다. 이렇게 하면 두 팀의 맥락이 서로 섞이지 않습니다. 자세한 나누는 법과 보안은 9장에서 다룹니다.
이 가이드의 구성
앞쪽 두 장은 “왜 이런 구조가 필요한가”, 가운데 장들은 층 하나씩, 뒤쪽 장은 팀 꾸리기와 운영입니다. 처음이라면 1 → 2 → 3장 순서를, 바로 팀을 띄우고 싶다면 3 → 6장을 먼저 보세요.
직접 따라 하기
활용편 — 시작 준비와 실습 10개. 팀 목표 한 장 쓰기부터 에이전트 팀 띄우기, 막혔을 때 고치기까지.
먼저 알아 두면 좋은 용어
가이드 전체에서 자주 나오는 말입니다. 별표 8개만 알아도 대부분 따라갈 수 있습니다. 각 장에서도 처음 나올 때 괄호로 다시 풉니다.
| 용어 | 쉬운 풀이 |
|---|---|
| ⭐ 에이전트 | 도구를 스스로 골라 쓰며 일을 반복해 나가는 AI. 원문 정의는 “루프 안에서 도구를 자율적으로 쓰는 언어 모델”. 이 가이드의 기준 예는 Claude Code. |
| ⭐ 세션 | 에이전트 하나가 켜져서 대화하고 일하는 한 번의 흐름. 새 세션은 빈 컨텍스트로 시작합니다. |
| ⭐ 컨텍스트(맥락) | 에이전트가 지금 보고 있는 글 전체 — 지침, 대화, 도구 결과, 읽은 파일 내용. |
| ⭐ 컨텍스트 창 | 컨텍스트를 한 번에 담을 수 있는 한도. 책상 넓이에 비유할 수 있습니다. |
| ⭐ 토큰 | AI 가 읽고 쓰는 글의 양을 세는 단위. 비용과 속도의 기준이 됩니다. |
| ⭐ 세컨드 브레인 | 원뜻(Forte Labs)은 “한 사람의 디지털 지식 창고”. 이 가이드에서는 “에이전트 팀이 함께 읽고 쓰는 공용 기억(파일 묶음)”. |
| ⭐ 지침 파일 | CLAUDE.md · AGENTS.md 처럼 매 세션 시작 때 읽히는, 사람이 쓴 파일. 강제 설정이 아니라 “읽고 판단하는 맥락”입니다. |
| ⭐ 서브에이전트 · 에이전트 팀 | 서브에이전트는 맡긴 일을 자기 컨텍스트에서 하고 결과만 돌려주는 도우미. 에이전트 팀은 리더 하나와 팀원 여럿이 공유 작업 목록·메시지로 함께 일하는 Claude Code 기능 실험 기능. |
용어 22개 더 보기 — 읽다가 모르는 말이 나오면 여기서 찾으세요
컨텍스트 · 기억 · 역할
| 용어 | 쉬운 풀이 |
|---|---|
| 주의력 예산 | attention budget. 모델이 많은 글을 읽을 때 쓰는 집중력의 한도. 글이 하나 늘 때마다 조금씩 줄어듭니다. |
| 컨텍스트 썩음 | context rot. 컨텍스트에 글이 많아질수록 그 안의 내용을 정확히 떠올리는 힘이 떨어지는 현상. |
| 압축 | compaction. 대화가 한도에 가까워지면 요약해 그 요약으로 새로 시작하는 것. Claude Code 명령은 /compact. |
| 구조화된 메모 | structured note-taking. 에이전트가 컨텍스트 창 바깥 파일(예: NOTES.md)에 메모를 남기고 나중에 다시 읽는 방법. |
| 필요할 때 불러오기 | just in time. 자료 전체를 미리 넣지 않고 파일 경로 같은 표시만 들고 있다가 그때그때 읽어 오는 방식. |
| 자동 메모리 | auto memory. Claude 가 내 수정·선호를 보고 스스로 적는 메모. 사람이 쓰는 지침 파일과 다릅니다. |
| 메모리 도구 | memory tool. Claude API 에서 Claude 가 /memories 디렉터리의 파일을 만들고 읽게 하는 도구. 저장은 내 앱이 맡습니다. |
| 스킬 | Skill. 절차·지식을 폴더(SKILL.md)로 묶어 필요할 때만 불러오는 것. |
| 범위 | scope. 지침이 적용되는 넓이 — 조직(managed policy) · 사용자(~/.claude/) · 프로젝트(저장소 안) · 로컬(CLAUDE.local.md). |
| 리더 · 팀원 | 에이전트 팀에서 일을 나누고 결과를 모으는 세션(team lead)과, 맡은 일을 하는 세션(teammate). |
| 역할 정의 파일 | subagent definition. .claude/agents/<이름>.md 에 역할·도구·지시를 적은 파일. 서브에이전트와 팀원 둘 다에 다시 쓸 수 있습니다. |
| 생성 지시문 | spawn prompt. 리더가 팀원을 만들 때 주는 첫 지시. 팀원이 받는 유일한 “대화”입니다. |
팀 · 연결
| 용어 | 쉬운 풀이 |
|---|---|
| 인수인계 노트 | 다음 세션·다른 에이전트가 이어받도록 남기는 진행 기록. 원문 예: claude-progress.txt, NOTES.md. |
| MCP | Model Context Protocol. AI 앱을 외부 도구·데이터에 잇는 표준 연결 방식. 원문 비유는 “AI 앱용 USB-C 포트”. |
| Claude 프로젝트 | claude.ai 에서 대화 기록과 지식 자료를 한데 묶은 작업 공간. 코딩을 하지 않는 팀의 선택지. |
| AGENTS.md | 여러 에이전트 도구가 함께 읽는 열린 형식의 지침 파일. Claude Code 도 CLAUDE.md 대신 읽을 수 있습니다. |
세컨드 브레인 방법 · 그 밖의 말
| 용어 | 쉬운 풀이 |
|---|---|
| CODE | Capture(모으기) · Organize(정리하기) · Distill(추리기) · Express(표현하기). 세컨드 브레인을 만들고 쓰는 네 단계. |
| PARA | Projects(프로젝트) · Areas(영역) · Resources(자원) · Archives(보관). 정보를 네 칸으로 나누는 정리법. |
| PKM | Personal Knowledge Management, 개인 지식 관리. 한 사람이 지식을 모으고 분류하고 찾고 나누는 과정. |
| 오케스트레이터 | 일을 나누고 모으는 지휘 역할. 이 가이드에서는 이후 “지휘 에이전트”라고 씁니다. |
| 훅 | hook. 정해진 순간에 Claude Code 가 반드시 실행하는 명령. 지침 파일과 달리 모델의 판단과 상관없이 실행됩니다. |
| 저장소 · git | 파일과 그 변경 이력을 함께 보관하는 프로젝트 폴더와, 그 이력을 기록하는 도구. 프로젝트 범위 지침은 이것으로 팀과 나눕니다. |
- 에이전트는 세션마다 빈 컨텍스트로 시작하고, 에이전트 팀의 팀원은 리더의 대화 기록을 받지 못합니다. 받는 것은 CLAUDE.md · MCP · 스킬 같은 프로젝트 맥락과 생성 지시문뿐입니다.
- 그래서 팀의 목표와 맥락은 파일로 적어 모두가 읽는 자리에 두어야 합니다. 이 가이드는 그 파일 묶음을 “팀의 세컨드 브레인(공용 기억)”이라 부릅니다. 원뜻은 한 사람의 디지털 지식 창고입니다.
- 공용 기억은 언제 읽히는지에 따라 다섯 층 — 항상 읽힘 · 필요할 때 · 스스로 쌓음 · 인수인계 · 바깥 연결 — 으로 나눕니다.
- 개인 팀과 회사 팀은 지침의 범위(사용자 · 프로젝트 · 조직)로 나누기를 이 가이드는 권합니다.
출처: https://fortelabs.com/blog/basboverview · https://en.wikipedia.org/wiki/Personal_knowledge_management · https://code.claude.com/docs/en/agent-teams (Context and communication) · https://code.claude.com/docs/en/sub-agents (What loads at startup) · https://code.claude.com/docs/en/memory · https://code.claude.com/docs/en/best-practices · https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents · https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents · https://modelcontextprotocol.io/docs/getting-started/intro (수집일 2026-11-10)
에이전트는 무엇을 기억하나 — 컨텍스트의 한계
공용 기억을 설계하려면 먼저 에이전트의 “기억”이 어떻게 생겼는지 알아야 합니다. 에이전트가 아는 것은 지금 펼쳐 놓은 글, 곧 컨텍스트뿐입니다. 이 장에서는 컨텍스트의 한도와 약점, 그리고 그 약점을 피하는 세 가지 방법(압축 · 메모 · 필요할 때 불러오기)을 차례로 보고, 이것이 이 가이드의 “다섯 층” 구조로 어떻게 이어지는지 정리합니다.
- 컨텍스트 창이 무엇이고, 그 안에 무엇이 들어가는지
- 글을 많이 넣을수록 오히려 흐려지는 “컨텍스트 썩음”과 “주의력 예산”
- 긴 대화를 요약해 이어 가는 압축(
/compact)의 장단점 - 창 바깥에 메모를 적어 두고 다시 읽는 방법(
NOTES.md, 메모리 도구) - 자료를 미리 다 넣지 않고 필요할 때 찾아 읽는 방법, 그리고 공용 기억의 다섯 층
컨텍스트 창 — 에이전트가 한 번에 펼쳐 보는 책상
Anthropic 의 컨텍스트 엔지니어링 글은 컨텍스트를 “모델이 답을 만들 때 함께 들어가는 토큰(AI 가 읽고 쓰는 글의 양을 세는 단위)의 묶음”이라고 정의합니다. 쉽게 말해 에이전트가 지금 책상 위에 펼쳐 둔 모든 글입니다. 컨텍스트 창(context window — 그 책상의 넓이, 한 번에 담을 수 있는 글의 한도)을 넘는 글은 올려놓을 수 없습니다.
책상 위에는 사람이 쓴 프롬프트(에이전트에게 보내는 지시문)만 있는 것이 아닙니다. 원문은 에이전트가 관리해야 할 컨텍스트로 시스템 지시, 도구, MCP, 외부 데이터, 대화 기록을 듭니다. 에이전트가 “생각 → 도구 사용 → 결과 확인”을 여러 차례 되풀이하며 일할수록 다음 차례에 쓸 만한 글이 계속 생기고, 무엇을 책상에 올릴지 매번 다시 골라야 합니다. 원문은 이 고르는 일을 컨텍스트 엔지니어링이라고 부르며, 좋은 문구를 찾는 프롬프트 작성의 다음 단계라고 설명합니다.
| 사실 | 원문이 말하는 것 | 공용 기억에 주는 뜻 |
|---|---|---|
| 새 세션 = 빈 책상 | Claude Code 의 모든 세션은 새 컨텍스트 창에서 시작 | 남기고 싶은 것은 파일로 적어야 다음 세션이 봅니다 |
| 요청마다 전체 전송 | 요청할 때마다 대화 전체를 보냄. 관계없는 일 세 개가 쌓인 세션은 네 번째 일의 매 차례에 셋을 다시 읽음 | 책상에 쌓인 글은 쓸 때마다 비용이 듭니다 |
| 창은 넓어짐 | 요즘 모델 대부분은 100만 토큰 창, 한도 가까이에서 자동 압축 — 창이 모자라는 일은 드묾 | 문제는 “모자람”보다 “흐려짐”과 “비용”입니다(다음 소절) |
비용 쪽 세부 — 캐시와 /usage
- Claude Code 모범 사례 문서: 쌓인 대화는 캐시가 살아 있는 동안 할인되고, 캐시가 끝나면 제값을 냅니다. 프롬프트 캐시는 구독에서 약 1시간, API 키·클라우드 사업자·사용 크레딧에서는 5분이며, 서브에이전트는 따로 바꾸지 않으면 5분입니다.
- 1시간 캐시에서 약 20만 토큰을 넘긴 세션이 쉬고 있으면 캐시가 끝나기 직전에 압축되어, 점심 뒤에는 요약에서 이어 갑니다. 기록이 필요 없다면 새 세션이 더 쌉니다.
/usage는 Pro·Max·Ultra·Team·Enterprise 에서 사용량을 스킬·서브에이전트·플러그인·MCP 서버별로 나눠 보여 주고, 긴 컨텍스트나 잦은 캐시 놓침이 사용량의 10% 를 넘으면 표시합니다.
컨텍스트 썩음 — 많이 넣을수록 흐려집니다
책상이 넓으면 무엇이든 다 올려 두면 될 것 같지만, 원문은 반대로 말합니다. 건초 더미에서 바늘 찾기 같은 시험에서 드러난 현상으로, 컨텍스트 창 안의 토큰이 늘어날수록 그 안의 정보를 정확히 떠올리는 힘이 떨어집니다. 원문은 이를 컨텍스트 썩음(context rot)이라 부르고, 정도의 차이는 있어도 모든 모델에서 나타난다고 적습니다.
원문은 사람의 작업 기억에 빗대어 언어 모델에도 주의력 예산(attention budget — 많은 글을 읽을 때 쓰는 집중력의 한도)이 있다고 말합니다. 새 토큰은 하나하나 이 예산을 조금씩 씁니다. 그래서 컨텍스트는 “쓸수록 효과가 줄어드는 한정된 자원”으로 다뤄야 합니다.
결론은 한 문장입니다. 좋은 컨텍스트란 원하는 결과가 나올 가능성을 가장 높이는, 꼭 필요한 정보만 담은 가장 작은 글 묶음입니다(원문 표현은 “신호가 강한 토큰의 가장 작은 묶음”). 공용 기억에 옮기면 “모두에게 항상 읽히는 파일은 짧고 알차게” 써야 한다는 뜻입니다.
지침 파일에 미치는 영향
Claude Code 메모리 문서는 CLAUDE.md 를 파일당 200줄 아래로 권합니다. 길수록 컨텍스트를 더 쓰고 지침을 덜 따르기 때문입니다.
강조보다 짧게
모범 사례 문서: 긴 파일 속에서 한 줄이 묻힌다면 강조를 더할 일이 아니라 파일을 줄일 일입니다. 꼭 지켜야 할 규칙은 훅이나 거부 규칙으로.
일과 일 사이 정리
창이 넓어진 지금도 /clear(지금 대화를 비우고 새로 시작하는 명령) 로 관계없는 일 사이를 끊는 것은 여전히 할 만합니다. 집중된 컨텍스트가 더 나은 답을, 더 적은 비용으로 줍니다.
왜 흐려지나 — 원문이 드는 구조적 이유
언어 모델은 트랜스포머 구조라서 모든 토큰이 다른 모든 토큰을 살펴봅니다. 토큰이 n 개면 쌍의 관계가 n² 개가 되어, 컨텍스트가 길어질수록 이 관계를 붙잡는 힘이 엷어집니다. 또 모델은 짧은 글이 더 흔한 학습 자료로 주의 패턴을 익혔기 때문에 컨텍스트 전체에 걸친 의존 관계에는 경험과 전용 파라미터가 적습니다. 위치 인코딩 보간 같은 기법으로 긴 글을 다루게 하지만, 토큰 위치를 이해하는 힘이 다소 떨어집니다. 이 요인들이 “절벽”이 아닌 “경사”를 만듭니다.
좋은 컨텍스트의 모양 — 공용 기억을 쓸 때 기준
원문은 컨텍스트의 부분마다 같은 원칙(알차게, 그러나 빈틈없이)을 적용합니다. 팀이 함께 읽을 지침과 목표 문서를 쓸 때 그대로 기준으로 삼을 수 있습니다.
| 부분 | 원문의 권고 | 공용 기억에서 |
|---|---|---|
| 지시문의 “높이” | 너무 구체적인 if-else 식 규칙(깨지기 쉬움)도, 너무 막연해 “다 아는 줄 아는” 지시도 피하고 그 사이의 알맞은 높이로 | 목표·원칙은 판단 기준이 되게, 세부 절차는 스킬로 분리 |
| 구성 | <background_information>, ## Tool guidance 처럼 절을 나누고 XML 태그나 마크다운 제목으로 구분 | 목표 · 하지 않을 것 · 결정 기록처럼 제목으로 나눔 |
| 최소한 | 기대하는 행동을 다 그리는 최소한의 정보. 최소가 꼭 짧다는 뜻은 아님. 가장 좋은 모델로 최소 지시부터 시험하고 실패 사례를 보며 보탬 | 처음엔 짧게 쓰고, 에이전트가 틀린 곳만 보탬 |
| 예시 | 예외 상황을 줄줄이 넣지 말고, 기대 행동을 보여 주는 다양하고 대표적인 예시를 골라 넣음 | 좋은 결과물 한두 개를 링크 |
| 도구 | 기능이 겹치지 않고 용도가 분명한 최소한의 도구. 사람이 어느 도구를 쓸지 못 정하면 에이전트도 못 정함 | 연결할 MCP 도구를 팀마다 골라 둠(8장) |
압축 — 긴 대화를 요약해 새 책상에서 이어 가기
압축(compaction — 대화가 한도에 가까워지면 내용을 요약하고, 그 요약으로 새 컨텍스트 창을 시작하는 것)은 원문이 “긴 작업에서 가장 먼저 당기는 손잡이”라고 부르는 방법입니다. Claude Code 는 컨텍스트 창이 차기 전에 대화를 자동으로 압축하고, 사람이 /compact 명령으로 직접 할 수도 있습니다.
1단계 — 쌓입니다. 일할수록 대화·도구 출력이 늘어 책상이 가득 찹니다.
2단계 — 요약합니다. 원문에 따르면 Claude Code 는 대화 기록을 모델에 넘겨 가장 중요한 세부를 요약·압축합니다. 설계 결정, 아직 해결 안 된 버그, 구현 세부는 남기고 중복된 도구 출력이나 메시지는 버립니다.
3단계 — 이어 갑니다. 에이전트는 압축된 컨텍스트와 최근에 열어 본 파일 다섯 개를 가지고 계속 일합니다. 사용자는 한도를 신경 쓰지 않고 흐름을 이어 갈 수 있습니다.
주의할 점은 “무엇을 버리느냐”입니다. 원문은 너무 세게 압축하면 나중에야 중요성이 드러나는 미묘한 맥락을 잃을 수 있다고 경고합니다. 그래서 압축 뒤에도 꼭 살아남아야 하는 것(팀 목표, 결정 이유, 진행 상황)은 대화 안에만 두지 말고 파일에 적어 두는 것이 안전합니다. 메모리 도구 문서도 같은 말을 합니다. 압축은 작업 중인 컨텍스트를 작게 유지하고, 메모리는 요약을 거쳐도 살아남아야 할 정보를 지킨다고 하며 둘을 함께 쓰라고 권합니다.
/compact 에 초점 주기
모범 사례 문서 예: /compact keep the API changes and the test commands
뜻: API 변경과 테스트 명령은 남기고 압축하라. 다만 긴 세션의 /compact 는 대화 전체를 읽어 요약하므로 그 자체로 큰 요청입니다.
압축 대신 새로 시작
관계없는 일로 넘어갈 때는 /clear. 비용이 들지 않고, 다음 일이 앞 일의 기록 값을 치르지 않습니다. /clear oauth-migration 처럼 이름을 주면 나중에 돌아올 수 있습니다.
압축을 직접 만드는 개발자용 — 원문 권고
- 복잡한 에이전트 실행 기록으로 압축 프롬프트를 조정하라. 먼저 관련 정보를 빠짐없이 담도록(재현율 최대) 만든 뒤, 군더더기를 덜어 정밀도를 높인다.
- 가장 손쉬운 군더더기는 도구 호출과 그 결과다. 깊은 과거의 도구 결과를 다시 볼 일은 드물다. 도구 결과 지우기(tool result clearing)는 가장 가볍고 안전한 압축의 하나로, Claude Developer Platform 기능으로 나왔다.
- Claude API 쪽에서는 컨텍스트 편집(context editing)이 클라이언트에서 특정 도구 결과를 지우고, 압축(compaction)은 대화가 한도에 가까워지면 서버에서 대화 전체를 자동 요약한다(메모리 도구 문서).
구조화된 메모 — 책상 밖 노트에 적고, 다시 펼쳐 읽기
두 번째 방법이 구조화된 메모(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 API)
메모리 도구는 클라이언트 쪽에서 동작합니다. Claude 는 파일 작업을 요청만 하고, 실제 실행은 내 애플리케이션이 내가 관리하는 저장소에서 합니다. /memories 는 내 처리기가 실제 저장소(사용자별 디렉터리, 데이터베이스 키 등)에 연결하는 경로 접두어입니다. 같은 도구 설정을 보내고 같은 저장소를 쓰면 다음 대화가 같은 기억에서 이어집니다. 보안을 위해 모든 메모리 작업을 /memories 안으로 제한하라고 원문은 적습니다. Anthropic 글에 따르면 이 도구는 Sonnet 4.5 출시 때 공개 베타로 나왔으며, 지금 메모리 도구 문서의 상태 표시는 stable 입니다.
필요할 때 불러오기 — 자료는 서랍에, 책상엔 색인만
세 번째 방법은 자료를 미리 다 올려 두지 않는 것입니다. 원문이 말하는 “필요할 때(just in time)” 방식의 에이전트는 파일 경로, 저장해 둔 검색어, 웹 링크 같은 가벼운 표시만 들고 있다가, 도구로 그때그때 자료를 컨텍스트에 올립니다. Claude Code 는 이 방식으로 큰 데이터베이스를 분석하는데, 겨냥한 검색을 쓰고 결과를 저장하며 head·tail 같은 명령으로 큰 자료를 통째로 올리지 않고 살펴봅니다.
많은 AI 앱이 답하기 전에 관련 자료를 미리 찾아 넣습니다(임베딩 기반 검색). 빠르지만, 관련 없을 수도 있는 자료가 책상을 채웁니다.
책상엔 색인만, 자료는 서랍에 둡니다. 원문은 이것이 사람의 방식과 닮았다고 합니다. 우리는 자료 전체를 외우지 않고 파일 시스템·받은편지함·책갈피로 필요할 때 찾습니다.
Claude Code 는 혼합형입니다. CLAUDE.md 는 처음부터 컨텍스트에 넣고, glob·grep 같은 기본 도구로 주변을 탐색해 필요한 파일을 그때 읽습니다. 원문은 이렇게 해서 낡은 색인 문제를 피한다고 설명합니다.
이 방식에서는 파일의 이름과 자리 자체가 정보가 됩니다. 원문 예로, tests 폴더 안의 test_utils.py 와 src/core_logic/ 안의 같은 이름 파일은 목적이 다르다는 신호를 줍니다. 폴더 구조, 이름 짓는 규칙, 날짜는 사람에게도 에이전트에게도 “이 정보를 언제 어떻게 쓸지” 알려 줍니다. 에이전트는 탐색하면서 한 겹씩 이해를 쌓고(점진적 공개), 꼭 필요한 것만 작업 기억에 둡니다. 공용 기억의 폴더를 잘 짜야 하는 이유가 여기 있습니다(2장 PARA).
셋 중 무엇을 쓰나 — 압축 · 메모 · 여러 에이전트
원문은 긴 작업을 위한 기법으로 압축, 구조화된 메모, 그리고 서브에이전트 구조를 함께 듭니다. 서브에이전트(맡긴 일을 자기 컨텍스트에서 하고 결과만 돌려주는 도우미)는 깨끗한 컨텍스트 창에서 집중된 일을 맡아 수만 토큰을 써 가며 탐색하더라도, 돌려줄 때는 압축된 요약(흔히 1,000~2,000 토큰)만 돌려줍니다. 세부 탐색은 서브에이전트 안에 머물고, 지휘하는 쪽은 결과를 엮는 데 집중합니다.
| 방법 | 원문이 말하는 잘 맞는 일 |
|---|---|
| 압축 | 주고받는 대화가 많이 필요한 일 — 대화의 흐름을 유지 |
| 구조화된 메모 | 분명한 단계(이정표)가 있는 반복 개발 |
| 여러 에이전트 구조 | 나란히 탐색하는 것이 이득인 복잡한 조사·분석 |
층으로 정리하기 — 공용 기억의 다섯 층
지금까지 본 원리를 모으면 공용 기억을 어떻게 나눌지가 보입니다. 기준은 “이 글이 언제 책상에 올라와야 하나”입니다. 모두가 항상 알아야 하는 짧은 것만 시작 때 넣고, 길거나 가끔 쓰는 것은 필요할 때 찾게 하고, 일하며 생긴 것은 창 밖에 적게 합니다.
| 이런 내용은 | 이 층에 | 이유 |
|---|---|---|
| 팀 목표 · 꼭 지킬 원칙 · 자주 틀리는 것 | ① 항상 읽힘 (3장) | 모든 에이전트가 매번 알아야 함. 짧아야 잘 따름 |
| 반복 절차 · 긴 참고 자료 | ② 필요할 때 (4장) | 스킬 본문은 쓸 때까지 컨텍스트를 거의 쓰지 않음 |
| 내 수정·선호에서 배운 것 | ③ 스스로 쌓음 (5장) | 사람이 따로 적지 않아도 Claude 가 남김 |
| 어디까지 했나 · 다음에 할 것 | ④ 인수인계 (7장) | 압축·새 세션을 넘어 살아남아야 함 |
| 회사 문서 · 외부 서비스 자료 | ⑤ 바깥 연결 (8장) | 복사하지 않고 원본에서 그때 가져옴 |
- 에이전트가 아는 것은 지금 컨텍스트 창(책상)에 올라온 글뿐이고, 새 세션은 빈 책상에서 시작합니다.
- 글이 많을수록 정확히 떠올리는 힘이 완만하게 떨어집니다(컨텍스트 썩음). 좋은 컨텍스트는 “꼭 필요한 정보만 담은 가장 작은 묶음”입니다.
- 긴 일에는 압축(요약해 이어 가기), 구조화된 메모(창 밖 파일에 적고 다시 읽기), 서브에이전트(요약만 돌려받기)를 일의 성격에 맞게 씁니다.
- 자료는 미리 다 넣지 말고 경로·이름 같은 표시만 두고 필요할 때 찾게 합니다. Claude Code 는 CLAUDE.md 만 먼저 넣는 혼합형입니다.
- 이 원리로 공용 기억을 다섯 층(항상 읽힘 · 필요할 때 · 스스로 쌓음 · 인수인계 · 바깥 연결)으로 나눕니다.
출처: https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents · https://code.claude.com/docs/en/best-practices (Keep cost and context down · Know what subagents cost · What you can stop doing) · https://platform.claude.com/docs/en/agents-and-tools/tool-use/memory-tool (How it works · Using with compaction) · https://code.claude.com/docs/en/memory (CLAUDE.md vs auto memory · Size) · https://code.claude.com/docs/en/skills (수집일 2026-11-10)
세컨드 브레인 설계 — CODE 와 PARA 를 에이전트용으로
1장에서 “어느 층에 둘까”를 정했다면, 이 장은 “무엇을, 어떤 모양으로 둘까”를 정합니다. 사람의 세컨드 브레인(배운 것을 뇌 바깥 한곳에 모아 둔 디지털 지식 창고)을 만드는 방법으로 널리 쓰이는 Forte Labs 의 CODE(네 단계)와 PARA(네 칸 정리법)를 먼저 원문대로 살펴보고, 이를 에이전트 팀의 공용 기억에 옮기는 방법을 제안합니다. 핵심은 두 가지입니다. 모든 정보를 팀의 목표와 프로젝트에 묶어 정리하고, 모든 메모를 다음 에이전트가 바로 쓸 수 있게 적는 것입니다.
- CODE — 모으기 · 정리하기 · 추리기 · 표현하기 — 의 원뜻과 에이전트 팀용 해석
- PARA — 프로젝트 · 영역 · 자원 · 보관 — 로 공용 기억 폴더를 나누는 법
- 점진적 요약으로 “짧은 층”과 “긴 층”을 나누는 법
- 팀 목표 문서를 만들어 모든 세션이 읽게 하는 법(이 가이드의 제안)
- “미래의 나를 위한 메모”를 “다음 에이전트를 위한 메모”로 바꿔 쓰는 법
- 카파시의 LLM 위키 — AI 가 원문을 읽어 위키를 쓰고 고치게 하는 방식과, 이 가이드에 끼우는 법(제안)
CODE — 세컨드 브레인을 만들고 쓰는 네 단계
Forte Labs 의 티아고 포르테는 세컨드 브레인을 만드는 방법을 CODE 네 단계로 정리합니다. Capture(모으기) · Organize(정리하기) · Distill(추리기) · Express(표현하기)입니다. 원문은 이것이 세컨드 브레인을 만드는 단계이자 이후 계속 함께 일하는 단계라고 말합니다. 직업이나 메모 도구에 상관없이 쓸 수 있고, 누구나 이미 어떤 형태로든 하고 있는 일이라고도 덧붙입니다.
| 단계 | 원문의 뜻 (사람용) | 에이전트 팀으로 옮기면 (이 가이드의 제안) |
|---|---|---|
| 모으기 | 정말 중요한 것만, 마음에 와닿는 것만 한곳에 모음 | 저장소(파일과 변경 이력을 함께 보관하는 프로젝트 폴더)·자료를 읽어서는 알 수 없는 결정·절차만 공용 기억에 적음 |
| 정리하기 | 주제가 아니라 “실행에 쓸모”로 정리 — PARA | 폴더를 팀의 프로젝트·영역 기준으로 나눠, 에이전트가 이름과 자리로 찾게 함 |
| 추리기 | 핵심만 남긴 짧은 요약을 겹겹이 | 항상 읽히는 층은 요약만, 세부는 필요할 때 읽는 파일로 |
| 표현하기 | 쌓은 지식으로 실제 결과물을 만들고 나눔 | 세션마다 결과물 하나를 끝내고, 그 결과를 다시 공용 기억에 남김 |
모으기 — 다 적지 말고, 다시 찾을 수 없는 것만
원문의 첫 단계는 “가장 중요한 정보만 모으라”입니다. 우리는 이미 많은 정보를 읽고 만들지만, 그것을 한곳에 모아 두지 않아서 흩어지고 잊힌다고 원문은 진단합니다. 무엇을 모을지 정할 때 원문은 세 가지를 물어보라고 합니다.
- 일과 삶에서 늘 되돌아오는 주제와 질문은 무엇인가?
- 이미 손에 있는 것 중 값지고 영향력 있는 정보는 무엇인가?
- 서로 엮고, 섞어 보고, 때때로 다시 꺼내 생각을 자극하고 싶은 지식은 무엇인가?
에이전트 팀에서는 이 질문이 더 날카로워집니다. Claude Code 모범 사례 문서는 “Claude 가 저장소(파일과 변경 이력을 함께 보관하는 프로젝트 폴더)를 읽어 찾을 수 없는 것, 또는 매 세션 다시 찾느라 시간을 쓰는 것만 적으라”고 권하며, 적기 전에 두 가지를 물어보라고 합니다. 코드를 읽어 찾을 수 있나? 실제로 찾아보러 갈까? 둘 다 “예”라면 빼 둡니다. 원문이 드는 “적어야 할 것”의 예는 회의에서 정한 결정, 한 사람 머릿속에만 있는 배포 절차, 통합 테스트에 필요한 환경 변수입니다.
원문 — 큐레이터처럼
눈앞의 정보를 바로 소비하지 말고 나중을 위해 저장해 두라고 원문은 권합니다. 남이 보여 주는 대로 반응하는 대신 무엇을 들일지 스스로 고르는 사람이 되라는 뜻입니다. 새 항목은 임시 보관함(Inbox)에 모았다가 한 주에 한 번쯤 몰아서 제자리에 둔다고 합니다.
이 가이드의 제안 — 팀의 받은편지함
공용 기억에 예시 이름 inbox.md 같은 임시 파일을 두고, 에이전트가 일하며 알게 된 “적을 만한 것”을 일단 거기 적게 합니다. 사람이 주기적으로 보고 제자리(목표 문서·지침 파일·자료 폴더)로 옮기거나 지웁니다.
원문 — 모으기 도구와 “와닿는 것만”
원문은 분석하듯 고르지 말고 직관적으로 마음에 와닿는(resonate) 것을 남기라고 합니다. 그것이 대개 내가 아끼거나 궁금해하는 것과 이어져 있기 때문입니다. 모으기 도구로는 전자책 앱의 밑줄 내보내기, 나중에 읽기 앱, 기본 메모 앱, SNS 즐겨찾기, 음성 받아쓰기 앱, 웹 클리퍼를 듭니다. 한곳에 다양한 정보를 모아 두면 서로 섞이며 뜻밖의 연결과 패턴이 보이고, 재료가 필요할 때 찾아볼 곳이 하나가 된다는 것이 원문의 설명입니다.
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 로 다시 나누려 하면 지칩니다. 원문 권고는 1분도 안 걸리는 방법 — 기존 파일을 전부 오늘 날짜를 붙인 Archive 폴더로 옮기는 것. 지우는 것이 아니니 필요하면 꺼내 쓰면 되고, 생각보다 옛 메모가 덜 필요할 것이라고 합니다.
- 프로젝트 목록이 영역 목록이 되는 실수: 원문의 코칭 사례에서 한 임원이 적은 “프로젝트 목록”은 전략 기획·휴가·채용처럼 끝나지 않는 일, 곧 모두 영역이었습니다. 영역을 구체적인 프로젝트로 쪼개지 않으면 내가 얼마나 많은 일을 맡았는지 알 수 없고, 지금의 노력을 장기 목표에 잇지 못한다고 원문은 말합니다.
- 단순해야 하는 이유: 정리 체계가 삶만큼 복잡하면 그것을 유지하느라 정작 삶에 쓸 시간과 힘을 빼앗긴다 — “체계는 시간을 주어야지 가져가면 안 된다.”
추리기 — 짧은 층과 긴 층을 겹겹이
원문의 세 번째 단계는 메모를 바로 쓸 수 있는 짧은 요약으로 추리는 것입니다. 작년에 읽은 책의 메모 10쪽을 바쁜 날 다시 볼 수는 없지만, 요점 세 줄이라면 금방 떠올려 지금 일에 쓸 수 있습니다. 원문은 이를 위해 점진적 요약(Progressive Summarization)을 권합니다. 가장 좋은 발췌만 남기고, 그 발췌를 요약하고, 다시 그 요약을 요약하는 식으로 단계마다 핵심을 짜냅니다.
이 생각은 Claude Code 의 실제 동작과 잘 맞습니다. 자동 메모리(Claude 가 스스로 적는 메모)의 색인 파일 MEMORY.md 는 매 세션 처음 200줄 또는 25KB 까지만 읽히고, Claude 는 자세한 메모를 별도 주제 파일로 옮겨 MEMORY.md 를 짧게 유지합니다. CLAUDE.md 도 파일당 200줄 아래가 권장이고, 길어진 절차는 쓸 때만 본문이 읽히는 스킬(절차를 폴더로 묶어 필요할 때만 불러오는 것)로 옮기라고 문서들은 말합니다. 짧은 층이 긴 층을 가리키는 구조가 바로 점진적 요약입니다.
| 원문의 추리기 원칙 | 공용 기억에서 (이 가이드의 제안) |
|---|---|
| 다음에 볼 나를 위해 설계하라 | 다음 에이전트를 위해 쓴다 — 아래 「다음 에이전트를 위한 메모」 |
| 여러 단계로 점진적으로 요약하라 | 목표 문서는 세 줄 요약 + 세부 링크, 세부는 프로젝트 폴더에 |
| 기회가 될 때 조금씩 추려라 — 메모를 만질 때마다 조금씩 값을 더하라 | 에이전트가 파일을 고칠 때마다 제목을 다듬거나 관련 파일 링크를 한 줄 더하게 함 |
원문 — 처음부터 완벽하게 쓰지 말 것
어떤 자료가 나중에 값질지는 대개 한참 뒤에야 압니다. 그래서 원문은 처음부터 많은 노력을 들이지 말고, 메모를 처음 볼 때는 알기 쉬운 제목을, 다음에는 핵심에 밑줄을, 그다음에는 관련 메모 링크를 더하라고 합니다. 이렇게 일을 시간에 나눠 두면 가장 자주 쓰이는(그래서 가장 값진) 메모가 스키장의 인기 코스처럼 자연스럽게 깊게 파인다고 원문은 비유합니다.
표현하기 — 창고가 아니라 공장으로
모으고 정리하고 추리는 모든 일의 목적은 실제 결과물입니다. 원문은 세컨드 브레인을 좋은 생각을 쌓아 두는 창고가 아니라, 생각을 구체적인 결과로 바꾸는 공장으로 여기라고 합니다. 정보는 써먹을 때 비로소 지식이 된다는 것입니다.
원문은 이를 위해 일을 중간 산출물(Intermediate Packets — 회의 메모, 조사 결과 목록, 초안 슬라이드처럼 따로 떼어 다시 쓸 수 있는 작은 결과)로 나누라고 합니다. 큰 프로젝트를 한 번에 밀어 올리려 하지 말고, 15분이든 3시간이든 작업 시간마다 중간 산출물 하나를 끝내라는 것입니다. 끝낸 산출물은 세컨드 브레인에 저장해 비슷한 일에 다시 씁니다.
에이전트 쪽 원문에도 같은 원칙
메모리 도구 문서의 여러 세션 작업 패턴은 “한 번에 기능 하나씩 하고, 끝에서 끝까지 확인했을 때만 완료로 표시하라”고 하며, 세션이 끝나기 전에 진행 기록에 한 일과 남은 일을 적게 합니다. 자세한 방법은 7장.
“완성”을 기다리지 않기
원문은 모든 것이 진행 중이고, 내놓는 모든 것에 “1.0 판”이 붙어 있다고 생각하라고 합니다. 공용 기억도 처음부터 완벽할 필요가 없습니다. 짧게 시작해 에이전트가 틀리는 곳을 보며 고쳐 갑니다.
팀 목표 문서 — 모두가 같은 목표를 보게 하는 한 장
이 가이드가 답하려는 질문의 절반은 “모든 에이전트가 같은 목표를 갖게 하려면?”입니다. 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 회의: 보고서는 한국어로만
불러오기(@import) 세부 — 원문 기준
- 상대 경로와 절대 경로 모두 됩니다. 상대 경로는 작업 폴더가 아니라 불러오는 파일 기준으로 풉니다.
- 불러온 파일이 다시 다른 파일을 불러올 수 있으며, 최대 네 단계까지입니다.
- 마크다운 코드 표시(백틱) 안의
@경로는 불러오지 않습니다. 경로를 글자로만 적고 싶으면 백틱으로 감쌉니다. - 작업 폴더 바깥 파일을 불러오면 Claude Code 가 승인을 묻습니다.
- 불러오기는 긴 파일을 정리하는 데는 도움이 되지만 컨텍스트 비용을 줄이지는 않습니다. 불러온 파일이 함께 읽히기 때문입니다. 일부에만 필요한 지침은 경로별 규칙(
.claude/rules/)으로 옮기면 해당 파일을 다룰 때만 읽힙니다(3장).
다음 에이전트를 위한 메모 — “미래의 나”를 “다음 에이전트”로
원문의 추리기 단계에는 힘 있는 마음가짐 하나가 나옵니다. “미래의 나를 생각하며 메모를 설계하라.” 메모는 시간 여행이고, 지금의 지식을 꾸러미로 묶어 미래의 나에게 보내는 일이라는 것입니다. 원문은 메모를 만들거나 고칠 때마다 다음에 찾고 쓰기 쉽게 조금씩 손보라고 하며, 세 가지 예를 듭니다.
| 원문의 예 (미래의 나에게) | 다음 에이전트에게 (이 가이드의 제안) |
|---|---|
| 잊을까 봐 핵심 용어를 정의해 둔다 | 팀 안에서만 쓰는 말·약어를 목표 문서나 지침 파일에 한 줄로 풀어 둔다 |
| 멈춘 자리에 표시를 남겨 어디서 다시 시작할지 안다 | 진행 기록에 “한 일 / 남은 일 / 다음 첫 단계”를 남긴다 — 원문의 인수인계 노트(claude-progress.txt 등)와 같은 일 |
| 시간이 지나면 잊을 관련 웹사이트·파일·메일 링크를 단다 | 결정의 근거가 된 파일 경로·자료 링크를 함께 적어, 다음 에이전트가 필요할 때 찾아 읽게 한다 |
에이전트에게 이 마음가짐은 비유가 아니라 사실입니다. 사람의 “미래의 나”는 그래도 어렴풋이 기억하지만, 다음 세션의 에이전트는 정말로 아무것도 기억하지 못합니다(소개). 긴 작업에 관한 Anthropic 글이 진행 기록 파일과 git 이력으로 “새 컨텍스트 창에서 시작하는 에이전트가 일의 상태를 빨리 파악하게” 만든 것도 같은 이유입니다. 원문은 이를 “앞으로 갚는(pay it forward)” 전략이라 부릅니다. 지금 조금 더 수고하면 나중에 그 덕을 봅니다.
개인 지식과 팀 지식 — 두 팀을 나누고 잇는 법
세컨드 브레인의 원뜻은 개인 지식 관리(PKM)입니다. 위키백과는 PKM 을 지식 관리의 “아래에서 위로” 접근이라고 설명하고, 개인과 조직의 지식을 함께 보는 모형도 소개합니다. 장(Zhang)의 모형에서 조직 지식은 개인에게 맞게 개인화되고, 개인 지식은 모여서 조직 지식으로 쓰이며, 둘은 이 순환으로 이어집니다(OAPI — organizationalize·aggregate·personalize·individualize). 위키백과는 반대 견해도 함께 싣습니다. 지식은 개인만의 산물이 아니라 연결·대화·사회적 상호작용에서 생긴다는 비판입니다.
카파시의 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 가 하니 위키가 최신으로 남습니다.
이 밖에 경쟁 분석, 실사, 여행 계획, 강의 메모, 취미 탐구처럼 시간을 두고 지식을 모으며 흩어지지 않게 정리하고 싶은 모든 일에 쓸 수 있다고 원문은 말합니다.
원문 — 도구 팁 (Obsidian · qmd · git)
- 검색 도구: 작은 규모에서는 목차 파일로 충분하지만, 커지면 제대로 된 검색이 필요해집니다. 원문은 qmd 를 듭니다 — 마크다운 파일용 로컬 검색 엔진으로 BM25·벡터 혼합 검색과 AI 재정렬을 모두 기기 안에서 하고, CLI(AI 가 명령으로 부를 수 있음)와 MCP 서버(AI 가 도구로 쓸 수 있음)를 둘 다 줍니다. AI 와 함께 단순한 검색 스크립트를 직접 만들어도 됩니다.
- Obsidian Web Clipper: 웹 글을 마크다운으로 바꾸는 브라우저 확장. 원문을 빠르게 모으기 좋습니다.
- 그림을 내 컴퓨터에 받기: Obsidian 설정 → Files and links 에서 “Attachment folder path” 를 고정 폴더(예:
raw/assets/)로 두고, Settings → Hotkeys 에서 “Download attachments for current file” 에 단축키(예: Ctrl+Shift+D)를 줍니다. 깨질 수 있는 URL 대신 AI 가 그림을 직접 봅니다. 다만 AI 는 그림이 섞인 마크다운을 한 번에 읽지 못하므로 글을 먼저 읽고 그림을 따로 보게 합니다. - Obsidian 그래프 보기: 무엇이 무엇과 이어졌는지, 어느 쪽이 중심이고 어느 쪽이 외톨이인지 보는 가장 좋은 방법.
- Marp(마크다운 슬라이드 형식)와 Dataview(쪽 머리 정보로 표·목록을 만드는 Obsidian 플러그인) — AI 가 쪽마다 YAML 머리 정보(태그·날짜·원문 수)를 달면 Dataview 가 표를 만들어 줍니다.
- 위키는 그냥 마크다운 파일의 git 저장소(파일의 변경 이력을 모두 기록해 두는 폴더)입니다. 버전 이력·갈래 나누기·협업이 저절로 따라옵니다.
아래 대응은 원문에 없는 이 가이드의 연결 방법입니다. 원문 층은 받아 둔 자료, 스키마는 지침 파일(3장), 위키는 PARA 와 함께 쓰는 팀 지식 창고, log.md 는 인수인계 노트(7장), 점검은 정기 점검(9장)에 대응합니다. 에이전트 팀이라면 여러 팀원이 같은 위키를 읽고, 쓰기는 한 명(또는 리더)이 맡기를 권합니다. 같은 파일을 여럿이 고치면 덮어쓰기 쉽기 때문입니다(6장).
- CODE(모으기 · 정리하기 · 추리기 · 표현하기)는 세컨드 브레인을 만들고 쓰는 네 단계입니다. 에이전트 팀에서는 “다시 찾을 수 없는 것만 모으고, 목표에 묶어 정리하고, 짧은 층과 긴 층으로 추리고, 세션마다 결과물을 남기는” 흐름이 됩니다.
- PARA 는 정보를 프로젝트 · 영역 · 자원 · 보관 네 칸으로, 주제가 아니라 실행 기준으로 나눕니다. 폴더 구조와 이름은 에이전트가 필요한 파일을 찾는 신호가 됩니다.
- 이 가이드는 팀 목표 문서(예시 이름
GOAL.md)를 짧게 쓰고 CLAUDE.md 에서@GOAL.md로 불러오기를 권합니다. 팀원과 다음 세션이 시작 때 함께 읽습니다. 다만 맥락일 뿐 강제는 아닙니다. - “미래의 나를 위한 메모”는 “다음 에이전트를 위한 메모”가 됩니다. 용어 풀이 · 멈춘 자리 · 관련 링크를 남깁니다.
- 개인 팀과 회사 팀의 공용 기억은 따로 두고, 오가는 길만 정해 둡니다.
- 카파시의 LLM 위키는 AI 가 원문을 읽어 위키를 쓰고 고치며 쌓아 갑니다. 원문 · 위키 · 스키마 세 층, 넣기 · 묻기 · 점검 세 작업.
출처: https://fortelabs.com/blog/basboverview · https://fortelabs.com/blog/para · https://en.wikipedia.org/wiki/Personal_knowledge_management (Models · Criticism) · https://code.claude.com/docs/en/best-practices (Tell Claude what it can't see) · https://code.claude.com/docs/en/memory (Import additional files · Size · auto memory) · https://code.claude.com/docs/en/agent-teams (Context and communication) · https://code.claude.com/docs/en/sub-agents (What loads at startup) · https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents · https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents · https://platform.claude.com/docs/en/agents-and-tools/tool-use/memory-tool (Multisession pattern) · https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f (수집일 2026-11-10)
항상 읽히는 층 — CLAUDE.md 와 AGENTS.md
팀 안의 모든 에이전트가 같은 목표와 맥락으로 일하게 만드는 가장 기본 도구는 지침 파일입니다. 사람이 써 두면 에이전트가 세션을 시작할 때마다 읽습니다. 이 장은 지침 파일을 어디에 두고, 어떻게 짧고 분명하게 쓰고, 안 읽힐 때 무엇을 확인하는지 다룹니다.
- 지침 파일이 "팀 전원이 매번 읽는 공용 기억"이 되는 이유
- 범위 4종(조직·사용자·프로젝트·로컬)과 개인 팀·회사 팀에 맞춰 나눠 두는 법
- 여러 지침 파일이 읽히는 순서, 잘 쓰는 법(구체적으로·200줄 아래·충돌 없이)
@가져오기,.claude/rules/, 여러 도구가 함께 읽는 AGENTS.md- 큰 조직에서 관리하는 법, 지침이 안 먹힐 때 확인할 것
- 지침 파일이란 — 팀 전원이 매번 읽는 공용 기억 — 왜 여기서 시작하는지
- 범위 4종 — 누구와 나눌지에 따라 둘 곳이 다르다 — 개인 팀·회사 팀을 나누는 기준
- 잘 쓰는 법 — 짧고 구체적으로 — 에이전트가 실제로 따르게 쓰는 요령
가져오기·규칙 폴더·대규모 관리·🔧 표시가 붙은 접힌 상자는 필요할 때 펼쳐 보면 됩니다.
지침 파일이란 — 팀 전원이 매번 읽는 공용 기억
무엇인가 — 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 Code 는 지금 작업 폴더와 그 위의 모든 폴더에서 CLAUDE.md 와 CLAUDE.local.md 를 찾아 읽습니다. 예를 들어 foo/bar/ 에서 시작하면 foo/bar/CLAUDE.md, foo/CLAUDE.md, 그리고 그 옆의 CLAUDE.local.md 를 읽습니다.
중요한 점은 찾은 파일들이 서로를 덮어쓰지 않고 차례로 이어 붙는다는 것입니다. 폴더 기준으로는 맨 위에서 작업 폴더 쪽으로 내려오며 붙으므로, 내가 시작한 곳에 가까운 지침이 마지막에 읽힙니다. 같은 폴더 안에서는 CLAUDE.md 다음에 CLAUDE.local.md 가 붙어, 내 개인 메모가 그 층의 마지막 글이 됩니다.
foo/bar/ 에서 Claude Code 를 시작했을 때. 점선 상자(하위 폴더 지침)는 시작 때가 아니라, Claude 가 그 폴더 안의 파일을 읽거나 고칠 때 한 번 불러옵니다./context all 을 실행해 Memory files(메모리 파일) 목록을 보면 됩니다.CLAUDE.md 는 Claude 가 그 하위 폴더의 다른 파일을 읽거나·쓰거나·고칠 때 불러옵니다. cat·head 로 파일 하나를 보는 것도 "읽기"로 칩니다./compact(압축 — 대화를 요약해 새로 시작)를 하면, 프로젝트 맨 위의 CLAUDE.md 는 디스크에서 다시 읽어 넣습니다. 하위 폴더 지침은 다시 그 폴더를 만질 때 불러옵니다. 대화로만 한 지시는 이때 사라질 수 있으니, 계속 지켜야 할 것은 지침 파일에 적습니다.<!-- 관리자 메모 --> 는 Claude 에게 넘기기 전에 지워집니다. 토큰(AI 가 읽고 쓰는 글의 양을 세는 단위 — 비용·속도의 기준)을 쓰지 않고 사람끼리 메모를 남길 수 있습니다. 코드 블록 안의 주석은 그대로 남습니다.다른 폴더의 지침도 불러오기 (--add-dir)
--add-dir 옵션은 작업 폴더 밖의 폴더에도 접근하게 해 주지만, 기본으로는 그 폴더의 CLAUDE.md 를 읽지 않습니다. 읽게 하려면 환경 변수 CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD 를 켭니다.
CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 claude --add-dir ../shared-config
이렇게 하면 그 폴더의 CLAUDE.md, .claude/CLAUDE.md, .claude/rules/*.md, CLAUDE.local.md 를 읽습니다. 매번 켜 두려면 ~/.claude/settings.json 의 env 블록에 넣습니다. --setting-sources 에서 local 을 빼면 CLAUDE.local.md 는 건너뜁니다. 큰 모노레포(여러 프로젝트를 한 저장소에 둔 것)에서 다른 팀의 CLAUDE.md 가 섞여 들어오면 claudeMdExcludes 로 뺄 수 있습니다(아래).
잘 쓰는 법 — 짧고 구체적으로
언제 한 줄을 더하나 — 원문은 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./init 의 대화형 흐름 (CLAUDE_CODE_NEW_INIT)
/init 실행 전에 환경 변수 CLAUDE_CODE_NEW_INIT 를 1 로 두면, 무엇을 만들지(CLAUDE.md 파일·스킬·훅) 묻고, 서브에이전트로 코드를 살펴본 뒤 빈 곳을 되묻고, 파일을 쓰기 전에 검토할 제안을 먼저 보여 줍니다. 이 상태에서 개인용 선택지를 고르면 CLAUDE.local.md 를 만들고 .gitignore 에 넣어 줍니다. 셸에서 설정하거나 설정 파일의 env 블록에 넣습니다.
가져오기(@) — 다른 파일을 지침에 끼워 넣기
무엇인가 — CLAUDE.md 안에 @경로 를 쓰면 그 파일을 펼쳐서 함께 읽힙니다. 상대 경로·절대 경로 모두 됩니다. 상대 경로는 작업 폴더가 아니라 가져오기를 쓴 그 파일을 기준으로 찾습니다. 가져온 파일이 또 다른 파일을 가져올 수 있고, 최대 4단계까지입니다.
See @README for project overview and @package.json for available npm commands for this project. # Additional Instructions - git workflow @docs/git-instructions.md # Individual Preferences - @~/.claude/my-project-instructions.md
뜻: 프로젝트 개요는 README 를, 쓸 수 있는 명령은 package.json 을 보라 / git 작업 방법은 docs/git-instructions.md / 개인 선호는 홈 폴더의 파일에서 가져온다.
왜 쓰나 — 긴 파일을 주제별로 나눠 관리하기 좋고, 이미 있는 문서(README 등)를 두 번 쓰지 않아도 됩니다. 단, 컨텍스트 비용은 줄지 않습니다. 가져온 파일은 가져온 CLAUDE.md 와 함께 매번 읽히기 때문입니다. 줄이려면 규칙 폴더의 paths 나 스킬을 씁니다.
GOAL.md)을 하나 두고, 프로젝트 CLAUDE.md 에 @GOAL.md 한 줄을 넣습니다. 그러면 리더와 팀원 모두 시작할 때 같은 목표를 읽습니다. 목표 파일 양식은 2장, 따라 하기는 활용편 1에 있습니다. 가져온 파일도 매번 읽히니 짧게 유지합니다.주의할 점
- 여러 워크트리에서 쓰기:
.gitignore한CLAUDE.local.md는 그것을 만든 워크트리(같은 저장소를 여러 작업 폴더로 꺼낸 복사본)에만 있습니다. 여러 워크트리에서 같은 개인 지침을 쓰려면 위 예처럼 홈 폴더의 파일을 가져옵니다. - 바깥 파일 승인: 프로젝트 지침이 작업 폴더 밖의 파일을 가져오면, 처음 한 번 Claude Code 가 승인 창으로 파일 목록을 보여 줍니다. 남이 공유 프로젝트에 올린 파일로부터 나를 지키기 위해서입니다. 거절하면 그 가져오기는 꺼진 채로 남고 창은 다시 뜨지 않습니다.
~/.claude/CLAUDE.md같은 사용자 범위 파일은 내가 쓴 것이라 이 창 없이 읽습니다(Cowork 데스크톱 세션은 예외).
경로 표기의 세부 규칙
- 경로에 공백이 있으면 공백마다 앞에 역슬래시를 붙입니다:
- API conventions @Design\ Docs/api-conventions.md. 역슬래시가 없으면 첫 공백에서 경로가 끝나고, 따옴표로 감싼 경로는 아예 가져오지 않습니다. - 가져오기 해석은 마크다운 코드 표시(백틱
`)와 코드 블록 안을 건너뜁니다. 가져오지 않고 경로를 글로만 적고 싶으면`@README`처럼 백틱으로 감쌉니다. - Cowork 데스크톱 세션에서는 사용자 범위 파일이 세션 작업 폴더 밖을 가리키는 가져오기를 건너뛰고, 심볼릭 링크·하드 링크인
~/.claude/CLAUDE.md도 건너뜁니다.
규칙 폴더 .claude/rules/ — 주제별로 나누고 필요할 때만
무엇인가 — 프로젝트가 커지면 지침을 .claude/rules/ 폴더에 주제별 파일로 나눌 수 있습니다. 파일 하나에 주제 하나, 이름은 testing.md·api-design.md 처럼 내용이 보이게 짓습니다. 하위 폴더(frontend/, backend/)로 묶어도 모든 .md 를 찾아 읽습니다.
your-project/ ├── .claude/ │ ├── CLAUDE.md # 프로젝트 기본 지침 │ └── rules/ │ ├── code-style.md # 코드 스타일 │ ├── testing.md # 테스트 약속 │ └── security.md # 보안 요구
왜 쓰나 — 필요한 파일을 만질 때만 읽히게 — 규칙 파일 맨 위에 paths 를 적으면, Claude 가 그 패턴에 맞는 파일을 읽거나·쓰거나·고칠 때만 그 규칙이 컨텍스트에 들어옵니다. 잡음이 줄고 컨텍스트를 아낍니다. paths 가 없는 규칙은 시작할 때 .claude/CLAUDE.md 와 같은 우선순위로 읽힙니다.
--- paths: - "src/api/**/*.ts" --- - Validate request bodies with the zod schemas in src/api/schemas/ - Every new endpoint needs an entry in openapi.yaml, CI fails without it
| 패턴 | 맞는 파일 |
|---|---|
**/*.ts | 어디에 있든 .ts 파일 |
src/**/* | src/ 아래 모든 파일 |
*.md | 어디에 있든 .md 파일 |
/*.md | 기준 폴더 바로 아래 .md 만 |
src/components/*.tsx | 그 폴더 바로 아래 .tsx 만 |
뜻(왼쪽 예): src/api/ 아래 TypeScript 파일을 다룰 때만 — 요청 내용은 정해 둔 zod 스키마로 검사하고, 새 엔드포인트는 openapi.yaml 에 꼭 적는다. ** 는 "몇 단계 아래 폴더든"이라는 뜻입니다.
내 모든 프로젝트에 쓰는 규칙 — ~/.claude/rules/ 에 둔 규칙은 내 컴퓨터의 모든 프로젝트에 적용됩니다(사용자 범위). 사용자 규칙이 먼저, 프로젝트 규칙이 나중에 읽히지만 어느 쪽도 다른 쪽을 덮어쓰지 않습니다. 둘이 어긋나면 Claude 가 아무거나 따를 수 있으니 서로 맞춰 둡니다.
규칙 파일 세부 — 기준 폴더·중괄호·심볼릭 링크
- 기준 폴더: 프로젝트 규칙은 그
.claude폴더가 있는 폴더, 사용자 규칙은 세션의 주 작업 폴더가 기준입니다. 옆 워크트리 파일에도 적용하려면 그 워크트리에서 시작하거나/cd로 옮깁니다. - 여러 패턴: 목록으로 여러 개, 중괄호로 확장자 여러 개(
"src/**/*.{ts,tsx}"). 한 규칙의paths전체가 펼친 패턴 1,000개·4 MiB 예산을 나눠 씁니다. - 앞머리 정보(frontmatter, 파일 맨 위
---사이)에서 Claude Code 가 읽는 필드는paths뿐입니다. YAML 이 깨지면paths없는 규칙처럼 읽히며,claude --debug로 오류를 봅니다. - 여러 프로젝트에 공유:
.claude/rules/는 심볼릭 링크(다른 곳의 파일·폴더를 가리키는 바로가기)를 지원합니다. 예:ln -s ~/shared-claude-rules .claude/rules/shared. 작업 폴더 밖을 가리키는 링크는 바깥 가져오기처럼 프로젝트마다 한 번 승인을 받아야 하고, 승인 후에도paths없는 것만 읽힙니다. 승인 없이 공유하려면~/.claude/rules/에 둡니다. 네트워크 경로를 가리키는 링크는 따라가지 않습니다. --setting-sources에서project를 빼면 프로젝트 규칙을 건너뜁니다(v2.1.211 이전에는 필요할 때 읽는 규칙은 그래도 읽혔음).
AGENTS.md — 여러 에이전트 도구가 함께 읽는 지침 파일
무엇인가 — AGENTS.md 는 특정 회사 제품이 아닌 오픈 형식입니다. 원문은 "에이전트용 README"라고 부르며 6만 개가 넘는 오픈소스 프로젝트가 쓴다고 합니다. 정해진 필드는 없고 보통 마크다운으로 씁니다. 개요, 빌드·테스트 명령, 코드 스타일, 테스트 방법, 보안 주의처럼 "새 팀원에게 말해 줄 것"을 적습니다. 지금은 Linux Foundation 아래 Agentic AI Foundation 이 관리합니다.
Claude Code 는 언제 AGENTS.md 를 읽나 — 기본으로는 작업 폴더나 그 위 폴더에 CLAUDE.md(·.claude/CLAUDE.md·CLAUDE.local.md)가 없을 때만 AGENTS.md 를 읽습니다. ~/.claude/CLAUDE.md, 조직 CLAUDE.md, .claude/rules/ 는 이 판단에 들어가지 않고 AGENTS.md 와 함께 읽힙니다.
| 저장소에 있는 것 | Claude 가 읽는 것 |
|---|---|
| AGENTS.md 만 (CLAUDE.md·CLAUDE.local.md 없음) | AGENTS.md |
| AGENTS.md 와 CLAUDE.md(또는 CLAUDE.local.md) | CLAUDE.md 만 |
AGENTS.md 를 가져오는(@AGENTS.md) CLAUDE.md | CLAUDE.md 와, 가져오기로 들어온 AGENTS.md |
어떻게 쓰나 — 여러 도구가 한 파일을 나눠 쓰기 — 프로젝트에 CLAUDE.md 도 있어야 한다면, AGENTS.md 옆 CLAUDE.md 맨 위에 @AGENTS.md 를 두고 그 아래에 Claude 전용 지시만 더합니다. Claude 는 가져온 파일을 먼저, 나머지를 그다음에 읽습니다.
@AGENTS.md ## Claude Code Use plan mode for changes under `src/billing/`.
뜻: AGENTS.md 를 먼저 읽고, Claude Code 에만 해당하는 지시로 "src/billing/ 아래를 바꿀 땐 계획 모드를 쓴다"를 더합니다. Claude 전용 내용이 필요 없으면 ln -s AGENTS.md CLAUDE.md 처럼 바로가기로 묶어도 되지만, 팀에 Windows 사용자가 있으면 가져오기 쪽을 쓰라고 원문은 권합니다.
Project instructions 설정 · 버전 조건 · CLAUDE.md 와 다른 점
/config 의 Project instructions(프로젝트 지침) 값으로 읽을 파일을 바꿉니다.
| 값 | 읽는 것 |
|---|---|
claude-md-or-agents-md (기본) | CLAUDE.md, 없으면 AGENTS.md |
claude-md-and-agents-md | 둘 다 — 폴더마다 CLAUDE.md 먼저, AGENTS.md 나중. 이미 읽은 AGENTS.md 는 두 번 읽지 않음 |
claude-md | CLAUDE.md 만 |
managed-only | 시작 때는 조직 CLAUDE.md 와 자동 메모리만. 하위 폴더 지침·paths 규칙은 필요할 때 읽힘 |
- 설정 파일로는
~/.claude/settings.json등의pluginConfigs→cc-plugin-agents-md@builtin→options.instructionFiles에 적습니다(프로젝트·로컬 설정 파일에서는 무시). v2.1.285 이전 ID 는agents-md@builtin. - AGENTS.md 를 직접 읽으려면 v2.1.277 이상. v2.1.281 이전에는 Amazon Bedrock·원격 측정 꺼짐 등 일부 세션이 CLAUDE.md 만 읽었습니다.
/plugin으로 내장 플러그인을 끈 경우, 업그레이드 직후 첫 세션에서도 못 읽을 수 있습니다 — 이때는 CLAUDE.md 에서@AGENTS.md로 가져옵니다. - 세션 시작 때 위 폴더들의
AGENTS.md·.claude/AGENTS.md를 읽고(대화창에no CLAUDE.md found; AGENTS.md loaded: …표시), 하위 폴더의 AGENTS.md 는 그 폴더에 CLAUDE.md 류가 없을 때 Read 도구로 그 폴더 파일을 열면 읽습니다.AGENTS.local.md,AGENTS.override.md,.agents/아래는 읽지 않습니다. - 설정으로 읽은 AGENTS.md 는 CLAUDE.md 와 달리
InstructionsLoaded훅이 울리지 않고,--add-dir폴더의 AGENTS.md 는 읽지 않으며, 바깥 파일 가져오기는 이미 승인한 경우에만 묻지 않고 읽습니다. - 예전 우회 방법 정리:
@AGENTS.md를 가져오는 CLAUDE.md 는 그대로 둬도 두 번 읽지 않음 / "AGENTS.md 를 읽어"라고 말로만 적은 CLAUDE.md 는 지우거나 가져오기로 바꿈 / AGENTS.md 를 출력하는SessionStart훅은 지움(두 번 들어감). - 다른 도구 지침 옮기기:
/init은.cursor/rules/·.cursorrules·.github/copilot-instructions.md를 읽어 반영합니다(CLAUDE_CODE_NEW_INIT=1이면 AGENTS.md·.windsurf/rules/등도)./import는 다른 에이전트의 설정을 한 번 복사해 옵니다.
큰 팀 관리 — 조직 지침과 강제 설정 나누기
무엇인가 — 회사가 여러 팀에 Claude Code 를 배포할 때는 조직 범위 CLAUDE.md를 중앙에서 관리합니다. 이 파일은 그 컴퓨터의 모든 사용자, 모든 저장소에 적용되고, 개인이 claudeMdExcludes 로 뺄 수 없습니다. 만드는 순서는 두 단계입니다.
- 조직 위치에 파일 만들기macOS
/Library/Application Support/ClaudeCode/CLAUDE.md· Linux·WSL/etc/claude-code/CLAUDE.md· WindowsC:\Program Files\ClaudeCode\CLAUDE.md - 설정 관리 도구로 배포MDM, 그룹 정책(Group Policy), Ansible 같은 도구로 직원 컴퓨터에 나눠 줍니다.
왜 나눠야 하나 — 안내와 강제는 다른 도구 — 원문은 조직 CLAUDE.md 를 "안내"에, 관리 설정(managed settings)을 "기술적 강제"에 쓰라고 분명히 나눕니다. 설정 규칙은 Claude 가 무엇을 하려 하든 프로그램이 막지만, CLAUDE.md 는 행동을 이끌 뿐 단단한 강제 층이 아닙니다.
| 하고 싶은 것 | 둘 곳 |
|---|---|
| 특정 도구·명령·파일 경로 막기 | 관리 설정 permissions.deny |
| 샌드박스(격리 실행) 강제 | 관리 설정 sandbox.enabled |
| 환경 변수, API 제공자 경로 | 관리 설정 env |
| 로그인 방법·조직 제한 | 관리 설정 forceLoginMethod, forceLoginOrgUUID |
| 코드 스타일·품질 기준 | 조직 CLAUDE.md |
| 데이터 취급·규정 준수 안내 | 조직 CLAUDE.md |
| Claude 에게 주는 행동 지시 | 조직 CLAUDE.md |
다른 팀 지침 빼기 — 큰 모노레포에서는 위 폴더의 CLAUDE.md 에 내 일과 상관없는 다른 팀 지시가 있을 수 있습니다. claudeMdExcludes 설정에 경로·패턴을 적어 그 파일을 건너뜁니다. 내 컴퓨터에만 적용하려면 .claude/settings.local.json 에 둡니다.
{
"claudeMdExcludes": [
"**/monorepo/CLAUDE.md",
"/home/user/monorepo/other-team/.claude/rules/**"
]
}
claudeMd 설정 키 · 제외 세부
- 별도 파일 대신
managed-settings.json안에"claudeMd": "Always run `make lint` before committing.\nNever push directly to main."처럼 직접 넣을 수 있습니다. 우선순위는 조직 CLAUDE.md 파일과 같고(사용자·프로젝트보다 먼저 읽힘), 관리·정책 설정에서만 통합니다 — 사용자·프로젝트·로컬 설정에 넣으면 효과가 없습니다. - 개발자가 CLAUDE.md 읽기를 아예 끄고 세션을 시작하면 조직 내용도 읽히지 않습니다. 그래서 반드시 막을 것은
permissions.deny같은 관리 설정으로 겁니다. claudeMdExcludes패턴은 절대 경로에 glob 으로 맞추며, 사용자·프로젝트·로컬·관리 설정 어디에 둬도 되고 목록은 층끼리 합쳐집니다. 심볼릭 링크로 들어온 규칙 파일은 링크 쪽 경로나 대상 경로 어느 쪽 패턴이든 맞으면 빠집니다(v2.1.239 이전엔 대상 경로만).
회사 팀에서 범위·보안을 어떻게 짜는지는 9장 「회사 팀」에서 이어서 다룹니다.
문제 해결 — 지침을 안 따를 때 확인할 것
먼저 알아 둘 것 — CLAUDE.md 내용은 시스템 프롬프트(AI 에게 가장 먼저 주는 기본 지시)의 일부가 아니라, 그 뒤에 오는 사용자 메시지로 전달됩니다. Claude 는 읽고 따르려 하지만, 특히 흐릿하거나 서로 어긋나는 지시는 꼭 지킨다는 보장이 없습니다. 아래 순서로 원인을 좁힙니다.
/context all 을 실행해 Memory files 목록에 그 CLAUDE.md·CLAUDE.local.md 가 있는지 봅니다. 없으면 Claude 는 그 파일을 볼 수 없습니다. Instruction file not loaded(지침 파일을 못 읽음) 알림이 떴다면 그 안내를 따릅니다. 하위 폴더 CLAUDE.md 는 시작 때가 아니라 필요할 때 읽혀서 이 목록에 없고, 읽힐 때 터미널에 Loaded 줄이 뜹니다./memory 로 합니다.증상: 지침이 많아졌고, 일부가 안 지켜집니다.
- 200줄이 넘는 파일은 컨텍스트를 더 쓰고 지키는 정도가 떨어질 수 있습니다. 권장 길이를 넘으면 시작할 때와
/status에서 경고가 뜹니다. 파일 각각은 괜찮아도 합계가 한도를 넘으면 경고가 뜹니다(CLAUDE.md·규칙 파일·@가져오기가 각각 한 파일). - 해결: 일부 파일에만 필요한 지시는
paths규칙으로, 매 세션 필요 없는 것은 덜어 냅니다.@로 쪼개는 것은 정리에는 좋지만 컨텍스트는 줄이지 않습니다. /doctor점검은 저장소에 올린 CLAUDE.md 에서 코드만 봐도 알 수 있는 내용(폴더 구조, 의존성 목록, 구조 개요)을 덜어 내자고 제안하고, 함정·이유·기본값과 다른 약속은 남깁니다.
증상: AGENTS.md 가 있는데 Claude 가 그 내용을 모릅니다.
- 작업 폴더나 그 위에
CLAUDE.md·.claude/CLAUDE.md·CLAUDE.local.md가 있는지(~/.claude/CLAUDE.md제외) — 있으면 그쪽을 대신 읽습니다. claude --version으로 버전 확인(조건은 위 접힌 상자)./config에서 Project instructions 가claude-md나managed-only가 아닌지.
읽혔는지는 /memory 목록에 경로가 있는지로 봅니다. 해결이 어려우면 AGENTS.md 옆에 @AGENTS.md 를 가져오는 CLAUDE.md 를 둡니다.
증상: /compact 뒤 지시가 사라진 것 같습니다.
- 프로젝트 맨 위 CLAUDE.md 는 압축 뒤 디스크에서 다시 읽어 넣습니다.
- 사라졌다면 ① 대화로만 한 지시였거나 ② 아직 다시 안 읽힌 하위 폴더 CLAUDE.md 이거나 ③ 그 뒤로 맞는 파일을 안 만진
paths규칙입니다. - 해결: 계속 지켜야 할 대화 속 지시는 CLAUDE.md 에 옮겨 적습니다.
| 명령 | 하는 일 |
|---|---|
/context all | 지금 읽힌 지침 파일(Memory files) 목록 확인 |
/memory | 사용자·프로젝트 범위의 CLAUDE.md·CLAUDE.local.md 목록, 열어서 고치기(없는 파일은 만들어 줌), 자동 메모리 켜고 끄기 |
/doctor | 설치·확장·CLAUDE.md 등 설정 점검. CLAUDE.md 에서 덜어 낼 것 제안 |
/doctor prompt-audit | 지침 파일의 낡은 지시·없는 파일 참조·서로 어긋나는 내용 찾기. 보고서와 수정안만 내고, 내가 적용하라고 하기 전에는 파일을 바꾸지 않음 |
/memory 로 파일을 열어 고칩니다. 팀원 모두가 읽어야 할 규칙이라면 프로젝트 CLAUDE.md 쪽이 맞습니다.점검 명령의 버전 조건 · 하위 폴더 크기 한도 · 그 밖의 방법
/doctor prompt-audit는 v2.1.283 이상. 기본 대상은 CLAUDE.md·CLAUDE.local.md·AGENTS.md 와.claude/·~/.claude/아래 규칙·스킬·명령·서브에이전트·출력 스타일이며,/doctor prompt-audit .claude/skills/deploy처럼 경로를 주면 그것만 봅니다. 내장/claude-api스킬로 돌아가므로skillOverrides·disableBundledSkills로 그 스킬을 끄면 쓸 수 없습니다.- Claude Code 는 4 MiB 가 넘는 파일을 건너뜁니다.
- 하위 폴더 CLAUDE.md 끝부분이 무시될 때: 필요할 때 읽히는 파일(하위 폴더 CLAUDE.md·CLAUDE.local.md 와 그 가져오기, 하위 폴더
.claude/rules/,paths규칙)은 파일당 글자 수 한도를 넘으면 앞부분만 들어가고, 나머지는 Read 도구로 읽으라는 메모로 끝납니다. 한도: 200K 컨텍스트 창 40,000자 / 1M 창 Claude Opus 4.6·Sonnet 4.6 은 200,000자, 그 뒤 모델은 150,000자.wc -m path/to/CLAUDE.md로 글자 수를 세어 비교합니다(v2.1.309 이전엔 이 한도 없음). - Claude Code 기본 git 안내와 부딪치면
includeGitInstructions로 끄고attribution으로 서명 문구를 정합니다. - 시스템 프롬프트 수준의 지시가 필요하면 시작할 때
--append-system-prompt로 줍니다(스크립트·자동화에 적합). InstructionsLoaded훅으로 어떤 CLAUDE.md·규칙 파일이 언제, 왜 읽혔는지 기록할 수 있습니다 —paths규칙이나 하위 폴더 지침을 디버깅할 때 유용합니다.- 새 하위 폴더 CLAUDE.md 를 시험할 때는 Claude 에게 쓰게 하지 말고 셸에서 직접 만든 뒤, Claude 에게 그 폴더의 파일을 읽게 합니다.
지침과 기억을 안 따를 때 전체를 순서대로 점검하는 실습은 활용편 10에 있습니다.
- 세션은 늘 빈 컨텍스트로 시작합니다. 사람이 쓴 지침 파일(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로 덜어 낼 것을 찾습니다.
출처: https://code.claude.com/docs/en/memory · https://agents.md · https://code.claude.com/docs/en/best-practices · https://code.claude.com/docs/en/agent-teams (Context and communication) (수집일 2026-11-10)
필요할 때 읽히는 층 — 스킬
3장의 지침 파일은 매 세션 처음부터 읽힙니다. 그런데 팀의 배포 순서, 장애 대응 절차, 보고서 쓰는 법처럼 길지만 가끔 필요한 지식까지 거기에 넣으면 모든 일이 무거워집니다. 이런 것을 폴더로 묶어 필요할 때만 꺼내 읽히는 장치가 스킬입니다.
- 스킬이 무엇이고, 항상 읽히는 CLAUDE.md 와 무엇이 다른지
- 무엇을 CLAUDE.md 에, 무엇을 스킬에 둘지 고르는 기준
SKILL.md만들기, 둘 곳(범위), 부르는 법(직접·자동)- 팀 전원이 같은 스킬을 쓰게 공유하는 법, 안 불릴 때 확인할 것
- 스킬이란 — 필요할 때만 펼치는 절차서 — 지침 파일과 무엇이 다른지
- 언제 무엇에 — CLAUDE.md · 규칙 · 스킬 · 훅 — 적고 싶은 것을 어디에 둘지
만들기·둘 곳·부르는 법은 첫 스킬을 만들 때 차례로 읽으면 됩니다. 🔧 표시가 붙은 접힌 상자는 필요할 때만 펼치세요.
스킬이란 — 필요할 때만 펼치는 절차서
무엇인가 — 스킬(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 하나
무엇이 필요한가 — 스킬 하나는 폴더 하나이고, 그 안에 SKILL.md 가 꼭 있어야 합니다. SKILL.md 는 두 부분으로 됩니다.
name)이 내가 치는 명령이 되고, description(설명)은 Claude 가 언제 이 스킬을 자동으로 불러올지 판단하는 근거가 됩니다.mkdir -p ~/.claude/skills/summarize-changes---
description: Summarizes uncommitted changes and flags anything risky. Use when the user asks what changed, wants a commit message, or asks to review their diff.
---
## Current changes
!`git diff HEAD`
## Instructions
Summarize the changes above in two or three bullet points, then list any risks you notice such as missing error handling, hardcoded values, or tests that need updating. If the diff is empty, say there are no uncommitted changes.
뜻: 설명 — "아직 커밋하지 않은 변경을 요약하고 위험한 점을 짚는다. 무엇이 바뀌었는지 묻거나, 커밋 메시지를 원하거나, 변경 검토를 부탁할 때 쓴다." 본문 — 아래 변경을 두세 줄로 요약하고, 빠진 오류 처리·박아 넣은 값·고쳐야 할 테스트 같은 위험을 적는다. !`git diff HEAD` 줄은 Claude Code 가 그 명령을 먼저 실행해 결과로 바꿔 넣는 자리입니다(동적 맥락 주입).
claude 로 시작합니다. 설명에 맞는 질문 What did I change?(뭘 바꿨지?)로 자동 호출을 보거나, /summarize-changes 로 직접 부릅니다. 어느 쪽이든 짧은 요약과 위험 목록이 나오면 성공입니다.앞머리에서 자주 쓰는 필드 — 모든 필드는 선택이고, description 만 권장입니다. 필드 이름이 표와 조금이라도 다르면 Claude Code 는 오류 없이 무시합니다.
| 필드 | 하는 일 |
|---|---|
name | / 메뉴에 보이는 명령 이름. 없으면 폴더 이름 |
description | 무엇을 하고 언제 쓰는지. Claude 가 부를지 판단하는 근거. 핵심 쓰임을 앞에 둠 |
when_to_use | 부를 때를 더 알려 주는 말(예: 이런 요청이 오면). 설명 뒤에 붙음 |
disable-model-invocation | true 면 Claude 가 스스로 못 부름 — 내가 /이름 으로만 |
user-invocable | false 면 Claude 만 부름 — / 메뉴에서 숨김 |
allowed-tools | 이 스킬을 부른 차례 동안 허락 없이 쓸 도구. 다음 메시지를 보내면 풀림 |
context: fork | 서브에이전트(맡긴 일을 자기 컨텍스트에서 하고 결과만 돌려주는 도우미)에서 따로 실행 |
paths | 이 패턴의 파일을 다룰 때만 자동으로 불러옴(규칙 폴더와 같은 형식) |
두 종류의 내용 — 원문은 부르는 방식에 따라 스킬 내용을 나눠 생각하라고 합니다.
약속·패턴·스타일 안내·업무 지식처럼, 지금 하는 일에 함께 적용할 지식. 대화 안에서 바로 쓰입니다.
예:
api-conventions — API 이름 짓기, 오류 형식, 요청 검사배포·커밋·코드 생성처럼 특정 행동의 단계별 지시. Claude 가 알아서 하기보다 내가
/이름 으로 부르는 경우가 많아 disable-model-invocation: true 를 붙입니다.예:
deploy — 테스트 → 빌드 → 배포--- name: release description: Cut a new release. Bumps the version, writes the changelog entry, tags it and pushes the tag so CI can publish. disable-model-invocation: true --- 1. Make sure you're on main with a clean tree. If not, stop and ask. 2. Run `pnpm changeset version` and commit the result. 3. Summarize the PRs merged since the last tag into CHANGELOG.md, one line each, user-facing changes only. 4. Tag `v<new version>` and push the tag. CI publishes from there, never publish from your machine.
뜻: 새 버전을 낸다 — ① main 에서 깨끗한 상태인지 확인, 아니면 멈추고 묻기 ② 버전 올리기 명령 실행 후 커밋 ③ 지난 태그 이후 합쳐진 변경을 사용자에게 보이는 것만 한 줄씩 변경 기록에 요약 ④ 태그를 붙여 올리기, 배포는 CI 가 하고 내 컴퓨터에서는 하지 않기. 실제로 출시라는 되돌리기 어려운 일을 하므로 Claude 가 스스로 시작하지 못하게 막았습니다.
짧게 쓰기 — 스킬이 한 번 불리면 그 내용은 이후 차례에도 컨텍스트에 남으므로, 한 줄 한 줄이 계속 드는 토큰(AI 가 읽고 쓰는 글의 양을 세는 단위 — 비용·속도의 기준) 비용입니다. "어떻게·왜"를 늘어놓기보다 "무엇을 할지"를 적고, CLAUDE.md 와 같은 기준으로 줄입니다. SKILL.md 는 500줄 아래로 두고, 긴 자료는 보조 파일로 뺍니다.
my-skill/ ├── SKILL.md # 꼭 필요 — 개요와 안내 ├── reference.md # 자세한 API 문서 — 필요할 때 읽음 ├── examples.md # 사용 예 — 필요할 때 읽음 └── scripts/ └── helper.py # 도우미 스크립트 — 읽지 않고 실행
SKILL.md 안에 "자세한 API 는 reference.md, 예시는 examples.md"처럼 각 보조 파일에 무엇이 있고 언제 읽을지 적어 두면, Claude 가 필요할 때만 그 파일을 엽니다.
앞머리 세부 · 고치면 바로 반영되나
- 앞머리는 여는
---가 파일 첫 줄일 때만 읽습니다. YAML 이 깨지면 필드 없이 본문만 읽힙니다. 참·거짓 값은true/false외에yes·no·on·off·1·0도 됩니다. description과when_to_use를 합친 글은 스킬 목록에서 1,536자로 잘립니다.description이 없으면 본문의 첫 줄을 씁니다.- 그 밖의 필드:
argument-hint(자동 완성 때 인자 힌트),arguments(이름 붙인 인자),disallowed-tools,model,effort,agent,background,hooks,shell,metadata,license,compatibility. - Claude Code 는 스킬 폴더의 파일 변경을 지켜보다가 세션을 다시 시작하지 않아도 반영합니다(
~/.claude/skills/, 프로젝트.claude/skills/,--add-dir폴더 안). 세션 시작 때 없던 최상위 스킬 폴더를 새로 만들었다면/reload-skills를 실행합니다. !`명령`동적 맥락 주입은 claude.ai 계정에서 동기화된 스킬에서는 내 컴퓨터에서 실행되지 않습니다(v2.1.228 이상).- 스킬 지우기: 개인·프로젝트 스킬은 그 폴더를 지웁니다. 남겨 두되 Claude 가 스스로 못 부르게 하려면
disable-model-invocation: true를 넣습니다.
둘 곳 — 범위에 따라 누가 쓰는지가 정해진다
무엇인가 — 지침 파일처럼 스킬도 저장한 위치가 어느 세션에서 읽히는지를 정합니다. 홈 폴더에 두면 내 모든 프로젝트에서, 저장소에 커밋하면 그 저장소에서 일하는 모두가, 플러그인이나 관리 설정으로 배포하면 팀 전체가 씁니다.
| 위치 | 경로 | 읽히는 곳 |
|---|---|---|
| 기업 (Enterprise) | 관리 설정 폴더 안 .claude/skills/<이름>/SKILL.md | 조직이 배포한 컴퓨터의 모든 사용자 |
| 개인 (Personal) | ~/.claude/skills/<이름>/SKILL.md | 이 컴퓨터의 내 모든 프로젝트 (Cowork·클라우드 세션은 제외) |
| 프로젝트 (Project) | .claude/skills/<이름>/SKILL.md | 이 저장소의 세션. 커밋하면 팀도 받음 |
| 하위 폴더 (Nested) | <하위폴더>/.claude/skills/<이름>/SKILL.md | 그 폴더에서 시작한 세션, 또는 Claude 가 그 폴더 파일을 다룰 때부터 |
| 플러그인 (Plugin) | <플러그인>/skills/<이름>/SKILL.md | 플러그인을 켠 곳, /플러그인:스킬 이름으로 |
| claude.ai 계정 | claude.ai 계정에서 켠 스킬 | Cowork·클라우드 세션, 그 계정으로 로그인한 터미널 세션 |
모노레포·워크트리·클라우드 세션에서 읽히는 스킬
- 위 폴더: 시작한 폴더와 그 위 폴더(저장소 맨 위까지)의
.claude/skills/를 읽습니다.packages/frontend/에서 시작해도 맨 위 스킬이 들어옵니다. - 하위 폴더: 시작 위치 아래의 스킬은 시작 때 읽지 않고, Claude 가 그 폴더 파일을 처음 읽거나 고칠 때 들어옵니다. 그 전엔
/메뉴에 없습니다. 미리 쓰려면/add-dir(v2.1.257 이상). 이름이 같으면/deploy는 맨 위 스킬,/apps/web:deploy는 하위 스킬입니다. - 워크트리: 연결된 git 워크트리에서는 워크트리 맨 위까지만 찾고, v2.1.277 이상에서는 워크트리 맨 위에
.claude/skills가 없으면 원래 저장소의 프로젝트 스킬을 읽습니다. - Cowork·클라우드 세션: 내 컴퓨터의
~/.claude/skills/를 읽지 않고 claude.ai 계정에서 켠 스킬을 씁니다. 개인 스킬을 거기서도 쓰려면 claude.ai 계정에서 켜거나(프로젝트 클라우드 스레드는 이 방법만), 저장소.claude/skills/에 커밋합니다. 데스크톱 예약 작업은 내 컴퓨터에서 돌아~/.claude/skills/를 읽습니다. - 이름 충돌 세부: 내 스킬이 내장 스킬이나 내장 명령과 이름이 같으면 내 스킬이 대신하지만 별칭(예:
/review,/cost)은 원래 것을 실행합니다. 스킬과.claude/commands/파일이 같은 이름이면 스킬이 이깁니다.--add-dir폴더의 같은 이름 스킬은/접두어:이름으로 실행합니다(v2.1.309 이상). 폴더 이름synced·anthropic-skills는 예약되어 있습니다.
부르는 법 — 직접 부르기와 자동으로 불리기
두 가지 길 — 기본으로는 나와 Claude 모두 어떤 스킬이든 부를 수 있습니다. 내가 메시지 맨 앞에 /스킬-이름 을 치면 바로 실행되고, Claude 는 대화가 스킬의 설명과 맞으면 스스로 불러옵니다.
description 에 사람들이 실제로 쓰는 말을 넣습니다.누가 부를지 정하기 — 앞머리 두 필드로 막을 수 있습니다.
| 앞머리 | 내가 부름 | Claude 가 부름 | 컨텍스트에 들어가는 때 |
|---|---|---|---|
| (기본) | 예 | 예 | 설명은 항상, 본문은 불렸을 때 |
disable-model-invocation: true | 예 | 스스로는 못 함 | 설명도 안 들어감, 본문은 불렸을 때 |
user-invocable: false | 아니오 | 예 | 설명은 항상, 본문은 불렸을 때 |
- 되돌리기 어렵거나 때를 내가 정할 일(커밋, 배포, 메시지 보내기)은
disable-model-invocation: true. 원문: "코드가 준비돼 보인다고 Claude 가 배포를 결정하길 원하진 않을 것입니다." Claude 가 그래도 부르려 하면 Claude Code 가 막고, 다른 방법으로 같은 단계를 흉내 내지 말라고 지시합니다. - 명령이 아닌 배경지식(예: 옛 시스템이 어떻게 돌아가는지)은
user-invocable: false— Claude 만 필요할 때 씁니다.
이름을 어디에 쓰나 — 메시지 맨 앞의 /deploy staging 은 바로 실행됩니다. go ahead and /deploy to staging 처럼 문장 중간에 쓰면 바로 실행되지는 않고, 그 메시지에 한해 "써도 된다"는 허락이 됩니다. 실행 허락 없이 스킬 이야기만 하려면 슬래시를 빼고 씁니다.
인자 넘기기 — 스킬 이름 뒤에 쓴 글은 본문의 $ARGUMENTS 자리에 들어갑니다. 원문 예에서 본문이 Fix GitHub issue $ARGUMENTS following our coding standards. 이면 /fix-issue 123 은 "우리 기준대로 GitHub 이슈 123 을 고쳐라"가 됩니다. 위치별로 $ARGUMENTS[0] 또는 $0, $1 처럼 나눠 받을 수도 있습니다.
allowed-tools 로 준 도구 허락은 다음 메시지를 보내면 풀립니다. 남는 것은 지시이지 권한이 아닙니다.SKILL.md 위쪽에 둡니다.서브에이전트에서 실행 (context: fork) · 여러 스킬 한 번에
context: fork를 넣으면agent필드에 적은 종류의 새 서브에이전트가 스킬 내용을 지시로 받아 따로 실행합니다. 그 서브에이전트는 내 대화 기록을 보지 못하므로 스킬 지시만으로 일이 되도록 써야 합니다. "이 API 약속을 따르라" 같은 지침만 있고 할 일이 없으면 의미 있는 결과 없이 돌아옵니다.- 기본은 백그라운드 실행이라 그동안 나는 계속 일하고, 끝나면 결과가 대화에 도착합니다.
background: false면 그 차례에서 결과를 기다립니다. 백그라운드 실행은 좁은 도구 묶음으로 돌고, 그 편집은 체크포인트 밖이라/rewind로 되돌려지지 않으니 git 으로 되돌립니다. - 내장
Explore·Plan에이전트는 CLAUDE.md 없이 시작합니다.agent: Explore로 실행하는 스킬에는 필요한 것을 모두SKILL.md에 넣습니다. - 반대 방향: 서브에이전트 정의의
skills필드에 스킬을 적으면 그 서브에이전트가 시작할 때 스킬 전체 내용을 미리 넣습니다(6장). - 터미널에서는
/write-tests /fix-issue 123처럼 메시지 맨 앞에 스킬 여러 개를 쌓을 수 있고, 뒤의123이 각 스킬의 인자로 갑니다.claude -p·Agent SDK 에서는 첫 스킬만 읽힙니다. - 인자를 줬는데 본문에 받을 자리가 없으면 끝에
ARGUMENTS: <입력>이 붙습니다.
공유 — 팀 전원이 같은 방법으로 일하게
어떻게 나누나 — 원문은 받을 사람에 따라 세 가지를 듭니다.
.claude/skills/ 를 버전 관리(git)에 커밋 — 그 저장소에서 일하는 사람과 에이전트가 받습니다.플러그인 안에
skills/ 폴더를 만들어 여러 프로젝트에 나눠 줍니다.관리 설정(managed settings)으로 조직 전체에 배포합니다.
.claude/agents/<이름>.md)을 팀원으로 쓸 때, 그 정의의 skills 필드는 팀원에게 적용되지 않고 팀원은 프로젝트와 사용자 설정에서 스킬을 불러옵니다. 팀원 전원이 써야 할 스킬은 프로젝트 .claude/skills/ 에 둡니다.공유하기 전에 — 정말 효과가 있나 재 보기 — 원문은 스킬이 불렸다는 것은 Claude 가 찾았다는 뜻일 뿐, 의도대로 했다는 뜻은 아니라고 말합니다. 그래서 두 가지를 따로 잽니다 — 불려야 할 요청에서 불리는지, 불렸을 때 결과가 기대와 맞는지. 방법은 기준선 비교입니다.
- 실제 같은 요청 몇 개 모으기팀이 실제로 할 법한 부탁으로
- 스킬을 켜고, 끄고 각각 새 세션에서 돌리기새 세션이어야 스킬을 만들며 쌓인 대화가 빈틈을 가리지 않습니다. 끄는 방법은
skillOverrides에서"off" - 결과 비교스킬 덕분에 나아졌는지, 드는 토큰·시간만큼 값어치가 있는지
평가 도구 · 안 쓰는 스킬 찾기 · skillOverrides
- skill-creator 플러그인:
/plugin install skill-creator@claude-plugins-official로 설치한 뒤 "evaluate my summarize-changes skill with skill-creator" 처럼 부탁하면, 시험 사례(evals/evals.json)를 함께 쓰고, 사례마다 깨끗한 서브에이전트로 돌리고, 통과 여부와 근거(grading.json), 스킬 있음/없음 비교(benchmark.json), 두 버전 블라인드 비교, 설명 문구 조정 제안까지 해 줍니다. - 플러그인으로 내는 스킬은
claude plugin eval로 플러그인 있음/없음을 비교합니다(skillOverrides는 플러그인 스킬에 적용 안 됨). - /skill-doctor(v2.1.252 이상): 스킬마다 컨텍스트 비용과 사용 빈도를 보여 주고, 한 번도 안 불린 스킬과 끌 곳을 알려 줍니다. 목록에 있는 스킬은 쓰든 안 쓰든 매 차례 컨텍스트를 씁니다.
- skillOverrides: SKILL.md 를 고치지 않고 설정에서 보이는 정도를 정합니다 —
"on"(이름+설명),"name-only"(이름만),"user-invocable-only"(Claude 에게 숨김,/메뉴엔 있음),"off"(모두 숨김)./skills메뉴에서 Space 로 바꾸고 Esc 로.claude/settings.local.json에 저장합니다.
문제 해결 — 안 불릴 때, 너무 자주 불릴 때, 중간에 잊을 때
증상: 이 스킬을 쓸 것 같은데 Claude 가 안 씁니다.
- 설명(
description)에 사람들이 실제로 쓰는 말이 들어 있는지 봅니다. What skills are available?(쓸 수 있는 스킬이 뭐야?)라고 물어 목록에 있는지 봅니다.- 요청을 설명과 더 비슷하게 바꿔 말해 봅니다.
- 직접
/스킬-이름으로 불러 봅니다. /스킬-이름도 안 되면 폴더 이름에 쓸 수 없는 글자(예: 폭 없는 공백,<)가 있는지 봅니다.paths를 설정했다면, 다루는 파일이 Claude 의 현재 작업 폴더 안에 있는지 봅니다(옆 워크트리 파일은 맞지 않음).
앞머리 YAML 이 깨지면 /이름 은 되지만 Claude 가 설명으로 맞춰 보지 못합니다. --debug 로 오류를 봅니다.
증상: 원하지 않는 때에도 스킬이 불립니다.
- 설명을 더 구체적으로 좁힙니다.
- 직접 부를 때만 쓰려면
disable-model-invocation: true를 넣습니다.
증상: 첫 답에서는 따랐는데 나중에 안 따릅니다.
| 경우 | 해결 |
|---|---|
| 매번 지켜야 할 규칙을 건너뜀 | 훅으로 옮깁니다. 스킬과 함께 두려면 스킬의 hooks 앞머리에 정의 — 스킬을 부른 때부터 세션 끝까지 적용 |
| 판단해서 적용할 안내를 건너뜀 | 작업 전체에 걸리게 씁니다("고칠 때마다 테스트를 돌려"). 스킬 파일은 다음 차례에 다시 읽히지 않습니다 |
| 대화가 압축됨 | 스킬을 다시 부릅니다. 압축 뒤엔 앞부분만 남을 수 있으니 중요한 지시를 위쪽에 |
증상: 스킬이 많아진 뒤 몇몇이 잘 안 불립니다.
- 스킬 목록(이름+설명)에는 글자 예산이 있어, 넘치면 덜 쓰는 스킬부터 설명이 빠지고 이름만 남습니다. 예산은 모델 컨텍스트 창의 1% 입니다.
/doctor로 목록의 컨텍스트 비용을,/skill-doctor로 끌 만한 스킬을 찾습니다./context의 Skills 줄은 예산을 적용한 뒤의 크기입니다.- 설명은 핵심 쓰임을 앞에 두고 줄입니다(설명+
when_to_use는 1,536자 상한).
그 밖의 증상 — 설명 속 꺾쇠 · 개인 스킬이 사라짐 · 예산 늘리기
- 설명에
<>가<>로 보임:<branch>대신[branch]로 쓰거나argument-hint로 옮깁니다. - 개인 스킬 폴더가 사라짐:
~/.claude/skills/.trash/를 봅니다. 시간이 적힌 폴더에서 다시~/.claude/skills/로 옮기면 되고, 기본 30일 뒤 지워집니다(v2.1.280 이전manifest.json문제). - 목록 예산 늘리기:
skillListingBudgetFraction(예:0.02= 2%) 또는SLASH_COMMAND_TOOL_CHAR_BUDGET. 덜 중요한 스킬은skillOverrides에서"name-only". 설명 상한은skillListingMaxDescChars. 넘치면 디버그 로그(--debug)에 경고가 남습니다. - 앞머리 오류 찾기:
claude plugin validate .claude/skills(프로젝트) 또는claude plugin validate ~/.claude/skills(개인) — v2.1.233 이상.
스킬·지침을 안 따를 때 전체를 순서대로 점검하는 실습은 활용편 10에 있습니다.
- 스킬은 절차·지식을
SKILL.md가 든 폴더로 묶은 것입니다. 평소 컨텍스트에는 이름과 설명만 있고, 본문은 쓸 때만 읽힙니다 — 매 세션 전부 읽히는 CLAUDE.md 와 다른 점입니다. - 같은 지시·체크리스트·여러 단계 절차를 계속 붙여 넣거나, CLAUDE.md 의 한 부분이 절차로 커졌다면 스킬로 옮깁니다. 매 세션 필요한 사실은 CLAUDE.md, 일부 파일용은 규칙, 반드시 지킬 것은 훅.
- 만들기: 폴더 +
SKILL.md(앞머리description+ 본문 지시). 짧게, 500줄 아래, 긴 자료는 보조 파일로. - 둘 곳: 기업 · 개인
~/.claude/skills/· 프로젝트.claude/skills/(커밋하면 팀 공유) · 플러그인. 같은 이름이면 기업 > 개인 > 프로젝트. - 부르기: 메시지 맨 앞
/이름으로 직접, 또는 Claude 가 설명을 보고 자동으로. 되돌리기 어려운 일은disable-model-invocation: true로 나만 부르게. - 에이전트 팀의 팀원도 만들어질 때 프로젝트·사용자 스킬을 불러오므로, 팀 공용 절차는 프로젝트 스킬로 두면 모두가 같은 방법으로 일합니다.
- 안 불리면 설명의 단어부터 고칩니다. 중간에 잊으면 계속 지킬 지시로 고쳐 쓰거나 다시 부르고, 꼭 지킬 것은 훅으로.
출처: https://code.claude.com/docs/en/skills · https://code.claude.com/docs/en/best-practices (Put team procedures in skills · Deterministic and non-deterministic instructions) · https://code.claude.com/docs/en/agent-teams (Context and communication · 역할 정의의 skills) (수집일 2026-11-10)
스스로 쌓는 기억 — 자동 메모리 · 메모리 도구
3장의 지침 파일은 사람이 쓰는 기억입니다. 이 장은 반대로 에이전트가 스스로 적는 기억을 다룹니다. Claude Code 의 자동 메모리, 역할마다 따로 두는 서브에이전트 기억, 그리고 개발자가 자기 에이전트를 만들 때 쓰는 Claude API 메모리 도구까지 — 팀의 세컨드 브레인에 "일하면서 배운 것"이 쌓이는 길을 살펴봅니다.
- 자동 메모리(auto memory — Claude 가 내 교정·선호를 보고 스스로 적어 두는 메모)가 무엇을 적고, 어디에 두고, 시작 때 얼마만큼 읽는지
/memory로 무엇이 저장됐는지 보고 고치는 법- 서브에이전트에 자기만의 지속 기억을 주는
memory설정 - Claude API 메모리 도구 — 파일 기반
/memories폴더로 대화를 넘어 기억하는 방식 - 기억을 쌓을 때 지켜야 할 보안 — 비밀 정보·크기·만료·경로
- 자동 메모리 — Claude 가 스스로 적는 메모 — 지침 파일과 무엇이 다른지, 언제 읽히는지.
- 기억 점검·편집 —
/memory— 에이전트가 무엇을 기억하는지 직접 확인하는 법. - 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 같은 알림이 뜨면 지금 기억을 쓰거나 읽고 있다는 뜻입니다.
어디에 저장되나 — 저장소마다 하나, 워크트리는 공유
프로젝트마다 기억 폴더가 하나씩 생깁니다: ~/.claude/projects/<project>/memory/. 여기서 <project> 는 git 저장소에서 정해지므로, 같은 저장소의 모든 워크트리와 하위 폴더는 기억 폴더 하나를 함께 씁니다. git 저장소가 아니면 프로젝트 맨 위 폴더가 기준입니다.
폴더 안에는 색인 역할의 MEMORY.md 와 메모 하나당 주제 파일 하나가 있습니다. Claude 는 세션 내내 이 폴더를 읽고 쓰며, MEMORY.md 로 무엇이 어디 있는지 관리합니다. 기억 파일에는 두 가지 성질이 더 있습니다.
- 이 컴퓨터에만 있습니다(machine-local). 다른 컴퓨터나 클라우드 환경과 공유되지 않습니다.
- 저절로 지워지지 않습니다. Claude Code 는 오래된 대화 기록을 보존 기간이 지나면 지우지만, 기억 폴더의 파일은 그 정리에서 빠집니다. 나나 Claude 가 고치거나 지울 때까지 남습니다.
시작 때 얼마나 읽히나 — 200줄 또는 25KB
대화가 시작될 때 읽히는 것은 MEMORY.md 의 처음 200줄 또는 처음 25KB 중 먼저 닿는 쪽까지입니다. 그 뒤는 시작 때 읽히지 않습니다. 주제 파일(user_role.md 등)은 시작 때 읽지 않고, Claude 가 필요할 때 평소 파일 도구로 꺼내 읽습니다.
1. 시작 — 색인 앞부분만 들어옵니다. 색인이 짧을수록 다른 일에 쓸 자리가 남습니다.
2. 필요할 때 — 자세한 내용은 그때그때 꺼내 읽습니다(1장의 "필요할 때 꺼내 읽기"와 같은 생각).
3. 한도 관리 — Claude 가 MEMORY.md 에 쓴 뒤, Claude Code 가 200줄·25KB 기준으로 크기를 잽니다. 가까우면 줄이라고 알리고, 넘으면 쓰기는 되지만 "색인을 다시 쓰라"는 오류를 돌려줍니다 — 한도 밖은 다음 시작 때 버려지기 때문입니다.
MEMORY.md 에만 적용됩니다. 시작 때 읽히는 CLAUDE.md 는 파일이 4 MiB 이하라면 전체가 읽히고, 4 MiB 를 넘으면 통째로 건너뜁니다. 그래도 CLAUDE.md 를 짧게 쓰라는 권장(파일당 200줄 아래)은 따로 있습니다 — 3장 참고.
Claude 가 머리말(YAML)로 시작하는 기억 파일을 쓰면, Claude Code 가 쓴 시각을 modified 칸에 ISO 8601 형식으로 기록합니다. 그 사실이 얼마나 최신인지 나와 Claude 모두 알 수 있게 하려는 것입니다.
켜고 끄기
자동 메모리는 내 컴퓨터에서 여는 세션에서 기본으로 켜져 있습니다. 세션 안에서 /memory 를 열고 자동 메모리 스위치를 누르면 끄고 켤 수 있고, 이 선택은 사용자 설정 ~/.claude/settings.json 의 autoMemoryEnabled 로 저장됩니다.
🔧 켜고 끄기·저장 위치의 세부 규칙
- 스스로 다시 켤 수 없는 세션: 백그라운드 세션, 그리고 다른 Claude Code 세션이 띄운 세션(예: Claude 가 Bash 도구로
claude를 실행한 경우)에서는 스위치로 끌 수는 있어도 켤 수는 없습니다. 이때 스위치에off · can't be turned on here; use a session started outside Claude Code라고 나옵니다. 터미널에서claude를 직접 실행한 세션에서 켜야 합니다. - 자체 호스팅 환경: Claude Tag 세션이 아닌 self-hosted 환경의 세션은 자동 메모리가 기본으로 꺼진 채 시작합니다.
- 저장 위치 바꾸기:
settings.json에"autoMemoryDirectory": "~/my-custom-memory-dir". 값은 절대 경로이거나~/로 시작해야 합니다. 사용자·프로젝트·로컬·정책·--settings어느 설정 범위에서도 읽힙니다. - 프로젝트의
.claude/settings.json·.claude/settings.local.json에 넣은autoMemoryDirectory는 설정 파일 속 훅과 같은 폴더 신뢰 규칙을 따릅니다.permissions.blockReadsOutsideWorkingDirectories가 켜져 있으면, 저장소가 지정한 설정 파일이 고른 폴더에서는 기억을 읽지도 쓰지도 않습니다. CLAUDE_CODE_PROJECT_DIR_NAME을CLAUDE_CONFIG_DIR와 함께 정하면, 어느 저장소에서 실행하든 그 이름의 폴더(<config dir>/projects/아래)를 기억 폴더로 씁니다 — 그 설정 폴더로 실행한 프로젝트들이 기억을 공유합니다. Claude Code v2.1.234 이상.
기억 점검·편집 — /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 에서 자동 메모리 폴더를 골라 둘러보기 — 을 제시합니다.
역할마다 자기 기억 — 서브에이전트 지속 메모리
서브에이전트(메인 에이전트가 맡긴 일을 자기 컨텍스트에서 하고 결과만 돌려주는 도우미 — 6장)는 기본적으로 메인 대화의 자동 메모리를 받지 않습니다(예외: 대화를 통째로 물려받는 fork). 대신 역할 정의 파일 머리말에 memory 칸을 적으면, 그 서브에이전트만의 기억 폴더가 생겨 대화를 넘어 남습니다. 원문 예로는 코드베이스의 패턴, 디버깅에서 얻은 통찰, 구조에 관한 결정이 있습니다.
---
name: code-reviewer
description: Reviews code for quality and best practices
memory: user
---
You are a code reviewer. As you review code, update your agent memory with
patterns, conventions, and recurring issues you discover.
뜻: 이름은 code-reviewer, 설명은 "코드의 품질과 모범 관행을 검토함", 기억 범위는 user. 본문 — "너는 코드 검토자다. 검토하면서 발견한 패턴·관례·반복되는 문제를 에이전트 기억에 갱신해라."
<name-of-agent>/)를 갖습니다. 역할 이름은 예시입니다.| 범위 | 위치 | 이럴 때 |
|---|---|---|
user | ~/.claude/agent-memory/<name-of-agent>/ | 모든 프로젝트에 걸쳐 배운 것을 기억해야 할 때 |
project | .claude/agent-memory/<name-of-agent>/ | 이 프로젝트에 한정된 지식이고, 버전 관리로 공유해도 될 때 |
local | .claude/agent-memory-local/<name-of-agent>/ | 이 프로젝트에 한정되지만 버전 관리에 올리면 안 될 때 |
켜면 무엇이 달라지나
- 서브에이전트의 시스템 프롬프트(에이전트에게 맨 먼저 주어지는 기본 지시문)에 기억 폴더를 읽고 쓰는 방법이 들어갑니다.
- 그 폴더
MEMORY.md의 처음 200줄 또는 25KB(먼저 닿는 쪽)도 함께 들어가고, 넘치면 정리하라는 지시가 붙습니다. - 기억 파일을 관리하도록 Read·Write·Edit 도구가 자동으로 켜집니다.
서브에이전트 기억은 자동 메모리의 일부입니다. autoMemoryEnabled 나 CLAUDE_CODE_DISABLE_AUTO_MEMORY 로 자동 메모리를 끄면 memory 칸은 효과가 없습니다.
기본은 project
원문 권장 기본값입니다. 버전 관리로 서브에이전트의 지식을 팀과 나눌 수 있습니다.
시작 전에 기억 확인
"Review this PR, and check your memory for patterns you've seen before." 뜻: 이 PR 을 검토하고, 전에 본 패턴이 있는지 기억을 확인해.
끝나면 기억 갱신
"Now that you're done, save what you learned to your memory." 뜻: 끝났으니 배운 것을 기억에 저장해.
정의 파일에 지시 넣기
"발견한 코드 경로·패턴·라이브러리 위치·주요 구조 결정을 기억에 간단히 적어라"는 문장을 역할 파일 본문에 넣으면 스스로 기억을 가꿉니다.
memory: project 로 두고 .claude/agent-memory/ 를 저장소에 함께 올리면, 검토 담당이 배운 반복 문제를 다음 사람의 검토 담당도 이어받습니다. 개인 팀이라면 내 모든 프로젝트에서 같은 역할이 배운 것을 쓰도록 user 범위가 어울립니다. 다만 기억 폴더도 결국 팀원이 읽는 글이므로 비밀 정보는 넣지 않습니다(보안).
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 는 도구 결과에 담긴 글을 그대로 읽으므로 필요하면 다른 문자열을 돌려줘도 됩니다.
| 명령 | 하는 일 | 입력 예 |
|---|---|---|
view | 폴더 내용 또는 파일 내용 보기(줄 범위 지정 가능) | "path": "/memories/notes.txt", "view_range": [1, 10] |
create | 새 파일 만들기 | "path", "file_text" |
str_replace | 파일 안 글 바꾸기 | "old_str", "new_str" |
insert | 지정한 줄에 글 넣기 | "insert_line": 2, "insert_text" |
delete | 파일·폴더 지우기 | "path": "/memories/old_file.txt" |
rename | 파일·폴더 이름 바꾸기·옮기기 | "old_path", "new_path" |
오류를 돌려줄 때는 도구 결과의 is_error 를 true 로 하고 content 에 메시지(예: Error: The path /memories/notes.txt does not exist)를 넣습니다.
API 가 자동으로 붙이는 지시문:
IMPORTANT: ALWAYS VIEW YOUR MEMORY DIRECTORY BEFORE DOING ANYTHING ELSE.
MEMORY PROTOCOL:
1. Use the `view` command of your `memory` tool to check for earlier progress.
2. ... (work on the task) ...
- As you make progress, record status / progress / thoughts etc in your memory.
ASSUME INTERRUPTION: Your context window might be reset at any moment, so you risk losing any progress that is not recorded in your memory directory.
도구 설명에 이미 "기억 폴더를 정리해 두라"는 내용이 있지만, 그래도 어지러워지면 프롬프트에 "Note: when editing your memory folder, always try to keep its content up-to-date, coherent and organized. You can rename or delete files that are no longer relevant. Do not create new files unless necessary."(뜻: 기억 폴더는 최신·일관·정돈 상태로, 쓸모없는 파일은 이름 바꾸거나 지우고, 꼭 필요할 때만 새 파일을 만들 것)를 덧붙일 수 있습니다. "Only write down information relevant to <topic> in your memory system."(뜻: <주제>와 관련된 정보만 기억에 적어라)처럼 무엇을 적을지 정할 수도 있습니다.
메모리 도구는 Claude 4 이후 모든 모델에서 쓸 수 있고, 컨텍스트 편집(context editing)과도 함께 쓸 수 있습니다. 데이터 보존: 기억이 내 쪽에 저장되므로 보존 기간을 내가 정하며, zero data retention(일부 모델 제외)·HIPAA 대상입니다.
어떤 기억을 어디에 — 네 가지 한눈에
| 지침 파일 (3장) | 자동 메모리 | 서브에이전트 기억 | 메모리 도구 | |
|---|---|---|---|---|
| 누가 쓰나 | 사람 | Claude | 그 서브에이전트 | 내가 만든 에이전트(Claude) |
| 어디에 | 저장소·사용자 폴더 | ~/.claude/projects/…/memory/ | agent-memory/<name>/ | /memories → 내 저장소 |
| 시작 때 읽히는 양 | 파일 전체 | MEMORY.md 200줄/25KB | MEMORY.md 200줄/25KB | Claude 가 먼저 view |
| 팀 공유 | 저장소에 올리면 공유 | 안 됨(이 컴퓨터만) | project 범위면 공유 | 내 저장소 설계에 따라 |
| 쓰는 곳 | Claude Code | Claude API 로 만든 앱 | ||
project 범위 서브에이전트 기억에, 나에 대한 선호는 자동 메모리에. 회사 업무용 에이전트를 직접 개발한다면 메모리 도구의 저장소를 팀이 함께 보는 곳으로 정할 수 있습니다.
기억을 쌓을 때의 보안 — 비밀 정보 · 크기 · 만료 · 경로
메모리 도구에서는 Claude 가 요청한 모든 파일 작업을 내 애플리케이션이 실행하므로, 아래 안전장치는 개발자의 책임입니다. 원문이 꼽는 네 가지는 다음과 같습니다.
🔒 비밀 정보
Claude 는 보통 민감한 정보를 기억 파일에 적기를 거절합니다. 더 확실히 하려면 처리기가 파일을 쓰기 전에 민감한 데이터를 걸러 내는 검사를 넣습니다.
📏 파일 크기
기억 파일 크기를 추적하고 한도를 둡니다. view 가 돌려주는 글자 수를 제한하고, 나머지는 view_range 로 나눠 읽게 할 수 있습니다.
⏳ 기억 만료
오랫동안 읽히지 않은 기억 파일은 주기적으로 지웁니다.
🚧 경로 넘어가기 막기
모든 명령의 모든 경로를 검사해 /memories 밖으로 나가지 못하게 합니다.
/memories/../../secrets.env 같은 악의적 경로는 기억 폴더 밖 파일에 닿을 수 있습니다.🔧 경로 검사 체크리스트 (원문)
- 모든 경로가
/memories로 시작하는지 확인 - 경로를 정규 형태(canonical form)로 바꾼 뒤에도 기억 폴더 안에 있는지 확인
../,..\\같은 상위 폴더 이동 표현이 든 경로 거절- URL 인코딩된 표현(
%2e%2e%2f)도 감시 - 언어에 내장된 경로 보안 도구 사용(예: Python 의
pathlib.Path.resolve()·relative_to())
Claude Code 쪽에서 기억할 것
project 범위 서브에이전트 기억은 저장소에 올라가 팀원 모두가 읽습니다. 개인적이거나 올리면 안 되는 기억은 local 범위(.claude/agent-memory-local/)를 씁니다. 회사 팀의 권한·보안 전반은 9장에서 다룹니다.
- 자동 메모리는 Claude 가 스스로 적는 메모(사람·교정·진행 상황·찾을 곳 네 종류)입니다. 지침 파일(사람이 씀)과 구분합니다.
- 저장소마다
~/.claude/projects/<project>/memory/하나 — 워크트리끼리 공유, 이 컴퓨터에만 있음. 시작 때MEMORY.md처음 200줄 또는 25KB 만 읽고, 주제 파일은 필요할 때 읽습니다. /memory로 기억 파일을 보고·고치고·자동 메모리를 켜고 끕니다. "기억해"는 자동 메모리로, "CLAUDE.md 에 추가해"는 지침 파일로 갑니다.- 서브에이전트는 메인의 자동 메모리를 받지 않습니다. 역할 파일에
memory: project(권장 기본)·user·local을 적으면 역할마다 자기 기억이 생깁니다. - Claude API 메모리 도구는
/memories파일 폴더로 대화를 넘어 기억합니다. Claude 는 요청만, 실행·저장은 내 애플리케이션이 합니다. - 보안: 비밀 정보 거르기, 크기 한도, 오래된 기억 지우기,
/memories밖 경로 막기. 기억은 강제 설정이 아니라 맥락이라, 꼭 막을 것은 훅으로.
출처: https://code.claude.com/docs/en/memory · https://code.claude.com/docs/en/sub-agents · https://platform.claude.com/docs/en/agents-and-tools/tool-use/memory-tool (수집일 2026-11-10)
팀 꾸리기 — 서브에이전트와 에이전트 팀
이제 여러 에이전트를 한 팀으로 묶을 차례입니다. 역할을 파일 하나로 정의하고, 그 역할을 서브에이전트나 팀원으로 불러 씁니다. 이 장의 핵심 질문은 "새로 생긴 팀원은 무엇을 알고 시작하나"입니다 — 그 답이 왜 팀에 세컨드 브레인이 필요한지를 보여 줍니다.
- 역할 정의 파일(
.claude/agents/) 한 장을 서브에이전트와 팀원에 함께 쓰는 법 - 서브에이전트와 에이전트 팀실험 기능의 차이, 언제 무엇을 고를지
- 팀원이 시작할 때 받는 것과 받지 못하는 것 — 그래서 공용 기억 파일이 필요한 이유
- 생성 지시문(spawn prompt — 리더가 팀원을 만들 때 주는 첫 지시)에 꼭 넣을 네 가지
- 팀 크기(3~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장에서 다룹니다.
🔧 머리말 칸 목록과 역할 파일 세부 규칙
| 칸 | 뜻 |
|---|---|
name (필수) | 고유 이름(최대 256자). 파일 이름과 달라도 됨. : 는 쓸 수 없음 |
description (필수) | Claude 가 언제 이 역할에게 맡길지 |
tools / disallowedTools | 쓸 수 있는 도구 / 뺄 도구. tools 를 비우면 쓸 수 있는 도구를 모두 물려받음 |
model | sonnet·opus·haiku·fable·전체 모델 ID·inherit |
permissionMode | 권한 방식(default·acceptEdits·auto·dontAsk·bypassPermissions·plan) |
skills | 시작 때 미리 넣을 스킬(설명만이 아니라 전체 내용) |
mcpServers | 이 역할만 쓸 MCP 서버 |
memory | 지속 기억 범위 user·project·local (5장) |
omitClaudeMd | true 면 사용자·프로젝트·로컬 CLAUDE.md 없이 시작 |
isolation | worktree 면 임시 워크트리(저장소의 독립 복사본)에서 실행 |
maxTurns·effort·background·hooks·color·initialPrompt·autoCompactWindow·experimental | 최대 턴 수·노력 수준·백그라운드 실행·훅·표시 색·첫 지시·자동 압축 창·실험 옵션 |
- 여러 단어 칸 이름은 camelCase 로 정확히 써야 합니다. 모르는 칸은 오류 없이 무시됩니다(
claude --debug로그에서does not recognize or apply를 찾으면 확인 가능). .claude/agents/·~/.claude/agents/는 하위 폴더까지 훑습니다. 폴더 구조는 이름에 영향이 없고, 정체는name칸으로만 정해지므로 이름을 겹치지 않게 합니다.- Claude Code 는 두 폴더를 지켜보다가 파일이 바뀌면 몇 초 안에 다음 위임부터 새 정의를 씁니다. 세션 시작 뒤 새로 만든
agents폴더,--add-dir로 추가한 폴더 안 정의는 재시작해야 읽힙니다. - 플러그인 역할은 보안상
hooks·mcpServers·permissionMode칸을 무시합니다. - 역할 설명들은 컨텍스트를 차지하므로 짧게 씁니다. 기본 제공 역할을 뺀 설명 합계가 15,000 토큰(AI 가 읽고 쓰는 글의 양을 세는 단위)을 넘으면 시작 때 경고가 뜹니다. 자세한 내용은 실행될 때만 읽히는 본문으로 옮깁니다.
서브에이전트 — 맡기고 요약만 받기
서브에이전트는 메인 에이전트가 맡긴 일을 자기 컨텍스트 창(한 번에 담을 수 있는 글의 한도)에서 하고 요약만 돌려주는 도우미입니다. 원문은 이렇게 쓸 때를 꼽습니다 — 검색 결과·로그·파일 내용처럼 다시 볼 일 없는 글이 메인 대화를 뒤덮을 것 같을 때, 같은 지시로 같은 종류의 일꾼을 자꾸 부를 때.
컨텍스트 지키기
탐색·구현을 메인 대화 밖에서 처리합니다.
제약 걸기
쓸 수 있는 도구를 제한합니다.
설정 재사용
사용자 범위 역할을 여러 프로젝트에서 씁니다.
전문화·비용
분야별 지시문, 빠르고 저렴한 모델(예: Haiku)로 보내기.
Claude 는 요청 내용과 역할의 description, 지금 맥락을 보고 알아서 맡깁니다. 더 적극적으로 맡기게 하려면 설명에 "use proactively"(뜻: 먼저 나서서 써라) 같은 말을 넣습니다. 서브에이전트도 자기 요청을 보내므로 메인 대화와 같은 사용량 한도에 함께 계산됩니다.
원문의 대표 쓰임 세 가지
"Use a subagent to run the test suite and report only the failing tests with their error messages" 뜻: 서브에이전트로 테스트를 돌리고 실패한 테스트와 오류 메시지만 알려 줘.
"Research the authentication, database, and API modules in parallel using separate subagents" 뜻: 인증·데이터베이스·API 모듈을 서브에이전트 여럿으로 나란히 조사해. 각자 자기 영역을 조사하고 Claude 가 결과를 합칩니다. 조사 경로가 서로 기대지 않을 때 가장 잘 맞습니다. 단, 서브에이전트마다 자세한 결과를 돌려주면 그것만으로 메인 컨텍스트를 많이 쓰고, 각자 토큰도 따로 씁니다.
"Use the code-reviewer subagent to find performance issues, then use the optimizer subagent to fix them" 뜻: code-reviewer 로 성능 문제를 찾고, 그다음 optimizer 로 고쳐. 앞 서브에이전트의 결과를 Claude 가 받아 필요한 맥락만 다음 서브에이전트에 넘깁니다.
메인 대화로 할까, 서브에이전트로 할까
| 메인 대화가 낫다 | 서브에이전트가 낫다 |
|---|---|
| 자주 주고받으며 다듬어야 하는 일 | 메인에 필요 없는 긴 출력이 나오는 일 |
| 계획·구현·테스트가 많은 맥락을 함께 쓰는 일 | 특정 도구 제한·권한을 강제하고 싶은 일 |
| 빠르고 작은 수정, 기다리기 싫을 때(새 서브에이전트는 맥락 모으는 시간이 듦) | 혼자 끝내고 요약만 돌려주면 되는 일 |
같은 절차를 메인 대화 안에서 재사용하고 싶다면 서브에이전트 대신 스킬(4장)을 고려하라고 원문은 말합니다.
🔧 중첩·동시 실행 한도
- 서브에이전트는 기본적으로 자기 서브에이전트를 다시 띄울 수 있고, 메인 대화 아래 세 층까지입니다. 바꾸려면
CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH(1이면 중첩 끔). 특정 역할이 더 띄우지 못하게 하려면tools에서Agent를 빼거나disallowedTools에 넣습니다. - 한 세션에서 서브에이전트가 20개 돌고 있으면 새로 띄우기가
Concurrent subagent limit reached로 실패합니다(총 개수 제한은 없음).CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS로 바꿉니다. Claude Code v2.1.217 이상. 에이전트 팀 팀원은 이 한도가 아니라 자기 규칙을 따릅니다.
에이전트 팀 — 리더와 팀원 실험 기능
에이전트 팀은 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_CODE_EXPERIMENTAL_AGENT_TEAMS 를 1 로. 셸 환경이나 settings.json 에 넣습니다.
{
"env": {
"CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
}
}
- 켜면 평소 위임도 달라집니다. Claude 가 이름을 붙여 띄운 서브에이전트는 팀원으로 실행되므로, 부탁하지 않아도 팀이 생길 수 있습니다. Claude Code 는 팀원 실행을 따로 확인받지 않습니다.
- 팀원 만들기는 대화형 세션에서만 됩니다.
-p비대화형 모드(Agent SDK 포함)에서는 팀원을 만들지 않고 이름 붙인 서브에이전트도 평범한 서브에이전트로 돕니다. - Claude 가 팀 대신 서브에이전트를 쓸 때가 있습니다. 둘 다 같은 에이전트 패널에 보이므로, 팀이 안 생겼다면 "에이전트 팀으로" 다시 분명히 부탁합니다.
표시 방식 — In-process(기본, 모든 터미널): 리더 터미널 안 에이전트 패널에서 위아래 화살표로 팀원을 고르고 Enter 로 대화를 열어 바로 메시지를 보냅니다. x 로 멈추고 Ctrl+T 로 작업 목록을 켜고 끕니다. Split panes: 팀원마다 창이 따로 열립니다. tmux 또는 iTerm2 가 필요하고 VS Code 내장 터미널·Windows Terminal·Ghostty 는 지원하지 않습니다.
품질 검사 훅 — TeammateIdle(팀원이 쉬려 할 때), TaskCreated(작업을 만들 때), TaskCompleted(완료 표시할 때). 종료 코드 2 로 끝내면 의견을 돌려주며 계속 일하게 하거나 생성·완료를 막습니다.
저장 위치 — 팀 설정 ~/.claude/teams/{team-name}/config.json(세션이 끝나면 지움, 손으로 고치지 말 것), 작업 목록 ~/.claude/tasks/{team-name}/(세션 뒤에도 남음), 우편함 ~/.claude/teams/{team-name}/inboxes/{agent-name}.json. 프로젝트 안 .claude/teams/teams.json 같은 파일은 설정으로 인식되지 않습니다 — 재사용할 역할은 역할 정의 파일로 만듭니다.
서브에이전트 vs 에이전트 팀 — 한 표로
| 서브에이전트 | 에이전트 팀 | |
|---|---|---|
| 컨텍스트 | 자기 컨텍스트 창, 결과는 부른 쪽으로 돌아감 | 자기 컨텍스트 창, 완전히 독립 |
| 소통 | 부른 쪽에 결과를 돌려줌(이름 붙은 서브에이전트끼리는 메시지 가능) | 팀원끼리 직접 메시지 |
| 조율 | 메인 에이전트가 모든 일을 관리 | 메시지로 스스로 조율 + 공유 작업 목록 |
| 잘 맞는 일 | 결과만 중요한 집중된 일 | 토론과 협업이 필요한 복잡한 일 |
| 토큰 비용 | 낮음 — 결과가 요약돼 돌아옴 | 높음 — 팀원마다 별도 Claude |
| 상태 | 정식 기능 | 실험 기능 기본 꺼짐 |
원문의 한 줄 기준: 빨리 맡기고 보고만 받을 일꾼이 필요하면 서브에이전트, 결과를 나누고 서로 따지고 스스로 조율해야 하면 에이전트 팀. 또 팀을 꾸리기 전에 더 가벼운 방법(서브에이전트, 세션 사이 메시지)으로 되는지 먼저 보라고 권합니다.
팀원이 시작 때 받는 것 — 그래서 세컨드 브레인이 필요합니다
이 가이드가 답하려는 질문 — "팀 안의 모든 에이전트가 같은 목표와 맥락을 갖게 하려면?" — 의 열쇠가 이 소절입니다. 원문은 팀원이 만들어질 때 받는 것을 분명히 적어 둡니다.
팀원이 받는 것
- 일반 세션과 같은 프로젝트 맥락 — CLAUDE.md, MCP 서버, 스킬
- 리더가 준 생성 지시문
- 리더가 정해 준 이름 — 누구에게나 이름으로 메시지 가능
팀원이 받지 못하는 것
- 리더의 대화 기록 — 리더가 나와 나눈 이야기, 이미 읽은 파일
- (서브에이전트의 경우) 메인 대화의 자동 메모리, 이미 부른 스킬, 출력 스타일 — 대신 CLAUDE.md 와 Claude 가 쓴 위임 메시지를 받습니다
리더와 오래 이야기해 정한 목표도, 팀원에게는 파일에 적혀 있거나 생성 지시문에 들어 있지 않으면 없는 것입니다. 원문 사실(팀원은 CLAUDE.md·MCP·스킬을 읽는다)을 뒤집어 보면, 팀 전체가 공유해야 할 목표·용어·결정은 모두가 시작 때 읽는 파일에 두면 된다는 뜻이 됩니다. 이것이 이 가이드가 말하는 세컨드 브레인 — 팀이 함께 읽고 쓰는 공용 기억 파일 묶음 — 입니다.
- 항상 알아야 할 것(팀 목표 한 단락, 지켜야 할 규칙, 용어): 프로젝트 CLAUDE.md 또는 그 CLAUDE.md 가 가져오는 파일(예시 이름
GOAL.md) — 3장. - 필요할 때 꺼낼 것(절차, 참고 지식): 스킬 — 4장.
- 이번 일에만 필요한 것(맡은 파일, 마감, 출력 형식): 생성 지시문 — 다음 소절.
vendor/ 폴더는 무시").
🔧 서브에이전트가 시작 때 받는 것 (원문 목록)
- 시스템 프롬프트: 역할 파일 본문 + Claude Code 가 붙이는 환경 정보(Claude Code 기본 시스템 프롬프트는 아님).
- 작업 메시지: Claude 가 맡기며 쓴 위임 지시.
- CLAUDE.md: 메인 대화가 읽는 모든 층(
~/.claude/CLAUDE.md, 프로젝트 규칙,CLAUDE.local.md, 관리 정책 파일, 프로젝트 지침으로 읽힌AGENTS.md). 기본 제공 Explore·Plan 은 건너뜀.omitClaudeMd를 켠 역할은 관리 정책 파일만. - git 상태 스냅숏, 역할 파일
skills칸에 적은 미리 넣은 스킬의 전체 내용. - 형제 명단:
SendMessage도구가 있고 이름 붙은 다른 에이전트가 있으면, 시작 시점의 에이전트 이름 목록. - 팀원의 경우: 리더를
--setting-sources로 시작하면 팀원도 같은 제한된 설정 출처에서 읽습니다(split-pane 팀원은 v2.1.281 전까지 모든 설정 출처를 읽음). - 역할 정의를 팀원에 쓸 때:
tools·model은 적용, 본문은 지시문으로 덧붙거나(in-process) 대신 쓰임(split-pane).skills칸은 팀원에게 적용되지 않고 팀원은 프로젝트·사용자 설정의 스킬을 읽습니다. in-process 팀원은mcpServers칸도 무시하고 프로젝트·사용자 설정의 MCP 서버를 씁니다.
생성 지시문에 넣을 것 — 목표 · 형식 · 도구 · 경계
팀원은 리더의 대화를 모르므로, 원문은 이번 일에 필요한 자세한 내용을 생성 지시문에 넣으라고 권합니다. Anthropic 의 멀티 에이전트 조사 시스템 글은 무엇을 넣을지 네 가지로 정리합니다 — 하위 에이전트마다 목표, 출력 형식, 쓸 도구·출처 안내, 분명한 작업 경계가 필요합니다.
원문의 생성 지시문 예
Spawn a security reviewer teammate with the prompt: "Review the authentication module
at src/auth/ for security vulnerabilities. Focus on token handling, session
management, and input validation. The app uses JWT tokens stored in
httpOnly cookies. Report any issues with severity ratings."
뜻: 보안 검토 팀원을 만들고 이렇게 지시해 — "src/auth/ 의 인증 모듈을 보안 취약점 위주로 검토해. 토큰 처리·세션 관리·입력 검증에 집중해. 이 앱은 httpOnly 쿠키에 저장한 JWT 토큰을 쓴다. 문제마다 심각도 등급을 붙여 보고해."
| 원문 예의 부분 | 네 가지 중 |
|---|---|
| "Review the authentication module at src/auth/" | 목표 + 경계(맡은 폴더) |
| "Focus on token handling, session management, and input validation" | 경계(볼 측면) |
| "The app uses JWT tokens stored in httpOnly cookies" | 리더만 알던 맥락을 옮겨 줌 |
| "Report any issues with severity ratings" | 출력 형식 |
이름을 정해 주기
나중에 프롬프트에서 부를 수 있게 생성 지시에서 팀원 이름을 정해 주라고 원문은 권합니다.
파일을 나눠 맡기기
두 팀원이 같은 파일을 고치면 덮어쓰게 됩니다. 팀원마다 다른 파일 묶음을 맡깁니다.
역할 파일 재사용
"Spawn a teammate using the security-reviewer agent type to audit the auth module." 뜻: security-reviewer 역할로 팀원을 만들어 인증 모듈을 점검해.
팀 크기 — 대부분 3~5명으로 시작
팀원 수에 정해진 한도는 없지만, 원문은 세 가지 현실적 제약을 듭니다 — 팀원마다 컨텍스트 창을 따로 쓰므로 토큰 비용이 팀원 수에 비례해 늘고, 팀원이 많을수록 소통·조율·충돌이 늘며, 어느 선을 넘으면 사람을 더해도 그만큼 빨라지지 않습니다. 그래서 대부분 3~5명으로 시작하라고 권합니다. 독립된 작업이 15개라도 3명이 좋은 출발점이고, "집중한 3명이 흩어진 5명보다 나은 경우가 많다"고 합니다.
작업 크기도 맞추기
너무 작으면
조율에 드는 수고가 얻는 이득보다 큽니다.
너무 크면
중간 점검 없이 오래 일해 헛수고 위험이 커집니다.
알맞으면
분명한 결과물이 나오는 독립 단위 — 함수 하나, 테스트 파일 하나, 검토 하나.
리더가 작업을 충분히 쪼개지 않으면 더 작게 나누라고 부탁합니다. 원문은 팀원 한 명당 작업 5~6개면 모두가 바쁘게 일하고, 누가 막혀도 리더가 일을 다시 나눌 수 있다고 합니다.
일을 나누는 패턴 — 단순하게 시작하기
Anthropic 의 "효과적인 에이전트 만들기" 글은 먼저 두 가지를 구분합니다. 워크플로(workflow)는 AI 와 도구가 미리 정해 둔 순서대로 움직이는 시스템이고, 에이전트(agent)는 AI 가 스스로 과정과 도구 사용을 정하는 시스템입니다. 그리고 가장 성공적인 사례들은 복잡한 프레임워크가 아니라 단순하고 조합하기 쉬운 패턴을 썼다고 말합니다.
프롬프트 연결(prompt chaining) — 일을 순서 있는 단계로 나눠 각 호출이 앞 결과를 처리합니다. 중간에 검사(gate)를 둘 수 있습니다. 고정된 단계로 깔끔하게 나뉘는 일에 맞습니다. 원문 예: 개요 쓰기 → 개요가 기준을 만족하는지 확인 → 본문 쓰기.
라우팅(routing) — 들어온 일을 분류해 알맞은 전문 처리로 보냅니다. 원문 예: 고객 문의를 일반 질문·환불 요청·기술 지원으로 나눠 각기 다른 처리로 보내기, 쉬운 질문은 작고 저렴한 모델에 어려운 질문은 더 강한 모델에 보내기.
병렬화(parallelization) — 독립된 하위 작업을 나란히 돌리는 나누기(sectioning)와, 같은 일을 여러 번 돌려 다양한 답을 얻는 투표(voting) 두 가지가 있습니다. 원문 예: 한 모델은 답을 만들고 다른 모델은 부적절한 요청을 걸러 내기, 여러 프롬프트가 같은 코드를 각자 취약점 검토하기.
오케스트레이터-작업자(orchestrator-workers) — 오케스트레이터(일을 나누고 모으는 지휘 역할)가 일을 그때그때 나눠 작업자에게 맡기고 결과를 합칩니다. 병렬화와 모양은 비슷하지만, 하위 작업이 미리 정해지지 않고 입력을 보고 지휘 에이전트가 정한다는 점이 다릅니다. 원문 예: 여러 파일을 매번 다르게 고치는 코딩, 여러 출처에서 정보를 모으는 검색. 멀티 에이전트 조사 시스템도 이 구조로, 리더가 전략을 세우고 하위 에이전트를 나란히 띄웁니다.
평가자-개선자(evaluator-optimizer) — 한 호출이 답을 만들고 다른 호출이 평가·의견을 주는 일을 되풀이합니다. 평가 기준이 분명하고, 다듬을수록 눈에 띄게 나아질 때 맞습니다. 원문 예: 미묘한 뜻을 살려야 하는 문학 번역.
원문은 에이전트를 만들 때의 세 원칙으로 끝맺습니다 — 설계를 단순하게, 에이전트의 계획 단계를 드러내 보이기, 도구 설명과 시험으로 에이전트가 쓰는 도구의 사용법을 잘 만들기.
한계와 주의할 점
에이전트 팀은 실험 기능이라 원문이 밝힌 한계가 있습니다. 미리 알면 덜 당황합니다.
| 한계 | 무슨 뜻인가 · 대처 |
|---|---|
| 세션을 이어 열면 팀원이 안 돌아옴 | /resume·/rewind 는 in-process 팀원을 되살리지 않습니다. 리더가 없는 팀원에게 말을 걸면 새 팀원을 만들라고 합니다. |
| 작업 상태가 늦게 바뀜 | 팀원이 완료 표시를 빠뜨려 뒤 작업이 막힐 수 있습니다. 실제로 끝났는지 보고 직접 고치거나 리더에게 재촉하게 합니다. |
| 종료가 느릴 수 있음 | 팀원은 지금 하던 요청·도구 실행을 마친 뒤 끝납니다. |
| 세션당 팀 하나 | 추가 팀을 만들거나 여러 세션이 팀을 공유할 수 없습니다. |
| 팀 안의 팀 없음 | 팀원은 자기 팀원을 만들 수 없습니다. 팀은 리더만 관리합니다. |
| 리더 고정 | 처음 세션이 끝까지 리더입니다. 팀원을 리더로 올릴 수 없습니다. |
| 팀원별 권한 방식을 만들 때 정할 수 없음 | 새 팀원은 리더의 권한 방식으로 시작합니다(bypassPermissions 포함). |
| 창 나누기 표시는 tmux·iTerm2 필요 | 기본 in-process 방식은 어느 터미널에서나 됩니다. |
원문의 운영 요령
조사·검토부터
처음이라면 코드를 쓰지 않는, 경계가 분명한 일로 — PR 검토, 라이브러리 조사, 버그 조사.
지켜보고 방향 잡기
진행을 확인하고, 안 되는 접근은 돌려세우고, 결과를 그때그때 합칩니다. 오래 방치하면 헛수고 위험이 큽니다.
리더가 직접 하려 들면
"Wait for your teammates to complete their tasks before proceeding" 뜻: 진행하기 전에 팀원들이 작업을 끝낼 때까지 기다려.
멀티 에이전트 조사 시스템 글도 비슷한 한계를 적습니다 — 모든 에이전트가 같은 맥락을 공유해야 하거나 서로 얽힌 일이 많은 분야는 아직 멀티 에이전트에 잘 맞지 않고, 대부분의 코딩은 조사보다 진짜로 나란히 할 수 있는 일이 적다고 합니다. 또 지휘 에이전트가 하위 에이전트를 기다리는 동안 전체가 멈추는 병목도 있다고 밝힙니다. 결과를 파일로 남겨 리더를 거치지 않고 주고받는 방법은 7장에서 다룹니다.
- 역할 정의 파일(
.claude/agents/<이름>.md, 필수 칸은name·description)을 한 번 쓰면 서브에이전트로도, 에이전트 팀의 팀원으로도 씁니다. 프로젝트 폴더에 두면 팀이 함께,~/.claude/agents/에 두면 나만 씁니다. - 서브에이전트는 자기 컨텍스트에서 일하고 요약만 돌려줍니다 — 긴 출력 격리, 나란히 조사, 차례로 잇기.
- 에이전트 팀실험 기능은 리더 1 + 팀원 여럿이 공유 작업 목록과 메시지로 협업합니다. 토큰을 훨씬 많이 쓰므로 나란히 탐색이 가치 있는 일에.
- 팀원이 시작 때 받는 것은 CLAUDE.md·MCP 서버·스킬 + 생성 지시문뿐, 리더의 대화 기록은 넘어가지 않습니다. 그래서 팀 목표·맥락은 대화가 아니라 모두가 읽는 파일(세컨드 브레인)에 둡니다.
- 생성 지시문에는 목표·출력 형식·도구와 출처·작업 경계를 넣습니다. 팀원마다 다른 파일을 맡깁니다.
- 팀은 대부분 3~5명으로 시작하고, 팀원당 작업 5~6개. 패턴은 가장 단순한 것부터.
- 한계: 이어 열면 팀원이 안 돌아옴, 세션당 팀 하나, 팀 안의 팀 없음, 리더 고정. 팀원은 내 대신 권한을 승인할 수 없습니다.
출처: https://code.claude.com/docs/en/sub-agents · https://code.claude.com/docs/en/agent-teams · https://www.anthropic.com/engineering/building-effective-agents · https://www.anthropic.com/engineering/multi-agent-research-system (수집일 2026-11-10)
이어 달리기 — 인수인계 노트와 긴 작업
몇 시간, 며칠짜리 일은 한 세션 안에 끝나지 않습니다. 새 세션은 앞 세션이 한 일을 전혀 모른 채 시작합니다. 이 장은 다음 세션·다른 에이전트가 바통을 이어받을 수 있게 인수인계 노트를 남기는 방법을 다룹니다. 세컨드 브레인에서 "지금 어디까지 왔나"를 맡는 층입니다.
- 긴 작업에서 에이전트가 실패하는 두 가지 모습과 그 이유
- 진행 기록 파일(
claude-progress.txt)·기능 목록(feature_list.json)·git 기록으로 세션 사이를 잇는 법 - 새 세션이 매번 같은 순서로 "현재 상태 파악"부터 하는 시작 루틴
- 메모리 도구의 여러 세션 작업 패턴(첫 세션 준비 → 매 세션 읽기 → 끝날 때 갱신)
- 서브에이전트 결과를 대화가 아니라 파일로 넘겨 "전화 게임"을 줄이는 법
- 자주 나오는 실패 네 가지와 해결책 한 표
- 긴 작업의 문제 — 새 세션은 앞 일을 모른다 — 교대 근무 비유 하나로 왜 노트가 필요한지
- 진행 기록 파일과 git — 다음 사람을 위한 메모 — 무엇을 남기는지
- 세션 시작 루틴 — 매번 같은 순서로 상태 파악 — 새 세션이 처음 할 일 다섯 단계
건너뛰어도 되는 곳: 「서브에이전트 결과는 파일로」는 여러 에이전트를 함께 쓸 때 봅니다. 「개발자용」으로 접힌 상자는 접어 둔 채 읽어도 됩니다.
긴 작업의 문제 — 새 세션은 앞 일을 모른다
에이전트는 세션(에이전트를 한 번 켜서 끌 때까지의 작업 한 판) 단위로 일하고, 새 세션은 앞 세션의 기억 없이 시작합니다. 컨텍스트 창(에이전트가 한 번에 담을 수 있는 글의 한도)에는 한도가 있고, 복잡한 일은 창 하나 안에 끝나지 않습니다. 그래서 세션과 세션 사이에 다리가 필요합니다.
압축만으로는 부족했다
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 에 있음
기능 목록 — "다 했다"를 막는 체크리스트
실패 1(한 번에 다 하기)과 실패 2(너무 일찍 끝났다고 하기)를 함께 막는 장치입니다. 첫 세션의 초기화 에이전트가 사용자의 짧은 지시를 펼쳐 기능 요구 사항 전체를 파일 하나에 씁니다. claude.ai 복제 예에서는 기능이 200개가 넘었습니다. 예를 들면 "사용자가 새 채팅을 열고 질문을 입력한 뒤 Enter 를 누르면 AI 답이 보인다" 같은 것입니다.
- 처음엔 전부 "실패" — 그래야 뒤의 세션들이 "완성된 모습"의 윤곽을 분명히 봅니다.
- 고칠 수 있는 것은 통과 여부 칸(
passes)뿐 — 원문은 "테스트를 지우거나 고치는 것은 용납할 수 없다. 기능이 빠지거나 버그가 생길 수 있다"처럼 강한 말로 지시했습니다. - 마크다운 대신 JSON(프로그램이 읽기 좋은 정해진 모양의 데이터 형식) — 실험해 보니 모델이 마크다운 파일보다 JSON 파일을 부적절하게 바꾸거나 덮어쓰는 일이 적었습니다.
🔧 개발자용 참고 — 원문의 기능 목록 한 항목
{
"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
}
뜻: 분류 "기능", 설명 "새 채팅 버튼이 새 대화를 만든다", 확인 단계(메인 화면으로 이동 → New Chat 클릭 → 새 대화가 생겼는지 → 채팅 영역이 환영 화면인지 → 사이드바에 대화가 보이는지), 통과 여부 false(아직 실패).
한 번에 기능 하나, 그리고 진짜로 확인하기
기능 목록이 생긴 뒤 코딩 에이전트에게는 한 번에 기능 하나만 하게 했고, 이것이 "한꺼번에 하려는 버릇"을 고치는 데 결정적이었습니다. 또 하나의 큰 실패는 제대로 시험하지 않고 완료 표시를 하는 것이었습니다. 코드를 바꾸고 간단한 시험까지는 해도, 기능이 처음부터 끝까지(end-to-end) 실제로 되는지는 놓쳤습니다. 브라우저 자동화 도구(사람 대신 브라우저를 열고 누르고 화면을 찍는 프로그램)로 사람 사용자처럼 시험하라고 분명히 지시하자 크게 나아졌습니다. 원문은 Puppeteer MCP 서버로 화면을 찍어 확인했고, 그래도 브라우저 기본 경고창은 그 도구로 볼 수 없어 그 기능들이 더 버그가 많았다는 한계도 적었습니다.
세션 시작 루틴 — 매번 같은 순서로 상태 파악
준비물이 갖춰지면, 모든 코딩 에이전트는 일을 시작하기 전에 정해진 순서로 "현재 위치"부터 확인하라는 지시를 받습니다. 아주 기본적인 단계도 있지만 그래도 도움이 됩니다. 원문은 이 덕분에 매 세션 "코드를 어떻게 시험하지?"를 알아내는 데 드는 토큰(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장 「반드시 막을 것」의 방법을 씁니다.메모리 도구의 여러 세션 패턴 — 기억을 "복구 장치"로
Claude API 의 메모리 도구(Claude 가 /memories 폴더에 파일을 만들고 읽어 대화를 넘어 기억하게 하는 기능, 5장) 문서에도 같은 생각이 정리되어 있습니다. 여러 세션에 걸친 소프트웨어 작업이라면, 일하면서 그때그때 메모를 쓰지 말고 메모리 파일을 미리 계획해 만들라고 합니다. 그러면 메모리가 복구 장치가 되어, 새 세션마다 지난 세션이 남긴 상태에서 다시 시작합니다.
- 첫 세션(준비) — 본격적인 일 전에 메모리 파일을 만듭니다: 진행 기록(한 일과 다음 할 일), 기능 체크리스트(일의 범위), 필요한 시작 스크립트를 가리키는 메모.
- 이후 세션 — 시작하자마자 그 파일들을 읽어 프로젝트 상태를 되살립니다. 코드를 다시 탐색하거나 예전 결정을 되짚지 않아도 됩니다.
- 세션 끝 — 끝나기 전에 진행 기록에 끝낸 것과 남은 것을 적어, 다음 세션이 정확한 출발점을 갖게 합니다.
핵심 원칙은 앞 소절과 같습니다: 한 번에 기능 하나, 그리고 코드를 썼을 때가 아니라 처음부터 끝까지 확인이 된 뒤에만 완료로 표시합니다. 그래야 진행 기록이 세션에서 세션으로 정확하게 유지됩니다.
ASSUME INTERRUPTION: Your context window might be reset at any moment…"가 있습니다. 뜻: 언제든 끊긴다고 가정하라 — 컨텍스트 창은 언제라도 초기화될 수 있고, 메모리 폴더에 적지 않은 진행은 잃을 수 있다. 인수인계 노트의 정신을 한 줄로 요약한 문장입니다.🔧 개발자용 참고 — 자동으로 붙는 지시 전문과 압축과의 조합
IMPORTANT: ALWAYS VIEW YOUR MEMORY DIRECTORY BEFORE DOING ANYTHING ELSE.
MEMORY PROTOCOL:
1. Use the `view` command of your `memory` tool to check for earlier progress.
2. ... (work on the task) ...
- As you make progress, record status / progress / thoughts etc in your memory.
ASSUME INTERRUPTION: Your context window might be reset at any moment, so you risk losing any progress that is not recorded in your memory directory.
뜻: 무엇보다 먼저 메모리 폴더를 본다 → view 로 이전 진행을 확인 → 일하면서 상태·진행·생각을 메모리에 기록 → 언제든 끊긴다고 가정.
압축과 함께 쓰기: 원문은 긴 작업 에이전트라면 둘 다 쓰기를 권합니다. 압축(서버 쪽에서 대화 전체를 요약)은 활성 컨텍스트를 작게 유지하고, 메모리는 요약을 거쳐도 살아남아야 할 정보를 지킵니다. 메모리 폴더가 어지러워지면 "항상 최신·일관·정리된 상태로 유지하고, 필요 없는 파일은 이름을 바꾸거나 지우고, 꼭 필요할 때만 새 파일을 만들라"는 지시를 덧붙일 수 있습니다.
서브에이전트 결과는 파일로 — "전화 게임" 줄이기
여러 에이전트가 함께 일할 때도 인수인계가 생깁니다. 서브에이전트(메인 에이전트가 맡긴 일을 자기 컨텍스트에서 하고 결과만 돌려주는 도우미, 6장)가 찾아낸 것을 지휘 에이전트(일을 나누고 모으는 역할)에게 말로 전하고, 지휘 에이전트가 다시 정리해 전하면 — 말이 건너갈 때마다 내용이 조금씩 빠집니다. 원문(Anthropic 멀티 에이전트 연구 시스템)은 이것을 "전화 게임"(귓속말 전달 놀이)이라고 부릅니다.
결과는 파일로
서브에이전트가 도구로 결과를 바깥 저장소(파일)에 저장하고, 지휘 에이전트에게는 가벼운 참조만 돌려줍니다. 여러 단계를 거치며 정보가 새는 것을 막고, 큰 결과를 대화 기록으로 복사하는 토큰도 줄입니다. 코드·보고서·데이터 시각화처럼 모양이 정해진 결과물에 특히 잘 맞습니다.
계획은 메모리에
원문의 지휘 연구 에이전트는 먼저 접근 방법을 생각한 뒤 계획을 메모리에 저장합니다. 컨텍스트 창이 200,000 토큰을 넘으면 잘려 나가므로, 계획만은 꼭 남겨 두려는 것입니다.
단계가 끝나면 요약해 보관
대화가 수백 턴(주고받기 한 번)에 이르면, 끝난 작업 단계를 요약해 바깥 메모리에 저장하고 다음 일로 넘어갑니다. 한도가 다가오면 깨끗한 컨텍스트의 새 서브에이전트를 띄우고 신중하게 인수인계해 흐름을 잇습니다.
outputs/)은 이 가이드의 예시 이름입니다. 에이전트 팀이라면 두 팀원이 같은 파일을 고치면 덮어쓰기가 생기므로, 원문(agent-teams)대로 팀원마다 맡는 파일을 나눕니다.자주 나오는 실패와 해결 — 한 표로
원문은 긴 작업 에이전트의 흔한 실패 네 가지와 해결책을, 첫 세션(초기화 에이전트)이 할 일과 매 세션(코딩 에이전트)이 할 일로 나눠 정리했습니다.
| 문제 | 첫 세션에 준비할 것 | 매 세션 할 일 |
|---|---|---|
| 프로젝트 전체를 너무 일찍 "다 했다"고 선언 | 기능 목록 파일: 처음 지시를 바탕으로 처음부터 끝까지 확인할 기능 설명을 JSON 파일 하나에 | 세션 시작 때 기능 목록을 읽고, 기능 하나만 골라 시작 |
| 버그나 기록 안 된 진행을 남긴 채 끝남 | 처음 git 저장소와 진행 기록 파일 만들기 | 시작: 진행 기록·git 로그 읽고 개발 서버에서 기본 시험(숨은 버그 찾기). 끝: git 커밋 + 진행 기록 갱신 |
| 기능을 너무 일찍 완료로 표시 | 기능 목록 파일 | 모든 기능을 스스로 확인. 꼼꼼히 시험한 뒤에만 통과로 |
| 앱을 어떻게 실행할지 알아내느라 시간을 씀 | 개발 서버를 켜는 init.sh 작성 | 세션 시작 때 init.sh 읽기 |
아직 열려 있는 질문
- 범용 코딩 에이전트 하나가 가장 나은지, 시험 담당·품질 보증 담당·코드 정리 담당 같은 전문 에이전트 여럿이 더 나은지는 원문 기준 아직 분명하지 않습니다(원문은 전문 에이전트가 더 잘할 수도 있다고 봄).
- 원문 실험은 풀스택 웹 앱 개발에 맞춰져 있고, 다른 분야로 넓히는 것은 앞으로의 과제입니다.
- 새 세션은 앞 세션을 기억하지 못합니다. 압축만으로는 부족하고, 파일로 남긴 인수인계 노트가 세션 사이의 다리입니다.
- 첫 세션은 진행 기록(
claude-progress.txt)·기능 목록(feature_list.json)·init.sh·첫 git 커밋을 준비합니다. - 기능 목록은 전부 "실패"로 시작하고, 통과 여부 칸만 바꾸며, 끝까지 확인한 뒤에만 통과로 바꿉니다.
- 매 세션: 폴더 확인 → 기록·git 로그 읽기 → 기능 하나 고르기 → 앱을 켜고 기본 시험 → 일 → 커밋과 기록 갱신.
- 메모리 도구도 같은 패턴(첫 세션 준비 → 매 세션 읽기 → 끝날 때 갱신)이며, "언제든 끊긴다고 가정하라"가 핵심입니다.
- 여러 에이전트는 결과를 파일로 남기고 경로만 주고받아 "전화 게임"의 손실을 줄입니다.
출처: https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents · https://www.anthropic.com/engineering/multi-agent-research-system · https://platform.claude.com/docs/en/agents-and-tools/tool-use/memory-tool · https://code.claude.com/docs/en/agent-teams (수집일 2026-11-10)
바깥 지식 잇기 — MCP 와 Claude 프로젝트
팀의 지식은 폴더 안 파일에만 있지 않습니다. 일정표·문서 도구·이슈 관리·데이터베이스에도 흩어져 있지요. 이 장은 에이전트가 그런 바깥 도구를 직접 읽고 쓰게 잇는 표준 MCP와, 코딩을 하지 않는 팀이 지식·지침을 한곳에 묶어 함께 쓰는 Claude 프로젝트를 다룹니다.
- MCP 가 무엇이고 왜 "AI 앱용 USB-C 포트"라고 부르는지
- Claude Code 에서 MCP 서버를 어느 범위(로컬·프로젝트·사용자)에 둘지 고르는 법
- 팀 전원이 같은 도구를 쓰도록
.mcp.json을 함께 쓰는 법과 그때의 승인 절차 - 코딩을 안 하는 팀의 선택지 — Claude 프로젝트의 지식·지침·공유 권한
- 지식이 아주 많아지면 쓰는 RAG 가 무엇인지
- MCP 란 — AI 앱용 USB-C 포트 — 그림 하나로 무엇을 잇는지
- 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 에 있습니다.🔧 개발자용 참고 — 서버 추가·관리 명령과 연결 방식
연결 방식(transport). 원격 서버는 HTTP 방식이 권장(클라우드 서비스에 가장 널리 지원)이고, 내 컴퓨터에서 프로그램으로 도는 서버는 stdio 방식(시스템에 직접 접근하거나 직접 만든 스크립트에 적합)입니다. 원문에는 SSE·WebSocket 방식도 있습니다.
# 원격 HTTP 서버 추가 (기본은 로컬 범위)
claude mcp add --transport http notion https://mcp.notion.com/mcp
# 범위를 정해 추가
claude mcp add --transport http stripe --scope local https://mcp.stripe.com
claude mcp add --transport http shared-server --scope project https://example.com/mcp
claude mcp add --transport http hubspot --scope user https://mcp.hubspot.com/anthropic
# 내 컴퓨터에서 도는 stdio 서버 ( -- 뒤는 서버 실행 명령 그대로 )
claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable \
-- npx -y airtable-mcp-server
# 관리
claude mcp list # 목록과 상태(✔ Connected · ! Needs authentication · ✘ Failed to connect)
claude mcp get notion # 한 서버 자세히
claude mcp remove notion # 지우기
/mcp # (Claude Code 안에서) 서버 상태 보기
원격 서버를 지우면 Claude Code 가 저장한 OAuth 토큰도 지우지만, 발급한 쪽에서 토큰을 취소하지는 않습니다. 취소까지 하려면 지우기 전에 claude mcp logout <name> 을 먼저 실행합니다.
도구 검색(tool search). 세션 시작 때는 도구 이름과 서버 안내문만 읽고 도구 정의는 필요할 때 불러오므로, 서버를 더 붙여도 컨텍스트 창에 주는 영향이 작습니다. 서버당 도구 개수 상한은 따로 없고, 실질적 한도는 컨텍스트 창 예산입니다.
팀과 같은 도구 쓰기 — .mcp.json 공유
회사 팀의 모든 에이전트가 같은 도구를 쓰게 하는 가장 간단한 방법은 프로젝트 범위입니다. 프로젝트 범위로 서버를 추가하면 Claude Code 가 프로젝트 맨 위 폴더의 .mcp.json 파일을 만들거나 고쳐 줍니다. 원문은 이 파일을 버전 관리(git 처럼 파일 변경 이력을 팀과 함께 관리하는 것)에 넣어 팀 전원이 같은 MCP 도구와 서비스를 얻게 하라고 권합니다.
1. 한 사람이 프로젝트 범위로 추가
--scope project 로 서버를 추가하면 .mcp.json 이 생깁니다.
2. 저장소에 커밋
.mcp.json 을 git 에 커밋하면, 저장소를 받는 사람 모두 같은 서버 목록을 갖게 됩니다. 비밀 값(API 키)은 파일에 직접 쓰지 말고 환경 변수로 넣습니다(아래 접힌 상자).
3. 팀원이 처음 열 때 승인
보안을 위해, 대화형 세션에서는 .mcp.json 의 프로젝트 서버를 쓰기 전에 승인을 묻습니다. 아직 승인하지 않은 서버는 claude mcp list 에 ⏸ Pending approval(승인 대기)로 보입니다. 받아 온 저장소가 스스로 자기 서버를 승인할 수는 없습니다 — 저장소에 들어 있는 승인 설정은 그 폴더를 믿겠다고(작업 공간 신뢰) 받아들이기 전에는 무시됩니다.
4. 에이전트 팀원도 같은 도구
에이전트 팀(리더 하나와 팀원 여럿이 공유 작업 목록·메시지로 협업하는 기능) 실험 기능의 팀원은 만들어질 때 일반 세션과 같은 프로젝트 맥락 — CLAUDE.md, MCP 서버, 스킬 — 을 불러옵니다. 그래서 .mcp.json 하나로 리더와 팀원이 같은 도구를 봅니다.
claude.ai 커넥터
claude.ai 계정으로 Claude Code 에 로그인했다면, claude.ai 에 추가한 MCP 서버(커넥터)를 Claude Code 에서도 자동으로 쓸 수 있습니다. Team·Enterprise 요금제에서는 관리자만 서버를 추가할 수 있습니다.
조직이 직접 제공
관리자는 관리 설정으로 모든 사용자에게 서버를 배포·제공할 수 있고, 조직 정책이 막은 서버는 ✘ Blocked by enterprise managed policy 로 보입니다. 어느 정책이 막는지는 관리자에게 묻습니다.
🔧 개발자용 참고 — .mcp.json 모양 · 환경 변수 · 승인 초기화
{
"mcpServers": {
"api-server": {
"type": "http",
"url": "${API_BASE_URL:-https://api.example.com}/mcp",
"headers": {
"Authorization": "Bearer ${API_KEY}"
}
}
}
}
${VAR}는 환경 변수 값으로,${VAR:-default}는 값이 없으면 기본값으로 바뀝니다.command·args·env·url·headers에 쓸 수 있어, 팀이 설정은 함께 쓰고 컴퓨터마다 다른 경로·API 키는 각자 둡니다.- 값도 기본값도 없는 변수는 설정은 읽히지만
claude mcp list에 경고가 뜨고${VAR}글자 그대로 쓰입니다. url은 있는데type이 없으면 설정 오류입니다(type없는 항목은 stdio 로 읽힘)."type": "http"를 적습니다.- 승인 선택을 처음으로 되돌리기:
claude mcp reset-project-choices. claude -p실행, Agent SDK 세션, (프로젝트 스레드 밖의) 클라우드 세션은 승인 창을 띄울 수 없어 프로젝트 서버를 묻지 않고 불러옵니다. 막으려면disabledMcpjsonServers에 넣거나,--setting-sources로 프로젝트 설정을 빼거나,--strict-mcp-config로 시작합니다(이 동작의 세부 버전 조건은 원문 참고, v2.1.246 이상).
Claude 프로젝트 — 코딩 안 하는 팀의 공용 지식 공간
터미널이나 저장소를 쓰지 않는 팀이라면 claude.ai 의 프로젝트가 세컨드 브레인 역할을 합니다. 프로젝트는 자기만의 대화 기록과 지식 창고를 가진 독립된 작업 공간입니다. 프로젝트마다 문서를 올리고, 맥락을 주고, 그 주제에 집중한 대화를 Claude 와 나눕니다. 무료 계정을 포함한 모든 사용자가 쓸 수 있고, 무료 사용자는 프로젝트를 최대 5개까지 만듭니다.
프로젝트 지식
관련 문서·글·코드·파일을 프로젝트의 지식 창고에 올리면, Claude 가 그 프로젝트 안의 각 대화에서 맥락과 배경을 이해하는 데 씁니다.
프로젝트 지침
프로젝트마다 지침을 정해 답을 맞춥니다. 예: 더 격식 있는 말투로, 또는 특정 역할·업계의 관점에서 답하게.
팀과 공유하기 (Team · Enterprise 요금제만)
| 항목 | 내용 |
|---|---|
| 권한 — Can view(보기) | 프로젝트 내용·지식·지침을 보고 프로젝트 안에서 대화할 수 있지만 고칠 수는 없음 |
| 권한 — Can edit(편집) | 지침과 지식을 고치고, 멤버를 추가·삭제하고, 멤버 설정을 바꾸고, 함께 기여 |
| 공유 방법 | 이메일로 특정 팀원에게 / 이메일 목록으로 여러 명 한꺼번에 / 조직 전체에 (만들 때나 나중에) |
| 찾기·알림 | 남이 공유한 프로젝트는 Shared with me(나와 공유됨) 탭에서 찾고, 공유되면 이메일 알림 |
| 관리 | 만든 사람은 권한을 바꾸거나 접근을 뺄 수 있음. 여러 멤버가 같은 프로젝트에 문서를 보태고 대화를 만들며 함께 일함 |
🔧 참고 — 관리자 설정과 새 버전 프로젝트(베타)
관리자 설정. Owner(소유자)는 조직의 프로젝트 공유를 끌 수 있고, Enterprise 요금제에서는 특정 역할에 대해서만 끌 수도 있습니다. Share projects 를 끄면 Public projects(공개 프로젝트)도 꺼집니다. 공유가 꺼지면 새 사용자·그룹과 공유할 수 없고, 기존 공유는 그대로 남습니다. Owner·Primary Owner 가 공개 프로젝트를 끄면 조직 전체 공유도 만들 때나 나중에나 꺼집니다.
새 버전 프로젝트(베타). Claude Code 부터 단계적으로 나오는 새 버전에서는 프로젝트가 대화 하나이고, Claude 가 일을 클라우드에서 도는 여러 갈래(thread)로 나눠 동시에 진행합니다. 노트북을 닫아도 갈래는 계속 돌고, 모든 갈래가 프로젝트의 파일·저장소·지침·메모리를 가지고 시작하며, 프로젝트의 Library 가 내가 넣은 파일과 Claude 가 만든 파일을 모읍니다. 수집일 기준 일부 Pro·Max·Ultra 의 Claude Code 사용자에게 베타로 열렸고, chat·Cowork·Team·Enterprise 는 뒤따를 예정입니다. 옮겨진 기존 프로젝트는 지침·파일·대화 기록·예약 작업이 그대로 따라옵니다. 여러 갈래를 동시에 돌리면 요금제 사용량을 더 빨리 씁니다. 이 장의 나머지 설명은 현재 버전 기준입니다.
지식이 아주 많아지면 — RAG
프로젝트 지식이 커져 컨텍스트 창 한도에 다가오면 어떻게 될까요? 유료 요금제(Pro·Max·Ultra·Team·Enterprise)에서는 프로젝트가 RAG(Retrieval Augmented Generation — 전부 읽는 대신, 질문과 관련된 조각만 찾아와서 답에 쓰는 방식)로 자동 전환됩니다. 원문에 따르면 이 모드는 답의 품질을 유지하면서 담을 수 있는 양을 최대 10배까지 늘립니다.
| 방식 | 어떻게 찾나 | 원문 |
|---|---|---|
| 전통적 RAG (정적 검색) | 입력 질문과 가장 비슷한 조각 묶음을 한 번에 가져와 답을 만듦 | 멀티 에이전트 연구 글 |
| 에이전트식 검색 | 여러 단계로 검색하며, 새로 알게 된 것에 맞춰 방향을 바꿈 | 멀티 에이전트 연구 글 |
| 필요할 때 읽기 (just in time) | 파일 경로 같은 가벼운 표식만 들고 있다가 도구로 그때그때 불러옴(1장) | 컨텍스트 엔지니어링 글 |
| 혼합 (Claude Code) | CLAUDE.md 는 처음부터 넣고, 나머지 파일은 glob·grep(파일 이름·내용을 찾는 명령)으로 필요할 때 찾아 읽음 | 컨텍스트 엔지니어링 글 |
원문은 어느 정도까지 미리 넣고 어디부터 찾아 읽게 할지는 일에 따라 다르며, "되는 것 중 가장 단순한 것을 하라"를 여전히 가장 좋은 조언으로 꼽습니다. 미리 넣는 쪽은 빠르고, 찾아 읽는 쪽은 느리지만 낡은 색인 문제를 피합니다.
- 코딩 안 하는 팀: Claude 프로젝트에 문서를 올리고, 많아지면 RAG 에 맡깁니다(유료 요금제).
- Claude Code 를 쓰는 팀: 항상 필요한 짧은 사실만
CLAUDE.md에, 나머지는 폴더에 정리해 두고 필요할 때 읽게 하며, 바깥 시스템의 최신 내용은 MCP 로 잇습니다.
무엇을 어디에 이을까 — 한 표로
이 장의 선택지를 "어떤 지식을, 누가, 어디서" 쓰는지로 정리했습니다. 각 칸의 기능은 원문 사실이고, 개인 팀·회사 팀에 짝짓는 방식은 이 가이드의 제안입니다(범위 전체는 9장).
| 이런 지식이라면 | 개인 팀 (이 가이드의 제안) | 회사 팀 (이 가이드의 제안) |
|---|---|---|
| 바깥 도구의 최신 내용 (일정·이슈·DB) | MCP 를 사용자 범위나 로컬 범위로 — 비밀 정보가 든 서버는 로컬 | MCP 를 프로젝트 범위 .mcp.json 으로 커밋, API 키는 환경 변수로 |
| 정리해 둔 문서 (목표·용어·결정) | 내 폴더의 파일 + 필요할 때 읽기 | 저장소의 파일, 또는 코딩 안 하는 팀은 Claude 프로젝트 지식 |
| 답하는 방식 (말투·관점) | 사용자 범위 지침 파일(3장) | 프로젝트 지침 파일, 또는 Claude 프로젝트 지침 |
| 지식이 아주 많을 때 | 폴더 정리 + 필요할 때 읽기 | Claude 프로젝트(유료 요금제)는 RAG 로 자동 확장 |
| 조직이 정해 주는 도구 | — | 관리자가 관리 설정으로 제공하거나 claude.ai 커넥터로 추가(Team·Enterprise 는 관리자만) |
- MCP 는 AI 앱을 데이터·도구·워크플로에 잇는 오픈 표준, "AI 앱용 USB-C 포트"입니다. 다른 도구 내용을 채팅에 복사하고 있다면 연결할 때입니다.
- Claude Code 의 MCP 범위: 로컬(나·이 프로젝트, 기본값) · 프로젝트(
.mcp.json, 버전 관리로 팀 공유) · 사용자(나·모든 프로젝트). - 회사 팀은
.mcp.json을 커밋해 모두 같은 도구를 쓰고, 팀원은 처음 쓸 때 승인합니다. 에이전트 팀원도 같은 MCP 서버를 불러옵니다. - 서버는 믿을 수 있는지 먼저 확인합니다(프롬프트 주입 위험).
- 코딩 안 하는 팀은 Claude 프로젝트: 프로젝트 지식 + 프로젝트 지침 + 대화. Team·Enterprise 에서 Can view / Can edit 로 공유합니다.
- 지식이 한도에 다가오면 유료 요금제의 프로젝트는 RAG 로 자동 전환해 최대 10배까지 담습니다.
출처: https://modelcontextprotocol.io/docs/getting-started/intro · https://code.claude.com/docs/en/mcp · https://support.claude.com/en/articles/9517075-what-are-projects · https://code.claude.com/docs/en/agent-teams · https://www.anthropic.com/engineering/multi-agent-research-system · https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents (수집일 2026-11-10)
개인 팀과 회사 팀 — 범위 · 보안 · 관리
이 가이드가 처음에 던진 질문으로 돌아옵니다: 개인 일을 하는 에이전트 팀과 회사 일을 하는 에이전트 팀을 따로 꾸리되, 각 팀 안에서는 모든 에이전트가 같은 목표와 맥락을 갖게 하려면? 열쇠는 앞 장들의 파일을 어느 범위에 두느냐입니다. 그리고 반드시 지켜야 할 규칙·비밀 정보·오래된 기억을 어떻게 관리하는지도 다룹니다.
- 범위(조직·사용자·프로젝트·로컬)로 개인 팀과 회사 팀을 나누는 법 — 한 표로
- 개인 팀과 회사 팀 각각의 구성 예(이 가이드의 제안)와 거기 쓰는 기능(원문 사실)
- 지침 파일은 "맥락"일 뿐 — 반드시 막아야 할 것은 훅·권한 규칙·관리 설정으로
- 팀원 에이전트는 내 대신 승인할 수 없다는 것, 메모리·MCP 의 비밀 정보 주의
- 세컨드 브레인을 낡지 않게: 정기 점검, 충돌 정리, 오래된 것 보관
- 개인 팀과 회사 팀을 어떻게 나누나 — 범위로 나눈다 — 표 하나로 "어디에 두면 누가 읽나"
- 개인 팀 구성 예 — 내 컴퓨터의 사용자 범위 + 개인용 폴더 하나
- 회사 팀 구성 예 — 회사 저장소의 프로젝트 범위 + 조직이 정한 층
회사에서 보안 담당이거나 팀 설정을 맡았다면 「반드시 지킬 규칙은 강제 장치로」도 꼭 보세요. 비밀 정보 다루는 법은 이 장 뒤쪽 「보안 — 비밀 정보와 승인」 소절에 있습니다.
개인 팀과 회사 팀을 어떻게 나누나 — 범위로 나눈다
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장).
🔧 참고 — 개인 범위의 세부 동작
- 여러 워크트리에서 같은 개인 메모: git 에 안 올리는
CLAUDE.local.md는 만든 워크트리에만 있습니다. 워크트리 사이에 개인 지침을 나누려면 홈 폴더의 파일을 불러옵니다:@~/.claude/my-project-instructions.md. - 개인 스킬의 범위:
~/.claude/skills/는 이 컴퓨터의 모든 프로젝트에서 읽히지만, Cowork·클라우드 세션에서는 읽히지 않습니다. 그쪽에서도 쓰려면 claude.ai 계정에 켠 스킬을 씁니다. - 역할 정의 우선순위: 같은 이름이면 관리 설정(1) ›
--agents명령줄(2) ›.claude/agents/(3) ›~/.claude/agents/(4) › 플러그인(5) 순으로 높은 쪽을 씁니다. - 서브에이전트 메모리: 역할 정의의
memory칸에user를 주면 모든 프로젝트에 걸친 배움을~/.claude/agent-memory/<이름>/에 쌓습니다.
회사 팀 구성 예 — 회사 저장소 + 조직 범위
회사 일을 하는 팀은 세컨드 브레인을 모두가 받는 곳, 즉 회사 저장소(프로젝트 범위)에 둡니다. 원문은 프로젝트 지침을 "버전 관리로 팀원과 공유하는 지침"(프로젝트 구조, 코딩 표준, 공통 작업 방식)이라고 설명합니다. 아래 구성은 이 가이드의 제안이고, 경로와 기능은 원문 그대로입니다.
조직 층
관리형 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.md위치: macOS/Library/Application Support/ClaudeCode/CLAUDE.md· Linux·WSL/etc/claude-code/CLAUDE.md· WindowsC:\Program Files\ClaudeCode\CLAUDE.md. MDM·그룹 정책·Ansible 같은 구성 관리 도구로 배포합니다. - 별도 파일 대신
managed-settings.json안의claudeMd키에 내용을 직접 넣을 수 있습니다(관리·정책 설정에서만 유효, 사용자·프로젝트·로컬 설정에 넣으면 무시). 예:{"claudeMd": "Always run `make lint` before committing.\nNever push directly to main."} - 세션을 지침 파일 읽기를 끈 채로 시작하면 관리형 내용도 읽히지 않습니다. 그래서 원문은 이 파일은 안내용으로 쓰고, 강제는 관리 설정(
permissions.deny등)으로 하라고 합니다. - 큰 모노레포에서 상위 폴더의 상관없는 지침을 빼려면
claudeMdExcludes(경로·glob 패턴, 설정 층끼리 합쳐짐)를 씁니다. 관리형 지침은 뺄 수 없습니다. - 스킬도 관리 설정 폴더의
.claude/skills/로 조직 전체에 배포할 수 있습니다.
반드시 지킬 규칙은 강제 장치로 — 지침은 맥락일 뿐
원문이 여러 번 강조하는 사실입니다: 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/settings.json — 권한 규칙 (원문 예)
{
"permissions": {
"allow": ["Bash(pnpm tsc --noEmit)"],
"ask": ["Bash(git push *)"],
"deny": ["Read(./.env)", "Read(./.env.local)", "Read(./secrets/**)"]
}
}
// .claude/settings.json — 파일 수정 뒤 서식 정리 훅 (원문 예)
{
"hooks": {
"PostToolUse": [
{ "matcher": "Edit|Write",
"hooks": [ { "type": "command", "command": "npx prettier --write --ignore-unknown \"$(jq -r '.tool_input.file_path')\"" } ] }
]
}
}
- 규칙은 의도가 아니라 도구 호출에 맞춰집니다.
Read규칙은cat .env도 잡지만, 그 파일을 여는 스크립트는 못 잡습니다.WebFetchdeny 는 샌드박스가 켜져 있지 않으면 같은 주소로의curl을 막지 못합니다. - 훅이 망가지거나 시간 초과돼도 막으려면
onFailure: "block"을 더합니다. .claude/settings.local.json·~/.claude/settings.json은 나만,.claude/settings.json은 커밋하면 저장소의 모두에게. 그 deny 규칙은 바로 적용되고,allow규칙과 훅은 각자 그 폴더의 신뢰 확인을 받아들인 뒤 적용됩니다.- 관리형
CLAUDE.md와 관리 설정의 역할 분담(원문 표): 도구·명령·경로 막기 →permissions.deny, 샌드박스 강제 →sandbox.enabled, 환경 변수 →env, 로그인 제한 →forceLoginMethod·forceLoginOrgUUID/ 코드 스타일·데이터 취급 안내·행동 지시 → 관리형CLAUDE.md. - 팀원 권한 세부(분할 창 팀원에게
--allowedTools가 전달되지 않음 등)와 버전 조건은 원문 agent-teams 「Permissions」를 봅니다.
보안 — 비밀 정보와 승인
세컨드 브레인은 여러 에이전트가 함께 읽는 곳이라, 거기 적힌 것은 그 팀의 모든 에이전트에게 보인다고 생각해야 합니다. 원문 곳곳의 주의 사항을 모으면 아래와 같습니다.
| 위험 | 원문의 대책 |
|---|---|
| 메모리에 비밀 정보가 저장됨 | 메모리 도구: Claude 는 보통 민감한 정보를 메모리 파일에 쓰기를 거부하지만, 더 확실히 하려면 저장 전에 민감한 데이터를 걷어내는 검사를 앱에 넣습니다. |
| 메모리 파일이 끝없이 커짐 | 메모리 도구: 파일 크기를 추적해 상한을 두고, view 가 돌려주는 글자 수도 제한합니다. |
| 메모리 폴더 밖 파일에 접근 | 메모리 도구: /memories/../../secrets.env 같은 경로로 폴더 밖에 닿을 수 있으니 모든 경로를 검사합니다(아래 접힌 상자). |
| 비밀 정보가 든 MCP 설정이 공유됨 | 그런 서버는 로컬 범위에. 공유하는 .mcp.json 에는 ${API_KEY} 처럼 환경 변수로. |
| 믿을 수 없는 MCP 서버 | 연결 전에 확인. 바깥 내용을 가져오는 서버는 프롬프트 주입 위험. |
| 남이 커밋한 파일이 내 홈 폴더 파일을 불러옴 | 프로젝트 지침의 바깥 불러오기는 처음에 승인 창이 뜹니다. 거절하면 계속 꺼진 채로 둡니다. |
| 저장소에 든 스킬이 도구 권한을 넓힘 | 스킬은 allowed-tools 로 스스로 넓은 도구 권한을 줄 수 있으니, 저장소에 들어 있는 스킬의 이 칸을 Claude Code 를 실행하기 전에 확인합니다. |
| 팀원이 대신 승인하려 함 | 팀원은 내 대신 승인·동의할 수 없음. 승인은 리더 세션에서 내가. |
| 회사 프로젝트를 너무 넓게 공유 | Claude 프로젝트: Owner 는 조직의 프로젝트 공유를 끌 수 있고, 만든 사람은 권한을 바꾸거나 접근을 뺄 수 있습니다. |
.env)은 지침이 아니라 deny 규칙으로 막습니다.🔧 개발자용 참고 — 메모리 도구의 경로 검사 (원문)
- 모든 경로가
/memories로 시작하는지 확인 - 경로를 정식 형태로 바꾼 뒤에도 메모리 폴더 안에 있는지 확인
../·..\같은 거슬러 오르기 패턴이 든 경로 거부- URL 인코딩된 패턴(
%2e%2e%2f)도 주의 - 언어에 있는 경로 보안 도구 사용(예: Python 의
pathlib.Path.resolve()와relative_to())
메모리 도구는 앱(클라이언트) 쪽에서 돌아가므로 이 보호 장치들은 앱을 만드는 쪽의 책임입니다.
낡지 않게 관리하기 — 정기 점검 · 충돌 정리 · 보관
세컨드 브레인은 쓸수록 쌓입니다. 쌓인 것이 서로 어긋나거나 낡으면, 같은 목표·맥락을 주려던 장치가 오히려 에이전트를 헷갈리게 합니다. 원문은 두 지시가 서로 어긋나면 Claude 가 아무거나 하나를 고를 수 있다고 말합니다.
① 쌓기 — 언제 지침에 더하나
원문 기준: Claude 가 같은 실수를 두 번째 할 때, 코드 검토에서 Claude 가 알았어야 할 것이 잡혔을 때, 지난 세션에 했던 정정을 또 입력하고 있을 때, 새 팀원도 알아야 할 맥락일 때. 매 세션 필요한 사실만 CLAUDE.md 에, 여러 단계 절차나 일부에만 해당하는 것은 스킬이나 경로별 규칙으로 옮깁니다.
② 점검 — 낡은 것과 충돌 찾기
원문은 CLAUDE.md, 하위 폴더의 CLAUDE.md, .claude/rules/ 를 주기적으로 검토해 낡거나 충돌하는 지시를 지우라고 합니다. Claude 에게 맡기려면 세션에서 /doctor prompt-audit 를 실행합니다: 예전 모델용 지시, 없는 파일·명령을 가리키는 내용, 서로 모순되는 파일을 찾아 고칠 안을 보고하고, 내가 적용하라고 하기 전에는 아무것도 바꾸지 않습니다.
③ 정리 — 짧게, 한쪽으로
지침 파일은 파일당 200줄 아래가 목표입니다(길수록 컨텍스트를 먹고 잘 안 따름). 사용자 규칙과 프로젝트 규칙이 부딪치면 어느 쪽을 따를지 모르니 한쪽으로 맞춥니다. 자동 메모리의 MEMORY.md 는 시작 때 처음 200줄 또는 25KB 까지만 읽히므로, 한도에 가까우면 Claude Code 가 한 줄 한 항목·세부는 주제 파일로·낡은 항목은 합치거나 지우라고 Claude 에게 알려 줍니다. /memory 로 직접 열어 고치거나 지울 수 있습니다.
④ 보관 — 끝난 것은 옮기기
PARA 의 보관(Archives)은 앞의 세 칸(프로젝트·영역·자원)에서 더는 활성이 아니지만 나중에 참고할 수 있는 것을 두는 곳입니다(2장). 끝난 프로젝트의 노트를 보관 폴더로 옮기면, 활성 맥락이 가벼워집니다. 메모리 도구 문서도 오랫동안 접근하지 않은 메모리 파일은 주기적으로 지우라고 권합니다.
| 무엇이 | 스스로 지워지나 (원문) | 그래서 |
|---|---|---|
| 세션 대화 기록 | 보관 기간(cleanupPeriodDays)이 지나면 Claude Code 가 지움 | 오래 남길 것은 파일로 |
자동 메모리(MEMORY.md·주제 파일) | 그 정리에서 빠짐 — 나나 Claude 가 고치거나 지울 때까지 남음 | 정기 점검에서 직접 보기 |
| 메모리 도구 파일 | 앱이 정함 | 오래 안 쓴 파일은 주기적으로 지우기 |
| 지침·스킬·역할 파일 | 내가 지울 때까지 남음 | /doctor prompt-audit 로 점검 |
🔧 참고 — 점검 명령의 범위와 조건
/doctor prompt-audit는 기본으로CLAUDE.md·CLAUDE.local.md·AGENTS.md와.claude/·~/.claude/아래의 규칙·스킬·명령·서브에이전트·출력 스타일을 봅니다. 한 파일이나 폴더만 보려면 경로를 줍니다:/doctor prompt-audit .claude/skills/deploy.- 번들
/claude-api스킬로 돌아가므로, 그 스킬을skillOverrides나disableBundledSkills로 꺼 두면 쓸 수 없습니다. Claude Code v2.1.283 이상이 필요합니다. - 자동 메모리 파일이 YAML 머리말로 시작하면 Claude Code 가 쓴 시각을
modified칸에 기록합니다. 그 사실이 얼마나 최신인지 나와 Claude 둘 다 볼 수 있습니다.
- 범위는 넷: 조직(관리형, 모든 사용자) · 사용자(
~/.claude/, 나·모든 프로젝트) · 프로젝트(저장소, 버전 관리로 팀) · 로컬(CLAUDE.local.md, 나·이 프로젝트). 넓은 범위부터 읽힙니다. - 이 가이드의 제안: 개인 팀 = 사용자 범위 + 개인용 폴더, 회사 팀 = 회사 저장소 + 조직 범위, 회사 일 속 나만의 메모 = 로컬. 사용자 범위는 회사 저장소에서도 읽히니 공통 선호만.
- 에이전트 팀의 팀원은 CLAUDE.md·MCP 서버·스킬을 불러오므로, 같은 폴더(저장소)에서 띄우면 같은 맥락을 갖습니다.
- 지침 파일은 맥락일 뿐입니다. 예외가 없어야 할 규칙은 훅·권한 deny·관리 설정으로, 그리고 강제 목록은 작게.
- 팀원은 내 대신 승인할 수 없고, 리더의 권한 모드로 시작합니다. 메모리·MCP 설정에 비밀 정보를 두지 않습니다.
- 쌓기 → 점검(
/doctor prompt-audit) → 정리(200줄 아래, 충돌 없애기) → 보관(끝난 것은 Archives)을 되풀이합니다.
출처: https://code.claude.com/docs/en/memory · https://code.claude.com/docs/en/agent-teams · https://code.claude.com/docs/en/best-practices · https://code.claude.com/docs/en/sub-agents · https://code.claude.com/docs/en/skills · https://code.claude.com/docs/en/mcp · https://platform.claude.com/docs/en/agents-and-tools/tool-use/memory-tool · https://support.claude.com/en/articles/9517075-what-are-projects · https://fortelabs.com/blog/para (수집일 2026-11-10)
부록 — 출처 · 받지 않은 자료 · 용어 대조
이 가이드가 근거로 쓴 원문 18쪽과, 일부러 받지 않은 자료, 원문 영어 용어와 이 가이드 한국어 용어의 대조표입니다.
- 어느 장이 어느 원문을 근거로 했는지
- 이 가이드가 다루지 않은 것(더 알아볼 곳)
- 원문을 직접 읽을 때 만나는 영어 용어의 뜻
출처 — 원문 18쪽 (수집일 2026-11-10)
하나의 공식 문서가 있는 주제가 아니어서, Anthropic 공식 문서(Claude Code·Claude API·Claude 도움말·엔지니어링 블로그)와 오픈 표준(AGENTS.md·MCP), 세컨드 브레인 원 개념(Forte Labs)과 레퍼런스(위키백과), 안드레 카파시의 「LLM Wiki」 아이디어 글(2026-11-10 사용자 요청으로 추가)을 모아 구성했습니다. 제품 문서는 자주 바뀌므로 화면·명령이 다르면 원문 최신판을 따르세요.
| 원문 | 주소 | 종류 | 다룬 내용 | 쓴 장 |
|---|---|---|---|---|
claude-code_memory | code.claude.com/docs/en/memory | 공식·표준 | CLAUDE.md(사람이 쓰는 지침)·자동 메모리, 범위(조직·프로젝트·개인), 불러오는 순서, rules | ch03, ch05, ch09 |
claude-code_sub-agents | code.claude.com/docs/en/sub-agents | 공식·표준 | 서브에이전트 정의 파일, 자기 컨텍스트, 도구 제한, 지속 메모리 | ch05, ch06 |
claude-code_agent-teams | code.claude.com/docs/en/agent-teams | 공식·표준 | 에이전트 팀 — 리더·팀원, 공유 작업 목록, 서로 메시지, 팀원이 받는 맥락 | ch00, ch06, ch09 |
claude-code_skills | code.claude.com/docs/en/skills | 공식·표준 | 스킬 — 절차·지식을 폴더로 묶어 필요할 때만 불러옴 | ch04 |
claude-code_mcp | code.claude.com/docs/en/mcp | 공식·표준 | MCP 서버 연결, 범위(로컬·프로젝트·사용자), 팀 공유 .mcp.json | ch08 |
claude-code_best-practices | code.claude.com/docs/en/best-practices | 공식·표준 | 컨텍스트 관리, CLAUDE.md 잘 쓰기, 여러 세션 병렬 작업 | ch01, ch03, ch04, ch09 |
claude-api_memory-tool | platform.claude.com/docs/en/agents-and-tools/tool-use/memory-tool | 공식·표준 | 메모리 도구 — 대화를 넘어 파일로 기억, 멀티 세션 작업 패턴 | ch01, ch05, ch07, ch09 |
claude-help_projects | support.claude.com/en/articles/9517075-what-are-projects | 공식·표준 | Claude 프로젝트 — 지식·지침을 묶어 팀과 공유 (코딩 없이) | ch08, ch09 |
anthropic_context-engineering | www.anthropic.com/engineering/effective-context-engineering-for-ai-agents | 공식·표준 | 컨텍스트 엔지니어링, 컨텍스트 썩음, 구조화된 메모, 서브에이전트 구조 | ch00, ch01 |
anthropic_multi-agent-research | www.anthropic.com/engineering/multi-agent-research-system | 공식·표준 | 오케스트레이터·작업자 구조, 위임할 때 줄 것, 기억 저장, 비용 | ch06, ch07 |
anthropic_building-effective-agents | www.anthropic.com/engineering/building-effective-agents | 공식·표준 | 워크플로와 에이전트, 단순하게 시작, 패턴들 | ch06 |
anthropic_long-running-harness | www.anthropic.com/engineering/effective-harnesses-for-long-running-agents | 공식·표준 | 긴 작업 — 진행 기록 파일·기능 목록·git 으로 세션 사이 인수인계 | ch07 |
agents-md | agents.md | 공식·표준 | AGENTS.md — 여러 에이전트 도구가 함께 읽는 오픈 형식 | ch03 |
mcp_intro | modelcontextprotocol.io/docs/getting-started/intro | 공식·표준 | MCP — AI 앱과 외부 시스템을 잇는 표준 (USB-C 비유) | ch08 |
fortelabs_basb | fortelabs.com/blog/basboverview | 공식·표준 | 세컨드 브레인 원 개념, CODE(모으기·정리·추리기·표현) | ch00, ch02 |
fortelabs_para | fortelabs.com/blog/para | 공식·표준 | PARA(프로젝트·영역·자원·보관) 정리법 | ch02 |
karpathy_llm-wiki | gist.github.com/karpathy/442a6bf555914893e9891c11519de94f | 블로그 | 안드레 카파시의 LLM 위키 — AI 가 원문을 읽어 마크다운 위키를 쌓고 고침(원문·위키·스키마 3층, 넣기·묻기·점검, index.md·log.md) | ch02 |
wikipedia_pkm | en.wikipedia.org/wiki/Personal_knowledge_management | 레퍼런스 | 개인 지식 관리(PKM)의 정의와 배경 | ch00, ch02 |
받지 않은 자료 — 더 알아볼 곳
조사 범위(원문 20쪽 이내)에 맞춰 아래는 받지 않았습니다. 이 가이드는 이 내용들을 원문에 나온 한 줄 언급 이상으로 설명하지 않습니다.
- Claude Code 설치·로그인 — 설치 방법은 공식 안내를 따르세요.
- 훅(hooks)·권한(permissions)·설정(settings) 전용 문서 — 「반드시 막아야 할 것은 훅·권한 규칙으로」라는 원칙은 다루지만, 설정 방법 세부는 다루지 않습니다.
- 세션 사이 메시지(cross-session messaging)·비용(costs) 전용 문서 — 에이전트 팀 문서가 가리키는 곳입니다.
- Claude Code 외 도구(Codex·Cursor 등)의 자체 문서 — AGENTS.md 가 여러 도구에서 읽힌다는 사실만 AGENTS.md 원문으로 씁니다.
- 세컨드 브레인 책·노트 앱별 사용법 — Forte Labs 소개 글 두 편과 위키백과 PKM 항목만 근거로 씁니다.
용어 대조 — 원문 영어 ↔ 이 가이드
| 원문 | 이 가이드 | 처음 설명하는 곳 |
|---|---|---|
| Second Brain | 세컨드 브레인 (팀이 함께 읽고 쓰는 공용 기억) | 0장 |
| context · context window | 컨텍스트 · 컨텍스트 창 | 1장 |
| attention budget · context rot | 주의력 예산 · 컨텍스트 썩음 | 1장 |
| compaction | 압축 | 1장 |
| structured note-taking | 구조화된 메모 | 1장 |
| Capture · Organize · Distill · Express (CODE) | 모으기 · 정리하기 · 추리기 · 표현하기 | 2장 |
| Projects · Areas · Resources · Archives (PARA) | 프로젝트 · 영역 · 자원 · 보관 | 2장 |
| LLM Wiki · Ingest · Query · Lint | LLM 위키 · 넣기 · 묻기 · 점검 | 2장 |
| CLAUDE.md · AGENTS.md | 지침 파일 | 3장 |
| scope (managed · user · project · local) | 범위 (조직 · 사용자 · 프로젝트 · 로컬) | 3장 |
| Skill | 스킬 | 4장 |
| auto memory · memory tool | 자동 메모리 · 메모리 도구 | 5장 |
| subagent · subagent definition | 서브에이전트 · 역할 정의 파일 | 6장 |
| agent teams · team lead · teammate | 에이전트 팀 · 리더 · 팀원 | 6장 |
| spawn prompt | 생성 지시문 | 6장 |
| progress file · feature list | 인수인계 노트 · 기능 목록 | 7장 |
| MCP (Model Context Protocol) | MCP (AI 앱을 외부 도구에 잇는 표준) | 8장 |
| Projects (claude.ai) | Claude 프로젝트 | 8장 |
- 근거는 원문 18쪽 — 대부분 Anthropic 공식 문서이고, 세컨드 브레인 원 개념은 Forte Labs 글, AI 가 관리하는 위키 방식은 카파시의 LLM Wiki 글입니다.
- 설치·훅·권한 설정 세부와 다른 도구의 자체 문서는 다루지 않았습니다.
- 원문을 직접 읽을 때는 위 용어 대조표를 곁에 두세요.
출처: agent-second-brain/sources/INDEX.md (수집일 2026-11-10)