---
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(
  team_name: "zio-dev-team",
  members: [
    { name: "analyst", agent_type: "analyst", model: "opus",
      prompt: "PROJECT_MAP.md를 읽고 요청 분석 후 _workspace/00_analysis.md 작성. 구현 계획과 영향 파일 목록 포함." },
    { name: "agent", agent_type: "general-purpose", model: "opus",
      prompt: "analyst의 계획을 읽고 코드 구현. React/Spring Boot/Mobile 스택에 맞는 컨벤션 준수." },
    { name: "bot", agent_type: "general-purpose", model: "opus",
      prompt: "구현 완료 후 테스트 실행, 린트, 빌드 검증. 결과를 _workspace/02_bot_report.md에 기록." }
  ]
)
```

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

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

```
TaskCreate(tasks: [
  { title: "프로젝트 분석 및 구현 계획 수립", assignee: "analyst",
    description: "PROJECT_MAP.md 기반으로 영향 범위 파악. _workspace/00_analysis.md 작성." },
  { title: "코드 구현", assignee: "agent",
    description: "_workspace/00_analysis.md 읽고 해당 스택 컨벤션으로 구현.",
    depends_on: ["프로젝트 분석 및 구현 계획 수립"] },
  { title: "테스트 및 검증", assignee: "bot",
    description: "구현 코드 테스트 실행. _workspace/02_bot_report.md 작성.",
    depends_on: ["코드 구현"] }
])
```

팀원 간 통신 프로토콜:
- analyst → agent: `SendMessage` ("분석 완료. `_workspace/00_analysis.md` 참조. 구현 시작.")
- agent → bot: `SendMessage` ("구현 완료. 테스트 실행 요청.")
- bot → orchestrator: `SendMessage` ("검증 완료. `_workspace/02_bot_report.md` 참조.")

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

1. `_workspace/02_bot_report.md` 확인 — 실패 항목 있으면 agent에 재작업 지시
2. 새 파일·폴더가 생성된 경우 `PROJECT_MAP.md` 업데이트 (`references/folder-map.md` 참조)
3. 변경 사항 요약을 사용자에게 보고

---

## 에러 핸들링

| 상황 | 대응 |
|------|------|
| 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가 사용자에게 보고