Agent Interaction Guide

에이전트 간 상호작용 구조와 워크플로우를 정의합니다.

팀 구성

┌─────────────────────────────────────────────────────────┐
│                    Strategic Layer                       │
│  ┌─────────┐    ┌──────────────────┐                    │
│  │   CTO   │───▶│ Planning Advisor │                    │
│  └────┬────┘    └────────┬─────────┘                    │
│       │                  │ (Codex 호출)                  │
│       ▼                  ▼                              │
│  ┌─────────────────────────────────────┐                │
│  │          .context/plan.md           │                │
│  └─────────────────────────────────────┘                │
└─────────────────────────────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────┐
│                   Execution Layer                        │
│                                                         │
│  ┌───────────┐  ┌──────────────┐  ┌──────────────┐     │
│  │  FE Lead  │  │ Electron Lead │  │ Platform Lead │     │
│  └─────┬─────┘  └──────┬───────┘  └──────┬───────┘     │
│        │               │                  │             │
│        └───────────────┼──────────────────┘             │
│                        │                                │
│                        ▼                                │
│              ┌─────────────────┐                        │
│              │    UX Lead      │ (UI 검토)              │
│              └─────────────────┘                        │
└─────────────────────────────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────┐
│                    Support Layer                         │
│                                                         │
│  ┌──────────────┐  ┌─────────────┐  ┌──────────────┐   │
│  │ DevOps Lead  │  │  Test Lead  │  │ Tech Writer  │   │
│  └──────────────┘  └─────────────┘  └──────────────┘   │
└─────────────────────────────────────────────────────────┘

워크플로우

Phase 1: 계획 수립

요청 접수
    │
    ▼
┌─────────┐
│   CTO   │ ─── .context/plan.md 작성
└────┬────┘
     │
     ▼
┌──────────────────┐
│ Planning Advisor │ ─── 계획 검토
└────────┬─────────┘
         │
    ┌────┴────┐
    │ 위험도? │
    └────┬────┘
         │
   ┌─────┼─────┐
   ▼     ▼     ▼
 저/중  고위험
   │     │
   │     ▼
   │  Codex 검증
   │     │
   └──┬──┘
      ▼
  피드백 반영
      │
      ▼
  계획 확정

Phase 2: 구현

계획에 명시된 담당 Lead가 작업 수행:

변경 영역	담당 Lead	협업 대상
React 컴포넌트	FE Lead	UX Lead
Main process	Electron Lead	Platform Lead
IPC 채널	Electron Lead	FE Lead
launchd 연동	Platform Lead	Electron Lead
스타일/디자인	UX Lead	FE Lead
빌드/패키징	DevOps Lead	-
테스트	Test Lead	해당 Lead
문서	Tech Writer	해당 Lead

Phase 3: 검증

구현 완료
    │
    ▼
┌──────────────┐
│  Test Lead   │ ─── 테스트 커버리지 및 품질 검토
└──────┬───────┘
       │
       ▼
┌──────────────┐
│ DevOps Lead  │ ─── bun run test && bun run build
└──────┬───────┘
       │
       ▼
┌──────────────┐
│   UX Lead    │ ─── UI 변경 시 시각적 검토
└──────┬───────┘
       │
       ▼
┌──────────────┐
│ Tech Writer  │ ─── 문서 업데이트 필요 시
└──────────────┘

공유 아티팩트

파일	용도	작성자	소비자
.context/plan.md	구현 계획	CTO	모든 Lead
.context/review.md	Planning Advisor 피드백	Planning Advisor	CTO
CLAUDE.md	프로젝트 가이드	Tech Writer	모든 에이전트

핸드오프 프로토콜

CTO → Planning Advisor

## 계획 검토 요청

plan.md 경로: .context/plan.md
주요 변경: [IPC 추가 / 시스템 연동 / UI 변경 / ...]
예상 위험도: [저 / 중 / 고]

Planning Advisor → CTO

## 계획 검토 결과

위험도: [저 / 중 / 고]
Codex 검증: [수행 / 생략]

### 이슈
1. ...

### 권고
1. ...

결론: [수정 필요 / 진행 가능]

CTO → Lead

## 작업 할당

담당: [FE Lead / Electron Lead / Platform Lead]
plan.md 섹션: [해당 섹션 참조]
성공 기준: [구체적 기준]
협업 필요: [다른 Lead와 협업 필요 시]

Lead → Lead (협업)

## 협업 요청

요청자: [FE Lead]
대상: [Electron Lead]
내용: IPC 채널 `jobs:newChannel` 추가 필요
스펙:
  - 입력: { ... }
  - 출력: { ... }

Lead → UX Lead (UI 검토)

## UI 검토 요청

변경 컴포넌트: [JobCard, LogViewer, ...]
스크린샷: [첨부 또는 dev server URL]
체크 포인트:
  - 디자인 시스템 준수
  - 레이아웃 깨짐

Lead → Tech Writer

## 문서 업데이트 요청

변경 내용: [새 IPC 채널 / 새 타입 / ...]
업데이트 대상: [CLAUDE.md / README.md]

IPC 변경 시 필수 협업

IPC 채널 추가/수정은 반드시 세 곳을 동시에 변경해야 함:

Electron Lead: src/main/ipc.ts (핸들러)
       │
       ├──▶ src/preload/index.ts (contextBridge)
       │
       └──▶ FE Lead: src/renderer/global.d.ts (타입)

협업 순서:

1. Electron Lead가 ipc.ts + preload/index.ts 수정
2. FE Lead에게 global.d.ts 타입 정의 요청
3. FE Lead가 렌더러에서 사용

에스컬레이션

Lead → CTO

다음 상황에서 CTO에게 에스컬레이션:

• 계획에 명시되지 않은 추가 변경 필요
• 다른 Lead와 의견 충돌
• 기술적 결정이 필요한 상황

Planning Advisor → CTO

다음 상황에서 계획 수정 요청:

• Codex가 심각한 이슈 발견
• 누락된 파일/변경사항 발견
• 실행 불가능한 계획

완료 조건

모든 작업은 다음을 만족해야 완료:

bun run test    # 전체 통과
bun run build   # 타입 에러 없음

추가로 plan.md에 명시된 성공 기준 충족.