Claude Code 활용 플레이북 · 에이전트 팀 설계
AI 혼자 쓰는 시대는 끝났다. 역할이 분명한 에이전트 팀을 구성하고 CLAUDE.md로 컨텍스트를 제어하면, 혼자서 팀 전체 수준의 결과물을 만들 수 있다.
CLAUDE.md는 Claude Code가 세션 시작 시 자동으로 읽는 컨텍스트 파일. 여기에 프로젝트 규칙·역할·제약을 기록하면 매번 설명하지 않아도 된다.
# 프로젝트 이름
## 역할 (이 에이전트는 누구인가)
너는 [역할명]이다. 너의 임무는 [핵심 목표]이다.
[절대 하지 않아야 할 것]은 하지 않는다.
## 컨텍스트 (프로젝트 배경)
- 프로젝트: [설명]
- 기술 스택: [스택]
- 현재 단계: [단계]
## 작업 규칙
1. 코드 수정 전 관련 파일을 먼저 읽는다
2. 완료 보고 전 실제 실행 증거를 포함한다
3. 요청 범위 밖 변경 금지
## 완료 기준 (Done의 정의)
- [ ] 빌드/테스트 통과
- [ ] 엣지 케이스 확인
- [ ] 보고 형식: 변경한 것 / 검증한 것 / 남은 리스크
## 파일 구조
[현재 폴더 구조 요약]• 메인 폴더 루트: 전체 프로젝트 공통 규칙
• 하위 프로젝트 폴더: 해당 프로젝트 전용 규칙
• .claude/agents/: 개별 에이전트 역할 파일
하위 CLAUDE.md가 상위를 오버라이드하므로, 공통 → 전용 순으로 계층 설계.
① 완료 정의 명시 — "완료됐습니다" 남발 방지
② 금지 패턴 열거 — 반복되는 실수 차단
③ 보고 형식 고정 — 결과물 품질 일관성 확보
3가지만 넣어도 에이전트 행동이 눈에 띄게 달라진다.
디렉터 에이전트가 전체 계획을 세우고 서브 에이전트들에게 태스크를 배분. 서브 에이전트는 결과만 반환.
디렉터비주얼라이저렌더엔지니어동일한 질문을 여러 에이전트가 각자 다른 소스에서 조사하고 결과를 합산. 교차검증으로 정확도 향상.
주식분석부동산리서치뉴스크롤러구현 에이전트 → 코드리뷰 에이전트 → QA 에이전트 순으로 체인. 각 단계가 이전 단계를 독립적으로 검증.
구현자코드리뷰어QA튜터 에이전트가 "왜"를 설명하고, 실행 에이전트가 "어떻게"를 구현. 결과물과 학습이 동시에 생산.
튜터구현자메모리 파일(.md)에 팀의 상태·결정·히스토리를 기록. 세션이 끊겨도 다음 세션에서 정확히 이어받음.
인제스터링커신서사이저CLAUDE.md에 단축어를 등록하면 짧은 명령으로 전체 팀이 활성화.
# CLAUDE.md에 추가
"모션팀 호출" →
027-1 모션영상 에이전트팀 활성화,
레퍼런스.html 기준으로 작업 시작
"주식팀 호출" →
023 주식섹터 에이전트 즉시 실행Claude는 XML 태그 구조로 쓴 프롬프트에 가장 정확하게 반응한다. 4요소를 갖추면 원하는 결과가 첫 시도에 나올 확률이 급격히 높아진다.
<role>
너는 [직함/역할]이다.
[특기 / 관점]
</role>
<context>
- 프로젝트: [배경]
- 현재 상황: [상태]
- 제약: [제약사항]
</context>
<task>
[구체적인 작업 지시]
순서:
1. [단계 1]
2. [단계 2]
</task>
<format>
- 출력 형식: [형식]
- 길이: [분량 기준]
- 언어: 한국어
</format><role>
너는 10년 경력의 시니어
프론트엔드 엔지니어다.
- Vanilla JS를 선호하고 불필요한
프레임워크를 경계한다
- 성능과 접근성을 동시에 고려한다
- 코드를 추가하기 전에 제거를
먼저 고려한다
</role>| 기법 | 사용법 | 효과 |
|---|---|---|
| Chain of Thought | "단계별로 생각하고 나서 답하라" | 복잡한 추론 정확도 향상 |
| Few-shot 예시 | 원하는 형식을 2~3개 예시로 제시 | 형식 일관성 보장 |
| 자기 검증 | "답을 내기 전에 스스로 검토하라" | 오류 30~50% 감소 |
| 역할 강화 | "전문가라면 어떻게 볼까?" | 깊이 있는 분석 유도 |
| 부정 지시 | "~하지 말 것" 명시 | unwanted behavior 차단 |
MEMORY.md에 모든 프로젝트 인덱스·결정 사항 기록
각 폴더에 역할·규칙·완료 정의 파일 배치
"디자인팀 호출" → 027 에이전트들이 역할 수행
여러 에이전트가 HTML 섹션·CSS·JS를 동시 작성
헤드리스 크롬으로 렌더 확인 → wrangler 배포
디자인·모션영상·옵시디언·리포트에디터·프롬프트 팀이 각자 독립 실행
MEMORY.md가 28개 프로젝트 맥락을 세션 간 유지 — 매번 새로 설명 불필요
HTML·CSS·JS 모두 에이전트 생성. 사람은 방향 결정과 검토만 담당
| 결정 | 이유 | 결과 |
|---|---|---|
| CDN 전용 (npm 없음) | 배포 복잡도 0 — 폴더 자체가 배포 단위 | wrangler 1개 명령으로 배포 |
| 단일 HTML 파일 | 빌드 파이프라인 없이 수정 즉시 반영 | 에이전트가 파일 하나만 편집 |
| frame-driven SVG 엔진 | CSS 애니메이션은 id 충돌로 제어 불가 | JS requestAnimationFrame으로 완전 제어 |
| Cloudflare Pages | git remote 없이 디렉토리 직접 업로드 | GitHub 없이도 전 세계 CDN 배포 |
| 메모리 파일 (.md) | Claude 컨텍스트 창 한계 극복 | 28개 프로젝트를 3줄 요약으로 즉시 로드 |
# 1. 메모리 확인 요청
MEMORY.md 읽고 [프로젝트명] 상태 확인해줘.
# 2. 현재 상태 파악
[프로젝트] 폴더 구조 확인하고
마지막 작업 어디까지 했는지 파악해.
# 3. 오늘 목표 설정
오늘 목표: [구체적 결과물]
예상 소요: 30분# 1. 완료 검증
오늘 작업한 것 목록으로 정리해줘.
미완료 항목 있으면 표시해.
# 2. 메모리 업데이트
MEMORY.md와 관련 프로젝트 메모리
파일 업데이트해줘.
# 3. 다음 세션 브리핑
다음에 이어서 할 것 3줄로 요약해줘.| 커맨드 | 용도 | 언제 쓰나 |
|---|---|---|
/kickoff | 프로젝트 착수 프로토콜 | 새 작업 시작 시 — 탐색→계획→구현 흐름 강제 |
/task-protocol | 5단계 작업 프로토콜 | 비자명한 복잡 작업에서 탐색→계획→구현→검증→보고 |
/self-verify | 자가 검증 체크리스트 | 완료 보고 전 — gate 1~4 강제 점검 |
/bughunt | 디버깅 프로토콜 | 버그 발생 시 — 원인 추적부터 검증까지 |
/deep-review | 코드 심층 리뷰 | 배포 전 독립적 품질 검사 |
/bigtask | 큰 작업 분해 | 1세션 이상 걸리는 작업 — 체크포인트 설정 |
/remember | 메모리 저장 | 중요 결정·선호·컨텍스트를 다음 세션에 전달 |
/code-review ultra | 멀티 에이전트 코드 리뷰 | 브랜치 전체를 클라우드 에이전트들이 병렬 검토 |
Esc — 현재 작업 중단 (취소가 아닌 중단)
⌘K — 대화 컨텍스트 초기화 (새 주제 시작)
⌘R — 이전 명령 재실행
Tab — 자동완성 수락
Shift+Tab — 대안 제안으로 순환
/clear — 화면 정리 (히스토리 유지)
gmail — 리서치 결과 자동 메일 발송
ms365 — 캘린더·OneNote·OneDrive 연동
NaverSearch — 데이터랩, 블로그, 뉴스 검색
UsStockInfo — 주식 데이터 자동 수집
Google Drive — 파일 자동 저장·공유
KakaoMap — 위치 기반 정보 연동
MEMORY.md와 CLAUDE.md를 읽고 현재 상태를 파악해줘.
그 다음 아래 작업을 진행해:
목표: [결과물 설명]
제약: [기술 스택, 시간, 형식]
완료 기준: [검증 방법]
시작 전 계획을 3줄로 먼저 보고하고, 내가 승인하면 구현 시작해.너는 [팀명]의 디렉터다.
아래 역할의 서브 에이전트를 소환해서 작업을 병렬로 진행해:
- 에이전트 A ([역할]): [담당 작업]
- 에이전트 B ([역할]): [담당 작업]
- 에이전트 C ([역할]): [담당 작업]
각 에이전트의 결과를 취합해서 최종 결과물 하나로 만들어줘.
완료 보고는: 각 에이전트 결과 요약 / 통합 결과 / 남은 작업 형식으로.아래 데이터를 분석해서 발표자료용 차트 HTML을 만들어줘.
데이터:
[데이터 붙여넣기]
요구사항:
- Chart.js 4 CDN 사용 (npm 없음)
- 다크 테마 (#0f172a 배경)
- 인사이트 제목: "[제목]"
- 차트 타입: [타입 (모르면 "추천해줘"로)]
- 크기: 800px 너비
완료 후 HTML 파일 저장해줘.아래 버그를 디버깅해줘. 샷건 수정(여기저기 고쳐보기) 금지.
증상: [현상 설명]
재현 방법: [단계]
예상 동작: [기대값]
실제 동작: [현재값]
접근 방법:
1. 원인을 한 문장으로 가설 제시
2. 해당 파일/라인 확인
3. 원인 확인 후 최소 변경으로 수정
4. 수정 후 재현 확인아래 코드를 독립적으로 리뷰해줘.
(내가 의도한 것과 관계없이 코드 자체만 평가)
검토 항목:
□ 보안 취약점 (XSS, injection, 노출된 키)
□ 성능 이슈 (불필요한 렌더링, 메모리 누수)
□ 엣지 케이스 누락
□ 유지보수 문제 (중복, 네이밍)
결과: 심각도 High/Medium/Low로 분류해서 보고.