전체 문서 목록
에이전트 세컨드 브레인 완전 가이드 · 2026-11-10 기준

에이전트 팀 모두가
같은 목표와 맥락으로 일하게 하는 공용 기억

이 가이드는 한 가지 질문에 답합니다. “개인 일을 하는 에이전트 팀, 회사 일을 하는 에이전트 팀을 따로 꾸리되, 팀 안의 모든 에이전트가 같은 목표와 맥락을 갖게 하려면 무엇을 어떻게 준비하나?” 답은 팀이 함께 읽고 쓰는 세컨드 브레인, 곧 에이전트들이 일을 시작할 때마다 읽고, 일하면서 고쳐 쓰는 공용 기억 파일 묶음입니다.

하나의 제품이 아니라 설계 방법기준 도구: Claude Code개인 팀 · 회사 팀공식 문서 등 원문 18쪽 기준
아주 쉽게 말하면 에이전트(사람 대신 도구를 써 가며 일하는 AI)를 교대 근무하는 직원이라고 생각해 보세요. 이 직원은 출근할 때마다 어제 일을 하나도 기억하지 못합니다. 새로 들어온 동료도 팀장이 그동안 나눈 대화를 듣지 못했습니다. 그래도 일이 이어지려면 모두가 출근하자마자 펼쳐 보는 공용 업무 노트가 있어야 합니다. 목표가 무엇인지, 어디까지 했는지, 무엇을 조심해야 하는지 적힌 노트 말입니다. 이 가이드는 그 노트를 어떤 파일에, 어떤 순서로, 누가 쓰게 할지 정하는 법을 다룹니다.
이 가이드를 읽는 법 본문만 읽어도 “무엇이고, 왜 필요하고, 어떻게 하는지” 알 수 있게 썼습니다. 설정 경로·버전 조건 같은 세부는 접힌 참고 상자에 넣었으니 처음에는 건너뛰어도 됩니다. 각 장 맨 위의 처음이라면 이것만 안내를 따라가면 핵심 소절만 골라 읽을 수 있습니다. 더 짧게 보려면 한눈에 보기나 필수판을, 그림으로 먼저 감을 잡으려면 쉬운 설명을, 직접 만들어 보려면 활용편(실습 10개)을 보세요.
이 가이드의 제안 — 표시 읽는 법 세컨드 브레인은 어느 회사가 파는 기능 이름이 아닙니다. 이 가이드는 Claude Code 공식 문서, Anthropic 엔지니어링 글, 열린 표준(AGENTS.md · MCP), 세컨드 브레인의 원래 개념(Forte Labs)을 엮어 설계 방법을 제안합니다. 그래서 두 가지를 구분해 씁니다. 제품이 실제로 하는 일(무엇이 언제 읽히는지, 파일 경로, 한도)은 원문에 적힌 그대로만 씁니다. 원문을 조합해 만든 설계(폴더 구성 예, 목표 문서 양식 등)는 지금 이 상자처럼 “이 가이드의 제안”이라고 밝힙니다. 원문에 없는 예시 파일 이름은 “예시 이름”이라고 적습니다.

문제 — 에이전트는 어제를 기억하지 못하고, 팀원은 리더의 대화를 모릅니다

사람으로 이루어진 팀은 회의록이 없어도 어느 정도 굴러갑니다. 각자 머릿속에 어제 회의, 지난주 결정, 팀장의 말버릇이 남아 있기 때문입니다. 에이전트 팀은 다릅니다. 원문은 두 가지 사실을 분명히 적고 있습니다.

① 세션이 바뀌면 ② 팀원이 새로 생기면 세션 1 나눈 대화 함께 정한 결정 찾아낸 사실 고친 실수 세션 2 빈 컨텍스트로 시작 같은 사실을 다시 찾아야 함 ✗ “새 세션은 앞선 일을 전혀 기억하지 못한 채 시작한다” — 긴 작업 에이전트에 관한 글 리더 나와 나눈 긴 대화 기록 팀원 자기 컨텍스트 창에서 따로 일함 ✗ 생성 지시문 프로젝트 맥락 = CLAUDE.md · MCP · 스킬 팀원이 생길 때 보통 세션처럼 읽어 들임 “리더의 대화 기록은 넘어가지 않는다” — 에이전트 팀 문서
에이전트에게 “어제의 기억”과 “팀장의 머릿속”은 저절로 전해지지 않습니다. 전해지는 것은 파일로 적어 둔 것과 처음 받은 지시뿐입니다.

① 세션마다 처음부터 시작합니다. 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 — 한 사람이 지식을 모으고, 분류하고, 저장하고, 찾고, 나누는 과정)라고 부릅니다.

원뜻 — 한 사람의 세컨드 브레인 이 가이드 — 팀의 세컨드 브레인 나 생각을 떠올림 디지털 지식 창고 메모 앱 · 폴더 배운 것 + 출처 적기 꺼내 쓰기 개인 지식 관리(PKM)의 한 방법 모으기 → 정리하기 → 추리기 → 표현하기 공용 기억 함께 보는 파일 묶음 리더 팀원 A 팀원 B 다음 세션 모두가 시작할 때 읽고, 일하며 고쳐 씀
원뜻은 “한 사람의 외부 기억”, 이 가이드의 뜻은 “여러 에이전트가 함께 쓰는 외부 기억”입니다.

이 가이드는 이 말을 넓혀 씁니다. 여기서 세컨드 브레인은 에이전트 팀이 함께 읽고 쓰는 공용 기억(파일 묶음)입니다. 사람 한 명의 메모장이 아니라, 리더·팀원·다음 세션이 모두 같은 곳을 보는 팀 노트입니다. 원뜻과 넓힌 뜻을 섞지 않도록 이후 장에서는 원래 개념을 말할 때 “Forte Labs 의 세컨드 브레인”이라고 출처를 붙입니다.

이 넓힌 뜻은 억지가 아닙니다. Anthropic 의 컨텍스트 엔지니어링 글은 에이전트가 정보를 다루는 좋은 방식을 사람의 기억법에 빗댑니다. 사람은 자료 전체를 외우지 않고, 파일 시스템·받은편지함·책갈피 같은 바깥 정리 체계를 두고 필요할 때 꺼내 봅니다. 에이전트도 파일 경로 같은 가벼운 “찾아가는 표시”만 들고 있다가 필요할 때 읽어 오는 편이 낫다는 것입니다. 사람의 세컨드 브레인을 잘 짜는 원칙이 에이전트의 공용 기억에도 그대로 통하는 이유입니다(2장).

이 가이드의 제안 공용 기억을 만드는 재료는 모두 원문에 있는 기능입니다. 사람이 쓰는 지침 파일(CLAUDE.md · AGENTS.md), 필요할 때 읽히는 스킬, Claude 가 스스로 쌓는 자동 메모리, 세션 사이에 남기는 진행 기록, 바깥 자료를 잇는 MCP 입니다. 이 가이드가 보태는 것은 이 재료를 “팀의 목표와 맥락을 모두에게 같게 전한다”는 하나의 목적에 맞게 배치하는 방법입니다.

한 장 그림 — 공용 기억을 가운데 두고 두 팀이 읽고 씁니다

아래 그림이 이 가이드 전체의 지도입니다. 가운데 공용 기억은 다섯 층으로 나뉩니다. 층을 나누는 기준은 “언제 에이전트의 컨텍스트에 들어오나”입니다. 컨텍스트는 한도가 있고 많이 넣을수록 흐려지므로(1장), 무엇이든 항상 넣지 않고 꼭 필요한 것만 항상 읽히게 합니다.

공용 기억 = 팀의 세컨드 브레인 ① 항상 읽힘 CLAUDE.md · AGENTS.md · 팀 목표 3장 ② 필요할 때 읽힘 스킬 · 지식 창고 폴더 4장 · 2장 ③ 스스로 쌓음 자동 메모리 · 메모리 도구 5장 ④ 인수인계 진행 기록 · NOTES.md · 기능 목록 7장 ⑤ 바깥 연결 MCP · Claude 프로젝트 지식 8장 개인 팀 내 일 · 나만 보는 범위 리더 에이전트 팀원 · 조사 (예) 팀원 · 글쓰기 (예) 회사 팀 회사 일 · 동료와 나누는 범위 리더 에이전트 팀원 · 검토 (예) 팀원 · 보고서 (예) 나 (사람) 목표를 정하고 지침을 쓰고 검토함 팀 구성 → 6장 개인·회사 나누기 → 9장
선 위의 점은 읽기(공용 기억 → 에이전트)와 쓰기(에이전트 → 공용 기억)를 나타냅니다. 팀원 역할 이름은 예시입니다.

층마다 “언제 읽히나”와 “누가 쓰나”가 다릅니다. 이 표의 사실은 모두 원문 기준이며, 자세한 내용은 표 오른쪽 장에서 다룹니다.

층무엇언제 컨텍스트에 들어오나누가 쓰나장
① 항상 읽힘CLAUDE.md · AGENTS.md 같은 지침 파일매 세션 시작 때. 팀원·서브에이전트도 대부분 읽음사람3장
② 필요할 때스킬(절차·지식을 폴더로 묶어 필요할 때만 불러오는 것), 주제별 자료 폴더스킬 본문은 쓸 때만. 자료는 에이전트가 찾아 읽을 때만사람4장 · 2장
③ 스스로 쌓음자동 메모리 · 메모리 도구자동 메모리는 매 세션 시작 때 처음 200줄 또는 25KB 까지Claude5장
④ 인수인계진행 기록(claude-progress.txt 등) · 기능 목록새 세션이 시작하며 읽도록 지시해 둠에이전트(사람이 양식을 정함)7장
⑤ 바깥 연결MCP(AI 앱을 외부 도구·데이터에 잇는 표준 연결 방식) · Claude 프로젝트 지식도구를 부르거나 자료를 찾을 때사람이 연결8장
이 가이드의 제안 — 개인 팀과 회사 팀은 “범위”로 나눕니다 Claude Code 는 지침 파일을 놓는 자리를 범위(scope — 그 지침이 누구에게 적용되는가)로 나눕니다. 사용자 범위 ~/.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.
MCPModel Context Protocol. AI 앱을 외부 도구·데이터에 잇는 표준 연결 방식. 원문 비유는 “AI 앱용 USB-C 포트”.
Claude 프로젝트claude.ai 에서 대화 기록과 지식 자료를 한데 묶은 작업 공간. 코딩을 하지 않는 팀의 선택지.
AGENTS.md여러 에이전트 도구가 함께 읽는 열린 형식의 지침 파일. Claude Code 도 CLAUDE.md 대신 읽을 수 있습니다.

세컨드 브레인 방법 · 그 밖의 말

용어쉬운 풀이
CODECapture(모으기) · Organize(정리하기) · Distill(추리기) · Express(표현하기). 세컨드 브레인을 만들고 쓰는 네 단계.
PARAProjects(프로젝트) · Areas(영역) · Resources(자원) · Archives(보관). 정보를 네 칸으로 나누는 정리법.
PKMPersonal 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)

CHAPTER 01

에이전트는 무엇을 기억하나 — 컨텍스트의 한계

공용 기억을 설계하려면 먼저 에이전트의 “기억”이 어떻게 생겼는지 알아야 합니다. 에이전트가 아는 것은 지금 펼쳐 놓은 글, 곧 컨텍스트뿐입니다. 이 장에서는 컨텍스트의 한도와 약점, 그리고 그 약점을 피하는 세 가지 방법(압축 · 메모 · 필요할 때 불러오기)을 차례로 보고, 이것이 이 가이드의 “다섯 층” 구조로 어떻게 이어지는지 정리합니다.

이 장에서 배우는 것
  • 컨텍스트 창이 무엇이고, 그 안에 무엇이 들어가는지
  • 글을 많이 넣을수록 오히려 흐려지는 “컨텍스트 썩음”과 “주의력 예산”
  • 긴 대화를 요약해 이어 가는 압축(/compact)의 장단점
  • 창 바깥에 메모를 적어 두고 다시 읽는 방법(NOTES.md, 메모리 도구)
  • 자료를 미리 다 넣지 않고 필요할 때 찾아 읽는 방법, 그리고 공용 기억의 다섯 층
처음이라면 이것만 컨텍스트 창에서 에이전트의 “책상”이 무엇인지 보고, 컨텍스트 썩음에서 왜 무엇이든 다 넣으면 안 되는지, 구조화된 메모에서 기억을 창 밖 파일에 두는 생각을 익히세요. 압축과 혼합 전략, 접힌 상자는 나중에 읽어도 됩니다.

컨텍스트 창 — 에이전트가 한 번에 펼쳐 보는 책상

Anthropic 의 컨텍스트 엔지니어링 글은 컨텍스트를 “모델이 답을 만들 때 함께 들어가는 토큰(AI 가 읽고 쓰는 글의 양을 세는 단위)의 묶음”이라고 정의합니다. 쉽게 말해 에이전트가 지금 책상 위에 펼쳐 둔 모든 글입니다. 컨텍스트 창(context window — 그 책상의 넓이, 한 번에 담을 수 있는 글의 한도)을 넘는 글은 올려놓을 수 없습니다.

컨텍스트 창 (책상) 한도가 있음 시스템 지시 도구 설명 지침 파일 CLAUDE.md 대화 기록 → 읽은 파일 · 도구 결과 일할수록 계속 늘어남 남은 빈자리 모델 이것만 보고 답함 요청마다 전체를 보냄 책상 위에 없는 것 = 에이전트가 모르는 것
대화가 이어질수록 “대화 기록”과 “읽은 파일”이 책상을 채워 갑니다. 다음 세션은 이 책상이 깨끗이 치워진 상태에서 시작합니다.

책상 위에는 사람이 쓴 프롬프트(에이전트에게 보내는 지시문)만 있는 것이 아닙니다. 원문은 에이전트가 관리해야 할 컨텍스트로 시스템 지시, 도구, 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 는 대화 기록을 모델에 넘겨 가장 중요한 세부를 요약·압축합니다. 설계 결정, 아직 해결 안 된 버그, 구현 세부는 남기고 중복된 도구 출력이나 메시지는 버립니다.

새 컨텍스트 창 요약 압축된 대화 최근 열어 본 파일 5개 함께 다시 올림 이어서 일함 빈자리가 다시 생김

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 파일을 관리하는 것이 그 예입니다.

창 바깥 메모 NOTES.md · /memories ① 일하기 ② 진행·결정 적기 ③ 창이 비워짐 압축 · 새 세션 ④ 메모부터 다시 읽기
컨텍스트는 비워져도 파일은 남습니다. 다음 차례의 에이전트는 메모를 읽고 그 자리에서 이어 갑니다.

원문은 코딩이 아닌 예로 포켓몬 게임을 하는 Claude를 듭니다. 이 에이전트는 수천 단계에 걸쳐 “1번 도로에서 1,234걸음째 훈련 중, 피카츄가 목표 10레벨 중 8레벨 올랐다” 같은 기록을 정확히 이어 갑니다. 메모 구조를 따로 알려 주지 않았는데도 탐험한 곳의 지도, 달성한 일, 상대별로 잘 통한 공격 같은 전략 메모를 스스로 남겼습니다. 컨텍스트가 초기화된 뒤에는 자기 메모를 읽고 몇 시간짜리 훈련과 던전 탐험을 이어 갔습니다.

원문에 있는 메모 장치누가 쓰나언제 다시 읽히나장
CLAUDE.md (지침 파일)사람매 세션 시작 때3장
자동 메모리Claude매 세션 시작 때 (처음 200줄 또는 25KB)5장
메모리 도구 /memoriesClaude (저장은 그 에이전트를 만든 개발자의 프로그램이 맡음)켜 두면 작업을 시작하기 전에 메모리 디렉터리를 자동으로 확인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.md 시작 때 넣음 찾은 파일 그때 읽음 glob · grep 저장소의 나머지 파일 이름·위치로 찾아감

Claude Code 는 혼합형입니다. CLAUDE.md 는 처음부터 컨텍스트에 넣고, glob·grep 같은 기본 도구로 주변을 탐색해 필요한 파일을 그때 읽습니다. 원문은 이렇게 해서 낡은 색인 문제를 피한다고 설명합니다.

이 방식에서는 파일의 이름과 자리 자체가 정보가 됩니다. 원문 예로, tests 폴더 안의 test_utils.py 와 src/core_logic/ 안의 같은 이름 파일은 목적이 다르다는 신호를 줍니다. 폴더 구조, 이름 짓는 규칙, 날짜는 사람에게도 에이전트에게도 “이 정보를 언제 어떻게 쓸지” 알려 줍니다. 에이전트는 탐색하면서 한 겹씩 이해를 쌓고(점진적 공개), 꼭 필요한 것만 작업 기억에 둡니다. 공용 기억의 폴더를 잘 짜야 하는 이유가 여기 있습니다(2장 PARA).

대가도 있습니다 원문은 실행 중 탐색이 미리 계산한 자료를 꺼내는 것보다 느리다고 적습니다. 알맞은 도구와 길잡이가 없으면 에이전트가 도구를 잘못 쓰거나, 막다른 길을 쫓거나, 핵심 정보를 놓쳐 컨텍스트를 낭비합니다. 법률·재무처럼 내용이 잘 안 바뀌는 일에는 일부를 미리 넣는 혼합 전략이 더 맞을 수 있고, 원문의 기본 조언은 “통하는 가장 단순한 것을 하라”입니다.

셋 중 무엇을 쓰나 — 압축 · 메모 · 여러 에이전트

원문은 긴 작업을 위한 기법으로 압축, 구조화된 메모, 그리고 서브에이전트 구조를 함께 듭니다. 서브에이전트(맡긴 일을 자기 컨텍스트에서 하고 결과만 돌려주는 도우미)는 깨끗한 컨텍스트 창에서 집중된 일을 맡아 수만 토큰을 써 가며 탐색하더라도, 돌려줄 때는 압축된 요약(흔히 1,000~2,000 토큰)만 돌려줍니다. 세부 탐색은 서브에이전트 안에 머물고, 지휘하는 쪽은 결과를 엮는 데 집중합니다.

메인 에이전트 큰 계획 · 결과 엮기 서브에이전트 1 서브에이전트 2 서브에이전트 3 각자 수만 토큰 탐색 돌려주는 것은 요약 1,000~2,000 토큰
세부 탐색의 흔적은 각 서브에이전트 안에 남고, 메인 에이전트의 책상에는 요약만 올라옵니다.
방법원문이 말하는 잘 맞는 일
압축주고받는 대화가 많이 필요한 일 — 대화의 흐름을 유지
구조화된 메모분명한 단계(이정표)가 있는 반복 개발
여러 에이전트 구조나란히 탐색하는 것이 이득인 복잡한 조사·분석
요즘 기준으로 덧붙이면 Claude Code 모범 사례 문서는 “컨텍스트 창을 지키려고 서브에이전트를 쓰라”는 조언을 이제 필요 없어진 옛 조언으로 분류합니다. 창이 모자라는 일이 드물어졌기 때문입니다. 서브에이전트는 여전히 나란히 하는 일, 시끄러운 출력 걸러내기, 독립 검토에 좋지만 그만큼 토큰이 더 듭니다. 팀 구성은 6장에서 다룹니다.

층으로 정리하기 — 공용 기억의 다섯 층

지금까지 본 원리를 모으면 공용 기억을 어떻게 나눌지가 보입니다. 기준은 “이 글이 언제 책상에 올라와야 하나”입니다. 모두가 항상 알아야 하는 짧은 것만 시작 때 넣고, 길거나 가끔 쓰는 것은 필요할 때 찾게 하고, 일하며 생긴 것은 창 밖에 적게 합니다.

① 항상 읽힘 — 지침 파일 · 팀 목표 짧게: CLAUDE.md 는 파일당 200줄 아래 권장 ② 필요할 때 — 스킬 · 자료 폴더 스킬 본문은 쓸 때만 올라옴 · 자료는 찾아서 읽음 ③ 스스로 쌓음 — 자동 메모리 · 메모리 도구 Claude 가 적고, 시작 때 일부(200줄 또는 25KB)만 읽힘 ④ 인수인계 — 진행 기록 · 기능 목록 세션 끝에 적고, 다음 세션 시작에 읽음 ⑤ 바깥 연결 — MCP · Claude 프로젝트 도구를 불러 그때 가져옴 시작 때 넣기 필요할 때 찾기 창 밖에 적기 ③은 시작 때 일부도 읽힘
층마다 원리가 다릅니다. 같은 내용이라도 어느 층에 두느냐에 따라 컨텍스트 비용과 따르는 정도가 달라집니다.
이런 내용은이 층에이유
팀 목표 · 꼭 지킬 원칙 · 자주 틀리는 것① 항상 읽힘 (3장)모든 에이전트가 매번 알아야 함. 짧아야 잘 따름
반복 절차 · 긴 참고 자료② 필요할 때 (4장)스킬 본문은 쓸 때까지 컨텍스트를 거의 쓰지 않음
내 수정·선호에서 배운 것③ 스스로 쌓음 (5장)사람이 따로 적지 않아도 Claude 가 남김
어디까지 했나 · 다음에 할 것④ 인수인계 (7장)압축·새 세션을 넘어 살아남아야 함
회사 문서 · 외부 서비스 자료⑤ 바깥 연결 (8장)복사하지 않고 원본에서 그때 가져옴
이 가이드의 제안 다섯 층은 원문의 세 원리(시작 때 넣기 · 필요할 때 찾기 · 창 밖에 적기)를 Claude Code 의 실제 장치에 짝지어 이 가이드가 붙인 이름입니다. 원문에 “다섯 층”이라는 표현이 있는 것은 아닙니다. 다음 장에서는 이 층에 담을 내용을 어떻게 고르고 정리할지, 사람용 세컨드 브레인 방법(CODE · PARA)을 빌려 정합니다.
한눈에 정리
  • 에이전트가 아는 것은 지금 컨텍스트 창(책상)에 올라온 글뿐이고, 새 세션은 빈 책상에서 시작합니다.
  • 글이 많을수록 정확히 떠올리는 힘이 완만하게 떨어집니다(컨텍스트 썩음). 좋은 컨텍스트는 “꼭 필요한 정보만 담은 가장 작은 묶음”입니다.
  • 긴 일에는 압축(요약해 이어 가기), 구조화된 메모(창 밖 파일에 적고 다시 읽기), 서브에이전트(요약만 돌려받기)를 일의 성격에 맞게 씁니다.
  • 자료는 미리 다 넣지 말고 경로·이름 같은 표시만 두고 필요할 때 찾게 합니다. 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)

CHAPTER 02

세컨드 브레인 설계 — CODE 와 PARA 를 에이전트용으로

1장에서 “어느 층에 둘까”를 정했다면, 이 장은 “무엇을, 어떤 모양으로 둘까”를 정합니다. 사람의 세컨드 브레인(배운 것을 뇌 바깥 한곳에 모아 둔 디지털 지식 창고)을 만드는 방법으로 널리 쓰이는 Forte Labs 의 CODE(네 단계)와 PARA(네 칸 정리법)를 먼저 원문대로 살펴보고, 이를 에이전트 팀의 공용 기억에 옮기는 방법을 제안합니다. 핵심은 두 가지입니다. 모든 정보를 팀의 목표와 프로젝트에 묶어 정리하고, 모든 메모를 다음 에이전트가 바로 쓸 수 있게 적는 것입니다.

이 장에서 배우는 것
  • CODE — 모으기 · 정리하기 · 추리기 · 표현하기 — 의 원뜻과 에이전트 팀용 해석
  • PARA — 프로젝트 · 영역 · 자원 · 보관 — 로 공용 기억 폴더를 나누는 법
  • 점진적 요약으로 “짧은 층”과 “긴 층”을 나누는 법
  • 팀 목표 문서를 만들어 모든 세션이 읽게 하는 법(이 가이드의 제안)
  • “미래의 나를 위한 메모”를 “다음 에이전트를 위한 메모”로 바꿔 쓰는 법
  • 카파시의 LLM 위키 — AI 가 원문을 읽어 위키를 쓰고 고치게 하는 방식과, 이 가이드에 끼우는 법(제안)
처음이라면 이것만 CODE 네 단계로 전체 흐름을 잡고, PARA 네 칸으로 폴더를 어떻게 나눌지 본 뒤, 팀 목표 문서로 “모두가 같은 목표”를 만드는 방법을 익히세요. 정리를 AI 에게 맡기고 싶다면 카파시의 LLM 위키도 보세요. 모으기·추리기·표현하기의 세부는 나중에 읽어도 됩니다.

CODE — 세컨드 브레인을 만들고 쓰는 네 단계

Forte Labs 의 티아고 포르테는 세컨드 브레인을 만드는 방법을 CODE 네 단계로 정리합니다. Capture(모으기) · Organize(정리하기) · Distill(추리기) · Express(표현하기)입니다. 원문은 이것이 세컨드 브레인을 만드는 단계이자 이후 계속 함께 일하는 단계라고 말합니다. 직업이나 메모 도구에 상관없이 쓸 수 있고, 누구나 이미 어떤 형태로든 하고 있는 일이라고도 덧붙입니다.

모으기 Capture 다시 찾을 수 없는 사실만 적기 정리하기 Organize 프로젝트·목표에 묶어 두기 추리기 Distill 짧은 요약 층과 긴 원본 층 나누기 표현하기 Express 결과물을 만들고 다시 쌓기 만든 결과물(중간 산출물)은 다시 세컨드 브레인으로 돌아감 상자 아래 두 줄 = 이 가이드가 제안하는 에이전트 팀용 해석
단계 이름은 원문 그대로, 상자 안 아래 두 줄은 이 가이드의 해석입니다.
단계원문의 뜻 (사람용)에이전트 팀으로 옮기면 (이 가이드의 제안)
모으기정말 중요한 것만, 마음에 와닿는 것만 한곳에 모음저장소(파일과 변경 이력을 함께 보관하는 프로젝트 폴더)·자료를 읽어서는 알 수 없는 결정·절차만 공용 기억에 적음
정리하기주제가 아니라 “실행에 쓸모”로 정리 — PARA폴더를 팀의 프로젝트·영역 기준으로 나눠, 에이전트가 이름과 자리로 찾게 함
추리기핵심만 남긴 짧은 요약을 겹겹이항상 읽히는 층은 요약만, 세부는 필요할 때 읽는 파일로
표현하기쌓은 지식으로 실제 결과물을 만들고 나눔세션마다 결과물 하나를 끝내고, 그 결과를 다시 공용 기억에 남김

모으기 — 다 적지 말고, 다시 찾을 수 없는 것만

원문의 첫 단계는 “가장 중요한 정보만 모으라”입니다. 우리는 이미 많은 정보를 읽고 만들지만, 그것을 한곳에 모아 두지 않아서 흩어지고 잊힌다고 원문은 진단합니다. 무엇을 모을지 정할 때 원문은 세 가지를 물어보라고 합니다.

  • 일과 삶에서 늘 되돌아오는 주제와 질문은 무엇인가?
  • 이미 손에 있는 것 중 값지고 영향력 있는 정보는 무엇인가?
  • 서로 엮고, 섞어 보고, 때때로 다시 꺼내 생각을 자극하고 싶은 지식은 무엇인가?
세션에서 생긴 것 회의 결정 · 찾은 사실 배포 절차 · 파일 구조 코드 규칙 … ① 읽어서 찾을 수 있나? ② 실제로 찾아볼까? 모범 사례 문서의 시험 공용 기억에 적기 하나라도 “아니오”일 때 적지 않기 둘 다 “예”이면 빼 둠
무엇을 모을지 거르는 시험은 Claude Code 모범 사례 문서에서 왔습니다. 사람의 “마음에 와닿는 것만”이 에이전트 팀에서는 “다시 찾을 수 없는 것만”이 됩니다.

에이전트 팀에서는 이 질문이 더 날카로워집니다. Claude Code 모범 사례 문서는 “Claude 가 저장소(파일과 변경 이력을 함께 보관하는 프로젝트 폴더)를 읽어 찾을 수 없는 것, 또는 매 세션 다시 찾느라 시간을 쓰는 것만 적으라”고 권하며, 적기 전에 두 가지를 물어보라고 합니다. 코드를 읽어 찾을 수 있나? 실제로 찾아보러 갈까? 둘 다 “예”라면 빼 둡니다. 원문이 드는 “적어야 할 것”의 예는 회의에서 정한 결정, 한 사람 머릿속에만 있는 배포 절차, 통합 테스트에 필요한 환경 변수입니다.

원문 — 큐레이터처럼

눈앞의 정보를 바로 소비하지 말고 나중을 위해 저장해 두라고 원문은 권합니다. 남이 보여 주는 대로 반응하는 대신 무엇을 들일지 스스로 고르는 사람이 되라는 뜻입니다. 새 항목은 임시 보관함(Inbox)에 모았다가 한 주에 한 번쯤 몰아서 제자리에 둔다고 합니다.

이 가이드의 제안 — 팀의 받은편지함

공용 기억에 예시 이름 inbox.md 같은 임시 파일을 두고, 에이전트가 일하며 알게 된 “적을 만한 것”을 일단 거기 적게 합니다. 사람이 주기적으로 보고 제자리(목표 문서·지침 파일·자료 폴더)로 옮기거나 지웁니다.

원문 — 모으기 도구와 “와닿는 것만”

원문은 분석하듯 고르지 말고 직관적으로 마음에 와닿는(resonate) 것을 남기라고 합니다. 그것이 대개 내가 아끼거나 궁금해하는 것과 이어져 있기 때문입니다. 모으기 도구로는 전자책 앱의 밑줄 내보내기, 나중에 읽기 앱, 기본 메모 앱, SNS 즐겨찾기, 음성 받아쓰기 앱, 웹 클리퍼를 듭니다. 한곳에 다양한 정보를 모아 두면 서로 섞이며 뜻밖의 연결과 패턴이 보이고, 재료가 필요할 때 찾아볼 곳이 하나가 된다는 것이 원문의 설명입니다.

PARA — 주제가 아니라 “실행”으로 나누는 네 칸

정리하기 단계에서 원문이 쓰는 방법이 PARA 입니다. 원문은 삶의 모든 정보가 단 네 칸에 들어간다고 말합니다.

Projects · 프로젝트

어떤 목표를 두고 하는 짧은 기간의 일. 예: 웹페이지 디자인 끝내기, 연구 보고서 쓰기.

Areas · 영역

시간을 두고 계속 챙기는 책임. 예: 마케팅, 인사, 건강, 재정. 끝나는 날이 없습니다.

Resources · 자원

앞으로 쓸모 있을지 모르는 관심 주제. 예: 그래픽 디자인, 사진, 습관 만들기.

Archives · 보관

앞의 세 칸에서 더는 활발하지 않은 것. 끝냈거나 멈춘 프로젝트, 관심이 식은 자원.

핵심 원칙은 “실행 가능성으로 정리하라”입니다. 학교에서 배운 대로 “마케팅”, “심리학” 같은 넓은 주제로 나누면, 바쁜 날 필요한 정보 하나를 찾느라 큰 칸을 뒤져야 합니다. 원문은 대신 지금 맡고 있는 프로젝트와 목표를 기준으로 정리하라고 합니다. 디자인 프로젝트를 시작하면 그에 필요한 메모·문서·자료가 한자리에 모여 있어야 한다는 것입니다.

새 정보 어느 프로젝트에 쓸모 있나? 없으면 어느 영역? 없으면 어느 자원? 보관하거나 저장 안 함 projects/ 에 areas/ 에 resources/ 에 원문: 익숙해지면 몇 초면 정함 · 자리를 고민하지 말 것 — 검색으로 거의 다 다시 찾을 수 있음 폴더 이름(projects/ 등)은 이 가이드의 예시 이름
원문이 권하는 세 가지 질문을 차례로 묻는 흐름입니다.

에이전트에게도 이 정리법이 잘 맞는 이유는 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.md · 목표 문서 · MEMORY.md 필요할 때 읽는 층에 — 세부와 원본 자료 폴더 · 주제별 파일 · 스킬
원문은 이 층들을 “확대·축소할 수 있는 디지털 지도”에 빗댑니다. 왼쪽 층 구조는 원문, 오른쪽 배치는 이 가이드의 제안입니다.

이 생각은 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 를 읽습니다(에이전트 팀 · 서브에이전트 문서).
그래서 목표 문서는 리더·팀원·다음 세션 모두의 시작 컨텍스트에 들어갑니다. 대신 불러온 파일도 컨텍스트 비용은 그대로이므로 짧게 씁니다.
GOAL.md 팀 목표 (예시 이름) @GOAL.md CLAUDE.md 매 세션 시작 때 읽힘 리더 세션 팀원 · 서브에이전트 내일의 새 세션 불러온 파일도 함께 컨텍스트에 들어감 → 목표 문서는 짧게
목표를 한곳에 적고, 항상 읽히는 파일이 그것을 불러오게 하면 “같은 목표”가 자동으로 퍼집니다.

목표 문서에 무엇을 적을지는 원문의 원칙에서 끌어옵니다. 목표(무엇을 이루려 하나), 그 목표에 묶인 끝이 있는 프로젝트들, 끝났다고 말할 기준, 그리고 저장소를 읽어서는 알 수 없는 결정입니다. 아래 양식은 이 가이드가 만든 예시입니다.

GOAL.md — 예시 양식 (이 가이드가 만든 것)
# 팀 목표 (2026 4분기)
분기 보고서를 매주 자동으로 초안까지 만든다.

## 진행 중 프로젝트 — 끝이 있는 일만
- 보고서 양식 확정 → projects/q4-report/
- 데이터 수집 절차 정리 → 스킬로 옮길 예정

## 끝났다고 말할 기준
- 초안이 양식의 모든 칸을 채우고, 숫자마다 출처 링크가 있다

## 하지 않을 것
- 외부 메일 보내기 (사람이 직접)

## 정한 것 (저장소엔 없는 결정)
- 2026-11-03 회의: 보고서는 한국어로만
목표 문서는 “맥락”이지 “강제”가 아닙니다 Claude Code 문서는 CLAUDE.md 와 자동 메모리를 “강제 설정이 아니라 맥락”으로 다룬다고 적습니다. 위 예의 “외부 메일 보내기 금지”처럼 반드시 막아야 할 일은 목표 문서에 적는 것만으로는 보장되지 않습니다. 원문은 그런 규칙에 훅(정해진 순간에 Claude Code 가 반드시 실행하는 명령)이나 권한 규칙을 쓰라고 권합니다(9장).
불러오기(@import) 세부 — 원문 기준
  • 상대 경로와 절대 경로 모두 됩니다. 상대 경로는 작업 폴더가 아니라 불러오는 파일 기준으로 풉니다.
  • 불러온 파일이 다시 다른 파일을 불러올 수 있으며, 최대 네 단계까지입니다.
  • 마크다운 코드 표시(백틱) 안의 @경로 는 불러오지 않습니다. 경로를 글자로만 적고 싶으면 백틱으로 감쌉니다.
  • 작업 폴더 바깥 파일을 불러오면 Claude Code 가 승인을 묻습니다.
  • 불러오기는 긴 파일을 정리하는 데는 도움이 되지만 컨텍스트 비용을 줄이지는 않습니다. 불러온 파일이 함께 읽히기 때문입니다. 일부에만 필요한 지침은 경로별 규칙(.claude/rules/)으로 옮기면 해당 파일을 다룰 때만 읽힙니다(3장).

다음 에이전트를 위한 메모 — “미래의 나”를 “다음 에이전트”로

원문의 추리기 단계에는 힘 있는 마음가짐 하나가 나옵니다. “미래의 나를 생각하며 메모를 설계하라.” 메모는 시간 여행이고, 지금의 지식을 꾸러미로 묶어 미래의 나에게 보내는 일이라는 것입니다. 원문은 메모를 만들거나 고칠 때마다 다음에 찾고 쓰기 쉽게 조금씩 손보라고 하며, 세 가지 예를 듭니다.

지금 세션 일을 마치며 적음 용어 풀이 멈춘 자리 표시 관련 파일 링크 다음 에이전트 빈 컨텍스트로 도착
원문의 “미래의 나”는 에이전트 팀에서 “다음 세션·다른 팀원”이 됩니다. 이들은 지금의 대화를 전혀 모른 채 도착합니다.
원문의 예 (미래의 나에게)다음 에이전트에게 (이 가이드의 제안)
잊을까 봐 핵심 용어를 정의해 둔다팀 안에서만 쓰는 말·약어를 목표 문서나 지침 파일에 한 줄로 풀어 둔다
멈춘 자리에 표시를 남겨 어디서 다시 시작할지 안다진행 기록에 “한 일 / 남은 일 / 다음 첫 단계”를 남긴다 — 원문의 인수인계 노트(claude-progress.txt 등)와 같은 일
시간이 지나면 잊을 관련 웹사이트·파일·메일 링크를 단다결정의 근거가 된 파일 경로·자료 링크를 함께 적어, 다음 에이전트가 필요할 때 찾아 읽게 한다

에이전트에게 이 마음가짐은 비유가 아니라 사실입니다. 사람의 “미래의 나”는 그래도 어렴풋이 기억하지만, 다음 세션의 에이전트는 정말로 아무것도 기억하지 못합니다(소개). 긴 작업에 관한 Anthropic 글이 진행 기록 파일과 git 이력으로 “새 컨텍스트 창에서 시작하는 에이전트가 일의 상태를 빨리 파악하게” 만든 것도 같은 이유입니다. 원문은 이를 “앞으로 갚는(pay it forward)” 전략이라 부릅니다. 지금 조금 더 수고하면 나중에 그 덕을 봅니다.

써 보면 좋은 습관 (예시 지시) 지침 파일에 이런 한 줄을 두는 방법이 있습니다. 이 가이드가 만든 예시 문장입니다. “세션을 마치기 전에, 이 대화를 전혀 모르는 다음 에이전트가 읽는다고 생각하고 NOTES.md 에 한 일·남은 일·다음 첫 단계를 적는다.” 진행 기록의 양식과 시작 순서는 7장에서 원문대로 다룹니다.

개인 지식과 팀 지식 — 두 팀을 나누고 잇는 법

세컨드 브레인의 원뜻은 개인 지식 관리(PKM)입니다. 위키백과는 PKM 을 지식 관리의 “아래에서 위로” 접근이라고 설명하고, 개인과 조직의 지식을 함께 보는 모형도 소개합니다. 장(Zhang)의 모형에서 조직 지식은 개인에게 맞게 개인화되고, 개인 지식은 모여서 조직 지식으로 쓰이며, 둘은 이 순환으로 이어집니다(OAPI — organizationalize·aggregate·personalize·individualize). 위키백과는 반대 견해도 함께 싣습니다. 지식은 개인만의 산물이 아니라 연결·대화·사회적 상호작용에서 생긴다는 비판입니다.

이 가이드의 제안 개인 팀과 회사 팀의 공용 기억은 폴더도 범위도 따로 둡니다. 개인 팀에서 쓸 만한 절차가 생기면 사람이 검토해 회사 팀의 프로젝트 지침이나 스킬로 옮기고, 회사 규칙 가운데 내 일에 필요한 것은 개인 쪽에 내 말로 짧게 옮겨 적습니다. 회사 정보가 개인 범위로 새지 않게 하는 방법과 권한은 9장에서 다룹니다.
개인 팀의 공용 기억 내 선호 · 내 프로젝트 사용자 범위 · 개인 폴더 회사 팀의 공용 기억 팀 결정 · 회사 규칙 프로젝트 범위 · 조직 범위 모으기 (사람이 검토 후) 개인화 (내 일에 맞게) 두 기억은 섞지 않고, 오가는 길만 정해 둠 (이 가이드의 제안)
위키백과가 소개하는 개인·조직 지식의 순환을 개인 팀·회사 팀에 옮긴 그림입니다. 범위 이름은 Claude Code 문서의 것입니다.

카파시의 LLM 위키 — AI 가 쓰고 고치는 지식 창고

지금까지는 사람의 세컨드 브레인 정리법을 에이전트용으로 옮겼습니다. 반대로 정리하는 일 자체를 AI 에게 맡기는 방법도 있습니다. 안드레 카파시(Andrej Karpathy)가 공개한 「LLM Wiki」 글이 말하는 LLM 위키(AI 가 원문을 읽고 마크다운 위키를 직접 쓰고 고쳐 가는 지식 창고 방식)입니다. 원문은 스스로를 “아이디어 파일”이라고 소개합니다. 자기 에이전트(원문 예: OpenAI Codex, Claude Code, OpenCode / Pi)에 그대로 붙여 넣도록 만든 글로, 큰 생각만 전하고 세부는 에이전트가 사용자와 함께 만들어 간다는 것입니다.

RAG 와 무엇이 다른가. 원문은 흔한 방식부터 짚습니다. 파일을 올려 두면 AI 가 질문을 받을 때마다 관련 조각을 찾아 답을 만드는 RAG(질문할 때마다 자료 더미에서 관련 부분을 찾아 답에 붙이는 방식, 8장)입니다. NotebookLM, ChatGPT 파일 올리기, 대부분의 RAG 시스템이 이렇게 동작한다고 원문은 말합니다. 이 방식도 되긴 하지만 AI 가 질문마다 지식을 처음부터 다시 찾아냅니다. 문서 다섯 개를 엮어야 하는 미묘한 질문이면 매번 조각을 찾아 다시 맞춰야 하고, 아무것도 쌓이지 않습니다.

RAG — 매번 찾기 원문 더미 그대로 쌓여 있음 질문마다 조각 찾기 조각을 맞춰 답 다음 질문엔 다시 처음부터 대화 기록에서 사라짐 쌓이는 것이 없음 LLM 위키 — 쌓아 두기 원문 새 자료가 들어올 때 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 입니다.

스키마 — 규칙 문서 CLAUDE.md · AGENTS.md — 사람과 AI 가 함께 고쳐 감 위키 — AI 가 전부 쓰고 고침 요약 · 대상별 쪽 · 개념 쪽 · 비교 · 개요 · 종합 원문 — 고치지 않는 기준 자료 글 · 논문 · 그림 · 데이터 파일 (읽기만) AI (에이전트) 규칙대로 일함 씀 읽기만 따름 사람은 위키를 읽음
원문의 세 층입니다. 원문은 스키마를 “AI 를 그냥 채팅 상대가 아니라 규율 있는 위키 관리자로 만드는 핵심 설정 파일”이라고 부릅니다.

세 작업 — 넣기 · 묻기 · 점검. 위키는 세 가지 일로 굴러갑니다. 아래 단계를 눌러 보세요.

1단계 · 넣기 (Ingest) — 새 원문을 원문 폴더에 넣고 AI 에게 처리하라고 합니다. 원문이 드는 흐름 예: AI 가 원문을 읽고, 핵심을 사람과 이야기하고, 위키에 요약 쪽을 쓰고, 목차를 고치고, 관련된 대상·개념 쪽을 고치고, 일지에 한 줄을 덧붙입니다. 원문 하나가 위키 10~15쪽을 건드릴 수도 있습니다. 원문 저자는 하나씩 넣으며 요약을 읽고 무엇을 강조할지 직접 이끄는 쪽을 좋아하지만, 여러 개를 한꺼번에 넣고 덜 지켜보는 방법도 있다고 합니다. 어떤 방식이든 정해지면 스키마에 적어 다음 세션도 따르게 합니다.
새 원문 1개raw sources 요약 쪽 새로 쓰기 대상·개념 쪽 고치기 index.md · log.md 10~15쪽한 번에 건드릴 수도
2단계 · 묻기 (Query) — 위키에 질문합니다. AI 는 관련 쪽을 찾아 읽고 인용을 붙여 답합니다. 답은 질문에 따라 마크다운 쪽, 비교표, 슬라이드(Marp), 차트(matplotlib) 등 여러 모양일 수 있습니다. 원문이 꼽는 중요한 깨달음은 좋은 답은 위키에 새 쪽으로 되돌려 넣을 수 있다는 것입니다. 부탁해서 얻은 비교, 분석, 새로 찾은 연결은 대화 기록 속에 사라지면 안 되는 값진 것이고, 이렇게 하면 탐구한 내용도 넣은 원문처럼 위키에 쌓입니다.
3단계 · 점검 (Lint) — 때때로 AI 에게 위키 건강 검진을 시킵니다. 원문의 점검 목록: 쪽끼리 어긋나는 내용, 새 원문 때문에 낡은 주장, 들어오는 링크가 없는 외톨이 쪽, 자주 언급되는데 자기 쪽이 없는 개념, 빠진 상호 링크, 웹 검색으로 채울 수 있는 빈 곳. AI 는 새로 물어볼 질문과 찾아볼 원문을 제안하는 데도 능하다고 원문은 말합니다.

두 특별 파일 — 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 저장소(파일의 변경 이력을 모두 기록해 두는 폴더)입니다. 버전 이력·갈래 나누기·협업이 저절로 따라옵니다.
원문은 일부러 추상적입니다 원문 끝의 메모: 이 글은 생각을 설명할 뿐 특정 구현이 아니며, 폴더 구조 · 스키마 약속 · 쪽 양식 · 도구는 모두 분야·취향·쓰는 AI 에 따라 다르고, 앞의 모든 것은 고르고 버릴 수 있는 선택지라고 합니다. 예를 들어 글만 다루면 그림 처리는 필요 없고, 위키가 작으면 목차 파일만으로 충분합니다. 올바른 사용법은 이 글을 자기 에이전트와 나누고 함께 맞는 판을 만드는 것입니다. 그래서 아래 연결 방법도 하나의 예입니다.
이 가이드의 제안 — LLM 위키를 이 가이드의 공용 기억에 끼우기

아래 대응은 원문에 없는 이 가이드의 연결 방법입니다. 원문 층은 받아 둔 자료, 스키마는 지침 파일(3장), 위키는 PARA 와 함께 쓰는 팀 지식 창고, log.md 는 인수인계 노트(7장), 점검은 정기 점검(9장)에 대응합니다. 에이전트 팀이라면 여러 팀원이 같은 위키를 읽고, 쓰기는 한 명(또는 리더)이 맡기를 권합니다. 같은 파일을 여럿이 고치면 덮어쓰기 쉽기 때문입니다(6장).

LLM 위키 (원문) 이 가이드에서 (제안) 원문 층 받아 둔 자료 (예시 이름 raw/) 스키마 지침 파일 CLAUDE.md · AGENTS.md (3장) 위키 팀 지식 창고 (예: PARA 의 Resources) log.md 인수인계 노트 (7장) 점검 (Lint) 공용 기억 정기 점검 (9장)
한눈에 정리
  • 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)

CHAPTER 03

항상 읽히는 층 — CLAUDE.md 와 AGENTS.md

팀 안의 모든 에이전트가 같은 목표와 맥락으로 일하게 만드는 가장 기본 도구는 지침 파일입니다. 사람이 써 두면 에이전트가 세션을 시작할 때마다 읽습니다. 이 장은 지침 파일을 어디에 두고, 어떻게 짧고 분명하게 쓰고, 안 읽힐 때 무엇을 확인하는지 다룹니다.

이 장에서 배우는 것
  • 지침 파일이 "팀 전원이 매번 읽는 공용 기억"이 되는 이유
  • 범위 4종(조직·사용자·프로젝트·로컬)과 개인 팀·회사 팀에 맞춰 나눠 두는 법
  • 여러 지침 파일이 읽히는 순서, 잘 쓰는 법(구체적으로·200줄 아래·충돌 없이)
  • @ 가져오기, .claude/rules/, 여러 도구가 함께 읽는 AGENTS.md
  • 큰 조직에서 관리하는 법, 지침이 안 먹힐 때 확인할 것
처음이라면 이것만

가져오기·규칙 폴더·대규모 관리·🔧 표시가 붙은 접힌 상자는 필요할 때 펼쳐 보면 됩니다.

지침 파일이란 — 팀 전원이 매번 읽는 공용 기억

무엇인가 — Claude Code(Anthropic 이 만든, 글로 지시하면 파일을 읽고 고치고 명령을 실행하는 AI 에이전트 도구)의 세션은 늘 빈 컨텍스트 창에서 시작합니다. 컨텍스트(에이전트가 한 번에 보고 있는 글 전체)가 비어 있으니 어제 대화에서 정한 것을 오늘의 에이전트는 모릅니다. 원문은 세션을 넘어 지식을 이어 주는 장치를 두 가지로 설명합니다.

CLAUDE.md (지침 파일)자동 메모리 (auto memory)
누가 쓰나나(사람)Claude 가 스스로
무엇이 들어가나지시와 규칙배운 점과 패턴
범위프로젝트·사용자·조직저장소마다(워크트리(같은 저장소를 여러 폴더에 펼친 작업용 복사본)끼리 공유)
언제 읽히나모든 세션모든 세션(처음 200줄 또는 25KB 까지)
쓰는 곳작업 규칙, 일하는 순서, 프로젝트 구조내 선호, 내가 바로잡아 준 것, 코드만 봐선 알 수 없는 사정

이 장은 왼쪽, 사람이 쓰는 지침 파일만 다룹니다. 자동 메모리는 5장에서 봅니다. 지침 파일은 마크다운(# 제목, - 목록처럼 간단한 기호로 꾸미는 글 형식)으로 쓴 보통 글 파일이고, Claude 는 매 세션 시작 때 이 파일을 읽습니다.

왜 "팀의 공용 기억"인가 — 에이전트 팀실험 기능에서도 같은 일이 일어납니다. 원문은 이렇게 적습니다.

원문 (agent-teams · Context and communication)"When spawned, a teammate loads the same project context as a regular session: CLAUDE.md, MCP servers, and skills."
뜻: 팀원은 만들어질 때 보통 세션과 같은 프로젝트 맥락 — CLAUDE.md, MCP 서버, 스킬 — 을 불러옵니다. 그리고 리더의 대화 기록은 넘어가지 않고, 리더가 준 생성 지시문(spawn prompt — 리더가 팀원을 만들 때 주는 첫 지시)만 받습니다.
CLAUDE.md 사람이 쓴 지침 파일 목표 · 규칙 · 일하는 순서 리더 (team lead)새 컨텍스트 창 + CLAUDE.md 팀원 A새 컨텍스트 창 + CLAUDE.md + 지시문 팀원 B새 컨텍스트 창 + CLAUDE.md + 지시문 팀원 C새 컨텍스트 창 + CLAUDE.md + 지시문
리더의 대화 기록은 팀원에게 넘어가지 않지만, 지침 파일은 모두가 시작할 때 똑같이 읽습니다. 그래서 "모두가 알아야 할 목표와 규칙"을 두기에 가장 확실한 자리입니다.
쉽게 말하면지침 파일은 회사 휴게실 벽에 붙인 "우리 팀 규칙" 게시판과 같습니다. 새로 들어온 사람도, 오늘 출근한 사람도 문을 열면 먼저 그 게시판을 봅니다. 말로만 전한 내용(대화)은 그 자리에 있던 사람만 알지만, 게시판에 붙인 것은 모두가 압니다.

주의할 점 — 강제 설정이 아니라 맥락 — 원문은 Claude 가 지침 파일을 "강제되는 설정이 아니라 맥락(context, not enforced configuration)"으로 다룬다고 분명히 적습니다. Claude 는 읽고 따르려 하지만 반드시 지킨다는 보장은 없습니다. 지시가 구체적이고 짧을수록 더 꾸준히 따릅니다.

반드시 막아야 하는 것은 지침 파일이 아니라 훅·권한 규칙으로"이 폴더는 절대 고치지 마"처럼 예외 없이 지켜야 하는 것은 훅(hook — 정해진 순간마다 Claude Code 가 자동으로 실행하는 명령)이나 거부 규칙(permissions.deny)으로 겁니다. 이것들은 Claude 가 무엇을 판단하든 Claude Code 가 매번 적용합니다. 자세한 구분은 9장에서 다룹니다.

범위 4종 — 누구와 나눌지에 따라 둘 곳이 다르다

무엇인가 — CLAUDE.md 는 한 곳에만 두는 파일이 아닙니다. 놓는 위치에 따라 범위(scope — 그 지침이 누구에게, 어느 프로젝트에 적용되는가)가 달라집니다. 원문의 표를 넓은 범위부터 좁은 범위 순으로 옮깁니다. 이 순서가 곧 읽히는 순서입니다.

범위위치무엇을 적나 (원문 예)누구와 공유
조직
Managed policy
macOS /Library/Application Support/ClaudeCode/CLAUDE.md
Linux·WSL /etc/claude-code/CLAUDE.md
Windows 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 는 "이 파일은 올리지 마"라고 적는 목록입니다.

① 조직 — Managed policy 회사 전체 · 관리자가 배포 · 개인이 뺄 수 없음 ② 사용자 — ~/.claude/CLAUDE.md 나만 · 내 모든 프로젝트에 적용 ③ 프로젝트 — ./CLAUDE.md 이 저장소의 모든 팀원 · git 으로 공유 ④ 로컬 — ./CLAUDE.local.md 나만 · 이 프로젝트에서만 · git 에 올리지 않음 읽는 순서 넓은 범위 → 좁은 범위 여럿이 함께 읽는 층 나 혼자 읽는 층
넓은 범위의 지침이 먼저, 좁은 범위가 나중에 읽힙니다. 노란 층은 여러 사람(과 그들의 에이전트)이 함께 읽고, 초록 층은 나만 읽습니다.

개인 팀·회사 팀과 어떻게 이어지나 — 원문의 범위를 요청하신 두 팀에 맞춰 보면 아래처럼 나눌 수 있습니다. 어느 팀이든 팀 전원이 같은 목표를 갖게 하는 자리는 프로젝트 범위입니다. 팀원 에이전트가 시작할 때 불러오는 것이 바로 그 프로젝트의 맥락이기 때문입니다.

이 가이드의 제안 — 개인 팀
  • 사용자 범위(~/.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 가 붙어, 내 개인 메모가 그 층의 마지막 글이 됩니다.

1 조직 CLAUDE.md 2 ~/.claude/CLAUDE.md (사용자) 3 foo/CLAUDE.md 4 foo/CLAUDE.local.md 5 foo/bar/CLAUDE.md (작업 폴더) 6 foo/bar/CLAUDE.local.md foo/bar/sub/CLAUDE.md (하위 폴더) 시작 때는 안 읽음 · 그 폴더 파일을 만질 때 세션의 컨텍스트 위 1~6 이 차례로 이어 붙음 (서로 덮어쓰지 않음) 맨 아래 = 마지막에 읽힘 = 시작한 곳에 가장 가까운 지침 그 뒤에 대화가 이어짐
foo/bar/ 에서 Claude Code 를 시작했을 때. 점선 상자(하위 폴더 지침)는 시작 때가 아니라, Claude 가 그 폴더 안의 파일을 읽거나 고칠 때 한 번 불러옵니다.
1단계 · 시작할 때 — 작업 폴더와 그 위 폴더의 지침, 그리고 조직·사용자 범위 지침이 한꺼번에 읽힙니다. 확인은 세션에서 /context all 을 실행해 Memory files(메모리 파일) 목록을 보면 됩니다.
2단계 · 일하는 도중 — 작업 폴더 아래 하위 폴더의 CLAUDE.md 는 Claude 가 그 하위 폴더의 다른 파일을 읽거나·쓰거나·고칠 때 불러옵니다. cat·head 로 파일 하나를 보는 것도 "읽기"로 칩니다.
3단계 · 대화를 압축한 뒤 — 대화가 길어져 /compact(압축 — 대화를 요약해 새로 시작)를 하면, 프로젝트 맨 위의 CLAUDE.md 는 디스크에서 다시 읽어 넣습니다. 하위 폴더 지침은 다시 그 폴더를 만질 때 불러옵니다. 대화로만 한 지시는 이때 사라질 수 있으니, 계속 지켜야 할 것은 지침 파일에 적습니다.
사람만 보는 메모 남기기지침 파일 안의 블록 단위 HTML 주석 <!-- 관리자 메모 --> 는 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 의 주의를 조금씩 가져갑니다. 그래서 "매 세션 필요한 사실"만 남기고 나머지는 알맞은 곳으로 보냅니다.

적어 두고 싶은 것 규칙 · 절차 · 사실 매 세션·모든 일에 필요한 사실 → CLAUDE.md 확인 명령, 작업 기준, 폴더 구조, "항상 X 한다" 일부 폴더·파일에만 해당 → .claude/rules/ paths 로 그 파일을 만질 때만 읽힘 여러 단계로 된 절차 → 스킬 필요할 때만 본문이 읽힘 (4장) 예외 없이 지켜야 함 → 훅 · 권한 규칙 Claude 의 판단과 상관없이 매번 적용 (9장)
원문(memory 「When to add」, best-practices 「Keep CLAUDE.md short」·「Deterministic」)을 한 그림으로 모은 것입니다.

구체적으로 쓰기 — 지침은 맥락일 뿐 강제가 아니므로, 확인할 수 있을 만큼 구체적으로 써야 잘 따릅니다. 원문 예를 옮깁니다.

흐릿한 지시구체적인 지시
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/ 까지 가끔 훑어 낡은 것·충돌하는 것을 지웁니다.
CLAUDE.md — 원문(best-practices)의 짧은 예
# 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 에 코드만 봐서는 알 수 없는 것 — 확인 명령, 헷갈리게 생긴 곳, 저장소에 안 적힌 결정, 두 번 이상 바로잡은 것 — 만 두라고 합니다.

IMPORTANT 를 붙여도 해결되지 않습니다원문: CLAUDE.md 에 있는 줄을 Claude 가 계속 무시한다면 "IMPORTANT" 같은 강조를 더해도 잘 안 고쳐집니다. 파일이 너무 길어져 그 줄이 묻혔거나, 예외가 없어야 하는 규칙이라 훅으로 옮겨야 하는 경우입니다.
처음부터 다 쓰지 않아도 됩니다/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단계까지입니다.

CLAUDE.md — 가져오기 예 (원문)
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 와 같은 우선순위로 읽힙니다.

.claude/rules/api.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 가 관련 있다고 판단할 때만 읽힙니다(4장).
규칙 파일 세부 — 기준 폴더·중괄호·심볼릭 링크
  • 기준 폴더: 프로젝트 규칙은 그 .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 이 관리합니다.

AGENTS.md 저장소 맨 위 · 마크다운 Codex (OpenAI) Cursor Gemini CLI Claude Code CLAUDE.md 없을 때
원문(agents.md)이 함께 쓴다고 밝힌 도구 가운데 일부입니다. 서로 다른 도구로 만든 에이전트를 한 팀에 섞어도, 이 파일 하나로 같은 지침을 읽힐 수 있습니다.

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.mdCLAUDE.md 와, 가져오기로 들어온 AGENTS.md

어떻게 쓰나 — 여러 도구가 한 파일을 나눠 쓰기 — 프로젝트에 CLAUDE.md 도 있어야 한다면, AGENTS.md 옆 CLAUDE.md 맨 위에 @AGENTS.md 를 두고 그 아래에 Claude 전용 지시만 더합니다. Claude 는 가져온 파일을 먼저, 나머지를 그다음에 읽습니다.

CLAUDE.md — AGENTS.md 를 공용으로 (원문 예)
@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 사용자가 있으면 가져오기 쪽을 쓰라고 원문은 권합니다.

CLAUDE.local.md 를 만들면 AGENTS.md 가 안 읽힐 수 있습니다CLAUDE.local.md 도 "CLAUDE.md 가 있다"로 치기 때문에, AGENTS.md 에 기대는 프로젝트에 내 개인 메모용 CLAUDE.local.md 를 더하면 그때부터 Claude 는 AGENTS.md 를 읽지 않습니다. 둘 다 읽게 하려면 아래 접힌 상자의 Project instructions 설정을 바꿉니다.
원문(agents.md)이 말하는 다른 도구에서의 동작큰 모노레포라면 하위 프로젝트마다 AGENTS.md 를 둘 수 있고, 에이전트는 가장 가까운 파일을 읽어 그것이 앞섭니다. 지시가 어긋나면 고치는 파일에 가장 가까운 AGENTS.md 가 이기고, 사용자가 채팅으로 직접 한 지시가 모든 것보다 앞섭니다. 이 FAQ 는 agents.md 사이트의 설명이며, Claude Code 가 하위 폴더 AGENTS.md 를 읽는 조건은 접힌 상자를 보세요.
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-mdCLAUDE.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 로 뺄 수 없습니다. 만드는 순서는 두 단계입니다.

  1. 조직 위치에 파일 만들기macOS /Library/Application Support/ClaudeCode/CLAUDE.md · Linux·WSL /etc/claude-code/CLAUDE.md · Windows C:\Program Files\ClaudeCode\CLAUDE.md
  2. 설정 관리 도구로 배포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 에 둡니다.

.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 는 읽고 따르려 하지만, 특히 흐릿하거나 서로 어긋나는 지시는 꼭 지킨다는 보장이 없습니다. 아래 순서로 원인을 좁힙니다.

1 · 읽히긴 했나 — 세션에서 /context all 을 실행해 Memory files 목록에 그 CLAUDE.md·CLAUDE.local.md 가 있는지 봅니다. 없으면 Claude 는 그 파일을 볼 수 없습니다. Instruction file not loaded(지침 파일을 못 읽음) 알림이 떴다면 그 안내를 따릅니다. 하위 폴더 CLAUDE.md 는 시작 때가 아니라 필요할 때 읽혀서 이 목록에 없고, 읽힐 때 터미널에 Loaded 줄이 뜹니다.
2 · 읽히는 자리에 있나 — 그 파일이 이 세션에서 읽히는 위치인지 범위 표로 확인합니다. 파일 열기·고치기는 /memory 로 합니다.
3 · 구체적인가, 부딪치지 않나 — "코드를 예쁘게"보다 "들여쓰기 2칸"처럼 고칩니다. 여러 지침 파일이 같은 행동에 다른 말을 하면 Claude 는 아무거나 고를 수 있으니 하나로 정리합니다. Claude Code 가 스스로 넣는 기본 안내(커밋·PR 규칙 등)와 부딪치는지도 봅니다.
4 · 지침이 맞는 도구인가 — 커밋 전마다, 파일 수정 후마다처럼 정해진 순간에 반드시 해야 하는 일이면 훅으로 옮깁니다. 훅은 Claude 의 판단과 상관없이 실행됩니다.

증상: 지침이 많아졌고, 일부가 안 지켜집니다.

  • 200줄이 넘는 파일은 컨텍스트를 더 쓰고 지키는 정도가 떨어질 수 있습니다. 권장 길이를 넘으면 시작할 때와 /status 에서 경고가 뜹니다. 파일 각각은 괜찮아도 합계가 한도를 넘으면 경고가 뜹니다(CLAUDE.md·규칙 파일·@ 가져오기가 각각 한 파일).
  • 해결: 일부 파일에만 필요한 지시는 paths 규칙으로, 매 세션 필요 없는 것은 덜어 냅니다. @ 로 쪼개는 것은 정리에는 좋지만 컨텍스트는 줄이지 않습니다.
  • /doctor 점검은 저장소에 올린 CLAUDE.md 에서 코드만 봐도 알 수 있는 내용(폴더 구조, 의존성 목록, 구조 개요)을 덜어 내자고 제안하고, 함정·이유·기본값과 다른 약속은 남깁니다.

증상: AGENTS.md 가 있는데 Claude 가 그 내용을 모릅니다.

  1. 작업 폴더나 그 위에 CLAUDE.md·.claude/CLAUDE.md·CLAUDE.local.md 가 있는지(~/.claude/CLAUDE.md 제외) — 있으면 그쪽을 대신 읽습니다.
  2. claude --version 으로 버전 확인(조건은 위 접힌 상자).
  3. /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지침 파일의 낡은 지시·없는 파일 참조·서로 어긋나는 내용 찾기. 보고서와 수정안만 내고, 내가 적용하라고 하기 전에는 파일을 바꾸지 않음
"기억해"와 "CLAUDE.md 에 적어"는 다릅니다대화에서 "항상 pnpm 을 써, 기억해"라고 하면 Claude 는 그것을 자동 메모리에 적습니다. 지침 파일에 넣고 싶으면 "이걸 CLAUDE.md 에 추가해"라고 직접 말하거나 /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)

CHAPTER 04

필요할 때 읽히는 층 — 스킬

3장의 지침 파일은 매 세션 처음부터 읽힙니다. 그런데 팀의 배포 순서, 장애 대응 절차, 보고서 쓰는 법처럼 길지만 가끔 필요한 지식까지 거기에 넣으면 모든 일이 무거워집니다. 이런 것을 폴더로 묶어 필요할 때만 꺼내 읽히는 장치가 스킬입니다.

이 장에서 배우는 것
  • 스킬이 무엇이고, 항상 읽히는 CLAUDE.md 와 무엇이 다른지
  • 무엇을 CLAUDE.md 에, 무엇을 스킬에 둘지 고르는 기준
  • SKILL.md 만들기, 둘 곳(범위), 부르는 법(직접·자동)
  • 팀 전원이 같은 스킬을 쓰게 공유하는 법, 안 불릴 때 확인할 것
처음이라면 이것만

만들기·둘 곳·부르는 법은 첫 스킬을 만들 때 차례로 읽으면 됩니다. 🔧 표시가 붙은 접힌 상자는 필요할 때만 펼치세요.

스킬이란 — 필요할 때만 펼치는 절차서

무엇인가 — 스킬(Skill — 절차나 지식을 SKILL.md 파일이 든 폴더로 묶어, 필요할 때만 불러오는 것)은 Claude 가 할 수 있는 일을 넓혀 줍니다. SKILL.md 에 지시를 적어 두면 Claude 가 그것을 자기 도구함에 넣고, 관련 있는 일이 오면 스스로 꺼내 쓰거나 내가 /스킬-이름 으로 바로 부릅니다.

왜 필요한가 — 원문은 이렇게 설명합니다. 더 뛰어난 모델은 공학 지식은 더 많이 알지만, 우리 팀이 출시를 어떻게 하는지, 장애 대응 문서에 무엇이 적혀 있는지, API 문서를 어떤 모양으로 쓰길 원하는지는 모릅니다. 그런 지식을 스킬에 담습니다. 그리고 CLAUDE.md 와 달리 스킬의 본문은 쓸 때만 읽히므로, 긴 참고 자료도 필요해지기 전까지는 컨텍스트(에이전트가 한 번에 보고 있는 글 전체)를 거의 쓰지 않습니다.

세션의 컨텍스트 CLAUDE.md 전체 항상 · 처음부터 끝까지 스킬 목록 (이름 + 설명) 항상 · 짧은 한두 줄씩 release 스킬 본문 출시 일을 할 때만 들어옴 그 뒤로는 대화 안에 계속 남음 .claude/skills/ release/SKILL.md 출시 순서 4단계 incident/SKILL.md 장애 대응 절차 — 지금은 안 읽힘 api-docs/SKILL.md API 문서 양식 — 지금은 안 읽힘
폴더 안에 스킬이 여러 개 있어도 평소 컨텍스트에는 이름과 설명만 실립니다. 출시 일을 하게 되면 그때 release 스킬의 본문 전체가 들어옵니다. 스킬 이름은 원문 예와 이 가이드의 예시를 섞은 것입니다.
쉽게 말하면CLAUDE.md 가 휴게실 벽의 "팀 규칙" 게시판이라면, 스킬은 책장에 꽂힌 업무 매뉴얼 바인더입니다. 평소에는 책등의 제목만 보이고, 그 일을 할 때 해당 바인더를 꺼내 펼칩니다. 바인더가 많아도 벽 게시판처럼 늘 눈앞을 가리지 않습니다.

알아 둘 것

  • 예전 "사용자 정의 명령"은 스킬로 합쳐졌습니다. .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 의 한 부분이 "사실"이 아니라 "절차"로 커졌을 때입니다.

세션 시작 세션 끝 CLAUDE.md 항상 rules (paths) 맞는 파일을 만질 때 스킬 설명은 항상, 본문은 필요할 때 훅 · 권한 규칙 정해진 순간마다 강제
가로축은 한 세션의 시간입니다. CLAUDE.md 는 처음부터 끝까지, paths 규칙은 맞는 파일을 만진 뒤부터, 스킬은 평소엔 얇은 설명만 있다가 필요해진 순간 본문이 들어옵니다. 훅은 컨텍스트가 아니라 Claude Code 가 정해진 순간마다 직접 실행합니다.
적고 싶은 것둘 곳이유 (원문)
모든 세션에 필요한 사실 — 확인 명령, 약속, 폴더 구조, "항상 X"CLAUDE.md매 세션 읽혀야 하는 것만 둔다
일부 폴더·파일에만 해당하는 규칙.claude/rules/ (paths)맞는 파일을 다룰 때만 읽힌다
여러 단계 절차, 팀 고유의 방법, 긴 참고 자료스킬본문은 쓸 때만 읽혀 관련 없는 일을 무겁게 하지 않는다
예외 없이 지켜야 하는 것훅 · 권한 규칙Claude 의 판단과 상관없이 매번 적용된다
스킬도 "Claude 가 판단하는" 쪽입니다원문(best-practices)은 프롬프트·CLAUDE.md·Claude 가 스스로 꺼내는 스킬을 "Claude 가 정하는(non-deterministic)" 지시로, 훅과 나만 시작할 수 있게 한 스킬을 "Claude Code 가 강제하는(deterministic)" 쪽으로 나눕니다. 꼭 정해진 때에만 돌아야 하는 스킬은 아래처럼 내가 직접 부를 때만 돌게 합니다.

팀에게 왜 중요한가 — 에이전트 팀실험 기능의 팀원은 만들어질 때 CLAUDE.md·MCP 서버와 함께 스킬도 불러옵니다(원문 agent-teams). 그래서 프로젝트에 스킬을 두면 리더와 팀원이 같은 절차서를 펼쳐 일하게 됩니다.

이 가이드의 제안 — 세컨드 브레인을 두 층으로팀의 목표·원칙·"항상 이렇게" 규칙처럼 짧고 매번 필요한 것은 CLAUDE.md(3장)에, 주간 보고서 쓰는 법·자료 조사 순서·검토 체크리스트처럼 길고 가끔 필요한 것은 스킬에 둡니다. 원문의 말처럼 두 곳 모두 Claude 가 스스로 알아낼 수 없는 것만 적습니다. 따라 하기는 활용편 7.

만들기 — 폴더 하나, SKILL.md 하나

무엇이 필요한가 — 스킬 하나는 폴더 하나이고, 그 안에 SKILL.md 가 꼭 있어야 합니다. SKILL.md 는 두 부분으로 됩니다.

SKILL.md --- 앞머리 (frontmatter) --- name · description … "언제 쓰나"를 알려 줌 본문 (마크다운) 스킬이 실행될 때 따를 지시 "무엇을 어떻게 하나" Claude 가 평소에 봄 설명으로 부를지 판단 불렸을 때만 읽힘 대화에 한 번 들어와 남음
폴더 이름(또는 앞머리의 name)이 내가 치는 명령이 되고, description(설명)은 Claude 가 언제 이 스킬을 자동으로 불러올지 판단하는 근거가 됩니다.
1 · 폴더 만들기 — 원문 예는 개인 스킬 폴더에 만듭니다. 개인 스킬은 내 모든 프로젝트에서 쓸 수 있습니다.
mkdir -p ~/.claude/skills/summarize-changes
2 · SKILL.md 쓰기 — 앞머리에 설명, 본문에 지시를 적습니다.
---
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 가 그 명령을 먼저 실행해 결과로 바꿔 넣는 자리입니다(동적 맥락 주입).

3 · 시험하기 — git 프로젝트에서 파일 하나를 조금 고친 뒤 claude 로 시작합니다. 설명에 맞는 질문 What did I change?(뭘 바꿨지?)로 자동 호출을 보거나, /summarize-changes 로 직접 부릅니다. 어느 쪽이든 짧은 요약과 위험 목록이 나오면 성공입니다.

앞머리에서 자주 쓰는 필드 — 모든 필드는 선택이고, description 만 권장입니다. 필드 이름이 표와 조금이라도 다르면 Claude Code 는 오류 없이 무시합니다.

필드하는 일
name/ 메뉴에 보이는 명령 이름. 없으면 폴더 이름
description무엇을 하고 언제 쓰는지. Claude 가 부를지 판단하는 근거. 핵심 쓰임을 앞에 둠
when_to_use부를 때를 더 알려 주는 말(예: 이런 요청이 오면). 설명 뒤에 붙음
disable-model-invocationtrue 면 Claude 가 스스로 못 부름 — 내가 /이름 으로만
user-invocablefalse 면 Claude 만 부름 — / 메뉴에서 숨김
allowed-tools이 스킬을 부른 차례 동안 허락 없이 쓸 도구. 다음 메시지를 보내면 풀림
context: fork서브에이전트(맡긴 일을 자기 컨텍스트에서 하고 결과만 돌려주는 도우미)에서 따로 실행
paths이 패턴의 파일을 다룰 때만 자동으로 불러옴(규칙 폴더와 같은 형식)

두 종류의 내용 — 원문은 부르는 방식에 따라 스킬 내용을 나눠 생각하라고 합니다.

참고형 (Reference)
약속·패턴·스타일 안내·업무 지식처럼, 지금 하는 일에 함께 적용할 지식. 대화 안에서 바로 쓰입니다.
예: api-conventions — API 이름 짓기, 오류 형식, 요청 검사
작업형 (Task)
배포·커밋·코드 생성처럼 특정 행동의 단계별 지시. Claude 가 알아서 하기보다 내가 /이름 으로 부르는 경우가 많아 disable-model-invocation: true 를 붙입니다.
예: deploy — 테스트 → 빌드 → 배포
.claude/skills/release/SKILL.md (원문 best-practices 예)
---
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/ 프로젝트 스킬 .claude/skills/ > > 이름이 같으면 왼쪽이 이깁니다 — /deploy 가 둘에 있으면 개인 쪽이 실행 플러그인 스킬은 /플러그인:이름 으로 따로 있어 겹치지 않음 프로젝트 맨 위 스킬과 하위 폴더 스킬은 둘 다 남음
원문 「Resolve skills that share a name」의 핵심만 그린 것입니다. 팀 공용 절차를 프로젝트 스킬로 두었는데 누군가 같은 이름의 개인 스킬을 갖고 있으면, 그 사람 세션에서는 개인 스킬이 실행됩니다.
이 가이드의 제안 — 개인 팀과 회사 팀개인 팀은 어떤 일에도 쓰는 내 습관(예: 하루 정리 방식)을 개인 스킬로, 그 일에만 쓰는 절차는 그 일 폴더의 프로젝트 스킬로 둡니다. 회사 팀은 팀 절차를 업무 저장소의 프로젝트 스킬로 커밋하고, 회사 전체 공통 절차는 관리자가 기업 스킬이나 플러그인으로 배포합니다. 팀 공용 스킬과 같은 이름의 개인 스킬은 만들지 않는 것이 좋습니다(위 그림). 범위 정리는 9장.
모노레포·워크트리·클라우드 세션에서 읽히는 스킬
  • 위 폴더: 시작한 폴더와 그 위 폴더(저장소 맨 위까지)의 .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 는 대화가 스킬의 설명과 맞으면 스스로 불러옵니다.

/deploy staging 메시지 맨 앞에 이름 "뭘 바꿨지?" 평범한 요청 바로 실행 설명과 맞나? Claude 가 스킬 목록을 봄 맞으면 불러옴 SKILL.md 본문이 대화에 들어옴 이후 차례에도 남음
위쪽은 내가 부르는 길, 아래쪽은 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 처럼 나눠 받을 수도 있습니다.

불린 뒤 1 · 대화에 남는다 — 스킬이 불리면 그 내용이 메시지 하나로 대화에 들어와 이후 차례에도 남습니다. Claude Code 는 다음 차례에 스킬 파일을 다시 읽지 않으므로, 작업 내내 지킬 것은 "한 번 할 일"이 아니라 "계속 지킬 지시"로 씁니다(예: "테스트를 돌려" 대신 "고칠 때마다 테스트를 돌려").
불린 뒤 2 · 허락은 한 차례만 — allowed-tools 로 준 도구 허락은 다음 메시지를 보내면 풀립니다. 남는 것은 지시이지 권한이 아닙니다.
불린 뒤 3 · 압축되면 앞부분만 — 대화가 자동 압축되면 Claude Code 는 각 스킬의 가장 최근 호출을 요약 뒤에 다시 붙이되, 스킬마다 앞의 5,000 토큰까지, 모두 합쳐 25,000 토큰 안에서 붙입니다. 최근에 부른 스킬부터 채우므로 많이 부른 세션에서는 오래된 스킬이 빠질 수 있습니다. 중요한 지시는 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/skills/weekly-report/ (예시 이름) 동료 사람 · 동료의 세션 에이전트 팀의 리더 팀원들 (만들어질 때 불러옴)
프로젝트 스킬은 그 저장소에서 시작한 모든 세션이 읽습니다. 에이전트 팀의 팀원도 만들어질 때 프로젝트와 사용자 설정의 스킬을 불러옵니다(원문 agent-teams).
팀원에게는 역할 정의의 skills 가 적용되지 않습니다원문(agent-teams): 역할 정의 파일(.claude/agents/<이름>.md)을 팀원으로 쓸 때, 그 정의의 skills 필드는 팀원에게 적용되지 않고 팀원은 프로젝트와 사용자 설정에서 스킬을 불러옵니다. 팀원 전원이 써야 할 스킬은 프로젝트 .claude/skills/ 에 둡니다.

공유하기 전에 — 정말 효과가 있나 재 보기 — 원문은 스킬이 불렸다는 것은 Claude 가 찾았다는 뜻일 뿐, 의도대로 했다는 뜻은 아니라고 말합니다. 그래서 두 가지를 따로 잽니다 — 불려야 할 요청에서 불리는지, 불렸을 때 결과가 기대와 맞는지. 방법은 기준선 비교입니다.

  1. 실제 같은 요청 몇 개 모으기팀이 실제로 할 법한 부탁으로
  2. 스킬을 켜고, 끄고 각각 새 세션에서 돌리기새 세션이어야 스킬을 만들며 쌓인 대화가 빈틈을 가리지 않습니다. 끄는 방법은 skillOverrides 에서 "off"
  3. 결과 비교스킬 덕분에 나아졌는지, 드는 토큰·시간만큼 값어치가 있는지
평가 도구 · 안 쓰는 스킬 찾기 · 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 가 안 씁니다.

  1. 설명(description)에 사람들이 실제로 쓰는 말이 들어 있는지 봅니다.
  2. What skills are available?(쓸 수 있는 스킬이 뭐야?)라고 물어 목록에 있는지 봅니다.
  3. 요청을 설명과 더 비슷하게 바꿔 말해 봅니다.
  4. 직접 /스킬-이름 으로 불러 봅니다.
  5. /스킬-이름 도 안 되면 폴더 이름에 쓸 수 없는 글자(예: 폭 없는 공백, <)가 있는지 봅니다.
  6. paths 를 설정했다면, 다루는 파일이 Claude 의 현재 작업 폴더 안에 있는지 봅니다(옆 워크트리 파일은 맞지 않음).

앞머리 YAML 이 깨지면 /이름 은 되지만 Claude 가 설명으로 맞춰 보지 못합니다. --debug 로 오류를 봅니다.

증상: 원하지 않는 때에도 스킬이 불립니다.

  1. 설명을 더 구체적으로 좁힙니다.
  2. 직접 부를 때만 쓰려면 disable-model-invocation: true 를 넣습니다.

증상: 첫 답에서는 따랐는데 나중에 안 따릅니다.

경우해결
매번 지켜야 할 규칙을 건너뜀훅으로 옮깁니다. 스킬과 함께 두려면 스킬의 hooks 앞머리에 정의 — 스킬을 부른 때부터 세션 끝까지 적용
판단해서 적용할 안내를 건너뜀작업 전체에 걸리게 씁니다("고칠 때마다 테스트를 돌려"). 스킬 파일은 다음 차례에 다시 읽히지 않습니다
대화가 압축됨스킬을 다시 부릅니다. 압축 뒤엔 앞부분만 남을 수 있으니 중요한 지시를 위쪽에

증상: 스킬이 많아진 뒤 몇몇이 잘 안 불립니다.

  • 스킬 목록(이름+설명)에는 글자 예산이 있어, 넘치면 덜 쓰는 스킬부터 설명이 빠지고 이름만 남습니다. 예산은 모델 컨텍스트 창의 1% 입니다.
  • /doctor 로 목록의 컨텍스트 비용을, /skill-doctor 로 끌 만한 스킬을 찾습니다. /context 의 Skills 줄은 예산을 적용한 뒤의 크기입니다.
  • 설명은 핵심 쓰임을 앞에 두고 줄입니다(설명+when_to_use 는 1,536자 상한).
쉽게 말하면스킬이 안 불리는 것은 대부분 바인더 책등의 제목이 애매해서입니다. 사람들이 "주간 보고 써 줘"라고 말하는데 책등에 "문서 작성 절차 v2"라고 적혀 있으면 찾기 어렵습니다. 책등(설명)에 사람들이 실제로 쓰는 말을 적으세요.
그 밖의 증상 — 설명 속 꺾쇠 · 개인 스킬이 사라짐 · 예산 늘리기
  • 설명에 < > 가 &lt; &gt; 로 보임: <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)

CHAPTER 05

스스로 쌓는 기억 — 자동 메모리 · 메모리 도구

3장의 지침 파일은 사람이 쓰는 기억입니다. 이 장은 반대로 에이전트가 스스로 적는 기억을 다룹니다. Claude Code 의 자동 메모리, 역할마다 따로 두는 서브에이전트 기억, 그리고 개발자가 자기 에이전트를 만들 때 쓰는 Claude API 메모리 도구까지 — 팀의 세컨드 브레인에 "일하면서 배운 것"이 쌓이는 길을 살펴봅니다.

이 장에서 배우는 것
  • 자동 메모리(auto memory — Claude 가 내 교정·선호를 보고 스스로 적어 두는 메모)가 무엇을 적고, 어디에 두고, 시작 때 얼마만큼 읽는지
  • /memory 로 무엇이 저장됐는지 보고 고치는 법
  • 서브에이전트에 자기만의 지속 기억을 주는 memory 설정
  • Claude API 메모리 도구 — 파일 기반 /memories 폴더로 대화를 넘어 기억하는 방식
  • 기억을 쌓을 때 지켜야 할 보안 — 비밀 정보·크기·만료·경로
처음이라면 이것만

저장 위치를 바꾸는 설정, 환경 변수, 메모리 도구의 명령 목록은 🔧 접힌 상자에 있습니다. 처음엔 건너뛰어도 됩니다.

자동 메모리 — Claude 가 스스로 적는 메모

한 줄 비유 지침 파일(CLAUDE.md)이 내가 써서 책상에 붙여 둔 업무 지침서라면, 자동 메모리는 에이전트가 일하다가 "아, 이분은 이렇게 하길 원하시는구나" 하고 스스로 적는 수첩입니다. 다음 날 출근하면 지침서와 수첩을 둘 다 먼저 펼쳐 봅니다.

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 저장소가 아니면 프로젝트 맨 위 폴더가 기준입니다.

워크트리 A 기능 작업용 폴더 워크트리 B 버그 수정용 폴더 하위 폴더 docs/ 같은 저장소 안 ~/.claude/projects/<project>/memory/ 저장소 하나에 기억 폴더 하나 · 이 컴퓨터에만 있음 MEMORY.md 색인 · 메모 하나에 한 줄 user_role.md feedback_testing.md … 주제 파일 색인이 "어디에 무엇이"를 가리키고, 자세한 내용은 주제 파일에 나눠 둡니다
같은 저장소라면 어느 워크트리에서 일하든 같은 기억을 봅니다. 다른 컴퓨터나 클라우드 환경과는 공유되지 않습니다.

폴더 안에는 색인 역할의 MEMORY.md 와 메모 하나당 주제 파일 하나가 있습니다. Claude 는 세션 내내 이 폴더를 읽고 쓰며, MEMORY.md 로 무엇이 어디 있는지 관리합니다. 기억 파일에는 두 가지 성질이 더 있습니다.

  • 이 컴퓨터에만 있습니다(machine-local). 다른 컴퓨터나 클라우드 환경과 공유되지 않습니다.
  • 저절로 지워지지 않습니다. Claude Code 는 오래된 대화 기록을 보존 기간이 지나면 지우지만, 기억 폴더의 파일은 그 정리에서 빠집니다. 나나 Claude 가 고치거나 지울 때까지 남습니다.
이 가이드의 제안 자동 메모리는 한 사람·한 컴퓨터의 기억입니다. 팀원 모두가 같은 목표를 봐야 하는 내용(팀 목표, 합의된 규칙)은 자동 메모리에 맡기지 말고 저장소 안의 지침 파일(3장 범위)에 사람이 직접 적어 두는 편이 안전합니다. 자동 메모리는 "나에 대해 에이전트가 배운 것"을 담는 개인 수첩으로 생각하세요.

시작 때 얼마나 읽히나 — 200줄 또는 25KB

대화가 시작될 때 읽히는 것은 MEMORY.md 의 처음 200줄 또는 처음 25KB 중 먼저 닿는 쪽까지입니다. 그 뒤는 시작 때 읽히지 않습니다. 주제 파일(user_role.md 등)은 시작 때 읽지 않고, Claude 가 필요할 때 평소 파일 도구로 꺼내 읽습니다.

MEMORY.md 처음 200줄 / 25KB 그 뒤는 시작 때 안 읽힘 세션 시작 컨텍스트 창 지침 파일 + 색인 앞부분 주제 파일은 아직 없음

1. 시작 — 색인 앞부분만 들어옵니다. 색인이 짧을수록 다른 일에 쓸 자리가 남습니다.

Claude "테스트 방식에 대한 교정이 있었지?" 필요할 때 읽기 feedback_testing.md 평소 파일 도구로 꺼냄

2. 필요할 때 — 자세한 내용은 그때그때 꺼내 읽습니다(1장의 "필요할 때 꺼내 읽기"와 같은 생각).

MEMORY.md 에 쓰기 한도에 가까움 Claude Code 의 알림 한 항목에 한 줄로 자세한 건 주제 파일로 낡은 항목은 합치거나 빼기

3. 한도 관리 — Claude 가 MEMORY.md 에 쓴 뒤, Claude Code 가 200줄·25KB 기준으로 크기를 잽니다. 가까우면 줄이라고 알리고, 넘으면 쓰기는 되지만 "색인을 다시 쓰라"는 오류를 돌려줍니다 — 한도 밖은 다음 시작 때 버려지기 때문입니다.

CLAUDE.md 와 한도가 다릅니다 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 로 저장됩니다.

/memory 스위치 내 모든 프로젝트 ~/.claude/settings.json 프로젝트 설정 이 프로젝트만 끄기 "autoMemoryEnabled": false 환경 변수 실행할 때 끄기 CLAUDE_CODE_DISABLE_ AUTO_MEMORY=1
끄는 방법은 범위에 따라 셋입니다. 서브에이전트 기억(아래)도 자동 메모리의 일부라 함께 꺼집니다.
🔧 켜고 끄기·저장 위치의 세부 규칙
  • 스스로 다시 켤 수 없는 세션: 백그라운드 세션, 그리고 다른 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/CLAUDE.md사용자 범위
./CLAUDE.md프로젝트 범위
./CLAUDE.local.md나만 보는 프로젝트 메모
자동 메모리 폴더 열기Claude 가 적은 것
auto memory: on켜고 끄는 스위치

원문이 설명하는 /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 (지침 파일)
이 가이드의 제안 — 정기 점검 순서
  1. /memory → 자동 메모리 폴더를 열어 MEMORY.md 색인을 읽습니다.
  2. 팀 전체가 알아야 할 내용이 개인 기억에 숨어 있으면 지침 파일로 옮깁니다("add this to CLAUDE.md").
  3. 틀렸거나 낡은 메모는 지웁니다. 파일의 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. 본문 — "너는 코드 검토자다. 검토하면서 발견한 패턴·관례·반복되는 문제를 에이전트 기억에 갱신해라."

메인 대화 자동 메모리 code-reviewer memory: project researcher memory: user writer memory: local 메인 기억은 안 넘어감 .claude/agent-memory/ 저장소에 커밋 · 팀 공유 ~/.claude/agent-memory/ 내 모든 프로젝트 .claude/agent-memory-local/ 이 프로젝트 · 커밋 안 함
역할(서브에이전트)마다 자기 이름의 기억 폴더(<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 프로젝트만 쓴다면 “직접 만든 에이전트도 파일 폴더로 기억을 이어 간다”는 것만 알고 보안으로 넘어가도 됩니다.

핵심: Claude 는 "부탁"만, 실제 저장은 내 프로그램이

메모리 도구는 클라이언트 쪽(client-side)에서 돌아갑니다. Claude 는 "이 파일 보여 줘", "이 파일 만들어 줘" 하고 요청만 하고, 그 요청을 실제 저장소에서 실행해 결과를 돌려주는 것은 내 애플리케이션입니다. 그래서 데이터를 어디에·어떻게 둘지 내가 정합니다. /memories 는 앞머리 경로일 뿐이고, 내 처리기(handler — 요청을 받아 실제로 실행하는 코드)가 이를 사용자별 폴더나 데이터베이스 키 같은 실제 저장소에 연결합니다.

Claude tool_use 요청 view /memories 내 애플리케이션 처리기가 경로 검사 후 실제 저장소에서 실행 내 저장소 폴더 · DB 등 내가 고름 요청 tool_result 같은 tools 항목을 보내고 처리기가 같은 저장소를 쓰면, 다음 대화도 같은 기억에서 이어집니다
기억은 전부 내 애플리케이션 안에 있습니다. 보안을 위해 모든 명령을 /memories 폴더 안으로 제한해야 합니다.

한 번의 흐름 — 고객 문의 답장 예

1. 사용자 요청 — "Help me respond to this customer service ticket." 뜻: 이 고객 문의에 답장하도록 도와줘.

사용자
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 두 파일이 있다고 알려 줍니다.

tool_result
/memories/customer_service_guidelines.xml1.5K
/memories/refund_policies.xml2.0K

4. 필요한 파일을 읽음 — view 로 응대 지침 파일을 열어 "고객을 이름으로 부를 것", "공감하는 말투" 같은 내용을 확인합니다.

{ "command": "view", "path": "/memories/customer_service_guidelines.xml" }

5. 기억을 바탕으로 답함 — "Based on your customer service guidelines, I can help you craft a response…" 뜻: 저장된 응대 지침에 따라 답장 작성을 돕겠습니다.

Claude
지난 대화에서 쌓인 지침을 다시 설명받지 않고도 같은 기준으로 답합니다.

시작하기 — 두 단계

  1. 요청에 도구 추가요청의 tools 에 {"type": "memory_20250818", "name": "memory"} 를 넣는 것이 설정의 전부입니다. 이름은 반드시 memory, 입력 형식은 따로 정의하지 않습니다.
  2. 처리기 구현메모리 명령마다 클라이언트 쪽 처리기를 만듭니다. /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줄/25KBMEMORY.md 200줄/25KBClaude 가 먼저 view
팀 공유저장소에 올리면 공유안 됨(이 컴퓨터만)project 범위면 공유내 저장소 설계에 따라
쓰는 곳Claude CodeClaude API 로 만든 앱
이 가이드의 제안 팀의 세컨드 브레인을 세 칸으로 나눠 생각하면 쉽습니다 — 팀 목표·규칙은 사람이 쓰는 지침 파일에, 역할별 노하우는 project 범위 서브에이전트 기억에, 나에 대한 선호는 자동 메모리에. 회사 업무용 에이전트를 직접 개발한다면 메모리 도구의 저장소를 팀이 함께 보는 곳으로 정할 수 있습니다.

기억을 쌓을 때의 보안 — 비밀 정보 · 크기 · 만료 · 경로

메모리 도구에서는 Claude 가 요청한 모든 파일 작업을 내 애플리케이션이 실행하므로, 아래 안전장치는 개발자의 책임입니다. 원문이 꼽는 네 가지는 다음과 같습니다.

🔒 비밀 정보

Claude 는 보통 민감한 정보를 기억 파일에 적기를 거절합니다. 더 확실히 하려면 처리기가 파일을 쓰기 전에 민감한 데이터를 걸러 내는 검사를 넣습니다.

📏 파일 크기

기억 파일 크기를 추적하고 한도를 둡니다. view 가 돌려주는 글자 수를 제한하고, 나머지는 view_range 로 나눠 읽게 할 수 있습니다.

⏳ 기억 만료

오랫동안 읽히지 않은 기억 파일은 주기적으로 지웁니다.

🚧 경로 넘어가기 막기

모든 명령의 모든 경로를 검사해 /memories 밖으로 나가지 못하게 합니다.

/memories/notes.txt /memories/../../secrets.env 처리기 검사 정규 경로로 바꾼 뒤 폴더 안인지 확인 ✓ 실행 ✕ 거절
원문 경고: /memories/../../secrets.env 같은 악의적 경로는 기억 폴더 밖 파일에 닿을 수 있습니다.
🔧 경로 검사 체크리스트 (원문)
  • 모든 경로가 /memories 로 시작하는지 확인
  • 경로를 정규 형태(canonical form)로 바꾼 뒤에도 기억 폴더 안에 있는지 확인
  • ../, ..\\ 같은 상위 폴더 이동 표현이 든 경로 거절
  • URL 인코딩된 표현(%2e%2e%2f)도 감시
  • 언어에 내장된 경로 보안 도구 사용(예: Python 의 pathlib.Path.resolve()·relative_to())

Claude Code 쪽에서 기억할 것

기억은 "강제 설정"이 아니라 맥락입니다 원문은 CLAUDE.md 와 자동 메모리 모두 Claude 가 맥락으로 받아들일 뿐, 강제되는 설정이 아니라고 밝힙니다. Claude 의 판단과 상관없이 반드시 막아야 할 동작은 PreToolUse 훅(도구를 쓰기 직전에 자동으로 실행돼 막을 수 있는 스크립트)으로 막습니다. 지시는 구체적이고 짧을수록 더 꾸준히 지켜집니다.
공유 범위를 의식하기 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)

CHAPTER 06

팀 꾸리기 — 서브에이전트와 에이전트 팀

이제 여러 에이전트를 한 팀으로 묶을 차례입니다. 역할을 파일 하나로 정의하고, 그 역할을 서브에이전트나 팀원으로 불러 씁니다. 이 장의 핵심 질문은 "새로 생긴 팀원은 무엇을 알고 시작하나"입니다 — 그 답이 왜 팀에 세컨드 브레인이 필요한지를 보여 줍니다.

이 장에서 배우는 것
  • 역할 정의 파일(.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. 본문 — "너는 코드 검토자다. 불려 오면 코드를 분석해 품질·보안·모범 관행에 대해 구체적이고 실행할 수 있는 의견을 줘라."

역할 정의 파일 .claude/agents/code-reviewer.md 머리말 + 본문(지시문) 서브에이전트로 "code-reviewer 로 검토해 줘" 에이전트 팀의 팀원으로 "그 역할로 팀원을 만들어 줘"
원문: 보안 검토·테스트 실행 같은 역할을 한 번 정의해, 맡기는 서브에이전트로도 팀원으로도 다시 쓸 수 있습니다.

어디에 두나 — 누가 쓸 수 있는가

파일을 둔 위치가 "누가 이 역할을 쓸 수 있는지"를 정합니다. 같은 이름이 여러 곳에 있으면 우선순위가 높은 쪽이 이깁니다.

위치범위우선순위
관리 설정(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 를 비우면 쓸 수 있는 도구를 모두 물려받음
modelsonnet·opus·haiku·fable·전체 모델 ID·inherit
permissionMode권한 방식(default·acceptEdits·auto·dontAsk·bypassPermissions·plan)
skills시작 때 미리 넣을 스킬(설명만이 아니라 전체 내용)
mcpServers이 역할만 쓸 MCP 서버
memory지속 기억 범위 user·project·local (5장)
omitClaudeMdtrue 면 사용자·프로젝트·로컬 CLAUDE.md 없이 시작
isolationworktree 면 임시 워크트리(저장소의 독립 복사본)에서 실행
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)은 각자 자기 컨텍스트 창에서 따로 일하면서 서로 직접 메시지를 주고받습니다. 나도 리더를 거치지 않고 어느 팀원에게나 바로 말할 수 있습니다. 원문은 이 기능이 실험 기능이며 기본으로 꺼져 있다고 밝힙니다.

리더 (team lead) 나누고 · 맡기고 · 모으기 팀원 A 자기 컨텍스트 창 팀원 B 자기 컨텍스트 창 팀원 C 자기 컨텍스트 창 메시지 메시지 공유 작업 목록 (task list) 대기 · 진행 중 · 완료 · 막힘 우편함 (mailbox) 에이전트 사이 메시지 전달
원문의 구성 요소 넷: 리더 · 팀원 · 공유 작업 목록 · 우편함. 팀원은 작업을 맡아 가고, 이름으로 서로 메시지를 보냅니다.

언제 쓰나

원문은 나란히 탐색하는 것이 실제로 가치를 더할 때 가장 효과적이라고 합니다. 가장 강한 쓰임은 넷입니다 — 여럿이 다른 측면을 조사하고 서로의 결과를 따져 보는 조사·검토, 각자 다른 조각을 맡는 새 모듈·기능, 서로 다른 가설을 동시에 시험하는 디버깅, 화면·서버·테스트를 각각 맡는 여러 층에 걸친 변경. 반대로 순서대로 해야 하는 일, 같은 파일을 고치는 일, 서로 얽힌 일이 많으면 한 세션이나 서브에이전트가 낫습니다. 팀은 조율에 드는 수고가 있고, 한 세션보다 토큰을 훨씬 많이 씁니다.

시작하기 — 말로 부탁하기

기능을 켠 뒤, 할 일과 원하는 팀원을 자연어로 설명하면 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 도구를 설계하고 있어. 팀원 셋을 만들어 다른 각도에서 살펴봐 — 하나는 사용 경험, 하나는 기술 구조, 하나는 일부러 반대 의견을 내는 역할.

공유 작업 목록 (예시 — 원문의 작업 상태를 바탕으로 그린 흉내)
ux 사용 흐름 정리completed · 완료
architect 저장 구조 비교in progress · 진행 중
(미배정) 반대 의견 검토pending · 대기
(미배정) 최종 설계 정리blocked · 앞 작업 기다림

작업은 대기·진행 중·완료 세 상태이고, 다른 작업에 기대는 작업은 앞 작업이 끝날 때까지 막힘으로 보입니다. 리더가 직접 배정하거나, 팀원이 일을 끝낸 뒤 배정 안 된·막히지 않은 다음 작업을 스스로 집어 갑니다(동시에 집지 않도록 파일 잠금을 씀). 팀원을 끝낼 때는 이름으로 부탁합니다 — "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
상태정식 기능실험 기능 기본 꺼짐
서브에이전트 메인 도우미 1 도우미 2 도우미 3 에이전트 팀 리더 팀원 1 팀원 2 팀원 3
왼쪽: 결과가 메인으로만 모입니다. 오른쪽: 팀원끼리 옆으로도 말을 주고받습니다.

원문의 한 줄 기준: 빨리 맡기고 보고만 받을 일꾼이 필요하면 서브에이전트, 결과를 나누고 서로 따지고 스스로 조율해야 하면 에이전트 팀. 또 팀을 꾸리기 전에 더 가벼운 방법(서브에이전트, 세션 사이 메시지)으로 되는지 먼저 보라고 권합니다.

팀원이 시작 때 받는 것 — 그래서 세컨드 브레인이 필요합니다

이 가이드가 답하려는 질문 — "팀 안의 모든 에이전트가 같은 목표와 맥락을 갖게 하려면?" — 의 열쇠가 이 소절입니다. 원문은 팀원이 만들어질 때 받는 것을 분명히 적어 둡니다.

CLAUDE.md 지침 파일 (3장) MCP 서버 외부 도구 연결 (8장) 스킬 필요할 때 읽는 절차 (4장) 생성 지시문 리더가 주는 첫 지시 새 팀원 자기 컨텍스트 창 리더의 대화 기록 넘어가지 않음 ✕
원문: 팀원은 일반 세션과 같은 프로젝트 맥락(CLAUDE.md · MCP 서버 · 스킬)을 읽고, 리더의 생성 지시문을 받습니다. 리더의 대화 기록은 넘어가지 않습니다.

팀원이 받는 것

  • 일반 세션과 같은 프로젝트 맥락 — CLAUDE.md, MCP 서버, 스킬
  • 리더가 준 생성 지시문
  • 리더가 정해 준 이름 — 누구에게나 이름으로 메시지 가능

팀원이 받지 못하는 것

  • 리더의 대화 기록 — 리더가 나와 나눈 이야기, 이미 읽은 파일
  • (서브에이전트의 경우) 메인 대화의 자동 메모리, 이미 부른 스킬, 출력 스타일 — 대신 CLAUDE.md 와 Claude 가 쓴 위임 메시지를 받습니다
그래서 — 목표와 맥락은 "대화"가 아니라 "파일"에

리더와 오래 이야기해 정한 목표도, 팀원에게는 파일에 적혀 있거나 생성 지시문에 들어 있지 않으면 없는 것입니다. 원문 사실(팀원은 CLAUDE.md·MCP·스킬을 읽는다)을 뒤집어 보면, 팀 전체가 공유해야 할 목표·용어·결정은 모두가 시작 때 읽는 파일에 두면 된다는 뜻이 됩니다. 이것이 이 가이드가 말하는 세컨드 브레인 — 팀이 함께 읽고 쓰는 공용 기억 파일 묶음 — 입니다.

이 가이드의 제안 — 세 군데에 나눠 담기
  1. 항상 알아야 할 것(팀 목표 한 단락, 지켜야 할 규칙, 용어): 프로젝트 CLAUDE.md 또는 그 CLAUDE.md 가 가져오는 파일(예시 이름 GOAL.md) — 3장.
  2. 필요할 때 꺼낼 것(절차, 참고 지식): 스킬 — 4장.
  3. 이번 일에만 필요한 것(맡은 파일, 마감, 출력 형식): 생성 지시문 — 다음 소절.
서브에이전트에게 꼭 전해야 할 규칙이 있으면 위임할 때 지시에 다시 적으라고 원문은 권합니다(예: "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 의 멀티 에이전트 조사 시스템 글은 무엇을 넣을지 네 가지로 정리합니다 — 하위 에이전트마다 목표, 출력 형식, 쓸 도구·출처 안내, 분명한 작업 경계가 필요합니다.

목표 — 무엇을 알아내거나 만들어야 하나
출력 형식 — 어떤 모양으로 돌려줘야 하나 (예: 심각도 등급을 붙인 문제 목록)
도구·출처 안내 — 어디를 보고 무엇을 써야 하나
작업 경계 — 어디까지가 내 몫이고 어디부터 남의 몫인가
모호한 지시 "반도체 부족 사태를 조사해" A: 2021 자동차 칩 위기 B: 2025 공급망 C: 2025 공급망 (B 와 겹침) 경계가 분명한 지시 목표 · 형식 · 출처 · 경계 A: 원인 — 맡은 범위만 B: 현재 공급망 — 맡은 범위만 C: 대응책 — 맡은 범위만
원문 사례: 짧은 지시를 받은 하위 에이전트 하나는 2021년 자동차 칩 위기를, 둘은 2025년 공급망을 똑같이 조사했습니다. 오른쪽 분담은 이 가이드가 만든 예시입니다.

원문의 생성 지시문 예

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명보다 나은 경우가 많다"고 합니다.

토큰 사용량 (채팅 = 1 기준, 멀티 에이전트 조사 시스템 글의 측정) 채팅 1 에이전트 약 4배 멀티 에이전트 약 15배 대신 내부 조사 평가에서 멀티 에이전트(리더 Opus 4 + 하위 Sonnet 4)가 단일 Opus 4 보다 90.2% 나았습니다
원문은 멀티 에이전트가 토큰을 빨리 쓰므로, 그만한 가치가 있는 일에만 경제적이라고 말합니다. 위 수치는 Claude Code 에이전트 팀이 아니라 Anthropic 조사 시스템의 측정입니다.

작업 크기도 맞추기

너무 작으면

조율에 드는 수고가 얻는 이득보다 큽니다.

너무 크면

중간 점검 없이 오래 일해 헛수고 위험이 커집니다.

알맞으면

분명한 결과물이 나오는 독립 단위 — 함수 하나, 테스트 파일 하나, 검토 하나.

리더가 작업을 충분히 쪼개지 않으면 더 작게 나누라고 부탁합니다. 원문은 팀원 한 명당 작업 5~6개면 모두가 바쁘게 일하고, 누가 막혀도 리더가 일을 다시 나눌 수 있다고 합니다.

일의 크기에 맞춰 사람 수 정하기 — 조사 시스템의 규칙 멀티 에이전트 조사 시스템은 에이전트가 알맞은 노력을 잘 가늠하지 못해 규칙을 프롬프트에 넣었습니다 — 단순한 사실 찾기는 에이전트 1개·도구 호출 3~10번, 직접 비교는 하위 에이전트 2~4개·각 10~15번, 복잡한 조사는 역할을 분명히 나눈 하위 에이전트 10개 이상. 초기에는 단순한 질문에 지나치게 많이 투입하는 실패가 흔했다고 합니다.

일을 나누는 패턴 — 단순하게 시작하기

Anthropic 의 "효과적인 에이전트 만들기" 글은 먼저 두 가지를 구분합니다. 워크플로(workflow)는 AI 와 도구가 미리 정해 둔 순서대로 움직이는 시스템이고, 에이전트(agent)는 AI 가 스스로 과정과 도구 사용을 정하는 시스템입니다. 그리고 가장 성공적인 사례들은 복잡한 프레임워크가 아니라 단순하고 조합하기 쉬운 패턴을 썼다고 말합니다.

원문의 첫 권고: 가장 단순한 해법부터 가능한 가장 단순한 해법을 찾고, 필요할 때만 복잡하게 만들라 — 에이전트 시스템을 아예 만들지 않는 것일 수도 있습니다. 에이전트 시스템은 속도와 비용을 내주고 성능을 얻습니다. 많은 경우 검색과 예시를 곁들인 한 번의 호출을 다듬는 것으로 충분합니다.
1단계 검문gate 2단계 결과

프롬프트 연결(prompt chaining) — 일을 순서 있는 단계로 나눠 각 호출이 앞 결과를 처리합니다. 중간에 검사(gate)를 둘 수 있습니다. 고정된 단계로 깔끔하게 나뉘는 일에 맞습니다. 원문 예: 개요 쓰기 → 개요가 기준을 만족하는지 확인 → 본문 쓰기.

라우팅(routing) — 들어온 일을 분류해 알맞은 전문 처리로 보냅니다. 원문 예: 고객 문의를 일반 질문·환불 요청·기술 지원으로 나눠 각기 다른 처리로 보내기, 쉬운 질문은 작고 저렴한 모델에 어려운 질문은 더 강한 모델에 보내기.

병렬화(parallelization) — 독립된 하위 작업을 나란히 돌리는 나누기(sectioning)와, 같은 일을 여러 번 돌려 다양한 답을 얻는 투표(voting) 두 가지가 있습니다. 원문 예: 한 모델은 답을 만들고 다른 모델은 부적절한 요청을 걸러 내기, 여러 프롬프트가 같은 코드를 각자 취약점 검토하기.

지휘 에이전트나누기 · 합치기 작업자 1 작업자 2 작업자 3 합친 결과

오케스트레이터-작업자(orchestrator-workers) — 오케스트레이터(일을 나누고 모으는 지휘 역할)가 일을 그때그때 나눠 작업자에게 맡기고 결과를 합칩니다. 병렬화와 모양은 비슷하지만, 하위 작업이 미리 정해지지 않고 입력을 보고 지휘 에이전트가 정한다는 점이 다릅니다. 원문 예: 여러 파일을 매번 다르게 고치는 코딩, 여러 출처에서 정보를 모으는 검색. 멀티 에이전트 조사 시스템도 이 구조로, 리더가 전략을 세우고 하위 에이전트를 나란히 띄웁니다.

평가자-개선자(evaluator-optimizer) — 한 호출이 답을 만들고 다른 호출이 평가·의견을 주는 일을 되풀이합니다. 평가 기준이 분명하고, 다듬을수록 눈에 띄게 나아질 때 맞습니다. 원문 예: 미묘한 뜻을 살려야 하는 문학 번역.

이 가이드의 제안 — Claude Code 기능과 짝 짓기 원문은 패턴과 Claude Code 기능을 직접 짝 짓지 않습니다. 이 가이드의 읽는 법은 이렇습니다 — 이어 달리기는 서브에이전트를 차례로 잇기(위 "차례로 잇기"), 나란히는 서브에이전트 여럿으로 나란히 조사, 지휘-작업자는 리더와 팀원(작업 목록을 보고 리더가 나누기), 평가-개선은 만드는 팀원과 검토 역할 팀원. 처음에는 원문 권고대로 가장 단순한 것(한 세션 → 서브에이전트)부터 해 보고, 서로 따지고 조율해야 할 때 팀으로 넓힙니다.

원문은 에이전트를 만들 때의 세 원칙으로 끝맺습니다 — 설계를 단순하게, 에이전트의 계획 단계를 드러내 보이기, 도구 설명과 시험으로 에이전트가 쓰는 도구의 사용법을 잘 만들기.

한계와 주의할 점

에이전트 팀은 실험 기능이라 원문이 밝힌 한계가 있습니다. 미리 알면 덜 당황합니다.

한계무슨 뜻인가 · 대처
세션을 이어 열면 팀원이 안 돌아옴/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)

CHAPTER 07

이어 달리기 — 인수인계 노트와 긴 작업

몇 시간, 며칠짜리 일은 한 세션 안에 끝나지 않습니다. 새 세션은 앞 세션이 한 일을 전혀 모른 채 시작합니다. 이 장은 다음 세션·다른 에이전트가 바통을 이어받을 수 있게 인수인계 노트를 남기는 방법을 다룹니다. 세컨드 브레인에서 "지금 어디까지 왔나"를 맡는 층입니다.

이 장에서 배우는 것
  • 긴 작업에서 에이전트가 실패하는 두 가지 모습과 그 이유
  • 진행 기록 파일(claude-progress.txt)·기능 목록(feature_list.json)·git 기록으로 세션 사이를 잇는 법
  • 새 세션이 매번 같은 순서로 "현재 상태 파악"부터 하는 시작 루틴
  • 메모리 도구의 여러 세션 작업 패턴(첫 세션 준비 → 매 세션 읽기 → 끝날 때 갱신)
  • 서브에이전트 결과를 대화가 아니라 파일로 넘겨 "전화 게임"을 줄이는 법
  • 자주 나오는 실패 네 가지와 해결책 한 표
처음이라면 이것만

건너뛰어도 되는 곳: 「서브에이전트 결과는 파일로」는 여러 에이전트를 함께 쓸 때 봅니다. 「개발자용」으로 접힌 상자는 접어 둔 채 읽어도 됩니다.

긴 작업의 문제 — 새 세션은 앞 일을 모른다

쉽게 비유하면 교대 근무하는 공장을 떠올려 보세요. 그런데 이 공장은 이상해서, 새로 출근한 사람은 앞 근무조가 무엇을 했는지 하나도 기억하지 못합니다. 교대 일지가 없으면 새 사람은 "어디까지 했지?"를 추측하느라 시간을 다 씁니다. 원문(Anthropic 엔지니어링 블로그)이 든 비유가 바로 이것입니다 — 에이전트의 세션 하나하나가 그 근무조입니다.

에이전트는 세션(에이전트를 한 번 켜서 끌 때까지의 작업 한 판) 단위로 일하고, 새 세션은 앞 세션의 기억 없이 시작합니다. 컨텍스트 창(에이전트가 한 번에 담을 수 있는 글의 한도)에는 한도가 있고, 복잡한 일은 창 하나 안에 끝나지 않습니다. 그래서 세션과 세션 사이에 다리가 필요합니다.

세션 1 컨텍스트 창 하나 일하다 한도에 닿음 세션 2 빈 창으로 새로 시작 "어디까지 했지?" 세션 3 역시 기억 없음 노트가 있으면 바로 이어 감 ✕ ✕ 인수인계 노트 · git 기록 세션이 바뀌어도 파일은 남는다 — 모든 세션이 여기서 읽고 여기에 쓴다
세션 사이의 기억(✕)은 끊겨도, 파일에 남긴 노트는 다음 세션이 그대로 읽습니다.

압축만으로는 부족했다

Claude Agent SDK(Anthropic 이 만든, 에이전트를 직접 만들 때 쓰는 도구 모음)에는 압축(compaction — 대화가 길어지면 앞부분을 요약해 창을 비우는 기능, 1장)이 있습니다. 이론상 그러면 끝없이 일할 수 있을 것 같지만, 원문 실험에서는 "claude.ai 를 똑같이 만들어 줘" 같은 큰 지시 하나만으로는 제품 수준의 웹 앱을 완성하지 못했습니다. 압축이 다음 에이전트에게 늘 완벽하게 분명한 지시를 넘겨주지는 않기 때문입니다.

실패 1 — 한 번에 다 하려 함

앱 전체를 한 번에 만들려다 구현 도중 컨텍스트가 바닥납니다. 다음 세션은 반쯤 만들어지고 기록도 없는 기능을 물려받아, 무슨 일이 있었는지 추측하고 기본 동작을 되살리는 데 시간을 씁니다.

실패 2 — 너무 일찍 "다 했다"

일이 꽤 진행된 뒤, 새 세션이 둘러보고 진척이 있는 것을 보고는 일이 끝났다고 선언해 버립니다. 남은 일이 무엇인지 알려 주는 목록이 없어서입니다.

원문은 이 문제를 둘로 나눕니다. ① 처음에 모든 기능의 토대가 될 환경을 준비해 한 단계씩 일하게 만들고, ② 매 세션이 목표를 향해 조금씩 나아가되 끝날 때는 깨끗한 상태로 두게 하는 것입니다. "깨끗한 상태"란 큰 버그가 없고 정리·기록이 되어 있어, 다음 사람이 엉뚱한 뒷정리 없이 바로 새 일을 시작할 수 있는 상태를 말합니다.

진행 기록 파일과 git — 다음 사람을 위한 메모

원문의 해결책은 두 가지 역할입니다. 맨 처음 세션만 다른 지시를 받아 환경을 준비하고, 그 뒤의 모든 세션은 조금씩 일하고 기록을 남깁니다. 원문 각주에 따르면 둘은 첫 지시만 다를 뿐, 시스템 프롬프트·도구·하네스(에이전트를 감싸 도구 사용과 반복 실행을 맡는 틀)는 똑같습니다.

첫 세션 한 번 초기화 에이전트(initializer) init.sh claude-progress.txt feature_list.json 첫 git 커밋 그다음 모든 세션 코딩 에이전트(coding agent) ① 읽기 기록 · 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 답이 보인다" 같은 것입니다.

feature_list.json 기능 200개 넘게 (claude.ai 복제 예) 1. 새 채팅 버튼이 새 대화를 만든다 통과 2. 질문을 보내면 답이 보인다 통과 3. 대화가 사이드바에 나타난다 작업 중 4 … 200. 아직 실패(false) 규칙 · 처음엔 모두 실패 · 고칠 수 있는 건 "passes" 칸 하나뿐 · 끝까지 확인한 뒤에만 통과
남은 일이 눈에 보이니 "진척이 있네, 끝!"이라고 착각하지 않고, 한 번에 하나씩 고릅니다.
  • 처음엔 전부 "실패" — 그래야 뒤의 세션들이 "완성된 모습"의 윤곽을 분명히 봅니다.
  • 고칠 수 있는 것은 통과 여부 칸(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(지금 있는 폴더 위치를 보여 주는 명령)를 실행합니다. 원문 지시: "이 폴더 안의 파일만 고칠 수 있다."

📂 작업 폴더 $ 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 Code 에서는 매 세션 시작 때 읽히는 지침 파일 CLAUDE.md(3장)에 "세션을 시작하면 진행 기록과 git 로그를 먼저 읽는다" 같은 짧은 줄을 두면 같은 효과를 노릴 수 있습니다. 다만 지침 파일은 강제 설정이 아니라 맥락이므로, 반드시 지켜야 하는 확인은 9장 「반드시 막을 것」의 방법을 씁니다.

메모리 도구의 여러 세션 패턴 — 기억을 "복구 장치"로

Claude API 의 메모리 도구(Claude 가 /memories 폴더에 파일을 만들고 읽어 대화를 넘어 기억하게 하는 기능, 5장) 문서에도 같은 생각이 정리되어 있습니다. 여러 세션에 걸친 소프트웨어 작업이라면, 일하면서 그때그때 메모를 쓰지 말고 메모리 파일을 미리 계획해 만들라고 합니다. 그러면 메모리가 복구 장치가 되어, 새 세션마다 지난 세션이 남긴 상태에서 다시 시작합니다.

① 첫 세션: 파일 준비 진행 기록 · 체크리스트 · 시작 스크립트 ② 매 세션: 먼저 읽기 코드를 다시 뒤지지 않음 ③ 끝날 때: 기록 갱신 한 것 · 남은 것 기능 하나씩 확인한 뒤에만 완료
원문 「Multisession software development pattern」의 세 단계와 핵심 원칙(기능 하나씩, 확인 후 완료).
  1. 첫 세션(준비) — 본격적인 일 전에 메모리 파일을 만듭니다: 진행 기록(한 일과 다음 할 일), 기능 체크리스트(일의 범위), 필요한 시작 스크립트를 가리키는 메모.
  2. 이후 세션 — 시작하자마자 그 파일들을 읽어 프로젝트 상태를 되살립니다. 코드를 다시 탐색하거나 예전 결정을 되짚지 않아도 됩니다.
  3. 세션 끝 — 끝나기 전에 진행 기록에 끝낸 것과 남은 것을 적어, 다음 세션이 정확한 출발점을 갖게 합니다.

핵심 원칙은 앞 소절과 같습니다: 한 번에 기능 하나, 그리고 코드를 썼을 때가 아니라 처음부터 끝까지 확인이 된 뒤에만 완료로 표시합니다. 그래야 진행 기록이 세션에서 세션으로 정확하게 유지됩니다.

메모리 도구가 스스로 붙이는 지시 메모리 도구를 켜면 API 가 시스템 프롬프트에 지시를 자동으로 넣습니다. 그 안에 "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 멀티 에이전트 연구 시스템)은 이것을 "전화 게임"(귓속말 전달 놀이)이라고 부릅니다.

말로 전달 (전화 게임) 서브에이전트 긴 보고서 100% 지휘 에이전트 다시 요약 … 최종 결과 일부가 빠짐 대화 기록으로 큰 결과를 옮기느라 토큰도 듦 파일로 저장 (산출물) 서브에이전트 결과를 파일에 📄 파일 그대로 보존 지휘 에이전트 "위치"만 받음 가벼운 참조(파일 경로)만 오감
원문: 서브에이전트가 결과를 바깥 저장소에 두고, 지휘 에이전트에게는 가벼운 참조만 넘기게 하라.

결과는 파일로

서브에이전트가 도구로 결과를 바깥 저장소(파일)에 저장하고, 지휘 에이전트에게는 가벼운 참조만 돌려줍니다. 여러 단계를 거치며 정보가 새는 것을 막고, 큰 결과를 대화 기록으로 복사하는 토큰도 줄입니다. 코드·보고서·데이터 시각화처럼 모양이 정해진 결과물에 특히 잘 맞습니다.

계획은 메모리에

원문의 지휘 연구 에이전트는 먼저 접근 방법을 생각한 뒤 계획을 메모리에 저장합니다. 컨텍스트 창이 200,000 토큰을 넘으면 잘려 나가므로, 계획만은 꼭 남겨 두려는 것입니다.

단계가 끝나면 요약해 보관

대화가 수백 턴(주고받기 한 번)에 이르면, 끝난 작업 단계를 요약해 바깥 메모리에 저장하고 다음 일로 넘어갑니다. 한도가 다가오면 깨끗한 컨텍스트의 새 서브에이전트를 띄우고 신중하게 인수인계해 흐름을 잇습니다.

이 가이드의 제안 — 팀 공용 결과 폴더 세컨드 브레인 관점에서는, 팀원(서브에이전트·에이전트 팀원)이 결과를 넣는 공용 폴더 하나를 정해 두고 "결과는 이 폴더에 파일로 쓰고, 나에게는 파일 경로만 알려 달라"고 맡길 때 적어 주기를 권합니다. 폴더 이름(예: outputs/)은 이 가이드의 예시 이름입니다. 에이전트 팀이라면 두 팀원이 같은 파일을 고치면 덮어쓰기가 생기므로, 원문(agent-teams)대로 팀원마다 맡는 파일을 나눕니다.

자주 나오는 실패와 해결 — 한 표로

원문은 긴 작업 에이전트의 흔한 실패 네 가지와 해결책을, 첫 세션(초기화 에이전트)이 할 일과 매 세션(코딩 에이전트)이 할 일로 나눠 정리했습니다.

문제첫 세션에 준비할 것매 세션 할 일
프로젝트 전체를 너무 일찍 "다 했다"고 선언기능 목록 파일: 처음 지시를 바탕으로 처음부터 끝까지 확인할 기능 설명을 JSON 파일 하나에세션 시작 때 기능 목록을 읽고, 기능 하나만 골라 시작
버그나 기록 안 된 진행을 남긴 채 끝남처음 git 저장소와 진행 기록 파일 만들기시작: 진행 기록·git 로그 읽고 개발 서버에서 기본 시험(숨은 버그 찾기). 끝: git 커밋 + 진행 기록 갱신
기능을 너무 일찍 완료로 표시기능 목록 파일모든 기능을 스스로 확인. 꼼꼼히 시험한 뒤에만 통과로
앱을 어떻게 실행할지 알아내느라 시간을 씀개발 서버를 켜는 init.sh 작성세션 시작 때 init.sh 읽기
실패 너무 일찍 끝냄 기록 없이 끝냄 확인 없이 완료 실행법을 헤맴 feature_list.json claude-progress.txt + git 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)

CHAPTER 08

바깥 지식 잇기 — MCP 와 Claude 프로젝트

팀의 지식은 폴더 안 파일에만 있지 않습니다. 일정표·문서 도구·이슈 관리·데이터베이스에도 흩어져 있지요. 이 장은 에이전트가 그런 바깥 도구를 직접 읽고 쓰게 잇는 표준 MCP와, 코딩을 하지 않는 팀이 지식·지침을 한곳에 묶어 함께 쓰는 Claude 프로젝트를 다룹니다.

이 장에서 배우는 것
  • MCP 가 무엇이고 왜 "AI 앱용 USB-C 포트"라고 부르는지
  • Claude Code 에서 MCP 서버를 어느 범위(로컬·프로젝트·사용자)에 둘지 고르는 법
  • 팀 전원이 같은 도구를 쓰도록 .mcp.json 을 함께 쓰는 법과 그때의 승인 절차
  • 코딩을 안 하는 팀의 선택지 — Claude 프로젝트의 지식·지침·공유 권한
  • 지식이 아주 많아지면 쓰는 RAG 가 무엇인지
처음이라면 이것만

건너뛰어도 되는 곳: 명령 옵션·설정 파일 예시는 「개발자용」으로 접혀 있습니다. 코딩을 하지 않는다면 MCP 두 소절은 개념만 보고 「Claude 프로젝트」로 바로 가도 됩니다.

MCP 란 — AI 앱용 USB-C 포트

MCP(Model Context Protocol — AI 앱을 외부 도구·데이터에 잇는 표준 연결 방식)는 AI 애플리케이션을 바깥 시스템에 연결하는 오픈소스 표준입니다. Claude 나 ChatGPT 같은 AI 앱이 MCP 로 데이터(로컬 파일·데이터베이스), 도구(검색 엔진·계산기), 워크플로(일의 정해진 순서 — 원문 예: 전문 프롬프트)에 연결해 필요한 정보에 닿고 일을 해낼 수 있습니다.

원문의 비유 MCP 는 AI 앱용 USB-C 포트입니다. USB-C 가 여러 전자 기기를 한 가지 방식으로 잇게 해 주듯, MCP 는 AI 앱을 바깥 시스템에 한 가지 방식으로 잇습니다. 한 번 만들면 MCP 를 지원하는 여러 앱(Claude, ChatGPT, Visual Studio Code, Cursor 등)에서 두루 쓸 수 있습니다.
AI 앱 Claude Code Claude (claude.ai) 그 밖의 앱 ChatGPT · VS Code · Cursor … MCP 표준 포트 하나 데이터 로컬 파일 · 데이터베이스 도구 검색 엔진 · 계산기 워크플로 전문 프롬프트
앱마다 따로 연결을 만들지 않고, 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 세컨드 브레인의 파일(목표·지침·노트)은 "팀이 정리해 둔 지식"이고, MCP 는 "살아 움직이는 바깥 지식"(오늘의 일정, 최신 이슈, 데이터베이스)을 잇는 통로입니다. 파일에는 어떤 도구에서 무엇을 찾는지만 적고, 바뀌는 내용 자체는 MCP 로 그때그때 읽게 하면 노트가 낡지 않습니다(필요할 때 읽기 — 1장).
연결 전에 믿을 수 있는지 확인 원문 경고: 연결하는 서버마다 믿을 수 있는지 먼저 확인하세요. 바깥 내용을 가져오는 서버는 프롬프트 주입(가져온 글 속에 숨은 지시가 에이전트를 엉뚱하게 움직이게 하는 공격) 위험에 노출될 수 있습니다.

MCP 서버를 둘 범위 — 나만 · 이 프로젝트 팀 · 내 모든 프로젝트

Claude Code 에서 MCP 서버는 세 가지 범위(scope — 그 설정이 어디까지 적용되고 누구와 나눠지는지) 중 하나에 둡니다. 범위가 정하는 것은 두 가지입니다: 어느 프로젝트에서 켜지나, 그리고 팀과 나눠지나.

범위켜지는 곳팀과 공유저장 위치쓰기 좋은 곳(원문)
로컬 (local, 기본값)지금 프로젝트만아니오~/.claude.json개인 개발용 서버, 실험 설정, 버전 관리에 넣고 싶지 않은 비밀 정보가 든 서버
프로젝트 (project)지금 프로젝트만예 — 버전 관리로프로젝트 맨 위 폴더의 .mcp.json팀이 함께 쓰는 도구·서비스
사용자 (user)내 모든 프로젝트아니오~/.claude.json여러 프로젝트에서 자주 쓰는 개인 도구
로컬 나 · 이 프로젝트 하나 ~/.claude.json 👤 나만 프로젝트 이 저장소를 쓰는 모두 .mcp.json 👥 팀 전원 사용자 나 · 내 모든 프로젝트 ~/.claude.json 👤 나만 같은 이름이 여러 곳에 있으면 (높은 쪽 하나만 씀) 조직 제공 › 로컬 › 프로젝트 › 사용자 › 플러그인 › claude.ai 커넥터
개인 팀에 쓰는 도구는 로컬·사용자 범위, 회사 팀이 함께 쓰는 도구는 프로젝트 범위(.mcp.json)가 기본 짝입니다.

겹칠 때의 순서. 같은 서버가 여러 곳에 정의되어 있으면 Claude Code 는 한 번만 연결하고, 가장 우선순위가 높은 곳의 정의 전체를 씁니다(범위끼리 칸을 섞지 않음). 순서는 로컬 → 프로젝트 → 사용자 → 플러그인이 준 서버 → claude.ai 커넥터이고, 조직이 관리 설정(managedMcpServers)으로 제공한 서버는 이 모두보다 위입니다.

헷갈리기 쉬운 이름 MCP 의 "로컬 범위"는 일반 설정의 "로컬 설정"과 다릅니다. MCP 로컬 범위 서버는 홈 폴더의 ~/.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 이 생깁니다.

👤 추가한 사람 --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개까지 만듭니다.

📁 프로젝트 하나 (예: 마케팅팀 분기 계획) 프로젝트 지식 문서 · 글 · 코드 · 파일 모든 대화의 배경 프로젝트 지침 말투 · 역할 · 관점 예: 격식체로 답하기 대화들 (이 프로젝트 안에서 따로따로) 대화 A 대화 B 대화 C 팀원 Team · Enterprise Can view 보기 + 대화만 편집 불가 Can edit 지침·지식 수정 멤버 추가·삭제 설정 변경
프로젝트 지식과 지침이 그 프로젝트의 모든 대화에 깔리는 공용 맥락이 됩니다. 프로젝트 이름은 예시입니다.

프로젝트 지식

관련 문서·글·코드·파일을 프로젝트의 지식 창고에 올리면, Claude 가 그 프로젝트 안의 각 대화에서 맥락과 배경을 이해하는 데 씁니다.

프로젝트 지침

프로젝트마다 지침을 정해 답을 맞춥니다. 예: 더 격식 있는 말투로, 또는 특정 역할·업계의 관점에서 답하게.

팀과 공유하기 (Team · Enterprise 요금제만)

항목내용
권한 — Can view(보기)프로젝트 내용·지식·지침을 보고 프로젝트 안에서 대화할 수 있지만 고칠 수는 없음
권한 — Can edit(편집)지침과 지식을 고치고, 멤버를 추가·삭제하고, 멤버 설정을 바꾸고, 함께 기여
공유 방법이메일로 특정 팀원에게 / 이메일 목록으로 여러 명 한꺼번에 / 조직 전체에 (만들 때나 나중에)
찾기·알림남이 공유한 프로젝트는 Shared with me(나와 공유됨) 탭에서 찾고, 공유되면 이메일 알림
관리만든 사람은 권한을 바꾸거나 접근을 뺄 수 있음. 여러 멤버가 같은 프로젝트에 문서를 보태고 대화를 만들며 함께 일함
이 가이드의 제안 — 프로젝트를 팀의 세컨드 브레인으로 코딩을 안 하는 회사 팀이라면 팀 하나 = 프로젝트 하나로 시작하길 권합니다. 팀 목표·용어·결정 사항 문서를 프로젝트 지식에 올리고, 공통 규칙("보고서는 결론부터")을 프로젝트 지침에 적습니다. 지침·지식을 고칠 사람만 Can edit, 나머지는 Can view 로 두면 기준 문서가 함부로 바뀌지 않습니다. 쓰는 기능(지식·지침·권한)은 원문 사실이고, 이렇게 나누는 방식은 이 가이드의 제안입니다.
🔧 참고 — 관리자 설정과 새 버전 프로젝트(베타)

관리자 설정. 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배까지 늘립니다.

큰 지식 창고 한 번에 다 넣을 수 없음 ❓ 질문 관련 조각 찾기 컨텍스트 창 관련 조각 1 관련 조각 2 → 이것으로 답
RAG 는 창고 전체가 아니라 질문과 관련된 조각(주황)만 컨텍스트 창에 넣습니다.
방식어떻게 찾나원문
전통적 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)

CHAPTER 09

개인 팀과 회사 팀 — 범위 · 보안 · 관리

이 가이드가 처음에 던진 질문으로 돌아옵니다: 개인 일을 하는 에이전트 팀과 회사 일을 하는 에이전트 팀을 따로 꾸리되, 각 팀 안에서는 모든 에이전트가 같은 목표와 맥락을 갖게 하려면? 열쇠는 앞 장들의 파일을 어느 범위에 두느냐입니다. 그리고 반드시 지켜야 할 규칙·비밀 정보·오래된 기억을 어떻게 관리하는지도 다룹니다.

이 장에서 배우는 것
  • 범위(조직·사용자·프로젝트·로컬)로 개인 팀과 회사 팀을 나누는 법 — 한 표로
  • 개인 팀과 회사 팀 각각의 구성 예(이 가이드의 제안)와 거기 쓰는 기능(원문 사실)
  • 지침 파일은 "맥락"일 뿐 — 반드시 막아야 할 것은 훅·권한 규칙·관리 설정으로
  • 팀원 에이전트는 내 대신 승인할 수 없다는 것, 메모리·MCP 의 비밀 정보 주의
  • 세컨드 브레인을 낡지 않게: 정기 점검, 충돌 정리, 오래된 것 보관
처음이라면 이것만

회사에서 보안 담당이거나 팀 설정을 맡았다면 「반드시 지킬 규칙은 강제 장치로」도 꼭 보세요. 비밀 정보 다루는 법은 이 장 뒤쪽 「보안 — 비밀 정보와 승인」 소절에 있습니다.

개인 팀과 회사 팀을 어떻게 나누나 — 범위로 나눈다

Claude Code 의 지침 파일·스킬·역할 정의·MCP 서버·설정은 모두 어디에 저장하느냐에 따라 적용 범위(scope — 그 파일이 어느 프로젝트에서 읽히고 누구와 나눠지는지)가 정해집니다. 원문의 범위는 넷입니다.

조직 (managed policy) IT·DevOps 가 배포 — 그 컴퓨터의 모든 사용자 사용자 (user) ~/.claude/ 나만 — 내 모든 프로젝트에 프로젝트 (project) 저장소 안 버전 관리로 팀원 모두 — 이 프로젝트에 로컬 (local) CLAUDE.local.md 나만 — 이 프로젝트에 (git 에 안 올림) 넓은 범위 읽히는 순서 좁은 범위
지침 파일은 넓은 범위부터 읽혀, 프로젝트 지침이 사용자 지침보다 뒤에(나중에) 컨텍스트에 들어갑니다.

아래 표는 앞 장들에서 본 것을 범위별로 모은 것입니다(경로는 원문 그대로).

범위지침 파일 (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 가 스스로 적는 자동 메모리(5장)는 저장소마다 하나(~/.claude/projects/<project>/memory/)이고 그 컴퓨터에만 있습니다. 같은 저장소의 워크트리(한 저장소를 여러 작업 폴더로 동시에 펼친 것)끼리는 나눠 쓰지만, 다른 컴퓨터나 클라우드 환경과는 공유되지 않습니다. 팀이 함께 봐야 할 사실은 자동 메모리가 아니라 저장소의 파일에 적습니다.
이 가이드의 제안 — 나누는 기준 한 줄 개인 팀 = 사용자 범위 + 개인용 폴더(저장소) 하나, 회사 팀 = 회사 저장소의 프로젝트 범위 + 조직 범위, 그리고 회사 일 속 "나만의 메모"는 로컬 범위. 주의할 점이 하나 있습니다: 사용자 범위(~/.claude/)는 원문대로 "내 모든 프로젝트"에 읽히므로, 회사 저장소에서 일할 때도 읽힙니다. 그래서 사용자 범위에는 어디서 읽혀도 괜찮은 공통 선호만 두고, 개인 팀의 목표·개인 일정 같은 것은 개인용 폴더의 프로젝트 지침에 둡니다.

개인 팀 구성 예 — 사용자 범위 + 개인용 폴더

개인 일을 하는 에이전트 팀의 세컨드 브레인을 이 가이드는 이렇게 꾸리기를 제안합니다. 폴더 이름 my-brain/(활용편과 같은 예시), 파일 이름 GOAL.md 와 PARA 폴더 이름은 이 가이드의 예시 이름이고, 나머지 경로(~/.claude/…, CLAUDE.md, .claude/agents/, claude-progress.txt 등)는 원문 이름입니다.

① 사용자 범위 — 어디서나 ~/.claude/ CLAUDE.md 공통 선호 rules/ 주제별 선호 skills/ 개인 절차 agents/ 개인 역할 ~/.claude.json MCP 사용자 범위 (일정·메모 앱 등) 회사 저장소에서도 읽힘 → 공통 선호만 ② 개인용 폴더 — 개인 팀만 ~/my-brain/ (예시) CLAUDE.md @GOAL.md 불러옴 GOAL.md (예시) 목표 한 장 Projects/ … (예시) PARA 창고 .claude/agents/ 팀 역할 claude-progress.txt 인수인계 여기서 띄운 팀원 모두 같은 지침을 읽음
사용자 범위는 "나라는 사람"의 공통 선호, 개인용 폴더는 "개인 팀"의 목표·지식·역할을 담습니다.

1. 사용자 범위에 공통 선호

~/.claude/CLAUDE.md 는 원문 기준 "모든 프로젝트에 쓰이는 개인 선호"(코드 스타일 선호, 개인 도구 단축 등) 자리입니다. 주제별로 나누려면 ~/.claude/rules/ 에 preferences.md·workflows.md 처럼 둡니다. 원문은 사용자 규칙이 프로젝트 규칙보다 먼저 읽히고, 둘이 충돌하면 어느 쪽을 따를지 모르니 일관되게 유지하라고 합니다.

~/.claude/CLAUDE.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/<이름>/ 에 쌓습니다.

회사 팀 구성 예 — 회사 저장소 + 조직 범위

회사 일을 하는 팀은 세컨드 브레인을 모두가 받는 곳, 즉 회사 저장소(프로젝트 범위)에 둡니다. 원문은 프로젝트 지침을 "버전 관리로 팀원과 공유하는 지침"(프로젝트 구조, 코딩 표준, 공통 작업 방식)이라고 설명합니다. 아래 구성은 이 가이드의 제안이고, 경로와 기능은 원문 그대로입니다.

조직 층 — IT·보안 담당이 배포 관리형 CLAUDE.md (회사 표준·보안 정책·규정 안내) + 관리 설정 (막을 것 강제) 회사 저장소 — 버전 관리로 팀 전원 (팀원 에이전트 포함) CLAUDE.md · AGENTS.md 팀 목표 · 구조 · 공통 방식 .claude/rules/ · .claude/skills/ 부분 규칙 · 팀 절차 .claude/agents/ · .claude/agent-memory/ 팀 역할 · 역할별 배움 .mcp.json · .claude/settings.json 공용 도구 · 팀 권한·훅 CLAUDE.local.md 나만의 테스트 주소·메모 — .gitignore 에 넣어 회사 저장소에 올리지 않음
조직이 정한 층 위에, 팀이 함께 고치는 저장소 층, 그리고 나만의 로컬 층이 얹힙니다.

조직 층

관리형 CLAUDE.md 는 그 컴퓨터의 모든 사용자에게, 어느 저장소에서든 적용됩니다. 개발자가 claudeMdExcludes 로 다른 지침 파일은 뺄 수 있어도 이것은 못 뺍니다. 원문 예: 회사 코딩 표준, 보안 정책, 규정 준수 요구.

회사 저장소 층

팀 지침·규칙·스킬·역할 정의를 저장소에 커밋해 함께 고칩니다. 원문은 프로젝트 역할 정의(.claude/agents/)를 버전 관리에 넣어 팀이 함께 쓰고 다듬으라고, 서브에이전트 메모리는 project 범위를 기본으로 권합니다.

나의 로컬 층

CLAUDE.local.md 는 이 프로젝트에서 나만 쓰는 선호(내 샌드박스(마음껏 시험해도 되는 따로 떼어 둔 환경) 주소, 즐겨 쓰는 테스트 데이터) 자리입니다. .gitignore 에 넣어 커밋되지 않게 합니다.

코딩 안 하는 팀

Claude 프로젝트 하나를 팀의 공용 공간으로 두고, Team·Enterprise 요금제에서 Can view / Can edit 권한으로 공유합니다(8장).

이 가이드의 제안 — 회사 팀에서 "같은 목표·맥락"을 보장하는 순서
  1. 회사 저장소 CLAUDE.md 맨 위에 팀 목표 한 단락(또는 목표 파일을 @ 로 불러오기). 원문 권장대로 파일당 200줄 아래로 짧게.
  2. 여러 도구(Claude Code 외)를 함께 쓴다면 AGENTS.md 를 기준 문서로 두는 방법(3장).
  3. 공용 도구는 .mcp.json, 공용 절차는 .claude/skills/, 역할은 .claude/agents/ 로 — 모두 커밋.
  4. 반드시 지켜야 할 것은 지침이 아니라 .claude/settings.json 의 권한 규칙·훅으로(다음 소절).
🔧 관리자용 참고 — 관리형 지침 배포와 관리 설정
  • 관리형 CLAUDE.md 위치: macOS /Library/Application Support/ClaudeCode/CLAUDE.md · Linux·WSL /etc/claude-code/CLAUDE.md · Windows C:\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 문서는 지시를 두 종류로 나눕니다.

Claude 가 판단 (맥락) non-deterministic — 보통 따르지만 보장 없음 프롬프트 · CLAUDE.md Claude 가 스스로 고르는 스킬 자동 모드의 판정 모델 대부분의 가이드라인은 여기 — 예외가 있으니까 Claude Code 가 강제 deterministic — 모델이 뭐라 하든 매번 훅 (command · http) 권한 규칙 deny · 샌드박스 관리 설정 (조직) 예외가 0 인 규칙만 여기로
원문 팁: CLAUDE.md 의 한 줄을 아무리 강조해도 계속 놓친다면, 그 줄은 훅으로 옮길 신호입니다.
장치무엇을 하나 (원문)예
훅(hook — Claude 의 작업 흐름 중 정해진 순간에 내 명령을 자동 실행하는 장치)도구 사용 전후, Claude 가 멈추려 할 때, 세션 시작 때 등에 실행. 진짜 강제는 command·http 훅으로(prompt·agent 훅은 다른 모델이 판단하므로 강제가 아님)파일을 고칠 때마다 서식 정리 실행, migrations/ 폴더 수정 막기
권한 규칙무엇을 실행·읽기·가져오기 할 수 있는지 정함. deny 규칙은 자동 모드·bypassPermissions 를 포함한 모든 권한 모드에서 유지.env 읽기 막기
샌드박스운영체제 수준에서 셸 명령의 파일·네트워크 접근을 가둠(/sandbox)보안 관련이면 권한 규칙과 함께
관리 설정조직이 배포. 어떤 개인 설정 파일도 덮어쓸 수 없어 보안팀 정책의 유일한 자리특정 도구·명령·경로 막기, 로그인 방식 제한

에이전트 팀의 권한 — 팀원은 내 대신 승인할 수 없다

원문 보안 규칙 에이전트끼리 메시지를 보내면, 받는 쪽은 그 메시지가 사용자가 아니라 다른 Claude 세션에서 왔다고 전달받습니다. 팀원은 권한 요청을 내 대신 승인하거나 동의를 대신할 수 없고, 거절당한 행동을 다른 팀원에게 넘겨 검사를 피할 수도 없습니다. 팀원의 권한 요청은 리더 세션에 뜨니, 거기서 직접 승인합니다.
  • 새 팀원은 리더의 권한 모드로 시작합니다(bypassPermissions 포함). 만들 때 팀원마다 다른 모드를 줄 수 없습니다 — 리더를 위험한 모드로 띄우면 팀원도 같다는 뜻입니다.
  • 권한 요청이 너무 자주 리더에게 올라오면, 팀원을 띄우기 전에 자주 쓰는 작업을 권한 설정에서 미리 허용해 둡니다.
  • 팀의 품질 관문은 훅으로: TeammateIdle(팀원이 쉬려 할 때), TaskCreated(작업이 만들어질 때), TaskCompleted(작업이 완료 표시될 때). 훅 명령이 종료 코드 2(명령이 끝나며 돌려주는 숫자 — 2는 “막음” 신호)로 끝나면 그 동작을 막고 되돌려 보낼 수 있습니다.
강제 장치는 적게 (원문) 어느 범위든 강제 목록은 작게 유지하세요. 훅과 deny 규칙은 가끔 엉뚱할 때도 작동하고, 누군가 하나하나 관리해야 합니다. 원문은 "40개쯤 되었다면 대부분은 Claude 가 스스로 판단해도 될 선호일 것"이라고 말합니다. 반대로 선호일 뿐인 것에 훅을 걸었다면 지우고 Claude 에게 맡깁니다.
🔧 개발자용 참고 — 설정 예와 누구에게 적용되나
// .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 도 잡지만, 그 파일을 여는 스크립트는 못 잡습니다. WebFetch deny 는 샌드박스가 켜져 있지 않으면 같은 주소로의 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」를 봅니다.

보안 — 비밀 정보와 승인

세컨드 브레인은 여러 에이전트가 함께 읽는 곳이라, 거기 적힌 것은 그 팀의 모든 에이전트에게 보인다고 생각해야 합니다. 원문 곳곳의 주의 사항을 모으면 아래와 같습니다.

세컨드 브레인 팀 전원이 읽는 곳 → 비밀은 넣지 않는다 메모리 파일 비밀 정보 거르기 받아 온 저장소 바깥 불러오기 · 서버 승인 MCP 서버 믿을 수 있는지 · 키 분리 다른 에이전트 메시지 승인 대신 불가
들어오는 길마다 원문이 정해 둔 확인 장치가 있습니다.
위험원문의 대책
메모리에 비밀 정보가 저장됨메모리 도구: 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)

APPENDIX

부록 — 출처 · 받지 않은 자료 · 용어 대조

이 가이드가 근거로 쓴 원문 18쪽과, 일부러 받지 않은 자료, 원문 영어 용어와 이 가이드 한국어 용어의 대조표입니다.

이 장에서 배우는 것
  • 어느 장이 어느 원문을 근거로 했는지
  • 이 가이드가 다루지 않은 것(더 알아볼 곳)
  • 원문을 직접 읽을 때 만나는 영어 용어의 뜻

출처 — 원문 18쪽 (수집일 2026-11-10)

하나의 공식 문서가 있는 주제가 아니어서, Anthropic 공식 문서(Claude Code·Claude API·Claude 도움말·엔지니어링 블로그)와 오픈 표준(AGENTS.md·MCP), 세컨드 브레인 원 개념(Forte Labs)과 레퍼런스(위키백과), 안드레 카파시의 「LLM Wiki」 아이디어 글(2026-11-10 사용자 요청으로 추가)을 모아 구성했습니다. 제품 문서는 자주 바뀌므로 화면·명령이 다르면 원문 최신판을 따르세요.

원문주소종류다룬 내용쓴 장
claude-code_memorycode.claude.com/docs/en/memory공식·표준CLAUDE.md(사람이 쓰는 지침)·자동 메모리, 범위(조직·프로젝트·개인), 불러오는 순서, rulesch03, ch05, ch09
claude-code_sub-agentscode.claude.com/docs/en/sub-agents공식·표준서브에이전트 정의 파일, 자기 컨텍스트, 도구 제한, 지속 메모리ch05, ch06
claude-code_agent-teamscode.claude.com/docs/en/agent-teams공식·표준에이전트 팀 — 리더·팀원, 공유 작업 목록, 서로 메시지, 팀원이 받는 맥락ch00, ch06, ch09
claude-code_skillscode.claude.com/docs/en/skills공식·표준스킬 — 절차·지식을 폴더로 묶어 필요할 때만 불러옴ch04
claude-code_mcpcode.claude.com/docs/en/mcp공식·표준MCP 서버 연결, 범위(로컬·프로젝트·사용자), 팀 공유 .mcp.jsonch08
claude-code_best-practicescode.claude.com/docs/en/best-practices공식·표준컨텍스트 관리, CLAUDE.md 잘 쓰기, 여러 세션 병렬 작업ch01, ch03, ch04, ch09
claude-api_memory-toolplatform.claude.com/docs/en/agents-and-tools/tool-use/memory-tool공식·표준메모리 도구 — 대화를 넘어 파일로 기억, 멀티 세션 작업 패턴ch01, ch05, ch07, ch09
claude-help_projectssupport.claude.com/en/articles/9517075-what-are-projects공식·표준Claude 프로젝트 — 지식·지침을 묶어 팀과 공유 (코딩 없이)ch08, ch09
anthropic_context-engineeringwww.anthropic.com/engineering/effective-context-engineering-for-ai-agents공식·표준컨텍스트 엔지니어링, 컨텍스트 썩음, 구조화된 메모, 서브에이전트 구조ch00, ch01
anthropic_multi-agent-researchwww.anthropic.com/engineering/multi-agent-research-system공식·표준오케스트레이터·작업자 구조, 위임할 때 줄 것, 기억 저장, 비용ch06, ch07
anthropic_building-effective-agentswww.anthropic.com/engineering/building-effective-agents공식·표준워크플로와 에이전트, 단순하게 시작, 패턴들ch06
anthropic_long-running-harnesswww.anthropic.com/engineering/effective-harnesses-for-long-running-agents공식·표준긴 작업 — 진행 기록 파일·기능 목록·git 으로 세션 사이 인수인계ch07
agents-mdagents.md공식·표준AGENTS.md — 여러 에이전트 도구가 함께 읽는 오픈 형식ch03
mcp_intromodelcontextprotocol.io/docs/getting-started/intro공식·표준MCP — AI 앱과 외부 시스템을 잇는 표준 (USB-C 비유)ch08
fortelabs_basbfortelabs.com/blog/basboverview공식·표준세컨드 브레인 원 개념, CODE(모으기·정리·추리기·표현)ch00, ch02
fortelabs_parafortelabs.com/blog/para공식·표준PARA(프로젝트·영역·자원·보관) 정리법ch02
karpathy_llm-wikigist.github.com/karpathy/442a6bf555914893e9891c11519de94f블로그안드레 카파시의 LLM 위키 — AI 가 원문을 읽어 마크다운 위키를 쌓고 고침(원문·위키·스키마 3층, 넣기·묻기·점검, index.md·log.md)ch02
wikipedia_pkmen.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 · LintLLM 위키 · 넣기 · 묻기 · 점검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)