Claude Code 용 Pure SKILL.md 기반 개발 워크플로 도구 모음. 외부 의존성 없이 Claude Code 안에서 기획·구현·검증·진단·문서화의 각 단계를 체계적으로 강제하는 11개 스킬을 제공한다.
v2.0 부터 Python orchestrator 를 완전히 제거하고 순수 SKILL.md 기반으로 동작합니다.
pip install도,harness init도 필요 없습니다.
- Zero-dependency: Python / pip / 외부 도구 0개. Claude Code 의 Read / Write / Bash / Glob 도구만으로 동작
- 11개 스킬 통합 제공: 단순 코딩부터 spec 작성, 코드 리뷰, 마이그레이션, 디버깅, 테스트 생성, 문서화까지 한 플러그인
- 사용자 확인 게이트: 비가역 작업 / 큰 변경 직전 HARD-GATE 로 의도치 않은 토큰 소비 차단
- Auto-detect: 빌드 파일과 확장자로부터 lang / test / build 명령 자동 감지 (Java / Python / TS / Go / Rust / C# 지원)
- State 머신 + Session Recovery:
.harness/state.json으로 작업 중단 시 정확한 지점에서 재개 - plugin-agnostic: 특정 superpowers 스킬에 의존하지 않음. 가용 스킬을 capability keyword 로 찾아 활용, 없어도 단독 동작
본 프로젝트는 비공개로 운영합니다. 공식 마켓플레이스에 노출되지 않으며, 직접 마켓플레이스를 등록한 사람만 설치할 수 있습니다.
# 1. 본 레포를 자신의 Claude Code 마켓플레이스로 등록
claude plugin marketplace add jooooonj/develop-agent
# 2. 플러그인 설치
claude plugin install develop-agent@develop-agent-marketplace설치 후 별도 셋업 없이 바로 사용 가능합니다.
| 스킬 | 명령 | 사용 시점 |
|---|---|---|
| Harness | /harness <task> |
새 기능 / 버그 수정 — 3-Phase (Planner → Generator → Evaluator) |
| Refactor | /refactor <target> |
동작 보존 코드 구조 개선 — single/multi/comprehensive 모드 |
| Migrate | /migrate <target> [--from .. --to ..] |
외부 의존성 변경 (버전업/교체) — single/multi 모드, WebSearch 기반 분석 |
| Debug | /debug <error> |
가설 기반 디버깅 — quick/deep 모드, 매 가설은 실제 행동으로 검증 (추론만으로 결론 금지) |
| Memory | /memory <save|show|search|clean> |
팀 공유 지식 베이스 — git-committed docs/harness/memory/ 에 결정/버그/패턴/컨벤션 저장 |
| Codebase Audit | /codebase-audit [--mode quick|deep|thorough] |
프로젝트 구조/의존성/패턴 체계적 분석 — 온보딩 문서 자동 생성 (3-tier, incremental 지원) |
| Code Review | /code-review <target> |
PR / 브랜치 / 커밋 / 파일 변경에 대한 편향 없는 코드 리뷰 — 3-tier 모드, 심각도 분류, large diff 분할 |
| MD Optimize | /md-optimize |
CLAUDE.md + .md 파일을 Dual-Zone 모델로 토큰 효율 최적화 — idempotency 마커 + gitignore 인식 |
| MD Generate | /md-generate |
코드베이스 분석 후 CLAUDE.md 자동 생성/보강 — content_lang 선택 (en/user/hybrid) |
| Test Gen | /test-gen <target> |
자동 테스트 생성 + 뮤테이션 기반 품질 검증 — coverage-gap / regression 모드 지원, production 코드 절대 미수정 |
| Spec | /spec <task> |
다회차 Q&A 로 모호함 해소 → /harness 가 받을 수 있는 spec.md 생성. deep 모드: 4 analyst + critic + re-synthesis 1회 한정 |
| 분류 | 스킬 | 핵심 |
|---|---|---|
| 구현 / 작업 실행 | /harness, /refactor, /migrate |
코드 변경을 단계적으로 강제 |
| 진단 / 분석 | /debug, /codebase-audit, /code-review |
변경하지 않고 발견 |
| 테스트 / 안전망 | /test-gen |
테스트만 작성 (production 미변경) |
| 문서 / 컨텍스트 관리 | /md-optimize, /md-generate, /memory |
.md 자동화 + 팀 지식 공유 |
| 요구사항 명세 | /spec |
모호한 아이디어 → 명확한 spec |
모호한 요청
↓
/spec (Q&A + critic) → docs/harness/<slug>/spec.md
↓
/harness (3-Phase) → 코드 변경
↓
(필요 시)
/debug → 버그 진단 → /test-gen --regression → 회귀 안전망
/refactor → 동작 보존 정리
/migrate → 외부 의존성 업그레이드
↓
/code-review → PR 머지 전 편향 없는 리뷰
처음 보는 프로젝트:
/codebase-audit → docs/harness/audit/*
↓
/md-generate → CLAUDE.md
↓ (시간 경과)
/md-optimize → CLAUDE.md 압축
팀 지식:
모든 단계에서 가치 있는 발견 → /memory save → docs/harness/memory/
Claude Code 세션에서 /harness 슬래시 명령으로 호출:
/harness 사용자 인증 추가
Claude 가 자동으로 수행:
- Setup: 현재 레포에서 lang/test/build 자동 감지 →
.harness/디렉토리 생성 →harness/<slug>브랜치 checkout - Phase 1 (Planner): 코드베이스 탐색 후
docs/harness/<slug>/spec.md작성. 사용자 확인 게이트 — spec 을 보여주고 승인 받기 전에는 Generator 로 진행 안 함 - Phase 2 (Generator): spec 에 따라 코드 구현,
changes.md에 변경 내역 기록 - Phase 3 (Evaluator): 테스트 실행 + 5-criterion 코드 리뷰 →
qa_report.md에 PASS/FAIL verdict - 판정: PASS → 종료 / FAIL + 남은 round → Generator 재시도 (피드백 주입) / max round 도달 → 강제 종료
/harness "..." → Setup (auto-detect + .harness/state.json + git branch)
↓
[Phase 1: Planner]
Claude: docs/harness/<slug>/spec.md 작성
↓ (사용자 확인 게이트)
[Phase 2: Generator]
Claude: 코드 구현 + changes.md
↓
[Phase 3: Evaluator]
Claude: 빌드/테스트 실행 + 5-criterion 리뷰 + qa_report.md
↓
Verdict?
├── PASS → 종료
├── FAIL + round < max → Phase 2 재진입 (round++)
└── FAIL + round == max → 강제 종료
/refactor UserService 클래스의 책임 분리 --scope src/user/** --mode multi
single— 작은 변경 (메서드 추출, 변수명 정리)multi— 모듈 단위 재구성comprehensive— 아키텍처 수준
Iron Law: 동작이 바뀌면 즉시 중단. atomic 단위 변경 + 매 단계 테스트 + stop-on-failure.
/migrate react --from 17 --to 18 # 명시적 버전
/migrate react --from 17 # --to 는 WebSearch 로 최신 stable 감지
/migrate react # from/to 모두 자동 감지
/migrate replace moment with dayjs # 라이브러리 교체
- WebSearch 로 공식 마이그레이션 가이드 자동 수집 → breaking change 추출
- 우리 코드의 영향 파일을 매핑
- 단계 분할 plan 작성 → 사용자 승인 → 단계별 실행
- 매 단계 테스트, 실패 시 즉시 중단
/debug "NPE at login.ts:45" --mode deep --reproduce-cmd "npm test -- login"
quick— 명확한 에러, 단일 orchestrator 가 가설 생성/검증/fix 모두deep— 미스터리 버그, 2개 specialist sub-agent + cross_verification
Iron Law: 매 가설은 반증 가능 형식 + 실제 행동(grep/test/git log) 으로 검증. 추론만으로 결론 금지.
산출: hypotheses.md / root_cause.md / fix_changes.md / debug_report.md
/memory save # 현재 세션에서 팀 가치 있는 항목 추출 → HARD-GATE → 저장
/memory show # 카테고리별 목록
/memory search jwt # 키워드 grep
/memory clean # stale / duplicate / superseded 정리 (사용자 승인 후)
Claude Code 내장 auto-memory 와의 차이: 본 스킬은 팀 공유 (git-committed), 내장 memory 는 개인용 (사용자 머신에만).
저장 위치: docs/harness/memory/{decisions,bugs,patterns,todos,conventions,<custom>}/
/codebase-audit # 자동 모드 선택 (파일 수 기반)
/codebase-audit --mode deep # 핵심 모듈 + 의존성 + 패턴 분석
/codebase-audit --mode thorough --scope src/api/** # 감사 수준
/codebase-audit --incremental # 이전 audit 산출 기반 갱신
산출: docs/harness/audit/{overview,structure,dependencies,patterns,findings}.md
/code-review #123 # PR 번호
/code-review feature/auth # 브랜치 (vs main)
/code-review abc..def # 커밋 범위
/code-review src/login.ts # 단일 파일
/code-review --staged # 스테이지된 변경
/code-review # unstaged 변경
--mode quick|deep|thorough 로 깊이 조절. 산출: docs/harness/<slug>/review_report.md (심각도별 그룹화)
/spec "사용자 인증 추가" # quick 모드 자동 선택 (단순 task)
/spec "결제 시스템 설계" --mode deep # 4 analyst + critic 활용
/spec "..." --reference docs/conventions.md # 컨벤션 파일 명시 (has_git=false 환경)
워크플로: Setup → Convention Scan → Q&A (최대 3 round) → Spec Generation (deep 시 4 analyst → synthesis → critic → re-synthesis 1회 한정) → HARD-GATE Approve → /harness handoff.
산출: docs/harness/<slug>/{spec.md, qa_notes.md, conventions.md, critic_findings.md} — /harness 가 자동 재사용.
/test-gen src/userService.ts # target 전체 분석 후 테스트 생성
/test-gen src/ --coverage-gap # 커버리지 낮은 영역만 보강
/test-gen --regression docs/harness/<slug>/debug_report.md # /debug 산출 기반 회귀 테스트
뮤테이션 테스팅으로 작성된 테스트가 실제로 동작 변화를 잡는지 자동 검증. mutation score ≥ 70% 임계값. production 코드는 절대 수정하지 않음 (테스트만).
/debug → /test-gen --regression 연계: 디버깅 후 root cause 가 재발해도 즉시 catch 되도록 회귀 안전망 자동 구축.
/md-optimize
이미 있는 CLAUDE.md + .md 들을 Dual-Zone (Inline / Index) 으로 재구조화. <!-- managed by md-optimize --> 마커로 재실행 idempotency 보장. gitignored 파일은 자동 제외.
산출: 압축된 .md 들 + docs/harness/<slug>/md-optimize-report.md (토큰 절감량 / 변환 요약)
/md-generate
CLAUDE.md 가 없거나 빈약한 프로젝트에서 코드베이스를 분석해 초안 자동 생성. content_lang 선택지 (en / user / hybrid). 이미 충실한 CLAUDE.md 가 있으면 /md-optimize 로 전환 권고.
<repo>/
├── .harness/
│ └── state.json # 작업 중 임시 상태 (작업 완료 후 정리 검토)
└── docs/harness/<task-slug>/
├── spec.md # Planner 산출
├── changes.md # Generator 산출
└── qa_report.md # Evaluator 산출
레포 루트에서 다음 파일을 찾아 lang/test/build 결정:
| 파일 | Language | Test cmd | Build cmd |
|---|---|---|---|
build.gradle / build.gradle.kts |
java | ./gradlew test |
./gradlew build |
pom.xml |
java | mvn test |
mvn compile |
pyproject.toml / setup.py |
python | pytest |
(없음) |
package.json (+ tsconfig.json) |
typescript / javascript | npm test |
npm run build |
*.csproj / *.sln |
csharp | dotnet test |
dotnet build |
go.mod |
go | go test ./... |
go build ./... |
Cargo.toml |
rust | cargo test |
cargo build |
매칭이 없으면 lang="unknown", test/build cmd 는 null.
- Phase 건너뛰기 금지 — Planner → Generator → Evaluator 순서 고정
- spec 확인 게이트 필수 — Generator 진입 전 사용자 동의
- Stay within scope — 선언된 scope 바깥 파일 수정 금지
- Evaluator 엄격 — 사소한 문제도 PASS 로 묻지 않는다
- Round 무한 루프 차단 — max round 도달 시 강제 종료
skills/harness/SKILL.md— 유일한 진입점, 모든 워크플로 규칙이 응축templates/{planner,generator,evaluator}_prompt.md— 각 phase 의 프롬프트 (Claude 가 inline 해석).claude-plugin/plugin.json— 플러그인 매니페스트.claude-plugin/marketplace.json— 비공개 마켓플레이스 인덱스
Python 코드는 v2.0 에서 통째로 제거되었습니다. v1.x 의 Python orchestrator 가 그리우면 git history 에서 v1.1.0 태그 시점을 참고하세요.
플러그인이 설치되었는지 확인:
claude plugin list설치되어 있지 않다면 설치 절차 재수행.
레포 루트에 표준 빌드 파일이 없는 경우. --lang 옵션은 지원하지 않으니, 작업 시작 시 사용자가 task 설명에 명시적으로 언어를 적어주세요 (예: "Python 으로 사용자 인증 추가").
진행 중인 작업이 있다는 의미입니다. Claude 가 state.json 을 보고 어느 phase 인지 안내합니다. 새로 시작하려면 .harness/ 를 수동 삭제하세요.