시작 전 준비 — 무엇을 쓸지 고르고 폴더 하나 만들기
완전 가이드가 “세컨드 브레인은 무엇이고 왜 필요한가”를 설명한다면, 활용편은 “내 에이전트 팀이 같은 목표와 맥락을 갖게 하려면 무엇을 어떤 순서로 만드나”를 따라 해 보는 문서입니다. 이 준비에서는 쓸 도구를 고르고, 팀이 함께 읽을 폴더 하나를 만듭니다.
- 1. 팀 목표 한 장 쓰고 모든 세션이 읽게 하기 — 첫 결과
- 2.
/init으로 프로젝트 지침 파일 시작하고 짧게 다듬기 - 3. PARA 로 지식 창고 폴더 만들기
- 4. 개인 팀 — 나만의 공통 선호를 사용자 범위에 적기
- 5. 역할 하나 정의하기 — 검토 담당 서브에이전트
- 6. 에이전트 팀 띄우고 모두 같은 맥락인지 확인하기
- 7. 반복 절차를 스킬로 — 팀 전원이 같은 방법으로 (선택)
- 8. 인수인계 노트로 여러 세션에 걸친 일 이어 가기 (선택)
- 9. 회사 팀 — 공용 도구 연결(MCP) · 프로젝트 공유 (선택)
- 10. 막힘 해결 — 에이전트가 지침·기억을 안 따를 때
예상 소요 시간: 15~20분 (설치 시간 제외)
준비물과 완료 기준을 읽고 따라 하기에서 도구 하나를 고른 뒤 폴더를 만드세요. 그다음 실습 1 → 실습 2 → 실습 3 순서로 첫 결과를 만들고, 실습 4~실습 8에서 실제 작업을, 실습 9~실습 10에서 회사 팀과 막힘 해결을 다룹니다.
준비물과 완료 기준
- Claude 계정과 아래 둘 중 하나: 파일을 다루는 코딩 도구 Claude Code, 또는 코딩 없이 쓰는 Claude 프로젝트(claude.ai 의 Projects).
- 세컨드 브레인(이 가이드에서는 에이전트 팀이 함께 읽고 쓰는 공용 기억 파일 묶음)을 둘 폴더를 만들 수 있는 내 컴퓨터. Claude 프로젝트만 쓴다면 올릴 문서를 모아 둘 폴더면 충분합니다.
- 이 팀이 할 일 한 문장. 예시: “이번 분기 개인 블로그 글 12편 발행” 또는 “우리 팀 신규 입사자 안내서 정리”.
쓸 도구를 하나 골랐고, 팀 이름이 붙은 빈 폴더(또는 빈 Claude 프로젝트)가 있으며, Claude Code 라면 그 폴더에서 /memory 를 실행해 지침 파일 목록을 본 적이 있으면 완료입니다.
따라 하기
1단계 · 도구 하나 고르기
폴더 안의 파일을 직접 읽고 쓰는 도구입니다. 매 세션은 빈 컨텍스트(에이전트가 한 번에 보고 있는 글 전체)로 시작하지만, 사람이 쓴 지침 파일 CLAUDE.md 와 Claude 가 스스로 적는 자동 메모리가 세션마다 다시 읽혀 기억을 이어 줍니다. 서브에이전트·에이전트 팀으로 역할을 나눌 수 있어 “팀”을 꾸리기에 가장 알맞습니다.
claude.ai 에서 쓰는, 대화 기록과 지식 창고를 따로 가진 작업 공간입니다. 문서·글·코드 파일을 프로젝트 지식에 올리면 그 프로젝트 안의 대화가 그 내용을 배경으로 씁니다. 프로젝트 지침으로 “격식 있는 말투”나 “특정 역할의 관점” 같은 요청을 줄 수 있습니다. 무료 계정도 쓸 수 있고(프로젝트 최대 5개), 다른 사람과 공유는 Team·Enterprise 요금제에서만 됩니다.
확인: 두 갈래 중 어느 쪽으로 갈지 정했습니다. 다른 코딩 도구도 함께 쓴다면 아래 접힌 상자를 봅니다.
다른 코딩 도구와 같이 쓴다면 — AGENTS.md
AGENTS.md 는 여러 코딩 에이전트가 함께 읽는 열린 형식의 지침 파일입니다(“에이전트용 README”). Claude Code 는 작업 폴더나 그 위에 CLAUDE.md·.claude/CLAUDE.md·CLAUDE.local.md 가 없을 때 AGENTS.md 를 프로젝트 지침으로 읽습니다(v2.1.277 이상). 둘 다 두려면 CLAUDE.md 첫 줄에 @AGENTS.md 를 넣어 가져오는 방법이 원문에 있습니다. 자세히: 3장 AGENTS.md.
2단계 · 설치하고 로그인하기
설치와 로그인 방법은 이 가이드의 원문에 없으므로 각 제품의 공식 안내를 따릅니다. 회사 컴퓨터라면 설치 가능 여부를 먼저 담당 부서에 확인하세요.
- Claude Code: 설치 후 터미널(명령을 글자로 입력하는 프로그램. macOS 는 「터미널」 앱)에서
claude --version을 실행하면 버전이 나옵니다. 이 가이드의 일부 기능은 버전 조건이 있어(예:AGENTS.md직접 읽기는 v2.1.277 이상) 숫자를 메모해 두면 좋습니다. - Claude 프로젝트: claude.ai 에 로그인한 뒤 화면에서 Projects(프로젝트)를 찾습니다. 새 버전 프로젝트는 일부 사용자에게 베타로 배포 중이어서 화면이 다를 수 있습니다.
확인: Claude Code 는 버전 숫자가 나오고 간단한 질문에 답합니다. Claude 프로젝트는 프로젝트 목록 화면이 열립니다.
3단계 · 팀마다 폴더 하나 만들기
개인 일과 회사 일을 섞지 않도록 팀마다 폴더(또는 프로젝트)를 따로 만듭니다. 폴더 이름은 예시입니다.
my-brain/ ← 개인 팀의 세컨드 브레인 (예시 이름)
work-brain/ ← 회사 팀의 세컨드 브레인 (예시 이름)
처음에는 개인 팀 폴더 하나로만 실습 1~8을 끝까지 해 보세요. 회사 팀은 같은 순서를 반복하되, 공유 범위와 보안만 달라집니다(실습 9, 9장 나누는 법). Claude 프로젝트 갈래라면 같은 이름으로 프로젝트를 두 개 만듭니다.
확인: 팀 이름이 붙은 빈 폴더(또는 빈 프로젝트)가 있습니다.
4단계 · 그 폴더에서 세션 열고 /memory 보기
Claude Code 갈래만 해당합니다. 터미널에서 my-brain 폴더로 이동한 뒤(예: cd my-brain) claude 를 입력해 Claude Code 를 시작하고, 열린 대화 칸에 /memory 를 입력합니다. 이 명령은 사용자 범위와 프로젝트 범위의 지침 파일 위치를 목록으로 보여 주는데, 아직 없는 파일도 목록에 나옵니다. 고르면 편집기로 열리고, 없는 파일이면 먼저 만들어 줍니다.
지금은 아무것도 만들지 말고 목록만 봅니다. 프로젝트 쪽(./CLAUDE.md)은 실습 1·실습 2에서, 사용자 쪽(~/.claude/CLAUDE.md)은 실습 4에서 채웁니다.
/memory 가 보여 주는 내용의 개념도입니다. 실제 배치와 문구는 버전에 따라 다릅니다.확인: 목록에 프로젝트와 사용자 지침 파일 항목이 보입니다. Claude 프로젝트 갈래는 이 단계를 건너뜁니다.
막히면
| 증상 | 해 볼 것 |
|---|---|
| 어느 도구를 골라야 할지 모르겠음 | 파일 폴더를 직접 다루고 역할을 나눈 팀을 원하면 Claude Code, 문서를 올려 대화만 하면 충분하면 Claude 프로젝트입니다. 나중에 바꿔도 목표 파일·폴더 구성은 그대로 다시 씁니다. |
claude --version 이 안 됨 | 설치가 끝나지 않았거나 터미널을 새로 열어야 할 수 있습니다. 공식 설치 안내의 확인 방법을 따릅니다. |
| Projects 메뉴가 안 보임 / 화면이 설명과 다름 | 새 버전 프로젝트가 단계적으로 배포 중이라 계정마다 화면이 다를 수 있습니다. 화면에서 Projects 를 찾습니다. |
| 회사 폴더를 어디에 둘지 모르겠음 | 회사 지침은 저장소(프로젝트 파일과 그 변경 이력을 담아 팀이 함께 받는 폴더)로 팀과 공유하거나 관리자가 조직 전체에 배포할 수 있습니다. 먼저 9장 회사 팀을 읽고 담당자와 정합니다. |
다음에 할 것
실습 1에서 이 폴더에 팀 목표 한 장을 쓰고, 모든 세션이 그것을 읽게 합니다. 개념이 먼저 궁금하면 0장 전체 그림과 용어표를 봅니다.
- Claude Code(파일·팀 기능) 또는 Claude 프로젝트(코딩 없이) 중 하나를 고릅니다.
- 설치·로그인은 공식 안내를 따릅니다.
- 개인 팀·회사 팀은 폴더(프로젝트)를 따로 만들고, 개인 팀부터 연습합니다.
- Claude Code 는
/memory로 지침 파일 자리를 먼저 확인합니다.
출처: sources/raw/claude-code_memory.md(CLAUDE.md vs auto memory, Choose where to put CLAUDE.md files, View and edit with /memory, AGENTS.md), claude-help_projects.md, agents-md.md. 폴더 이름·팀 목표 문장·학습 순서는 이 활용편의 예시와 제안입니다.
첫 결과 — 팀 목표 한 장 쓰고 모든 세션이 읽게 하기
팀의 모든 에이전트가 같은 목표를 갖게 하는 가장 짧은 길은, 목표를 파일 한 장에 쓰고 매 세션 시작 때 자동으로 읽히는 지침 파일이 그 파일을 가져오게 하는 것입니다. 이 실습이 끝나면 새 세션을 열 때마다 에이전트가 목표를 먼저 알고 시작합니다.
- 목표·완료 기준·하지 않을 일을 담은 목표 파일 한 장을 씁니다.
CLAUDE.md의@경로가져오기로 그 파일이 매 세션 함께 읽히게 합니다.- 새 세션에서 에이전트가 목표를 알고 있는지 확인합니다.
예상 소요 시간: 15~20분
준비물을 확인하고 따라 하기 1~4단계를 차례로 하세요. 가져오기가 안 되는 것 같으면 막히면에서 경로·공백·승인 창을 확인합니다. Claude 프로젝트 갈래는 4단계의 탭을 봅니다.
준비물과 완료 기준
- 시작 전 준비에서 만든 팀 폴더(예시 이름
my-brain/) 또는 빈 Claude 프로젝트. - 이 팀이 이번에 끝내고 싶은 일 한두 개. 예시: “이번 분기 블로그 글 12편 발행”.
새로 연 세션에서 “이 팀의 목표가 뭐야?”라고 물었을 때, 목표 파일에 쓴 목표와 완료 기준을 그대로 말하면 완료입니다. Claude Code 는 /context all 의 Memory files 목록에 CLAUDE.md 가 보여야 합니다.
GOAL.md 는 이 가이드가 붙인 예시 이름입니다.따라 하기
1단계 · 목표를 “프로젝트” 단위로 적기
PARA(정보를 프로젝트·영역·자원·보관 네 칸으로 나누는 정리법 — 실습 3)를 만든 티아고 포르테(Tiago Forte)는 프로젝트를 “어떤 목표를 갖고 맡는 짧은 기간의 일”로, 영역(Area, 끝나지 않고 계속 돌봐야 하는 책임)과 구분합니다. “마케팅”, “건강”은 끝나지 않는 영역이라 진행 상황을 알 수 없고, 그 안을 끝이 있는 프로젝트로 쪼개야 얼마나 남았는지와 장기 목표와의 연결이 보인다고 말합니다.
그래서 목표 파일에는 끝이 있는 프로젝트를 적습니다. 종이에 먼저 써 봅니다.
- 블로그 운영
- 신규 입사자 관리
- 12월 31일까지 블로그 글 12편 발행
- 다음 달 입사자 3명용 안내서 완성
확인: 적은 목표마다 “언제 끝났다고 말할 수 있나”가 한 줄로 답해집니다.
2단계 · 목표 파일 한 장 만들기
팀 폴더에 GOAL.md(예시 이름)를 만들고 아래 양식을 채웁니다. 양식은 이 가이드의 제안이며, 원문 기준의 핵심은 “검증할 수 있을 만큼 구체적으로, 머리글과 목록으로 짧게”입니다.
# 팀 목표 (예시)
## 지금 프로젝트
- 블로그 글 12편 발행 — 기한 12/31
## 완료 기준
- 글마다 1,500자 이상, 맞춤법 검사 통과, 발행 링크를 진행 기록(claude-progress.txt, 실습 8)에 적음
## 하지 않을 일
- 발행 버튼은 사람이 누른다. 에이전트는 초안까지만.
## 독자·말투
- 독자: 처음 배우는 직장인 / 말투: 존댓말, 짧은 문장
한 장(수십 줄)을 넘기지 마세요. 지침 파일은 짧을수록 잘 따르고, 가져온 파일도 가져온 쪽과 함께 매번 읽히므로 컨텍스트 비용이 그대로 듭니다. 배경 자료는 실습 3의 폴더에 두고 필요할 때 찾게 합니다.
확인: 파일을 처음 보는 동료가 읽어도 “무엇을, 언제까지, 어디까지” 할지 압니다.
3단계 · CLAUDE.md 에서 목표 파일 가져오기
같은 폴더에 CLAUDE.md 를 만들고(/memory 에서 프로젝트 항목을 골라도 됩니다) 아래처럼 씁니다. CLAUDE.md 는 @경로 문법으로 다른 파일을 가져올 수 있고, 가져온 파일은 펼쳐져 함께 컨텍스트에 들어갑니다.
# 이 팀이 일하는 방식
- 모든 작업 전에 아래 팀 목표를 기준으로 판단한다.
- 팀 목표 @GOAL.md
상대 경로는 작업 폴더가 아니라 이 CLAUDE.md 가 있는 위치를 기준으로 풀립니다. 가져온 파일이 다시 다른 파일을 가져올 수 있지만 최대 네 단계까지입니다.
확인: CLAUDE.md 안에 @GOAL.md 가 백틱(` 기호 — 마크다운에서 코드 표시)·따옴표 없이 들어 있습니다.
4단계 · 새 세션에서 목표를 아는지 확인하기
- 세션을 끝내고 같은 폴더에서 새로 시작매 세션은 빈 컨텍스트로 시작하므로 “파일만 보고 아는지”가 확인됩니다.
/context all실행Memory files 목록에 이 폴더의CLAUDE.md가 있는지 봅니다.- 예시 질문 보내기“파일을 바꾸지 말고, 이 팀의 목표와 완료 기준을 말해 줘.”
Claude 프로젝트에는 @ 가져오기 설명이 원문에 없습니다. 대신 GOAL.md 를 프로젝트 지식에 올리고, 프로젝트 지침에 “모든 답은 프로젝트 지식의 팀 목표를 기준으로”라고 씁니다(지침 문장은 예시). 그 프로젝트 안에서 새 대화를 열어 같은 질문을 보냅니다. 올리는 화면 위치는 화면에서 찾습니다.
확인: 답이 목표 파일의 기한·완료 기준·하지 않을 일을 그대로 말합니다. 다르게 말하면 막히면으로 갑니다.
막히면
| 증상 | 해 볼 것 |
|---|---|
Memory files 에 CLAUDE.md 가 없음 | 세션을 그 폴더(또는 그 아래)에서 시작했는지 봅니다. 작업 폴더와 그 위 폴더의 CLAUDE.md 만 시작 때 읽히고, 아래 폴더의 것은 그 폴더 파일을 다룰 때 읽힙니다. |
| 목표를 모름 (CLAUDE.md 는 보임) | @GOAL.md 가 백틱·코드 블록·따옴표 안에 있지 않은지, 상대 경로가 CLAUDE.md 위치 기준으로 맞는지 봅니다. |
| 가져오기 승인 창이 떴음 | 작업 폴더 밖(예: 홈 폴더)의 파일을 가져오면 처음 한 번 승인 창이 뜹니다. 거절하면 그 가져오기는 꺼진 채로 남고 창도 다시 뜨지 않습니다. |
| 목표를 알지만 따르지 않음 | 지침 파일은 강제 설정이 아니라 맥락입니다. 문장을 더 구체적으로 바꾸고, 반드시 막아야 할 일은 훅으로 옮깁니다 — 실습 10. |
가져오기의 세부 규칙 (원문)
절대 경로와 상대 경로를 모두 쓸 수 있습니다. 가져오기 해석은 마크다운 코드 조각과 코드 블록을 건너뜁니다. 프로젝트 범위 파일에서 작업 폴더 밖을 가리키는 가져오기는 “외부 가져오기”로 보고 처음 한 번 승인 창을 띄웁니다 — 다른 사람이 공유 프로젝트에 넣은 파일로부터 나를 보호하려는 것입니다. 사용자 범위 파일(~/.claude/CLAUDE.md)의 가져오기는 창 없이 읽힙니다(데스크톱 Cowork 세션 제외). 가져오기는 정리를 돕지만 컨텍스트 비용을 줄이지는 않습니다. 자세히: 3장 가져오기.
다음에 할 것
목표 파일이 생겼으니 실습 2에서 /init 으로 지침 파일 나머지를 채우고 짧게 다듬습니다. 이 목표는 실습 5의 서브에이전트와 실습 6의 팀원에게도 그대로 전해집니다 — 둘 다 시작할 때 CLAUDE.md 를 읽기 때문입니다. 개념: 2장 목표 파일.
- 목표는 끝이 있는 프로젝트 단위로, 완료 기준과 하지 않을 일까지 한 장에 씁니다.
CLAUDE.md에@GOAL.md한 줄을 넣으면 매 세션 함께 읽힙니다.- 상대 경로는 가져오는 파일 기준, 공백은 역슬래시, 백틱·따옴표 안은 가져오지 않습니다.
- 새 세션에서 목표를 물어 확인합니다. Claude 프로젝트는 프로젝트 지식에 올립니다.
출처: sources/raw/claude-code_memory.md(Import additional files, How CLAUDE.md files load, Write effective instructions, Set up a project CLAUDE.md), fortelabs_para.md(4 Categories, The Power of Organizing By Project), claude-help_projects.md(Project knowledge), claude-code_sub-agents.md(What loads at startup), claude-code_agent-teams.md(Context and communication). 목표 파일 이름·양식·질문 문장은 이 활용편의 예시입니다.
/init 으로 프로젝트 지침 파일 시작하고 짧게 다듬기
프로젝트 지침 파일 CLAUDE.md 는 팀원 모두가 공유하는 “항상 읽히는 층”입니다. 처음부터 쓰지 않아도 /init 이 초안을 만들어 주고, 그 뒤의 일은 대부분 줄을 지우는 것입니다. 이 실습에서는 초안을 만들고, 매 세션 필요한 사실만 남깁니다.
/init으로CLAUDE.md초안을 만들거나, 이미 있으면 개선 제안을 받습니다.- “에이전트가 스스로 알아낼 수 없는 것만” 남기는 기준으로 줄을 지웁니다.
/context all로 실제로 읽히는지 확인합니다.
예상 소요 시간: 20분
준비물과 완료 기준
- 실습 1을 마친 팀 폴더 —
CLAUDE.md에@GOAL.md가 들어 있는 상태. 실습 1을 건너뛰었다면 빈 폴더여도 됩니다. - Claude Code. (Claude 프로젝트 갈래는 이 실습 대신 프로젝트 지침 칸을 같은 기준으로 짧게 다듬습니다.)
CLAUDE.md 가 200줄 아래이고, 남은 줄마다 “이것이 없으면 에이전트가 매번 틀리거나 다시 물어볼 것”이라고 말할 수 있으며, 새 세션의 /context all → Memory files 에 보이면 완료입니다.
따라 하기
1단계 · 이 파일이 어느 범위인지 알기
폴더 안의 ./CLAUDE.md(또는 ./.claude/CLAUDE.md)는 프로젝트 범위입니다. 저장소(프로젝트 파일과 그 변경 이력을 담은 폴더 — git 으로 팀원이 같은 내용을 받음)로 공유하면 팀원 모두가 같은 파일을 받습니다. 그래서 여기에는 개인 취향이 아니라 이 팀 모두에게 해당하는 기준을 씁니다. 내 취향은 실습 4의 사용자 범위로 갑니다.
| 범위 | 위치 | 누구와 공유 |
|---|---|---|
| 프로젝트 | ./CLAUDE.md · ./.claude/CLAUDE.md | 저장소를 받는 팀원 |
| 로컬 | ./CLAUDE.local.md | 나만 (이 프로젝트) |
| 사용자 | ~/.claude/CLAUDE.md | 나만 (모든 프로젝트) |
확인: 지금 다듬을 파일이 팀 공용(프로젝트 범위)이라는 것을 압니다.
2단계 · /init 실행하기
팀 폴더에서 세션을 열고 /init 을 입력합니다. Claude 가 폴더를 살펴 발견한 명령·규칙을 담은 시작용 CLAUDE.md 를 만듭니다. 이미 CLAUDE.md 가 있으면 덮어쓰지 않고 개선을 제안합니다 — 실습 1에서 만든 @GOAL.md 줄은 그대로 남습니다.
세컨드 브레인 폴더처럼 코드가 없는 폴더라면 초안이 짧거나 일반적일 수 있습니다. 그럴수록 3단계에서 “Claude 가 스스로 알아내지 못할 것”을 사람이 채웁니다.
확인: CLAUDE.md 가 생겼거나, 기존 파일에 대한 개선 제안이 나왔습니다. 제안은 읽고 고른 것만 받아들입니다.
질문을 주고받으며 만드는 /init (환경 변수)
/init 전에 환경 변수 CLAUDE_CODE_NEW_INIT 를 1 로 두면 여러 단계 흐름으로 바뀝니다. 무엇을 만들지(CLAUDE.md·스킬·훅) 묻고, 서브에이전트로 폴더를 살핀 뒤 후속 질문으로 빈 곳을 채우고, 파일을 쓰기 전에 검토할 제안을 보여 줍니다. 이 흐름에서 개인 옵션을 고르면 CLAUDE.local.md 를 만들고 .gitignore 에 넣는 일도 해 줍니다.
3단계 · 남길 줄과 지울 줄 가르기
CLAUDE.md 는 매 세션 읽히므로 한 줄 한 줄이 관련 없는 작업에서도 에이전트의 주의를 조금씩 씁니다. 원문의 기준은 “에이전트가 스스로 알아낼 수 없는 것만”입니다.
문장은 확인할 수 있을 만큼 구체적으로 바꿉니다. 원문의 예: “코드를 잘 정리해” 대신 “2칸 들여쓰기”, “테스트해” 대신 “커밋 전 npm test 실행”. 세컨드 브레인 폴더라면 예시로 이렇게 바꿉니다: “글을 잘 써” → “제목은 30자 이내, 본문은 존댓말”.
확인: 남은 줄마다 남긴 이유를 한마디로 말할 수 있습니다.
4단계 · 머리글로 묶고 200줄 아래로
관련 지침을 마크다운 머리글과 목록으로 묶습니다. 원문의 짧은 CLAUDE.md 예는 명령 · 규칙 · 주의할 점 세 덩어리입니다. 세컨드 브레인용으로 바꾸면 다음과 같습니다(예시).
# 팀 목표
- @GOAL.md
# 확인 방법
- 글 초안은 drafts/ 에, 끝나면 claude-progress.txt 에 한 줄 기록
# 규칙
- 출처 없는 숫자는 쓰지 않는다
- 발행은 사람이 한다. 에이전트는 초안까지
# 주의할 점
- archive/ 의 옛 글 말투를 따라 하지 않는다
<!-- 사람용 메모: 매달 한 번 이 파일을 점검 -->
블록 단위 HTML 주석(<!-- -->)은 컨텍스트에 넣기 전에 지워지므로, 사람용 메모를 토큰(AI 가 읽는 글의 양을 세는 단위) 비용 없이 남길 수 있습니다.
확인: 파일이 200줄 아래이고 서로 어긋나는 지시가 없습니다. 두 지시가 충돌하면 Claude 가 아무 쪽이나 고를 수 있습니다.
5단계 · 새 세션에서 읽히는지 확인하기
세션을 새로 열고 /context all 을 실행해 Memory files 목록에 이 CLAUDE.md 가 있는지 봅니다. 그다음 예시 질문 “파일은 바꾸지 말고, 이 폴더에서 일할 때 지켜야 할 규칙을 세 줄로 말해 줘”를 보냅니다.
/context 만 치면 이 목록이 접힙니다.확인: 목록에 파일이 보이고, 답이 남긴 규칙과 같습니다. 화면 흉내는 개념도이며 실제 표시는 버전마다 다릅니다.
막히면
| 증상 | 해 볼 것 |
|---|---|
| 시작할 때 길이 경고가 뜸 | 권장 길이를 넘은 파일이 있거나, 각각은 괜찮아도 합계가 한도를 넘으면 시작 때와 /status 에서 경고가 뜹니다. 가져온 파일·규칙 파일도 따로 셉니다. 일부에만 해당하는 규칙은 .claude/rules/ 경로 규칙으로, 절차는 스킬로 옮깁니다. |
| 무엇을 지울지 모르겠음 | /doctor 가 코드에서 알아낼 수 있는 내용(폴더 구조·의존성 목록 등)을 지우자고 제안합니다. 함정·이유·기본값과 다른 약속은 남기라고 합니다. |
| 오래되거나 서로 어긋나는 지시가 의심됨 | /doctor prompt-audit 이 옛 모델용 지시·없는 파일 언급·서로 어긋나는 파일을 찾아 수정안을 보고합니다. 적용하라고 할 때까지 파일은 바뀌지 않습니다(v2.1.283 이상). |
| “IMPORTANT” 를 붙여도 무시함 | 파일이 길어져 줄이 묻혔거나, 예외 없이 지켜야 하는 규칙이라 훅으로 가야 하는 경우입니다 — 실습 10. |
다음에 할 것
지침 파일이 가벼워졌으니 실습 3에서 자료를 담을 폴더(지식 창고)를 만듭니다. 개념과 범위 표 전체는 3장 잘 쓰는 법·3장 범위에 있습니다.
- 프로젝트 범위
CLAUDE.md는 팀 공용 — 개인 취향은 넣지 않습니다. /init은 초안을 만들고, 이미 있으면 개선만 제안합니다.- 에이전트가 스스로 알 수 없는 것만, 구체적으로, 머리글로 묶어 200줄 아래로.
- 새 세션
/context all의 Memory files 로 확인합니다.
출처: sources/raw/claude-code_memory.md(Set up a project CLAUDE.md, Write effective instructions, Audit your instruction files, How CLAUDE.md files load, My CLAUDE.md is too large), claude-code_best-practices.md(Keep CLAUDE.md short). 세컨드 브레인용 CLAUDE.md 예와 질문 문장은 이 활용편의 예시입니다.
PARA 로 지식 창고 폴더 만들고 LLM 위키 방식으로 굴리기
목표와 지침은 매 세션 읽히지만, 자료까지 전부 지침 파일에 넣으면 컨텍스트가 금방 찹니다. 자료는 폴더에 두고, 에이전트가 필요할 때 찾아 읽게 하는 편이 낫습니다. 이 실습에서는 PARA 네 칸으로 팀의 지식 창고 폴더를 만들고, 에이전트가 그 폴더를 길잡이 삼아 찾도록 지침 한 덩어리를 붙입니다. 이어서 자원 칸 안에 안드레 카파시의 LLM 위키(AI 가 원문을 읽고 마크다운 위키를 직접 쓰고 고쳐 가는 지식 창고 방식)를 하나 차려, 원문을 넣으면 AI 가 위키를 쓰고 고치게 해 봅니다.
- PARA(Projects·Areas·Resources·Archives — 프로젝트·영역·자원·보관) 네 폴더와 임시 보관함을 만듭니다.
- 기존 자료를 날짜 붙은 보관 폴더로 한 번에 옮겨 깨끗하게 시작합니다.
- “어디에 넣을까” 세 질문을 지침 파일에 적어, 에이전트도 같은 규칙으로 넣고 찾게 합니다.
- LLM 위키의 세 층(원문 · 위키 · 스키마)을 폴더와 지침으로 만들고, 넣기 · 묻기 · 점검을 한 번씩 시켜 봅니다.
예상 소요 시간: PARA 20~25분 + LLM 위키 25~30분
준비물을 확인하고 따라 하기 1~3단계로 폴더를 만드세요. 4단계는 에이전트에게 규칙을 알려 주는 단계이고, 5단계로 실제로 넣고 찾는지 확인합니다. 정리를 AI 에게 더 맡기고 싶으면 LLM 위키 방식으로 굴리기 6~10단계를 이어서 합니다. 폴더 구성은 이 가이드의 제안입니다.
준비물과 완료 기준
- 실습 1·실습 2를 마친 팀 폴더(예시 이름
my-brain/) —CLAUDE.md와 목표 파일이 있는 상태. - 팀이 쓸 자료 몇 개. 예시: 참고 글 링크 모음, 지난 회의 메모, 예전 초안.
- LLM 위키 단계용으로 위키에 넣을 원문 한두 편(글·회의록 같은 텍스트 파일이 쉽습니다).
폴더 다섯 개(보관함 포함)가 있고, 새 세션에 “이 메모를 알맞은 곳에 넣어 줘”라고 했을 때 세 질문 순서대로 판단해 넣으며, “○○ 관련 자료 찾아 줘”에 폴더를 뒤져 경로를 답하면 PARA 부분 완료입니다. LLM 위키 부분은 원문 하나를 넣었을 때 위키에 요약 쪽이 생기고 index.md·log.md 가 고쳐지며 원문 파일은 그대로이면 완료입니다.
따라 하기
1단계 · 기존 자료를 날짜 붙은 보관 폴더로 옮기기
원문이 꼽는 가장 큰 걸림돌은 “기존 자료를 전부 분류해야 한다”는 생각입니다. 대신 기존 파일을 모두 오늘 날짜가 붙은 Archive 폴더로 옮기라고 권합니다(1분이면 됩니다). 지우는 것이 아니라 “타임캡슐”이고, 필요할 때 꺼내 쓰면 됩니다.
my-brain/
└── archive/
└── 2026-11-10 이전 자료/ ← 예시 이름. 오늘 날짜로
확인: 팀 폴더에 CLAUDE.md·목표 파일·archive/ 말고는 아무것도 없습니다.
2단계 · 네 칸과 보관함 만들기
아래처럼 폴더를 만듭니다. 폴더 이름은 모두 예시이며, 영어·한국어 어느 쪽이든 팀 안에서 하나로 통일합니다. inbox/ 는 원문의 “Inbox”(제자리에 넣기 전 잠시 쌓아 두는 곳)입니다.
my-brain/
├── CLAUDE.md
├── GOAL.md
├── inbox/ ← 새로 들어온 것 (잠시)
├── projects/ ← 목표 파일의 프로젝트마다 하위 폴더 하나
│ └── blog-12-posts/
├── areas/ ← 예: health/, finance/
├── resources/ ← 예: writing-tips/
└── archive/
원문은 “네 개의 최상위 폴더, 그 안에 각 프로젝트·영역·자원·보관마다 몇 개 안 되는 하위 폴더”를 말합니다. 하위 폴더를 미리 많이 만들지 않습니다.
확인: projects/ 아래 폴더 이름이 실습 1 목표 파일의 프로젝트와 하나씩 맞습니다.
3단계 · 세 질문으로 첫 자료 넣어 보기
자료 하나를 손으로 넣어 봅니다. 원문의 세 질문을 차례로 묻습니다.
확인: 넣은 자료가 어느 질문에서 자리를 찾았는지 말할 수 있습니다.
4단계 · 에이전트에게 규칙만 알려 주기
자료 내용은 지침 파일에 넣지 않습니다. 원문은 Claude Code 가 CLAUDE.md 는 처음부터 컨텍스트에 넣고, 나머지 파일은 검색 도구로 필요한 순간에 찾아 읽는 방식(just in time — 그때그때 불러오기)을 쓴다고 설명합니다. 이때 폴더 구조·이름 규칙·날짜 같은 정보가 에이전트에게 “이 파일이 무엇인지” 알려 주는 신호가 됩니다.
그래서 CLAUDE.md 에는 폴더 목록이 아니라 넣고 찾는 규칙만 몇 줄 덧붙입니다(예시).
# 자료 넣고 찾기
- 새 자료는 inbox/ 에 넣는다. 정리는 내가 요청할 때만.
- 정리할 때는 "어느 프로젝트 → 영역 → 자원" 순서로 묻고, 셋 다 아니면 archive/ 로.
- projects/ 하위 폴더 이름은 GOAL.md 의 프로젝트 이름과 같게.
- 자료가 필요하면 먼저 projects/<지금 프로젝트>/ 를 찾는다.
- 파일을 지우지 않는다. 끝난 것은 archive/ 로 옮긴다.
원문은 “폴더 구조를 CLAUDE.md 에 설명하지 말라 — Claude 는 저장소를 직접 읽는다”고 합니다. 위 예시가 폴더 이름을 언급하는 것은 구조 설명이 아니라 팀의 약속(어디에 넣고, 무엇을 지우지 않는가)이기 때문입니다. 폴더가 스스로 말해 주는 것은 적지 않습니다.
확인: 추가한 줄이 열 줄 안팎이고, 모두 폴더만 봐서는 알 수 없는 약속입니다.
5단계 · 새 세션에서 넣기·찾기 시켜 보기
새 세션을 열고 예시 프롬프트 두 개를 차례로 보냅니다.
inbox/ 에 있는 메모를 규칙대로 정리할 곳을 제안해 줘. 아직 옮기지는 마.
블로그 글 쓰는 데 참고할 자료가 어디 있는지 찾아서 경로만 알려 줘.
확인: 첫 답이 세 질문 순서로 이유를 대며 자리를 제안하고, 둘째 답이 실제 있는 경로를 말합니다.
LLM 위키 방식으로 굴리기 (6~10단계)
PARA 폴더는 사람이 정리하는 칸입니다. 카파시의 LLM 위키는 한 걸음 더 나가, 원문은 사람이 고르고 위키는 AI 가 전부 쓰고 고치게 합니다. 질문할 때마다 원문 조각을 다시 찾는 대신, 넣을 때 한 번 엮어 두고 계속 최신으로 유지하므로 지식이 쌓입니다. 원문은 일부러 추상적인 아이디어 글이라 폴더 이름·양식은 정해져 있지 않습니다. 아래 이름과 문장은 모두 이 활용편의 예시입니다. 개념: 2장 카파시의 LLM 위키.
6단계 · 원문 폴더 · 위키 폴더 · 목차 · 일지 만들기
자원 칸 안에 위키 하나를 차립니다(위치는 이 가이드의 제안). raw/ 는 원문 층, wiki/ 는 위키 층입니다. index.md(목차)와 log.md(일지)는 원문이 말하는 두 특별 파일로, 처음엔 빈 파일이면 됩니다.
my-brain/
└── resources/
└── llm-wiki/ ← 예시 이름
├── raw/ ← 원문. 읽기만, 고치지 않음
└── wiki/ ← AI 가 쓰고 고침
├── index.md ← 목차: 쪽마다 링크 + 한 줄 요약
└── log.md ← 일지: 덧붙이기만
확인: raw/·wiki/ 두 폴더와 빈 index.md·log.md 가 있습니다.
7단계 · 지침 파일에 스키마(위키 규칙) 몇 줄 적기
원문은 스키마를 “AI 를 그냥 채팅 상대가 아니라 규율 있는 위키 관리자로 만드는 핵심 설정 파일”이라 부르고, 예로 Claude Code 의 CLAUDE.md, Codex 의 AGENTS.md 를 듭니다. 4단계에서 만든 규칙 아래에 이어 적습니다(예시 — 원문의 작업 순서를 옮긴 것).
# LLM 위키 규칙 (resources/llm-wiki/)
- raw/ 파일은 읽기만 한다. 고치거나 지우지 않는다.
- wiki/ 는 네가 쓰고 고친다. 쪽마다 근거가 된 raw/ 파일을 적는다.
- 넣기: 원문을 읽고 핵심을 나와 먼저 이야기한 뒤, 요약 쪽을 쓰고,
관련 쪽을 고치고, index.md 를 고친다.
- 묻기: index.md 부터 읽고 관련 쪽으로 들어가 근거와 함께 답한다.
- 넣기·묻기·점검마다 log.md 끝에 한 줄 덧붙인다 (고치거나 지우지 않음).
머리말은 "## [날짜] ingest | 제목" 처럼 같게 (query · lint 도).
- 점검: 요청하면 어긋남·낡은 주장·외톨이 쪽·빠진 링크를 목록으로 보고한다.
원문은 이 스키마를 사람과 AI 가 함께 시간을 두고 고쳐 간다고 말합니다. 처음부터 완벽하게 쓰지 않습니다.
확인: CLAUDE.md 에 위 규칙이 들어가 있고, 새 세션에서 “위키 규칙을 요약해 줘”라고 하면 세 층과 넣기·묻기·점검을 말합니다.
8단계 · 원문 하나 넣고 “넣기” 시키기
원문 한 편을 raw/ 에 넣고 아래처럼 시킵니다(한국어 예시 프롬프트). 원문 저자는 하나씩 넣으며 요약을 읽고, 무엇을 강조할지 직접 이끄는 쪽을 좋아한다고 합니다.
raw/ 에 새로 넣은 회의록-1110.md 를 위키 규칙대로 넣어 줘.
먼저 핵심 세 가지를 말해 주고, 내가 좋다고 하면 위키를 고쳐.
확인: wiki/ 에 요약 쪽이 생겼고, index.md 에 그 쪽이 한 줄로 올랐으며, log.md 끝에 ## [날짜] ingest | … 항목이 덧붙었고, raw/ 의 원문은 그대로입니다.
9단계 · 질문하고, 좋은 답을 위키로 되돌려 넣기
원문 두 편 이상을 넣은 뒤 위키에 질문합니다. 원문이 꼽는 중요한 깨달음은 좋은 답은 위키에 새 쪽으로 넣을 수 있다는 것입니다 — 비교·분석·새로 찾은 연결이 대화 기록 속에 사라지지 않게 합니다(한국어 예시 프롬프트).
위키만 보고 두 회의의 결정을 비교해 줘. 근거가 된 쪽을 함께 적어.
방금 비교를 wiki/ 에 새 쪽으로 넣고, index.md 와 log.md 도 고쳐 줘.
확인: 첫 답에 근거 쪽 이름이 붙어 있고, 둘째 요청 뒤 wiki/ 에 비교 쪽이 생기며 index.md 와 log.md 에 함께 올라 있습니다.
10단계 · 점검 시키기
때때로 위키 건강 검진을 시킵니다. 아래 점검 항목은 원문의 목록이고, 문장은 한국어 예시입니다.
위키를 점검해 줘. 쪽끼리 어긋나는 내용, 새 원문 때문에 낡은 주장,
들어오는 링크가 없는 쪽, 자주 나오는데 자기 쪽이 없는 개념, 빠진 링크를 찾아
목록으로만 보여 줘. 아직 고치지는 마. 더 물어볼 질문도 제안해 줘.
일지 머리말을 같게 맞춰 두었으므로, 원문 팁대로 grep "^## \[" log.md | tail -5 를 wiki/ 폴더에서 실행하면 최근 다섯 항목(넣기·묻기·점검)이 보입니다.
확인: 점검 결과가 항목별 목록으로 나오고, 위 명령에 ingest 항목과 함께 이번 점검까지 최근 기록이 보입니다.
막히면
| 증상 | 해 볼 것 |
|---|---|
| 자료를 어디에 넣을지 오래 고민하게 됨 | 원문의 조언은 “깊이 고민하지 말라 — 간단한 검색으로 거의 다시 찾을 수 있다”입니다. 일단 inbox/ 에 넣고 주 1회 몰아서 정리합니다. |
| 프로젝트와 영역이 헷갈림 | “언젠가 끝나는가?”를 묻습니다. 끝나면 프로젝트, 계속되면 영역입니다. 영역 안에서 끝이 있는 일을 꺼내 프로젝트로 만듭니다(실습 1의 1단계). |
| 에이전트가 규칙과 다르게 넣음 | 규칙 문장이 구체적인지, 다른 지침과 어긋나지 않는지 봅니다. 그래도 안 되면 실습 10. |
AI 가 raw/ 원문을 고쳐 버림 | 스키마에 “읽기만” 줄이 있는지 봅니다. 다만 지침 파일은 강제 설정이 아니라 맥락입니다. 반드시 막아야 하면 권한 규칙·훅으로 막습니다(9장). 원문은 위키가 “그냥 마크다운 파일의 git 저장소”라 버전 이력이 저절로 따라온다고 말합니다. 폴더를 git 으로 관리하면 무엇이 바뀌었는지 이력으로 볼 수 있습니다. |
위키가 커져 index.md 로 찾기가 버거움 | 원문은 중간 규모(원문 약 100개, 수백 쪽)까지는 목차로 잘 된다고 하고, 더 커지면 검색 도구(예: qmd)나 AI 와 함께 만든 단순한 검색 스크립트를 권합니다(2장 접힌 상자). |
| 그림이 들어 있는 원문 | 원문 팁: AI 는 그림이 섞인 마크다운을 한 번에 읽지 못하므로, 글을 먼저 읽게 하고 그림은 따로 보게 합니다. 글만 다루면 그림 처리는 필요 없습니다. |
| 원문을 한꺼번에 많이 넣고 싶음 | 원문은 여러 개를 한꺼번에 넣고 덜 지켜보는 방법도 있다고 합니다. 처음에는 하나씩 넣어 요약을 확인하고, 정한 방식은 스키마에 적어 다음 세션도 따르게 합니다. |
| 폴더마다 따로 지침을 두고 싶음 | 아래 접힌 상자를 봅니다. |
하위 폴더에만 해당하는 지침 (원문)
작업 폴더 아래 하위 폴더의 CLAUDE.md 는 시작 때가 아니라, Claude 가 그 폴더의 다른 파일을 읽거나 쓰거나 고칠 때 한 번 읽힙니다. 예를 들어 projects/blog-12-posts/CLAUDE.md 에 그 프로젝트 전용 말투를 두면 그 폴더를 다룰 때만 읽힙니다. 이렇게 필요할 때 읽히는 파일에는 파일당 글자 수 한도가 있어 넘으면 앞부분만 전달됩니다(200K 컨텍스트 창 기준 40,000자). 특정 파일 종류에만 해당하는 규칙은 .claude/rules/ 의 paths: 규칙으로 둘 수 있습니다. 자세히: 3장 읽히는 순서·3장 규칙 폴더.
다음에 할 것
여기까지가 팀 공용 기억의 뼈대(목표 · 지침 · 지식 창고)이고, 지식 창고의 한 칸은 AI 가 관리하는 위키가 되었습니다. 위키 점검은 공용 기억 정기 점검(9장) 때 함께 하고, log.md 는 인수인계 노트(실습 8)와 같은 역할을 합니다(이 가이드의 제안). 에이전트 팀이라면 팀원 여럿이 위키를 읽고 쓰기는 한 명이 맡기를 권합니다. 실습 4에서는 개인 팀을 위해 나만의 공통 선호를 사용자 범위에 적습니다. 개념: 2장 PARA·2장 LLM 위키·1장 그때그때 불러오기. Claude 프로젝트 갈래는 정리한 문서를 프로젝트 지식에 올리고, 세 질문은 프로젝트 지침에 적습니다.
- 기존 자료는 날짜 붙은 보관 폴더로 한 번에 옮기고 깨끗하게 시작합니다.
- 프로젝트·영역·자원·보관 네 칸과 보관함(inbox)을 만듭니다.
- 어느 프로젝트 → 영역 → 자원, 아니면 보관 — 세 질문으로 넣습니다.
- 지침 파일엔 자료가 아니라 넣고 찾는 규칙만. 자료는 에이전트가 필요할 때 찾아 읽습니다.
- LLM 위키:
raw/원문은 고치지 않고,wiki/는 AI 가 쓰고 고치며, 규칙(스키마)은CLAUDE.md에.index.md는 목차,log.md는 덧붙이기만 하는 일지. - 넣기 → 묻기(좋은 답은 새 쪽으로 되돌려 넣기) → 때때로 점검.
출처: sources/raw/fortelabs_para.md(4 Categories, The Key Principle), fortelabs_basb.md(Organize for actionability — Start with a clean slate, Ask three questions), anthropic_context-engineering.md(just in time 전략, Claude Code 의 혼합 방식), claude-code_best-practices.md(Keep CLAUDE.md short, 표의 “architecture and file layout”), claude-code_memory.md(How CLAUDE.md files load, subdirectory 크기 한도), karpathy_llm-wiki.md(https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f — The core idea, Architecture, Operations, Indexing and logging, Optional: CLI tools, Tips and tricks, Note). 폴더 이름·지침 문장·프롬프트는 이 활용편의 예시입니다.
개인 팀 — 나만의 공통 선호를 사용자 범위에 적기
개인 팀이든 회사 팀이든 “나”는 같습니다. 말투·보고 형식·늘 쓰는 도구처럼 어느 팀에서나 같은 내 선호는 팀 폴더가 아니라 내 컴퓨터의 사용자 범위에 한 번만 적습니다. 그러면 모든 폴더의 모든 세션이 그것을 먼저 읽고, 팀 폴더에는 그 팀의 일만 남습니다.
- 사용자 범위
~/.claude/CLAUDE.md에 모든 프로젝트 공통 선호를 적습니다. - 이 프로젝트에서만 쓰는 내 메모는
CLAUDE.local.md로 나눕니다. - 범위들이 어떤 순서로 합쳐져 읽히는지 확인하고, 서로 어긋나지 않게 맞춥니다.
예상 소요 시간: 15~20분
준비물을 확인한 뒤 따라 하기 1·2·4단계를 하세요. 3단계(CLAUDE.local.md)는 회사 저장소처럼 남과 공유하는 폴더에서 나만의 메모가 필요할 때 합니다. 결과가 이상하면 막히면을 봅니다.
준비물과 완료 기준
- Claude Code. (Claude 프로젝트 갈래는 원문에 계정 전체 공통 지침 설명이 없어 이 실습을 건너뜁니다. 대신 프로젝트마다 지침 칸에 같은 선호를 적습니다.)
- 시작 전 준비에서 만든 팀 폴더 하나 이상(예시 이름
my-brain/). - 어느 팀에서나 바라는 내 선호 3~5개. 예시: “답은 한국어 존댓말”, “요약을 먼저, 자세한 내용은 그 뒤”.
서로 다른 두 폴더에서 세션을 열었을 때 둘 다 /context all 의 Memory files 에 ~/.claude/CLAUDE.md 가 보이고, 답이 내 선호를 따르면 완료입니다.
따라 하기
1단계 · 선호를 “어디서나”와 “이 팀만”으로 가르기
적어 둔 선호를 두 칸으로 나눕니다. 원문 표의 쓰임 예는 사용자 범위가 “코드 스타일 선호, 개인 도구 단축 방법”, 프로젝트 범위가 “프로젝트 구조, 코딩 기준, 자주 쓰는 작업 흐름”입니다.
- 답은 한국어 존댓말
- 요약 먼저, 자세한 내용은 뒤에
- 파일을 지우기 전에 먼저 묻기
- 팀 목표
@GOAL.md - 블로그 글은 1,500자 이상
- 자료는 inbox/ 에 넣기
선호 문장은 모두 예시입니다.
확인: “어디서나” 칸의 항목은 회사 일을 할 때도 그대로 맞습니다. 하나라도 회사 일에 맞지 않으면 그 항목은 팀 폴더로 옮깁니다.
2단계 · ~/.claude/CLAUDE.md 에 적기
아무 폴더에서 세션을 열고 /memory 를 입력해 사용자 항목을 고릅니다. 파일이 아직 없으면 만들어서 편집기로 열어 줍니다. 아래처럼 짧게 씁니다(예시).
# 나에 대한 공통 선호 (모든 프로젝트)
- 답은 한국어 존댓말로 쓴다.
- 답의 첫 줄은 결론 한 문장, 자세한 내용은 그 아래 목록으로.
- 파일을 지우거나 옮기기 전에 목록을 보여 주고 묻는다.
이 파일은 나만 쓰고 모든 프로젝트에서 읽힙니다. 팀 폴더를 저장소로 공유해도 이 파일은 함께 가지 않습니다.
확인: 파일이 홈 폴더의 .claude 폴더 안에 저장됐습니다.
선호가 많아지면 — 사용자 규칙 폴더 ~/.claude/rules/
~/.claude/rules/ 의 규칙 파일(예: preferences.md, workflows.md)도 내 컴퓨터의 모든 프로젝트에 적용됩니다. 사용자 규칙은 프로젝트 규칙보다 먼저 읽히며, 둘이 어긋나면 Claude 가 어느 쪽이든 따를 수 있으므로 서로 맞춰 둡니다. 자세히: 3장 규칙 폴더.
3단계 · (필요할 때) 이 프로젝트만의 내 메모는 CLAUDE.local.md
회사 팀 폴더처럼 남과 공유하는 프로젝트에서 “나만 쓰는 시험용 주소, 내가 좋아하는 테스트 자료” 같은 메모가 필요하면 프로젝트 맨 위에 CLAUDE.local.md 를 만듭니다. CLAUDE.md 와 함께 읽히고, 같은 폴더에서는 CLAUDE.md 뒤에 붙어 그 층에서 가장 나중에 읽힙니다. 저장소에 올라가지 않도록 .gitignore 에 추가합니다.
CLAUDE.local.md 는 만든 워크트리에만 있습니다. 같은 저장소의 여러 워크트리에서 쓰려면 홈 폴더 파일을 가져오는 방법을 씁니다(아래 접힌 상자).확인: .gitignore 에 CLAUDE.local.md 한 줄이 있습니다. git 을 쓰지 않는 개인 폴더라면 이 단계는 건너뜁니다.
워크트리 여러 개에서 같은 개인 메모를 쓰려면 / AGENTS.md 와 함께 쓸 때
여러 git 워크트리에서 일하면 gitignore 된 CLAUDE.local.md 는 만든 워크트리에만 있습니다. 원문은 대신 홈 폴더 파일을 가져오라고 합니다: - @~/.claude/my-project-instructions.md. 작업 폴더 밖을 가리키므로 처음 한 번 승인 창이 뜹니다.
주의: AGENTS.md 만 쓰는 프로젝트에 CLAUDE.local.md 를 추가하면, 그것이 CLAUDE.md 로 쳐져 Claude 가 AGENTS.md 를 읽지 않게 됩니다. 둘 다 읽히게 하려면 /config 의 Project instructions 를 claude-md-and-agents-md 로 바꿉니다. 자세히: 3장 AGENTS.md.
4단계 · 두 폴더에서 확인하고 어긋남 없애기
- 팀 폴더에서 새 세션 →
/context allMemory files 에~/.claude/CLAUDE.md와./CLAUDE.md가 함께 보이는지 봅니다. - 다른 폴더(예:
work-brain/)에서 새 세션 → 같은 확인사용자 파일은 보이고,my-brain의 프로젝트 파일은 보이지 않아야 합니다. - 예시 질문“파일은 바꾸지 말고, 지금 읽은 지침 중 사용자 범위와 프로젝트 범위에서 서로 어긋나는 것이 있으면 알려 줘.”
모든 파일은 서로 덮어쓰지 않고 이어 붙어 읽힙니다. 그래서 두 범위가 같은 일에 다른 말을 하면 Claude 가 아무 쪽이나 고를 수 있습니다. 어긋남을 찾으면 한쪽을 고쳐 맞춥니다.
확인: 두 폴더 모두 내 선호대로 답하고, 어긋나는 지시가 없습니다.
막히면
| 증상 | 해 볼 것 |
|---|---|
| “기억해 줘”라고 했는데 파일에 없음 | “항상 pnpm 을 써” 처럼 기억을 부탁하면 Claude 는 자동 메모리에 저장합니다. 지침 파일에 넣으려면 “이걸 CLAUDE.md 에 추가해 줘”라고 분명히 말하거나 /memory 로 직접 고칩니다. 자동 메모리는 5장. |
| 사용자 파일이 Memory files 에 없음 | 경로가 ~/.claude/CLAUDE.md(홈 폴더의 .claude 안)인지 확인합니다. /memory 의 사용자 항목으로 열면 경로가 틀릴 일이 없습니다. |
| 회사 폴더에서 개인 선호가 회사 규칙과 부딪침 | 사용자 범위에서 그 항목을 빼서 개인 팀 폴더의 프로젝트 범위로 옮깁니다. 회사 규칙이 조직 범위로 배포돼 있다면 그것을 기준으로 맞춥니다 — 9장 회사 팀. |
| 선호를 계속 무시함 | 문장을 확인할 수 있게 구체적으로 바꿉니다. 그래도 안 되면 실습 10. |
다음에 할 것
나에 대한 층이 생겼으니 실습 5에서 팀의 첫 역할(검토 담당)을 정의합니다. 서브에이전트도 시작할 때 이 사용자 파일을 포함한 CLAUDE.md 단계를 모두 받으므로 같은 선호로 일합니다. 개념: 9장 개인 팀·3장 범위.
- 어느 팀에서나 같은 내 선호는
~/.claude/CLAUDE.md(사용자 범위)에 한 번만. - 공유 프로젝트 안의 나만의 메모는
CLAUDE.local.md+.gitignore. - 범위는 넓은 것부터 이어 붙어 읽히며 서로 덮어쓰지 않습니다 — 어긋나면 직접 맞춥니다.
- “기억해”는 자동 메모리로, “CLAUDE.md 에 추가해”는 지침 파일로 갑니다.
출처: sources/raw/claude-code_memory.md(Choose where to put CLAUDE.md files, Import additional files — CLAUDE.local.md·워크트리, How CLAUDE.md files load, User-level rules, When Claude Code reads AGENTS.md, View and edit with /memory), claude-code_best-practices.md(Keep CLAUDE.md short — 개인 선호는 CLAUDE.local.md), claude-code_sub-agents.md(What loads at startup). 선호 문장·폴더 이름·질문 문장은 이 활용편의 예시입니다.
역할 하나 정의하기 — 검토 담당 서브에이전트
팀이 되려면 역할이 있어야 합니다. 가장 쓸모 있는 첫 역할은 검토 담당입니다. 결과물이 팀 목표와 규칙에 맞는지 읽기만 하고, 고칠 점을 돌려줍니다. 역할은 파일 한 장(역할 정의 파일)으로 만들고, 팀 폴더에 두면 그 폴더의 모든 사람과 세션이 같은 검토자를 씁니다.
- 역할 정의 파일
.claude/agents/<이름>.md를 Claude 에게 만들게 하고 내용을 확인합니다. - 읽기 전용 도구만 주어 검토 담당이 파일을 고치지 못하게 합니다.
- 이름을 불러 일을 맡기고, 검토 담당이 팀 목표를 알고 있는지 확인합니다.
예상 소요 시간: 20분
준비물을 확인하고 따라 하기 1~4단계를 하세요. 서브에이전트가 무엇을 받고 무엇을 못 받는지는 2단계 그림에 있습니다. 불러도 안 나타나면 막히면을 봅니다. 이 실습은 Claude Code 전용입니다.
준비물과 완료 기준
- Claude Code 와 실습 1·실습 2를 마친 팀 폴더(예시 이름
my-brain/) — 목표 파일을 가져오는CLAUDE.md가 있는 상태. - 검토받을 결과물 하나. 예시:
projects/blog-12-posts/안의 글 초안 한 편.
.claude/agents/goal-reviewer.md(예시 이름)가 있고, 일을 맡겼을 때 대화에 goal-reviewer(…) 같은 위임 줄이 보이며, 돌아온 검토가 목표 파일의 완료 기준을 근거로 들면 완료입니다. 검토 담당은 파일을 바꾸지 않아야 합니다.
따라 하기
1단계 · 어느 범위에 둘지 정하기
역할 정의 파일은 놓는 위치에 따라 쓸 수 있는 사람이 달라집니다.
| 위치 | 범위 | 이럴 때 |
|---|---|---|
.claude/agents/ | 이 프로젝트 | 팀 폴더 전용 역할. 저장소에 올려 팀원과 함께 쓰고 고칩니다. |
~/.claude/agents/ | 내 모든 프로젝트 | 어느 팀에서나 쓰는 내 개인 도우미. |
검토 기준이 이 팀의 목표에 묶여 있으므로 이번에는 팀 폴더의 .claude/agents/ 에 둡니다. 이름이 같은 역할이 여러 곳에 있으면 우선순위가 높은 쪽이 쓰입니다(조직 관리 설정 > 실행 옵션 --agents > 프로젝트 > 사용자 > 플러그인).
확인: 팀 폴더 안에 둘지, 홈 폴더에 둘지 정했습니다.
2단계 · 서브에이전트가 받는 것 알아 두기
검토 담당이 팀 목표를 알려면, 시작할 때 무엇을 받는지 알아야 합니다. 서브에이전트는 새롭고 분리된 컨텍스트로 시작합니다.
그래서 팀 목표는 대화가 아니라 CLAUDE.md(와 가져온 목표 파일)에 두는 것이 핵심입니다. 그러면 역할마다 목표를 따로 적지 않아도 모두 같은 목표를 받습니다 — 이 가이드가 “공용 기억”이라고 부르는 이유입니다.
확인: 검토 담당이 실습 1의 목표를 따로 적지 않아도 받는다는 것을 압니다.
3단계 · Claude 에게 역할 파일 만들게 하기
팀 폴더에서 세션을 열고, 원하는 역할과 저장 위치를 말합니다. 아래는 원문 빠른 시작 예를 이 팀에 맞게 바꾼 예시 프롬프트입니다.
Create a project goal-reviewer subagent in .claude/agents/ that reviews
drafts against the team goal and rules in CLAUDE.md. It should list each
problem with the line it found it in and a suggested fix. Make it read-only.
뜻: “.claude/agents/ 에 프로젝트용 goal-reviewer 서브에이전트를 만들어 줘. 초안을 CLAUDE.md 의 팀 목표·규칙에 비추어 검토하고, 문제마다 찾은 줄과 고칠 방법을 적게 해. 읽기 전용으로.” 한국어로 말해도 됩니다.
Claude 가 name·description·tools 등을 담은 파일을 씁니다. 파일을 열어 아래와 비슷한지 확인합니다(예시).
---
name: goal-reviewer
description: Reviews drafts against the team goal and rules in CLAUDE.md. Use proactively after a draft is written.
tools: Read, Grep, Glob
---
You review drafts for this team. Check each draft against the goal,
completion criteria and "do not" list in CLAUDE.md. For each problem,
quote the line, say which rule it breaks, and suggest a fix.
Do not edit files.
위쪽 --- 사이(머리말)가 설정이고, 아래 본문이 이 역할의 지시문이 됩니다. 꼭 필요한 칸은 name 과 description 둘뿐입니다. tools 를 Read, Grep, Glob 로 제한하면 고치기·쓰기 도구가 빠져 읽기만 합니다. description 에 “use proactively” 같은 말을 넣으면 Claude 가 알아서 맡기는 일이 늘어납니다.
확인: 파일 첫 줄이 --- 이고, name·description 이 있으며, tools 에 Edit·Write 가 없습니다.
머리말에 더 넣을 수 있는 칸 (원문 일부)
model(sonnet·opus·haiku·inherit 등), disallowedTools(뺄 도구), skills(시작 때 미리 넣을 스킬 — 설명만이 아니라 전체 내용), memory(user·project·local — 세션을 넘어 이 역할만의 기억을 쌓음), omitClaudeMd(true 면 사용자·프로젝트·로컬 CLAUDE.md 없이 시작 — 팀 목표를 받지 못하므로 이 실습에는 쓰지 않음, v2.1.271 이상), isolation: worktree(저장소의 분리된 복사본에서 일함) 등. 칸 이름은 표와 정확히 같아야 하며, 모르는 칸은 오류 없이 무시됩니다. 자세히: 6장 서브에이전트·5장 서브에이전트 기억.
4단계 · 이름 불러 일 맡기고 확인하기
원문은 세 가지 부르는 법을 소개합니다.
- 이름을 말로“goal-reviewer 서브에이전트로 projects/blog-12-posts/ 의 초안을 검토해 줘” — 맡길지는 Claude 가 정합니다.
- @-멘션
@를 치고 목록에서 고르거나@agent-goal-reviewer를 직접 씁니다. 그 일에 이 역할이 반드시 쓰입니다. - 세션 전체를 그 역할로
claude --agent goal-reviewer로 시작하면 세션 자체가 그 역할의 도구 제한·모델로 돕니다.
확인: 위임 줄이 보이고, 검토가 목표 파일의 완료 기준·하지 않을 일을 근거로 들며, 초안 파일은 그대로입니다.
막히면
| 증상 | 해 볼 것 |
|---|---|
| 새 역할을 못 찾음 | 세션을 시작할 때 agents 폴더가 없었다면, 처음 만든 뒤 Claude Code 를 다시 시작해야 읽힙니다. 이미 있던 폴더라면 몇 초 안에 변경을 알아채 재시작 없이 다음 위임부터 반영됩니다. |
| 파일이 있는데 조용히 무시됨 | 머리말에 name 이 없거나, 첫 줄이 --- 가 아니거나, name 만 있고 description 이 없거나, YAML 이 깨지면 알림 없이 건너뜁니다. --debug 로 실행해 디버그 기록을 봅니다. |
| 검토가 팀 목표를 모름 | 머리말에 omitClaudeMd: true 가 있지 않은지 봅니다. 꼭 전해야 할 조건이 대화에만 있었다면 맡길 때 다시 말하거나 CLAUDE.md 에 옮깁니다. |
| 검토 담당이 파일을 고침 | tools 칸을 빼먹으면 쓸 수 있는 도구를 모두 물려받습니다. tools: Read, Grep, Glob 처럼 명시합니다. |
| 알아서 맡기지 않음 | description 을 “언제 맡길지”가 드러나게 고치거나 @-멘션으로 부릅니다. 역할 설명들은 짧게 — 합계가 15,000토큰을 넘으면 시작 때 경고가 뜹니다. |
다음에 할 것
같은 역할 정의 파일은 실습 6의 에이전트 팀에서 팀원을 만들 때 다시 쓸 수 있습니다. 역할을 늘리기 전에 검토 담당 하나로 몇 번 써 보고 지시문을 다듬으세요. 개념: 6장 역할 나누기.
- 역할은
.claude/agents/<이름>.md한 장 — 팀 폴더에 두면 팀 전원이 같은 역할을 씁니다. - 서브에이전트는 대화 기록 없이 시작하지만 CLAUDE.md 단계는 모두 받아 팀 목표를 압니다.
tools: Read, Grep, Glob로 읽기 전용 검토자를 만듭니다.- 말로, @-멘션으로,
--agent로 부르고, 위임 줄로 확인합니다.
출처: sources/raw/claude-code_sub-agents.md(Quickstart, Choose the subagent scope, Write subagent files, Frontmatter reference, Subagent files Claude Code skips, Understand automatic delegation, Invoke subagents explicitly, What loads at startup, Example subagents — Code reviewer). 역할 이름·지시문·프롬프트·검토 내용은 이 활용편의 예시입니다.
에이전트 팀 띄우고 모두 같은 맥락인지 확인하기 실험 기능
리더 한 명과 팀원 세 명으로 작은 조사 팀을 띄워 봅니다. 그리고 팀원에게 직접 물어 "지침 파일·스킬은 받았지만, 리더와 나눈 대화는 받지 못했다"는 것을 눈으로 확인합니다. 팀 전체가 같은 목표를 갖게 하려면 무엇을 파일에 두고, 무엇을 생성 지시문에 넣어야 하는지가 이 실습의 핵심입니다.
- 원문대로 에이전트 팀(리더 1명 + 팀원 여럿이 공유 작업 목록·메시지로 함께 일하는 Claude Code 기능)을 켜고 끕니다.
- 팀원이 시작할 때 무엇을 자동으로 받고 무엇을 받지 못하는지 직접 확인합니다.
- 꼭 알아야 할 내용을 생성 지시문(spawn prompt — 리더가 팀원을 만들 때 주는 첫 지시)이나 지침 파일에 넣어 빈틈을 메웁니다.
예상 소요 시간: 20~30분
준비물을 확인한 뒤 따라 하기 1~4단계까지만 해도 이 실습의 목적은 이룹니다. 팀원이 안 보이거나 서브에이전트로 뜨면 막히면을 봅니다. 개념 설명은 완전 가이드 팀원이 받는 맥락에 있습니다.
준비물과 완료 기준
- 실습 1·실습 2에서 만든 프로젝트 폴더. 프로젝트
CLAUDE.md에 팀 목표(또는 목표 파일을 불러오는@줄)가 들어 있으면 됩니다. - 터미널에서 직접 대화하는 Claude Code 세션. 원문에 따르면 팀원을 만드는 일은 대화형 세션에서만 됩니다 —
-p옵션으로 돌리는 비대화형 실행에서는 팀원이 생기지 않습니다. - 설정 파일
settings.json을 고칠 수 있는 권한(1단계에서 한 줄 추가). - 코드를 쓰지 않는 조사 과제 하나. 원문은 처음이라면 PR(pull request — 코드 변경을 합치기 전에 검토받는 요청) 검토·라이브러리 조사·버그 조사처럼 경계가 분명하고 코드를 쓰지 않는 일부터 시작하라고 권합니다.
팀원 세 명이 에이전트 패널에 보이고, 팀원 한 명에게 직접 물었을 때 ① 프로젝트 목표는 맞게 답하고 ② 리더에게만 대화로 말한 내용은 모른다고 답합니다. 그 내용을 생성 지시문에 넣어 다시 물었을 때 맞게 답하면 끝입니다. 마지막에 팀원을 정리합니다.
따라 하기
1단계 · 에이전트 팀 켜기
에이전트 팀은 원문 기준 실험 기능이고 기본은 꺼져 있습니다. 환경 변수 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS를 1로 두면 켜집니다. 환경 변수(프로그램이 실행될 때 읽는 이름=값 설정)를 터미널(셸) 환경에 넣어도 되고, 설정 파일 settings.json(예: 사용자 설정 ~/.claude/settings.json)에 이렇게 적어도 됩니다.
{
"env": {
"CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
}
}
켜져 있는 동안에는 Claude 가 이름을 붙여 부른 서브에이전트(맡긴 일을 자기 컨텍스트에서 하고 결과만 돌려주는 도우미)가 팀원으로 뜹니다. Claude 는 스스로 서브에이전트에 이름을 붙이기도 하므로, 팀을 부탁하지 않았는데도 팀이 생길 수 있습니다. 실습이 끝나면 6단계에서 끄는 방법을 확인합니다.
확인: 설정을 저장한 뒤 프로젝트 폴더에서 claude를 대화형으로 실행했습니다.
2단계 · 리더에게만 대화로 한 가지 말해 두기
시험용으로, 파일에는 없고 대화에만 있는 사실을 하나 만듭니다. 아래는 이 가이드가 만든 예시 문장입니다.
(예시) 참고로, 이번 조사의 마감은 금요일 오후 3시야. 아직 아무것도 하지 말고 "알겠다"고만 답해 줘.
이 문장은 리더의 대화 기록에만 남습니다. CLAUDE.md에 적지 않습니다.
확인: 리더가 답했고, 프로젝트 파일 어디에도 "금요일 오후 3시"가 없습니다.
3단계 · 팀원 세 명 띄우기
원하는 일과 팀원 구성을 평범한 말로 부탁합니다. 원문 예시는 서로 기다릴 필요 없는 세 역할로 나누었습니다.
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 담당, 기술 구조 담당, 일부러 반대 의견을 내는 담당."
자기 과제로 바꿀 때는 이름까지 정해 주면 뒤에서 부르기 쉽습니다. 원문은 나중 프롬프트에서 부를 예측 가능한 이름이 필요하면 생성 지시 때 각 팀원의 이름을 리더에게 알려 주라고 합니다.
(예시) 팀원 세 명을 만들어 줘. 이름은 researcher, critic, writer.
각자 다른 관점으로 [조사 주제]를 살펴보고 결과를 너에게 보고하게 해 줘.
금요일 마감 이야기는 아직 전하지 마.
리더 터미널의 입력 칸 아래 에이전트 패널에 팀원이 나열됩니다. 위·아래 화살표로 고르고, Enter로 그 팀원의 기록을 열어 직접 말을 걸고, Esc로 선택을 풉니다.
확인: 패널에 팀원 세 명이 보입니다. 원문은 서브에이전트도 같은 패널에 보이므로 패널만으로는 팀이 생겼는지 확정할 수 없다고 합니다. 리더에게 "지금 만든 것이 에이전트 팀의 팀원인지" 물어 확인하고, 서브에이전트였다면 에이전트 팀을 명시해 다시 부탁합니다.
4단계 · 팀원에게 직접 묻기 — 무엇을 받았나
패널에서 팀원 한 명을 고르고 Enter로 연 뒤, 아래 두 질문을 그 팀원에게 보냅니다(예시).
(예시) 작업은 잠깐 멈추고 두 가지만 답해 줘.
1. 이 프로젝트의 목표는 뭐야? 어느 파일에서 봤어?
2. 이번 조사의 마감은 언제야?
기대하는 답: 1번은 CLAUDE.md(또는 거기서 불러온 목표 파일)를 근거로 맞게 답합니다. 2번은 모른다고 답하거나 근거 없이 추측합니다. 팀원은 일반 세션과 같은 프로젝트 맥락(CLAUDE.md·MCP 서버·스킬)을 읽지만, 리더의 대화 기록은 넘어가지 않기 때문입니다.
팀원 화면을 연 상태에서 입력한 일반 글과 스킬은 그 팀원에게 가지만, 내장 명령은 리더 세션에 적용됩니다. /compact·/clear·/rewind는 리더 대화에 작동하므로 실행 전에 확인을 묻고, /model·/fast는 이 화면에서 실행되지 않습니다.
확인: 1번은 맞게, 2번은 모른다고(또는 추측으로) 답했습니다. 2번을 맞혔다면 리더가 생성 지시 때 이미 전달했을 수 있으니, 리더에게 생성 지시문 원문을 보여 달라고 해 확인합니다.
5단계 · 빈틈 메우기 — 생성 지시문에 넣거나 파일로 옮기기
원문은 팀원에게 그 과제에 필요한 세부 사항을 생성 지시문에 담으라고 합니다. 원문 예시는 검토 대상 폴더, 집중할 점, 앱의 특징, 보고 형식까지 지시문 안에 적습니다.
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 토큰을 쓴다. 발견한 문제는 심각도와 함께 보고."
이번 실습에서는 리더에게 이렇게 부탁합니다(예시).
(예시) checker 라는 팀원을 하나 더 만들어 줘. 생성 지시문에
"이번 조사의 마감은 금요일 오후 3시"를 꼭 넣어 줘. 만든 뒤 마감이 언제인지 물어봐.
모든 팀원이 매번 알아야 하는 것(목표·용어·금지 사항)은 생성 지시문이 아니라 CLAUDE.md나 목표 파일에 둡니다 — 그래야 다음 팀, 다음 세션도 자동으로 받습니다. 이번 과제에만 필요한 것(마감·대상 폴더·보고 형식)은 생성 지시문에 넣습니다. 이미 떠 있는 팀원에게는 이름으로 메시지를 보내 알려 줄 수도 있습니다. 모두에게 알리려면 원문대로 받는 사람마다 메시지를 하나씩 보냅니다.
확인: 새 팀원 checker 가 마감을 "금요일 오후 3시"라고 맞게 답합니다.
6단계 · 팀원 정리하고, 필요하면 기능 끄기
팀원은 이름으로 불러 정리합니다. 원문 예시:
Ask the researcher teammate to shut down
뜻: "researcher 팀원에게 종료하라고 전해 줘." 리더가 종료 요청을 보내고, 팀원은 받아들여 정상 종료하거나 이유를 들어 거절할 수 있습니다. 팀의 공유 폴더는 세션이 끝날 때 자동으로 정리되므로 따로 지울 단계는 없습니다.
평소에는 서브에이전트만 쓰고 싶다면 같은 변수를 0으로 둡니다. 원문에 따르면 설정 파일의 env 값은 저장하면 실행 중인 세션에 다시 적용되므로 새 세션을 열 필요가 없습니다.
{
"env": {
"CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "0"
}
}
확인: 패널에서 팀원이 사라졌고(종료), 다음에 Claude 가 이름 붙여 부르는 도우미가 서브에이전트로 뜹니다.
팀 정보가 어디에 남나 · 끄는 설정이 안 먹을 때
팀 설정은 ~/.claude/teams/{team-name}/config.json에 있고 세션이 끝나면 지워집니다. 작업 목록은 ~/.claude/tasks/{team-name}/에 있고 세션이 끝나도 남습니다(보관 기간은 cleanupPeriodDays). 팀 이름은 session- 뒤에 세션 ID 앞 8글자입니다. 팀 설정 파일은 실행 상태를 담으므로 손으로 고치거나 미리 써 두지 않습니다 — 다음 상태 갱신 때 덮어써집니다. 프로젝트 안의 .claude/teams/teams.json 같은 파일은 설정으로 인식되지 않습니다. 재사용할 역할은 실습 5의 역할 정의 파일(.claude/agents/)로 만듭니다.
사용자 settings.json에서 0으로 두면 셸의 export 를 이깁니다. 하지만 우선순위가 높은 프로젝트 설정·로컬 설정·--settings에서 1로 켜 두었거나, 조직의 관리 설정(managed settings)이 켜 두었다면 그쪽이 이깁니다. 관리 설정이라면 관리자에게 요청합니다.
막히면
| 증상 | 해 볼 것과 확인 기준 |
|---|---|
| 팀원이 안 보임 | 기본 표시 방식(in-process — 모든 팀원이 내 터미널 하나 안에서 동작)에서는 입력 칸 아래 에이전트 패널에 나옵니다. 모든 에이전트가 쉬면 쉬는 줄은 30초 뒤 숨겨질 뿐 멈춘 것이 아닙니다 — 이름으로 메시지를 보내면 다시 보입니다. 넷 이상 쉬면 세 줄을 넘는 것은 N idle agents 한 줄로 접히고 Enter로 펼칩니다. 과제가 팀이 필요할 만큼 복잡한지도 봅니다 — 팀원을 만들지는 Claude 가 과제를 보고 정합니다. |
| 팀 대신 서브에이전트가 뜸 | 원문대로 에이전트 팀을 명시해 다시 부탁합니다. 반대로 원치 않는데 팀원이 뜨면 6단계처럼 변수를 0으로 둡니다. |
| 권한 확인 창이 너무 많이 뜸 | 팀원의 권한 요청은 리더 세션으로 올라오고, 내가 리더 세션에서 직접 승인합니다. 자주 쓰는 동작은 팀원을 만들기 전에 권한 설정에서 미리 허용해 둡니다. |
| 리더가 팀원을 안 기다리고 직접 일함 | Wait for your teammates to complete their tasks before proceeding(뜻: 진행하기 전에 팀원들이 맡은 일을 끝낼 때까지 기다려)라고 말합니다. |
| 팀원이나 리더가 일찍 멈춤 | 팀원은 오류를 만나면 회복하지 않고 멈출 수 있습니다. 패널에서 골라 Enter로 출력을 읽고, 직접 추가 지시를 주거나 대신할 팀원을 새로 만듭니다. 리더가 일이 다 끝나기 전에 끝났다고 판단하면 계속하라고 말합니다. |
/resume 뒤 팀원이 없음 | 원문의 알려진 한계입니다 — /resume·/rewind는 in-process 팀원을 되살리지 않습니다. 리더에게 팀원을 새로 만들라고 말합니다. 그래서 이어 할 일은 실습 8의 인수인계 노트처럼 파일에 남겨 둡니다. |
원문에 따르면 한 에이전트가 다른 에이전트에게 보낸 메시지는 "다른 Claude 세션에서 왔다"고 표시됩니다. 팀원은 나 대신 권한 요청을 승인하거나 동의를 해 줄 수 없고, 거절당한 동작을 다른 팀원에게 넘겨 검사를 피할 수도 없습니다. 반면 새 팀원은 리더의 권한 모드로 시작합니다 — 리더가 bypassPermissions(모든 확인 건너뛰기) 모드라면 팀원도 그렇게 시작하므로, 실습은 평소 모드에서 합니다.
표시 방식 · 비용 · 한계 더 보기
표시 방식: 기본은 "in-process"(모든 팀원이 내 터미널 하나 안에서 동작, 추가 설치 없음). 팀원마다 창을 나누는 split panes 는 tmux 나 iTerm2(it2 CLI)가 필요합니다. ~/.claude/settings.json의 teammateMode("auto"·"tmux"·"iterm2")로 바꾸거나, 한 세션만 claude --teammate-mode auto로 실행합니다. 분할 창은 VS Code 내장 터미널·Windows Terminal·Ghostty 에서 지원되지 않습니다.
비용: 팀원마다 자기 컨텍스트 창이 있어 토큰(AI 가 읽고 쓰는 글의 양을 세는 단위) 사용량이 활동 중인 팀원 수에 비례해 늘어납니다. 원문은 대부분 3~5명으로 시작하라고 하고, 팀원당 작업 5~6개면 모두 바쁘게 일하면서 리더가 일을 다시 나눌 여유가 생긴다고 합니다. 두 팀원이 같은 파일을 고치면 덮어쓰게 되므로 팀원마다 맡을 파일을 나눕니다.
한계: 세션당 팀은 하나이고 세션끼리 팀을 나눌 수 없습니다. 팀원은 자기 팀원을 만들 수 없습니다(중첩 팀 없음). 리더는 바꿀 수 없습니다. 작업 상태 표시가 늦을 수 있으니 막힌 작업은 실제로 끝났는지 확인합니다. --setting-sources로 리더를 시작하면 팀원도 같은 제한된 설정 출처만 읽습니다(v2.1.281 이전 split-pane 팀원은 모든 설정 출처를 읽었음).
역할 정의 재사용: 팀원을 만들 때 실습 5의 역할 정의 파일 이름을 부를 수 있습니다(예: Spawn a teammate using the security-reviewer agent type to audit the auth module.). 이때 정의의 tools·model·본문은 적용되지만 skills 필드는 적용되지 않고, 팀원은 프로젝트·사용자 설정에서 스킬을 읽습니다.
다음에 할 것
- 팀 모두가 같은 방법으로 일하게 하려면 반복 절차를 스킬로 묶습니다 — 실습 7. 팀원은 프로젝트·사용자 범위의 스킬을 받습니다.
- 며칠에 걸친 일이라면 리더 대화 대신 파일에 진행 상황을 남깁니다 — 실습 8.
- 팀 구성의 원리(서브에이전트와의 차이, 팀 크기, 패턴)는 완전 가이드 에이전트 팀·생성 지시문·팀 크기·한계.
- 에이전트 팀은 실험 기능이며
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1로 켜고, 대화형 세션에서만 팀원이 생깁니다. - 팀원은 CLAUDE.md·MCP 서버·스킬과 생성 지시문을 받지만, 리더의 대화 기록은 받지 못합니다.
- 모두가 늘 알아야 할 것은 파일(CLAUDE.md·목표 파일)에, 이번 과제에만 필요한 것은 생성 지시문에 넣습니다.
- 처음에는 코드를 쓰지 않는 조사·검토 과제로 시작합니다. 원문은 팀을 대부분 3~5명으로 시작하라고 하며, 이 실습은 그 아래쪽인 3명으로 합니다. 팀원은 나 대신 권한을 승인할 수 없습니다.
출처: https://code.claude.com/docs/en/agent-teams (수집일 2026-11-10). 팀원 이름(researcher·critic·writer·checker)과 한국어 프롬프트, "금요일 오후 3시" 시험 문장은 이 가이드가 만든 연습용 예시입니다.
반복 절차를 스킬로 — 팀 전원이 같은 방법으로
매번 채팅에 붙여 넣던 절차 하나를 스킬로 만들어 프로젝트에 넣습니다. 그러면 나도, 서브에이전트도, 에이전트 팀의 팀원도 같은 절차를 같은 순서로 따릅니다. 평소에는 이름과 설명만 보이고 본문은 쓸 때만 읽히므로 지침 파일을 무겁게 하지 않습니다.
- 스킬(절차·지식을 폴더 하나의
SKILL.md로 묶어 필요할 때만 불러오는 것)로 옮길 내용을 고릅니다. - 프로젝트 범위에 스킬을 만들고, 자동으로 불리는지와
/이름으로 직접 부르는지 확인합니다. - 부작용이 있는 절차는 내가 부를 때만 돌게 막고, 커밋해서 팀과 나눕니다.
예상 소요 시간: 20~25분
준비물을 확인하고 따라 하기 1~4단계로 첫 스킬을 만들어 불러 봅니다. 불리지 않으면 막히면을 봅니다. 개념은 완전 가이드 스킬이란·언제 스킬로 만드나에 있습니다.
준비물과 완료 기준
- 실습 2에서 만든 프로젝트 폴더(가능하면 git 저장소)와 Claude Code.
- 채팅에 자꾸 붙여 넣는 지시나 체크리스트 하나. 없다면 이 실습의 예시 "주간 보고 정리 절차"를 씁니다.
CLAUDE.md에서 사실이 아니라 절차로 길어진 부분이 있다면 그것도 후보입니다.
.claude/skills/<이름>/SKILL.md가 있고, ① 설명에 맞는 말로 부탁했을 때 Claude 가 스킬을 쓰며 ② /<이름>으로 직접 불러도 같은 절차대로 결과가 나옵니다. 팀과 나눌 거라면 커밋까지 합니다.
disable-model-invocation: true)은 설명도 평소 컨텍스트에 넣지 않습니다.따라 하기
1단계 · 스킬로 옮길 절차 고르기
원문은 이럴 때 스킬을 만들라고 합니다 — 같은 지시·체크리스트·여러 단계 절차를 채팅에 계속 붙여 넣을 때, 또는 CLAUDE.md의 한 절이 사실이 아니라 절차로 커졌을 때. 모델은 일반적인 지식은 알지만 우리 팀이 릴리스를 어떻게 하는지, 장애 대응 문서에 뭐라고 적혀 있는지는 모릅니다. 그런 팀 지식이 스킬 자리입니다.
모든 일에 늘 적용되는 짧은 사실·규칙 (예: 팀 목표, 쓰지 말 말투)
특정 일에만 필요한 절차·긴 참고 자료 (예: 주간 보고 정리, 배포 순서)
원문은 CLAUDE.md 규칙이 스킬에도 똑같이 적용된다고 합니다 — Claude 가 스스로 찾을 수 없는 것만 적습니다.
확인: 스킬로 만들 절차 하나와, 그 절차를 부를 때 내가 쓸 말(예: "주간 보고 정리해 줘")을 적었습니다.
2단계 · 둘 곳 고르기 — 나만 쓸지, 팀과 쓸지
스킬을 저장한 위치가 어느 세션에서 읽힐지를 정합니다.
| 위치 | 경로 | 읽히는 곳 |
|---|---|---|
| 개인 Personal | ~/.claude/skills/<skill-name>/SKILL.md | 이 컴퓨터의 내 모든 프로젝트 (Cowork·클라우드 세션 제외) |
| 프로젝트 Project | .claude/skills/<skill-name>/SKILL.md | 이 저장소의 세션. 커밋하면 팀도 받음 |
| 조직 Enterprise | 관리 설정 폴더 안 .claude/skills/ | 조직이 배포한 컴퓨터의 모든 사용자 |
| 플러그인 Plugin | <plugin>/skills/<skill-name>/SKILL.md | 플러그인을 켠 곳, /plugin-name:skill-name |
확인: 이번 실습은 팀과 나눌 것이므로 프로젝트 범위 .claude/skills/로 정했습니다.
3단계 · SKILL.md 쓰기
SKILL.md는 두 부분입니다. 위쪽 --- 사이의 YAML 머리말(frontmatter — 언제 이 스킬을 쓸지 알려 주는 짧은 설정)과, 그 아래 Claude 가 따를 본문입니다. 폴더 이름(또는 머리말의 name)이 내가 입력할 명령이 되고, description(설명)은 Claude 가 이 스킬을 자동으로 불러올지 판단하는 데 씁니다.
아래는 이 가이드가 만든 예시입니다. 폴더 이름 weekly-report와 내용은 예시 이름입니다.
mkdir -p .claude/skills/weekly-report
# .claude/skills/weekly-report/SKILL.md (예시)
---
description: 주간 보고를 정리한다. 사용자가 "주간 보고", "이번 주 정리", "보고서 초안"을 말할 때 사용.
---
## 이 작업 내내 지킬 것
- 팀 목표 파일의 목표 순서대로 묶는다.
- 사실만 쓰고, 추측은 "확인 필요"로 표시한다.
## 순서
1. 이번 주에 바뀐 파일과 진행 기록을 읽는다.
2. 목표별로 끝낸 일 · 진행 중 · 막힌 일 세 칸으로 정리한다.
3. 다음 주 할 일 세 가지를 제안한다.
① 설명에는 사람들이 실제로 말할 낱말을 넣습니다. ② 작업 내내 적용될 내용은 "한 번 하는 단계"가 아니라 계속 지킬 지시로 씁니다(예: "테스트를 돌려" 대신 "고칠 때마다 테스트를 돌려") — 스킬 본문은 불릴 때 대화에 한 번 들어가고, 이후 턴에 파일을 다시 읽지 않기 때문입니다. ③ 가장 중요한 지시를 맨 위에 둡니다 — 압축 뒤에는 앞부분만 남을 수 있습니다(막히면 참고).
확인: 파일이 .claude/skills/weekly-report/SKILL.md에 있고, --- 머리말에 description이 있습니다.
4단계 · 두 가지 방법으로 불러 보기
Claude Code 는 스킬 폴더의 변화를 지켜보므로, 세션 중에 .claude/skills/ 아래 스킬을 추가·수정하면 다시 시작하지 않아도 반영됩니다. 다만 세션을 시작할 때 없던 최상위 스킬 폴더를 새로 만들었다면 /reload-skills를 실행합니다.
- 있는지 확인
What skills are available?(뜻: 쓸 수 있는 스킬이 뭐가 있어?)라고 물어 목록에 보이는지 봅니다. - 자동으로 불리게 하기설명에 맞는 말로 부탁합니다. 예시: "이번 주 정리해서 주간 보고 초안 만들어 줘."
- 직접 부르기메시지 맨 앞에
/weekly-report를 씁니다. 원문에 따르면 이름은 메시지 맨 앞에 있어야 바로 실행되고, 일반 글 뒤에 쓰면 실행 허락으로만 받아들여집니다.
확인: 두 방법 모두에서 결과가 SKILL.md 의 순서(목표별 세 칸 → 다음 주 할 일 세 가지)를 따릅니다.
5단계 · 부작용이 있는 절차는 내가 부를 때만
배포·메시지 보내기처럼 되돌리기 어려운 절차는 Claude 가 스스로 시작하지 못하게 합니다. 머리말에 disable-model-invocation: true를 넣으면 내가 /이름을 입력할 때만 돕니다. 원문 예:
---
name: deploy
description: Deploy the application to production
disable-model-invocation: true
---
| 머리말 | 내가 부름 | Claude 가 부름 | 컨텍스트에 들어가는 때 |
|---|---|---|---|
| (기본) | 예 | 예 | 설명은 늘, 본문은 불릴 때 |
disable-model-invocation: true | 예 | 스스로는 못 함 | 설명도 평소엔 없음, 본문은 불릴 때 |
user-invocable: false | 아니오 | 예 | 설명은 늘, 본문은 불릴 때 |
user-invocable: false는 명령으로 실행할 일이 아닌 배경지식(원문 예: 옛 시스템 설명)에 씁니다.
확인: 부작용 있는 스킬이 있다면 disable-model-invocation: true를 넣었고, Claude 에게 "배포해 줘"라고 해도 직접 실행하지 않고 /deploy를 내가 실행하라고 안내합니다.
6단계 · 커밋해서 팀 전원에게
원문은 스킬을 나누는 방법으로 세 가지를 듭니다 — 프로젝트 스킬은 .claude/skills/를 버전 관리에 커밋, 플러그인은 skills/ 폴더, 조직 전체는 관리 설정으로 배포.
git add .claude/skills/weekly-report/SKILL.md
git commit -m "주간 보고 스킬 추가" # 커밋 메시지는 예시
이제 이 저장소를 받는 동료의 세션, 그리고 실습 6의 에이전트 팀 팀원도 이 스킬을 읽습니다 — 팀원은 프로젝트·사용자 설정에서 스킬을 불러옵니다.
스킬 본문 첫머리에 "팀 목표 파일을 먼저 읽는다"를 넣어 두면, 누가 이 절차를 돌리든 같은 목표에서 출발합니다. Claude Code 스킬은 여러 AI 도구가 함께 쓰는 Agent Skills 오픈 표준을 따르므로, 다른 도구로 옮길 때도 같은 폴더를 바탕으로 삼을 수 있습니다(어떤 머리말이 표준이고 어떤 것이 Claude Code 확장인지는 원문 표를 확인).
확인: 커밋 기록에 스킬 파일이 있고, 동료(또는 새 세션)에서 /weekly-report가 보입니다.
막히면
| 증상 | 해 볼 것과 확인 기준 |
|---|---|
| 스킬이 자동으로 안 불림 | ① 설명에 사람들이 실제로 말할 낱말이 있는지 ② What skills are available?에 보이는지 ③ 설명과 더 비슷하게 다시 부탁 ④ /이름으로 직접 부르기 ⑤ /이름도 인식 안 되면 이름에 쓸 수 없는 글자가 있는지 ⑥ paths를 설정했다면 대상 파일이 현재 작업 폴더 안인지. 머리말 YAML 이 깨지면 본문은 읽혀 /이름은 되지만 설명으로 맞추지 못합니다 — --debug로 실행해 오류를 봅니다. |
| 원치 않을 때도 불림 | 설명을 더 구체적으로 좁히거나, 직접 부를 때만 돌게 disable-model-invocation: true를 넣습니다. |
| 처음엔 따르다 나중에 안 따름 | 매번 반드시 지켜야 하는 규칙이면 훅(정해진 순간마다 자동으로 도는 명령)으로 옮깁니다. 판단해서 적용할 지침이면 작업 전체에 적용되게 고쳐 씁니다. 대화가 압축됐다면 스킬을 다시 불러 전체 내용을 되살립니다. |
| 스킬이 많아 설명이 잘림 | 스킬 목록은 컨텍스트 창의 1% 예산 안에 들어가야 해서, 넘치면 덜 쓰는 스킬부터 설명이 빠집니다. /doctor로 목록의 컨텍스트 비용을 보고, 설명은 핵심 용도를 맨 앞에 둡니다(항목당 1,536자 상한). |
| 개인 스킬 폴더가 사라짐 | ~/.claude/skills/.trash/를 봅니다. 기본 30일 뒤 정리되기 전에 폴더를 ~/.claude/skills/로 되돌립니다. |
압축 뒤 스킬은 얼마나 남나
자동 압축(대화가 길어지면 요약해 공간을 비우는 것) 때 Claude Code 는 각 스킬의 가장 최근 호출을 요약 뒤에 다시 붙이되, 스킬마다 처음 5,000 토큰만 남깁니다. 다시 붙는 스킬들은 합쳐서 25,000 토큰 예산을 나눠 쓰고, 가장 최근에 부른 스킬부터 채우므로 한 세션에서 스킬을 많이 불렀다면 오래된 스킬은 통째로 빠질 수 있습니다. 서브에이전트에 미리 실어 둔 스킬은 다르게, 시작할 때 전체 내용이 들어갑니다. 예전 형식인 .claude/commands/deploy.md도 /deploy를 만들고 그대로 작동하지만, 새 작업에는 보조 파일을 둘 수 있는 스킬을 권합니다.
다음에 할 것
- 여러 세션에 걸친 일은 스킬만으로는 진행 상황이 남지 않습니다 — 실습 8의 인수인계 노트를 함께 씁니다.
- 회사 팀 전체에 나누려면 공용 도구 연결·프로젝트 공유까지 — 실습 9.
- 원리와 더 많은 설정: 완전 가이드 만들기·부르는 방법·나누기·문제 해결.
- 같은 지시를 자꾸 붙여 넣거나 CLAUDE.md 가 절차로 길어지면 스킬로 옮깁니다.
- 팀이 같이 쓸 스킬은
.claude/skills/<이름>/SKILL.md에 두고 커밋합니다. 팀원·동료 세션이 같은 절차를 받습니다. - 설명엔 실제로 말할 낱말을, 본문엔 계속 지킬 지시를, 중요한 것은 맨 위에 씁니다.
- 부작용 있는 절차는
disable-model-invocation: true로 내가 부를 때만 돌게 합니다.
출처: https://code.claude.com/docs/en/skills · https://code.claude.com/docs/en/best-practices (Put team procedures in skills) · https://code.claude.com/docs/en/agent-teams (팀원이 읽는 스킬) (수집일 2026-11-10). 스킬 이름 weekly-report와 SKILL.md 내용·커밋 메시지는 이 가이드가 만든 연습용 예시입니다.
인수인계 노트로 여러 세션에 걸친 일 이어 가기
새 세션은 앞 세션을 기억하지 못합니다. 원문은 이것을 "교대 근무하는 엔지니어가 매번 앞 근무 기억 없이 출근하는 것"에 비유합니다. 이 실습에서는 진행 기록 파일과 기능 목록을 만들어 두고, 세션을 끝낼 때와 시작할 때 정해진 순서를 따라 다음 세션(또는 다른 에이전트)이 추측 없이 이어받게 합니다.
- 첫 세션에서 인수인계 노트(다음 세션·다른 에이전트가 이어받도록 남기는 진행 기록)와 기능 목록을 준비합니다.
- 한 번에 기능 하나씩 일하고, 세션 끝에 커밋과 진행 기록을 남깁니다.
- 새 세션을 원문의 "현황 파악" 순서로 시작해 이어 갑니다.
예상 소요 시간: 30~40분 (세션 두 번)
준비물을 보고 따라 하기 1·4·5단계(준비 → 끝낼 때 → 시작할 때)만 해도 흐름을 익힙니다. 다음 세션이 엉뚱하게 시작하면 막히면을 봅니다. 원리는 완전 가이드 진행 기록·시작 순서에 있습니다.
준비물과 완료 기준
- git 저장소인 프로젝트 폴더와 Claude Code. 원문은 git 기록을 진행 기록과 함께 "무엇을 했는지 파악하는 근거"로 씁니다.
- 한 세션에 끝나지 않을 만한 일 하나(원문 예: 웹 앱 만들기). 처음에는 기능 3~5개짜리 작은 일로 연습합니다.
- 원문 이름 그대로 쓸 파일: 진행 기록
claude-progress.txt, 기능 목록feature_list.json, 실행 스크립트init.sh(필요할 때).
두 번째 세션이 처음 몇 메시지 안에 진행 기록·기능 목록·git 기록을 스스로 읽고, 아직 안 끝난 기능 중 하나를 골라 일을 시작합니다. 그리고 끝낼 때 커밋과 진행 기록 갱신을 남깁니다.
따라 하기
1단계 · 첫 세션 — 이어받을 바탕부터 깔기
원문은 첫 세션에만 다른 지시를 줍니다. 본격적인 일보다 먼저, 앞으로의 모든 세션이 쓸 환경을 준비하게 합니다 — init.sh, 에이전트가 한 일을 적는 claude-progress.txt, 그리고 어떤 파일을 추가했는지 보여 주는 첫 git 커밋.
(예시) 아직 기능은 만들지 말고, 여러 세션에 걸쳐 이어 갈 준비만 해 줘.
1. 요청 내용을 끝에서 끝까지 확인할 수 있는 기능 목록으로 풀어
feature_list.json 에 적어. 모든 항목의 passes 는 false 로.
2. 개발 서버를 띄우는 init.sh 를 만들어.
3. claude-progress.txt 를 만들고 지금까지 한 일을 적어.
4. 추가한 파일을 git 에 첫 커밋으로 남겨.
확인: 세 파일이 생겼고 git log에 첫 커밋이 있습니다. 기능 목록의 모든 항목이 "passes": false입니다.
2단계 · 기능 목록은 JSON 으로, 고치는 칸은 하나만
원문은 에이전트가 일을 한 번에 다 하려 하거나, 일부만 해 놓고 "다 됐다"고 선언하는 문제를 막으려고 기능 목록을 썼습니다(예에서는 200개가 넘는 기능). 항목 하나의 원문 모양:
{
"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
}
뜻: "새 대화 버튼을 누르면 새 대화가 만들어진다" — 확인 순서 다섯 단계와, 통과 여부 칸.
원문은 이 파일을 passes 칸만 바꿔서 고치게 했고, "테스트를 지우거나 고치는 것은 기능 누락·버그로 이어질 수 있으므로 용납되지 않는다"처럼 강한 말로 지시했습니다. 마크다운보다 JSON 을 쓴 까닭은 모델이 JSON 파일을 부적절하게 바꾸거나 덮어쓸 가능성이 더 낮았기 때문입니다.
이 규칙("feature_list.json 은 passes 칸만 바꾼다")을 프로젝트 CLAUDE.md에 한 줄로 적어 두면 매 세션이 시작할 때 읽습니다(실습 2). 코딩이 아닌 일이라면 같은 모양으로 "할 일 · 확인 방법 · 완료 여부" 목록을 만들 수 있습니다 — 원문도 이 교훈의 일부나 전부가 과학 연구·재무 모델링 같은 다른 분야의 긴 작업에 적용될 가능성이 높다고 앞으로의 과제로 적었습니다.
확인: 지침에 "passes 칸만 바꾼다"가 들어갔습니다.
3단계 · 한 번에 기능 하나만
원문에서 결정적이었던 것은 기능 하나씩 일하게 한 것입니다. 한꺼번에 하려다 구현 중간에 컨텍스트가 바닥나면, 다음 세션은 반쯤 만들어지고 기록도 없는 상태에서 시작해 무슨 일이 있었는지 추측해야 했습니다.
(예시) feature_list.json 에서 아직 passes 가 false 인 것 중
가장 우선인 기능 하나만 골라 구현해 줘. 다른 기능은 건드리지 마.
사람이 쓰듯 끝에서 끝까지 확인한 뒤에만 passes 를 true 로 바꿔.
원문은 끝에서 끝까지 확인하지 않고 "완료"로 표시하는 경향도 실패 유형으로 듭니다. 웹 앱이라면 브라우저 자동화 도구로 사람처럼 시험하라고 명시했을 때 잘했습니다.
확인: 이번 세션에서 바뀐 passes는 하나뿐이고, 그 기능을 실제로 써 본 확인 결과가 대화에 있습니다.
4단계 · 세션을 끝낼 때 — 커밋과 진행 기록
원문은 바뀐 내용을 설명이 담긴 커밋 메시지로 git 에 커밋하고, 진행 파일에 요약을 쓰게 했을 때 가장 좋았다고 합니다. 그래야 잘못된 변경을 git 으로 되돌리고 작동하던 상태를 되찾을 수 있습니다. 끝낼 때의 목표는 "깨끗한 상태" — 큰 버그 없고, 정리되어 있어, 다음 사람이 엉뚱한 뒷정리 없이 새 기능을 시작할 수 있는 상태입니다.
(예시) 이번 세션을 마무리하자.
1. 오늘 바꾼 내용을 설명이 담긴 메시지로 커밋해.
2. claude-progress.txt 에 끝낸 일, 남은 일, 다음 세션이 먼저 볼 것을 적어.
확인: git log에 새 커밋이 있고, claude-progress.txt의 마지막에 오늘 날짜의 "끝낸 일 · 남은 일"이 있습니다.
5단계 · 새 세션을 열고 현황부터 파악하기
세션을 닫고 새로 엽니다. 원문은 매 세션이 일을 시작하기 전에 현황 파악 단계를 거치게 했습니다.
pwd지금 작업 중인 폴더를 확인합니다. 이 폴더 안의 파일만 고칠 수 있습니다.- git 기록과 진행 파일 읽기최근에 무엇을 했는지 파악합니다.
- 기능 목록 읽기아직 안 끝난 기능 중 가장 우선인 것을 고릅니다.
init.sh로 실행하고 기본 시험새 기능을 만들기 전에, 앞 세션이 고장 난 상태로 두지 않았는지 먼저 확인합니다. 고장 난 채로 새 기능을 시작하면 문제가 더 커집니다.
(예시) 일을 시작하기 전에 현황부터 파악해 줘.
pwd 확인 → claude-progress.txt 읽기 → feature_list.json 읽기 →
git log --oneline -20 → init.sh 로 실행해서 기본 기능 확인.
그다음 가장 우선인 미완료 기능 하나를 골라 이유와 함께 알려 줘.
원문이 보여 준 전형적인 세션 시작 모습도 같은 순서입니다 — pwd → claude-progress.txt 읽기 → feature_list.json 읽기 → git log --oneline -20 → 개발 서버 시작 → 기본 기능 확인 → 새 기능 시작.
확인: 새 세션이 내가 설명하지 않았는데도 앞 세션에서 끝낸 기능과 다음 기능을 맞게 말합니다.
6단계 · 팀에 쓰기 — 대화 대신 노트로 이어받기
실습 6에서 본 것처럼 팀원은 리더의 대화를 받지 못하고, /resume은 in-process 팀원을 되살리지 않습니다. 원문 컨텍스트 엔지니어링 글은 같은 생각을 "구조화된 메모"라고 부릅니다 — 에이전트가 컨텍스트 창 밖에 메모를 꾸준히 남기고 나중에 다시 불러오는 방법으로, Claude Code 의 할 일 목록이나 직접 만든 에이전트의 NOTES.md가 그 예입니다.
에이전트 팀으로 긴 일을 할 때는 생성 지시문에 "시작할 때 claude-progress.txt와 기능 목록을 읽고, 맡은 기능을 끝내면 진행 기록에 한 줄 남겨라"를 넣습니다. 기능마다 맡는 팀원을 나누면 원문이 경고한 "같은 파일을 두 팀원이 고쳐 덮어쓰는" 일도 줄어듭니다. 단, 진행 기록 파일 하나를 여러 팀원이 동시에 고치면 같은 문제가 생길 수 있으니 기록은 리더가 모아 쓰게 하는 편이 안전합니다.
확인: 다음에 팀을 띄울 때 쓸 생성 지시문에 "노트 읽기 → 일 → 노트 남기기"가 들어갔습니다.
막히면
원문은 긴 작업에서 자주 생긴 실패 네 가지와 해결을 표로 정리했습니다.
| 증상 | 첫 세션이 할 일 | 이후 세션이 할 일 |
|---|---|---|
| 프로젝트 전체를 너무 일찍 "끝났다"고 선언 | 요청을 끝에서 끝까지의 기능 설명으로 풀어 JSON 기능 목록을 만든다 | 시작할 때 기능 목록을 읽고, 기능 하나를 골라 일한다 |
| 버그가 남거나 기록 없는 진행이 남음 | git 저장소와 진행 기록 파일을 만든다 | 시작 때 진행 기록과 git 기록을 읽고 기본 시험을 돌린다. 끝날 때 커밋과 진행 기록을 남긴다 |
| 기능을 너무 일찍 완료로 표시 | 기능 목록을 만든다 | 모든 기능을 스스로 확인하고, 꼼꼼히 시험한 뒤에만 "통과"로 표시한다 |
| 앱 실행 방법을 알아내느라 시간을 씀 | 개발 서버를 띄우는 init.sh를 쓴다 | 시작할 때 init.sh를 읽는다 |
원문에 따르면 압축(대화가 길어지면 요약해 이어 가는 것)이 있어도 다음 에이전트에게 늘 완전히 분명한 지시가 넘어가지는 않습니다. 그래서 이어받을 내용은 대화가 아니라 파일에 둡니다.
직접 만든 앱이라면: Claude API 메모리 도구로 같은 패턴
Claude API 의 메모리 도구는 Claude 가 /memories 디렉터리의 파일을 만들고 읽고 고치게 해 대화를 넘어 기억하게 합니다. 파일 작업은 내 앱이 실행하므로 저장 위치는 내가 정합니다. 도구를 켜면 API 가 시스템 프롬프트에 "무엇보다 먼저 메모리 디렉터리를 보라"는 지시와 "컨텍스트 창은 언제든 초기화될 수 있다고 가정하라(ASSUME INTERRUPTION)"를 자동으로 넣습니다.
원문의 멀티 세션 패턴: ① 첫 세션이 본격적인 일 전에 진행 기록·기능 체크리스트·시작 스크립트 참조를 메모리 파일로 만든다 ② 이후 세션은 그 파일부터 읽는다 ③ 세션을 끝내기 전에 진행 기록을 갱신한다. 원칙은 같습니다 — 기능 하나씩, 코드를 썼을 때가 아니라 끝에서 끝까지 확인했을 때만 완료로 표시.
메모리 파일이 어지러워지면 원문 예시 문장(Note: when editing your memory folder, always try to keep its content up-to-date, coherent and organized. ...)으로 정리를 강조할 수 있습니다. 보안: 민감한 정보를 걸러 내는 검증을 추가하고, 모든 경로가 /memories 안인지 확인해 ../ 같은 경로 이탈을 막습니다. 오래 안 쓴 파일은 주기적으로 지웁니다.
다음에 할 것
- 회사 팀에서 같은 저장소를 여럿이 쓴다면 공용 도구 연결과 지침 관리까지 — 실습 9.
- 다음 세션이 지침이나 노트를 안 읽는 것 같으면 — 실습 10.
- 원리: 완전 가이드 긴 작업의 문제·기능 목록·실패 유형.
- 새 세션은 앞 세션을 기억하지 못하므로, 이어받을 내용은 진행 기록·기능 목록·git 기록 같은 파일에 둡니다.
- 첫 세션은 바탕(기능 목록·진행 기록·
init.sh·첫 커밋)만 깝니다. 기능 목록은 JSON, 고치는 칸은passes하나. - 한 번에 기능 하나, 끝에서 끝까지 확인한 뒤에만 완료. 끝낼 때 커밋과 진행 기록.
- 시작할 때는
pwd→ 기록 → 목록 → git 기록 → 기본 시험 → 새 기능 순서.
출처: 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·Security) · https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents (Structured note-taking) · https://code.claude.com/docs/en/agent-teams (팀원 맥락·한계) (수집일 2026-11-10). 한국어 프롬프트는 이 가이드가 만든 연습용 예시입니다.
회사 팀 — 공용 도구 연결(MCP) · 프로젝트 공유
회사 팀은 여러 사람과 여러 에이전트가 같은 도구와 같은 지침을 써야 합니다. 이 실습에서는 MCP 서버 하나를 프로젝트 범위로 연결해 저장소에 커밋하고, 코딩을 하지 않는 동료에게는 Claude 프로젝트를 공유하며, 조직 전체 지침은 어디에 두는지 정리합니다.
- MCP(AI 앱을 외부 도구·데이터에 잇는 표준 연결 방식 — 원문 비유로 "AI 앱용 USB-C 포트") 서버를 로컬·프로젝트·사용자 범위 중 알맞은 곳에 연결합니다.
- 비밀 값은 저장소에 넣지 않고
.mcp.json을 팀과 나눕니다. - Claude 프로젝트를 권한과 함께 공유하고, 큰 팀의 지침을 조직·프로젝트 범위로 나눕니다.
예상 소요 시간: 25~35분
준비물을 보고 따라 하기 1~4단계(범위 고르기 → 추가 → 커밋·승인 → 확인)를 합니다. 코딩을 안 하는 팀이라면 5단계만 해도 됩니다. 연결이 안 되면 막히면을 봅니다. 원리는 완전 가이드 MCP 범위·회사 팀에 있습니다.
준비물과 완료 기준
- 팀이 함께 쓰는 git 저장소(실습 2의 프로젝트
CLAUDE.md가 들어 있는 것)와 Claude Code. - 회사가 쓰는 원격 MCP 서버 주소 하나. 이 실습에서는 원문 예시 주소
https://example.com/mcp와 이름shared-server로 적습니다 — 실제 주소·이름으로 바꿉니다. - Claude 프로젝트를 공유하려면 Team 또는 Enterprise 요금제(원문 기준 공유는 이 두 요금제에서만).
저장소 루트에 .mcp.json이 커밋되어 있고, 동료(또는 저장소를 새로 받은 내 다른 폴더)에서 승인 후 claude mcp list에 그 서버가 연결됨으로 보입니다. 비밀 값은 파일에 직접 적혀 있지 않습니다. 코딩하지 않는 동료와는 Claude 프로젝트가 알맞은 권한으로 공유되어 있습니다.
따라 하기
1단계 · 이 도구는 누구와 나눌지 정하기
범위는 어느 프로젝트에서 서버가 읽힐지, 팀과 설정을 나눌지를 정합니다.
| 범위 | 읽히는 곳 | 팀과 공유 | 저장 위치 |
|---|---|---|---|
| 로컬 Local (기본) | 지금 프로젝트만 | 아니오 | ~/.claude.json |
| 프로젝트 Project | 지금 프로젝트만 | 예, 버전 관리로 | 프로젝트 루트의 .mcp.json |
| 사용자 User | 내 모든 프로젝트 | 아니오 | ~/.claude.json |
원문은 개인 개발 서버·실험 설정·버전 관리에 넣고 싶지 않은 자격 증명이 있는 서버는 로컬 범위에 두라고 합니다. 사용자 범위는 여러 프로젝트에서 자주 쓰는 개인 도구용입니다.
개인 팀(실습 4)의 도구는 사용자·로컬 범위에, 회사 팀이 같이 써야 하는 도구는 프로젝트 범위에 둡니다. 이렇게 나누면 개인 도구가 회사 저장소로 새어 들어가지 않고, 회사 저장소를 받은 사람·에이전트는 모두 같은 도구를 받습니다. 에이전트 팀의 팀원도 프로젝트·사용자 설정에서 MCP 서버를 읽습니다(실습 6).
확인: 연결할 서버를 "프로젝트 범위"로 정했고, 그 서버에 필요한 비밀 값(API 키 등)이 무엇인지 적었습니다.
2단계 · 프로젝트 범위로 추가하고, 비밀 값은 변수로
저장소 루트에서 원문 명령을 실행합니다. Claude Code 가 .mcp.json을 만들거나 고칩니다.
claude mcp add --transport http shared-server --scope project https://example.com/mcp
만들어진 .mcp.json 모양:
{
"mcpServers": {
"shared-server": {
"type": "http",
"url": "https://example.com/mcp"
}
}
}
서버에 API 키가 필요하면 값을 직접 쓰지 말고 환경 변수를 부릅니다. .mcp.json은 ${VAR}(변수 값)과 ${VAR:-default}(변수가 없으면 기본값)를 펼쳐 줍니다. 원문 예:
{
"mcpServers": {
"api-server": {
"type": "http",
"url": "${API_BASE_URL:-https://api.example.com}/mcp",
"headers": {
"Authorization": "Bearer ${API_KEY}"
}
}
}
}
각자 자기 컴퓨터에서 API_KEY를 정해 두면, 같은 파일을 나눠도 키는 저장소에 들어가지 않습니다.
확인: 명령이 Added ... 줄을 출력했고, .mcp.json에 키 값 자체가 아니라 ${...}만 있습니다.
3단계 · 커밋하고, 받은 사람은 한 번 승인
git add .mcp.json
git commit -m "팀 공용 MCP 서버 추가" # 커밋 메시지는 예시
원문은 .mcp.json을 버전 관리에 넣어 팀 전원이 같은 MCP 도구를 받게 하라고 합니다. 보안을 위해 대화형 세션에서는 .mcp.json의 프로젝트 범위 서버를 쓰기 전에 승인을 묻습니다. 받은 저장소가 스스로 자기 서버를 승인할 수는 없습니다 — 아직 승인하지 않은 서버는 claude mcp list에 ⏸ Pending approval (run `claude` to approve)로 보이고, 저장소 폴더에서 claude를 대화형으로 실행해 검토·승인합니다.
확인: 동료(또는 저장소를 새로 받은 폴더)에서 claude를 실행했을 때 승인을 묻는 창이 뜨고, 승인했습니다.
4단계 · 연결 상태 확인하기
claude mcp list # 설정된 서버와 상태
claude mcp get shared-server
/mcp # Claude Code 안에서 서버 상태 확인
claude mcp list는 서버마다 ✔ Connected(연결됨)·! Needs authentication(인증 필요)·✘ Failed to connect(연결 실패) 같은 상태를 보여 줍니다. 실패 표시는 목록 명령이 실패한 게 아니라 그 서버에 연결하지 못했다는 뜻입니다. 화면에는 ${VAR} 참조가 값 대신 이름으로 보입니다.
확인: shared-server가 ✔ Connected입니다. ! Needs authentication이면 그 서버의 인증을 마칩니다.
5단계 · 코딩하지 않는 동료에게는 Claude 프로젝트 공유
Claude 프로젝트는 자기 대화 기록과 지식 창고를 가진 독립된 작업 공간입니다. 프로젝트 지식에 문서·글·코드 등 파일을 올리면 그 프로젝트의 대화에서 Claude 가 배경으로 쓰고, 프로젝트 지침으로 말투나 관점을 정할 수 있습니다(원문 예: 더 격식 있는 말투, 특정 역할·업계의 관점).
- 지식과 지침 넣기실습 1의 팀 목표 파일과 팀 규칙 문서를 프로젝트 지식에 올리고, 프로젝트 지침에 답변 방식을 적습니다(예시).
- 공유 범위 고르기이메일로 특정 동료(개별), 이메일 목록으로 여러 명(일괄), 또는 조직 전체에 공개. 만든 뒤에도 바꿀 수 있습니다.
- 권한 고르기아래 표에서 고릅니다. 받은 사람은 Shared with me(나와 공유됨) 탭에서 찾고, 공유되면 이메일 알림을 받습니다.
| 권한 | 할 수 있는 것 |
|---|---|
| Can view 보기 | 프로젝트 내용·지식·지침을 보고 프로젝트 안에서 대화. 편집은 못 함 |
| Can edit 편집 | 프로젝트 지침과 지식 수정, 구성원 추가·제거, 구성원 설정 변경 |
목표·규칙 같은 "기준 문서"를 고치는 사람은 소수에게 Can edit 로, 나머지는 Can view 로 두면 모두가 같은 목표를 보되 기준이 흔들리지 않습니다. 저장소의 목표 파일을 고쳤다면 프로젝트 지식의 파일도 함께 바꿔 둘이 어긋나지 않게 합니다.
요금제·관리자 설정·새 버전 프로젝트
프로젝트는 무료 계정을 포함한 모든 사용자가 쓸 수 있고, 무료 사용자는 최대 5개까지 만듭니다. 공유는 Team·Enterprise 요금제에서만 됩니다. 유료 요금제에서는 프로젝트 지식이 컨텍스트 한도에 가까워지면 RAG(필요한 부분만 찾아 꺼내 쓰는 방식) 모드가 켜져 용량이 최대 10배까지 늘어납니다.
Owner 는 조직의 프로젝트 공유를 끌 수 있고(Enterprise 는 역할별로도), 공유를 끄면 공개 프로젝트도 꺼집니다. 꺼져 있으면 새로 공유할 수 없지만 기존 공유는 남습니다. Owner·Primary Owner 가 공개 프로젝트를 끄면 조직 전체 공유도 꺼집니다.
새 버전 프로젝트(베타)는 Claude Code 부터 단계적으로 배포 중입니다. 새 버전에서는 프로젝트가 하나의 대화이고, Claude 가 일을 클라우드의 병렬 스레드로 나눕니다. 모든 스레드는 프로젝트의 파일·저장소·지침·메모리로 시작합니다. 위 공유 설명은 현재 버전 기준입니다.
확인: 동료의 Shared with me 탭에 프로젝트가 보이고, 권한이 의도대로(Can view / Can edit)입니다.
6단계 · 큰 팀 — 조직 지침과 강제 규칙 나누기
지침 파일(CLAUDE.md 처럼 매 세션 시작 때 읽히는, 사람이 쓴 파일)도 범위가 있습니다. 회사 전체 규칙은 조직 범위, 저장소별 규칙은 프로젝트 범위에 둡니다.
원문은 조직 관리 CLAUDE.md 를 행동 지침에 쓰고, 반드시 막아야 하는 것은 관리 설정의 permissions.deny 같은 기술적 강제로 하라고 합니다. 설정 규칙은 Claude 가 어떻게 판단하든 클라이언트가 강제하지만, CLAUDE.md 지침은 행동을 이끌 뿐 강제 장치가 아닙니다.
| 하고 싶은 것 | 둘 곳 |
|---|---|
| 특정 도구·명령·파일 경로 막기 | 관리 설정 permissions.deny |
| 샌드박스 격리 강제 | 관리 설정 sandbox.enabled |
| 코드 스타일·품질 지침, 데이터 취급·규정 준수 안내, Claude 행동 지침 | 조직 관리 CLAUDE.md |
조직 CLAUDE.md 위치 · claudeMd 키 · 다른 팀 지침 빼기
조직 관리 CLAUDE.md 위치: macOS /Library/Application Support/ClaudeCode/CLAUDE.md, Linux·WSL /etc/claude-code/CLAUDE.md, Windows C:\Program Files\ClaudeCode\CLAUDE.md. MDM·Group Policy·Ansible 같은 구성 관리 도구로 배포합니다. 파일 대신 managed-settings.json의 claudeMd 키에 내용을 넣을 수도 있습니다(관리·정책 설정에서만 유효). 예: {"claudeMd": "Always run `make lint` before committing.\nNever push directly to main."}
큰 모노레포에서 상위 폴더의 다른 팀 CLAUDE.md 가 내 일과 무관하면 claudeMdExcludes로 경로·글롭 패턴을 지정해 뺍니다. 내 컴퓨터에만 적용하려면 .claude/settings.local.json에 둡니다. 조직 관리 CLAUDE.md 는 뺄 수 없습니다.
MCP 도 관리자가 managed-mcp.json으로 고정된 서버 묶음을 배포하거나, managedMcpServers로 모든 사용자에게 서버를 제공하고, allowedMcpServers·deniedMcpServers로 제한할 수 있습니다.
확인: "반드시 막아야 할 것"과 "따랐으면 하는 것"을 나눠 적었고, 앞의 것은 권한 설정 쪽으로 관리자에게 요청할 목록에 넣었습니다.
막히면
| 증상 | 해 볼 것과 확인 기준 |
|---|---|
⏸ Pending approval에서 안 넘어감 | 저장소 폴더에서 claude를 대화형으로 실행해 작업 공간 신뢰 창과 승인 창을 받아들입니다. 신뢰하지 않은 폴더에서는 저장소에 커밋된 .claude/settings.json의 자동 승인 설정이 무시됩니다. |
| 승인을 잘못 골랐음 | claude mcp reset-project-choices로 승인 선택을 초기화합니다. |
| 변수 누락 경고 | 참조한 변수가 없고 기본값도 없으면 설정은 읽히지만 claude mcp list에 경고가 나오고 ${VAR} 글자가 그대로 쓰입니다. 변수를 정하거나 :-default를 붙입니다. 빈 문자열로 정하면 "정해진 것"으로 쳐서 기본값이 쓰이지 않습니다. |
| 키를 넣었는데 401 로 거절됨 | 원격 서버의 url·headers에서 ANTHROPIC_API_KEY·ANTHROPIC_AUTH_TOKEN·클라우드 제공자 자격 증명 같은 변수는 일부러 빈 값으로 읽힙니다. 내 이름의 변수(예: API_KEY)로 복사해 그 이름을 씁니다. |
✘ Blocked by enterprise managed policy | 조직 정책이 그 서버를 막은 것입니다. 어떤 정책인지 관리자에게 묻습니다. |
| 같은 이름의 서버가 여러 곳에 있음 | 가장 우선인 정의 하나만 통째로 씁니다(필드를 섞지 않음). 우선순위: 로컬 → 프로젝트 → 사용자 → 플러그인 → claude.ai 커넥터. 조직의 managedMcpServers는 그보다 위입니다. |
| 프로젝트 공유 메뉴가 없음 | Team·Enterprise 요금제인지, 조직 Owner 가 프로젝트 공유를 꺼 두지 않았는지 확인합니다. |
원문에 따르면 claude -p 실행·Agent SDK 세션 등에서는 승인 창을 띄울 수 없어 프로젝트 범위 서버를 묻지 않고 읽습니다. 특정 서버를 막아야 한다면 disabledMcpjsonServers에 넣습니다 — 모든 권한 모드에서 막힙니다.
다음에 할 것
- 연결은 됐는데 에이전트가 지침·도구를 안 쓰는 것 같으면 — 실습 10.
- 개인 팀과 회사 팀을 나누는 전체 그림: 완전 가이드 나누는 법·강제할 것·보안, 연결 원리 공유·Claude 프로젝트.
- 회사 팀이 같이 쓸 MCP 서버는
--scope project로 추가해.mcp.json을 커밋합니다. 비밀 값은${VAR}로 부르고 각자 정합니다. - 받은 사람은 대화형
claude에서 한 번 승인하고,claude mcp list로 연결 상태를 봅니다. - 코딩하지 않는 동료에게는 Claude 프로젝트를 Can view / Can edit 권한으로 공유합니다(Team·Enterprise).
- 조직 지침은 관리 CLAUDE.md 로 안내하고, 반드시 막을 것은
permissions.deny같은 관리 설정으로 강제합니다.
출처: https://code.claude.com/docs/en/mcp · https://modelcontextprotocol.io/docs/getting-started/intro · https://support.claude.com/en/articles/9517075-what-are-projects · https://code.claude.com/docs/en/memory (Choose where to put CLAUDE.md files · Manage CLAUDE.md for large teams) (수집일 2026-11-10). 서버 이름·주소는 원문 예시, 커밋 메시지와 권한 배분 방법은 이 가이드의 예시·제안입니다.
막힘 해결 — 에이전트가 지침·기억을 안 따를 때
"분명 적어 뒀는데 안 따라요"는 대개 둘 중 하나입니다 — 그 글이 아예 읽히지 않았거나, 읽혔지만 지키게 만들 힘이 약했거나. 이 실습은 원문의 문제 해결 절차대로 먼저 "읽혔나"를 확인하고, 증상별로 고치는 순서를 따라갑니다.
/context all·/memory로 지금 세션에 어떤 지침 파일이 들어왔는지 확인합니다.- 지침 무시 · AGENTS.md 안 읽힘 · 파일이 너무 큼 ·
/compact뒤 사라짐 · 자동 메모리 내용 모름을 각각 고칩니다. - 스킬이 안 불리거나 팀원이 안 보일 때 어디를 볼지 압니다.
예상 소요 시간: 증상 하나당 5~15분
준비물을 보고 따라 하기 1·2단계(증상 적기 → 읽혔는지 확인)는 꼭 합니다. 그다음은 내 증상에 해당하는 단계만 봅니다. 증상 목록 전체는 막히면 표에 있습니다. 원리는 완전 가이드 지침 파일 문제 해결에 있습니다.
준비물과 완료 기준
- 지침을 안 따르는 것 같은 Claude Code 세션 하나와, 안 지켜진 지침 한 줄(예시: "보고서는 항상 목표 순서대로 정리한다").
- 그 지침이 들어 있는 파일의 경로(실습 1~4에서 만든
CLAUDE.md·CLAUDE.local.md·~/.claude/CLAUDE.md·AGENTS.md등). - 터미널에서
wc명령을 쓸 수 있으면 5단계가 빠릅니다.
문제의 원인을 "안 읽힘 / 읽혔지만 약함 / 압축으로 빠짐 / 다른 기능 문제" 중 하나로 짚고, 해당 고침을 적용한 뒤 같은 부탁을 다시 해서 지침대로 결과가 나옵니다.
따라 하기
1단계 · 증상을 한 줄로 적기
"안 돼요" 대신 무엇을 기대했고 무엇이 나왔는지 적습니다(예시).
(예시) 지침: "보고서는 항상 목표 순서대로 정리한다" (위치: ./CLAUDE.md 12번째 줄)
부탁: "이번 주 보고서 정리해 줘"
결과: 날짜 순서로 정리됨
언제부터: 대화가 길어진 뒤 / 처음부터 / 하위 폴더에서 일할 때
"언제부터"가 단서입니다. 처음부터 안 따랐다면 2~5단계, 대화가 길어진 뒤부터라면 6단계를 먼저 봅니다.
확인: 지침의 위치와 기대·실제 결과가 한 줄씩 적혀 있습니다.
2단계 · 그 지침 파일이 읽혔는지부터
/context all실행Memory files 목록에 시작 때 읽혀야 할CLAUDE.md·CLAUDE.local.md가 있는지 봅니다. 목록에 없으면 Claude 는 그 파일을 볼 수 없습니다./memory실행사용자·프로젝트 범위의 CLAUDE.md, CLAUDE.local.md, 그 밖의 메모리 파일 위치가 나열됩니다. 여기서 파일을 열어 고칠 수 있습니다.- 하위 폴더의 CLAUDE.md 라면작업 폴더의 하위 폴더에 있는 CLAUDE.md 는 시작 때가 아니라 필요할 때 읽히므로 Memory files 에 나오지 않습니다. 읽히면 터미널에 경로가 담긴
Loaded줄이 보입니다. 새 파일을 시험하려면 Claude 에게 쓰게 하지 말고 셸에서 직접 만든 뒤, 그 하위 폴더의 파일을 읽어 달라고 합니다.
Instruction file not loaded 알림이 뜨면 원문 오류 안내를 봅니다. 파일이 있어야 할 위치에 있는지도 확인합니다 — 작업 폴더 위쪽 경로의 CLAUDE.md·CLAUDE.local.md 는 시작 때, 하위 폴더 것은 필요할 때 읽힙니다.
확인: 문제의 파일이 Memory files 에 있다(→ 3단계) 또는 없다(→ 4·5단계)를 판정했습니다.
언제 어떤 파일이 읽혔는지 기록으로 남기기
InstructionsLoaded 훅을 쓰면 어떤 CLAUDE.md·rules 파일이 언제, 왜 읽혔는지 기록할 수 있습니다. 경로별 규칙이나 하위 폴더에서 늦게 읽히는 파일을 추적할 때 유용합니다.
3단계 · 읽혔는데 안 따를 때 — 지키게 만들기
원문에 따르면 CLAUDE.md 내용은 시스템 프롬프트의 일부가 아니라 그 뒤의 사용자 메시지로 전달됩니다. Claude 는 읽고 따르려 하지만, 특히 모호하거나 서로 부딪치는 지침은 엄격히 지킨다는 보장이 없습니다.
- 더 구체적으로. 원문 예: "코드를 보기 좋게 정리해" 보다 "들여쓰기는 공백 2칸"이 낫습니다.
- 충돌 찾기. 두 파일이 같은 행동에 다른 지침을 주면 Claude 는 아무거나 하나를 고를 수 있습니다. 사용자·프로젝트·로컬 파일을 나란히 열어 비교합니다.
- 내장 지침과 겹치는지. CLAUDE.md 에 커밋·PR 규칙을 적었다면
includeGitInstructions로 내장 지침을 끄고attribution으로 표시 문구를 정합니다. - 특정 순간에 반드시 해야 하는 일은 훅으로. "커밋할 때마다", "파일을 고칠 때마다"처럼 정해진 시점의 일은 훅(정해진 순간마다 셸 명령으로 자동 실행되는 장치)으로 씁니다. 훅은 Claude 의 판단과 상관없이 실행됩니다.
반드시 막아야 할 것(특정 명령·파일 접근)은 지침 문장이 아니라 권한 규칙·훅으로 막습니다 — 회사 팀이라면 실습 9의 관리 설정 permissions.deny.
확인: 지침을 구체적인 한 문장으로 고치거나 충돌을 지웠고, 같은 부탁을 다시 했을 때 지침대로 나옵니다. 그래도 안 되면 훅이 필요한 지침인지 판단했습니다.
시스템 프롬프트 수준으로 주고 싶다면
--append-system-prompt를 실행할 때 넘기면 시스템 프롬프트 수준의 지시가 됩니다. 실행 때마다 넘겨야 하므로 대화형보다는 스크립트·자동화에 알맞습니다.
4단계 · AGENTS.md 가 안 읽힐 때
저장소에 AGENTS.md가 있는데 Claude 가 그 내용을 모르는 것 같다면, 흔한 원인은 프로젝트 경로 어딘가의 CLAUDE.md입니다. 기본값으로 Claude 는 작업 폴더나 그 위쪽에 CLAUDE.md·CLAUDE.local.md가 없을 때만 AGENTS.md를 읽습니다.
- CLAUDE.md 찾기작업 폴더와 그 위쪽에
CLAUDE.md·.claude/CLAUDE.md·CLAUDE.local.md가 있는지 봅니다(~/.claude/CLAUDE.md는 제외). 있다면 Project instructions 설정을claude-md-and-agents-md로 두지 않는 한 그 파일을 대신 읽습니다. - 설정 확인
/config로 설정 화면을 열어 Project instructions가claude-md나managed-only가 아닌지 봅니다. 설정이 아예 안 보이면 그 세션은 AGENTS.md 를 읽을 수 없는 세션입니다. - 읽혔는지 보기
/memory목록에 AGENTS.md 경로가 있는지 봅니다.
CLAUDE.md 도 유지하고 싶거나 AGENTS.md 를 읽을 수 없는 세션이라면, AGENTS.md 옆에 그것을 불러오는 CLAUDE.md 를 둡니다(@AGENTS.md 한 줄로 import).
확인: /memory 목록에 AGENTS.md(또는 그것을 불러오는 CLAUDE.md)가 보입니다.
버전 조건
claude --version이 v2.1.277 이상인지 확인합니다. v2.1.281 이전에는 Amazon Bedrock 이나 텔레메트리를 끈 세션 등 일부에서 AGENTS.md 를 읽지 못했으므로 v2.1.281 이상으로 올립니다. v2.1.280 이전에는 /memory·/context가 직접 읽은 AGENTS.md 를 나열하지 않았으니, 그 버전에서는 Claude 에게 프로젝트 지침이 뭐라고 하는지 물어 확인합니다.
5단계 · 지침 파일이 너무 크거나 끝부분이 무시될 때
원문: 200줄이 넘는 파일은 컨텍스트를 더 쓰고 지키는 정도가 떨어질 수 있습니다. 4 MiB 가 넘는 파일은 통째로 건너뜁니다. 권장 길이를 넘으면 시작할 때와 /status에서 경고가 나옵니다.
- 특정 파일에만 필요한 지침은 경로별 규칙(
.claude/rules/,paths:머리말)으로 옮겨 맞는 파일을 다룰 때만 읽히게 합니다. - 매 세션 필요 없는 내용은 지웁니다. 절차라면 스킬로 옮깁니다(실습 7).
@path불러오기로 쪼개는 것은 정리에만 도움이 됩니다 — 불러온 파일도 함께 읽히므로 컨텍스트는 줄지 않습니다./doctor점검은 커밋된 CLAUDE.md 에서 코드에서 알아낼 수 있는 내용(폴더 구조·의존성 목록·구조 개요)을 줄이고, 함정·이유·기본값과 다른 규칙은 남기는 손질을 제안합니다.
하위 폴더 CLAUDE.md 의 끝이 무시된다면: 필요할 때 읽히는 파일(하위 폴더의 CLAUDE.md·CLAUDE.local.md 와 그 import, 하위 폴더 .claude/rules/, 경로별 규칙)은 파일당 크기 한도가 있어 넘으면 앞부분만 받습니다. 한도는 200K 컨텍스트 창에서 40,000자입니다.
wc -m path/to/CLAUDE.md # 글자 수 세기
확인: 문제 파일이 200줄 아래(하위 폴더 파일은 글자 수 한도 아래)이고, 시작 때 길이 경고가 사라졌습니다.
컨텍스트 창별 한도 · 여러 파일 합계 경고
1M 컨텍스트 창: Claude Opus 4.6·Sonnet 4.6 은 200,000자, 그 뒤 모델은 150,000자. 넘으면 파일을 줄이거나 일부를 rules 파일 여러 개로 옮깁니다 — 각자 따로 한도를 셉니다. 한도를 넘은 파일의 앞부분 끝에는 나머지를 Read 도구로 읽으라는 메모가 붙고, Claude 가 읽기 전까지 뒷부분 지침은 컨텍스트에 없습니다(v2.1.309 이전에는 이 한도가 적용되지 않았음). 하나하나는 권장 길이 안이어도 시작 때 합계가 한도를 넘으면 경고가 나오며, CLAUDE.md·rules 파일·@path import 는 각각 별도 파일로 셉니다.
6단계 · /compact 뒤 지침이 사라졌을 때
압축(대화가 길어지면 요약해 공간을 비우는 것, 명령은 /compact) 뒤에 무엇이 남는지는 지침을 둔 곳에 따라 다릅니다.
사라진 지시가 대화에서만 말한 것이라면 CLAUDE.md 에 적어 둡니다. 하위 폴더 CLAUDE.md 나 경로별 규칙이라면 그 폴더의 파일을 다시 다루면 다시 읽힙니다. 스킬을 따르다 멈췄다면 스킬을 다시 부르고, 중요한 지시는 SKILL.md 맨 위로 옮깁니다.
확인: 같은 지시를 대화가 아니라 파일(프로젝트 루트 CLAUDE.md 등)에 두었고, /compact 뒤에 다시 부탁해도 지시대로 나옵니다.
7단계 · 자동 메모리가 무엇을 저장했는지 모를 때
자동 메모리(auto memory — 내가 아니라 Claude 가 스스로 적는 메모)는 /memory에서 자동 메모리 폴더를 골라 볼 수 있습니다. 모두 평범한 마크다운이라 읽고, 고치고, 지울 수 있습니다. 대화 중 "Saved 2 memories"·"Recalled 2 memories" 같은 표시는 Claude 가 ~/.claude/projects/<project>/memory/를 고치거나 읽고 있다는 뜻입니다.
memory 필드)는 따로 된 폴더입니다.팀 모두가 알아야 할 내용이 자동 메모리에만 있다면, 그것은 Claude 한 세션의 메모일 뿐 팀의 기준이 아닙니다 — 팀원·서브에이전트에게도 닿게 CLAUDE.md 로 옮깁니다. 원문도 "CLAUDE.md 에 넣어"라고 직접 말하면 지침 파일에, "기억해"라고 하면 자동 메모리에 저장된다고 구분합니다.
확인: 자동 메모리 폴더를 열어 보았고, 팀 기준이어야 할 항목은 CLAUDE.md 로 옮겼으며 틀린 항목은 지웠습니다.
8단계 · 지침이 아니라 스킬·팀 기능 문제라면
- 설명 낱말설명에 사람들이 실제로 말할 낱말이 있는지 봅니다.
- 목록 확인
What skills are available?에 보이는지 봅니다. - 직접 부르기메시지 맨 앞에
/스킬이름. 이것도 안 되면 이름에 쓸 수 없는 글자가 있는지, 머리말 YAML 이 깨졌는지(--debug) 봅니다. - 스킬이 많다면목록 예산 때문에 설명이 잘렸을 수 있습니다 —
/doctor.
자세한 내용은 실습 7 막히면.
- 패널 보기기본 표시 방식에서 팀원은 입력 칸 아래 에이전트 패널에 나옵니다. 화살표로 고르고 Enter.
- 숨겨졌을 뿐인지모두 쉬면 쉬는 줄은 30초 뒤 숨겨집니다. 이름으로 메시지를 보내면 다시 보입니다.
- 과제 크기팀을 만들지는 Claude 가 과제를 보고 정합니다. 충분히 복잡한 과제인지 봅니다.
- 분할 창을 요청했다면
which tmux로 tmux 가 PATH 에 있는지, iTerm2 라면it2CLI 와 Python API 가 켜졌는지 봅니다.
자세한 내용은 실습 6 막히면.
확인: 스킬이 목록에 보이고 직접 부르면 돌거나, 팀원이 패널에 다시 보입니다.
막히면
증상별로 어느 단계를 볼지 모았습니다.
| 증상 | 먼저 할 것 | 단계 |
|---|---|---|
| CLAUDE.md 를 안 따름 | /context all의 Memory files 확인 → 구체화·충돌 제거 → 반드시 지킬 것은 훅 | 2·3 |
| AGENTS.md 가 안 읽힘 | 경로의 CLAUDE.md 확인 → /config의 Project instructions → @AGENTS.md import | 4 |
| CLAUDE.md 가 너무 큼 | 200줄 아래로 · 경로별 규칙 · /doctor | 5 |
| 하위 폴더 CLAUDE.md 끝이 무시됨 | wc -m으로 글자 수 → 한도 넘으면 줄이거나 rules 로 나누기 | 5 |
/compact 뒤 지침이 사라짐 | 대화로만 준 지시를 루트 CLAUDE.md 로 | 6 |
| 자동 메모리가 뭘 저장했는지 모름 | /memory → 자동 메모리 폴더 열기 | 7 |
| 스킬이 안 불림 · 너무 자주 불림 · 중간에 안 따름 | 설명 낱말 · disable-model-invocation · 다시 부르기 | 8, 실습 7 |
| 팀원이 안 보임 · 서브에이전트로 뜸 · 일찍 멈춤 | 패널·숨김 확인 · 에이전트 팀을 명시해 다시 부탁 · 직접 추가 지시 | 8, 실습 6 |
다음에 할 것
- 고친 지침이 다시 흐트러지지 않게, 원문대로 CLAUDE.md·하위 폴더 CLAUDE.md·
.claude/rules/를 주기적으로 훑어 오래되거나 서로 부딪치는 지침을 지웁니다. Claude 에게 찾게 하려면/doctor prompt-audit를 실행합니다 — 고칠 제안 보고서만 나오고, 적용하라고 하기 전에는 파일이 바뀌지 않습니다(v2.1.283 이상). - 반드시 지켜야 하는 규칙 목록은 관리자와 권한 설정으로 옮깁니다 — 실습 9 6단계.
- 원리: 완전 가이드 지침 파일 문제 해결·자동 메모리 점검·스킬 문제 해결·강제할 것.
- 먼저 읽혔는지 봅니다 —
/context all의 Memory files 와/memory목록. - 읽혔는데 안 따르면 더 구체적으로, 충돌을 지우고, 정해진 순간에 꼭 해야 할 일은 훅으로 옮깁니다. 지침 파일은 강제 장치가 아닙니다.
- AGENTS.md 는 경로에 CLAUDE.md 가 있으면 기본으로 안 읽힙니다. 200줄 넘는 지침은 줄이고, 대화로만 준 지시는
/compact뒤 사라질 수 있으니 파일에 둡니다. - 자동 메모리는
/memory에서 열어 보고, 팀 기준이 될 내용은 CLAUDE.md 로 옮깁니다.
출처: https://code.claude.com/docs/en/memory (Troubleshoot memory issues · Auto memory · /memory) · https://code.claude.com/docs/en/skills (Troubleshooting · Skill content lifecycle) · https://code.claude.com/docs/en/agent-teams (Troubleshooting) (수집일 2026-11-10). 예시 지침 문장과 증상 기록 양식은 이 가이드가 만든 연습용 예시입니다.