From 15023c03734f5c2078585494bb24b08a2ae0cf33 Mon Sep 17 00:00:00 2001 From: art Date: Wed, 1 Jul 2026 12:19:17 +0900 Subject: [PATCH] =?UTF-8?q?docs(dev):=20freeze=20=EA=B7=BC=EA=B1=B0?= =?UTF-8?q?=ED=99=95=EC=9D=B8=20+=20frontend-design=20fork=20=EC=9C=84?= =?UTF-8?q?=EC=9E=84=20=ED=8C=A8=ED=84=B4=EB=8F=84=20workflow-patterns=20?= =?UTF-8?q?=EB=A1=9C=20=EC=9D=B4=EC=A0=84?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit verification-strategies.md 에 남아있던 나머지 두 "작업 방식" 패턴 (freeze/동결 분류 판단절차, frontend-design 스킬 fork 위임)을 workflow-patterns.md 로 이전. index.md 목록 설명도 항목 위치에 맞게 정정. Co-Authored-By: Claude Sonnet 5 Claude-Session: https://claude.ai/code/session_011h6etRXJLx1xdfxmVcHjBg --- docs/development/index.md | 4 ++-- docs/development/verification-strategies.md | 23 --------------------- docs/development/workflow-patterns.md | 23 +++++++++++++++++++++ 3 files changed, 25 insertions(+), 25 deletions(-) diff --git a/docs/development/index.md b/docs/development/index.md index 8b22452..8945dd2 100644 --- a/docs/development/index.md +++ b/docs/development/index.md @@ -4,8 +4,8 @@ ## 목록 -- [verification-strategies.md](./verification-strategies.md) — `verification-advisor` 가 읽는 검증 전략 레지스트리 (프로젝트별 `cmd` 를 채워 사용). 설계·테스트 단계 구조적 교훈(SSR 영향맵, fixture 전수 감사, freeze 분류 근거 확인, frontend-design fork 패턴) 포함. -- [workflow-patterns.md](./workflow-patterns.md) — 검증(테스트 통과)과 무관한 **작업 진행 방식** 패턴. 사용자 합의를 눈으로 보는 산출물로 받는 법, 결정 수렴 절차 등. +- [verification-strategies.md](./verification-strategies.md) — `verification-advisor` 가 읽는 검증 전략 레지스트리 (프로젝트별 `cmd` 를 채워 사용). 설계·테스트 단계 구조적 교훈(SSR 영향맵, fixture 전수 감사, 매퍼 alias 케이스폴딩, 보안 vacuous PASS 회피) 포함. +- [workflow-patterns.md](./workflow-patterns.md) — 검증(테스트 통과)과 무관한 **작업 진행 방식** 패턴. freeze 분류 근거 확인, frontend-design fork 위임, 다중 UI 안 Artifact 시각비교→AskUserQuestion 선택 수렴 등. - [document-category-classification.md](./document-category-classification.md) — 카테고리 분류 기준 (불필요한 카테고리는 프로젝트에 맞게 정리) - [agent-output-conventions.md](./agent-output-conventions.md) — 에이전트 출력 규약. 사용자 대면 의사결정 제시문엔 압축 비적용(배경+선택지+권장 풀어쓰기), 압축은 내부 산출물 한정 - [git-workflow.md](./git-workflow.md) — 브랜치 분류(메인스트림 vs 비-메인스트림) · 비-메인스트림 브랜치 커밋 표준 승인 · push 명시 요청 한정 · Conventional Commits + `Co-Authored-By` 트레일러 규약. CLAUDE.md '작업 원칙' 커밋 정책의 정본. diff --git a/docs/development/verification-strategies.md b/docs/development/verification-strategies.md index d2c1e8f..6cb92e5 100644 --- a/docs/development/verification-strategies.md +++ b/docs/development/verification-strategies.md @@ -148,29 +148,6 @@ strategies: > 근거: W3-2 고도화 세션(20260622) — B2(본문 10자)·6축 필수 계약 도입 시 기존 fixture 8건이 미갱신되어 L1 RED. 컨트롤러는 무버그. -### 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 유지. - ### 신규 `*Test.java` 는 "(검증)" 소유태그여도 구현 산출물 design 파일 영향맵에서 신규 테스트 파일이 owner 칸에 `(검증)` 으로 표시되더라도, **테스트 작성은 implementation 단계의 산출물**이다. `verification-advisor` 는 테스트를 **실행만** 하며 Write 권한이 없다. `(검증)` 은 "검증 관련 파일"이라는 용도 라벨일 뿐 작성 주체가 아니다. implementation 단계에서 파일 영향맵의 신규 `*Test.java` 를 전수 작성해야 하며, 빠뜨리면 verification 단계에서 시나리오 AC(VP) 가 "미커버"로 떨어진다(테스트가 없으니 실행할 게 없음). diff --git a/docs/development/workflow-patterns.md b/docs/development/workflow-patterns.md index e8a18b4..c788067 100644 --- a/docs/development/workflow-patterns.md +++ b/docs/development/workflow-patterns.md @@ -2,6 +2,29 @@ `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 계획가시성 의무를 산문 대신 **눈으로 보는 산출물**로 충족하는 변형.