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 |
개인정보처리방침 |
zioinfo_*.png |
브랜드 이미지 (ZIO INFOTECH 로고 기반) (banner, icon, social, team) |
.claude-plugin/ (플러그인 매니페스트)
| 파일 |
용도 |
plugin.json |
harness 플러그인 메타 (name, version, author, keywords) |
marketplace.json |
마켓플레이스(ythong) 등록 정보. 현재 등록 플러그인: harness (v1.3.1), zio-harness (v1.1.0), proposal-builder (v1.0.0), zioinfo (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/designer.md |
Designer 에이전트 — UI/UX 스펙·디자인 토큰·선 SVG 아이콘·Stitch 의뢰 design.md 생성(MCP 요청) |
references/hermes.md |
Hermes 에이전트 — 전령: Gitea commit/push·배포 확인·에이전트 간 산출물 중계·최종 알림·릴리즈 노트 |
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 (⚠️ 비-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/ 신설 |
- |
2517bc7489