harness/plugins/zioinfo/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) 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·배포 트리거·배포 확인, 에이전트 간 산출물 중계, 최종 알림·릴리즈 노트	references/hermes.md	_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·전달·알림만 — 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: "general-purpose", team_name: "zio-dev-team", name: "hermes",
      prompt: "references/hermes.md 지침대로 _workspace/02_bot_report.md PASS 확인 후 전달 패키지(_workspace/03_delivery.md)·commit/push·배포 확인·알림. push는 사용자 요청 시만. 파이프라인 중 산출물 중계 보조.")

작업 유형별 팀 조정:

• 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. 변경 사항 요약을 사용자에게 보고
5. 모든 작업 완료 후 팀원 종료(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가 사용자에게 보고