시리즈: 클로드 코드 Team 기능 완전 가이드 (총 9편) | 9편
표준 템플릿과 도입 로드맵 - Team 기능을 조직에 안착시키기
9편의 시리즈를 달려오면서 Team 기능의 구조부터 운영 전략까지 다뤘어요. 마지막 편에서는 CLAUDE.md를 팀의 공통 헌법으로 설계하는 법, 스폰 프롬프트 필수 4요소, 태스크 분해 템플릿, 그리고 개발/리서치/보안 역할별 도입 전략까지 실전 착수에 필요한 모든 걸 정리해 드릴게요.
Summary
- CLAUDE.md는 팀의 "공통 헌법"으로, 프로젝트 목표/금지 사항/표준 테스트 커맨드를 담아요
- 스폰 프롬프트에는 작업 목표, 대상 파일, 완료 기준, 출력 형식 4가지가 필수예요
- 스테이크홀더별(개발, 리서치, 보안) 맞춤 도입 전략이 있어야 조직 안착이 가능해요
- Team은 실험 기능이지만, 운영 설계를 갖추면 강력한 협업 실행 프레임이 돼요
이 글의 대상
- Team 기능을 조직 단위로 도입하려는 개발/리서치 리더
- CLAUDE.md와 프롬프트 템플릿을 체계적으로 설계하고 싶은 분
- 보안/거버넌스 관점에서 Team 도입 기준을 세우고 싶은 분
목차
1. CLAUDE.md - 팀의 공통 헌법 만들기
CLAUDE.md는 모든 팀원이 공유하는 규칙과 맥락을 담은 파일이에요. 리더와 팀원이 이 파일을 읽고 시작하기 때문에, 팀의 "공통 헌법" 역할을 해요.
CLAUDE.md가 왜 중요하냐면, Team의 팀원들은 독립된 컨텍스트에서 작업한다고 했잖아요. 그 말은 팀원끼리 공유하는 암묵적 지식이 없다는 뜻이에요. CLAUDE.md가 그 빈자리를 채워주는 거예요.
CLAUDE.md에 포함해야 할 핵심 항목을 정리하면 이래요:
| 항목 | 내용 예시 | 왜 필요한가 |
|---|---|---|
| 프로젝트 목표 | "이 프로젝트는 결제 시스템 리팩터링" | 팀원이 맥락 없이 코드만 보면 방향을 잃어요 |
| 금지 사항 | "production DB 직접 수정 금지" | 명시하지 않으면 에이전트가 할 수도 있어요 |
| 표준 테스트 커맨드 | npm test, pytest tests/ |
팀원마다 다른 방식으로 테스트하는 걸 방지해요 |
| PR/리포트 템플릿 경로 | .github/PULL_REQUEST_TEMPLATE.md |
산출물 형식을 통일해요 |
| 금지 경로와 승인 규칙 | src/auth/ 변경 시 Plan approval 필수 |
7편에서 다룬 가드레일과 연결돼요 |
주의할 점: CLAUDE.md에 API 키, 비밀번호 같은 비밀정보를 절대 넣으면 안 돼요. 이 파일은 팀원 전체가 읽기 때문에 비밀정보가 노출될 위험이 있어요. 비밀정보는 환경 변수나 별도 시크릿 관리 도구를 사용하는 게 맞아요.
2. 스폰 프롬프트 필수 4요소
팀원을 생성(스폰)할 때 주는 프롬프트에 4가지 요소가 빠지면 결과물 품질이 크게 떨어져요.
스폰 프롬프트는 리더가 팀원에게 "이 일을 해줘"라고 지시하는 텍스트예요. 여기서 명확하지 않으면 팀원이 엉뚱한 방향으로 가거나, 완료 시점을 판단하지 못해요.
필수 4요소는 이래요:
1) 작업 목표 (무엇/왜)
"무엇을 하라"만 주면 안 돼요. "왜 하는지"도 함께 줘야 해요. "인증 모듈을 리뷰해 줘"보다 "인증 모듈에서 토큰 만료 처리가 제대로 되는지 보안 관점에서 리뷰해 줘"가 훨씬 좋은 프롬프트예요.
2) 대상 파일/PR 링크
팀원은 독립 컨텍스트라서, 어떤 파일을 봐야 하는지 모를 수 있어요. "src/auth/" 디렉토리 전체인지, 특정 PR인지 명시해 주는 게 좋아요.
3) 완료 기준
"다 되면 알려줘"는 너무 모호해요. "리뷰 의견을 critical/major/minor로 분류해서 review.md에 저장하면 완료"처럼 구체적인 기준을 주는 게 좋아요.
4) 출력 형식
결과를 어떤 형태로 내놓을지 정해줘야 해요. 마크다운 파일인지, JSON인지, 표 형식인지. 이게 없으면 팀원마다 제각각의 형식으로 결과를 내놔서 리더가 취합하기 어려워요.
| 요소 | 나쁜 예 | 좋은 예 |
|---|---|---|
| 목표 | "코드 리뷰해 줘" | "결제 모듈에서 동시성 이슈가 있는지 확인해 줘" |
| 대상 | (미지정) | "src/payment/ 디렉토리 전체" |
| 완료 기준 | "다 되면 알려줘" | "이슈를 severity별로 분류해서 파일로 저장" |
| 출력 형식 | (미지정) | "마크다운 표 형식, 파일명: review_payment.md" |
3. 태스크 분해 템플릿
태스크를 독립 산출물 단위로 쪼개고, 팀원당 5~6개 동시 태스크를 넘기지 않는 게 효율적이에요.
태스크 분해를 잘하면 팀원들이 서로 충돌 없이 병렬로 일할 수 있어요. 분해를 잘못하면 "팀원 A가 끝나야 팀원 B가 시작할 수 있는" 병목이 생겨요.
좋은 태스크 분해의 원칙은 이래요:
- 독립 산출물 단위: 각 태스크가 다른 태스크에 의존하지 않고 독립적으로 완료 가능해야 해요
- 팀원당 5~6개: 너무 많으면 컨텍스트가 길어지고, 너무 적으면 팀원을 비효율적으로 쓰는 거예요
- 의존성 명시: 어쩔 수 없이 의존성이 있다면 명시적으로 표시하고, 순서를 정해야 해요
태스크 분해 템플릿의 예시를 보여드릴게요:
[태스크 분해 템플릿]
프로젝트: 결제 시스템 리팩터링
팀원 수: 4명
팀원 A (보안 리뷰):
- T1: 인증 모듈 토큰 처리 리뷰 → review_auth.md
- T2: 결제 API 입력 검증 리뷰 → review_payment_input.md
- T3: 에러 응답에 민감정보 포함 여부 확인 → review_error_response.md
팀원 B (성능 분석):
- T1: DB 쿼리 실행 계획 분석 → perf_db_queries.md
- T2: API 응답 시간 병목 분석 → perf_api_latency.md
- T3: 캐싱 전략 개선안 → perf_cache_strategy.md
팀원 C (테스트 보강):
- T1: 결제 성공 시나리오 테스트 작성 → test_payment_success.py
- T2: 결제 실패 시나리오 테스트 작성 → test_payment_failure.py
- T3: 동시성 테스트 작성 → test_payment_concurrency.py
팀원 D (문서화):
- T1: API 변경 사항 문서 → docs_api_changes.md
- T2: 마이그레이션 가이드 → docs_migration_guide.md
- T3: 아키텍처 결정 기록(ADR) → adr_payment_refactor.md
의존성: 없음 (모두 병렬 가능)
완료 기준: 각 팀원의 모든 산출물 파일이 생성되면 완료이렇게 해두면 리더가 한눈에 "누가 뭘 하고 있고, 뭐가 완료됐는지" 파악할 수 있어요.
4. 스테이크홀더별 도입 전략
역할에 따라 Team 도입의 시작점과 중점이 달라요. 한 가지 전략으로 모든 역할을 커버하려 하면 실패해요.
개발 리더
개발 리더가 Team을 도입할 때는 PR 다관점 리뷰와 디버깅 병렬화부터 시작하는 게 좋아요. 이게 가장 효과가 눈에 보이고, 기존 워크플로에 자연스럽게 녹아들거든요.
기본 패키지로 갖춰야 할 것:
- Plan approval (7편에서 다룬 것)
- Hooks 기반 테스트 통과 강제 (7편)
- 보호 브랜치 설정 (7편)
이 세 가지를 "기본 가드레일 패키지"로 묶어서 Team 도입과 동시에 적용하는 게 좋아요.
리서치 리더
리서치 팀이라면 비교표, ADR(Architecture Decision Record), PoC 산출물 템플릿을 미리 만들어두는 게 핵심이에요. 각 팀원이 조사한 결과를 같은 형식으로 내놓으면 리더가 비교하기 쉽거든요.
주의할 점은 broadcast 최소화예요. 리서치 과정에서 "이것도 봐봐"라고 전체에게 보내고 싶은 유혹이 있는데, 이러면 비용만 올라가요. 개별 팀원에게 필요한 정보만 보내는 게 낫아요.
보안/거버넌스 담당
보안 팀에서는 이 세 가지를 먼저 정립하는 게 중요해요:
| 항목 | 설명 |
|---|---|
| 권한 상속 정책 명문화 | 리더가 어떤 권한으로 실행해야 하는지 문서로 남기기 |
| 훅 기반 감사 로그 | 7편에서 다룬 TaskCompleted 훅으로 모든 작업 기록 |
| 민감 경로 차단 | src/auth/, config/secrets/ 등 변경 시 자동 차단 |
5. Looking Ahead - 앞으로의 진화
Team 기능은 아직 실험적이지만, 안정화되면 더 정교한 통제와 비용 관리가 가능해질 거예요.
현재 Team 기능의 로드맵을 전망해 보면 크게 세 방향이에요:
- 실험 기능 안정화:
/resume,/rewind지원, 팀원 상태 자동 모니터링 등이 안정화되면 운영 부담이 크게 줄어들 거예요 - 통제 지점 확장: 지금은 권한, Plan approval, Hooks가 주요 통제 수단인데, 더 세밀한 정책 엔진이 추가될 가능성이 있어요
- 비용 관리 정교화: 팀원별/태스크별 비용 추적이 가능해지면 더 효율적인 운영이 가능해져요
중요한 건, "안정화될 때까지 기다리자"가 아니라 "지금부터 운영 설계를 갖추고 시작하자"라는 거예요. 운영 기반이 있으면 기능이 안정화됐을 때 바로 확장할 수 있거든요.
핵심 정리
1. CLAUDE.md = 팀의 공통 헌법 → 목표, 금지 사항, 테스트 커맨드, 산출물 형식 통일
2. 스폰 프롬프트 필수 4요소: 작업 목표, 대상 파일, 완료 기준, 출력 형식
3. 태스크 분해: 독립 산출물 단위, 팀원당 5~6개, 의존성 명시
4. 역할별 도입: 개발(PR 리뷰), 리서치(비교표/ADR), 보안(권한 정책+감사 로그)
5. Team = 독립 컨텍스트를 가진 다중 세션을 조율하고 승인·훅으로 통제하는 협업 실행 프레임FAQ
Q. CLAUDE.md에 꼭 들어가야 하는 최소 항목은 뭔가요?
A. 최소한 프로젝트 목표, 금지 사항, 표준 테스트 커맨드 이 세 가지는 넣어야 해요. 이게 없으면 팀원이 방향을 잡지 못하고 엉뚱한 작업을 하거나, 해서는 안 될 일을 할 수 있어요. 나머지는 팀의 성숙도에 따라 점진적으로 추가하면 돼요.
Q. 스폰 프롬프트가 너무 길어지면 어떡하나요?
A. 프롬프트가 길어지면 팀원의 컨텍스트를 잡아먹어서 오히려 비효율적이에요. 핵심 4요소만 간결하게 적고, 상세한 가이드라인은 CLAUDE.md나 별도 파일에 넣어서 "이 파일을 참고해"라고 하는 게 좋아요. 프롬프트는 짧고 명확하게, 배경 정보는 파일로 분리하는 거예요.
Q. 태스크를 너무 잘게 쪼개면 오히려 비효율적이지 않나요?
A. 맞아요. 태스크 하나가 너무 작으면(예: "파일 하나 읽고 한 줄 코멘트") 팀원 생성 비용이 실제 작업 비용보다 커질 수 있어요. 적절한 단위는 "30분~2시간 정도 걸리는 독립적인 산출물 하나"예요. 이보다 작으면 합치고, 크면 쪼개는 게 좋아요.
Q. 우리 팀에 보안 담당자가 없는데 거버넌스는 어떻게 하나요?
A. 보안 전담자가 없어도 최소한의 거버넌스는 할 수 있어요. 7편에서 다룬 "권한 allowlist 설계 + Hooks 기반 테스트 강제 + 보호 브랜치"만 세팅해도 기본적인 안전망이 돼요. 개발 리더가 이 역할을 겸하면서, 팀이 커지면 전담자를 두는 단계적 접근이 현실적이에요.
Q. Team 도입을 작은 규모로 시작하고 싶은데, 추천하는 첫 번째 사용 사례가 뭔가요?
A. PR 다관점 리뷰를 추천해요. 팀원 2~3명에게 각각 보안/성능/코드 품질 관점에서 같은 PR을 리뷰하게 하는 거예요. 위험이 낮고, 결과가 바로 눈에 보이고, 기존 코드 리뷰 프로세스에 자연스럽게 녹아들어요. 여기서 감을 잡은 뒤에 디버깅이나 리서치로 확장하면 돼요.
Q. 기존 CI/CD 파이프라인이 잘 되어 있는데 Team을 도입하면 충돌하지 않나요?
A. 충돌하지 않아요. 오히려 보완 관계예요. Team의 로컬 훅은 "작업 중 빠른 피드백"을, CI/CD는 "병합 전 최종 검증"을 담당해요. 기존 CI/CD를 그대로 두고, Team의 가드레일을 그 앞단에 추가하는 형태로 도입하면 자연스럽게 맞물려요.
Q. 이 시리즈를 다 읽었는데, 한마디로 정리하면 Team 기능이 뭔가요?
A. "독립 컨텍스트를 가진 다중 세션을 조율하고, 승인과 훅으로 통제하는 협업 실행 프레임"이에요. 그냥 여러 개 동시에 돌리는 게 아니라, 리더가 조율하고 가드레일이 지키는 구조화된 협업이 핵심이에요.
참고 자료 (References)
데이터 출처
| 출처 | 설명 | 링크 |
|---|---|---|
| Agent Teams 공식 문서 (KO) | 한국어 공식 가이드 | Agent Teams KO |
| Agent Teams 공식 문서 (EN) | 영문 공식 가이드 | Agent Teams EN |
| Best Practices | Claude Code 운영 모범 사례 | Best Practices |
| Hooks Guide | 훅 설정 및 활용 가이드 | Hooks Guide |
| CLI Reference | CLI 옵션 및 플래그 | CLI Reference |
핵심 인용
"Team은 독립 컨텍스트를 가진 다중 세션을 조율하고 승인·훅으로 통제하는 협업 실행 프레임"
— 클로드 코드 Team 기능 완전 가이드 시리즈 결론
시리즈를 마치며
9편에 걸쳐 Claude Code Team 기능의 A부터 Z까지 함께 살펴봤어요.
시리즈 전체를 한 줄씩 요약하면 이래요:
| 편 | 핵심 |
|---|---|
| 1편 | Team = 병렬 실행이 아닌 협업 런타임 |
| 2편 | 서브에이전트 vs Team, 독립 컨텍스트가 핵심 차이 |
| 3편 | 리더-팀원 구조와 메시징 흐름 |
| 4편 | 설정부터 실행까지 실전 가이드 |
| 5편 | 개발 팀 운영 모델 설계 |
| 6편 | 리서치/기획 팀 운영 모델 설계 |
| 7편 | 가드레일: 권한, 승인, Hooks |
| 8편 | 비용 관리와 실패 대응 |
| 9편 | 표준 템플릿과 조직 도입 로드맵 |
Team 기능은 아직 실험적인 단계에요. /resume이 안 되고, 비용 추적이 제한적이고, split-pane에 환경 의존성이 있어요. 하지만 이 시리즈에서 다룬 운영 설계 - 가드레일, 체크포인트, 복구 루틴, 템플릿 -를 갖추면, 실험 기능의 한계를 충분히 관리하면서 강력한 협업 도구로 활용할 수 있어요.
여러분의 팀에 맞는 방식으로, 작은 사용 사례부터 시작해 보세요. 이 시리즈가 그 여정에 도움이 됐으면 좋겠어요.