adev-poc-guide

adev PoC — Claude Agent SDK + Agent Teams 검증

adev 시스템의 2계층(자율 개발)에서 사용할 Claude Agent SDK와 Agent Teams의 실제 동작을 검증하는 PoC 프로젝트. 이 PoC 결과에 따라 v2.3 아키텍처가 확정된다.

결과 요약

전체 5/5 PASS — v2.3 아키텍처 채택 확정

총 PoC 비용: ~$2.79

테스트별 상세 결과

P0: SDK 기본 동작 확인

query()로 "1+1은?" 전송 → "2" 응답 정상 수신.

이벤트 흐름 (총 4개): system → assistant → rate_limit_event → result

{
  "subtype": "success",
  "result": "2",
  "total_cost_usd": 0.046,
  "duration_ms": 2330,
  "num_turns": 1
}

발견사항:

• allowedTools: []로 설정해도 system init에 TeamCreate, TeamDelete, SendMessage 등이 포함됨
• Agent Teams 도구는 allowedTools와 별도 레이어에서 관리됨
• rate_limit_event가 매 query마다 발생 — rateLimitType: "five_hour" 등 rate limit 메타데이터 제공

---

P2-1: 동시 query() 안정성

독립 query()를 Promise.all로 동시 실행하여 병렬 안정성 검증.

Phase 1 — 3개 동시 (13.5s):

Phase 2 — 5개 동시 (10.2s):

발견사항:

• 5개 동시 실행에서도 모든 결과가 정확 — 크로스 오염 없음
• 5개 동시가 3개보다 오히려 빠름 (10.2s vs 13.5s) — cache_read_input_tokens 활용 효과 추정
• 각 query가 독립 subprocess로 spawn → 완전 격리 확인

---

P2-2: Agent Teams 기본 동작

Agent Teams 라이프사이클(TeamCreate → Agent → SendMessage → TeamDelete)이 SDK query()에서 동작하는지 확인.

라이프사이클 타임라인:

전체 tool_use 목록 (18개):

{
  "subtype": "success",
  "total_cost_usd": 0.875,
  "duration_ms": 128097,
  "num_turns": 19
}

발견사항:

• Task/TaskCreate 미사용: teammate 생성은 Agent 도구(subagent spawn)로 수행됨
• TeamDelete 7회 반복: researcher가 shutdown_request에 응답하지 않아 모델이 반복 시도
  • 시도 순서: shutdown_request → TeamDelete → 대기(Bash sleep) → 재시도 → config.json 직접 편집(Edit) → 최종 삭제 성공
• teammate 종료의 비결정성: 132.5초 중 약 100초가 종료 처리에 소비됨

---

P2-3: Agent Teams Hooks 감시

SDK의 hooks 옵션으로 Agent Teams 도구 호출을 실시간 모니터링할 수 있는지 확인.

Hook 이벤트 타임라인 (총 26개):

Hook rawInput 구조 예시:

{
  "session_id": "6ce9907b-...",
  "transcript_path": "C:\\Users\\...\\6ce9907b-....jsonl",
  "hook_event_name": "PreToolUse",
  "tool_name": "TeamCreate",
  "tool_input": { "team_name": "poc-hook-team", "description": "..." },
  "tool_use_id": "toolu_011EH2i8aZpCFVkX9DMnh2uH"
}

Stream vs Hook 감지 비교:

{
  "subtype": "success",
  "total_cost_usd": 0.785,
  "duration_ms": 66982,
  "num_turns": 10
}

발견사항:

• Hooks가 SDK options에서 정상 동작 — query() options에 hooks를 직접 전달하는 방식 확인
• Pre/Post 쌍 보장: 모든 PreToolUse에 PostToolUse가 정확히 대응 (12ms 미만 간격)
• Hook이 subagent 내부의 도구 호출까지 캡처 → stream-monitor는 Hooks 기반이 훨씬 정확
• TaskCompleted 미발화: 작업 완료 감지는 result 이벤트 또는 디스크 기반으로 별도 구현 필요

---

P3: 디스크 기반 IPC 확인

Agent Teams 실행 중 생성되는 파일시스템 구조를 확인하여, 디스크 폴링 감시 가능성 검증.

발견된 파일시스템 구조:

~/.claude/
├── teams/poc-ipc-team/
│   ├── config.json              ← 팀 설정 (512B)
│   └── inboxes/
│       ├── observer.json        ← teammate inbox (167B)
│       └── team-lead.json       ← leader inbox (171B)
└── tasks/poc-ipc-team/
    ├── .lock                    ← 동시성 제어 (0B)
    └── 1.json                   ← 태스크 상세 (184B)

파일 생성 타임라인:

파싱된 JSON 내용:

config.json — 팀 구성 정보:

{
  "name": "poc-ipc-team",
  "description": "IPC 테스트용 POC 팀",
  "createdAt": 1772551008998,
  "leadAgentId": "team-lead@poc-ipc-team",
  "members": [{
    "agentId": "team-lead@poc-ipc-team",
    "name": "team-lead",
    "agentType": "team-lead",
    "model": "claude-opus-4-6"
  }]
}

tasks/1.json — 태스크:

{
  "id": "1",
  "subject": "observer",
  "description": "Hello라고 답해",
  "status": "in_progress",
  "blocks": [],
  "blockedBy": [],
  "metadata": { "_internal": true }
}

inboxes/observer.json — leader → teammate 메시지:

[{
  "from": "team-lead",
  "text": "상태 보고",
  "summary": "상태 보고 요청",
  "timestamp": "2026-03-03T15:16:58.299Z",
  "read": false
}]

inboxes/team-lead.json — teammate → leader 응답:

[{
  "from": "observer",
  "text": "Hello",
  "summary": "Hello 응답",
  "timestamp": "2026-03-03T15:16:58.806Z",
  "color": "blue",
  "read": false
}]

{
  "subtype": "success",
  "total_cost_usd": 1.082,
  "num_turns": 19
}

발견사항:

• 경로 확정: ~/.claude/teams/{team_name}/ + ~/.claude/tasks/{team_name}/ — POC-SKILL.md 예상과 일치
• inbox는 JSON Array (JSONL 아님) — 전체 파일을 읽고 파싱해야 함
• .lock 파일 존재 → 동시성 제어 메커니즘 내장
• 500ms 폴링으로 파일 변경 감지 충분
• teammate → leader 응답에 "color": "blue" 필드가 추가됨

---

프로덕션 적용 시 주의사항

teammate 종료 비결정성

P2-2에서 TeamDelete가 7회 반복됨. 권장 패턴:

shutdown_request → 10초 대기 → TeamDelete 시도
→ 실패 시 재시도 (최대 3회, 5초 간격)
→ 최종 실패 시 config.json에서 member 직접 제거 후 TeamDelete

TaskCompleted 미발화

Hooks의 TaskCompleted가 한 번도 발화되지 않음. 대안:

• result 이벤트의 subtype: "success" 감시
• 디스크의 tasks/{id}.json의 status 필드 폴링
• TeammateIdle 이벤트 + 추가 로직 조합

비용

Hook vs Stream 감시 범위

---

프로젝트 구조

├── CLAUDE.md                 ← Claude Code 지침
├── POC-SPEC.md               ← 검증 항목, 성공 기준, 실패 대안
├── POC-SKILL.md              ← SDK 사용법, 이벤트 구조, 함정 목록
├── POC-ARCHITECTURE.md       ← 파일 구조, 실행 순서, 공통 패턴
└── poc/
    ├── p0-sdk-sanity.ts          ← SDK 기본 동작 확인
    ├── p2-1-concurrent-query.ts  ← 동시 query() 안정성
    ├── p2-2-agent-teams-basic.ts ← Agent Teams 라이프사이클
    ├── p2-3-agent-teams-hooks.ts ← Hooks 감시 가능성
    ├── p3-disk-ipc.ts            ← 디스크 기반 IPC 확인
    └── results/                  ← 결과 JSON + 분석 리포트

실행 순서

P0 (필수 선행)
 ↓ PASS
P2-1 (동시 query)
 ↓ PASS
P2-2 (Agent Teams 기본)
 ↓ PASS
P2-3 (Hooks 감시)    →  FAIL → P3 (디스크 IPC)
 ↓ PASS                       ↓ PASS
아키텍처 확정               대안 확정

사전 요구사항

• Node.js 18+
• Claude Code CLI 설치 (npm i -g @anthropic-ai/claude-code)
• API 인증: ANTHROPIC_API_KEY 환경변수 또는 Claude Code 로그인 (Pro/Max)

설치 및 실행

cd poc
npm install

# 순서대로 실행 (각 단계 PASS 확인 후 다음 진행)
npm run p0      # SDK 기본 동작
npm run p2-1    # 동시 query() 안정성
npm run p2-2    # Agent Teams 기본 동작
npm run p2-3    # Agent Teams Hooks 감시
npm run p3      # 디스크 기반 IPC 확인

결과는 poc/results/에 JSON + Markdown 리포트로 저장된다.

아키텍처 결정 매트릭스

주요 문서

참고 출처

• Claude Agent SDK - TypeScript
• Claude Agent SDK - Streaming
• Agent Teams 공식 문서
• @anthropic-ai/claude-agent-sdk (npm)

License

Private — adev 내부 검증용