# PROJECT_MAP

> 마지막 업데이트: 2026-06-23
> 프로젝트: harness — Claude Code Plugin (Team-Architecture Factory)
> 버전: 1.3.1 (plugin.json 기준)
> 업데이트 방법: "PROJECT_MAP 업데이트해줘" 또는 구조 변경 후 analyst 에이전트 자동 갱신

---

## 프로젝트 목적

Claude Code용 **팀 아키텍처 팩토리** 플러그인 저장소.
- `harness` 스킬: 도메인 설명 → 에이전트 팀 + 스킬 자동 생성 (메타 스킬)
- `zio-harness` 스킬: React + Spring Boot + Mobile 풀스택 개발 에이전트 팀

---

## 루트 디렉토리 구조

| 파일/폴더 | 용도 |
|----------|------|
| `.claude-plugin/` | Claude Code 플러그인 매니페스트 |
| `.claude/` | 이 저장소의 에이전트 정의 파일 |
| `.github/` | GitHub 이슈/PR 템플릿 |
| `skills/` | 플러그인 스킬 정의 |
| `docs/` | 장기 참조 문서 (퀵스타트, 실험적 의존성) |
| `_workspace/` | 에이전트 작업 중간 산출물 (git 추적 제외 권장) |
| `CLAUDE.md` | Claude Code 세션 진입 포인터 + 하네스 트리거 규칙 |
| `PROJECT_MAP.md` | 이 파일 — 폴더 구조 메모리 |
| `README.md` | 영문 메인 설명 |
| `README_KO.md` | 한국어 설명 |
| `README_JA.md` | 일본어 설명 |
| `CHANGELOG.md` | 버전별 변경 이력 (Semantic Versioning) |
| `CONTRIBUTING.md` | 기여 가이드 + SLA (PR 72h, Issue 48h) |
| `LICENSE` | Apache 2.0 |
| `index.html` | 플러그인 마켓플레이스 랜딩 |
| `privacy.html` | 개인정보처리방침 |
| `harness_*.png` | 브랜드 이미지 (banner, icon, social, team) |

---

## .claude-plugin/ (플러그인 매니페스트)

| 파일 | 용도 |
|------|------|
| `plugin.json` | harness 플러그인 메타 (name, version, author, keywords) |
| `marketplace.json` | 마켓플레이스(`ythong-harness`) 등록 정보. 현재 등록 플러그인: `harness` (v1.3.1), `zio-harness` (v1.1.0), `proposal-builder` (v1.0.0), `pm-pmo` (v1.1.0) |

---

## .claude/agents/ (에이전트 정의)

zio-harness 풀스택 개발 에이전트 팀. 4종 에이전트가 파이프라인으로 협업.

| 파일 | 에이전트 타입 | 역할 |
|------|------------|------|
| `orchestrator.md` | general-purpose | 작업 분석, 팀 구성, 결과 종합. PROJECT_MAP 읽기 첫 번째 |
| `analyst.md` | Explore | 코드/구조 분석, PROJECT_MAP.md 생성·유지, 구현 계획 수립 |
| `bot.md` | general-purpose | 테스트·빌드·린트·Playwright E2E·DB 마이그레이션 자동화 |
| `agent.md` | general-purpose | React/Spring Boot/Mobile 코드 구현 |

**실행 순서**: orchestrator → analyst → agent → bot

---

## skills/ (플러그인 스킬)

### skills/harness/ (메타 하네스 — 핵심 플러그인)

| 파일 | 용도 |
|------|------|
| `SKILL.md` | 메인 스킬 정의. 7 Phase 워크플로우 (감사→분석→설계→에이전트→스킬→통합→검증) |
| `references/agent-design-patterns.md` | 6가지 아키텍처 패턴 + 에이전트 분리 기준 + 재사용 설계 |
| `references/orchestrator-template.md` | 팀/서브에이전트/하이브리드 오케스트레이터 템플릿 3종 |
| `references/team-examples.md` | 실전 팀 구성 예시 5종 (파일 전문 포함) |
| `references/skill-writing-guide.md` | 스킬 작성 패턴 + Progressive Disclosure + 재사용 설계 |
| `references/skill-testing-guide.md` | 테스트/평가/반복 개선 방법론 |
| `references/qa-agent-guide.md` | QA 에이전트 통합 가이드 + 7개 버그 패턴 |

### plugins/zio-harness/skills/zio-harness/ (풀스택 개발 하네스 — 독립 플러그인)

| 파일 | 용도 |
|------|------|
| `SKILL.md` | 오케스트레이터 진입점. 팀 구성·워크플로우·에러 핸들링·테스트 시나리오 포함 |
| `references/folder-map.md` | **PROJECT_MAP.md 생성·유지 시스템**. 폴더 구조 메모리 핵심 가이드 |
| `references/react.md` | React 18 + TypeScript + TanStack Query + Zustand 패턴 |
| `references/spring-boot.md` | Spring Boot 3.x 레이어 아키텍처 + JPA + JWT + Flyway |
| `references/mobile.md` | React Native + Expo + React Navigation + AsyncStorage |
| `references/playwright.md` | E2E 테스트 + 페이지 오브젝트 패턴 + CI 통합 |
| `references/database.md` | PostgreSQL/MySQL MCP 설정 + Flyway 마이그레이션 + JPA 최적화 |
| `references/orchestrator.md` | Orchestrator 에이전트 상세 정의 템플릿 |
| `references/analyst.md` | Analyst 에이전트 상세 정의 템플릿 |
| `references/bot.md` | Bot 에이전트 상세 정의 템플릿 |
| `references/agent.md` | Dev Agent 에이전트 상세 정의 템플릿 |

---

## docs/ (참조 문서)

| 파일 | 용도 |
|------|------|
| `quickstart.md` | 5분 퀵스타트 (마켓플레이스 설치 → 하네스 생성 → 샘플 실행) |
| `experimental-dependency.md` | `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` 플래그 설명 및 변경 대응 계획 |
| `plugin-guide.md` | **하네스 플러그인 작성 가이드** — 플러그인 구조·`plugin.json`/`marketplace.json`·스킬/에이전트 레이아웃·로컬 테스트·버전 관리 (작성자용) |

---

## .github/ (GitHub 자동화)

| 경로 | 용도 |
|------|------|
| `ISSUE_TEMPLATE/bug_report.yml` | 버그 리포트 템플릿 |
| `ISSUE_TEMPLATE/feature_request.yml` | 기능 요청 템플릿 |
| `ISSUE_TEMPLATE/question.yml` | 질문 템플릿 |
| `ISSUE_TEMPLATE/config.yml` | 이슈 템플릿 설정 |
| `PULL_REQUEST_TEMPLATE.md` | PR 템플릿 |

---

## _workspace/ (에이전트 작업 공간)

에이전트가 실행 중 생성하는 중간 산출물. 세션 간 유지되므로 작업 이력 추적 가능.

| 파일/폴더 | 용도 |
|----------|------|
| `01_auditor_repo_audit.md` | 저장소 감사 산출물 (이전 실행) |
| `02_content_launch_contents.md` | 런치 콘텐츠 산출물 (이전 실행) |
| `03_scout_outreach_map.md` | 아웃리치 맵 산출물 (이전 실행) |
| `04_strategist_launch_plan.md` | 런치 전략 산출물 (이전 실행) |
| `release/audit-2026-04-18.md` | v1.2.0 릴리즈 감사 |
| `release/post-m0-audit-2026-04-18.md` | M0 릴리즈 후 감사 |

---

## 핵심 컨벤션

| 항목 | 규칙 |
|------|------|
| 스킬 위치 | `skills/{skill-name}/SKILL.md` |
| 참조 파일 | `skills/{skill-name}/references/*.md` |
| 에이전트 정의 | `.claude/agents/{name}.md` |
| SKILL.md 크기 제한 | 500줄 이내 (초과 시 references/ 분리) |
| 버전 관리 | Semantic Versioning, plugin.json 기준 |
| 다국어 문서 | README.md (EN) · README_KO.md · README_JA.md 동기화 필수 |

---

## 환경 요구사항

| 항목 | 값 |
|------|-----|
| Claude Code 버전 | v2.x 이상 |
| 필수 환경 변수 | `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` |
| 설치 명령(이 저장소) | `claude plugin marketplace add https://git.zioinfo.co.kr/ythong/harness.git` → `claude plugin install harness@ythong-harness` (⚠️ 비-GitHub git 저장소는 **`.git` 필수** — 없으면 `expected object, received string` 오류) |

---

## 최근 변경 이력

| 날짜 | 변경 내용 | 담당 |
|------|----------|------|
| 2026-06-23 | `docs/plugin-guide.md` 신설(하네스 플러그인 작성 가이드) + CONTRIBUTING 포인터 + PROJECT_MAP 현행화(버전 1.3.1·마켓플레이스명·설치명령) | - |
| 2026-06-17 | PROJECT_MAP.md 초기 생성 | analyst |
| 2026-06-17 | zio-harness 스킬 + 에이전트 4종 신규 생성 | orchestrator |
| 2026-04-18 | v1.2.0/1.2.1 릴리즈: 버전 정합성·포지셔닝·CONTRIBUTING·docs/ 신설 | - |