harness/docs/plugin-guide.md

하네스 플러그인 가이드

도메인 전용 하네스(에이전트 팀 + 스킬)를 Claude Code 플러그인으로 패키징·배포하는 방법. 대상: 자신의 도메인(예: 풀스택 개발, 데이터 마이그레이션, 보안 점검)에 맞는 하네스를 만들어 팀·조직에 재사용시키려는 작성자.

English(예정) · 한국어

---

0. 두 가지를 먼저 구분하자

개념	무엇	예시
harness 메타 스킬	도메인 한 문장 → 에이전트 팀 + 스킬을 생성하는 팩토리	claude "이 프로젝트용 하네스 구성해줘"
하네스 플러그인	특정 도메인에 맞춰 이미 완성된 하네스(오케스트레이터 스킬·에이전트·레퍼런스)를 배포 단위로 묶은 것	zio-harness(React+Spring+모바일 풀스택)

이 가이드는 후자(완성된 하네스를 플러그인으로 만들기)를 다룹니다. 하네스 자체를 처음 설계하는 방법은 메타 스킬(skills/harness/SKILL.md)을 참고하세요.

워크플로우 요약:

① harness 메타 스킬로 하네스 초안 생성  →  ② 플러그인 구조로 패키징  →  ③ 로컬 link 테스트  →  ④ 마켓플레이스 등록·버전 배포

---

원칙 0 — 설계(디자인)가 먼저다 ⚠️

플러그인 작성에서 가장 중요한 건 plugin.json도 폴더 구조도 아니라, 그 안에 담길 하네스의 설계 품질이다.

플러그인은 하네스를 배포·증폭하는 그릇일 뿐, 설계를 대신 잘해주지 않는다. 에이전트 분리·스킬 경계·아키텍처 패턴·트리거 description이 허술하면 그 결함이 그대로 패키징되어 여러 사람·여러 세션·여러 프로젝트로 퍼진다. 잘못된 설계는 잘 배포될수록 더 큰 부채가 된다.

그래서 순서를 반드시 지킨다:

① 하네스를 제대로 설계하고(메타 스킬 활용) → 실제 작업으로 동작·검증한 뒤 → ② 비로소 플러그인으로 묶는다. 검증되지 않은 하네스를 먼저 패키징하지 않는다.

좋은 설계의 4축(패키징 전에 점검):

• 에이전트 분리 — "누가"가 명확한가? 역할이 겹치거나 한 에이전트가 너무 많은 일을 하지 않는가? (전문성·병렬성·컨텍스트·재사용성)
• 스킬 경계 — "어떻게"가 에이전트와 분리됐는가? 스킬은 절차·패턴만, 에이전트는 역할·협업만 담는가?
• 아키텍처 패턴 — 6가지 패턴(파이프라인/팬아웃·인/전문가 풀/생성-검증/감독자/계층 위임) 중 작업 성격에 맞는 것을 골랐는가?
• 트리거 설계 — description이 발동/비발동을 정확히 가르는가? 후속 표현까지 포함하는가?

설계 기준의 상세는 메타 스킬의 references/agent-design-patterns.md·skill-writing-guide.md를 따른다. 이 가이드(아래 §1~)는 "잘 설계된 하네스"를 전제로 그것을 어떻게 플러그인으로 포장·배포하는가만 다룬다.

---

1. 플러그인 해부 (디렉토리 구조)

이 저장소는 플러그인 마켓플레이스입니다. 루트가 마켓플레이스이자 기본 플러그인(harness)이고, plugins/ 아래에 도메인 플러그인이 들어갑니다.

harness/                              ← 마켓플레이스 저장소 루트
├── .claude-plugin/
│   ├── marketplace.json              ← 마켓플레이스 매니페스트(플러그인 목록)
│   └── plugin.json                   ← 루트 플러그인(harness) 매니페스트
├── skills/
│   └── harness/SKILL.md              ← 루트 플러그인이 제공하는 스킬
└── plugins/
    └── zio-harness/                  ← 도메인 플러그인 1개 = 폴더 1개
        ├── .claude-plugin/
        │   └── plugin.json           ← 이 플러그인의 매니페스트
        ├── skills/
        │   └── zio-harness/
        │       ├── SKILL.md          ← 오케스트레이터 스킬(필수)
        │       └── references/       ← 조건부 로딩 참조 문서
        │           ├── orchestrator.md
        │           ├── analyst.md
        │           ├── react.md
        │           └── ...
        ├── agents/                   ← (선택) 에이전트 정의 .md
        └── commands/                 ← (선택) 슬래시 커맨드

핵심 규칙: 플러그인 1개 = plugins/<name>/ 폴더 1개, 그 안에 .claude-plugin/plugin.json 1개. 나머지(skills/·agents/·commands/)는 표준 Claude Code 레이아웃을 그대로 따릅니다.

---

2. plugin.json — 플러그인 매니페스트

각 플러그인은 <plugin>/.claude-plugin/plugin.json을 가집니다. (루트 플러그인은 저장소 루트의 .claude-plugin/plugin.json.)

{
  "name": "zio-harness",
  "description": "React + Spring Boot + Mobile App 풀스택 개발 하네스. orchestrator·analyst·bot·agent 에이전트 팀이 기능 개발·테스트·배포를 파이프라인으로 처리.",
  "version": "1.0.1",
  "author": { "name": "ythong", "url": "https://git.zioinfo.co.kr/ythong" },
  "homepage": "https://git.zioinfo.co.kr/ythong/harness",
  "repository": "https://git.zioinfo.co.kr/ythong/harness",
  "license": "Apache-2.0",
  "keywords": ["harness", "zio-harness", "fullstack", "react", "spring-boot", "mobile", "claude-code-plugin", "multi-agent"]
}

필드	필수	설명
name	✅	플러그인 식별자(kebab-case). 설치 시 <name>@<marketplace>로 참조됨. 폴더명과 일치 권장.
description	✅	한 줄 요약. 무엇을·어떤 도메인·어떤 에이전트 구성인지 구체적으로. 마켓플레이스 목록에 노출.
version	✅	SemVer(MAJOR.MINOR.PATCH). 배포마다 올림(§7).
author	권장	{ name, url } (이메일은 마켓플레이스 owner에만).
homepage / repository	권장	문서·소스 위치.
license	권장	예: Apache-2.0.
keywords	권장	검색·분류용. harness·claude-code-plugin은 공통으로 포함.

---

3. marketplace.json — 마켓플레이스에 등록

새 플러그인을 만들면 루트 .claude-plugin/marketplace.json의 plugins[]에 항목을 추가해야 사용자가 설치할 수 있습니다.

{
  "name": "ythong-harness",
  "owner": { "name": "ythong", "email": "ythong86@gmail.com", "url": "https://git.zioinfo.co.kr/ythong" },
  "plugins": [
    { "name": "harness", "source": "./", "description": "에이전트 팀 & 스킬 아키텍트 메타 스킬.", "version": "1.3.1" },
    { "name": "zio-harness", "source": "./plugins/zio-harness", "description": "React+Spring+모바일 풀스택 하네스.", "version": "1.0.1" }
  ]
}

필드	설명
name	마켓플레이스 이름(claude plugin marketplace add 후 노출).
owner	{ name, email, url }.
plugins[].name	플러그인 plugin.json의 name과 정확히 일치.
plugins[].source	저장소 내 상대경로. 루트 플러그인은 "./", 서브플러그인은 "./plugins/<name>".
plugins[].description / version	plugin.json과 동기화(불일치 시 혼란).

⚠️ 버전 3중 동기화: plugins/<name>/.claude-plugin/plugin.json, marketplace.json의 해당 항목, (있다면) README 뱃지의 버전을 함께 올리세요.

---

4. 스킬 — 플러그인의 본체

하네스 플러그인의 핵심은 오케스트레이터 스킬 하나입니다. <plugin>/skills/<skill>/SKILL.md에 둡니다.

---
name: zio-harness
description: "React + Spring Boot + Mobile App 풀스택 개발 하네스. (1) 'zio 실행', '풀스택 개발 시작' 요청 시, (2) React/Spring/모바일 개발 요청 시, (3) '프로젝트 분석', 'PROJECT_MAP 업데이트' 시 … 반드시 이 스킬을 사용하라. 다시 실행·재실행·업데이트·보완 요청도 포함."
---

# zio-harness — Full-Stack Dev Orchestrator
…본문(워크플로우·에이전트 구성·데이터 흐름)…

작성 원칙(요약 — 상세는 메타 스킬의 skill-writing-guide 참조):

• description은 유일한 트리거다. "무엇을 한다 + 어떤 표현일 때 발동"을 적극적으로 나열하고, 후속 표현("다시/재실행/업데이트/보완")을 반드시 포함한다.
• SKILL.md 본문은 500줄 이내. 도메인별 세부(예: react.md, database.md)는 references/로 분리하고 본문엔 "언제 이 파일을 읽으라"는 포인터만 남긴다(단계적 정보 공개).
• 반복 실행 코드는 references/ 옆 scripts/에 번들링한다(로딩 없이 실행 가능).

에이전트·커맨드(선택):

• 에이전트 정의가 필요하면 <plugin>/agents/<name>.md에 둔다(역할·원칙·입출력·협업·model: opus).
• 슬래시 커맨드가 필요하면 <plugin>/commands/<name>.md. (하네스는 보통 스킬 트리거만으로 충분 — 커맨드는 선택.)

zio-harness는 에이전트 정의를 skills/zio-harness/references/(orchestrator·analyst·bot·agent·react·mobile·database·playwright)에 두고 오케스트레이터가 필요 시 로딩하는 방식을 씁니다. 어느 쪽이든 일관되게만 하세요.

---

5. 새 플러그인 만들기 — 단계별

5-1. 하네스 초안 생성 (메타 스킬 활용)

먼저 도메인 하네스를 설계합니다. 빈손으로 쓰지 말고 메타 스킬에 맡기세요:

claude "<도메인> 개발/검증/운영을 위한 하네스 구성해줘"

→ .claude/agents/, .claude/skills/에 에이전트·스킬 초안이 생깁니다. 이게 플러그인의 원재료입니다.

5-2. 플러그인 폴더로 패키징

mkdir -p plugins/<name>/.claude-plugin plugins/<name>/skills/<name>
# 초안 스킬을 옮기고
cp -r .claude/skills/<orchestrator>/* plugins/<name>/skills/<name>/
# (에이전트가 별도 .md면) plugins/<name>/agents/ 로

plugins/<name>/.claude-plugin/plugin.json을 §2 형식으로 작성합니다.

5-3. 마켓플레이스에 등록

루트 .claude-plugin/marketplace.json의 plugins[]에 항목 추가(§3).

5-4. 로컬 link 테스트 (배포 전 필수)

# 실험 플래그(에이전트 팀) 활성화
export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

# 마켓플레이스 게시 없이 로컬 체크아웃을 연결
claude plugin link ./plugins/<name>
claude plugin list | grep <name>          # 등록 확인

새 세션에서 트리거 문장을 입력해 스킬이 발동·동작하는지 확인합니다. 끝나면 claude plugin unlink <name>.

5-5. 배포

버전을 올리고(§7) 커밋·푸시하면, 마켓플레이스를 add한 사용자가 설치할 수 있습니다.

---

6. 설치·사용 (사용자 입장)

# 1) 마켓플레이스 추가 (저장소 지정)
claude plugin marketplace add ythong/harness        # 또는 git URL

# 2) 플러그인 설치
claude plugin install zio-harness@ythong-harness

# 3) 에이전트 팀 플래그 (하네스는 멀티에이전트 API에 의존)
export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

이후 트리거 문장(예: "풀스택 개발 시작")으로 발동합니다. 플래그가 필요한 이유는 experimental-dependency.md 참조.

---

7. 버전·네이밍 규칙

• 이름: kebab-case, 도메인을 드러내게(zio-harness, sec-audit-harness). 폴더명 = plugin.json name = marketplace 항목 name.
• 버전(SemVer):
  • PATCH — 문구·버그·레퍼런스 보강(동작 동일)
  • MINOR — 에이전트/스킬/레퍼런스 추가(하위호환)
  • MAJOR — 트리거·워크플로우·산출물 구조의 호환 깨짐
• 배포 시 plugin.json + marketplace.json + README 뱃지 버전을 함께 올린다.
• 변경은 CHANGELOG.md에 기록한다(작성자/사용자 모두 추적).

---

8. 작성자 체크리스트

• plugins/<name>/.claude-plugin/plugin.json — name·description·version·license·keywords
• marketplace.json의 plugins[]에 항목 추가, source 경로·name 일치
• 오케스트레이터 SKILL.md — description이 적극적 트리거 + 후속 표현 포함, 본문 500줄 이내
• 도메인 세부는 references/로 분리, 본문에 로딩 포인터
• 에이전트 정의 파일 존재(빌트인 타입이라도), model: opus
• commands/에 불필요한 커맨드 생성 안 함(스킬 트리거 우선)
• claude plugin link로 로컬 발동·동작 검증
• should-trigger / should-NOT-trigger 문장으로 트리거 확인(기존 플러그인과 충돌 없는지)
• 버전 3중 동기화 + CHANGELOG 기록

---

9. 참고

• 하네스 설계(에이전트·스킬 패턴): skills/harness/SKILL.md 및 그 references/
• 빠른 시작(사용자용): quickstart.md
• 실험 플래그 의존성: experimental-dependency.md
• 실제 예시 플러그인: plugins/zio-harness/ (오케스트레이터 스킬 + 도메인별 레퍼런스 구성)
• 기여 절차: ../CONTRIBUTING.md