본문으로 건너뛰기

Claude Code — 스킬과 플러그인을 중앙 관리하는 구조 설계

in9yu97

2026.03.22

# Claude Code 하네스 레포 만들기 — 스킬과 플러그인을 중앙 관리하는 구조 설계

> Claude Code를 여러 프로젝트에서 쓰면서, 스킬과 에이전트 설정을 프로젝트마다 반복하는 게 비효율적이라고 느꼈다. "한 곳에서 관리하고, 모든 프로젝트가 공유하면 안 될까?" 그 질문에서 시작된 하네스 레포 구축기.

---

## 문제 인식: 왜 하네스가 필요했나

Claude Code는 `.claude/` 디렉토리에서 스킬과 설정을 읽는다. 프로젝트마다 `.claude/skills/`를 만들고, 같은 스킬을 복사하고, 설정을 맞추는 작업을 반복하고 있었다.

그런데 Claude Code에는 하나의 특성이 있다 — **현재 디렉토리에서 루트까지 상위로 `.claude/`를 탐색한다.** 즉, 상위 디렉토리에 `.claude/`가 있으면 하위 프로젝트 전부가 그 설정을 공유한다.

이걸 이용하면:
```
in9yu-harness/           ← 여기에 .claude/ 를 두면
├── .claude/skills/      ← 모든 스킬을 한 곳에서 관리
├── projects/
│   ├── repo-a/          ← 이 프로젝트에서 Claude Code를 실행해도
│   └── repo-b/          ← 상위의 .claude/skills/ 를 자동으로 발견
```

별도 설정 없이 스킬과 에이전트를 공유할 수 있다. 이게 하네스 레포의 기본 아이디어다.

---

## Step 1: 초기 구조 잡기

가장 먼저 한 일은 디렉토리 구조를 잡는 것이었다.

```
in9yu-harness/
├── .claude/
│   ├── CLAUDE.md         # 프로젝트 지침
│   ├── settings.json     # Claude Code 설정
│   ├── skills/           # 공유 스킬
│   └── agents/           # 공유 에이전트
├── docs/                 # 문서
├── projects/             # 외부 레포 클론 위치 (.gitignore)
└── README.md
```

`projects/`는 `.gitignore`로 추적에서 제외했다. 실제 작업 레포들이 여기 클론되지만, 하네스 레포가 관리할 영역은 아니기 때문이다.

oh-my-claudecode(OMC) 플러그인을 설치하고 `/omc-setup`으로 CLAUDE.md를 구성했다. 이 파일이 Claude Code의 행동을 정의하는 핵심이다 — 어떤 에이전트를 쓸지, 어떤 워크플로우를 따를지, 검증은 어떻게 할지.

---

## Step 2: 첫 번째 스킬 추가 — autoresearch

하네스에 처음 추가한 스킬은 `autoresearch`다. Andrej Karpathy의 autoresearch 방법론을 Claude Code 스킬에 적용한 것으로, 기존 스킬의 프롬프트를 자동으로 최적화한다.

동작 원리는 단순하다:
1. 스킬을 여러 번 실행하고 binary eval(합/불)로 채점
2. 프롬프트를 한 가지만 변이
3. 점수가 오르면 유지, 아니면 폐기
4. 반복

스킬을 `.claude/skills/autoresearch/`에 넣고 README에 문서화한 뒤 첫 커밋을 만들었다.

이 시점에서 "스킬을 추가했는데 README에도 반영해야 한다"는 걸 깨달았다. 스킬이 늘어날수록 문서화를 병행하지 않으면 나중에 뭐가 있는지 파악하기 어려워진다.

---

## Step 3: 기획 스킬을 찾아서 — gstack 검토와 포기

다음으로 원한 건 **기획 관련 스킬**이었다. 아이디어 검증, 전략 수립, 디자인 리뷰 같은 것들.

Garry Tan(YC CEO)이 만든 [gstack](https://github.com/garrytan/gstack)이 눈에 들어왔다. 23개 스킬로 개발 전 과정을 커버하는 "소프트웨어 팩토리"를 표방하는 프로젝트다. GitHub 스타 35K+.

기획 카테고리만 봐도 매력적이었다:
- `/office-hours` — YC 파트너 역할로 아이디어 검증
- `/plan-ceo-review` — 창업자 관점 전략 리뷰 (11개 섹션, 4가지 모드)
- `/plan-eng-review` — 엔지니어링 매니저 관점 아키텍처 리뷰
- `/plan-design-review` — 시니어 디자이너 관점 플랜 리뷰
- `/design-consultation` — 디자인 시스템 처음부터 생성

**"기획 스킬만 선별해서 가져오자"**고 생각했다. 전체를 설치하면 OMC와 충돌할 가능성이 있었기 때문이다:
- gstack의 `/browse`(자체 Chromium 데몬)와 OMC의 MCP 브라우저 도구가 충돌
- 슬래시 커맨드 네이밍 겹침
- 단일 에이전트(gstack) vs 멀티 에이전트(OMC) 라우팅 차이

### 시행착오: 선별 도입의 벽

의존성을 분석해보니, **선별 도입이 사실상 불가능**했다.

| 스킬 | 단독 사용 | 이유 |
|------|-----------|------|
| `/design-consultation` | 가능 | 가장 독립적 |
| `/plan-design-review` | 부분 가능 | |
| `/office-hours` | 부분 가능 | 바이너리/텔레메트리 스텁 필요 |
| `/plan-ceo-review` | **불가** | office-hours 산출물 필수 |
| `/plan-eng-review` | **불가** | office-hours 산출물 + /qa 연동 필수 |

모든 기획 스킬이 gstack 인프라에 의존하고 있었다:
- `~/.gstack/` 디렉토리 (세션, 프로젝트 문서, 텔레메트리)
- gstack 전용 바이너리 (`gstack-update-check`, `gstack-config`, `remote-slug` 등)
- `{{PREAMBLE}}` 공유 템플릿 시스템
- 스킬 간 산출물 체이닝 (`/office-hours` → `/plan-ceo-review` → `/plan-eng-review`)

기획 스킬들이 하나의 파이프라인으로 엮여 있어서, 중간 하나만 떼어내면 앞뒤 맥락이 끊긴다. 전체를 설치하자니 OMC와 충돌하고, 선별하자니 의존성이 걸리고 — 전형적인 **올인 아니면 포기** 상황이었다.

**교훈: 외부 도구를 도입할 때는 기능 목록보다 의존성 구조를 먼저 봐야 한다.** 스킬이 아무리 좋아도 인프라에 종속되어 있으면 선별 도입이 불가능하다.

---

## Step 4: pm-skills 발견 — 완벽한 대안

gstack을 포기하고 대안을 찾던 중 [pm-skills](https://github.com/phuryn/pm-skills)를 발견했다. Paweł Huryn이 만든 PM 도메인 지식 플러그인 마켓플레이스.

분석해보니 gstack과는 완전히 다른 철학이었다:

| | pm-skills | gstack |
|---|-----------|--------|
| **의존성** | 없음 (순수 마크다운) | 바이너리, ~/.gstack/, 텔레메트리 |
| **독립성** | 스킬 개별 사용 가능 | 스킬 간 체이닝 의존 |
| **OMC 충돌** | 없음 (레이어가 다름) | 브라우저/에이전트 라우팅 충돌 |
| **설치** | `claude plugin install` | setup 스크립트 + Bun + Playwright |

pm-skills는 **도메인 지식**(마크다운)이고, OMC는 **오케스트레이션 레이어**다. 레이어가 다르니 충돌할 이유가 없다. pm-skills로 "무엇을" 할지 정의하고, OMC로 "어떻게" 실행하는 조합이 자연스럽게 성립한다.

65개 스킬, 36개 커맨드, 8개 플러그인 — 기획부터 전략, 실행, 리서치, 분석, GTM, 마케팅까지. gstack의 기획 스킬을 대체하고도 남을 정도로 PM 프레임워크가 풍부했다.

**교훈: "기능이 풍부한 올인원"보다 "한 가지를 잘하는 조합형"이 유연하다.** 특히 이미 다른 도구(OMC)를 쓰고 있다면, 독립적으로 작동하는 도구가 훨씬 도입하기 쉽다.

---

## Step 5: 플러그인 설치와 재현성 문제

pm-skills 8개 플러그인을 하나씩 설치했다:

```bash
claude plugin marketplace add phuryn/pm-skills
claude plugin install pm-product-discovery@pm-skills
claude plugin install pm-product-strategy@pm-skills
# ... 8개 반복
```

설치가 끝나고 README에 문서화하는데, 한 가지 문제가 떠올랐다.

**"다른 환경에서 이 레포를 클론하면 플러그인을 못 쓰잖아?"**

하네스의 핵심 가치는 "클론하면 바로 사용 가능"인데, `.claude/skills/`에 직접 넣은 autoresearch와 달리 플러그인은 `claude plugin install`로 사용자 환경에 설치되는 거였다. 레포에 포함되지 않는다.

### 해결: 셋업 스크립트

`bin/setup.sh`를 만들어서 해결했다:

```bash
#!/usr/bin/env bash
set -euo pipefail

# Claude Code 설치 확인
if ! command -v claude &>/dev/null; then
  echo "ERROR: Claude Code가 설치되어 있지 않습니다."
  exit 1
fi

# 마켓플레이스 등록
claude plugin marketplace add Yeachan-Heo/oh-my-claudecode
claude plugin marketplace add phuryn/pm-skills

# OMC 설치
claude plugin install oh-my-claudecode

# pm-skills 8개 플러그인 설치
for plugin in pm-product-discovery pm-product-strategy ...; do
  claude plugin install "${plugin}@pm-skills"
done
```

처음에는 OMC를 "감지만" 하고 넘어갔다가, OMC도 결국 플러그인이니 설치까지 자동화해야 한다는 걸 깨달았다. OMC의 설치 방법도 확인해서 (`claude plugin marketplace add Yeachan-Heo/oh-my-claudecode`) 스크립트에 통합했다.

**교훈: "셋업을 한 번 해놨으니 됐다"는 착각이다. 재현 가능한 셋업이어야 진짜 셋업이다.** 새 환경, 새 팀원, 새 기기 — 언제든 동일한 환경을 만들 수 있어야 한다.

---

## Step 6: 활용 가이드 문서화

플러그인을 설치하는 것과 잘 쓰는 것은 다른 문제다. 두 가지 문서를 만들었다:

### plugin-guide.md — 각 플러그인을 어떻게 쓰는가

OMC의 19개 에이전트 각각의 역할과 활용 시나리오, pm-skills의 36개 커맨드별 입력/산출물/활용 시점, autoresearch의 사용법과 핵심 원칙을 정리했다.

### workflow-guide.md — 어떻게 조합해서 쓰는가

10가지 실전 케이스를 구체적인 명령어 순서와 함께 정리했다:

1. **풀사이클** — 아이디어 → 검증 → 전략 → 구현 → 출시
2. **경쟁사 대응** — 분석 → 배틀카드 → 전략 → 빠른 구현
3. **피드백 기반 개선** — 분석 → 우선순위 → PRD → 구현
4. **A/B 테스트** — 가설 → 지표 → 구현 → 결과 분석
5. **분기 계획** — 전략 → OKR → 로드맵 → 스프린트
6. **새 시장 진입** — 시장 분석 → 비즈니스 모델 → GTM
7. **스프린트 루틴** — 계획 → 구현 → 회고 → 릴리즈 노트
8. **스킬 최적화** — autoresearch 자율 실험
9. **IR/보드 준비** — 전략 + 시장 분석 + 성장 계획
10. **디버깅** — 단순/복잡/보안 케이스별 에이전트 조합

핵심 원칙을 다섯 가지로 정리했다:
- **pm-skills로 "무엇을"** 정의하고, **OMC로 "어떻게"** 실행
- pm-skills는 순서대로 체이닝하면 산출물이 자연스럽게 연결
- OMC 워크플로우는 상황에 맞게 선택 (단일 → executor, 병렬 → ultrawork, 반복 → ralph)
- autoresearch는 메타 레벨 — 다른 스킬의 품질을 올리는 데 사용
- 리서치와 실행을 분리

---

## 최종 결과물

4개의 커밋으로 하네스 레포가 완성되었다:

```
48d6d6a INIT :: 초기 셋팅
881f221 ADD :: autoresearch 스킬 추가 및 README 문서화
1521624 ADD :: 환경 셋업 스크립트 및 플러그인 문서화
2638c2f ADD :: 플러그인 활용 가이드 및 워크플로우 가이드 문서 추가
```

최종 구조:
```
in9yu-harness/
├── .claude/
│   ├── CLAUDE.md              # OMC 오케스트레이션 설정
│   ├── settings.json
│   └── skills/
│       └── autoresearch/      # 스킬 자동 최적화
├── bin/
│   └── setup.sh               # 원클릭 환경 셋업
├── docs/
│   ├── plugin-guide.md        # 플러그인별 활용법
│   └── workflow-guide.md      # 10가지 조합 워크플로우
├── projects/                  # 실제 작업 레포들 (gitignore)
└── README.md
```

새 환경에서의 셋업:
```bash
git clone [repo] && cd in9yu-harness
./bin/setup.sh          # OMC + pm-skills 자동 설치
# Claude Code 실행 후
/omc-setup              # OMC 구성
```

---

## 배운 것들

### 1. 도구 선택은 의존성 분석이 먼저

gstack은 기능적으로 훌륭했지만, 모든 스킬이 gstack 인프라에 종속되어 있었다. 기능 데모에 현혹되지 말고, "이걸 우리 환경에 넣었을 때 뭐가 필요한가?"를 먼저 물어야 한다.

### 2. 레이어가 다르면 충돌하지 않는다

OMC(오케스트레이션)와 pm-skills(도메인 지식)는 레이어가 달라서 완벽하게 공존한다. 같은 레이어에서 경쟁하는 도구(OMC vs gstack)는 반드시 충돌한다. 도구를 조합할 때는 "같은 레이어인가, 다른 레이어인가"를 판단하는 게 핵심이다.

### 3. 재현 가능해야 진짜 셋업이다

"내 환경에서 돌아간다"는 셋업이 아니다. 스크립트 한 줄로 동일한 환경을 만들 수 있어야 한다. 플러그인처럼 레포에 포함되지 않는 의존성은 반드시 자동화된 설치 경로가 있어야 한다.

### 4. 문서화는 설치 가이드가 아니라 활용 가이드

README에 "이 커맨드를 실행하세요"만 적는 건 반쪽짜리다. 실제로 가치를 만드는 건 "이 상황에서 이 도구들을 이 순서로 조합하면 된다"는 워크플로우 가이드다. 도구를 알려주는 것보다 도구의 **조합법**을 알려주는 게 더 중요하다.

### 5. Claude Code의 디렉토리 탐색 특성을 활용하라

Claude Code가 상위로 `.claude/`를 탐색한다는 특성 하나로, 멀티 프로젝트 환경에서 스킬과 설정을 중앙 관리하는 구조를 만들 수 있었다. 프레임워크의 기본 동작을 이해하면, 별도의 도구 없이도 강력한 구조를 설계할 수 있다.

---

## 다음 단계

- `projects/`에 실제 프로젝트를 클론하고 워크플로우를 실전에 적용
- autoresearch로 기존 스킬들의 품질을 체계적으로 개선
- 프로젝트별로 필요한 커스텀 스킬을 `.claude/skills/`에 추가
- 워크플로우 가이드를 실사용 경험을 바탕으로 업데이트
1

함께 이야기해요 1

로그인하고 댓글을 남겨 주세요

댕댕이멍멍 프로필 이미지
댕댕이멍멍2026.03.25

오! 저도 고민하고 있는 부분인데 사례 발표 빨리 들어 보고 싶은 주제네요.

필요한 AI 정보만
메일함에 쏙쏙 넣어드려요.

지금 핫한 AI 소식부터 직접 해 본 사례까지, 월요일마다 무료로 받아보세요

이런 사례도 있어요

사례 전체 보기