---
name: zio-harness
description: "React + Spring Boot + Mobile App 풀스택 개발 하네스. (1) 'zio 실행', 'zio-harness 시작', '풀스택 개발 시작' 요청 시, (2) React 컴포넌트/화면 개발, Spring Boot API 개발, 모바일 앱 개발 요청 시, (3) '프로젝트 분석', '폴더 구조 파악', 'PROJECT_MAP 업데이트' 요청 시, (4) Playwright E2E 테스트, 데이터베이스 MCP 작업 요청 시, (5) 기능 추가, 버그 수정, 리팩터링, 코드 리뷰 요청 시, (6) 오케스트레이터·분석가·봇·에이전트 팀 구성 요청 시 반드시 이 스킬을 사용하라. 다시 실행, 재실행, 업데이트, 보완 요청도 포함."
---

# zio-harness — Full-Stack Dev Orchestrator

React + Spring Boot + Mobile App 풀스택 개발을 에이전트 팀이 조율하는 통합 하네스.

## 실행 모드: 에이전트 팀 (파이프라인 패턴)

```
analyst → agent → bot → (orchestrator 종합)
```

## 에이전트 구성

| 팀원 | 역할 | 주요 스킬 | 출력 |
|------|------|---------|------|
| analyst | 코드 분석·폴더 구조 파악·구현 계획 | `references/analyst.md` | `_workspace/00_analysis.md` |
| agent | React/Spring Boot/Mobile 코드 구현 | `references/react.md`, `spring-boot.md`, `mobile.md` | 실제 코드 파일 |
| bot | 테스트 실행·빌드·린트·DB 마이그레이션 | `references/playwright.md`, `database.md` | `_workspace/02_bot_report.md` |

## 참조 파일 로딩 가이드

| 작업 유형 | 로드할 파일 |
|----------|-----------|
| 폴더 구조 파악/업데이트 | `references/folder-map.md` |
| React 개발 | `references/react.md` |
| Spring Boot 개발 | `references/spring-boot.md` |
| 모바일 앱 개발 | `references/mobile.md` |
| E2E 테스트 | `references/playwright.md` |
| DB/MCP 작업 | `references/database.md` |
| 에이전트 설계 | `references/orchestrator.md`, `references/analyst.md`, `references/bot.md`, `references/agent.md` |

---

## 워크플로우

### Phase 0: PROJECT_MAP 로드 (폴더 구조 메모리)

프로젝트 루트의 `PROJECT_MAP.md` 존재 여부를 확인한다:

- **존재**: 파일을 읽어 현재 프로젝트 구조를 파악한다. 이후 분석 시 참조 기준이 된다.
- **미존재**: 초기 실행으로 판단. Phase 1 완료 후 `references/folder-map.md`를 읽고 PROJECT_MAP.md를 생성한다.

PROJECT_MAP.md는 Claude Code가 세션 간에 프로젝트 구조를 기억하는 핵심 파일이다. 항상 최신 상태를 유지한다.

### Phase 1: 컨텍스트 확인

```
_workspace/ 존재 여부 확인
├── 미존재 → 초기 실행 (Phase 2로)
├── 존재 + 부분 수정 요청 → 부분 재실행 (해당 에이전트만 재호출)
└── 존재 + 새 요청 → 새 실행 (_workspace/ → _workspace_{YYYYMMDD_HHMMSS}/ 이동)
```

작업 유형을 감지한다:
- **Feature**: 새 기능 개발 (React 화면 + API + 모바일)
- **Bug**: 버그 수정
- **Test**: 테스트 작성/실행
- **Refactor**: 코드 개선
- **Analysis**: 코드/구조 분석만
- **Setup**: 초기 프로젝트 설정
- **DocMap**: PROJECT_MAP.md 생성/업데이트만

### Phase 2: 팀 구성

> **요구사항:** 팀 도구(`TeamCreate`/`SendMessage`/`TaskCreate`)는 `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` 플래그가 켜진 세션에서만 사용 가능하다.

`TeamCreate`는 **빈 팀**을 만든다(`members` 인자 없음). 팀원은 `Agent` 도구로 `team_name`·`name`·`subagent_type`을 지정해 spawn한다. 오케스트레이터(이 스킬 세션)가 곧 팀 리더이며, 별도 팀원으로 만들지 않는다.

1) 빈 팀 생성:

```
TeamCreate(team_name: "zio-dev-team", description: "React+Spring Boot+Mobile 풀스택 개발")
```

2) 팀원 spawn (커스텀 에이전트 타입 analyst/agent/bot 사용):

```
Agent(subagent_type: "analyst", team_name: "zio-dev-team", name: "analyst",
      prompt: "PROJECT_MAP.md를 읽고 요청 분석 후 _workspace/00_analysis.md 작성. 구현 계획과 영향 파일 목록 포함.")
Agent(subagent_type: "agent",   team_name: "zio-dev-team", name: "agent",
      prompt: "analyst의 계획을 읽고 코드 구현. React/Spring Boot/Mobile 스택에 맞는 컨벤션 준수.")
Agent(subagent_type: "bot",     team_name: "zio-dev-team", name: "bot",
      prompt: "구현 완료 후 테스트 실행·린트·빌드 검증. 결과를 _workspace/02_bot_report.md에 기록.")
```

작업 유형별 팀 조정:
- **Analysis/DocMap**: analyst만 spawn (팀 불필요)
- **Test**: bot만 spawn
- **Feature/Bug**: 전체 팀 파이프라인

### Phase 3: 작업 등록 및 실행

태스크는 **한 번에 하나씩** 생성한다(`subject`/`description`). 소유자는 `TaskUpdate`의 `owner`로, 의존성은 `blockedBy`로 지정한다:

```
t1 = TaskCreate(subject: "프로젝트 분석 및 구현 계획 수립",
                description: "PROJECT_MAP.md 기반으로 영향 범위 파악. _workspace/00_analysis.md 작성.")
TaskUpdate(task: t1, owner: "analyst")

t2 = TaskCreate(subject: "코드 구현",
                description: "_workspace/00_analysis.md 읽고 해당 스택 컨벤션으로 구현.")
TaskUpdate(task: t2, owner: "agent", blockedBy: [t1])

t3 = TaskCreate(subject: "테스트 및 검증",
                description: "구현 코드 테스트 실행. _workspace/02_bot_report.md 작성.")
TaskUpdate(task: t3, owner: "bot", blockedBy: [t2])
```

팀원 간 통신 프로토콜 — `SendMessage`는 `{to, summary, message}` 형식이며, 작업 완료는 `TaskUpdate`로 `completed` 처리하면 리더에게 자동 통지된다:
- analyst → agent: `SendMessage(to: "agent", summary: "분석 완료", message: "_workspace/00_analysis.md 참조. 구현 시작.")`
- agent → bot: `SendMessage(to: "bot", summary: "구현 완료", message: "테스트 실행 요청.")`
- 각 팀원: 작업 끝나면 `TaskUpdate(task, status: "completed")` → 리더(오케스트레이터)가 태스크 완료 알림과 `_workspace/` 파일로 진행 파악 (별도 보고 메시지 불필요)

### Phase 4: 결과 종합 및 PROJECT_MAP 업데이트

1. `_workspace/02_bot_report.md` 확인 — 실패 항목 있으면 agent에 재작업 지시(`SendMessage`)
2. 새 파일·폴더가 생성된 경우 `PROJECT_MAP.md` 업데이트 (`references/folder-map.md` 참조)
3. 변경 사항 요약을 사용자에게 보고
4. 모든 작업 완료 후 팀원 종료(`SendMessage(to, message: {type: "shutdown_request"})`) → `TeamDelete`로 팀·태스크 정리

---

## 에러 핸들링

| 상황 | 대응 |
|------|------|
| analyst 분석 실패 | 기본 파일 스캔으로 대체, 계속 진행 |
| agent 구현 오류 | 오류 메시지를 analyst에 전달, 재계획 1회 |
| bot 테스트 실패 | 실패 로그를 agent에 전달, 수정 1회 재시도 |
| PROJECT_MAP.md 손상 | 삭제 후 재생성 (folder-map.md 절차 따름) |

---

## 테스트 시나리오

**정상 흐름 — Feature 개발:**
1. 사용자: "사용자 로그인 기능 추가해줘 (React 화면 + Spring Boot API + 모바일)"
2. Phase 0: PROJECT_MAP.md 로드 → 현재 auth 관련 파일 파악
3. Phase 2: 3인 팀 구성
4. analyst → 영향 파일 식별, API 스펙 정의
5. agent → React LoginPage, Spring Boot AuthController, Mobile LoginScreen 구현
6. bot → Playwright E2E, JUnit 테스트 실행
7. PROJECT_MAP.md 업데이트

**에러 흐름 — 빌드 실패:**
1. bot이 빌드 실패 감지 → agent에 SendMessage
2. agent가 오류 수정 → bot이 재검증
3. 2회 실패 시 orchestrator가 사용자에게 보고
