# 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/`에 추가
- 워크플로우 가이드를 실사용 경험을 바탕으로 업데이트
