docs(dev): AskUserQuestion 사실전제 grep 선검증 규칙(#4) 등재 + \u 이스케이프 재발 기록

game-register.jsp 세션에서 orchestrator가 CSS 변수 대체 가능성을 grep 없이 옵션 전제로 제시했다가 재확인 왕복이 발생한 사례를 규칙 4로 명문화. 같은 세션에서 AskUserQuestion \u 이스케이프 손타이핑 실수(규칙 2)도 재발했음을 발원 사례에 추가 — 이번엔 스키마 검증에서 걸렸으나 항상 그렇게 걸리지는 않는다는 점을 명시. 세션 20260701-142000 report.md 기록. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_011h6etRXJLx1xdfxmVcHjBg
2026-07-01 14:39:06 +09:00 · 2026-07-01 14:39:06 +09:00 · 64e91e4786
parent 4d0c2caceb
commit 64e91e4786
2 changed files with 133 additions and 0 deletions
--- a/.claude/work-session/20260701-142000/report.md
+++ b/.claude/work-session/20260701-142000/report.md
@ -0,0 +1,115 @@
+---
+schema_version: 2
+sid: 20260701-142000
+started_at: 2026-07-01T14:20:00+09:00
+ended_at: 2026-07-01T14:45:00+09:00
+branch: feat/v2
+user_request: |
+  /frontend-design:frontend-design http://localhost:8080/game/new 게임 신규 등록 구간도 리디자인
+  대상자였어야 했는데 누락되었어. 다음에 누락 안되게끔 문서에 추가해두고 여기 디자인 들어가자.
+---
+
+# Summary
+
+`/game/new`(game-register.jsp)가 2026-06-30 9단위 리디자인 목록에서 빠져 있던 것을 발견·보강.
+실제 로그인 스샷 대조 결과 레이아웃/토큰은 이미 sibling(recruit-form.jsp 등)과 일치했음 —
+필수(*) 표시 2건 + 미리보기 eyebrow 라벨만 recruit-form.jsp 패턴 재사용으로 추가.
+재발방지로 `frontend-redesign-coverage-checklist.md` 신설 + `workflow-patterns.md` 등재.
+graph-refresh-checker partial-stale 판정 → full scope 증분 재생성 완료.
+
+# Invocations
+
+- [research 없음 — orchestrator 직접 grep/Read] docs/changes, docs/analysis 확인해 9단위 리디자인 대상 목록과 game-register.jsp 부재 확인
+- [orchestrator 직접] claude-in-chrome 으로 로그인 후 `/game/new`, `/recruit/new`, `/` 실사용 스샷 대조
+- [AskUserQuestion ×2] 리디자인 범위(A vs B) → B 선택 → 전제 오류 발견 후 재확인 → A안으로 확정
+- [orchestrator 직접] game-register.jsp 마크업/CSS 2건 추가 (.game-req, .game-preview__label)
+- [atp-graphify:graph-refresh-checker] 커밋 86b0528 이후 staleness 판정 → partial-stale
+- [general-purpose (graphify semantic extraction)] 11개 변경 파일 재추출
+
+# Decisions
+
+- 로컬 CSS 토큰(`--surface/--accent/--text` 등)은 bibimbap.css(`--color-*`)와 네이밍이 달라
+  대체 불가함을 확인 → 이 파일만 단독 전환하면 sibling 관례와 갈라지므로 범위 제외, 별도 과제로 이월.
+- 필수(*) 표시·미리보기 라벨은 `recruit-form.jsp`의 `.rf-req`/`.rf-preview__label` 패턴을
+  클래스명만 바꿔 재사용 — 새 디자인 언어 도입 없음.
+- WebGL zip 필수(*) 표시는 `editMode`가 아닐 때만 노출(기존 required 로직과 일치).
+
+# user_signals
+
+positive:
+  - "A안만 진행 (권장)" 선택 — 두 라운드 모두 재질의 없이 1라운드 수렴.
+negative:
+  - structural: true
+    signal: "(명시적 지적 발화는 없었으나) orchestrator가 B안 프레이밍 시 bibimbap.css 변수 네이밍을
+      실제로 grep 확인하지 않고 '공유 CSS로 전환 가능'을 전제로 옵션을 제시 → 사용자가 B안을 고른 뒤
+      실제 구현 단계에서 grep 검증 결과 전제가 틀렸음을 발견, 재질의로 정정해야 했음. 재발방지: 옵션을
+      제시하기 전에 grep/Read로 전제 사실을 먼저 확인한다."
+
+# verified_by_me
+
+- L1: `docker compose exec app mvn -o test` — 362/362 PASS
+- L1: `rg '<%@ taglib'` game-register.jsp — 0건(stray taglib 없음)
+- L2: 로그인(admin@bibimbap.local) 후 `/game/new` 라이트/다크 육안 확인 — 필수(*) 2건, 미리보기 라벨 렌더 확인
+- known pitfall 회피: JSP 저장 즉시반영 stale 렌더링 함정 — `docker compose restart app` 후 재대조
+
+# needs_user_verification
+
+- WebGL zip 실제 업로드 → 등록 제출 전체 플로우 회귀 확인 (마크업/CSS만 변경이라 로직 영향 없음으로 판단하되 실제 제출 미실행)
+- `editMode=true`(게임 수정) 경로에서 WebGL zip 라벨에 `*` 미표시 확인 (dev 시드에 기존 게임 보유 계정 부재로 미확인)
+
+# graph_refresh
+
+partial-stale → full scope 증분 재생성 완료(1477 노드 / 4503 엣지 / 76 커뮤니티, 고스트 중복 486 exact+251 fuzzy 추가 제거). `docs/graph/index.md` 갱신 커밋 `4d0c2ca`.
+
+# open_items
+
+(없음 — git status clean)
+
+# Retrospective
+
+```yaml
+Retrospective:
+  signals:
+    positive:
+      - quote_or_paraphrase: "A안만 진행 (권장)"
+        about: AskUserQuestion 두 라운드 모두 재질의 없이 1라운드 수렴 — 재확인 이후 재구성된 옵션 제시가 자기완결적이었음
+    negative:
+      - quote_or_paraphrase: "(명시적 발화 없음 — orchestrator 자가 포착) B안 프레이밍 시 bibimbap.css 변수 네이밍 전제를 grep 없이 '공유 CSS로 전환 가능'으로 제시했다가, 구현 단계 grep 검증에서 전제가 틀렸음을 발견해 재확인 라운드가 필요했음"
+        about: "AskUserQuestion 옵션(B안) 구성 시 핵심 전제(CSS 변수 네이밍 대체 가능성)를 사실 확인 없이 서술"
+        structural: true
+  what_went_well:
+    - "리디자인 대상 목록과 실제 파일 전수를 대조해 game-register.jsp 누락을 찾아낸 뒤, 재발방지용 커버리지 체크리스트(frontend-redesign-coverage-checklist.md)를 신설하고 workflow-patterns.md에 즉시 등재 — 이번 세션 안에서 교훈이 문서화까지 닫힘."
+    - "재확인 후 A안으로 좁힌 다음에는 옵션이 자기완결적이어서 1라운드 수렴(재질의 0) — agent-output-conventions.md 규칙 1(제시문 풀어쓰기)이 실제로 작동한 사례."
+    - "recruit-form.jsp 패턴을 클래스명만 바꿔 재사용해 새 디자인 언어를 도입하지 않은 보수적 선택 — sibling 관례 유지 우선."
+  what_to_improve:
+    - "AskUserQuestion 옵션(특히 '기존 인프라/토큰으로 대체 가능' 류 기술적 전제를 포함하는 옵션)을 구성하기 전에, 그 전제를 뒷받침하는 사실을 grep/Read로 먼저 확인한다. 이번 세션은 전제가 틀린 옵션(B안)을 사용자가 고른 뒤에야 구현 단계에서 오류가 드러나 재확인 왕복이 발생했다 — 결과적으로 A안으로 정정되었으나, 발견이 늦었던 것은 순전히 운(구현 착수 전 grep을 돌린 시점)이었다. 옵션에 전제가 실려 있다면 제시 전 검증이 필수다."
+  memory_candidates:
+    - name: askuserquestion-premise-verify-before-present
+      type: feedback
+      description: "AskUserQuestion 옵션에 기술적 전제(예: 기존 리소스로 대체 가능)가 실려 있으면, 옵션을 제시하기 전에 grep/Read로 그 전제를 먼저 확인한다."
+      body_draft: |
+        Why: AskUserQuestion 옵션 문구가 "A는 이렇게, B는 공유 리소스로 전환 가능"처럼 사실 주장을 포함할 때,
+        그 주장을 검증 없이 제시하면 사용자는 검증된 사실로 오인하고 선택한다. 사용자가 그 옵션을 고른 뒤
+        구현 착수 시점에야 grep 등으로 전제 오류가 발견되면, 이미 사용자 의사결정이 한 번 소비된 뒤라
+        재확인 왕복(선택 무효화 → 재질의 → 재선택)이 발생한다. 결정 제시문의 신뢰도는 문구의 매끄러움이
+        아니라 그 안의 사실 주장의 검증 여부로 결정된다.
+
+        How to apply:
+        1. 옵션 문구를 작성하기 전, 그 문구가 의존하는 사실 주장(공유 가능성, 네이밍 일치, 기존 구현 존재 등)을 나열한다.
+        2. 나열된 주장 각각을 grep/Read로 실제 확인한다 — "~일 것 같다"로 제시하지 않는다.
+        3. 확인이 안 되거나 시간이 없으면, 옵션 문구에서 그 주장을 빼거나 "미확인, 구현 착수 시 재검증 필요"로 명시한다.
+        4. 이미 틀린 전제로 옵션을 제시해 선택까지 받은 경우, 구현 착수 전 첫 검증 단계에서 걸러지도록
+           옵션 확정 직후 "선택 근거가 된 전제 재검증"을 착수 first-step으로 둔다(이번 세션처럼 늦게라도
+           구현 착수 전에 걸러지면 피해가 제한된다).
+      rationale_for_saving: >
+        agent-output-conventions.md 규칙 1(제시문 풀어쓰기)은 "어떻게 보여주는가"를 다루지만, 이번 사례는
+        "보여주기 전에 사실을 확인했는가"라는 선행 단계의 결함이라 규칙 1과는 구별되는 별개 규칙이다.
+        재현 가능(다른 프로젝트/CSS 리팩터링·API 계약 대체 가능성 등 "전환 가능" 류 전제를 포함하는
+        모든 AskUserQuestion 상황에 적용됨)하고 기존 문서에 없는 관찰이라 후보로 남긴다.
+      signal_source: negative
+      docs_sync_target: /Users/wemadeplay/workspace/stz/bibimbap/docs/development/agent-output-conventions.md
+      memory_optional: true
+  protocol_feedback:
+    - "agent-output-conventions.md 규칙 1(제시문 풀어쓰기)은 옵션의 '표현 형식'만 규율한다. 이번 사례처럼 옵션에 실린 '사실 주장'의 사전 검증 의무는 별도 규칙(예: 규칙 4)으로 명문화할 필요가 있다 — 제시문이 아무리 풀어써졌어도(규칙 1 충족) 그 안의 사실이 틀렸으면 재질의 왕복은 똑같이 발생한다. 두 결함은 독립적이므로 문서에서도 별도 항목으로 분리하는 게 재발방지에 유리하다."
+  applied_changes: []
+```
--- a/docs/development/agent-output-conventions.md
+++ b/docs/development/agent-output-conventions.md
@ -48,6 +48,24 @@ W3 골자 합의 세션(`20260617-174635`)에서 orchestrator 가 W3-1 마무리

 세션 `20260701-102212` — `AskUserQuestion` 옵션 라벨/설명에 한글을 `\u` 이스케이프로 수동 작성하다 코드포인트 오타 2회 발생. 사용자: "육각 마범롘 다이었 끝점(궁벀 불망 지겁)..." 같은 깨진 텍스트를 받고 "한글이 죄다깨져서 뭐라하는지 모르겟어 다시 질문해봐"로 지적. 리터럴 문자로 재작성하자 즉시 정상 렌더링.

+> **재발 확인** — 세션 `20260701-142000`: 동일 실수가 다시 발생, 첫 `AskUserQuestion` 호출이 `InputValidationError`(params type mismatch)로 즉시 거부됐다(다행히 사용자에게 깨진 텍스트가 전달되기 전에 스키마 단계에서 걸림). 원인은 동일 — 질문/옵션 텍스트를 타이핑하는 과정에서 글자가 오염됨. **툴 스키마 오류로 걸리지 않는 경우도 있으므로**(오타가 유효한 JSON 문자열이면 스키마는 통과하고 사용자에게 그대로 전달됨 — 첫 발원 사례가 그 경우), 스키마 통과 여부에 의존하지 말고 발신 전 자체 검토를 실제로 수행한다.
+
+## 규칙 4 — `AskUserQuestion` 옵션에 실린 기술적 전제는 제시 전에 grep/Read로 확인한다
+
+옵션 문구가 "기존 리소스로 대체 가능", "이미 동일한 패턴", "네이밍이 일치" 같은 **사실 주장**을 포함할 때, 그 주장을 검증 없이 제시하면 사용자는 검증된 사실로 오인하고 선택한다. 사용자가 그 옵션을 고른 뒤 구현 착수 시점에야 grep 등으로 전제 오류가 발견되면, 이미 사용자 의사결정이 한 번 소비된 뒤라 재확인 왕복(선택 무효화 → 재질의 → 재선택)이 발생한다.
+
+규칙 1(제시문 풀어쓰기)과는 독립된 결함이다 — 문구가 아무리 풀어써졌어도(규칙 1 충족) 그 안의 사실이 틀렸으면 재질의 왕복은 똑같이 발생한다.
+
+절차:
+
+1. 옵션 문구를 작성하기 전, 그 문구가 의존하는 사실 주장(공유 가능성, 네이밍 일치, 기존 구현 존재 등)을 나열한다.
+2. 나열된 주장 각각을 grep/Read로 실제 확인한다 — "~일 것 같다"로 제시하지 않는다.
+3. 확인이 안 되거나 시간이 없으면, 옵션 문구에서 그 주장을 빼거나 "미확인, 구현 착수 시 재검증 필요"로 명시한다.
+
+### 발원 사례
+
+세션 `20260701-142000` — game-register.jsp CSS 토큰 정리 범위를 묻는 `AskUserQuestion`에서 orchestrator가 "bibimbap.css 공유 변수로 전환 가능"을 grep 없이 전제로 제시(B안). 사용자가 B안을 선택했으나, 구현 착수 전 grep 확인 결과 `bibimbap.css`(`--color-*` 네이밍)가 game-register.jsp가 쓰는 변수(`--surface/--accent/--text` 등)를 대체하지 못함이 드러나 재확인 라운드가 필요했다. 구현 착수 전 단계에서 걸러져 실제 코드 오염은 없었으나, 발견 시점이 빨랐던 것은 우연이었다.
+
 ## 규칙 3 — 사용자 지적에 복수 대상 표현이 있으면 스코프를 임의로 좁히지 말고 대상 목록을 먼저 확인

 이미지·스크린샷을 동반한 지적에 "각 그래프", "이것들" 처럼 복수/포괄 표현이 쓰이면, 그 중 하나(가장 먼저 눈에 띄는 요소)로 스코프를 임의 축소해 확인 질문(`AskUserQuestion` 등)을 구성하지 않는다. 확인 질문 자체에 "지적 대상이 A/B/C 중 무엇인지"를 먼저 명시하거나, 최소한 확인 질문의 배경 문장에 전체 후보를 나열해 사용자가 스코프 오판을 즉시 정정할 수 있게 한다.