범용 혼합 벤더 하네스 플러그인 for Claude Code.
run + uiux + resume 3개의 스킬을 harness: 플러그인 네임스페이스로 통합 제공한다. Claude Code 의 plugin:skill 콜론 문법으로 호출한다.
/harness:run Planner → Codex Plan Review → Generator → Build Gate → Codex Quick Review → Evaluator ∥ Codex Adversarial → R2 Refinement → Post-Refactor Verification
/harness:uiux UI primitive inventory → matrix → probe-gen → execute → gap → catalog feedback (6단계 PDCA, 100% 커버리지 게이트)
/harness:resume 체크포인트 기반 자동 재개 (구현 예정)
- Claude Code v2.x (plugin subsystem 지원)
- macOS / Linux bash
jq(checkpoint_writer.sh사용 시)- Codex CLI (
--codex-level=pro경로 사용 시, 선택)
claude --plugin-dir /path/to/claude-harness-plugin.claude/settings.json (또는 ~/.claude/settings.json) 에 추가:
{
"extraKnownMarketplaces": {
"harness-local": {
"source": {
"source": "git",
"url": "file:///path/to/claude-harness-plugin"
}
}
}
}설치:
/plugin install harness@harness-localclaude-harness-plugin/
├── .claude-plugin/
│ ├── plugin.json ← **플러그인 매니페스트 (버전 SSOT)**
│ └── marketplace.json ← 로컬 마켓플레이스 매니페스트
├── README.md ← 이 문서
├── LICENSE ← MIT
├── CHANGELOG.md ← 버전 이력
├── .gitignore
└── skills/
├── run/SKILL.md ← /harness:run
├── uiux/SKILL.md ← /harness:uiux
└── resume/SKILL.md ← /harness:resume
- v0.7.0 (2026-04-20): Starter templates —
templates/overrides-starter/5분 onboarding kit + README §커스터마이징 가이드 (P8) - v0.6.0 (2026-04-20): Multi-Session Hardening (HARNESS-MSC-001) — BL-ID 네임스페이스 격리, session registry, atomic-write, seed/restore 가드, per-session config (P7)
- v0.5.0 (2026-04-20):
.harness/config.yaml프로젝트 SSOT 도입 — L0 config loader + 3단 cascade + SKILL env 치환 (P1 v2) - v0.4.4 (2026-04-20): commands/ flatten + 슬래시 커맨드 중복 해소
- v0.4.3 (2026-04-20):
/harness:*슬래시 커맨드 노출 복구 (BL-307) - v0.4.1 (2026-04-20): hook 등록 공식 스펙 재배선 (hotfix)
- v0.4.0 (2026-04-20): L2 Agent Replace + L3 호환성 게이트 — SessionStart hook, link-farm, semver check
- v0.3.0 (2026-04-20): L1 변수 주입 레이어 — userConfig 4키 + SKILL.md 치환점
- v0.2.0 (2026-04-20):
.harness/경로 통일 (BL-305) + plugin.json SSOT 확정 + marketplace.json 번들링 - v0.1.0 (2026-04-19): 초기 스켈레톤 + 기존 2개 스킬 이전 +
resumestub
.claude-plugin/plugin.json의version필드가 유일한 SSOT 이다 (Claude Code plugin spec 가 이 값을 읽는다).claude-plugin/marketplace.json의metadata.version과plugins[0].version은plugin.json값을 따라 수동 동기화한다- 버전 bump 시 세 필드를 반드시 함께 갱신한다
shared/는 플러그인에 의존하지 않는 자족형 벤더 중립 스킬이다 (Claude·Codex·OpenCode·Pi 어디서나 단독 사용 가능; SessionStart hook/${CLAUDE_PLUGIN_ROOT}비의존).- 따라서
shared/VERSION은 플러그인 버전(plugin.json SSOT)과 별개의 독립 트랙으로 관리한다. 두 값이 달라도(예: 플러그인0.7.2↔ shared 스킬0.8.0) 의도된 정상 상태다. - 플러그인 SSOT 3필드(위)와
shared/VERSION을 강제로 일치시키지 않는다 — 공용 스킬은 플러그인 릴리즈 주기와 독립적으로 진화한다. - 단, 플러그인이 번들한
shared/자산을 의미 있게 변경하는 릴리즈에서는 plugin.json SSOT 도 함께 bump 하는 것을 권장한다.
상세 플랜: docs/PLAN-v1.0.md — 3-레이어 아키텍처 (userConfig 주입 · Agent Replace · 호환성 게이트) + v0.3~v1.0 릴리즈 로드맵 + 7 리스크 + 6 품질 게이트
| 버전 | 내용 |
|---|---|
| v0.1.x (완료) | 스켈레톤, run/uiux 이전, resume stub |
| v0.2.x (완료) | .harness/ 경로 통일, plugin.json SSOT 확정, marketplace 번들링 |
| v0.3.x (완료) | L1 변수 주입 레이어 — userConfig 4키 + SKILL.md 치환점 |
| v0.4.x (완료) | L2 Agent Replace + L3 호환성 게이트 — SessionStart hook + link-farm + semver check + commands/ 슬래시 커맨드 |
| v0.5.x (완료) | P1 v2 — .harness/config.yaml 프로젝트 SSOT + L0 config loader + 3단 cascade |
| v0.6.x (완료) | P7 Multi-Session Hardening — BL-ID namespace + session registry + atomic-write + seed guard + per-session config |
| v0.7.x (완료) | P8 Starter templates + §커스터마이징 가이드 |
| v0.8.x | Evaluation criteria override 전용 파이프라인 + /harness:resume 본체 구현 |
| v0.9.x | Cross-project migration tool + Telemetry opt-in (선택) |
| v1.0.x | API stable lock-in, Anthropic 공식 마켓플레이스 등록 검토 |
# 1. 플러그인 설치
/plugin marketplace add taemire/claude-harness-plugin
/plugin install harness
# 2. 프로젝트 루트에서 starter 복사
cp -r ${CLAUDE_PLUGIN_ROOT}/templates/overrides-starter .harness/overrides
cp ${CLAUDE_PLUGIN_ROOT}/templates/config.yaml.example .harness/config.yaml
# 3. .example 제거
cd .harness/overrides
mv override-manifest.json.example override-manifest.json
mv eval_criteria.md.example eval_criteria.md
mv agents/planner.md.example agents/planner.md
cd ../..
# 4. 프로젝트 값 입력 (config.yaml 의 project_name, bl_prefix 수정)
$EDITOR .harness/config.yaml
# 5. 첫 실행
/harness:run "BL-001 첫 기능"┌─────────────────────────────────────────────────────────────┐
│ L0. Config Loader (.harness/config.yaml → HARNESS_* env) │
│ project_name · bl_prefix · eval_criteria_path · mode │
└─────────────────────────────────────────────────────────────┘
↓ SessionStart hook 이 export
┌─────────────────────────────────────────────────────────────┐
│ L2. Agent Replace (.harness/overrides/agents/ → link-farm)│
│ planner.md · evaluator.md 등 프로젝트 도메인 override │
└─────────────────────────────────────────────────────────────┘
↓ Claude Code subagent priority (project > plugin)
┌─────────────────────────────────────────────────────────────┐
│ L3. Semver Gate (override-manifest.json 호환성 검사) │
│ compatible_base_version ~0.6 → 불일치 시 경고 │
└─────────────────────────────────────────────────────────────┘
Q. .harness/overrides/ 를 git 에 커밋해야 하나요?
→ 예. 팀 공유 자산입니다. .claude/agents/ (symlink) 만 gitignore 합니다.
Q. 플러그인 버전이 bump 되면 내 override 가 깨지나요? → 아니요. L3 호환성 게이트가 경고만 출력하고 파이프라인은 계속 실행됩니다 (fail-open). 마이그레이션 가이드가 있으면 경고에 경로가 표시됩니다.
Q. 멀티 프로파일 / 멀티세션 환경에서 안전한가요?
→ v0.6+ 부터 .harness/active-sessions.json + SessionStart preflight + archive-restore drift 감지를 내장합니다 (PHASE-P7 참조).
Q. UI 커버리지/SPA 상태 보존 같은 프로젝트별 규약을 에이전트에 주입하려면?
→ templates/overrides-starter/agents/planner.md.example 의 [여기에 프로젝트 제약을 작성] 섹션을 프로젝트 규약으로 채웁니다. Portal Hub 의 실사례는 docs/PHASE-P7-multi-session-hardening.md §1.1 참조.
- templates/overrides-starter/README.md — 단계별 세부 가이드
- docs/PLAN-v1.0.md — 장기 아키텍처 로드맵
- docs/PHASE-P7-multi-session-hardening.md — 멀티세션 방어 설계
- 호출 시 작업 디렉토리 (
${CLAUDE_PROJECT_DIR}) 를 프로젝트 루트로 간주한다. 하네스 산출물은.harness/(체크포인트) 및.harness/<type>/(SPEC/SELF_CHECK/QA_REPORT/output) 아래에 기록된다. - 체크포인트 엔진 의존 스크립트는
.harness/common/에 위치해야 하며, 프로젝트 측에서 자체 준비한다 (checkpoint_reader.sh,checkpoint_writer.sh,error_detector.sh,extract_bl_id.sh).
MIT — 자세한 내용은 LICENSE 참조.