클로드 코드 팀 운영법, 폴더 하나에 역할 하나 만드는 법

클로드 코드 팀 운영법을 28단계로 알려 드립니다. 세션(클로드 코드 창) 하나를 책상 하나로 보고, 역할마다 폴더를 따로 만들어 규칙 파일(CLAUDE.md)을 나눠 두는 방식입니다. 설계 승인과 실서비스 배포 같은 큰 결정만 사람이 맡습니다.

별도 프레임워크나 서비스 없이 폴더, 마크다운 파일, 세션 사이의 메시지만 씁니다. 규칙이 파일로 남기 때문에 모델이 바뀌어도 그대로 이어서 쓸 수 있습니다.

이런 방식이 필요한 경우

세션 한두 개를 가끔 쓴다면 이렇게까지 나눌 필요는 없습니다. 같은 종류의 일을 여러 세션이 반복하면서 품질을 지켜야 할 때 쓰는 구조입니다. 장점은 세 가지입니다.

• 과제 하나에 세션 하나라서 대화가 서로 섞이지 않습니다.
• 한 세션이 배운 것이 파일로 남아 다른 세션도 바로 씁니다.
• 설계에 사람이 OK하기 전에는 코드를 짜지 않으므로 엉뚱한 방향으로 토큰을 쓰는 일이 줄어듭니다.

반대로 큰 작업 중간마다 사람이 끼어들기 때문에 속도는 느려집니다. 그 대신 한참 잘못된 방향으로 가는 일은 막을 수 있습니다.

시작 전에 확인할 것

• 클로드 코드를 실행할 수 있는 터미널. 설치와 로그인은 공식 설치 문서(code.claude.com/docs/ko/setup)를 따릅니다. 이 글은 역할마다 터미널 탭을 하나씩 엽니다.
• 같은 종류의 일을 여러 세션이 반복해야 하는 상황.
• 폴더 구조의 예시는 아래와 같습니다. 이름은 바꿔도 되고, 워커 폴더는 필요한 만큼만 만듭니다.

my-team/
├─ CLAUDE.md          팀 공통 규칙 (모든 세션이 읽음)
├─ MEMORY.md          규칙 목차: 한 줄에 하나, 120줄 안, 새 규칙은 맨 위
├─ HANDBOOK.md        두 번 나온 지적이 올라가는 정식 규칙
├─ QUALITY_GATES.md   넘기기 전 관문 5칸
├─ tools/             권한을 막아 둔 도구 (deploy.py 등)
├─ leader/            대장: 승인 요청 · 배정 · 2차 검수 · 테스트 서버 배포 (STATUS.md, inbox/)
├─ reviewer/  designer/  docs/
└─ worker-01 … 12/    작업 (tasks/과제명/INTENT.md)

1부. 폴더 뼈대 만들기

폴더는 파일 탐색기에서 만들어도 되고, 터미널에서 한 번에 만들어도 됩니다. 맥과 리눅스의 터미널(또는 윈도우의 Git Bash) 기준입니다.

mkdir -p my-team/{leader,reviewer,designer,docs,worker-01,tools}

1단계. 맨 위 팀 폴더 my-team을 만듭니다. 확인: 빈 팀 폴더가 생깁니다.

2단계. 팀 폴더 안에 대장 역할 폴더 leader를 만듭니다. 확인: my-team/leader 폴더가 있습니다.

3단계. 팀 폴더 안에 검수 역할 폴더 reviewer를 만듭니다. 확인: my-team/reviewer 폴더가 있습니다.

4단계. 팀 폴더 안에 화면 담당 폴더 designer를 만듭니다. 확인: my-team/designer 폴더가 있습니다.

5단계. 팀 폴더 안에 문서 담당 폴더 docs를 만듭니다. 확인: my-team/docs 폴더가 있습니다.

6단계. 팀 폴더 안에 실제 작업을 하는 워커 폴더를 만듭니다. 예시는 worker-01부터 12까지입니다. 개수는 필요한 만큼 정하면 되고, 처음에는 1~2개로 시작해도 충분합니다. 확인: worker-01 같은 폴더가 있습니다.

2부. 규칙 파일 만들기

클로드 코드는 실행한 폴더와 그 위 폴더들의 CLAUDE.md를 모두 읽어 한꺼번에 컨텍스트에 넣습니다. 그래서 맨 위에는 팀 공통 규칙, 아래 폴더에는 역할 규칙을 둡니다. 위 폴더 파일이 먼저, 아래 폴더 파일이 나중에 들어갑니다.

7단계. 팀 폴더 맨 위에 팀 공통 규칙 파일 CLAUDE.md를 만듭니다. 경로는 my-team/CLAUDE.md입니다. 확인: 이 폴더 아래 모든 세션이 이 파일을 읽습니다.

8단계. 역할 폴더마다 역할 규칙 CLAUDE.md를 만듭니다. 예를 들어 worker-01/CLAUDE.md입니다. 확인: worker-01에서 실행하면 공통 규칙과 역할 규칙이 함께 들어옵니다.

9단계. 역할 규칙에 "할 일" 칸을 씁니다. 확인: 그 역할이 맡은 일이 적혀 있습니다.

10단계. 역할 규칙에 "하지 않을 일" 칸을 씁니다. 이 칸이 있어야 남의 일을 덜 건드립니다. 확인: 하지 않을 일이 적혀 있습니다.

CLAUDE.md는 한 파일을 200줄 안쪽으로 유지하는 것이 공식 권장입니다. 길어지면 지침이 잘 지켜지지 않으니 역할 규칙은 짧게 씁니다.

3부. 팀 공통 파일 만들기

11단계. 팀 폴더에 MEMORY.md를 만듭니다. 규칙 목차 파일입니다. 한 줄에 하나, 120줄 안, 새 규칙은 맨 위에 둡니다. 확인: my-team/MEMORY.md가 있습니다.

이 파일은 클로드 코드의 자동 메모(auto memory)와 이름만 같은 직접 만든 파일입니다. 세션이 시작할 때 읽히려면 팀 공통 CLAUDE.md에서 불러오도록 한 줄 적어 둡니다. 클로드 코드의 @경로 가져오기 문법입니다.

@MEMORY.md
@HANDBOOK.md

12단계. 팀 폴더에 HANDBOOK.md를 만듭니다. 두 번 나온 지적이 올라가는 정식 규칙 파일입니다. 확인: my-team/HANDBOOK.md가 있습니다.

13단계. 팀 폴더에 QUALITY_GATES.md를 만듭니다. 넘기기 전에 거치는 관문 5칸은 테스트, 린트(코드 형식 검사), 화면, 문서, 보고입니다. 확인: my-team/QUALITY_GATES.md가 있습니다.

4부. 세션 열기

14단계. 터미널 탭을 하나 엽니다. 확인: 새 탭이 열립니다.

15단계. 그 탭에서 역할 폴더(예: leader)로 들어갑니다. cd my-team/leader처럼 입력합니다. 확인: 현재 위치가 해당 역할 폴더입니다.

16단계. 클로드를 실행합니다.

claude

확인: 이 세션이 곧 그 역할의 세션이 됩니다. 세션 이름은 /rename leader처럼 붙여 두면 다른 세션이 이름으로 부르기 쉽습니다.

17단계. 역할마다 탭을 따로 열어 14~16단계를 반복합니다. 확인: 책상 하나가 세션 하나인 상태로 역할별 세션이 떠 있습니다.

5부. 과제 하나 돌리기: 로그인 화면 개선 예시

18단계. 과제를 리더 세션에 입력합니다. 확인: 리더가 바로 시작하지 않고, 방향을 두세 가지로 묶어 먼저 물어봅니다.

19단계. 리더가 띄운 선택지에서 하나를 고릅니다. 확인: 리더가 비어 있는 워커에게 메시지로 일을 배정합니다.

20단계. 배정받은 워커 세션이 작업 폴더에 INTENT.md를 만드는지 봅니다. 경로는 worker-NN/tasks/과제명/INTENT.md입니다. 확인: 사람이 한 말 원문, 하지 말라고 한 것, 결정 기록이 들어 있습니다. 항목은 목표, 지시 원문, 하지 않을 것, 결정 기록으로 나누면 됩니다.

21단계. 워커가 보낸 설계안을 읽습니다. 확인: 설계안이 도착해 있습니다.

22단계. 설계안에 OK합니다. 순서가 고정입니다. 사람이 OK하기 전에는 코드를 짜지 않습니다. 확인: OK 후에 워커가 구현을 시작합니다.

6부. 검수 두 번과 배포

23단계. 워커가 관문 5칸을 채운 표를 리더에게 보고하는지 확인합니다. 관문 5칸은 테스트, 린트, 화면, 문서, 보고입니다. 확인: 표가 리더에게 붙어 도착합니다.

24단계. 리더가 같은 표로 한 번 더 확인하는지 봅니다. 테스트가 하나라도 실패하거나 휴대폰 화면에서 버튼이 겹치면 바로 반려합니다. 어디서, 무엇이, 어떤 기준에 걸렸는지 한 줄로 적어 돌려보냅니다. 확인: 반려 사유가 한 줄로 적혀 있습니다.

25단계. 반려됐다면 워커가 고쳐 다시 보고하게 합니다. 확인: 고쳐서 통과합니다.

26단계. 테스트 서버 배포는 리더가 하게 둡니다. 확인: 테스트 서버에 배포됩니다.

27단계. 실서비스 배포는 사람이 직접 합니다. 확인: 배포 명령을 사람이 실행합니다.

7부. 권한은 도구로 막기

28단계. 배포 도구에서 실서비스 옵션을 아예 뺍니다. CLAUDE.md에 "하지 말라"고 써 두는 것만으로는 부족할 때가 있습니다. CLAUDE.md는 클로드에게 주는 지침일 뿐 강제되는 설정이 아니기 때문입니다. 그래서 배포 도구 자체에서 실서비스 선택지를 없앱니다. 예시는 tools/deploy.py에서 선택 가능한 값을 staging 하나로 제한하는 방식입니다.

import argparse

parser = argparse.ArgumentParser()
parser.add_argument("target", choices=["staging"])
args = parser.parse_args()
print(f"{args.target} 서버에 배포합니다")

확인: 실수로 production을 넣어도 도구가 그런 선택지는 없다고 막습니다. 되돌리기 어려운 명령을 도구 쪽에서 먼저 막아 두는 것입니다.

특정 명령을 실행 자체에서 막고 싶다면 클로드 코드의 PreToolUse 훅(도구를 쓰기 직전에 검사하는 설정)이나 권한의 deny 규칙을 함께 씁니다. 공식 문서도 어떤 지침에도 상관없이 막아야 하는 동작은 훅으로 막으라고 안내합니다.

운영 규칙

단계는 아니지만 함께 정해 두면 좋은 운영 방식입니다.

• 세션끼리는 클로드 코드의 세션 간 메시지로 주고받습니다. 같은 컴퓨터에서 내가 띄운 세션끼리 클로드가 서로 메시지를 보내는 기능으로, Claude Code 2.1.224 이상(윈도우는 2.1.234 이상)에서 따로 켤 필요 없이 쓸 수 있습니다. 리더가 꺼져 있을 때는 리더 폴더의 inbox 파일로 남깁니다.
• 메시지는 짧게 쓰고 자세한 내용은 파일 경로로 넘깁니다.
• 세션은 끝나면 대화를 잊으므로 기억은 파일로 남깁니다. 과제마다 INTENT.md, 팀 전체는 MEMORY.md입니다.
• 사람이 지적하면 그 세션이 MEMORY.md 맨 위에 한 줄로 적습니다. 같은 지적이 두 번 나오면 리더가 HANDBOOK.md의 정식 규칙으로 올립니다.
• MEMORY.md는 세션이 시작할 때마다 읽히니 120줄 안으로 묶습니다. 넘으면 겹치는 줄을 합치고 오래된 것은 HANDBOOK으로 옮깁니다.

메시지와 캐시

메시지를 받을 때마다 세션은 지금까지의 대화를 다시 읽습니다. 토큰이 많이 들 것 같지만 앞부분은 캐시(이미 읽은 내용을 싸게 다시 읽는 장치)에서 읽습니다. API 가격표 기준으로 캐시에서 읽는 입력은 기본 입력 단가의 10분의 1입니다. Opus 5.5와 Sonnet 5.5는 20분의 1, Fable 5.1은 40분의 1까지 내려갑니다(2026년 10월 공식 가격표 기준). 구독 요금제의 사용 한도는 계산 방식이 다르니 가격표는 참고로만 봅니다.

• 가격표: platform.claude.com/docs/en/about-claude/pricing
• CLAUDE.md 읽는 방식: code.claude.com/docs/en/memory

공식 기능과의 관계

이 글의 방식은 사람이 폴더와 파일로 직접 만드는 구조입니다. 클로드 코드에는 비슷한 목적의 공식 기능도 있습니다. 하나는 한 세션이 팀원 세션을 띄워 공유 작업 목록으로 일을 나누는 에이전트 팀(agent teams)인데, 실험 기능이라 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1을 설정해야 켜지고 토큰을 훨씬 많이 씁니다. 다른 하나는 위에서 말한 세션 간 메시지입니다. 처음에는 역할 2~3개로 폴더 방식을 써 보고, 팀원 수가 늘면 공식 기능을 비교해 봅니다.

써 본 뒤 알아 둘 점

• 누가 무엇을 하는지 폴더만 봐도 보이고, 같은 말을 두 번 할 일이 줄어듭니다.
• 큰 작업 중간마다 사람이 끼어드는 것은 장점이자 단점입니다. 느려지지만 엉뚱한 방향으로 한참 가는 일은 없습니다.
• 규칙이 계속 늘어나는 것은 괜찮습니다. 메모리 목차만 짧게 유지하면서 중간중간 정리합니다.
• 세션 하나하나를 세밀하게 제어하며 운영하고 싶을 때 맞는 방식입니다. 역할 이름과 관문 칸만 바꾸면 영상 편집 같은 콘텐츠 작업에도 쓸 수 있습니다.

막히는 곳과 대처

• 세션이 남의 일을 건드리면: 역할 규칙에 "하지 않을 일" 칸을 씁니다.
• CLAUDE.md에 하지 말라고 써도 위험하면: 도구 자체에서 선택지를 막고, 필요하면 훅이나 deny 규칙을 더합니다.
• MEMORY.md가 너무 길면: 120줄 안으로 정리하고 오래된 것은 HANDBOOK으로 옮깁니다.
• 새 세션이 팀 규칙을 모르는 것 같으면: 세션을 역할 폴더에서 켰는지 확인하고, 공통 CLAUDE.md의 @MEMORY.md 줄이 있는지 봅니다.

체크리스트

• my-team 폴더와 역할 폴더가 만들어졌다
• 공통 CLAUDE.md와 역할 CLAUDE.md(할 일 / 하지 않을 일)가 있다
• MEMORY.md, HANDBOOK.md, QUALITY_GATES.md가 있다
• 역할별 터미널 탭에서 세션이 열린다
• 설계안에 OK하기 전에는 코드가 시작되지 않는다
• 배포 도구에서 실서비스 옵션이 빠져 있다