bibimbap/docs/development/workflow-patterns.md

# Workflow Patterns — 작업 진행 방식

`verification-strategies.md` 는 "코드가 옳은가"(L1/L2/L3 검증)를 다룬다. 이 문서는 그와 무관하게 **사람과 어떻게 합의하며 작업을 진행하는가** — 결정 수렴 절차, 산출물 제시 방식 — 를 다룬다. 재사용 가능한 것만 등재한다.

## freeze/동결 분류는 근거 문서 확인 선행

어떤 변경을 "동결 영역 해제·고위험 게이트"로 분류하기 전에, 동결 범위를 정의한 **근거 문서(ADR·roadmap·work-log)를 줄 번호까지 직접 확인**한다. 표면적 유사성("평점 집계" 등)만으로 freeze 인접 추론 금지.

절차:
1. 동결 선언 근거 문서를 실제로 열어 동결 범위 정의를 줄 번호로 확인.
2. 변경 대상 테이블/뷰/심볼이 그 범위에 **명시적으로** 포함되는지 판단.
3. 포함 확인 시만 §6 게이트 표기.

> 근거: W3-2 고도화 세션(20260622) — `game_review_stats` 집계뷰가 phantom 고위험 게이트로 오분류 → `roadmap:63/201/202` 직접 확인으로 일반 DDL 정정.

## (긍정 패턴) frontend-design 스킬 fork 위임

production-grade UI(SVG·a11y·다중 JS 인터랙션 포함)를 구현할 때, `frontend-design` 스킬을 **fork(컨텍스트 상속)로 서브에이전트에 위임**하면 스킬 호출 + 단일파일 폴리시 + 프리뷰 render-verify 를 컨텍스트 오염 없이 수행 가능하다. 검증된 패턴.

조건:
- L1 전체 GREEN 확인 후 진입.
- 단일파일 폴리시: JSP 1파일 안에서 완결(신규 파일 0).
- 가드레일 명시: 기존 JS 로직 보존 / a11y / BE API 계약 무변경 / 외부 JS 라이브러리·CDN 도입 금지.
- 산출물에 프리뷰 HTML 포함(`artifacts/`).

> 근거: W3-2 고도화 세션(20260622) — 육각형 SVG 레이더·6축 radiogroup·C1~C6 를 fork 위임으로 단일 JSP 파일 승격 + L1 43/43 GREEN 유지.

## (긍정 패턴) 다중 UI 안 Artifact 시각비교 → AskUserQuestion 선택 수렴

레이아웃·배치처럼 "여러 방식이 다 타당한" UI 결정은, 구현 전에 실제 프로젝트 CSS 토큰(색상·폰트·기존 클래스명)을 그대로 이식한 정적 Artifact(HTML)로 후보 N안을 한 화면에 나란히 렌더해 사용자가 비교하게 하고, `AskUserQuestion` 으로 확정받은 뒤에만 소스에 반영한다. `/task` §5.0 계획가시성 의무를 산문 대신 **눈으로 보는 산출물**로 충족하는 변형.

절차:
1. 실제 프로젝트 색상/폰트/컴포넌트 클래스를 `grep`/`Read` 로 확인해 Artifact 에 그대로 이식 — 가짜 톤 금지(재현 신뢰도가 선택 신뢰도를 결정).
2. 결정축이 여러 개면(예: "요약 영역" + "카드 영역") 섹션을 분리하고 각 섹션 안에서만 후보를 나열 — 축을 섞으면 조합폭발.
3. 후보에 A/B/C/D 같은 안정적 레터를 부여해 이후 `AskUserQuestion` 옵션 라벨과 1:1 대응 — 참조 혼동 방지.
4. Artifact 자체의 라디오/버튼 선택은 눈요기일 뿐 상태를 orchestrator 로 되돌리지 못한다 — 실제 확정은 반드시 `AskUserQuestion`(같은 레터 옵션)으로 받는다.
5. 확정 전 단계는 소스 변경 0건이므로 verification-advisor/L1 게이트 대상이 아니다 — §9 종료조건 미적용, 세션은 사용자 응답 대기로 열어둔 채 진행.

> 근거: 세션 20260701-113509 — game-detail.jsp 리뷰 영역(요약 그래프 vs 그래프+범례, 카드 미터바 배치 4안)을 Artifact 로 제시 → `AskUserQuestion` 1회로 즉시 확정(재작업 요청 0) → 반영 커밋 `0c8da40`.

## (긍정 패턴) 시각 디자인 결정은 텍스트 diff 대신 앱 정적경로 프리뷰로 공동 확인

CSS 위계·여백·색 같은 시각 변경은 before→after **텍스트 표**로 제시해도 사용자가 결과를 예측하기 어렵다. 실제 토큰·CSS 로 렌더한 정적 프리뷰(현재/변경안 나란히, 라이트·다크·상태별)를 만들어 **앱의 화이트리스트 정적경로**(이 프로젝트: `src/main/webapp/css/`)에 두면 `:8080/css/<preview>.html` 로 서빙되어(재시작 불요, DefaultServlet 직접 서빙) 사용자는 브라우저 새로고침으로, 에이전트는 동일 URL 스크린샷으로 **공동 확인**한다. private 파일 전송(SendUserFile)은 사용자가 텍스트로만 볼 수 있는 경우가 있어 시각 비교엔 부적합. 결정 후 프리뷰 파일은 삭제(커밋 금지). 주의: top-level 경로(`/preview.html`)는 보안필터가 302 리다이렉트하므로 화이트리스트 정적 prefix 아래 둔다.

위 "다중 UI 안 Artifact 시각비교" 패턴의 자매 변형이다 — Artifact 는 별도 호스팅 URL, 이 패턴은 **앱 자체 정적경로**를 프리뷰 서버로 재사용한다. 앱 정적경로가 화이트리스트로 이미 열려 있고 재시작 없이 서빙 가능할 때 이 변형이 더 빠르다.

> 근거: 세션 20260701-083240 — 카드 위계 변경안 A/B 를 텍스트 표로 제시하자 "어떻게 변할지 예측 어렵다" 피드백 → 앱 `/css/` 프리뷰 서빙으로 전환, 사용자가 B 를 1라운드 수락.

## 모호한 시각 결함 어휘는 단일 결정축 협소화 전 다축 스캔 선행

"비율이 떨어진다 / 가시성이 떨어진다" 같은 **모호한 시각 결함 어휘**는 결함의 위치를 한정하지 않는다. 이를 곧장 단일 결정축(예: "비율" → 카드 종횡비)으로 좁혀 `AskUserQuestion` 을 던지면, 같은 어휘가 가리키던 다른 축(레이아웃 비율·정렬·대비·표현 총량)이 옵션 공간에서 누락된다. 모호 시각 어휘 수신 시 옵션 축을 확정하기 **전에** 다축 스캔(최소 레이아웃비율·종횡비·대비가시성·타이포간격 4축)을 선행한다. 스크린샷이 있으면 관찰 1 에이전트 → 축별 병렬 평가 → 종합의 multi-axis 위임(`ui-multiaxis-eval` 패턴)이 협소화 맹점을 구조적으로 메운다. UI/UX 변경 검증은 위 "시각 디자인 결정 프리뷰 공동확인" 패턴과 함께, **라이트/다크 양 테마 × 영향 화면 전수** 육안으로 수행한다(토큰 대비·종횡비는 테마별로 다르게 발현).

> 근거: 세션 20260630-175023 — 사용자 지적 "비율/가시성" 2건을 카드 종횡비 단일 축으로 협소화 → 사용자가 "검색바도 혼자 짧다"로 레이아웃 비율 축 직접 추가. 이후 multi-axis 위임 평가(6 에이전트)가 13건 결함으로 복원, 라이트/다크 양화면 스모크로 검증.

## "전 페이지 반영" 서술은 실제 파일 전수와 대조 필요 — 리디자인 대상 체크리스트 선행

"전 페이지 리디자인" 같은 세션 요약은 **작업 당시 작성자가 열거한 목록**을 뜻할 뿐, `find`로 뽑은 실제 뷰 파일 전수와 항상 일치하지 않는다. 과거 `docs/changes/*.md` 서술만 신뢰하고 다음 세션을 시작하면, 그 목록에 없던 파일(신규 추가분·의도적 스코프 제외분 모두 포함)이 조용히 계속 빠진 채로 남는다.

절차:
1. 리디자인/시각 일관성류 작업 착수 전 `docs/development/frontend-redesign-coverage-checklist.md` 를 읽고 `find src/main/webapp/WEB-INF/views -maxdepth 1 -name "*.jsp"` 실제 파일 수와 표 행 수를 대조한다.
2. 불일치(신규 파일 미등재) 시 표를 먼저 동기화한 뒤 진행한다.
3. 신규 뷰 파일을 추가하는 세션은 같은 커밋으로 그 표에 행을 추가한다(상태 `미착수`) — 다음 리디자인 세션이 처음부터 전수 파악하지 않아도 되게 한다.

> 근거: 세션 20260701 — `game-register.jsp`(`/game/new`) 가 2026-06-30 9단위 리디자인 서술에 없어 사용자가 직접 지적할 때까지 누락 상태로 남음. 체크리스트 부재가 원인.

## needs_user_verification 은 "미완료 목록" 이 아니라 "결정 분기" 단위로 구조화

세션 종료 시 `needs_user_verification` 을 단순 잔여 작업 나열로 적으면, 다음 세션이 각 항목마다 "어떻게 할까요" 재질의로 시작한다. 대신 각 항목을 **사용자가 한 번에 고를 수 있는 결정 분기**(예: 직접 적용 / 지금 구현 / 배포 후 이월 / 추가 하드닝)로 미리 구조화하면, 다음 세션 착수 시 결정이 1라운드에 수렴하고 재질의가 0이 된다. 항목마다 "기본 가정값 + 영향 범위" 를 병기한다(§2.2 open_questions 규약과 정합).

> 근거: 세션 20260629-142115 — 직전 세션이 needs 4건을 결정 분기로 명시 → 사용자 4건 일괄 결정, 재질의 0, 모든 분기 첫 라운드 수렴.

## `needs_user_verification` 이월 시 최근 세션의 렌더 관련 known pitfall 교차 인용

`needs_user_verification` 으로 브라우저 육안 확인을 이월할 때, 변경 대상이 최근 세션에서 docs 화된 렌더링 함정과 같은 경로(JSP/정적 asset)를 공유하면 그 문서를 명시적으로 인용한다. 단순히 "브라우저에서 육안 확인" 이라고만 적으면, 다음 세션/사용자가 이미 알려진 함정(예: JSP stale 렌더링 — `local-dev-setup.md` §JSP/정적)을 다시 밟고도 브라우저 화면만 보고 오탐(false pass) 할 수 있다. 작성 규칙: 최근 work-session 3~5개 이내 docs 반영된 구조적 함정 중 렌더 경로가 겹치는 것이 있으면 `needs_user_verification` 항목에 "known pitfall: `<문서 링크>` — curl 로 서빙값 대조 선행 권고" 를 병기한다.

> 근거: 세션 20260701-100731 — game-detail.jsp 레이더 차트 데이터(6축 axis) 백필 세션. 직전 세션(20260701-093754, 4분 전 종료)이 방금 "JSP 저장 즉시반영 실패 → 브라우저가 stale 렌더링을 정상으로 오판" 함정을 `local-dev-setup.md` 에 반영했음에도, 같은 렌더 경로(JSP)를 다루는 후속 세션의 `needs_user_verification` 이 이를 인용하지 않아 재발 위험을 남김(retrospective-advisor 포착).

## 도메인/상호작용 모델은 UI taxonomy 가정 전에 근거 문서·enum 으로 접지

기능의 상호작용 모델(예: 게시판이 제작자 peer-to-peer 포럼인가 편집형 일방 발행인가)이 UI 구조(카테고리 축·CTA 노출·인터페이스 톤)를 좌우할 때, orchestrator 는 **가정하지 말고** 착수 시 (a) 관련 permission enum(`PermissionKeys.java` — 예: `POST_WRITE` 게이트 존재 = 발행 권한자 한정 = 일방 발행 신호), (b) `docs/work-log/` 의 해당 기능 골자 문서를 먼저 확인한다. 모델을 잘못 가정하면 요구분해·설계 초반이 어긋나 사용자 정정 왕복(AskUserQuestion 다회)이 발생한다. §5.0 계획 가시성 이전에 "모델 접지" 를 둔다.

> 근거: 세션 20260724 — 포스트 보드를 peer-to-peer 커뮤니티로 가정해 카테고리 축에 '피드백요청/자유'(상호작용축)를 배치했으나, 사용자 정정으로 '편집형 일방 발행'(Unity 블로그 모델)로 뒤집혀 편집 taxonomy 로 재설계(AskUserQuestion 3회 왕복). 그러나 `POST_WRITE` 게이트와 `docs/work-log/2026-06-17-w3-feature-skeletons.md`('포스터 권한자만 작성, 일반 유저 읽기만(댓글 없음)')에 이미 일방 발행 모델이 W3-3 설계 시점(2026-06-23)에 명문화돼 있어 docs-first 로 조기 포착 가능했다(documentation-advisor 도 "새 결정이 아니라 orchestrator 가정 오류의 재확인" 으로 판정).