Planner-Generator-Evaluator 하네스. Planner+Generator는 메인 컨텍스트에서 직접 실행하고, Evaluator만 subagent로 격리하여 독립 검수를 보장한다.
Planner-Generator-Evaluator 하네스. Planner+Generator는 메인 컨텍스트에서 직접 실행하고, Evaluator만 subagent로 격리하여 독립 검수를 보장한다.
npx skills add https://github.com/moongci38-oss/forge --skill pgeこのコマンドをClaude Codeにコピー＆ペーストしてスキルをインストール
| name | pge |
| description | Planner-Generator-Evaluator 하네스. Planner+Generator는 메인 컨텍스트에서 직접 실행하고, Evaluator만 subagent로 격리하여 독립 검수를 보장한다. |
| user-invocable | true |
역할: 당신은 PGE 하네스를 직접 실행하는 에이전트입니다. Planner와 Generator를 메인 컨텍스트에서 수행하고, Evaluator만 subagent로 스폰합니다.
컨텍스트: 복잡한 구현/생성 작업에서 품질이 결과를 결정할 때 사용합니다.
출력: 최종 산출물 + PGE 실행 보고서 (docs/pge/YYYY-MM-DD-{task-name}-pge-report.md)
AI 출력 품질의 핵심 변수는 모델이 아니라 **구조(하네스)**다.
Grader Isolation 원칙: Evaluator subagent는 Generator 컨텍스트를 상속받지 않는다. 독립 판단 보장.
아키텍처 원칙:
/pge <task description>
/pge --rubric custom # 커스텀 Rubric 사용
/pge --cycles 2 # 최대 2사이클 (기본 3)
| 적합 | 부적합 |
|---|---|
| 코드 기능 구현 | 단순 정보 조회 |
| 버그 수정 | 파일 탐색 |
| 기획서/문서 초안 작성 | 1회성 수정 |
| 에셋/이미지 생성 기획 | 설정 변경 |
Evaluator가 사용할 평가 기준을 Generator 실행 전에 명시한다.
기본 Rubric (작업 유형에 따라 조정):
| 항목 | 가중치 | 불합격 기준 |
|---|---|---|
| 요구사항 충족도 | 40% | 핵심 요구사항 미충족 시 즉시 FAIL |
| 품질/완성도 | 30% | AI 슬롭(무의미 반복·복붙·미완성) 감지 시 0점 |
| 구조/아키텍처 | 20% | 설계 의도 위반 시 0점 |
| 문서/명확성 | 10% | 주요 내용 누락 시 5점 이하 |
PASS 기준: 합산 70점 이상 + 요구사항 즉시 FAIL 없음
PGE Workflow 시작 시 Planner가 다음 contract를 작성. Generator·Evaluator 양쪽이 참조.
sprint_contract:
scope: "이번 반복에서 다룰 것 (구체적 기능 / 파일 / 출력)"
out_of_scope: "명시적 제외 (다음 반복에서 다룸 또는 영구 제외)"
done_criteria: "Evaluator가 PASS 판정하는 객관적 조건"
rollback_trigger: "이 조건 충족 시 즉시 STOP + 사용자 에스컬레이션"
예시:
sprint_contract:
scope: "결제 API /payment/charge 엔드포인트 + 단위 테스트"
out_of_scope: "환불 API, 결제 이력 조회 (별도 sprint)"
done_criteria: "단위 테스트 PASS + Stripe sandbox 1회 전송 성공 응답"
rollback_trigger: "민감정보 로그 노출 발견 시 즉시 STOP"
출처: 하네스 엔지니어링 백과사전 제9장 Generator-Evaluator 패턴 — Sprint Contract. 효과: Generator 범위 이탈 방지 + Evaluator 판정 기준 명확화 → codex-review FAIL 사이클 감소.
subagent 스폰하지 않는다. 메인 대화에서 직접 수행한다. 이유: subagent는 이전 분석/실패 이력을 참조하지 못해 동일 실수를 반복한다.
{project_root}/.claude/reference/ 존재 확인 → 태스크 유형에 맞는 파일 Read (하단 Reference 로딩 표 참조)
1b. 과거 PGE 실패·버그 패턴 로드 (compounding — 필수):
LEARN_BY=pge bash ~/.claude/scripts/learnings.sh load pge-failure 2>/dev/null
LEARN_BY=pge bash ~/.claude/scripts/learnings.sh load bug-fix-pattern 2>/dev/null
pge-failure 항목의 apply = "이 방식은 이전 PGE에서 FAIL했음 — 피하라". 실행 계획에 반영. (access.log 자동 기록.)1. mcp__gitnexus__list_repos → indexed_date 확인 (7일+ stale = 경고)
2. mcp__gitnexus__query({query: "기능_요약"}) → 기존 구현 패턴 (재사용 가능?)
3. mcp__gitnexus__context({name: "수정_대상_클래스"}) → breaking change 위험 callers
4. mcp__gitnexus__impact({target: "수정_함수", maxDepth: 2})
→ d=1 심볼 = Generator에 "반드시 테스트" 전달
→ d=2 심볼 = 회귀테스트 범위
→ gitnexus 인덱스 없으면 skip
{project_root}/.claude/state/current-analysis.md 존재 확인 — 있으면 먼저 Read하여 이전 분석 재사용 판단{project_root}/.claude/reference/key-file-map.md Read — 기능별 파일 위치 + 쌍 수정 패턴{project_root}/.claude/reference/code-snippets.md Read — DOTween/UI/이벤트 표준 패턴{project_root}/.claude/reference/pre-modification-analysis-detail.md Read — Step 0~5 의존성 분석 지침 (핵심: Step 3 실행 흐름 추적){project_root}/.claude/reference/pge-game-evaluator-rubric-detail.md Read — 평가 기준 숙지pre-modification-analysis-detail.md의 Step 0~4 지침을 순서대로 수행 (Step 3 실행 흐름 추적이 가장 중요){project_root}/.claude/state/current-analysis.md에 저장 (Write) — Step 0출력: {project_root}/.claude/state/PGE_SPEC.md + (Unity .cs 수정 시) {project_root}/.claude/state/current-analysis.md
Planner 산출 직후 Codex 2차 게이트 실행. PGE_SPEC.md의 요구 명확성·누락·모순·YAGNI 위반 검증.
/codex-review --stage plan --target {project_root}/.claude/state/PGE_SPEC.md --blocking
forge-outputs/docs/reviews/plan/{date}-pge-spec-{slug}.{md,json}## 이전 시도 실패 이력 섹션에 추가하여 같은 갭 반복 방지)gpt-5.5 = $0.00. API key + gpt-5-mini = ~$0.02subagent 스폰하지 않는다. 메인 대화에서 직접 수행한다. 이유: Planner 분석 결과와 이전 실패 맥락을 그대로 보유한 상태에서 구현해야 한다.
{project_root}/.claude/state/PGE_SPEC.md 읽기 (Phase 1에서 이미 작성했으므로 컨텍스트에 있음){project_root}/.claude/state/current-analysis.md 재확인{project_root}/.claude/state/current-analysis.md의 Step 4에 수정 결과 추가 (수정된 파일:라인, 수정 전/후 동작 차이, 잔존 이슈)출력: {project_root}/.claude/state/PGE_SELF_CHECK.md + 산출물(코드/파일) + (Unity .cs 수정 시) 갱신된 current-analysis.md
핵심 원칙: 개발자 ≠ 테스터 Generator(메인)의 컨텍스트(의도, 시도, 가정)를 공유하지 않는 별도 subagent가 검증한다.
Generator 완료 (메인 컨텍스트)
↓ subagent 스폰 — 전달: 변경 파일 목록 + PGE_SPEC.md 경로 (Generator의 의도/가정은 전달하지 않음)
↓
QA Agent (별도 subagent, 독립 컨텍스트)
↓ 변경 파일 확장자로 트랙 자동 감지
↓
트랙별 검증 실행
| 트랙 | 감지 조건 | 호출 대상 | 비고 |
|---|---|---|---|
| A. 기능 | 서버/로직 코드 변경 (.cs service, .ts service, .py) | verify.sh code + 데이터 흐름 트레이싱 | 항상 실행 |
| B. 웹/앱 UI | .tsx/.jsx/.css/.html 변경 | /visual-loop + /playwright-parallel-test | 해당 시만 |
| C. 게임 연출/UI | Unity .cs + .prefab + .anim 변경 | /game-qa | 해당 시만 |
트랙은 중복 가능 — 서버+클라이언트 동시 변경이면 A+C 모두 실행.
PGE_QA_RESULT.md에 PASS/FAIL 기록/playwright-parallel-test → 3-Agent 병렬 브라우저 테스트PGE_QA_RESULT.md에 병합/game-qa 스킬을 호출한다.
검증 3계층:
QA FAIL 시: PGE_QA_RESULT.md를 메인 컨텍스트의 Generator에 전달 → Phase 2 재실행
반드시 subagent로 스폰한다. 메인 컨텍스트에서 실행하지 않는다. 이유: Generator와 같은 컨텍스트에서 평가하면 자기평가 편향이 발생한다.
subagent_type: general-purpose
model: sonnet
subagent에 전달하는 정보:
{project_root}/.claude/state/current-analysis.md (분석 기준){project_root}/.claude/state/PGE_SPEC.md (요구사항){project_root}/.claude/state/PGE_QA_RESULT.md (QA 결과).claude/rules/pge-game-evaluator-rubric.md + .claude/reference/pge-game-evaluator-rubric-detail.md전달하지 않는 정보: Generator의 의도, 시도 과정, 실패 이력 (독립 판정을 위해)
Evaluator 수행:
출력: {project_root}/.claude/state/PGE_QA_REPORT.md
Evaluator 산출 직후 Codex 코드 리뷰 자동 실행. Evaluator(Claude) 동일-모델 맹점 보완.
/codex-review --stage code --target <PGE diff>
Evaluator 점수별 정책:
--effort medium) — 확인 차원--effort high) — 추가 검증Evaluator vs Codex diff 처리 (Plan v2-C2 spec 기반):
agreement → Evaluator 점수 확정disagreement → Phase 4.6 (Opus Advisor) 호출extension (Codex가 추가 이슈 발견) → Codex issues PGE_QA_REPORT.md에 추가, 사용자 컨펌 후 진행 (자동 재평가 X — code stage = blocking NO per v2-C1)출력: PGE_QA_REPORT.md에 Codex 섹션 추가 (forge-outputs/docs/reviews/code/{date}-pge-{slug}.md 링크).
다음 조건 중 하나일 때 실행. PASS(80+ + Codex agreement)는 스킵.
트리거:
disagreement 발생FORGE_ADVISOR_AUTO 환경변수가 "off"가 아닌 경우 advisor-strategist 호출:
Agent(
subagent_type="advisor-strategist",
prompt="""
<판정 맥락 (500토큰 이내)>
- Rubric 항목별 점수 + 감점 사유 요약
- Codex 리뷰 결과 (있으면)
- 산출물 핵심 부분
질문:
1. 이 판정의 놓치기 쉬운 맹점 1~2개.
2. PASS/FAIL 의견 + 핵심 근거 1~2개만 답하라.
"""
)
Advisor 응답 기준:
PGE_QA_REPORT.md를 메인 컨텍스트에서 읽고 → Phase 2 재실행 (이전 실패 원인을 알고 있으므로 같은 실수 반복 방지)최대 3사이클. 3사이클 후 FAIL 잔존 시 현재 상태로 전달 + 이슈 보고.
Evaluator 최종 FAIL 시 — pge-failure 후보 기록 (compounding): 3사이클 후에도 FAIL 잔존하면 (= 이 접근 방식이 막혔다는 신호), 그 실패 패턴을 종료 핸드오버에 pge-failure 후보: 1줄로 기록 (current-analysis.md "## 이전 시도 실패 이력" 섹션 + handover 모두). /end-sonnet 또는 /end-opus가 그 후보를 learnings.sh append --category pge-failure --summary "<무엇을 하려다> <왜 막혔나>" --apply "<향후 PGE에서 이 접근 회피 — 대안은>" --evidence "<PGE 보고서 경로 or 사이클 요약>"로 learnings에 반영. (end-* 가 이미 learnings append 수행하므로 후보 큐만 넘기면 됨.)
모든 PGE 중간 파일은 {project_root}/.claude/state/에 저장한다.
| 파일 | 작성자 | 읽는 자 | 내용 |
|---|---|---|---|
PGE_SPEC.md | Planner (메인) | Generator (메인), QA (subagent), Evaluator (subagent) | 설계서 + reference 목록 |
current-analysis.md | Planner (메인) | Generator (메인), Evaluator (subagent) | 4단계 의존성 분석 + 이전 시도 실패 이력 |
PGE_SELF_CHECK.md | Generator (메인) | QA (subagent), Evaluator (subagent) | 자체 점검 결과 |
PGE_QA_RESULT.md | QA (subagent) | Evaluator (subagent), Generator (메인, 피드백 시) | 트랙별 검증 결과 |
PGE_QA_REPORT.md | Evaluator (subagent) | Generator (메인, 피드백 시) | Rubric 판정 + 개선 지시 |
| 태스크 유형 | 읽을 파일 |
|---|---|
| Unity 클라이언트 | key-file-map.md, code-snippets.md, pre-modification-analysis-detail.md |
| 서버 / 웹 / 앱 | codebase-analysis.md (존재 시), key-file-map.md, code-snippets.md, golden-rules.md |
| 웹 / 앱 UI | ~/forge/shared/design-tokens/design-rules.md |
| 프로토콜 / 네트워크 | key-file-map.md, protocol-ranges.md, tech-stack.md |
| 빌드 / 배포 | build-commands.md, dependency-order.md |
완료 시 아래 형식으로 보고:
## PGE 실행 완료
**결과물**: [산출물 경로]
**QA 반복 횟수**: X회
**최종 점수**: [항목별]
**실행 흐름**:
1. Planner (메인): [분석 내용 한 줄]
2. Generator R1 (메인): [구현 결과 한 줄]
3. QA (subagent): [검증 결과 한 줄]
4. Evaluator (subagent): [판정 + 핵심 피드백 한 줄]
5. Generator R2 (메인): [수정 내용 한 줄] (해당 시)
...
| 원칙 | 적용 |
|---|---|
| 컨텍스트 연속성 | Planner+Generator는 메인에서 실행 → 이전 분석/실패 이력 자동 참조 |
| 독립 검수 | Evaluator는 subagent → Generator의 맥락 오염 없이 코드만 보고 판정 |
| 자기평가 금지 | Generator(메인) ≠ Evaluator(subagent), 같은 에이전트가 생성+평가하지 않음 |
| 실패 이력 영속화 | current-analysis.md에 "이전 시도 실패 이력" 섹션 → 같은 실수 반복 방지 |
| 분석 프로토콜 강제 | PreToolUse hook이 current-analysis.md 내용 검증 → 분석 없이 코드 수정 차단 |
본 스킬 결과 산출 후 자동으로 eval-rubric 호출 → 4축 Rubric 채점 (clarity/consistency/completeness/safety) → eval_cases.jsonl 누적.
/eval-rubric --target {산출물 경로}
eval_cases.jsonl append:
~/.claude/skills/pge/eval_cases.jsonlEC-pge-{N} (auto-increment)hash(case_id) % 100 < 20 → holdout, 그 외 sample)sha256(skill+input.context+input.args) 충돌 시 observed_count++EVAL_RUBRIC_AUTO=off 설정 시 스킵eval_cases: off 명시 시 스킵 (특수 케이스)~/.claude/skills/eval-rubric/SKILL.md "보안 정책" 참조)출처: 하네스 백과사전 제5장 평가 하네스, eval_cases.jsonl 설계 (
forge-outputs/11-platform/skills/eval-cases/2026-05-10-v1-design/plan.md) 실패 시 [[pev-self-correction]] 적용
병렬/다단계 실행 = Workflow 도구로 컨텍스트 격리 + resume 지원. 패턴: Plan→Generate→Evaluate (Evaluator에 plan 미전달 격리).
실행: Workflow({ script: Bash("cat ~/.claude/skills/pge/workflow.js") })
CLAUDE_CODE_DISABLE_WORKFLOWS=1 시 기존 방식 fallback.
QA 전 사이클 오케스트레이터 (AD-93 Phase A~H). 브랜치 생성→시나리오 전수→버그 발견→수정 계획→Healer 병렬→cr-* + Codex 검증→develop 자동 머지→Wiki 축적. 스코프 지정 가능 (--scope=full|domain|file-pattern).
Spec 문서와 구현 코드 간의 추적성(Traceability)을 검증하는 전문 스킬. FR별 구현 파일 매핑, 테스트 존재 여부, API 계약 일치, 데이터 모델 일치를 체크하고 PASS/WARN/FAIL JSON을 반환한다. Forge Dev Phase 8 구현 완료 후 Check 8.5에서 자동 실행.
레거시→신규 스택 마이그레이션 검수 하네스. legacy=SSoT 원칙으로 로직 100% sync 도달까지 audit→fix→re-audit 자율 반복. 트리거: "/migration-audit", "마이그레이션 검수", "레거시 대조", "migration audit", "legacy vs src 비교". 지원 스택: node-nest (Socket.IO↔NestJS), php-nest, 확장 가능. 7 Phase: 인벤토리→이벤트커버리지→로직대조→DB대조→멀티검수→리포트→fix루프. 3-bucket 분류: MIGRATION-DRIFT / KNOWN-DIVERGENCE / LEGACY-BUG-CANDIDATE. 오라클: golden-test(순수함수) + black-box trace(부수효과 영역). PEV 루프 종료조건: CRITICAL+HIGH=0 AND golden 100% AND 회귀 0 AND UNVERIFIED=0(or waiver).
Clarify ambiguous requirements through focused dialogue before implementation. Use when requirements are unclear, features are complex (>2 days), or involve cross-team coordination. Ask two core questions - Why? (YAGNI check) and Simpler? (KISS check) - to ensure clarity before coding.
HMAC 기반 MAS worker 승인 토큰 발행 스킬. 사용자 TTY에서 /approve-worker {task_id} {worker} {allowed_tools} {target_paths} 호출 시 HMAC-SHA256 서명 토큰을 ${FORGE_OUTPUTS:-$HOME/forge-outputs}/.claude/audit/approvals/{task_id}-{nonce}.yaml에 저장. mas P0 approval gate 선행 필수. 트리거: /approve-worker, worker 승인, approval token 발행, mas P0 구현 시작 전.
게임/앱 UI 스크린샷에서 배경·버튼·컴포넌트를 게임 사용 가능한 투명 PNG로 추출. 배경은 nanobanana edit_image(AI inpainting), 버튼/컴포넌트는 /clip 템플릿 매칭으로 bbox를 찾고 SAM2로 pixel-accurate 세그멘테이션하여 투명 배경 PNG로 추출. 트리거: 배경 뽑아줘, 버튼 추출해줘, 컴포넌트 분리해줘, 전부 다 추출해줘, 이미지 경로와 함께 추출 요청 시.