CLI Harness — Claude CLI 제어 명세

Node.js 서버가 Claude CLI를 spawn으로 제어하는 하네스 구조 문서. 에이전트 역할 부여, 옵션 변경, 문제 발생 시 이 문서를 참조한다.

1. 현재 사용 중인 CLI 옵션

아직 미사용이지만 활용 가능한 옵션

2. Node.js 하네스 구조

프로세스 생명주기

callClaude(message, cwd, channelId)
  │
  ├─ clearActivityLogs()          // 이전 활동 로그 정리
  ├─ sendActivityLog('🚀 시작')   // 시작 알림
  │
  ├─ args 조합
  │   ├─ 기본: -p, --dangerously-skip-permissions, --model, --output-format, --verbose
  │   ├─ 이어서: -c (channelStarted에 있으면)
  │   ├─ 규칙: --append-system-prompt HARD_RULES
  │   └─ 메시지: message
  │
  ├─ spawn('claude', args, { cwd, stdio: pipe })
  │
  ├─ stdout 이벤트 루프
  │   ├─ JSON 파싱 (줄 단위)
  │   ├─ tool_use → 활동 로그 (Read, Write, Edit, Bash, Glob, Grep, Agent)
  │   └─ result → finalResult 저장
  │
  ├─ proc.on('close')
  │   ├─ 성공: channelStarted.add(channelId), resolve(finalResult)
  │   └─ 실패: reject(Error)
  │
  └─ sendActivityLog('✅ 완료')

3. 도메인 특화 에이전트 역할 부여

방식

각 에이전트에 역할을 부여하는 데 사용할 수 있는 CLI 옵션 조합:

const args = [
  '-p',
  '--session-id', agentSessionId,           // 에이전트별 세션 격리 (UUID)
  '--model', agentModel,                     // 에이전트별 모델 (haiku/sonnet/opus)
  '--output-format', 'stream-json',
  '--system-prompt', agentSystemPrompt,      // 역할 정의 (DB agents.system_prompt)
  '--append-system-prompt', HARD_RULES,      // 공통 규칙
  '--allowedTools', agentAllowedTools,       // 역할별 도구 제한
  '--effort', agentEffort,                   // 역할별 노력 수준
  message,
];

역할별 allowedTools (4명 병렬 토론 결과)

세션 격리

에이전트 A (backend_dev_a) → --session-id aaa-bbb-111 → 독립 대화
에이전트 B (frontend_dev_a) → --session-id ccc-ddd-222 → 독립 대화
에이전트 C (security_a)     → --session-id eee-fff-333 → 독립 대화

• 같은 CWD에서 여러 에이전트가 동시 실행 가능
• -c 대신 --session-id로 대화 이어감 (재사용 시 동일 UUID)
• 세션 ID는 서버가 에이전트별로 생성/관리

4. 병렬 실행 검증 결과

=== 병렬 spawn 테스트 (3개 에이전트) ===

✅ [be-arch]  (18.4s) — 아키텍처 일관성 검증
✅ [fe-arch]  (10.1s) — 클라이언트 간 아키텍처 일관성
✅ [security] (8.9s)  — RLS 정책 검증

총 소요: 18.4s (순차였으면 ~37.4s)

• 3개 동시 spawn → 전부 성공
• 병렬 실행 시 약 2배 속도 향상
• --session-id로 세션 충돌 없음 확인

5. 알려진 이슈 & 주의사항

6. 파일 위치

7. DELEGATE (병렬 위임)

Director가 에이전트에게 작업을 위임할 때 사용하는 태그:

[DELEGATE]
api_dev_1: 로그인 API 엔드포인트 구현
ios_dev_1: iOS 로그인 화면 구현
db_security_1: 인증 관련 RLS 정책 검토
[/DELEGATE]

서버 처리 흐름:

1. Director 응답에서 [DELEGATE]...[/DELEGATE] 블록 파싱
2. DB에서 해당 에이전트 존재 확인 + system_prompt 로드
3. callAgentsParallel() — 모든 에이전트 동시 spawn
4. 결과 수집 → Director에게 전달 → 종합 보고

관련 함수:

• parseDelegates(content) — DELEGATE 블록 파싱
• callAgent(agentId, systemPrompt, message, cwd) — 개별 에이전트 spawn
• callAgentsParallel(tasks[], cwd) — 병렬 실행

8. 조직 구조

회장 (모바일)
  └── Director (고정, 운영 총괄)
        ├── Architecture: System, Data, Cloud
        ├── Backend: API, Business Logic, Database
        ├── Frontend: Web, iOS, Android, Designer
        ├── Security: App, DB, Infra
        ├── QA: Functional, Performance
        ├── DevOps: CI/CD, Infrastructure
        ├── Research: Tech, Market
        ├── Marketing: Growth, Content
        └── Finance: Accountant

• Director: 고정 (해고 불가). 회장 메시지 수신 → 분석 → DELEGATE → 종합 보고
• 에이전트: 회장이 모바일에서 고용/해고. 같은 직종 복수 고용 가능 (난제시 토론)

변경 이력