프로젝트 위임 오케스트레이터

개요

주인님(또는 사용자)이 프로젝트 요구사항을 제시하면, ICBM2가 다음을 자동으로 수행합니다:

• 요구사항 분석 → 구조화된 태스크로 분할
• 에이전트 선택 → 작업 유형에 따라 최적 에이전트 자동 배정
• CLAUDE.md 생성 → 에이전트가 프로젝트를 이해할 수 있도록 컨텍스트 파일 작성
• 병렬 실행 → 독립 작업은 동시에, 의존 작업은 순차적으로
• 결과 취합 → 변경사항 요약, 테스트 검증, 리포트 제공

에이전트 선택 가이드

| 상황 | 에이전트 | 방식 | 이유 |
|------|---------|------|------|
| 복잡한 기능 구현 (5+ 파일) | Claude Code | claude -p (print mode) | 강력한 코딩, 긴 컨텍스트 |
| 긴 대화형 세션 필요 | Claude Code | tmux interactive | 다단계 리팩토링 |
| 간단한 구현/수정 (1~3 파일) | delegate_task | 내장 서브에이전트 | 빠르고 가벼움 |
| OpenCode 프로바이더 활용 | OpenCode | opencode run | oh-my-openagent 연동 |
| 단순 검토/분석 | delegate_task | 내장 (file만) | 파일 읽기만으로 충분 |
| 코딩+리서치 혼합 | delegate_task | 내장 (file+web) | 웹 검색 필요시 |

실행 절차

Phase 1: 요구사항 분석 및 계획

입력: 주인님의 프로젝트 설명 (텍스트, URL, PR 링크 등)

• 요구사항 파싱

- 기능 목록 추출
- 기술 스택 파악
- 제약 조건 식별
- 기존 코드베이스 분석 (있는 경우)

• 작업 분할

- 각 태스크는 2~10분에 완료 가능한 단위
- 태스크 간 의존성 그래프 생성
- 병렬 가능한 태스크 식별

• 에이전트 배정

- 각 태스크에 최적 에이전트 할당
- toolsets 설정 (terminal, file, web 등)

• TODO 리스트 생성

todo([
  {"id": "phase1-plan", "content": "요구사항 분석 및 계획 수립", "status": "in_progress"},
  {"id": "phase1-claudemd", "content": "CLAUDE.md 프로젝트 컨텍스트 생성", "status": "pending"},
  {"id": "task-1", "content": "...", "status": "pending"},
  {"id": "task-2", "content": "...", "status": "pending"},
  ...
  {"id": "phase-final-review", "content": "최종 통합 리뷰", "status": "pending"},
])

Phase 2: CLAUDE.md 생성 (필요시)

기존 프로젝트에 위임하는 경우, 에이전트가 프로젝트를 빠르게 이해하도록 CLAUDE.md를 생성/업데이트:

delegate_task(
    goal="""[CODING AGENT]
프로젝트 구조를 분석하고 CLAUDE.md를 생성하세요.
프로젝트 디렉토리 구조 파악 (find . -type f -name "*.py" | head -50)
package.json / requirements.txt / pyproject.toml 확인
핵심 파일 5~10개 읽어서 아키텍처 파악
다음 내용으로 CLAUDE.md 작성:
CLAUDE.md 구조

프로젝트 이름과 한 줄 설명
아키텍처 개요
핵심 디렉토리와 역할
빌드/테스트/실행 명령어
코드 스타일 (indent, naming convention)
주의사항 (의존성, 환경변수 등)
작성 위치: {workdir}/CLAUDE.md
""",
    context=f"프로젝트 경로: {workdir}",
    toolsets=["terminal", "file"]
)

Phase 3: 태스크 실행

패턴 A: Claude Code 위임 (복잡한 코딩)

terminal(
    command=f"claude -p '{prompt}' --allowedTools 'Read,Edit,Write,Bash' --max-turns {turns}",
    workdir=workdir,
    timeout=300
)

prompt 구성 팁:

{프로젝트 컨텍스트 - 핵심만 3~5줄}
작업

{구체적인 태스크 설명}
요구사항

{필수 조건 1}
{필수 조건 2}
제외사항

{하지 말아야 할 것}
완료 조건

{테스트 통과, 특정 파일 생성 등}

세션 연속성이 필요할 때:

# 첫 번째 작업 - JSON 출력으로 session_id 확보
result = terminal(
    command=f"claude -p '작업1' --output-format json --max-turns 10",
    workdir=workdir, timeout=300
)
session_id = json_parse(result["output"]).get("session_id")
두 번째 작업 - 같은 세션으로 이어서

terminal(
    command=f"claude -p '작업2' --resume {session_id} --max-turns 10",
    workdir=workdir, timeout=300
)

패턴 B: 내장 delegate_task 위임 (가벼운 작업)

delegate_task(
    goal=f"""[CODING AGENT]
당신은 코딩 전문 에이전트입니다.
프로젝트 컨텍스트

{프로젝트_요약_3줄}
작업

{태스크_설명}
규칙

구현 전 기존 코드 먼저 읽을 것
테스트 작성 후 구현할 것 (TDD)
최소 변경 원칙
완료 후 python3 -m py_compile로 문법 검증
""",
    context=f"작업 디렉토리: {workdir}\n관련 파일: {files}",
    toolsets=["terminal", "file"],
    max_iterations=30
)

패턴 C: OpenCode 위임

terminal(
    command=f"opencode run '{prompt}' -f {context_file}",
    workdir=workdir,
    timeout=300
)

패턴 D: 병렬 실행 (delegate_task tasks)

독립적인 태스크들을 동시에 실행:

delegate_task(
    tasks=[
        {
            "goal": "[CODING AGENT] 태스크 A 설명...",
            "context": "프로젝트: ...",
            "toolsets": ["terminal", "file"]
        },
        {
            "goal": "[CODING AGENT] 태스크 B 설명...",
            "context": "프로젝트: ...",
            "toolsets": ["terminal", "file"]
        },
        {
            "goal": "[RESEARCH AGENT] 조사 태스크...",
            "context": "조사 주제: ...",
            "toolsets": ["web"]
        }
    ]
)

Phase 4: 리뷰 및 검증

각 태스크 완료 후:

• 스펙 준수 검증 — 요구사항을 모두 구현했는지
• 코드 품질 리뷰 — 스타일, 에러 처리, 테스트
• 테스트 실행 — pytest, npm test 등
• 변경 요약 — 어떤 파일이 어떻게 바뀌었는지

delegate_task(
    goal=f"""[CODE REVIEWER]
다음 변경사항을 리뷰하세요.
원래 요구사항

{original_requirements}
변경된 파일

{changed_files}
리뷰 체크리스트

[ ] 모든 요구사항 구현됨?
[ ] 불필요한 변경 없음?
[ ] 에러 처리 적절?
[ ] 테스트 충분?
[ ] 보안 이슈 없음?
결과: PASS 또는 수정 필요 항목 목록
""",
    toolsets=["terminal", "file"]
)

Phase 5: 최종 취합

# 전체 테스트 실행
terminal(command="pytest tests/ -q", workdir=workdir, timeout=60)
변경사항 요약

terminal(command="git diff --stat", workdir=workdir)
terminal(command="git log --oneline -10", workdir=workdir)

프롬프트 작성 베스트 프랙티스

에이전트에게 줄 프롬프트는 구체적이고, 한정적이고, 검증 가능해야 합니다.

❌ 나쁜 프롬프트

인증 시스템을 만들어줘

✅ 좋은 프롬프트

## 작업: JWT 인증 미들웨어 구현
파일 생성

src/middleware/auth.py — JWT 검증 미들웨어
tests/middleware/test_auth.py — 단위 테스트
요구사항

Authorization 헤더에서 Bearer 토큰 추출
jwt.decode로 토큰 검증 (SECRET_KEY 환경변수 사용)
만료 토큰 → 401, 유효 → request.user에 payload 저장
토큰 없음 → 401
제외사항

로그인/회원가입 엔드포인트는 만들지 마세요 (별도 태스크)
데이터베이스 조회는 하지 마세요
완료 조건

pytest tests/middleware/test_auth.py -v 전체 통과
python3 -m py_compile src/middleware/auth.py 에러 없음

실행 전략: 순차 위임 (기본)

핵심 원칙: 컨텍스트 확보가 목적, 속도가 아님

병렬 실행의 진정한 가치는 속도가 아니라 각 서브에이전트의 독립 컨텍스트에 있습니다. 따라서 기본적으로 모든 태스크를 순차로 실행합니다.

순차 위임의 장점

• 컨텍스트 계승: 앞 태스크의 결과(파일 구조, 패턴, 결정사항)를 뒤 태스크의 context로 전달
• ZAI 동시성 리밋 회피: 한 번에 하나의 API 커넥션만 사용
• 에러 복구: 실패 시 즉시 수정 후 다음 태스크 진행
• 자연스러운 의존성 처리: A 결과가 B 입력인 경우 자동 해결

컨텍스트 계승 패턴

각 태스크 완료 후, 다음 태스크의 context에 이전 결과를 포함:

# 태스크 1 완료 후 결과 확보
result_1 = delegate_task(goal="...", toolsets=["terminal", "file"])
태스크 2에 태스크 1의 결과를 context로 전달

result_2 = delegate_task(
    goal="...",
    context=f"""
    ## 이전 태스크 결과
    {result_1의_요약}
    
    ## 생성된 파일
    - src/models/user.py (User 모델, bcrypt 해싱)
    - tests/test_user.py (3개 테스트)
    
    ## 프로젝트 컨텍스트
    {project_context}
    """,
    toolsets=["terminal", "file"]
)

병렬 실행은 거의 사용하지 않음

| 상황 | 전략 | 이유 |
|------|------|------|
| 일반적인 모든 작업 | 순차 | 컨텍스트 계승 + 안정성 |
| 완전히 독립적인 파일 | 순차 (권장) | 속도 차이 1~2분, 리밋 리스크 불필요 |
| 다른 프로바이더 사용 가능 | 병렬 고려 가능 | Claude Code + OpenCode는 프로바이더가 다름 |
| ZAI 동시성 리밋 발생 | 즉시 순차 전환 | 429/529 에러 시 |

비용 및 시간 추정

| 에이전트 | 적합 작업 | 예상 시간 | 예상 비용 |
|---------|----------|----------|----------|
| delegate_task | 1~3 파일 수정 | 1~3분 | 낮음 |
| Claude Code (-p) | 기능 구현 | 2~5분 | 중간 |
| Claude Code (interactive) | 대규모 리팩토링 | 5~15분 | 높음 |
| OpenCode run | 간단 구현 | 2~5분 | 중간 |

에러 대응

에이전트 실패 시

• 에러 로그 분석
• 프롬프트 수정 후 재시도 (최대 2회)
• 그래도 실패하면 더 간단한 하위 태스크로 분할
• 최후 수단: 직접 구현

컨텍스트 초과 시

• 프롬프트에서 불필요한 컨텍스트 제거
• CLAUDE.md로 프로젝트 컨텍스트 대체
• 세션 분할 (큰 작업 → 2개의 작은 작업)

ZAI 동시성 리밋 시

• 기본적으로 발생하지 않음 (순차 실행이 기본 정책)
• 만약 발생하면 60초 대기 후 재시도
• 프로바이더 전환 고려 (acp_command로 Claude Code 사용)

사용 예시

예시 1: 새 프로젝트 시작

주인님: "FastAPI로 TODO 앱 만들어줘"
→ Phase 1: 계획 수립 (모델, API, 테스트 3개 태스크)
→ Phase 2: CLAUDE.md 생성
→ Phase 3: 순차 실행 (모델→API→테스트, 의존성 때문)
→ Phase 4: 리뷰
→ Phase 5: 최종 검증

예시 2: 기존 프로젝트에 기능 추가

주인님: "기존 Flask 앱에 이메일 발송 기능 추가해줘"
→ Phase 1: 기존 코드 분석 + 태스크 분할
→ Phase 2: CLAUDE.md 업데이트 (기존 구조 반영)
→ Phase 3: delegate_task로 기능 구현
→ Phase 4: 기존 테스트 회귀 확인
→ Phase 5: 보고

예시 3: 버그 수정 (긴급)

주인님: "로그인 API가 500 에러 뜨는데 봐줘"
→ Phase 1: 최소 분석 (에러 로그 확인)
→ Phase 3: Claude Code -p로 빠른 수정 (max-turns 5)
→ Phase 5: 핫픽스 보고 (간소화된 파이프라인)

Pitfalls

• 프롬프트가 너무 길면 에이전트가 핵심을 놓침 — CLAUDE.md에 공통 컨텍스트를 넣고 프롬프트는 태스크에만 집중
• 컨텍스트 계승을 까먹으면 뒤 태스크가 앞 태스크 결과를 모름 — 각 태스크 완료 후 반드시 결과를 요약해서 다음 context에 포함
• ZAI 동시성 리밋에 병렬로 돌리면 실패 — 기본 순차, 절대 병렬 남발 금지
• 에이전트 실패를 무시하면 누적됨 — 각 태스크 완료 후 반드시 검증
• git 커밋 없이 여러 태스크가 같은 디렉토리 작업하면 꼬임 — 각 태스크 후 커밋 권장
• Claude Code -p는 대화형이 아님 — 피드백 루프가 필요하면 tmux interactive 모드 사용
• max-turns를 너무 높이면 비용 폭발 — 5~10으로 시작, 필요시 증가

Rules

• 항상 계획부터 — 무작정 에이전트에 던지지 마라
• 순차 위임이 기본 — 컨텍스트 계승 + ZAI 리밋 회피
• 컨텍스트 계승을 항상 — 앞 태스크 결과를 뒤 태스크 context에 포함
• CLAUDE.md는 프로젝트의 단일 진실 공급원 — 에이전트들이 이해할 수 있도록 유지
• 태스크 단위는 작게 — 하나의 에이전트가 10분 안에 끝낼 수 있게
• 검증은 필수 — 에이전트 결과를 맹신하지 마라
• 보고는 간결하게 — 주인님에게 "무엇을, 왜, 어떻게 바꿨는지" 요약만
• 실패해도 당황하지 마라 — 재시도, 분할, 직접 수행으로 대응
• 비용 인식 — max-turns, max-budget-usd로 비용 통제
• 병렬은 예외 상황 — 기본적으로 순서대로, 프로바이더가 다를 때만 병렬 고려