Surface Gap Analysis

Loopy V2 표면 레이어
보완 로드맵

Loopy Command Set V2 문서가 제안한 표면 6개 명령(/loopy:start, auto, resume, status, history, measure) 대비 현재 loopy-era 엔진이 갖춘 것과 부족한 것을 정리하고, 최소 비용으로 격상하는 단계별 계획.

6
surface cmds
4/6
already covered
2
missing wrappers
~200
lines to add
Source Document
V2 문서가 말한 것
"명령어를 모두 노출하는 방식보다, 표면은 5~6개만 남기고 내부 단계는 자동 매핑하는 구조가 더 적합함. 사용자는 시작·실행·재개·상태 확인만 기억하면 되고, 하네스의 폐루프는 내부적으로 유지되어야 함." — Loopy Command Set V2 / Korean, 핵심 결론

문서는 엔진 재설계가 아니라 표면 UX 재설계를 요구한다. init-project, team, qa-scenario-gen, qa-cycle, self-improve, eval은 전부 내부로 숨기고, 사용자는 /loopy: 접두사가 붙은 6개 표면 명령만 외운다.

표면 명령내부 매핑사용 시점
/loopy:startinit-project + team + qa-scenario-gen최초 1회
/loopy:autoqa-cycle + self-improve + eval + keep/discard평소 실행
/loopy:resumecheckpoint / pending 재로딩 → auto 재진입중단 복구
/loopy:statusmetric parse + latest state수시 확인
/loopy:historyresults.tsv + findings 추이사후 검토
/loopy:measureeval only (변경 없음)진단
Before vs After
현재 시스템 vs V2 표면
Current — Stage-Exposed
/init-project
  ↓
/team
  ↓
/qa-scenario-gen
  ↓
/qa-cycle
  ↓
/self-improve
  ↓
/loopy-era-eval [N]
6개 스킬을 사용자가 직접 호출. 단계 이름이 내부 구현을 그대로 반영해서 "게으른 일반 사용자"는 순서를 기억하지 못함. 디버깅에는 유리하지만 재사용 가능성이 떨어진다.
V2 Proposal — Surface-Hidden
/loopy:start  (1회)
  ↓
/loopy:auto   (무한)
  ↓
/loopy:status (수시)
  ↓
/loopy:history (검토)

+ /loopy:resume, measure
6개 표면 명령만 암기. 흐름 이름이 start → auto → resume처럼 의도 기반으로 추측 가능. 내부 단계는 변경되어도 표면 API는 안정적이다.
Gap Analysis
무엇이 이미 있고, 무엇이 비어있나
표면 명령현재 구현엔진 성숙도갭
/loopy:start 없음 부분 (개별 스킬 존재) init-project → team → qa-scenario-gen을 순서대로 호출하는 오케스트레이션 래퍼 필요
/loopy:auto 없음 부분 (eval에 통합됨) qa-cycle → self-improve → loopy-era-eval을 폐루프로 묶는 오케스트레이션 래퍼 필요
/loopy:resume 구현됨 성숙 /loopy-era-eval resume alias만 추가
/loopy:status 구현됨 성숙 /loopy-era-eval status alias만 추가
/loopy:history 구현됨 성숙 /loopy-era-eval history alias만 추가
/loopy:measure 구현됨 성숙 /loopy-era-eval measure alias만 추가
4/6
already covered
2/6
need wrappers
0/6
namespace
100%
engine ready
What To Build
보완 필요 항목 (7개)
Implementation Plan
구현 로드맵 (3단계)
1
Alias 레이어 — 즉시 투입
~60줄 / 30분
/loopy:resume, /loopy:status, /loopy:history, /loopy:measure 4개 alias를 ~/.claude/commands/에 생성. 각 파일은 15줄 이내. 기존 엔진을 그대로 호출하므로 회귀 위험 제로.
  • commands/loopy-resume.md — /loopy-era-eval resume 호출
  • commands/loopy-status.md — /loopy-era-eval status 호출
  • commands/loopy-history.md — /loopy-era-eval history 호출
  • commands/loopy-measure.md — /loopy-era-eval measure 호출
2
오케스트레이션 래퍼 — 핵심 작업
~140줄 / 2시간
/loopy:start와 /loopy:auto 2개 래퍼 스킬 작성. 이 둘은 단순 alias가 아니라 여러 스킬을 순차 호출하므로 각 단계 실패 처리 + 진행 로그 필요. V2 §4 "내부 매핑 규칙" 표를 그대로 구현.
  • skills/loopy-start/SKILL.md — 3스킬 순차 호출 + 실패 시 stop
  • skills/loopy-auto/SKILL.md — 폐루프 반복 + $ARGUMENTS로 회차 제어
  • 각 단계 진행 상황을 results.tsv에 기록
  • 수렴 판정 이벤트 발생 시 텔레그램 알림
3
문서 · 엔포스먼트 · UX — 마감
~80줄 / 1시간
공식 README 작성, 기존 스킬에 "INTERNAL" 주석 추가, measure 파일 비변경 검증, status 출력 포맷 확장. V2 문서의 §5, §6 네이밍/UX 규칙을 마지막에 적용한다.
  • loopy-era-eval/README.md — 4단계 사용자 가이드
  • 기존 stage 스킬 상단에 INTERNAL 배너
  • measure 변경 금지 검증 (git diff empty assert)
  • status 출력에 HARD%·SOFT수·pending·회차 표준화
Risks
도입 리스크와 대응
리스크영향대응
묶음 실패 시 디버깅 어려움 중 /loopy:auto 실패 시 실패한 내부 단계명을 로그에 표시. 필요 시 원시 /qa-cycle 등 직접 호출 가능 경로 유지.
기존 사용자 마이그레이션 혼란 낮음 삭제 없이 공존. 기존 /loopy-era-eval도 계속 동작. README에 V2 매핑표 명시.
추상화 레이어 유지 부담 낮음 alias 4개는 15줄 파일, 래퍼 2개는 ~70줄씩. 총 유지 비용 ~200줄 고정.
V2 문서와 기존 측정 메트릭 불일치 중 V2 §4가 "loopy-era-eval"을 명시적으로 호출하므로 현재 HARD 비율 엔진과 완벽 호환. 신규 래퍼는 이 엔진을 내부 호출.
Verdict
결론
최종 판단
V2 문서는 엔진 개조가 아니라 표면 API 정의다. 현재 loopy-era는 엔진(HARD 측정 · keep/discard · resume · measure)을 이미 완성했으므로, 표면 6개 중 4개는 alias로, 2개는 얇은 래퍼로 달성 가능하다. 총 구현 비용은 ~200줄 / 3~4시간. 기존 스킬은 삭제하지 않고 공존시켜 하위 호환성을 유지한다. V2는 부정할 필요도, 리팩토링할 필요도 없다 — 6개 래퍼 파일만 추가하면 끝난다.

문서의 핵심 통찰은 "기억 가능성·추측 가능성·내부 단계 은닉"이라는 UX 원칙이다. 이 3가지를 만족하는 표면 레이어를 엔진 위에 얹으면, 현재 시스템의 디버깅 유연성을 잃지 않으면서 "게으른 일반 사용자"도 재사용할 수 있게 된다. 제안된 3단계 로드맵은 이 전환을 회귀 위험 없이 수행하는 최단 경로다.