harness/docs/plugin-guide.md

# 하네스 플러그인 가이드

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

[English](plugin-guide.en.md)(예정) · **한국어**

---

## 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`.)

```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[]`에 항목을 추가해야 사용자가 설치할 수 있습니다.

```json
{
  "name": "ythong",
  "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`에 둡니다.

```markdown
---
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. 하네스 초안 생성 (메타 스킬 활용)
먼저 도메인 하네스를 설계합니다. 빈손으로 쓰지 말고 메타 스킬에 맡기세요:
```bash
claude "<도메인> 개발/검증/운영을 위한 하네스 구성해줘"
```
→ `.claude/agents/`, `.claude/skills/`에 에이전트·스킬 초안이 생깁니다. 이게 플러그인의 원재료입니다.

### 5-2. 플러그인 폴더로 패키징
```bash
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 테스트 (배포 전 필수)
```bash
# 실험 플래그(에이전트 팀) 활성화
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. 설치·사용 (사용자 입장)

```bash
# 1) 마켓플레이스 추가 — git 저장소 URL은 반드시 .git 으로 끝나야 한다
claude plugin marketplace add https://git.zioinfo.co.kr/ythong/harness.git

# 2) 플러그인 설치
claude plugin install zio-harness@ythong    # 또는 harness / proposal-builder

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

> ⚠️ **`.git` 누락 주의.** 비-GitHub git 저장소(gitea 등)를 `.git` 없이 추가하면 Claude가 git clone 대신 단일 파일 URL로 해석해 저장소 **웹페이지(HTML)**를 가져오고, `Invalid marketplace schema from URL: ... expected object, received string` 오류가 난다. GitHub은 `owner/repo` 단축형도 되지만, 그 외 git 호스트는 **전체 `https://…/repo.git` URL**을 쓴다.

이후 트리거 문장(예: "풀스택 개발 시작")으로 발동합니다. 플래그가 필요한 이유는 [`experimental-dependency.md`](./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`](./quickstart.md)
- 실험 플래그 의존성: [`experimental-dependency.md`](./experimental-dependency.md)
- 실제 예시 플러그인: `plugins/zio-harness/` (오케스트레이터 스킬 + 도메인별 레퍼런스 구성)
- 기여 절차: [`../CONTRIBUTING.md`](../CONTRIBUTING.md)