| 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)
PGE — Planner-Generator-Evaluator 하네스
AI 출력 품질의 핵심 변수는 모델이 아니라 **구조(하네스)**다.
Grader Isolation 원칙: Evaluator subagent는 Generator 컨텍스트를 상속받지 않는다. 독립 판단 보장.
아키텍처 원칙:
- Planner + Generator: 메인 컨텍스트에서 직접 실행 → 이전 분석/실패 이력을 자연스럽게 참조
- Evaluator: subagent로 격리 → Generator의 의도/가정을 모른 채 코드 자체만 보고 독립 검수
- 자기평가 금지: Generator가 만든 코드를 Generator가 평가하지 않는다
사용법
/pge <task description>
/pge --rubric custom # 커스텀 Rubric 사용
/pge --cycles 2 # 최대 2사이클 (기본 3)
적용 대상
| 적합 | 부적합 |
|---|
| 코드 기능 구현 | 단순 정보 조회 |
| 버그 수정 | 파일 탐색 |
| 기획서/문서 초안 작성 | 1회성 수정 |
| 에셋/이미지 생성 기획 | 설정 변경 |
실행 워크플로우
Phase 0: Rubric 확정
Evaluator가 사용할 평가 기준을 Generator 실행 전에 명시한다.
기본 Rubric (작업 유형에 따라 조정):
| 항목 | 가중치 | 불합격 기준 |
|---|
| 요구사항 충족도 | 40% | 핵심 요구사항 미충족 시 즉시 FAIL |
| 품질/완성도 | 30% | AI 슬롭(무의미 반복·복붙·미완성) 감지 시 0점 |
| 구조/아키텍처 | 20% | 설계 의도 위반 시 0점 |
| 문서/명확성 | 10% | 주요 내용 누락 시 5점 이하 |
PASS 기준: 합산 70점 이상 + 요구사항 즉시 FAIL 없음
Sprint Contract (Generator ↔ Evaluator 합의 형식)
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 사이클 감소.
Phase 1: Planner (메인 컨텍스트에서 직접 실행)
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 자동 기록.)- 작업 요구사항 분석
2b. GitNexus 구조 탐색 (인덱스된 프로젝트에서 추가 실행 — 계획서 P1-G3):
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
- Unity 클라이언트 .cs 수정이 포함된 경우 (필수 순서):
{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 04 섹션 + 대상 파일명 필수 포함
→ Hook이 내용 검증함: Step 04 섹션 없거나 대상 파일명 없으면 .cs 수정이 차단됨
- 이전 시도 실패 이력 확인: 대화 컨텍스트에 이전 PGE 시도가 있으면 실패 원인을 current-analysis.md "## 이전 시도 실패 이력" 섹션에 기록하고, 같은 접근을 반복하지 않는다
- 산출물 구조 설계 (목차, 컴포넌트, 인터페이스 등)
- Phase 0에서 확정한 Rubric을 실행 계획에 포함
출력: {project_root}/.claude/state/PGE_SPEC.md + (Unity .cs 수정 시) {project_root}/.claude/state/current-analysis.md
- 상단에 "## 참조 컨텍스트" 섹션 — 로드한 reference 파일 목록 + 핵심 내용 요약
- 이후 실행 계획 본문
Phase 1.5: Codex Plan Review (자동, blocking)
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}
- PASS/WARN → Phase 2 진입
- FAIL → Planner 재실행 (Codex issues[]를 PGE_SPEC.md
## 이전 시도 실패 이력 섹션에 추가하여 같은 갭 반복 방지)
- 비용: ChatGPT OAuth
gpt-5.5 = $0.00. API key + gpt-5-mini = ~$0.02
Phase 2: Generator (메인 컨텍스트에서 직접 실행)
subagent 스폰하지 않는다. 메인 대화에서 직접 수행한다.
이유: Planner 분석 결과와 이전 실패 맥락을 그대로 보유한 상태에서 구현해야 한다.
{project_root}/.claude/state/PGE_SPEC.md 읽기 (Phase 1에서 이미 작성했으므로 컨텍스트에 있음)- Unity .cs 수정이 포함된 경우 필수:
{project_root}/.claude/state/current-analysis.md 재확인
- 계획에 따라 산출물 생성/구현 — 반드시 reference의 패턴/규칙을 준수
- Rubric 기준을 의식하며 생성. 목표: "museum quality" (라이브러리 기본값·AI 슬롭 패턴 금지)
- QA 핸드오프 전 자기검토:
- Unity .cs 수정 완료 후:
{project_root}/.claude/state/current-analysis.md의 Step 4에 수정 결과 추가 (수정된 파일:라인, 수정 전/후 동작 차이, 잔존 이슈)
출력: {project_root}/.claude/state/PGE_SELF_CHECK.md + 산출물(코드/파일) + (Unity .cs 수정 시) 갱신된 current-analysis.md
Phase 3: QA — 독립 에이전트 검증 (subagent)
핵심 원칙: 개발자 ≠ 테스터
Generator(메인)의 컨텍스트(의도, 시도, 가정)를 공유하지 않는 별도 subagent가 검증한다.
QA 에이전트 스폰
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 모두 실행.
트랙 A: 기능 테스트
- 빌드: 프로젝트 빌드 실행 → Error 0건 확인
- 데이터 흐름 트레이싱 (버그 수정 시 필수):
- 수정한 코드의 전체 호출 경로를 추적
- 각 단계에서 값 유효성 확인
- 결과:
PGE_QA_RESULT.md에 PASS/FAIL 기록
트랙 B: 웹/앱 UI/UX 테스트
/playwright-parallel-test → 3-Agent 병렬 브라우저 테스트- 결과:
PGE_QA_RESULT.md에 병합
트랙 C: 게임 연출/UI 테스트
/game-qa 스킬을 호출한다.
검증 3계층:
- 파라미터 검증: 코드 수치 ↔ 기획서/레퍼런스 1:1 대조
- 런타임 검증: Unity MCP로 캡처 → 레퍼런스 비교
- Human 필요 항목 명시: AI가 판단할 수 없는 퀄리티 항목을 리스트업
QA FAIL 시: PGE_QA_RESULT.md를 메인 컨텍스트의 Generator에 전달 → Phase 2 재실행
Phase 4: Evaluator (subagent — 독립 검수)
반드시 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 결과)- 코드 diff (변경된 파일 목록 + git diff)
.claude/rules/pge-game-evaluator-rubric.md + .claude/reference/pge-game-evaluator-rubric-detail.md
전달하지 않는 정보: Generator의 의도, 시도 과정, 실패 이력 (독립 판정을 위해)
Evaluator 수행:
- 루브릭 파일 읽기
- PGE_SPEC.md 읽기 (참조 컨텍스트 확인)
- Phase 0의 Rubric으로 항목별 점수 산정
- QA 결과 반영 — 잔존 이슈가 있으면 감점
- PASS/FAIL 판정
- FAIL 항목에 대한 구체적 개선 지시 — 위치 + 이유 + 방법 3요소 필수
- 절대 관대하게 보지 마라: Generator 자체검토(SELF_CHECK.md)를 그대로 믿지 않는다
출력: {project_root}/.claude/state/PGE_QA_REPORT.md
Phase 4.5: Codex 2차 리뷰 (자동, 이중 게이트)
Evaluator 산출 직후 Codex 코드 리뷰 자동 실행. Evaluator(Claude) 동일-모델 맹점 보완.
/codex-review --stage code --target <PGE diff>
Evaluator 점수별 정책:
- 80점+ (PASS): Codex 일반 리뷰 (
--effort medium) — 확인 차원
- 60~79점 (경계): Codex 적대적 리뷰 (
--effort high) — 추가 검증
- 60점 미만 (FAIL): Codex 호출 생략 — 이미 명백한 실패
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 링크).
Phase 4.6: Opus Advisor (경계 케이스 + 모순 시)
다음 조건 중 하나일 때 실행. PASS(80+ + Codex agreement)는 스킵.
트리거:
- Evaluator 점수 60~79점 (경계)
- Phase 4.5에서 Evaluator-Codex
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 응답 기준:
- Advisor가 PASS → 최종 PASS (Evaluator·Codex 판정 오버라이드)
- Advisor가 FAIL 동의 → FAIL로 Phase 2 재실행
- 응답은 400~600토큰 이내로 제한
Phase 5: 피드백 루프
- PASS: 종료 → 최종 산출물 저장 → 보고서 작성
- FAIL (사이클 1~2):
PGE_QA_REPORT.md를 메인 컨텍스트에서 읽고 → Phase 2 재실행 (이전 실패 원인을 알고 있으므로 같은 실수 반복 방지)
- 3회 연속 같은 항목 FAIL: 구현 방식 자체 변경 (단순 수정 불가)
- FAIL (사이클 3 이후): [STOP] Human 에스컬레이션
최대 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 판정 + 개선 지시 |
프로젝트 Reference 로딩 (Planner 필수)
| 태스크 유형 | 읽을 파일 |
|---|
| 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 통합)
본 스킬 결과 산출 후 자동으로 eval-rubric 호출 → 4축 Rubric 채점 (clarity/consistency/completeness/safety) → eval_cases.jsonl 누적.
호출 시점
- 본 스킬 핵심 산출물 저장 직후 — Evaluator subagent 결과 (PGE Phase 4 종료)
절차
- 스킬 산출물 저장 후 다음 호출:
/eval-rubric --target {산출물 경로}
- eval-rubric의 verdict (PASS/WARN/FAIL) + 4축 점수 + rationale 수신
eval_cases.jsonl append:
- 위치:
~/.claude/skills/pge/eval_cases.jsonl
- case_id:
EC-pge-{N} (auto-increment)
- split: holdout 결정 (
hash(case_id) % 100 < 20 → holdout, 그 외 sample)
- dedupe key:
sha256(skill+input.context+input.args) 충돌 시 observed_count++
자동 비활성 조건
- 환경변수
EVAL_RUBRIC_AUTO=off 설정 시 스킵
- 본 스킬 frontmatter에
eval_cases: off 명시 시 스킵 (특수 케이스)
통합 효과
- FAIL 케이스 자동 누적 → 회귀 평가 데이터셋 구축
- WARN 시 사용자 알림 (자동 차단 X — 본 스킬 verdict 우선)
- 분기별 Harness GC 사이클의 Quality Audit 입력으로 활용
보안 / 데이터 보호
- eval-rubric의 입력 redaction 정책 자동 적용 (
~/.claude/skills/eval-rubric/SKILL.md "보안 정책" 참조)
- 산출물에 secret/PII 의심 시 → eval-rubric STOP fail-safe 발화 → 본 스킬도 STOP
출처: 하네스 백과사전 제5장 평가 하네스, eval_cases.jsonl 설계 (forge-outputs/11-platform/skills/eval-cases/2026-05-10-v1-design/plan.md)
실패 시 [[pev-self-correction]] 적용
Workflow 통합 (계획서 P1)
병렬/다단계 실행 = Workflow 도구로 컨텍스트 격리 + resume 지원. 패턴: Plan→Generate→Evaluate (Evaluator에 plan 미전달 격리).
실행: Workflow({ script: Bash("cat ~/.claude/skills/pge/workflow.js") })
CLAUDE_CODE_DISABLE_WORKFLOWS=1 시 기존 방식 fallback.
