メニュー
Planner-Generator-Evaluator 하네스. Evaluator만 subagent로 격리해 독립 검수한다. spec 없이 개발할 때 사용한다. 버그 수정은 /forge-fix.
Codex または Claude でインストール この Prompt をコピーして Codex、Claude、または他のアシスタントに貼り付けると、Skill ページを確認してインストールできます。
SOC 職業分類に基づく
Multi-worker 검수 스킬 (Codex + Gemini Double / Opus + Codex + Gemini Triple). 단일 Codex 검수 대비 100% 보완 카테고리 커버. 트리거: /cr-multi, /cr-double, /cr-triple, plan/spec 저장 후 자동(CR_MULTI_AUTO=on), plateau 3회 자동 승격.
Forge 하네스 읽기전용 레거시 감사: 낡은룰/중복/과대 전역컨텍스트/넓은 Skill/불필요 Hook·MCP/제품중복 분류. 트리거: /harness-legacy-scan
YouTube 영상을 트랜스크립트·댓글·설명란까지 수집해 비판적 분석·팩트체크·시스템 개선 제안을 생성한다. 사용자가 YouTube URL을 보내거나 영상 분석을 요청할 때 사용한다.
REST API 엔드포인트 HTTP 레벨 E2E 자동 테스트. Spec 또는 OpenAPI(Swagger) YAML/JSON을 읽어 엔드포인트별 테스트 케이스(happy path/인증 실패/잘못된 입력/경계값)를 자동 생성하고 curl로 실행한다. 응답 스키마를 OpenAPI 스펙과 대조해 드리프트를 감지한다. /qa 스킬이 서버/API 프로젝트 감지 시 자동 트리거. 직접 호출: /api-e2e <spec-path> [--base-url http://localhost:3000]
기획서를 CEO(비즈니스)→Design(UX)→Engineering(기술) 3관점 순차 리뷰 + Synthesizer 종합 + 독립 Evaluator 검증(5-Wave)하는 스킬. Phase 3 에이전트 회의 후 자동 트리거. (적대적 Codex 검수는 cr-triple/codex-review 별도 게이트.)
PR 생성 전 develop 대비 feature 브랜치의 성능을 비교하는 스킬. 번들 크기, 테스트 시간, API 응답 시간을 측정. P7 PR 생성 전 자동 트리거.
| name | forge-pge |
| description | Planner-Generator-Evaluator 하네스. Evaluator만 subagent로 격리해 독립 검수한다. spec 없이 개발할 때 사용한다. 버그 수정은 /forge-fix. |
역할: 당신은 PGE 하네스를 직접 실행하는 에이전트입니다. Planner와 Generator를 메인 컨텍스트에서 수행하고, Evaluator만 subagent로 스폰합니다.
컨텍스트: 복잡한 구현/생성 작업에서 품질이 결과를 결정할 때 사용합니다.
출력: 최종 산출물 + PGE 실행 보고서 (docs/pge/YYYY-MM-DD-{task-name}-pge-report.md)
spec 없는 개발 전용 하네스 — 버그 수정은
/forge-fix사용.
AI 출력 품질의 핵심 변수는 모델이 아니라 **구조(하네스)**다.
Grader Isolation 원칙: Evaluator subagent는 Generator 컨텍스트를 상속받지 않는다. 독립 판단 보장.
아키텍처 원칙:
forge-implement와의 관계 (oracle 가용성 분기 — 병합하지 않음): spec이 있는 구현은 /forge-implement가 담당하며 Evaluator 역할을 qa(Check 5.8)에 위임한다 — forge-pge는 spec이 없는 국면 전용이고, 여기서는 forge-pge 자체 Evaluator subagent가 그 독립-채점자 역할을 수행한다. 즉 둘은 하나의 구현 하네스 패밀리(oracle 가용성 분기)이며 병합하지 않는다. (라우팅 결정표: ${FORGE_ROOT:-$HOME/forge}/.claude/rules-on-demand/harness-family-map.md 참조.)
/forge-pge <task description>
/forge-pge --rubric custom # 커스텀 Rubric 사용
/forge-pge --cycles 2 # maxCycles=2 (기본 3). max_cycles·same_issue 트리거가 이 값에 연동됨 (하드코딩 아님)
/forge-pge --coder codex:max # Generator를 Codex로 라우팅(Evaluator는 독립 Claude 고정). claude:tier|codex:tier|sol|terra|luna|ab
/forge-pge --coder claude:high --advisor sol # Opus 구현 + Codex sol advisor(무료·독립). --advisor sol|terra|opus|fable
| 적합 | 부적합 |
|---|---|
| 코드 기능 구현 | 단순 정보 조회 |
| 기획서/문서 초안 작성 | 파일 탐색 |
| 에셋/이미지 생성 기획 | 1회성 수정 |
| — | 설정 변경 |
버그 수정은 여기 해당 없음 —
/forge-fix사용 (PGE = spec 없는 개발 전용).
PGE 기구(Rubric/Sprint Contract/Evaluator/Codex 2차)는 무겁다. 진입 시 아래를 먼저 판정한다:
harness-family-map.md 3분기(spec有→/forge-implement / spec無 생성→pge / 버그·증상→/forge-fix)를 실측(.specify/specs/ 존재, 증상 문구 여부)으로 먼저 판정하고, 불일치 시 올바른 하네스로 재라우팅 제안. 실증: 2026-07-09 optool 세션 2/2가 pge 부적합(정산 4메뉴=implement, 시드=직접) — "미구현처럼 보임"의 다수는 미연동·미머지·설정 드리프트다.${FORGE_ROOT:-$HOME/forge}/.claude/rules-on-demand/pre-work-branch-sweep.md 실행 — 대상 도메인의 미머지 완성물이 있으면 재작성 금지.rules-on-demand/grilling-protocol.md 준수: 권고안+근거 동반, 사실은 조사해 (detected) 표기)**로 라우팅(dev-workflow-rules §"리서치만/분석만/확인만 → 직접 응답" 정합). PGE Phase 2 Generator는 코드를 생성하므로 "제안만" 요청에 부적합. "구현/만들어/추가해"류 명시 시에만 정상 PGE.스타일 정합 pre-flight (P3, WARN — 증분 UI 셰이핑 마찰 방지): 착수 전 (a) prettier config 부재 + (b) eslint↔prettier 스타일 충돌(코드베이스 실제 스타일 vs prettier 기본값, 예: 작은따옴표 코드에 큰따옴표 기본 prettier)을 감지하면 WARN. 미정합 시 pre-commit prettier --write가 전파일 재포맷 → diff 부풀림 + 편집 워크트리 vs 커밋 브랜치 발산(증분 패치 깨짐·워크트리 재구성 반복)을 유발한다. 권고: 세션 시작 시 스타일 정합 1회 처리(prettier config 정렬 또는 eslint-config-prettier 정렬). non-blocking(감지·경고만, forge-fix에도 동일 적용).
적용 조건: 산출물이 신규 UI 화면 빌드(트랙 B — 웹/앱 화면을 처음 생성)일 때만 실행한다. 기존 화면 수정·버그수정·비-UI 산출물(서버 로직/문서/게임 연출 등)은 이 Phase를 skip하고 바로 Phase 0으로 진행한다(1줄 명시: "Phase -1 스킵 — 신규 UI 화면 아님").
이유: 사용자 규칙(tool-rules.md) — "모든 UI/UX 작업의 시작점은 Claude Design(claude.ai/design)". Design source 없이 Generator가 UI를 생성하면 rubric Phase 0의 anti-slop 축(G7·G10-b, 라인 62)이 사후 감점만 할 뿐 애초에 근거 없는 디자인이 만들어지는 것을 막지 못한다 — Phase -1은 그 사전 게이트다.
절차:
{project_root}/DESIGN.md, 05-design/ 등) 존재 확인
b. 없으면 레포 내 자매 화면(sibling-screen) 패턴 탐색 — 동일 프로젝트의 유사 화면(레이아웃/컴포넌트/토큰)을 재사용 가능한지 확인 (Grep/Glob로 유사 라우트·컴포넌트 디렉토리 탐색)
c. 둘 다 없으면 → [STOP] DESIGN_SOURCE_ABSENT (WARN, GUIDE-STOP): "신규 UI 화면인데 확정된 design source가 없음 — Claude Design(claude.ai/design)에서 컴포넌트를 먼저 만들거나, 재사용할 자매 화면을 지정하라. 디자인 소스 없이 임의 생성 진행 시 AI 슬롭 위험." Human이 (i) Claude Design 산출물 제공, (ii) 자매 화면 명시적 지정, (iii) "임의 생성 승인"(명시적 override) 중 하나를 선택할 때까지 Generator(Phase 2) 진입 보류. AD-168 WARN-first — 자동 hard-BLOCK 아님, Human 확인 없이 침묵 진행도 아님.PGE_SPEC.md 상단 ## Design Source 섹션에 기록 (경로 또는 링크 + 채택 사유 a/b/c). Phase 0 Rubric의 anti-slop 축·Phase 2 Generator가 이 섹션을 참조한다.Evaluator가 사용할 평가 기준을 Generator 실행 전에 명시한다.
기본 Rubric (작업 유형에 따라 조정):
| 항목 | 가중치 | 불합격 기준 |
|---|---|---|
| 요구사항 충족도 | 40% | 핵심 요구사항 미충족 시 즉시 FAIL |
| 품질/완성도 | 30% | AI 슬롭(무의미 반복·복붙·미완성) 감지 시 0점 |
| 구조/아키텍처 | 20% | 설계 의도 위반 시 0점 |
| 문서/명확성 | 10% | 주요 내용 누락 시 5점 이하 |
UI 태스크(트랙 B) rubric 보강 (G7·G10-b): 산출물이 UI면 "품질/완성도" 축을 구체화한다 — (a)프로젝트 {project-root}/DESIGN.md 존재 시 committed direction·토큰 계층(primitive→semantic→component)·간격/타이포 스케일 준수 여부, (b)anti-slop = forge-check-ui 블랙리스트 위반(shadcn-gray/Inter방치/cardocalypse/획일 fade-in 등) 시 감점. "museum quality"를 이 기준으로 조작 가능하게(측정가능) 만든다. reference 표의 design-tokens/design-rules.md도 로드.
rubric = 대리지표(G15): Evaluator는 점수를 좇지 말 것 — 점수 최적화·무한 폴리싱은 reward hacking. eval_ids 격리(이미 보유)에 더해, Evaluator는 목표 점수를 모른 채 결함 유무로 판정(score-blind).
PASS 기준: 합산 70점 이상 + 요구사항 즉시 FAIL 없음
PGE Workflow 시작 시 Planner가 다음 contract를 작성. Generator·Evaluator 양쪽이 참조.
sprint_contract:
scope: "이번 반복에서 다룰 것 (구체적 기능 / 파일 / 출력)"
out_of_scope: "명시적 제외 (다음 반복에서 다룸 또는 영구 제외)"
done_criteria: "Evaluator가 PASS 판정하는 객관적 조건"
eval_ids: "done_criteria별 canonical 평가 id 목록 ({requirement}:{check} kebab). Evaluator는 이 목록의 id만 사용 — 신규 wording 금지"
rollback_trigger: "이 조건 충족 시 즉시 STOP + 사용자 에스컬레이션"
eval_ids = id 안정성 레지스트리 (필수): stop-condition 결정표(regression·same_issue·data_integrity)는 사이클 간 byte-identical id를 전제한다. Evaluator(비결정적 subagent)가 같은 결함에 사이클마다 다른 wording의 id를 붙이면(예:
payment-api:stripe-validation↔payment-api:stripe-response-validation) regression이 조용히 누락된다(false-negative). 이를 막기 위해 Planner가 done_criteria마다 canonical id를 여기 고정하고, Evaluator는 이 목록에서만 id를 선택한다. 목록에 없는 신규 결함 발견 시 → Evaluator가 새 id를 제안하고 다음 사이클부터 레지스트리에 추가(append). id 변형·재명명 금지. 타이밍 (false-stop 방지): 신규 id는 발견 당-사이클 items[]에 즉시 포함(보통 FAIL verdict)되므로 rubric_all_pass(순위2)의 당-사이클 커버리지 계산에 이미 들어간다. "다음 사이클부터 레지스트리 추가"는 후속 사이클의 커버 floor 갱신용일 뿐 — 당-사이클 items에 그 id가 존재하므로 "커버 누락"으로 오판되지 않는다. 즉 동적 append와 당-사이클 커버 요구는 충돌하지 않는다.
Sprint Contract 작성 예시(YAML, 결제 API 케이스) →
reference.md §Sprint Contract 예시(필요 시 Read)
출처: 하네스 엔지니어링 백과사전 제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}-forge-pge-spec-{slug}.{md,json}## 이전 시도 실패 이력 섹션에 추가하여 같은 갭 반복 방지)gpt-5.5 = $0.00. API key + gpt-5-mini = ~$0.02subagent 스폰하지 않는다. 메인 대화에서 직접 수행한다. 이유: Planner 분석 결과와 이전 실패 맥락을 그대로 보유한 상태에서 구현해야 한다.
Generator 실행자 라우팅 (--coder, DMC 트랙C — 2026-07-15): --coder 지정 시 Generator(코드 생성)만 Claude/Codex/ab로 라우팅한다. Phase 3 Evaluator는 항상 독립 Claude subagent 고정(무변경) — Grader Isolation 원칙(자기평가 금지)은 어느 모델이 생성했든 유지된다. 즉 Codex가 Generator여도 Evaluator는 Codex를 상속·검수하지 않는다(구현자≠검증자).
MODEL=$("${FORGE_ROOT:-$HOME/forge}/shared/scripts/coder-model-resolve.sh" "$CODER_SPEC"). 미지정 = 기존 메인 컨텍스트 직접 생성(무변경, no-op).mcp__codex__codex(sandbox=workspace-write, approval-policy=on-request, cwd=현재 워크트리, model=$MODEL). PGE_SPEC.md·Sprint Contract·Rubric·Planner 분석을 프롬프트에 주입(Codex 재탐색 방지). Codex 산출물은 표시·커밋 전 secret-content-scan.sh 경유(LN-03 마스킹). Codex는 메인 컨텍스트를 상속하지 못하므로 Planner 결과를 명시 주입해야 한다(위 no-op 경로의 "맥락 보유" 이점은 Codex 라우팅 시 프롬프트 주입으로 대체).ProjectSettings/ProjectVersion.txt 또는 Unity .cs 수정 포함) → Claude 폴백. Codex Linux 샌드박스는 Unity batchmode 불가(실측 확정 2026-07-15). PGE의 Unity .cs 경로(Phase 2 항목 2·6)는 Codex로 라우팅하지 않는다.GATE=$("${FORGE_ROOT:-$HOME/forge}/shared/scripts/advisor-tier-gate.sh" "$CODER_SPEC"). skip(Generator≥Opus: sol/terra/opus/fable) → Phase 1.5 Codex Plan Review의 strategic 조언 성격은 유지하되 Opus advisor 접근조언은 생략(tier 역전 방지). advise(Generator<Opus) → advisor 조언을 Generator 프롬프트에 주입. ⚠️ bounding/STOP·T4는 tier 무관 유지. (Phase 3 Evaluator 독립은 별개 — 무변경.)--advisor <spec>(sol/terra/opus/fable)로 advisor 모델을 경우별 선택. AMODEL=$("${FORGE_ROOT:-$HOME/forge}/shared/scripts/coder-model-resolve.sh" "$ADVISOR_SPEC") → 결과가 gpt/codex면 mcp__codex__codex(sandbox=read-only)로 advisor 스폰(sol/terra, Plus 정액=무료·독립 관점), claude면 Agent(subagent_type="advisor-strategist", model=$AMODEL)(opus/fable). 미지정=현행(Opus + tier-gate). ⚠️ 독립성: advisor 벤더 ≠ 구현자 벤더 권고(같은 벤더=자기훈수 무의미 → Codex 구현엔 opus/fable advisor, Claude 구현엔 sol/terra advisor). fable은 **현재 구독 정액(종량 아님, 2026-07-16 사용자 확인)**이라 sol과 동급으로 자유 선택 가능(advisor-model-resolve 가드=kill-switch·가용성 폴백만 유지).coder-attribution.sh write "$WORKTREE" "$MODEL" → Phase 1.5 Codex Plan Review 및 후속 cr-* 진입 시 MODE=$("${FORGE_ROOT:-$HOME/forge}/shared/scripts/coder-attribution.sh" review-mode "$WORKTREE")를 --cr $MODE로 전달(codex Generator→degrade=codex 레그 배제 / 그 외→on / 무마커→on fail-open). Phase 3 Evaluator(Claude subagent)는 원래 독립이라 별개. 자기검수 방지 = 스크립트 강제.FORGE_DUAL_CODE=off → codex 요청도 Claude(메인) 대체. Codex 미가용 = Claude 폴백(로그+경고, fail-open). 모델 id = model-registry.json SSoT(버전무관).{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, 독립 컨텍스트)
↓ 변경 파일 확장자로 트랙 자동 감지
↓
트랙별 검증 실행
변경 파일 목록 = 기계적 산출 (필수):
git diff --name-only {base}...HEAD(또는git status --porcelain)로 산출한다. Generator나 사람이 손으로 골라 전달하지 않는다 — principal-agent 갭(Generator가 자신에게 유리한 파일만 선별해 넘기는 위험) 차단.
| 트랙 | 감지 조건 | 호출 대상 | 비고 |
|---|---|---|---|
| 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의 verify.sh, 트랙 B의 /visual-loop는 프로젝트마다 존재 여부가 다른 프로젝트-로컬 도구다. 부재를 브릭(무한 실패·정지)이 아니라 WARN + 대체 경로로 처리한다(forge-implement.md §Node-Repair — 진단→대체 절차→재시도의 fail-open 정신을 도구-부재 케이스에 적용):
test -f "{project_root}/verify.sh" / /visual-loop 스킬 설치 여부(claude plugin list 또는 .claude/skills/visual-loop/ 존재).WARN: verify.sh 없음 — {project_root}/package.json의 test/build 스크립트(npm test, npm run build) 또는 언어별 표준 명령(pytest, dotnet test 등)으로 대체. 대체 명령도 없으면 "빌드" 단계만으로 축소하고 QA_RESULT에 verify.sh: SKIPPED (not found, no fallback) 명시 — 트랙 A 전체를 실패 처리하지 않는다./visual-loop 부재 시 (트랙 B): WARN: /visual-loop 미설치 — /playwright-parallel-test 단독으로 진행(트랙 B는 이미 2개 도구를 병기하므로 하나만 남아도 검증 자체는 유지). 둘 다 없으면 트랙 B를 PGE_QA_RESULT.md에 SKIPPED (no UI test tool available)로 기록하고 Phase 4 Evaluator에 그 사실을 전달(Evaluator가 UI 검증 부재를 감안해 판정, 침묵 PASS 금지).bash "${FORGE_ROOT:-$HOME/forge}/shared/scripts/assert-db-isolation.sh". DB_ISOLATION: WARN(격리 미증명) 시 격리 DB(_test/_qa) 지정 후 재확인. WARN-first(non-blocking, FORGE_DB_ISOLATION_ENFORCE=1 opt-in BLOCK, fail-open).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 결과)git diff --name-only {base}...HEAD(또는 git status --porcelain)로 기계적 산출, Generator/사람이 손으로 고르지 않음 + git diff 본문){project_root}/.claude/reference/pge-game-evaluator-rubric-detail.md — 파일 존재 시에만 전달. 부재 시 WARN + Phase 0 기본 Rubric(요구사항충족도/품질완성도/구조아키텍처/문서명확성)만으로 진행(fail-open). 비-게임/비-Unity 트랙(A/B)은 이 항목 자체를 스킵.전달하지 않는 정보: Generator의 의도, 시도 과정, 실패 이력 (독립 판정을 위해)
Evaluator 수행:
{requirement}:{check} kebab-case)에 대해 PASS 또는 FAIL을 개별 선언한다.FAIL [{requirement}:{check}] — {위치} / {이유} / {방법} (위치+이유+방법 3요소 필수)PASS [{requirement}:{check}]SECURITY_CRIT [{requirement}:{check}] — {발견 내용} 을 별도 섹션에 명시한다.eval_ids 레지스트리에서만 선택 — 목록에 없는 신규 결함만 새 id 제안(다음 사이클부터 레지스트리 append). 변형·재명명 금지(regression false-negative 방지).PGE_EVAL_HISTORY.jsonl에 append (덮어쓰기 금지):
{"cycle": <N>, "score": <합산 점수>, "items": [{"id": "<requirement>:<check>", "verdict": "PASS|FAIL"}, ...], "security_crit": [<id>, ...]}
출력:
{project_root}/.claude/state/PGE_QA_REPORT.md (Rubric 판정 전문 — 사이클마다 덮어씀){project_root}/.claude/state/PGE_EVAL_HISTORY.jsonl (사이클별 누적 레코드 — append 전용, 절대 덮어쓰지 않음)Evaluator 산출 직후 Codex 코드 리뷰 자동 실행. Evaluator(Claude) 동일-모델 맹점 보완.
/codex-review --stage code --target <PGE diff>
Evaluator 점수별 정책:
--effort medium) — 확인 차원--effort high) — 추가 검증/codex-review --stage code --target <PGE diff>, 프롬프트에 "보안 관점 우선" 명시). 점수·Evaluator 분류 무관 — under-report 보완. 보안 민감 surface(가이드): auth/login/session/token/password/crypt/payment/billing/checkout/secret/credential 키워드, api·routes·controllers·handlers·middleware 경로, .env/.pem/.key 확장자.
결정론 enforcement = B2 트랙 (정직성): 변경 파일 경로를 git에서 결정론적으로 추출(stage/commit/working-tree 전부 + diff base 정확)해 자동 발동하는 것은 inline prose bash로는 신뢰 불가(diff base 누락·동시성·exit-code swallow). 진짜 mechanical 보안 게이트는 B2 훅(Human 승인) 영역 —
b2-token-enforcement-design.md패턴. 본 spec은 LLM 실행 의도만 규정.
⚠️ security STOP = best-effort advisory (B2까지): 본 보안 게이트(gate G·security_crit·security_event)는 전부 비결정적 LLM의 "의도" 실행이다. Evaluator가 SECURITY_CRIT를 미방출하거나 루프가 append/STOP를 누락하면 또 다른 비결정 단계가 잡지 못해 CRITICAL이 조용히 누락(fail-open)될 수 있다. 운영자·리뷰어는 이 보안 STOP을 hard gate가 아니라 best-effort로 취급하라 — 진짜 mechanical 강제는 B2 훅(Human 승인). 이하는 그 전제 위의 의도 규정: ⚠️ security_crit 예외 (양방향): (a) Evaluator가
SECURITY_CRIT를 보고하면 점수 정책 무관 Phase 5security_crit중단 즉시 발화 — Codex 생략 여부 무관, Evaluator 단독으로 STOP 보장(best-effort). (b) 역으로 Evaluator 누락 위험은 위 보안 민감 surface Codex 리뷰로 완화. Codex가 CRITICAL을 발견하면 루프(메인)가 그 finding을 별도security_event라인으로 JSONL에 append(새 라인 = append-only 유지 + 중단/재개에도 보존, durable) → Phase 5 순위1에서 사이클security_crit[]∪security_event로 [STOP]. in-memory 휘발 보유 금지 — 보안 신호 소실(fail-open) 방지.
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}-forge-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 응답 기준:
사이클 N 완료(Evaluator + Codex + EVAL_HISTORY append) 후, 아래 결정표를 우선순위 순으로 1회 평가한다. 먼저 매칭되는 행에서 즉시 행동하고 이후 행은 평가하지 않는다(상호 배타 보장). 모든 판정은 PGE_EVAL_HISTORY.jsonl 누적 레코드의 구조화 id만 사용 (string fuzzy 금지 — 루프-커널 표준 §2). 유일한 예외 = rollback_trigger(순위1) — Human이 작성한 prose hard-STOP 조건이라 structured-id가 없고 자연어 판정을 허용한다(명시적 carve-out, 그 외 전 조건은 id-only).
maxCycles = --cycles 인자 (기본 3). 아래 표의 N=maxCycles·N<maxCycles는 이 값에 연동(하드코딩 아님). same_issue는 3사이클 연속 FAIL 휴리스틱이라 maxCycles≥3에서만 도달 가능. ⚠️ --cycles 1~2면 regression(N≥2)·same_issue(N≥3) 가드가 모두 비활성 = 회귀 보호 없는 단발/이중 모드(명시적 선택 시에만 권장 — 기본 3 유지 권고).
전제 게이트 G (평가 가능성 — 번호 없음): data_integrity. 사이클 N 레코드(regression 평가 시 N-1 포함) 누락·JSON 파싱불가면 결정표 평가 자체가 불가 → 즉시 [STOP] DATA_INTEGRITY. 아래 [루프 지시] 게이트 G가 규정(검증 = LLM 실행 의도; 진짜 mechanical 파서 = B2 트랙). ("우선순위"가 아니라 "평가 가능 여부" 게이트라 번호를 빼 1↔2 순위 모순 제거.)
| 순위 | 조건 | 트리거 (EVAL_HISTORY 기반) | 발화 사이클 | 행동 |
|---|---|---|---|---|
| 1 | security_crit / rollback_trigger | 사이클 N 레코드 security_crit[] ≠ ∅ OR JSONL에 security_event 라인 존재(Codex CRITICAL을 별도 라인 append — durable, append-only) 또는 Sprint Contract rollback_trigger 충족(prose 조건 — structured-id 예외, 아래 주) | N≥1 | [STOP] Human (메시지 [SECURITY_CRIT] / 비보안은 [ROLLBACK]) |
| 2 | rubric_all_pass | 사이클 N items가 eval_ids 레지스트리 ∪ 이전 PASS id 합집합을 커버 AND items[] 전체(커버 집합 + 신규 발견 id 포함) verdict=PASS (FAIL이 단 1개라도 items[]에 있으면 — 신규 비등록 결함이라도 — SUCCESS 아님. 항목판정 authoritative; 합산<70이면 재산정 1회) | N≥1 | SUCCESS → 산출물 저장 + 보고서. 커버 누락 OR items[] 내 FAIL 존재 시 SUCCESS 아님 → N≥2면 순위3(regression) 재확인, N=1이면 continue(재시도) |
| 3 | regression | (N-1 PASS id) ∩ (N FAIL id 또는 N items에서 사라진 id — 1회 re-emit 재확인 후) ≠ ∅. ※N-1 레코드 누락/파싱불가 시 게이트 G로 [STOP] DATA_INTEGRITY | N≥2 | [STOP] Human — 이전 통과 깨짐(위험). oscillation 첫 flip 포섭 |
| 4 | same_issue (kernel 실호출, 아래 [루프 지시] 4번) | 동일 id가 3사이클 연속(N-2·N-1·N) 모두 FAIL — 구조적 막힘 (maxCycles>3: cap 전 조기 STOP / 기본 maxCycles=3: cap과 동시 발화 = STOP 메시지 구분만, 조기종료 효과 X) | N≥3 (maxCycles<3이면 dead row — 의도됨) | [STOP] + "구현 방식 전환 권고" |
| 5 | max_cycles | N ≥ maxCycles 또는 PGE_CALL_CAP(tool-call 횟수) 초과 | N=maxCycles | [STOP] 현재 상태 + 잔존 이슈 전달 |
| — | (그 외 FAIL 잔존) | 게이트 G·순위 1~5 미해당 | N<maxCycles | continue → Phase 2 재진입. Evaluator FAIL 피드백 = 접근방식 전환 입력 (정상 루프 본체) |
id 표기: 사람용 라벨
SECURITY_CRIT(대문자) = JSONL 필드security_crit(소문자) = 동일 개념(verdict PASS/FAIL은 라벨·필드 모두 대문자). 결정표(게이트 G + 순위15)와 아래 [루프 지시] 단계(G + 15)는 1:1 정렬.
도달성·상호배타 (검수 모순 해소):
/forge-loop-maker maxCycles≥6, regression이 STOP 아닌 advisory)에서 별도 분기로 살아있고, PGE에서는 regression이 흡수하는 것이 정확한 구현. (이전 버전의 oscillation continue 분기 = dead code였음 — 제거.)STOP 메시지 형식:
"[REGRESSION] {req}:{check} — 사이클 {N-1} PASS → 사이클 {N} FAIL(또는 items 소멸). Human 에스컬레이션.""[SECURITY_CRIT] {finding}. 보안 CRITICAL — Human 에스컬레이션." (Sprint Contract rollback_trigger 중복 시 동일)"[SAME_ISSUE] {id} 3사이클 연속 FAIL = 구조적 막힘. 구현 방식 전환 권고(현 접근 회피)." + current-analysis.md "## 이전 시도 실패 이력"에 id 기록"[DATA_INTEGRITY] 사이클 {N 또는 N-1} 레코드 누락/파싱불가 — 평가/regression 판정 불가. fail-safe STOP."최대 maxCycles 사이클(결정표 순위5, 기본 3). 도달 후 FAIL 잔존 시 현재 상태로 전달 + 이슈 보고.
Phase 5 결정표 Acceptance trace(C1~C3 워크스루) + SSoT 단일화 현황 rationale(same_issue kernel 실호출 vs 나머지 4종 정직한 경계) →
reference.md §Phase 5 결정표 Acceptance trace/§SSoT 단일화 현황(필요 시 Read)
call-budget 캡: 각 사이클(Phase 1→2→3→4) 진입 전 확인 — 실측 tool-call 횟수(loop-call-accum.sh PostToolUse 훅이 누적한 .calls)를 loop-budget.sh로 읽어 비교.
구
PGE_TOKEN_CAP(LLM 자가추정 토큰)은 theater였다 — PostToolUse payload에output_tokens필드가 없어 토큰 실측 불가(799세션 토큰파일 전부 0으로 실증). B2에서 tool-call 횟수(tool_name존재로 실측 가능)로 전환. 이것이 line 363 "P4 agent-budget 훅 연동 예정"의 이행분.
PGE_CALL_CAP = 환경변수 PGE_CALL_CAP (기본: 600 — orchestrator급)
사이클 진입 전 (bash, 메인 컨텍스트):
used=$(bash ${FORGE_ROOT:-~/forge}/shared/scripts/loop-budget.sh "${PGE_CALL_CAP:-600}")
rc=$?
if [ "$rc" -ne 0 ]; then # exit 1 = over cap (loop-budget.sh가 cap 비교)
"[STOP] PGE_CALL_CAP={cap} 도달 (tool-call ${used}). 사이클 {N} 시작 취소."
현재까지 산출물 경로 + Evaluator 마지막 판정 반환
loop-budget.sh <cap> [sid] = loop-call-accum.sh가 ${PWD}/.claude/agent-budget/${SID}.calls에 누적한 실측 tool-call 횟수를 읽어 cap과 비교 (exit 0=under / 1=over). 훅 미등록 또는 .calls 부재 시 0 반환=inert(안전).${CLAUDE_SESSION_ID:-unknown}로 키잉. producer(훅)는 payload .session_id(= 세션 UUID)로 키잉하므로, 메인 컨텍스트에 CLAUDE_SESSION_ID(동일 UUID)가 set이면 정렬, 미set이면 unknown 버킷 → 0=inert(미정렬은 under-STOP=안전방향). 정확 정렬 필요 시 loop-budget.sh <cap> <session-uuid> 2번째 인자로 명시.stop-condition 가드: 모든 판정은 PGE_EVAL_HISTORY.jsonl에 append된 사이클 레코드를 유일한 데이터 소스로 사용한다. 구조화 id 기반 비교만 허용 (string fuzzy 금지 — 루프-커널 표준 §2). Evaluator는 각 항목에 결정론적 id를 부여해야 한다: 형식 {requirement}:{check} (예: payment-api:stripe-response-validation, ui-layout:responsive-breakpoint). prose 요약 앞 N자 비교는 사이클 간 wording drift로 false-negative가 발생하므로 사용 금지.
파일명 규약: 본문 전체는 canonical base명
PGE_EVAL_HISTORY.jsonl로 참조한다. 동시성 격리 (472-799 세션 환경): 실제 파일은 base명에 per-run suffix(PGE_EVAL_HISTORY.{run_id}.jsonl)를 붙여 생성한다. run_id handshake (writer/reader 동일 경로 보장):{run_id}는 Phase 0에서 1회 생성(시작 시각+nonce)해PGE_SPEC.md상단에 기록한다. Evaluator(쓰기)·루프(읽기) 모두 매 사이클 PGE_SPEC.md의run_id를 읽어 경로를 도출 → 양측이 동일 파일 참조 보장(reader가 fresh run_id 재계산해 빈 파일 읽는 fail-open 차단). 단일 런 내 순차 append라 런-내 race 없음. 진짜 atomic append + flock = B2 트랙(Human 승인) — inline prose는 per-run 파일 분리·handshake까지만 보장.
[Evaluator 지시] 항목별 판정 출력 형식 (사이클마다 전항목 필수):
PASS 항목: `PASS [{requirement}:{check}]`
FAIL 항목: `FAIL [{requirement}:{check}] — {위치} / {이유} / {방법}`
CRITICAL 보안: `SECURITY_CRIT [{requirement}:{check}] — {발견 내용}` (별도 섹션)
규칙: 동일 결함은 사이클이 달라도 동일 id. 설명 wording 변경 금지. **id는 Sprint Contract `eval_ids` 레지스트리에서만 선택** — 목록에 없는 신규 결함만 새 id 제안(다음 사이클부터 레지스트리 append). 변형·재명명 금지(regression false-negative 방지).
[레코드 스키마 — 2종 (각 1줄 JSONL)]:
· eval-record (Evaluator): `{"type":"eval", "cycle": <N>, "score": <합산>, "items": [{"id":"<req>:<chk>","verdict":"PASS|FAIL"}, ...], "security_crit": [<id>, ...]}`
· security_event (루프, Codex CRITICAL 시): `{"type":"security_event", "cycle": <N>, "security_event": [{"id":"<req>:<chk>","src":"codex"}]}`
**한 cycle에 eval-record 1줄 + security_event 0~N줄 공존 = valid** (`type`으로 판별). 같은 cycle 값의 복수 라인은 정상 — gate G는 'cycle 중복'을 오류로 보지 않는다.
[Evaluator 지시] 사이클 eval-record append (PGE_EVAL_HISTORY.jsonl):
위 eval-record 스키마 1줄.
※ 파일이 없으면 새로 생성. 존재하면 마지막 줄 뒤에 newline + 새 JSON 객체 1줄. 덮어쓰기 금지.
※ **read-modify-write 금지** — 파일 전체를 읽고 재작성하면 이전 사이클 레코드 유실 위험. 반드시 끝에 한 줄만 추가(`>>` 의미).
append 도구가 없으면 마지막 줄 1개만 읽어 형식 확인 후 newline+신규객체 추가. 1줄=1 JSON 객체(JSONL) 불변식 유지.
※ append 누락·malformed JSONL 발생 시 → 루프가 **당-사이클 N 게이트 G**(append 직후 즉시 읽기)에서 data_integrity로 감지해 [STOP] fail-safe (N+1로 미루지 않음 — 조용한 false-negative 방지).
[루프 지시] 사이클 N 완료 후 게이트 G → 결정표(순위1~5)를 순서대로 1회 평가 (PGE_EVAL_HISTORY.jsonl 참조). 먼저 매칭되는 행에서 즉시 행동·중단, 이후 행 미평가 (상호 배타). 단계 번호 = 결정표(G + 1~5)와 1:1:
G. data_integrity (전제 게이트 — 평가 가능성): Evaluator append 직후 루프(메인)가 **반드시** 사이클 N의 **eval-record**(`type=eval`, cycle=N인 마지막 라인)를 읽어 파싱(N+1로 미루지 않음 — STOP 경로가 N+1을 막을 수 있어 당-사이클 검증 필수). **regression(순위3) 평가하는 N≥2 사이클에서는 N-1 eval-record도 함께 파싱**. eval-record 누락·JSON 파싱불가 → 즉시 [STOP] DATA_INTEGRITY. (security_event 라인은 별개 type — 같은 cycle 공존이 정상이라 '중복'으로 STOP하지 않음. 순위1이 별도로 스캔.)
> **결정론 validator = B2 트랙 (정직성)**: 진짜 mechanical JSONL 검증(파서 exit-code 강제 + per-run 격리 + 동시성 lock)은 **B2 훅(Human 승인)** 영역. inline prose는 LLM이 읽어 STOP하는 **의도**만 규정 — 100% 기계 강제 보장 아님. (이전 인라인 python `-c`/heredoc은 diff base·exit-code·동시성 버그를 양산해 제거.)
1. security_crit / rollback_trigger:
(a) Phase 4.5에서 Codex CRITICAL 발견 시 → 루프가 **별도 라인을 append**: `{"cycle": N, "security_event": [{"id":"<req:chk>","src":"codex"}]}`. 새 라인 = append-only 유지 + 중단/재개에도 보존(durable). (in-memory 휘발 금지 — fail-open 방지.)
(b) JSONL의 사이클 N `security_crit[]` ∪ 전체 `security_event` 라인 중 하나라도 비어있지 않으면 → [STOP] SECURITY_CRIT.
(c) Sprint Contract `rollback_trigger`(보안/비보안) 충족 → [STOP] (비보안은 `[ROLLBACK]` 메시지). rollback_trigger는 prose 조건이라 structured-id 비교의 명시적 예외(Human이 작성한 hard-STOP 트리거).
2. rubric_all_pass:
전제1 (커버리지) — 사이클 N items의 id 집합이 (Sprint Contract eval_ids 레지스트리 전체 ∪ 직전 사이클 PASS id 합집합)을 **커버**.
전제2 (전항목 PASS) — 사이클 N **items[] 전체**에 verdict=FAIL이 하나도 없어야 함. 신규 발견(레지스트리 미등록) 결함이 items[]에 FAIL로 있으면 SUCCESS 불가 — all-PASS 집계는 covered 부분집합이 아니라 items[] 전수.
전제1·2 중 하나라도 불충족 → SUCCESS 아님. N≥2면 순위3(regression) re-emit 재확인. **N=1이면 regression(N≥2) 미도달 → continue(재시도)** — 이전 PASS 집합 없어 회귀 개념 미성립.
커버 충족 + 커버된 전 items verdict=PASS → SUCCESS (산출물 저장 + 보고서).
합산<70인데 전항목 PASS면 항목판정 authoritative — Evaluator 점수 재산정 1회. 재산정 후 일부 FAIL 전환 시 SUCCESS 취소 → 순위3~ 재평가.
3. regression (N ≥ 2):
(사이클 N-1 PASS id 집합) ∩ (사이클 N FAIL id 집합 ∪ {N items[]에서 사라진 N-1 PASS id, 단 아래 re-emit 후}) ≠ ∅
→ [STOP] REGRESSION (해당 id 보고). oscillation 첫 flip 포섭 — 별도 oscillation 체크 없음.
※ 전제: 사이클 N-1 레코드 필요. 누락/파싱불가 시 → 게이트 G로 [STOP] DATA_INTEGRITY (false-negative 방지).
※ item-set 축소 (열거 drift false-STOP 방지): N-1 PASS id가 N items[]에서 사라지면 **즉시 hard-STOP 금지** — 먼저 Evaluator에 **해당 id 1회 re-emit 요청**(verdict만 재확인). re-emit 결과: (i) PASS → 단순 열거 drift였음, regression 아님(계속) / (ii) FAIL 또는 재차 누락 → 진짜 regression = [STOP]. 1회 재확인으로 LLM 열거 drift에 의한 false Human-escalation 차단.
4. same_issue (N ≥ 3, maxCycles≥3; maxCycles<3이면 dead row — 의도됨) — **kernel 실호출 (SSoT 단일화)**:
PGE 메인 컨텍스트는 일반 Bash 프로세스이므로 `loop-kernel.js`의 `checkSameIssue`를 실제로 import한다(healer.md·forge-implement.md의 검증된 호출 패턴을 그대로 이식 — 재구현 금지):
> 실행 스크립트 본문(node --input-type=module 호출 + KERNEL_OUT/STATE_FILE 처리) → `reference.md §same_issue kernel 실호출 스크립트 본문` (필요 시 Read)
- `timeout 10` 래핑 = cr-final H2 수정(2026-07-05, healer.md/forge-implement.md 동일 적용) — kernel import가 hang해도 10초 후 강제종료로 `KERNEL_RC=124`를 돌려받아 폴백이 반드시 발동한다.
- **정지 판정**: `KERNEL_OUT`의 `tripped==true`(동일 id가 kernel `SAME_ISSUE_MAX=3`회 누적) → [STOP] SAME_ISSUE.
- **폴백(캡 소실 금지, fail-open)**: `KERNEL_RC≠0`(timeout exit 124 포함) 또는 `KERNEL_OUT` 빈 값이면 kernel을 무시하고 기존 로컬 판정(사이클 N-2·N-1·N 레코드 모두에서 동일 id가 FAIL)으로 즉시 폴백 — same_issue 캡이 어느 경로든 사라지지 않는다.
→ [STOP] SAME_ISSUE + "방식 전환 권고" (재진입 없음). current-analysis.md "## 이전 시도 실패 이력"에 id 기록.
- 상세 근거·검증 이력은 `.claude/agents/healer.md §loop-kernel.js SSoT 연동`·`.claude/commands/forge-implement.md` 동 섹션 참조 — 새 script 파일 작성 금지, 동일 kernel 재사용.
5. max_cycles (N ≥ maxCycles, PGE_CALL_CAP 초과 포함):
→ [STOP] 현재 상태 + 잔존 이슈 전달
— 그 외 FAIL 잔존 (N < maxCycles):
→ continue: current-analysis.md "## 이전 시도 실패 이력"에 FAIL id 기록 후 Phase 2 재진입.
Evaluator FAIL 피드백 = 접근방식 전환 입력. 재진입 시 기록된 id의 이전 접근방식 명시적 제외.
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 수행하므로 후보 큐만 넘기면 됨.)
.specify/ 프로젝트 한정, WARN-first)배경 (2026-07-12 실발화, Batch 4-1): PGE는 spec 없는 개발 전용 하네스다. 그런데 SDD를 채택한 프로젝트(.specify/specs/ 존재)에서는 CI spec-validation job이 fix/* 외 브랜치에 대해 .specify/specs/{branch}.md 존재를 요구한다 — PGE 산출물은 이 요구를 충족하지 못해 PR 단계에서 항상 FAIL한다. 라우팅(spec 無 = pge)과 프로젝트 CI(spec 요구)가 구조적으로 모순되므로, PGE 자신이 종료 시점에 트레이서빌리티 자산을 남겨 이 모순을 해소한다.
절차 (Phase 5 SUCCESS 판정 직후, PR 단계 진입 전):
test -d "{project_root}/.specify" 확인.
.specify/specs/{branch-name}.md 사후 Spec 발행 (현재 브랜치명 = git rev-parse --abbrev-ref HEAD로 기계적 산출). 기존 파일 있으면 덮어쓰지 않고 append 섹션 추가. 최소 포함 항목:
## 구현된 FR — Sprint Contract done_criteria/eval_ids를 FR 형태로 역변환## 변경 범위 — git diff --name-only {base}...HEAD 산출 파일 목록## 검증 결과 — Phase 4 Evaluator 최종 점수 + PGE_EVAL_HISTORY.jsonl 최종 사이클 items[] 요약## 산출 근거 — PGE_SPEC.md·PGE_QA_REPORT.md 경로 링크 (사후 검토 가능하도록).specify/specs/{branch}.md 발행 완료" 1줄 추가.WARN-first: 발행 실패(쓰기 권한·경로 오류 등)해도 PGE 전체를 FAIL 처리하지 않는다 — WARN 후 완료 보고에 "spec 발행 실패, 수동 보완 필요" 명시(AD-168 준수, 신규 hard-BLOCK 아님).
모든 PGE 중간 파일은 {project_root}/.claude/state/에 저장한다.
| 파일 | 작성자 | 읽는 자 | 쓰기 방식 | 내용 |
|---|---|---|---|---|
PGE_SPEC.md | Planner (메인) | Generator (메인), QA (subagent), Evaluator (subagent) | 덮어쓰기 | 설계서 + reference 목록 |
current-analysis.md | Planner (메인) | Generator (메인), Evaluator (subagent) | 본체 덮어쓰기 + ## 이전 시도 실패 이력 섹션은 append(사이클 간 누적) | 4단계 의존성 분석(덮어쓰기) + 이전 시도 실패 이력(append — same_issue 추적 입력, 덮어써 유실 금지) |
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 판정 + 개선 지시 (사이클별 최신 상태) |
PGE_EVAL_HISTORY.jsonl | Evaluator (subagent) + 루프(security_event 라인) | Phase 5 루프 (메인) | append 전용 (절대 덮어쓰기 금지) | 사이클별 누적 레코드(cycle 레코드) + Codex CRITICAL security_event 라인 — regression(oscillation 포섭)·same_issue·security_crit·data_integrity 판정의 유일한 데이터 소스. 누락/손상 시 data_integrity STOP |
| 태스크 유형 | 읽을 파일 |
|---|---|
| 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/forge-pge/eval_cases.jsonlEC-forge-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/forge-pge/workflow.js") })
CLAUDE_CODE_DISABLE_WORKFLOWS=1 시 기존 방식 fallback.