harness/plugins/zioinfo/skills/zio-harness/SKILL.md

---
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) UI 디자인, 화면 시안, 디자인 시스템/토큰, 선(line) SVG 아이콘 제작 요청 시, (7) 배포, Gitea push, 전달, 릴리즈 노트, 결과 알림, 헤르메스(전령) 요청 시, (8) 오케스트레이터·분석가·디자이너·봇·에이전트·전령 팀 구성 요청 시 반드시 이 스킬을 사용하라. 다시 실행, 재실행, 업데이트, 보완 요청도 포함."
---

# zio-harness — Full-Stack Dev Orchestrator

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

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

```
analyst → designer(UI 작업 시) → agent → bot → hermes(전달·배포 시) → (orchestrator 종합)
```

## 에이전트 구성

| 팀원 | 역할 | 주요 스킬 | 출력 |
|------|------|---------|------|
| analyst | 코드 분석·폴더 구조 파악·구현 계획 | `references/analyst.md` | `_workspace/00_analysis.md` |
| designer | UI/UX 설계·디자인 토큰·컴포넌트 스펙·선 SVG 아이콘·스티치(Stitch) 의뢰 design.md 생성(MCP 연결 시 직접 요청) | `references/designer.md` | `_workspace/01_design_spec.md` + `assets/icons/*.svg` (+ 필요 시 `design.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` |
| hermes | 전령 — 검증 통과 산출물의 Gitea commit/push·배포 확인, 산출물 중계, 알림·릴리즈 노트 + **4대 특징: persistent memory(`memory: user`)·skill 자가 축적·cron 정기작업·External APIs(Gitea REST·webhook)** | `references/hermes.md` + `hermes-delivery` 스킬(사전 로드) | `_workspace/03_delivery.md` |

> designer는 **UI가 있는 작업에만**, hermes는 **전달·배포·알림이 있는 작업에만** 참여한다 (분석·로컬 수정만은 3인 파이프라인).

## 참조 파일 로딩 가이드

| 작업 유형 | 로드할 파일 |
|----------|-----------|
| 폴더 구조 파악/업데이트 | `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` |
| UI/UX 디자인·아이콘 제작 | `references/designer.md` |
| 배포·push·전달·알림 | `references/hermes.md` |
| 에이전트 설계 | `references/orchestrator.md`, `references/analyst.md`, `references/designer.md`, `references/bot.md`, `references/agent.md`, `references/hermes.md` |
| KINTEX 도메인 지식 | `knowledge/kintex/` (기획서·설계·분석·백로그 등 md 전체) |
| GUARDiA 전사 지식 | `knowledge/guardia/` (솔루션 카탈로그·표준 프레임워크·운영 CI/CD·개발 교훈) |

## 지식 그래프 (graphify) — 소스 자동 분석

플러그인 설치만으로 프로젝트 소스가 자동 분석된다. SessionStart 훅(`scripts/graphify_setup.py`)이:

1. `graphifyy[sql]` 패키지를 자동 설치 (pip, 1회)
2. 그래프가 없으면 `graphify extract . --code-only`로 최초 구축 (로컬 AST — LLM/외부 API 불필요)
3. 그래프가 있으면 `graphify update .`로 변경분만 갱신

**규칙 — 코드베이스 구조 질문은 그래프 우선:**

- `graphify-out/graph.json`이 존재하면 파일 전수 검색 전에 반드시 그래프를 먼저 조회한다:
  - `graphify query "<질문>"` — 관련 노드 BFS 탐색
  - `graphify explain "<심볼>"` — 노드·이웃 설명
  - `graphify path "A" "B"` — 두 심볼 간 경로
  - `graphify affected "X"` — 변경 영향 범위 (리팩터링 전 필수)
- analyst는 Phase 1 분석 시 그래프 조회 결과를 `_workspace/00_analysis.md`에 인용한다.
- agent는 구현 전 `graphify affected`로 영향 파일을 확인한다.
- 훅을 끄려면 환경변수 `ZIO_HARNESS_NO_GRAPHIFY=1`.

## KINTEX 지식 베이스

`knowledge/kintex/`에 KINTEX AI 전시·행사시스템의 전체 md 문서(기획 PLANNING·design·데이터표준·벤치마킹 분석·백로그·소유자 피드백 로그 등)가 내장되어 있다. KINTEX 관련 작업 시 이 폴더를 도메인 지식 소스로 우선 참조한다.

## GUARDiA 전사 지식 베이스

GUARDiA 전체 md 문서(2,400여 개)를 분석·정제한 지식이 `knowledge/guardia/`에 내장되어 있다:

| 파일 | 내용 | 참조 시점 |
|------|------|----------|
| `solutions-catalog.md` | 전 솔루션 카탈로그 (스택·포트·DB·연동 맵) | 어떤 GUARDiA 솔루션이든 작업 시작 시 |
| `standard-framework.md` | GUARDiA 표준 프레임워크 (UIMS 기준 스택·인증 JWT+2FA·공통모듈·WISE 디자인·AI 플랫폼·보안 불변) | 신규 기능/솔루션 개발 시 |
| `operations-cicd.md` | 배포 파이프라인·webhook·systemd·health 게이트·테스트 체계 | 배포/운영 작업 시 |
| `lessons-learned.md` | 증상→근본원인→해결 패턴 교훈 모음 (DB·배포·AI·UI·프로세스) | 오류 진단·리팩터링 전 필수 |

analyst는 분석 시작 시 이 지식 베이스를 프로젝트 컨텍스트로 로드하고, 교훈 문서의 기지 함정과 충돌하는 구현을 발견하면 즉시 보고한다.

---

## 워크플로우

### 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 + 모바일) — UI 포함 시 designer 참여
- **Design**: UI 디자인·화면 시안·디자인 토큰·아이콘만
- **Bug**: 버그 수정
- **Test**: 테스트 작성/실행
- **Refactor**: 코드 개선
- **Analysis**: 코드/구조 분석만
- **Setup**: 초기 프로젝트 설정
- **DocMap**: PROJECT_MAP.md 생성/업데이트만
- **Deploy**: 배포·push·전달·알림·정기작업(cron/스케줄) — hermes 담당

### 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: "general-purpose", team_name: "zio-dev-team", name: "designer",
      prompt: "references/designer.md 지침대로 _workspace/00_analysis.md 기반 디자인 스펙(_workspace/01_design_spec.md)과 선 SVG 아이콘 산출. 기존 스타일 자산 우선.")
Agent(subagent_type: "agent",           team_name: "zio-dev-team", name: "agent",
      prompt: "analyst의 계획과 designer의 01_design_spec.md를 읽고 코드 구현. React/Spring Boot/Mobile 스택에 맞는 컨벤션 준수.")
Agent(subagent_type: "bot",             team_name: "zio-dev-team", name: "bot",
      prompt: "구현 완료 후 테스트 실행·린트·빌드 검증. 결과를 _workspace/02_bot_report.md에 기록.")
Agent(subagent_type: "zioinfo:hermes",   team_name: "zio-dev-team", name: "hermes",
      prompt: "_workspace/02_bot_report.md PASS 확인 후 전달 패키지(_workspace/03_delivery.md)·commit/push·배포 확인·알림. push는 사용자 요청 시만. 메모리의 채널 레지스트리·학습 패턴 우선 조회.")
# 번들 에이전트(zioinfo:hermes)는 memory: user + hermes-delivery 스킬 사전 로드.
# 플러그인 미설치 환경 폴백: subagent_type "general-purpose" + references/hermes.md 지침 주입.
```

작업 유형별 팀 조정:
- **Analysis/DocMap**: analyst만 spawn (팀 불필요)
- **Design**: designer만 spawn (필요 시 analyst 선행)
- **Test**: bot만 spawn
- **Deploy**: hermes만 spawn (검증 리포트 없으면 bot 선행)
- **Feature(UI 포함 + 전달)**: 5인 전체 파이프라인 (analyst → designer → agent → bot → hermes)
- **Feature(UI 없음)/Bug/Refactor**: designer 제외 — 전달·배포 요청 있으면 hermes 포함, 없으면 3인 파이프라인

### 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: "디자인 스펙 작성 (UI 작업 시)",
                description: "_workspace/00_analysis.md 기반 01_design_spec.md + 선 SVG 아이콘 산출.")
TaskUpdate(task: t2, owner: "designer", blockedBy: [t1])

t3 = TaskCreate(subject: "코드 구현",
                description: "_workspace/00_analysis.md(+01_design_spec.md) 읽고 해당 스택 컨벤션으로 구현.")
TaskUpdate(task: t3, owner: "agent", blockedBy: [t2])   # UI 없는 작업은 blockedBy: [t1]

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

t5 = TaskCreate(subject: "전달·배포·알림 (전달 작업 시)",
                description: "02_bot_report.md PASS 확인 → _workspace/03_delivery.md·commit/push(요청 시)·배포 확인·최종 알림.")
TaskUpdate(task: t5, owner: "hermes", blockedBy: [t4])
```

팀원 간 통신 프로토콜 — `SendMessage`는 `{to, summary, message}` 형식이며, 작업 완료는 `TaskUpdate`로 `completed` 처리하면 리더에게 자동 통지된다:
- analyst → designer(UI 작업) 또는 agent: `SendMessage(to: "designer", summary: "분석 완료", message: "_workspace/00_analysis.md 참조. 디자인 스펙 시작.")`
- designer → agent: `SendMessage(to: "agent", summary: "디자인 스펙 완료", message: "_workspace/01_design_spec.md + assets/icons 참조. 구현 시작.")`
- agent → bot: `SendMessage(to: "bot", summary: "구현 완료", message: "테스트 실행 요청.")`
- bot → designer: 시각 QA 실패(레이아웃 깨짐·대비 미달) 시 스펙 보완 요청
- bot → hermes: `SendMessage(to: "hermes", summary: "검증 통과", message: "_workspace/02_bot_report.md PASS. 전달 시작.")`
- hermes → agent: push 거부·배포 실패가 코드 원인일 때 수정 요청
- hermes(중계): 단계 전환 시 이전 산출물 경로+요지를 다음 담당자에게 요약 전달 (대용량은 _workspace/ 파일로)
- 각 팀원: 작업 끝나면 `TaskUpdate(task, status: "completed")` → 리더(오케스트레이터)가 태스크 완료 알림과 `_workspace/` 파일로 진행 파악 (별도 보고 메시지 불필요)

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

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

---

## 에러 핸들링

| 상황 | 대응 |
|------|------|
| analyst 분석 실패 | 기본 파일 스캔으로 대체, 계속 진행 |
| agent 구현 오류 | 오류 메시지를 analyst에 전달, 재계획 1회 |
| bot 테스트 실패 | 실패 로그를 agent에 전달, 수정 1회 재시도 |
| hermes push 거부 | 원인 진단(behind·훅 실패) 후 보고 — force push·`--no-verify` 우회 금지 |
| hermes 배포 확인 실패 | 배포 로그·health 결과를 agent에 전달, 코드 원인이면 수정 후 재전달 1회 |
| PROJECT_MAP.md 손상 | 삭제 후 재생성 (folder-map.md 절차 따름) |

---

## 테스트 시나리오

**정상 흐름 — Feature 개발 (UI 포함):**
1. 사용자: "사용자 로그인 기능 추가해줘 (React 화면 + Spring Boot API + 모바일)"
2. Phase 0: PROJECT_MAP.md 로드 → 현재 auth 관련 파일 파악
3. Phase 2: 4인 팀 구성 (analyst·designer·agent·bot)
4. analyst → 영향 파일 식별, API 스펙 정의
5. designer → 로그인 화면 레이아웃·토큰·컴포넌트 스펙 + 선 SVG 아이콘 (`01_design_spec.md`)
6. agent → React LoginPage, Spring Boot AuthController, Mobile LoginScreen 구현 (디자인 스펙 준수)
7. bot → Playwright E2E, JUnit 테스트 실행
8. hermes → 02_bot_report.md PASS 확인 → 03_delivery.md·commit/push(사용자 요청 시)·최종 알림
9. PROJECT_MAP.md 업데이트

**정상 흐름 — 배포·전달(Deploy):**
1. 사용자: "이번 변경 Gitea에 push하고 배포 확인해줘"
2. hermes 단독 spawn → 기존 `02_bot_report.md` PASS 확인 (없으면 bot 선행 spawn)
3. 전달 패키지(03_delivery.md) 구성 → 변경 파일만 add → 커밋·push → webhook 배포 로그·health 확인 → 결과 보고

**정상 흐름 — 디자인 의뢰(Design):**
1. 사용자: "메인 히어로 이미지를 스티치에 의뢰할 design.md 만들어줘"
2. designer 단독 spawn → 참조 에셋 분석 → `_workspace/design.md`(영문 프롬프트+검수 기준) 산출
3. Stitch MCP 연결 시 직접 생성 요청 → 수령물 검수, 미연결 시 의뢰서만 전달

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