diff --git a/docs/development/document-category-classification.md b/docs/development/document-category-classification.md index fb3c40e..5d34f75 100644 --- a/docs/development/document-category-classification.md +++ b/docs/development/document-category-classification.md @@ -65,3 +65,5 @@ - 문서 동기화만 했다면 원칙적으로 `changes/` 를 만들지 말고, 대상 기준 문서를 직접 갱신한다. - 장애 수정이 있었더라도 핵심 가치가 장애 원인과 대응 이력 보존이라면 `issues/` 를 우선하고, 필요할 때만 관련 `changes/` 를 추가한다. - ADR 에 해당하는 결정이면 `changes/` 대신 `adr/` 에 불변 레코드로 남긴다. +- **기존 문서에 append 하기 전에는 그 문서 자신의 스코프 선언과 먼저 대조한다.** 카테고리(`development/` 등)가 맞다는 것만으로 그 카테고리의 "비슷해 보이는" 기존 파일에 바로 적지 않는다. 대상 파일 맨 앞에 "이 파일은 X만 다룬다" 류의 스코프 선언이 있으면, 추가하려는 내용이 그 선언에 부합하는지 확인하고, 부합하지 않으면 새 파일(또는 스코프가 맞는 다른 기존 파일)로 분리한다. 같은 파일 안에 이미 스코프를 벗어난 선례가 있다는 사실은 정당화 근거가 되지 않는다 — 선례 자체가 과거의 같은 실수일 수 있다. + - 사례: `verification-strategies.md`("`verification-advisor` 가 읽는 단일 레지스트리 — 검증 전략만 대상")에 작업 진행 방식(사용자 의사결정 수렴 절차 등)을 "구조적 교훈"이라는 이름으로 반복 혼입 → `workflow-patterns.md` 신설 후 재분류(세션 20260701-113509 계열). index.md 의 카테고리 설명 문구가 실제 파일 스코프보다 넓게 서술돼 있으면 그 문구부터가 오분류 신호일 수 있다 — 문구를 믿기 전에 대상 파일 원문 스코프 선언을 직접 읽는다. diff --git a/docs/development/verification-strategies.md b/docs/development/verification-strategies.md index 6cb92e5..8022612 100644 --- a/docs/development/verification-strategies.md +++ b/docs/development/verification-strategies.md @@ -190,12 +190,6 @@ SSRF·zip-slip·경로 boundary·sanitize 같은 보안핵심은 verification-ad > 근거: W3-3 SSRF — 설계 concern 이 "IP핀닝 또는 connect후 peer검증" 을 열어둠 → 1차가 IP핀닝(Host override) 선택, HTTPS SNI 깨짐 + restricted-header 미검증. fix1 에서 option-b(hostname-connect)로 전환. -### needs_user_verification 은 "미완료 목록" 이 아니라 "결정 분기" 단위로 구조화 - -세션 종료 시 `needs_user_verification` 을 단순 잔여 작업 나열로 적으면, 다음 세션이 각 항목마다 "어떻게 할까요" 재질의로 시작한다. 대신 각 항목을 **사용자가 한 번에 고를 수 있는 결정 분기**(예: 직접 적용 / 지금 구현 / 배포 후 이월 / 추가 하드닝)로 미리 구조화하면, 다음 세션 착수 시 결정이 1라운드에 수렴하고 재질의가 0이 된다. 항목마다 "기본 가정값 + 영향 범위" 를 병기한다(§2.2 open_questions 규약과 정합). - -> 근거: 세션 20260629-142115 — 직전 세션이 needs 4건을 결정 분기로 명시 → 사용자 4건 일괄 결정, 재질의 0, 모든 분기 첫 라운드 수렴. - ### 런타임/환경 의존 보장은 L1(값 확인)과 L3(실반영) 레이어로 분리 설정값이 "코드에서 세팅되는가" 와 "런타임에 실제 반영되는가" 가 다른 레이어인 경우(예: `Security.setProperty("networkaddress.cache.ttl")` 는 `InetAddressCachePolicy` lazy init 경합으로 best-effort), 단위검증으로 **값 설정만** 확인하고 **실제 런타임 반영은 L3 스모크**로 분리 배정한다. best-effort 한계와 결정적 정본(예: JVM `$JAVA_HOME/conf/security/java.security`)을 코드 주석·체크리스트에 함께 명시해, "값=설정됨" 을 "동작=보장됨" 으로 오인하지 않게 한다. @@ -279,26 +273,8 @@ graphify(`/graphify src/ docs/`)는 `src/main/webapp/WEB-INF/views/*.jsp`, `src/ > 근거: 세션 20260630-160000 후속 브라우저 리뷰 — posts-empty/recruit-empty.jspf(UTF-8)가 정적 include 되며 빈상태 한글 전부 mojibake. 빌드 PASS·페이지 200이라 빌드/문자열검증으론 미포착, 브라우저에서 발견 → 각 파편에 pageEncoding 추가로 해소 (fix a4d163d). -### 모호한 시각 결함 어휘는 단일 결정축 협소화 전 다축 스캔 선행 - -"비율이 떨어진다 / 가시성이 떨어진다" 같은 **모호한 시각 결함 어휘**는 결함의 위치를 한정하지 않는다. 이를 곧장 단일 결정축(예: "비율" → 카드 종횡비)으로 좁혀 `AskUserQuestion` 을 던지면, 같은 어휘가 가리키던 다른 축(레이아웃 비율·정렬·대비·표현 총량)이 옵션 공간에서 누락된다. 모호 시각 어휘 수신 시 옵션 축을 확정하기 **전에** 다축 스캔(최소 레이아웃비율·종횡비·대비가시성·타이포간격 4축)을 선행한다. 스크린샷이 있으면 관찰 1 에이전트 → 축별 병렬 평가 → 종합의 multi-axis 위임(`ui-multiaxis-eval` 패턴)이 협소화 맹점을 구조적으로 메운다. UI/UX 변경 검증은 §291 런타임 스모크를 **라이트/다크 양 테마 × 영향 화면 전수** 육안으로 수행한다(토큰 대비·종횡비는 테마별로 다르게 발현). - -> 근거: 세션 20260630-175023 — 사용자 지적 "비율/가시성" 2건을 카드 종횡비 단일 축으로 협소화 → 사용자가 "검색바도 혼자 짧다"로 레이아웃 비율 축 직접 추가. 이후 multi-axis 위임 평가(6 에이전트)가 13건 결함으로 복원, 라이트/다크 양화면 스모크로 검증. - -### 시각 디자인 결정은 텍스트 diff 대신 앱 정적경로 프리뷰로 공동 확인 - -CSS 위계·여백·색 같은 시각 변경은 before→after **텍스트 표**로 제시해도 사용자가 결과를 예측하기 어렵다. 실제 토큰·CSS 로 렌더한 정적 프리뷰(현재/변경안 나란히, 라이트·다크·상태별)를 만들어 **앱의 화이트리스트 정적경로**(이 프로젝트: `src/main/webapp/css/`)에 두면 `:8080/css/.html` 로 서빙되어(재시작 불요, DefaultServlet 직접 서빙) 사용자는 브라우저 새로고침으로, 에이전트는 동일 URL 스크린샷으로 **공동 확인**한다. private 파일 전송(SendUserFile)은 사용자가 텍스트로만 볼 수 있는 경우가 있어 시각 비교엔 부적합. 결정 후 프리뷰 파일은 삭제(커밋 금지). 주의: top-level 경로(`/preview.html`)는 보안필터가 302 리다이렉트하므로 화이트리스트 정적 prefix 아래 둔다. - -> 근거: 세션 20260701-083240 — 카드 위계 변경안 A/B 를 텍스트 표로 제시하자 "어떻게 변할지 예측 어렵다" 피드백 → 앱 `/css/` 프리뷰 서빙으로 전환, 사용자가 B 를 1라운드 수락. - ### 정적 `.html`(DefaultServlet 서빙)도 `` 필수 — §299 의 정적파일 짝 §299 는 `.jspf` 정적 include 의 `pageEncoding` 을 다루지만, **DefaultServlet 이 서빙하는 순수 `.html`** 도 동일 mojibake 함정이 있다. Tomcat 은 정적 `.html` 에 `Content-Type: text/html`(charset 없음)만 붙이므로, 파일에 `` 가 없으면 브라우저가 Latin-1 로 추정해 UTF-8 한글이 깨진다. 앱 정적경로에 두는 프리뷰·정적 페이지는 `` 에 `` 를 반드시 포함한다. > 근거: 세션 20260701-083240 — 카드 프리뷰 정적 html 을 `/css/` 서빙했으나 meta charset 누락으로 전체 한글 mojibake, 사용자 스샷으로 표면화 → meta 추가로 즉시 해소. 변경 상세: [changes/2026-06-30-ui-multiaxis-ratio-visibility-fix.md](../changes/2026-06-30-ui-multiaxis-ratio-visibility-fix.md). - -### `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 포착). diff --git a/docs/development/workflow-patterns.md b/docs/development/workflow-patterns.md index c788067..2a55a24 100644 --- a/docs/development/workflow-patterns.md +++ b/docs/development/workflow-patterns.md @@ -37,3 +37,29 @@ production-grade UI(SVG·a11y·다중 JS 인터랙션 포함)를 구현할 때, 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/.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건 결함으로 복원, 라이트/다크 양화면 스모크로 검증. + +## 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 포착).