harness/skills/zio-harness/SKILL.md

name	description
zio-harness	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가 사용자에게 보고