fix(claude): fe 스킬이 문서 체계 개편으로 옮긴 문서를 가리키게 한다
frontend-quality-gates / merge / static checks (pull_request) Successful in 2m35s
frontend-quality-gates / merge / tests (pull_request) Failing after 14m34s
frontend-quality-gates / merge / browser tests (pull_request) Successful in 11m54s
frontend-quality-gates / FE-GATE-017 / diagram-review (pull_request) Skipped
frontend-quality-gates / main / checker self-tests (pull_request) Skipped
frontend-quality-gates / FE-GATE-014 / config-compatibility (pull_request) Skipped
frontend-quality-gates / FE-GATE-023 / runbook-api-degradation (pull_request) Skipped
frontend-quality-gates / FE-GATE-024 / runbook-telemetry (pull_request) Skipped
frontend-quality-gates / FE-GATE-025 / runbook-release-rollback (pull_request) Skipped
frontend-quality-gates / FE-GATE-028 / manual-accessibility-review (pull_request) Skipped
frontend-quality-gates / FE-GATE-026 / lab-performance (pull_request) Skipped
frontend-quality-gates / FE-GATE-015 / immutable-release-candidate (pull_request) Skipped
frontend-quality-gates / external-vulnerability-provider (pull_request) Skipped
frontend-quality-gates / external-provenance-provider (pull_request) Skipped
frontend-quality-gates / promote-verified-immutable-candidate (pull_request) Skipped
frontend-quality-gates / deploy-promoted-release (pull_request) Skipped
frontend-quality-gates / FE-GATE-019 / hosting-header (pull_request) Skipped
frontend-quality-gates / FE-GATE-021 / runbook-boot-config (pull_request) Skipped
frontend-quality-gates / FE-GATE-022 / runbook-chunk-mismatch (pull_request) Skipped
frontend-quality-gates / FE-GATE-018 / field-web-vitals (pull_request) Skipped

문제: #15가 결정 기록을 docs/adr/로, 설계서 넷을 docs/design/의 설계 기록으로
옮겼다. fe-* 스킬 8개가 옛 경로를 적고 있어 verify:documentation(FE-GATE-017)과
그 시험(tests/unit/documentation-readiness.test.ts, FE-GATE-005)이 실패했다.

고른 방법: 옛 경로를 옮긴 곳으로 바꿨다(VD-* → docs/adr/, design-system-platform·
frontend-platform-testing-strategy·routing-pages-and-patterns·
typescript-state-and-data-flow → docs/design/2026-07-26-*-design.md). 스킬이 인용한
절 번호는 기록에 그대로 있다. 버린 대안: 기록 머리의 「현재 정본」으로 바꾸기
(인용한 절이 정본 쪽에 없는 것이 많아 근거가 끊긴다).

위험: 설계 기록은 쓴 때의 원문이라 지금 동작과 다를 수 있다. 스킬이 그 절을
근거로 든 규칙은 검사기·시험 경로를 함께 적어 두었다.

검증: 바꾼 문서에서 백틱 경로를 검사기 방식으로 다시 뽑아 없는 경로 0개,
python3 -m unittest discover -s scripts/tests 통과, scripts/verify.sh docs rc=0.
This commit is contained in:
DongHyeonka
2026-11-12 06:56:09 +09:00
parent 5d3e0f59ae
commit 2901785436
8 changed files with 61 additions and 61 deletions
+8 -8
View File
@@ -23,23 +23,23 @@ paths:
## 함정
1. axe 통과를 접근성 완료로 적는다. e2e 스캔의 태그는 `wcag2a`·`wcag2aa`·`wcag21a`·`wcag21aa`뿐이다. WCAG 2.2에서 더해진 기준(포커스가 가려지지 않음, 목표 크기 최소, 드래그 대안 등)은 자동으로 보지 않는다. 그리고 critical·serious 위반만 막는다. — `tests/e2e/accessibility.spec.ts`, `docs/accessibility/manual-checklist.md`, `docs/styling/design-system-platform.md` 13절
1. axe 통과를 접근성 완료로 적는다. e2e 스캔의 태그는 `wcag2a`·`wcag2aa`·`wcag21a`·`wcag21aa`뿐이다. WCAG 2.2에서 더해진 기준(포커스가 가려지지 않음, 목표 크기 최소, 드래그 대안 등)은 자동으로 보지 않는다. 그리고 critical·serious 위반만 막는다. — `tests/e2e/accessibility.spec.ts`, `docs/accessibility/manual-checklist.md`, `docs/design/2026-07-26-design-system-platform-design.md` 13절
2. 자동 스캔이 본 상태를 넘겨 짐작한다. 보호 라우트는 데모 로그인 뒤, 목록은 빈 상태, 단건 읽기 상세는 실패 상태에서 스캔하고 `notChecked`로 남긴다. 데이터가 찬 목록·상세는 기능 시험과 수동 검토 몫이다. — `docs/accessibility/manual-checklist.md` 「What the automated run scans」
3. 린트가 의미를 잡아 줄 거라 믿는다. `eslint.config.ts`에 접근성 규칙 플러그인이 없다. `div` + 키 핸들러로 만든 버튼, 이름 없는 아이콘 버튼은 component 시험·axe·리뷰가 잡는다. — `eslint.config.ts`, `docs/styling/design-system-platform.md` 13절
3. 린트가 의미를 잡아 줄 거라 믿는다. `eslint.config.ts`에 접근성 규칙 플러그인이 없다. `div` + 키 핸들러로 만든 버튼, 이름 없는 아이콘 버튼은 component 시험·axe·리뷰가 잡는다. — `eslint.config.ts`, `docs/design/2026-07-26-design-system-platform-design.md` 13절
4. 저장 중 버튼을 `disabled`로 바꿔 키보드 포커스를 잃게 한다. `pending`을 쓴다. — `docs/manual/02-decision-tables.md` 6절
5. 실패·복구 전이 뒤 포커스와 안내를 잃는다. 한 전이에서만 고치고 복구 성공·확인·진행 중 전이에는 없어 버튼이 무반응으로 남았다. — `docs/work/reference/structure.md` 7절, `docs/work/reference/defect-patterns.md` C11
6. 라우트 heading의 focus outline을 CSS로 없앤다. 마우스 사용자에게 불필요한 ring을 줄일 수는 있지만 키보드 포커스 표시를 전역으로 지우지 않는다. — `docs/architecture/routing-pages-and-patterns.md` 6.3·11절
6. 라우트 heading의 focus outline을 CSS로 없앤다. 마우스 사용자에게 불필요한 ring을 줄일 수는 있지만 키보드 포커스 표시를 전역으로 지우지 않는다. — `docs/design/2026-07-26-routing-pages-and-patterns-design.md` 6.3·11절
7. 포커스 색 토큰을 `color-mix()`·알파로 만든다. 3:1 대비를 계산하지 못해 `check:design-system`이 실패한다. — `docs/styling/design-tokens.md` UI-01
8. modal의 포커스 가두기·배경 비활성·복원을 페이지마다 만든다. 공통 `Dialog`·`Drawer`·`ConfirmationDialog`를 쓴다. 닫으면 trigger나 안전한 위치로 포커스를 돌린다. — `docs/styling/design-system-platform.md` 8.2절
8. modal의 포커스 가두기·배경 비활성·복원을 페이지마다 만든다. 공통 `Dialog`·`Drawer`·`ConfirmationDialog`를 쓴다. 닫으면 trigger나 안전한 위치로 포커스를 돌린다. — `docs/design/2026-07-26-design-system-platform-design.md` 8.2절
9. 같은 변경을 여러 번 읽어 준다. live region은 필요한 변경만 한 번, 라우트 제목 발표도 중복 없이. — 같은 문서 8.1절, routing 6.3절
10. 수동 검토 기록을 not-applicable로 채운다. 폼이나 dialog가 있는 라우트는 M4·M5를 not-applicable로 둘 수 없다. 새 라우트에 pending 기록이 없으면 `verify:documentation`이 실패한다. merge 게이트는 형식만 보고, 서명은 release 게이트 FE-GATE-028이 본다. — `docs/accessibility/manual-checklist.md`
11. 상태를 색만으로 전하거나 필요한 정보를 tooltip에만 둔다. — `docs/styling/design-system-platform.md` 6.1절 10번, `docs/styling/design-tokens.md` 「Included primitives」
11. 상태를 색만으로 전하거나 필요한 정보를 tooltip에만 둔다. — `docs/design/2026-07-26-design-system-platform-design.md` 6.1절 10번, `docs/styling/design-tokens.md` 「Included primitives」
## 이 분야에서 실패는 이렇게 보인다
의미·이름
- [ ] 맞는 native element와 role을 쓴다. 행동은 `<button>`, 이동은 링크다. — `docs/styling/design-system-platform.md` 8.1절
- [ ] 맞는 native element와 role을 쓴다. 행동은 `<button>`, 이동은 링크다. — `docs/design/2026-07-26-design-system-platform-design.md` 8.1절
- [ ] 모든 조작에 보이는 레이블이나 accessible name이 있다. 아이콘만 있는 버튼은 버튼에 이름을 두고 아이콘은 장식(`aria-hidden`)이다. 정보를 전하는 아이콘은 `Icon`의 `label`을 쓴다. — 같은 문서 6.1절 7~9번
- [ ] 페이지마다 `h1` 하나와 landmark가 있다. — `tests/component/layout-landmarks.test.tsx`, `docs/accessibility/manual-checklist.md`
@@ -75,6 +75,6 @@ pnpm·브라우저는 desktop에서만 돈다(`docs/work/operate.md` 4.1절).
- `PRODUCT.md` 「Accessibility & Inclusion」 — WCAG 2.2 AA 기준, 라이트·다크 대비, 수동 검토 절차.
- `docs/accessibility/manual-checklist.md` — M1~M7과 스크린 리더, 기록 형식, 자동 스캔이 보는 범위.
- `docs/accessibility/route-reviews/` — 등록 라우트마다 기록 하나(`<ROUTE_ID>.md`).
- `docs/styling/design-system-platform.md` 8절 — 공통·overlay·form 기준.
- `docs/architecture/routing-pages-and-patterns.md` 6.3절 — 라우트 포커스와 스크롤.
- `docs/design/2026-07-26-design-system-platform-design.md` 8절 — 공통·overlay·form 기준.
- `docs/design/2026-07-26-routing-pages-and-patterns-design.md` 6.3절 — 라우트 포커스와 스크롤.
- `docs/styling/design-tokens.md` — UI-01 포커스 대비, 색만으로 전하지 않는 primitive.
+10 -10
View File
@@ -17,7 +17,7 @@ paths:
# 디자인 시스템 — 토큰만, 닫힌 API, 시각 회귀
고칠 때와 리뷰할 때 같은 목록을 쓴다. 아래 「함정」이 이 repo에서 실제로 틀린 곳이다. 흐름은 `product page → template → pattern → primitive → token`이다(`docs/styling/design-system-platform.md` 2절).
고칠 때와 리뷰할 때 같은 목록을 쓴다. 아래 「함정」이 이 repo에서 실제로 틀린 곳이다. 흐름은 `product page → template → pattern → primitive → token`이다(`docs/design/2026-07-26-design-system-platform-design.md` 2절).
## 언제 쓰나 · 넘기는 곳
@@ -30,16 +30,16 @@ paths:
## 함정
1. `check:design-system`이 통과했으니 토큰만 썼다고 본다. 날 색 검사는 `src`의 TS·TSX에서 `#hex`·`oklch(`·`rgb(`만 찾는다. `hsl()`, 색 이름(`red`), 날 px 간격은 안 본다. 토큰 파일 밖 CSS(`src/presentation/styles/**`)는 없는 토큰 참조와 혼합 색 공간만 보고 날 색은 안 본다. 기능 폴더 CSS는 아예 안 본다. 리뷰가 잡는다. — `scripts/check-design-system.ts`, `docs/styling/design-system-platform.md` 4.1절 「토큰 CSS 검사 규칙」
2. tooltip에만 필요한 정보를 둔다. 검사기의 tooltip 규칙은 음성 fixture에서만 돌고 실제 소스는 보지 않는다. — `scripts/check-design-system.ts`, `docs/styling/design-system-platform.md` 6.1절 10번
1. `check:design-system`이 통과했으니 토큰만 썼다고 본다. 날 색 검사는 `src`의 TS·TSX에서 `#hex`·`oklch(`·`rgb(`만 찾는다. `hsl()`, 색 이름(`red`), 날 px 간격은 안 본다. 토큰 파일 밖 CSS(`src/presentation/styles/**`)는 없는 토큰 참조와 혼합 색 공간만 보고 날 색은 안 본다. 기능 폴더 CSS는 아예 안 본다. 리뷰가 잡는다. — `scripts/check-design-system.ts`, `docs/design/2026-07-26-design-system-platform-design.md` 4.1절 「토큰 CSS 검사 규칙」
2. tooltip에만 필요한 정보를 둔다. 검사기의 tooltip 규칙은 음성 fixture에서만 돌고 실제 소스는 보지 않는다. — `scripts/check-design-system.ts`, `docs/design/2026-07-26-design-system-platform-design.md` 6.1절 10번
3. 포커스 대비 토큰을 `color-mix()`·알파·키워드로 만든다. 3:1 계산은 불투명한 `oklch()`로 끝나는 토큰만 하고 나머지는 실패한다. `color-mix()`는 `in oklab`만 쓴다. — `docs/styling/design-tokens.md` UI-01·UI-02
4. 다크 테마 재정의를 빠뜨리거나 light 전용 패널·글자색을 박는다. 핵심 역할 토큰은 `:root[data-theme="dark"]`에 모두 있어야 하고, `component.css`에 forced-colors 대체가 있어야 한다. — `docs/styling/design-tokens.md`, `scripts/check-design-system.ts`
5. 디자인 시스템 하위 파일, `lucide-react`, headless 라이브러리를 직접 import한다. `src/presentation/design-system/index.ts`와 vendor facade로만 들어간다. — `docs/architecture/layers.md` 규칙 `design-system-is-reached-through-its-index`·`icon-vendor-is-facade-only`, `docs/styling/design-system-platform.md` 6.1절
5. 디자인 시스템 하위 파일, `lucide-react`, headless 라이브러리를 직접 import한다. `src/presentation/design-system/index.ts`와 vendor facade로만 들어간다. — `docs/architecture/layers.md` 규칙 `design-system-is-reached-through-its-index`·`icon-vendor-is-facade-only`, `docs/design/2026-07-26-design-system-platform-design.md` 6.1절
6. 사용자 값이나 실행 중에 조립한 class 문자열을 쓰고, 같은 bracket 값을 여러 곳에 쓴다. variant는 닫힌 정적 표에서 고르고, 반복되는 bracket 값은 `@theme`로 올린다. — `docs/styling/design-tokens.md` 「Arbitrary-value policy」
7. 컴포넌트 API를 열어 둔다: 날 색 prop, vendor 타입 노출, 무제한 `as`, 범위 없는 `className`. — `docs/styling/design-system-platform.md` 11절 4단계, 13절
7. 컴포넌트 API를 열어 둔다: 날 색 prop, vendor 타입 노출, 무제한 `as`, 범위 없는 `className`. — `docs/design/2026-07-26-design-system-platform-design.md` 11절 4단계, 13절
8. primitive가 API·query·인증·저장소를 직접 부른다. pattern·template도 use case를 고르지 않고 상태와 callback을 props로 받는다. — 같은 문서 2절
9. 세 번째 사용 사례가 나오기 전에 제품 전용 조합을 primitive로 올린다. — 같은 문서 2절
10. 시각 골든을 그냥 다시 찍는다. 골든은 코드 리뷰 대상이다. Chromium 하나, Linux, 글꼴 고정(`tests/visual/fonts.conf`)이고 허용 차이는 절대 픽셀 수다. 비율 허용이 1천 px 넘는 회귀를 통과시킨 일이 있어 절대 수로 바꿨다. 실패 screenshot은 시각 회귀가 아니다. — `playwright.visual.config.ts`, `docs/styling/design-system-platform.md` 10.3절
10. 시각 골든을 그냥 다시 찍는다. 골든은 코드 리뷰 대상이다. Chromium 하나, Linux, 글꼴 고정(`tests/visual/fonts.conf`)이고 허용 차이는 절대 픽셀 수다. 비율 허용이 1천 px 넘는 회귀를 통과시킨 일이 있어 절대 수로 바꿨다. 실패 screenshot은 시각 회귀가 아니다. — `playwright.visual.config.ts`, `docs/design/2026-07-26-design-system-platform-design.md` 10.3절
11. 골든이 그리는 범위를 넘겨 짐작한다. 골든은 셸·홈·플랫폼 구성·갤러리 story만 찍고 기능 영역은 가린다. 새 primitive·상태는 갤러리 story에 넣어야 골든에 든다. — `tests/visual/platform.visual.spec.ts`, `PRODUCT.md` 「Capabilities and Constraints」
12. 디자인 시스템이 side effect를 갖거나 무거운 것을 끌어와 초기 청크에 실린다. — `docs/work/reference/defect-patterns.md` B3, `tests/unit/design-system-initial-chunk.test.ts`
@@ -49,7 +49,7 @@ paths:
- [ ] 새 값은 primitive → semantic → component 순서로 파생하고, 컴포넌트는 semantic 토큰을 읽는다. 브랜드는 토큰으로만 바꾼다. — `docs/styling/design-tokens.md`, `PRODUCT.md` 원칙 2
- [ ] 새 component 토큰은 `src/presentation/design-system/tokens/token-contract.ts`에 이름이 있고 어떤 스타일이 읽는다. — UI-03
- [ ] 첫 글꼴은 일반 키워드나 `@font-face`로 싣는 글꼴이다. 패키지로 싣는 글꼴은 `PRODUCT_LOADED_FONT_FAMILIES`에 적는다. — UI-05, `docs/styling/design-system-platform.md` 4.1절
- [ ] 첫 글꼴은 일반 키워드나 `@font-face`로 싣는 글꼴이다. 패키지로 싣는 글꼴은 `PRODUCT_LOADED_FONT_FAMILIES`에 적는다. — UI-05, `docs/design/2026-07-26-design-system-platform-design.md` 4.1절
- [ ] 아이콘 크기·stroke는 `--icon-size-*`·`--icon-stroke-*`, 색은 `currentColor`다. — 같은 문서 6.1절
컴포넌트
@@ -62,7 +62,7 @@ paths:
시각
- [ ] 화면이 바뀌면 골든 갱신이 같은 커밋에 있고 이유가 본문에 있다. 바뀌지 않아야 할 골든은 그대로다. — `PRODUCT.md`, `docs/styling/design-system-platform.md` 10.3절
- [ ] 화면이 바뀌면 골든 갱신이 같은 커밋에 있고 이유가 본문에 있다. 바뀌지 않아야 할 골든은 그대로다. — `PRODUCT.md`, `docs/design/2026-07-26-design-system-platform-design.md` 10.3절
- [ ] 라이트·다크, compact·wide 골든이 둘 다 있다. 시간·랜덤·네트워크 응답은 고정하고 동적 ID는 가린다. — 같은 절
## 검증
@@ -79,8 +79,8 @@ pnpm·브라우저는 desktop에서만 돈다(`docs/work/operate.md` 4.1절).
## 이 repo에서 정한 것
- `docs/styling/design-tokens.md` — 지금 구현된 토큰 세 층, 리브랜딩이 지킬 규칙(UI-01·02·03·05), 테마 계약, arbitrary-value 정책.
- `docs/styling/design-system-platform.md` — 소유권, 카탈로그, 아이콘 facade, headless 선택 기준, 접근성·국제화 계약, Storybook·시각 검증, 컴포넌트 추가 순서, 완료 기준, 금지 패턴. 목표 설계 부분은 수용 시험이 통과해야 구현으로 본다.
- `docs/design/2026-07-26-design-system-platform-design.md` — 소유권, 카탈로그, 아이콘 facade, headless 선택 기준, 접근성·국제화 계약, Storybook·시각 검증, 컴포넌트 추가 순서, 완료 기준, 금지 패턴. 목표 설계 부분은 수용 시험이 통과해야 구현으로 본다.
- `scripts/lib/design-system-rules.ts` — 규칙 본문과 이유.
- `src/presentation/design-system/galleries.stories.tsx` — 토큰·primitive 갤러리, 골든 대상.
- `docs/architecture/decisions/VD-05-icon-and-headless-ui.md`, `docs/architecture/decisions/VD-08-storybook-and-visual-evidence.md`.
- `docs/adr/VD-05-icon-and-headless-ui.md`, `docs/adr/VD-08-storybook-and-visual-evidence.md`.
- `PRODUCT.md` 「Product Principles」 — 브랜드는 토큰으로만, 서비스 종류별 컴포넌트 복제 금지.
+3 -3
View File
@@ -40,14 +40,14 @@ paths:
8. 조건 없이 숫자를 비교한다. 노트북 측정, 지난 측정을 대조군으로 쓰기, 표본 하나는 비교에 쓰지 않는다. — 같은 문서 3절
9. lab이 재는 범위를 넘겨 짐작한다. `/` 밖 화면의 layout shift, 스크롤바가 보이는 환경은 어느 게이트도 재지 않는다. 기능 라우트 로딩을 바꾸면 그 라우트 첫 진입을 lab과 같은 조건으로 따로 잰다(제안). — 같은 문서 6절, 결함 패턴 B2
10. Service Worker를 페이지 코드처럼 다룬다. install에서 `skipWaiting()`을 부르지 않는다. 모든 탭이 닫히거나 `requestActivation()`까지 기다린다. 캐시 이름은 자산 묶음 digest이고, 기다리는 동안 release마다 precache가 하나씩 남는다. worker는 HTML·자산과 같은 빌드에서 나온다. 지우는 데 release 셋이 든다. — `docs/operations/release-cache-rollback.md` 「Service Worker steps」
11. 청크 로드 실패에 제한 없이 `location.reload`한다. 새 manifest가 확인되고 같은 build에서 한 번만 reload한다. — `docs/architecture/routing-pages-and-patterns.md` 6.2·11절
11. 청크 로드 실패에 제한 없이 `location.reload`한다. 새 manifest가 확인되고 같은 build에서 한 번만 reload한다. — `docs/design/2026-07-26-routing-pages-and-patterns-design.md` 6.2·11절
12. 런타임 설정·release manifest를 캐시하게 둔다. `config.json`·`release-manifest.json`은 `no-store`, HTML은 `no-cache`, 해시 자산만 1년 `immutable`이다. — `config/hosting/cache-policy.json`
## 이 분야에서 실패는 이렇게 보인다
- [ ] 라우트와 context는 지연 로딩되고, 첫 화면은 그 라우트에 필요한 코드만 싣는다. — `tests/architecture/context-lazy-loading.test.ts`
- [ ] 한 화면이 같은 자원을 여러 번 부르지 않는다. 같은 query key는 중복 제거되고 라우트 unmount 때 abort된다. — `check:request-fanout`, `docs/testing/frontend-platform-testing-strategy.md` 7.1절
- [ ] 캐시된 데이터가 있으면 전체 skeleton 대신 갱신 표시를 쓴다(체감 속도와 CLS). — `docs/architecture/routing-pages-and-patterns.md` 6.1절
- [ ] 한 화면이 같은 자원을 여러 번 부르지 않는다. 같은 query key는 중복 제거되고 라우트 unmount 때 abort된다. — `check:request-fanout`, `docs/design/2026-07-26-frontend-platform-testing-strategy-design.md` 7.1절
- [ ] 캐시된 데이터가 있으면 전체 skeleton 대신 갱신 표시를 쓴다(체감 속도와 CLS). — `docs/design/2026-07-26-routing-pages-and-patterns-design.md` 6.1절
- [ ] 이미지·미디어는 크기를 지정해 layout shift를 막는다. 글꼴은 `@font-face`로 싣거나 `PRODUCT_LOADED_FONT_FAMILIES`에 적는다. — 일반 원칙, `docs/styling/design-tokens.md` UI-05
- [ ] query `measureResult`에서 `JSON.stringify`를 쓰지 않는다. — `docs/manual/01-add-a-feature.md` 7단계
- [ ] 측정값에 위치(desktop)·CPU·Node·부하·브라우저 조건·반복(5회 중앙값과 표본 전부)·커밋과 build id·같은 세션의 대조군을 붙인다. — `docs/work/reference/performance.md` 3절
+7 -7
View File
@@ -25,7 +25,7 @@ paths:
1. 로딩 화면이나 오류 화면을 보고 "통과"로 적는다. 앱 셸은 라우트 청크보다 `main`을 먼저 그린다. 라우트 자신의 `h1`이 뜬 뒤에 본다. 접근성 e2e가 기능의 빈 목록이 아니라 오류 화면을 검사하고 passed로 적은 일이 있다. — `docs/work/reference/testing.md` 3절, `tests/e2e/accessibility.spec.ts`, `docs/work/reference/defect-patterns.md` T2
2. 템플릿 원래 상태(기능 0개)에서만 본다. 기능을 하나 더하면 시각 시험이 깨진 일이 있다. `create:feature`로 기능을 만든 트리에서도 본다. 생성 기능 드릴(`test:feature-scaffold`)은 브라우저 게이트를 돌리지 않고, 브라우저 동작은 이름을 고정한 기능 하나로만 본다. 제품 기능의 브라우저 흐름은 그 기능의 시험 몫이다. — `docs/work/reference/testing.md` 3절 표, `docs/manual/reference/create-feature.md`, 결함 패턴 G2
3. 성공 경로만 본다. timeout, abort, schema mismatch, 권한, 충돌, 재시도 소진이 빠진다. — `docs/testing/frontend-platform-testing-strategy.md` 1절 7번
3. 성공 경로만 본다. timeout, abort, schema mismatch, 권한, 충돌, 재시도 소진이 빠진다. — `docs/design/2026-07-26-frontend-platform-testing-strategy-design.md` 1절 7번
4. 결과 불명 쓰기(저장 중 연결 끊김, 503)를 안 본다. `KEYED` 쓰기에서 결과 불명 화면을 빠뜨린 것은 기능 시험으로만 잡힌다. 다시 보내기는 같은 키여야 하고, `NEVER` 쓰기는 확인만 남는다. 이 repo의 High 예가 이 모양이다. — `docs/manual/01-add-a-feature.md` 8단계, `docs/manual/02-decision-tables.md` 3·4절, 결함 패턴 C2
5. 실패·복구 전이 뒤 다음 행동을 안 본다. 한 전이에서 고친 포커스·안내가 다른 전이(복구 성공, 확인, 진행 중)에는 없어 키보드 사용자가 위치를 잃거나 버튼이 무반응으로 남았다. — `docs/work/reference/structure.md` 7절, 결함 패턴 C11
6. MSW 응답을 짝 백엔드 응답으로 믿는다. 짝 백엔드는 필드 검증 거절을 400 `VALIDATION_FAILED` + `details[{field, code}]`로 보낸다. 공유 시나리오의 `validation-422`로만 보면 실제 폼이 막히는 것을 못 본다. — `docs/manual/01-add-a-feature.md` 8단계, 결함 패턴 T6
@@ -36,7 +36,7 @@ paths:
## 이 분야에서 실패는 이렇게 보인다
탐색 차터. 한 번에 흐름 하나, 30~60분이다. 일반 원칙(탐색 시험). 상태 목록은 `docs/testing/frontend-platform-testing-strategy.md` 11.2절의 시나리오 ID다.
탐색 차터. 한 번에 흐름 하나, 30~60분이다. 일반 원칙(탐색 시험). 상태 목록은 `docs/design/2026-07-26-frontend-platform-testing-strategy-design.md` 11.2절의 시나리오 ID다.
```text
목표: 누가 무엇을 하려는가 (예: 목록에서 새 항목을 만들고 상세로 간다)
@@ -49,14 +49,14 @@ paths:
흐름
- [ ] 라우트마다 `h1`이 catalog 제목과 같고, 이동 뒤 포커스가 `h1`로 간다. — `docs/accessibility/manual-checklist.md`, `docs/architecture/routing-pages-and-patterns.md` 6.3절
- [ ] 라우트마다 `h1`이 catalog 제목과 같고, 이동 뒤 포커스가 `h1`로 간다. — `docs/accessibility/manual-checklist.md`, `docs/design/2026-07-26-routing-pages-and-patterns-design.md` 6.3절
- [ ] 딥 링크·새로고침·뒤로 가기에서 같은 화면이 나오고 스크롤이 복원된다. — 같은 절, `tests/e2e/scroll-restoration.spec.ts`
- [ ] 401은 다시 보내지 않고 로그인 필요로 끝난다. 다시 로그인하면 원래 주소로 온다. — `docs/testing/frontend-platform-testing-strategy.md` 11.2절, `docs/manual/01-add-a-feature.md` 8단계
- [ ] 401은 다시 보내지 않고 로그인 필요로 끝난다. 다시 로그인하면 원래 주소로 온다. — `docs/design/2026-07-26-frontend-platform-testing-strategy-design.md` 11.2절, `docs/manual/01-add-a-feature.md` 8단계
상태
- [ ] 빈 목록은 빈 상태로, 오류는 다음 행동(다시 시도·로그인·이동)과 함께 나온다. 캐시된 데이터가 있으면 배경 오류 때문에 내용을 지우지 않는다. — `docs/architecture/routing-pages-and-patterns.md` 6.1·11절
- [ ] 폼: 제출 실패 시 첫 오류로 포커스가 간다. 저장 중 두 번 눌러도 한 번만 보낸다. 409는 입력을 남긴다. 이탈하면 확인을 묻는다. — `docs/architecture/typescript-state-and-data-flow.md` 8절
- [ ] 빈 목록은 빈 상태로, 오류는 다음 행동(다시 시도·로그인·이동)과 함께 나온다. 캐시된 데이터가 있으면 배경 오류 때문에 내용을 지우지 않는다. — `docs/design/2026-07-26-routing-pages-and-patterns-design.md` 6.1·11절
- [ ] 폼: 제출 실패 시 첫 오류로 포커스가 간다. 저장 중 두 번 눌러도 한 번만 보낸다. 409는 입력을 남긴다. 이탈하면 확인을 묻는다. — `docs/design/2026-07-26-typescript-state-and-data-flow-design.md` 8절
- [ ] 결과 불명 뒤 "확인"과 "같은 요청으로 다시 보내기"가 계약대로 그려진다. — `docs/manual/02-decision-tables.md` 3절 표
기기
@@ -85,7 +85,7 @@ pnpm·브라우저는 desktop에서만 돈다(`docs/work/operate.md` 4.1절).
## 이 repo에서 정한 것
- `docs/testing/taxonomy.md` — 시험 층과 명령, 세 엔진, 한 파일 실행.
- `docs/testing/frontend-platform-testing-strategy.md` — 위험 기반 시험 계층(3절), query·mutation 필수 시나리오(7절), 공유 MSW 시나리오 ID(11.2절). 목표 설계라 코드와 다르면 코드가 맞다.
- `docs/design/2026-07-26-frontend-platform-testing-strategy-design.md` — 위험 기반 시험 계층(3절), query·mutation 필수 시나리오(7절), 공유 MSW 시나리오 ID(11.2절). 목표 설계라 코드와 다르면 코드가 맞다.
- `docs/work/reference/testing.md` — RED 먼저, 변이, 템플릿 원래 상태 밖에서 돌리기.
- `docs/work/improve.md` 4.2절 — 결함 수정 순서(원인 → RED → GREEN → 같은 원인의 다른 자리).
- `docs/manual/01-add-a-feature.md` 10단계 — 기능 시험의 위치와 예.
+8 -8
View File
@@ -31,12 +31,12 @@ paths:
1. 결과 불명 쓰기를 무방비로 다시 보낸다. 적용됐을 수 있는 쓰기를 키 없이, 또는 새 키로 다시 보내는 입구가 남는다. 입구는 재전송 버튼, hook 재제출, 실행기 재시도, poll 재시도, 업로드 재시도다. 하나를 막으면 다른 입구에서 다시 나왔다. `NEVER` 쓰기는 결과 불명 뒤 다시 보내지 않고, `KEYED`는 같은 키로만 보낸다. — `docs/work/reference/structure.md` 6절, `docs/manual/02-decision-tables.md` 3·4절, `docs/work/reference/defect-patterns.md` C2
2. 실패를 status 하나로 분류한다. status와 code를 함께 보고, 표 밖의 값은 안전한 쪽(결과 불명)에 둔다. 짝 백엔드 쓰기 응답의 판정 표는 `src/adapters/http/backend-envelope.ts`의 `REFUSED_BEFORE_WRITE` 하나다. operation 단위 예외는 descriptor의 `commandEffect.refusedBeforeWrite`로만 선언한다. — `docs/work/reference/structure.md` 6절, 결함 패턴 C1
3. 뮤테이션 정책의 operation ID와 멱등 키 여부를 손으로 적는다. `commandMutationIdentity(<OPERATION>_CONTRACT)`로 descriptor에서 받는다. descriptor 대신 손으로 만든 객체를 넘긴 오타는 저장할 때만 드러난다. — `docs/manual/01-add-a-feature.md` 7단계
4. 서버 응답을 전역 client store에 복사하거나, URL에 있어야 할 filter·sort·page를 숨은 store에만 둔다. 서버 상태는 query cache다. 검색값의 정본은 URL이고 입력 중인 글자만 state에 둔다. — `docs/architecture/typescript-state-and-data-flow.md` 3.1절, `docs/manual/reference/patterns.md` 「URL 검색값을 바꾸는 폼」
5. presentation에서 `fetch`·저장소·auth SDK·telemetry SDK를 직접 부르거나 TanStack을 직접 import한다. 데이터는 `bindQuery` + `useApplicationQuery`·`useApplicationMutation`(`src/presentation/adapters/query/application-query.ts`)이다. — `docs/architecture/layers.md` `presentation-does-not-fetch-directly`, `docs/architecture/routing-pages-and-patterns.md` 11절
4. 서버 응답을 전역 client store에 복사하거나, URL에 있어야 할 filter·sort·page를 숨은 store에만 둔다. 서버 상태는 query cache다. 검색값의 정본은 URL이고 입력 중인 글자만 state에 둔다. — `docs/design/2026-07-26-typescript-state-and-data-flow-design.md` 3.1절, `docs/manual/reference/patterns.md` 「URL 검색값을 바꾸는 폼」
5. presentation에서 `fetch`·저장소·auth SDK·telemetry SDK를 직접 부르거나 TanStack을 직접 import한다. 데이터는 `bindQuery` + `useApplicationQuery`·`useApplicationMutation`(`src/presentation/adapters/query/application-query.ts`)이다. — `docs/architecture/layers.md` `presentation-does-not-fetch-directly`, `docs/design/2026-07-26-routing-pages-and-patterns-design.md` 11절
6. `useParams()`·`URLSearchParams` 값을 cast만 하고 쓴다. `useRouteInput` + codec으로 읽고 URL은 `buildRouteUrl`로 만든다. `/`부터 조립한 URL은 하위 경로 배포에서 앱 밖을 가리킨다. — routing 11절, `docs/manual/reference/patterns.md` 「라우트」, 결함 패턴 C7
7. `react-hooks/exhaustive-deps`를 끄거나 의존성을 빼서 effect를 "고친다". `rules-of-hooks`와 함께 lint error다. effect는 외부 시스템 동기화(구독·abort·타이머)에만 쓰고 정리 함수를 둔다. 서버 데이터를 effect + `setState`로 받지 않는다. — `eslint.config.ts` `hookRules`, 일반 원칙
8. 같은 입력을 두 번 보낸다. 쓰기 정책은 `duplicatePolicy: "REJECT_WHILE_ACTIVE"`다. `NEVER` 쓰기의 같은 입력은 훅이 `DUPLICATE_IN_FLIGHT`로 거절한다. — `docs/manual/01-add-a-feature.md` 7·8단계
9. 409를 검증 오류로 위장하거나 backend message·알 수 없는 path를 필드 문구로 쓴다. 짝 백엔드는 필드 거절을 400 `VALIDATION_FAILED` + `details[{field, code}]`로 보낸다. 받을 필드는 `useAppForm`의 `allowedServerFields`로 정한다. — `docs/architecture/typescript-state-and-data-flow.md` 8절, `docs/manual/01-add-a-feature.md` 8단계
9. 409를 검증 오류로 위장하거나 backend message·알 수 없는 path를 필드 문구로 쓴다. 짝 백엔드는 필드 거절을 400 `VALIDATION_FAILED` + `details[{field, code}]`로 보낸다. 받을 필드는 `useAppForm`의 `allowedServerFields`로 정한다. — `docs/design/2026-07-26-typescript-state-and-data-flow-design.md` 8절, `docs/manual/01-add-a-feature.md` 8단계
10. 오류 경계의 custom fallback이 retry·reset을 잃거나, 라우트를 옮겨도 오류 화면에 머문다. `location.key`나 route ID가 바뀌면 reset한다. 청크 로드 실패는 `ChunkRecoveryBoundary`가 같은 build에서 한 번만 reload한다. 제한 없는 `location.reload`는 금지다. — routing 6.2·11절, `src/presentation/boundaries/chunk-recovery-boundary.tsx`
11. Suspense 노출이 늦는 것을 잊는다. 라우트는 `React.lazy`이고 React 19는 Suspense 노출을 실제 300ms 타이머로 붙잡는다. 시험은 고정 대기 대신 `findBy*`·`waitFor`를 쓴다. — `tests/setup.ts`
12. 브라우저 저장소·파일 API(`localStorage`, `indexedDB`, `navigator.storage`, `URL.createObjectURL` 등)를 기능·presentation에서 직접 쓴다. adapter 소유이고 lint가 별칭 우회까지 막는다. — `eslint.config.ts` `restrictedBrowserDataProperties`
@@ -45,13 +45,13 @@ paths:
상태
- [ ] 상태 소유자를 표대로 골랐다: 한 컴포넌트 → `useState`·`useReducer`, 공유·복원 → URL codec, 서버 → query, 입력 중 → `useAppForm`, 저빈도 공통 → Context·`useSyncExternalStore`, 새로고침 뒤 → `StoragePort`. — `docs/architecture/typescript-state-and-data-flow.md` 3.1절
- [ ] 상태 소유자를 표대로 골랐다: 한 컴포넌트 → `useState`·`useReducer`, 공유·복원 → URL codec, 서버 → query, 입력 중 → `useAppForm`, 저빈도 공통 → Context·`useSyncExternalStore`, 새로고침 뒤 → `StoragePort`. — `docs/design/2026-07-26-typescript-state-and-data-flow-design.md` 3.1절
- [ ] 파생할 수 있는 값을 state에 복사하지 않고 렌더 중에 계산한다. 컴포넌트 안 modal 상태를 전역으로 올리지 않는다. — 일반 원칙, 같은 절
데이터
- [ ] query마다 namespace·profile·무효화 topic이 있다. topic은 복사하지 않고 새로 만든다. `measureResult`에서 `JSON.stringify`를 쓰지 않는다. — `docs/manual/01-add-a-feature.md` 7단계
- [ ] 쓰기 성공 뒤 맞는 namespace만 무효화한다. 낙관적 갱신(`optimistic`)은 실패 rollback과 함께다. — `docs/testing/frontend-platform-testing-strategy.md` 7.2절
- [ ] 쓰기 성공 뒤 맞는 namespace만 무효화한다. 낙관적 갱신(`optimistic`)은 실패 rollback과 함께다. — `docs/design/2026-07-26-frontend-platform-testing-strategy-design.md` 7.2절
- [ ] 라우트 이동 때 진행 중 query는 취소하고, mutation은 취소가 안전할 때만 취소한다. abort를 terminal error나 telemetry 실패로 세지 않는다. — routing 6.4절, strategy 7.1절
- [ ] 실패에서 화면 행동은 `AppFailure.action`(`reauth`·`navigate`·`retry`·`reload-once`)으로 정한다. — `docs/manual/01-add-a-feature.md` 8단계
- [ ] 공유 어휘·결과·실패 타입은 `src/contracts/result.ts`·`src/contracts/errors.ts`의 닫힌 어휘를 쓴다. — `docs/manual/reference/patterns.md` 「API와 검증」
@@ -81,10 +81,10 @@ pnpm·브라우저는 desktop에서만 돈다(`docs/work/operate.md` 4.1절).
## 이 repo에서 정한 것
- `docs/architecture/typescript-state-and-data-flow.md` — 상태 소유 표, 표준 데이터 호출 경로, HTTP timeout·취소·재시도, 인증, 오류 표면, 폼 표준.
- `docs/architecture/routing-pages-and-patterns.md` — route 계약과 codec, guard, navigation lifecycle, page controller, 금지 패턴.
- `docs/design/2026-07-26-typescript-state-and-data-flow-design.md` — 상태 소유 표, 표준 데이터 호출 경로, HTTP timeout·취소·재시도, 인증, 오류 표면, 폼 표준.
- `docs/design/2026-07-26-routing-pages-and-patterns-design.md` — route 계약과 codec, guard, navigation lifecycle, page controller, 금지 패턴.
- `docs/manual/02-decision-tables.md` 3·4절 — 재시도 의미(`KEYED`·`IDEMPOTENT`·`NEVER`)와 결과 불명.
- `docs/manual/reference/patterns.md` — 패턴마다 정의 파일과 예제 위치. 예제가 없으면 「없음」.
- `docs/architecture/backend-api-and-server-state-contract.md` 4.1·6·6.1절과 `config/contracts/backend-contract-pin.json` — 짝 백엔드 계약과 기준 커밋. 짝 백엔드 repo는 읽기만 한다.
- `docs/architecture/decisions/VD-03-react-router-data-mode.md`, `docs/architecture/decisions/VD-04-native-form-facade.md`, `docs/architecture/decisions/VD-25-server-state-cache-lifecycle.md`.
- `docs/adr/VD-03-react-router-data-mode.md`, `docs/adr/VD-04-native-form-facade.md`, `docs/adr/VD-25-server-state-cache-lifecycle.md`.
- `docs/manual/reference/errors.md` — 생성·조립 실패 메시지와 고칠 파일.
+6 -6
View File
@@ -37,11 +37,11 @@ paths:
1. HTML을 그대로 넣는다. `dangerouslySetInnerHTML`, `eval`·`new Function`, `javascript:` URL, `document.createElement("script")`는 lint가 막는다(`eslint.config.ts` `commonSecurityRules`). `innerHTML`·`outerHTML` 대입, `insertAdjacentHTML`, `iframe`의 `srcdoc`, 사용자 값으로 만든 `href`는 lint 규칙에 없다. 리뷰가 잡는다. 신뢰할 수 없는 내용은 `SafeText`(텍스트 노드)로 그린다. — `docs/security/browser-boundary.md`, `src/presentation/security/safe-text.tsx`
2. CSP를 깨는 코드를 넣는다. CSP는 `unsafe-inline`·`unsafe-eval` 없이 `script-src 'self'`·`style-src 'self'`다. `zod`를 직접 import하면 첫 object 스키마의 `Function("")` 탐침이 매 부팅 CSP 위반을 낸다. `z`는 `src/contracts/zod.ts`(jitless)에서 가져온다. — `docs/security/browser-boundary.md`, `config/hosting/security-headers.json`
3. `connect-src`를 믿는다. 지금 `connect-src 'self' https:`라 script가 어느 HTTPS origin에나 닿는다. 좁히려면 배포마다 헤더를 만드는 생성기가 필요하고 아직 없다. 선택 기능(recipe)을 켜면 CSP 추가가 필요하다. — `docs/security/browser-boundary.md`, `docs/architecture/optional-adapter-recipes.md` 4절 9번
4. token을 `localStorage`·`sessionStorage`·일반 store에 둔다. 기본 뼈대에는 token manager가 없다. credential은 외부 auth owner(SDK 메모리 또는 HttpOnly cookie)가 갖고, UI는 credential을 읽지 않는다. — `docs/architecture/typescript-state-and-data-flow.md` 3.1·6절
4. token을 `localStorage`·`sessionStorage`·일반 store에 둔다. 기본 뼈대에는 token manager가 없다. credential은 외부 auth owner(SDK 메모리 또는 HttpOnly cookie)가 갖고, UI는 credential을 읽지 않는다. — `docs/design/2026-07-26-typescript-state-and-data-flow-design.md` 3.1·6절
5. auth owner가 돌려준 헤더를 그대로 붙이는 새 경로를 만든다. 허용된 자격 증명 헤더 이름만, 빈 값·CR/LF·8 KiB 초과는 거절한다. — `src/adapters/auth/external-session-adapter.ts` `validateCredentialPatch`
6. 401 뒤 자동으로 다시 보낸다. V3 실행기는 401을 `UNAUTHENTICATED`로 끝내고 재전송하지 않는다. 복구 루프를 만들지 않는다. — `src/adapters/http/http-execution-v3.ts`, `docs/testing/frontend-platform-testing-strategy.md` 11.2절
6. 401 뒤 자동으로 다시 보낸다. V3 실행기는 401을 `UNAUTHENTICATED`로 끝내고 재전송하지 않는다. 복구 루프를 만들지 않는다. — `src/adapters/http/http-execution-v3.ts`, `docs/design/2026-07-26-frontend-platform-testing-strategy-design.md` 11.2절
7. 라우트 guard나 클라이언트 검증을 권한 검사로 믿는다. UX 힌트일 뿐이고 인가·검증은 백엔드가 한다. — `docs/security/browser-boundary.md`
8. 오류 원문·stack·token·URL query·개인 정보를 화면 문구, 일반 로그, telemetry에 싣는다. 진단 reason은 이 repo가 가진 닫힌 목록이고 서버 code는 `AppFailure.code`에만 남는다. — `docs/architecture/typescript-state-and-data-flow.md` 7.2절, `docs/work/reference/structure.md` 7절
8. 오류 원문·stack·token·URL query·개인 정보를 화면 문구, 일반 로그, telemetry에 싣는다. 진단 reason은 이 repo가 가진 닫힌 목록이고 서버 code는 `AppFailure.code`에만 남는다. — `docs/design/2026-07-26-typescript-state-and-data-flow-design.md` 7.2절, `docs/work/reference/structure.md` 7절
9. 비밀 같은 값을 런타임 설정이나 빌드 변수에 넣는다. 번들과 `config.json`은 누구나 읽는다. — `docs/security/browser-boundary.md`, `config/security/secret-scan-policy.json`
10. 공개 source map을 배포한다. `check:browser-security`가 `dist`의 `.map`을 거절한다. — `scripts/check-browser-security.ts`, `config/hosting/cache-policy.json`
11. desktop에서 `scripts/verify.sh gate FE-GATE-013`만 돌리고 보안 검사가 돌았다고 적는다. 첫 명령 `test:system`이 호스트 제약으로 실패하면 `ci:gate`가 거기서 멈춰 `check:browser-security`까지 가지 않는다. `parts`로 끝까지 돌린다. — `docs/work/reference/gates.md` 3절, `docs/work/operate.md` 4.1절
@@ -52,10 +52,10 @@ paths:
- [ ] 사용자·서버가 준 문자열은 React 텍스트로만 그린다. URL로 쓰면 scheme(`http:`·`https:`)과 origin을 확인한다. 로그인 뒤 돌아갈 주소는 같은 origin의 경로만 받는다. — 일반 원칙(XSS, open redirect)
- [ ] 새 창 링크(`target="_blank"`)는 `rel="noopener noreferrer"`다. — 일반 원칙
- [ ] cookie session이면 CSRF 정책과 `credentials`를 정했다. OIDC면 PKCE이고 token은 SDK 메모리에 있다. — `docs/architecture/typescript-state-and-data-flow.md` 6절, `recipes/session-owners/cookie-session-owner.ts`, `recipes/session-owners/oidc-pkce-session-owner.ts`
- [ ] cookie session이면 CSRF 정책과 `credentials`를 정했다. OIDC면 PKCE이고 token은 SDK 메모리에 있다. — `docs/design/2026-07-26-typescript-state-and-data-flow-design.md` 6절, `recipes/session-owners/cookie-session-owner.ts`, `recipes/session-owners/oidc-pkce-session-owner.ts`
- [ ] 짝 백엔드 인증 모드(JWT·Keycloak, Redis session)에 맞는 세션 owner다. — `docs/manual/04-paired-backend-session.md`
- [ ] `postMessage`·BroadcastChannel 수신은 origin과 메시지 모양을 검사한다. — 일반 원칙
- [ ] MSW worker·mock selector·가짜 credential이 production 번들에 없다. 런타임 설정에 `MOCK_MODE` 같은 키를 더하지 않는다. — `docs/testing/frontend-platform-testing-strategy.md` 1절 11번, 11.4절
- [ ] MSW worker·mock selector·가짜 credential이 production 번들에 없다. 런타임 설정에 `MOCK_MODE` 같은 키를 더하지 않는다. — `docs/design/2026-07-26-frontend-platform-testing-strategy-design.md` 1절 11번, 11.4절
- [ ] 의존성을 더하면 license·integrity·기준선 diff·번들 증가를 함께 본다. 설치 스크립트는 돌지 않는다(`--ignore-scripts`). — `docs/security/supply-chain.md`
- [ ] 보안 헤더 선언과 실제 응답을 비교한다. — `docs/security/browser-boundary.md`, `config/hosting/security-headers.json`
@@ -76,6 +76,6 @@ pnpm·브라우저는 desktop에서만 돈다(`docs/work/operate.md` 4.1절).
- `docs/security/browser-boundary.md` — 금지 기본값, CSP와 zod jitless, `connect-src`의 한계, guard는 UX 힌트.
- `docs/security/supply-chain.md` — lockfile·SBOM·secret scan·기준선, 산출물마다 증명하는 것과 못 하는 것.
- `config/hosting/security-headers.json` — 선언한 헤더.
- `docs/architecture/typescript-state-and-data-flow.md` 6절 — 인증 profile과 token 소유.
- `docs/design/2026-07-26-typescript-state-and-data-flow-design.md` 6절 — 인증 profile과 token 소유.
- `docs/manual/04-paired-backend-session.md` — 짝 백엔드 인증 모드별 세션 owner 붙이기.
- `config/security/` — 의존성 정책·기준선·취약점 정책과 예외·secret scan 정책.
+4 -4
View File
@@ -29,7 +29,7 @@ paths:
2. 단언이 대상에 닿지 않는다. fixture가 비어 첫 줄에서 return하거나, 로딩·오류 화면이나 fixture 자신을 검사한다. — 같은 절, 결함 패턴 T2
3. 시간·속도에 기댄다. React 19는 Suspense 노출을 실제 300ms 타이머로 붙잡고, MSW와 user-event는 실제 시계를 쓴다. 공통 대기 기한은 `tests/setup.ts` 한 곳이다. 시험마다 timeout을 늘리지 않는다. — `tests/setup.ts`, 결함 패턴 T3
4. 브라우저의 추정에 기대거나 그리는 중인 화면을 누른다. WebKit의 preload 경고는 곧 쓰일 preload로 가끔 실패했고, 렌더 중 12px 밀린 버튼은 클릭이 닿지 않았다. 확인하려는 사실을 직접 보고, 시험이 붙이는 조작 요소는 고정 층에 둔다. "다 그려질 때까지 기다리기"는 신호가 없어 쓰지 않는다. — `docs/work/reference/testing.md` 5절, 결함 패턴 T4·T5
5. `fetch`나 HTTP client를 `vi.fn()`으로 바꾼다. 네트워크 경계는 MSW로 본다. 시나리오는 `createHttpScenarioHandler(<계약>, { scenario })`로 받고 catalog(`tests/mocks/scenarios/catalog.ts`)를 고치지 않는다. — `docs/testing/frontend-platform-testing-strategy.md` 11·19절
5. `fetch`나 HTTP client를 `vi.fn()`으로 바꾼다. 네트워크 경계는 MSW로 본다. 시나리오는 `createHttpScenarioHandler(<계약>, { scenario })`로 받고 catalog(`tests/mocks/scenarios/catalog.ts`)를 고치지 않는다. — `docs/design/2026-07-26-frontend-platform-testing-strategy-design.md` 11·19절
6. 시험 대역이 실제와 다르다. 메모리 IndexedDB, fake, 백엔드 문서에서 옮긴 MSW 응답이 결함을 숨겼다. 짝 백엔드의 400 `VALIDATION_FAILED`를 공유 `validation-422`로 대신하지 않는다. — 결함 패턴 T6, `docs/manual/01-add-a-feature.md` 8단계
7. 플랫폼 시험을 샘플·스타터 화면·매뉴얼 예시 이름에 묶는다. 시험 전용 라우트와 `tests/mocks/`의 플랫폼 catalog를 쓰고, 탐침 이름은 `typecheck-probe-*`다. 지워도 되는 문서(`docs/reviews/` 등)를 읽으면 제거 드릴이 깨진다. — `docs/work/reference/testing.md` 2절, 결함 패턴 T7, `tests/unit/deletable-history-documents.test.ts`
8. 한 파일을 `pnpm exec vitest run <file>`로 돌린다. `src/.generated/`를 안 만들어 import 오류가 난다. `pnpm test:unit -- <file>`은 범위를 좁히지 않는다. `node scripts/run-vitest.ts run <file>`을 쓴다. — `docs/testing/taxonomy.md`
@@ -41,13 +41,13 @@ paths:
## 이 분야에서 실패는 이렇게 보인다
- [ ] 층은 필요한 실행 환경으로 골랐다: Node만 `tests/unit`, 소비자 계약 `tests/contract`, React·hook `tests/component`, HTTP/MSW·IndexedDB·조립된 경계 `tests/integration`, 실제 브라우저 `tests/e2e` 등, 한 기능 `tests/features/<id>/`. — `docs/testing/taxonomy.md`
- [ ] query 시험마다 새 `QueryClient`를 만들고 retry를 시험이 정한다. helper는 production factory를 부르고 시간·retry만 덮는다. — `docs/testing/frontend-platform-testing-strategy.md` 7.1·7.3절
- [ ] query 시험마다 새 `QueryClient`를 만들고 retry를 시험이 정한다. helper는 production factory를 부르고 시간·retry만 덮는다. — `docs/design/2026-07-26-frontend-platform-testing-strategy-design.md` 7.1·7.3절
- [ ] mutation 시험: 한 번만 보냄, 같은 키 유지, 맞는 namespace만 무효화, 실패 시 rollback, 409와 500 구분, 비멱등 쓰기 자동 재시도 없음. — 같은 문서 7.2절
- [ ] 실패 경로를 시나리오 ID로 덮는다(timeout, aborted, schema-mismatch, 401, 403, 409, 429, 503). 기대 요청 수와 중요한 header·body를 단언하고, retry 시험은 시도 카운터를 시험 안에서 초기화한다. 처리 안 된 요청은 실패다(`onUnhandledRequest: "error"`). — 같은 문서 11.2·11.3절
- [ ] 기본값은 고정 값이고 timestamp·UUID는 seed로 만든다. fixture에 실제 개인 정보·token을 넣지 않는다. — 같은 문서 11.3절
- [ ] 객체·입력이 셋 이상이고, 기능을 더한 상태·확장 지점을 채운 상태에서도 돈다. — `docs/work/reference/testing.md` 3절
- [ ] 검사기·게이트를 시험하면 통과 fixture와 거절 fixture가 함께 있다. — `docs/testing/taxonomy.md`, `docs/work/reference/gates.md` 6·8절
- [ ] `.only`가 없다(`allowOnly: false`, `forbidOnly`). Vitest의 skip·todo는 reporter가 실패시킨다. Playwright quarantine은 owner·defect·route·만료일이 있다. 빠른 층에는 quarantine이 없다. — `docs/testing/frontend-platform-testing-strategy.md` 16.5절, `scripts/check-test-evidence.ts`
- [ ] `.only`가 없다(`allowOnly: false`, `forbidOnly`). Vitest의 skip·todo는 reporter가 실패시킨다. Playwright quarantine은 owner·defect·route·만료일이 있다. 빠른 층에는 quarantine이 없다. — `docs/design/2026-07-26-frontend-platform-testing-strategy-design.md` 16.5절, `scripts/check-test-evidence.ts`
- [ ] 대형 DOM snapshot이나 구현 class 단언으로 동작 시험을 대신하지 않는다. `any`·`@ts-ignore`·이중 cast로 타입 오류를 숨기지 않는다. — 같은 문서 19절
- [ ] MSW worker·mock selector·가짜 credential이 production 번들에 없다. — 같은 문서 1절 11번
@@ -66,7 +66,7 @@ pnpm·브라우저는 desktop에서만 돈다(`docs/work/operate.md` 4.1절).
- `docs/testing/taxonomy.md` — 층·명령·실행 환경, 한 파일 실행, 결정적 시험 프로세스.
- `docs/work/reference/testing.md` — 결함을 막는지 보는 법, 환경에 기대지 않기, 흔들리는 시험 조사 절차.
- `docs/testing/frontend-platform-testing-strategy.md` — 위험 기반 계층, query·mutation·form 시나리오, MSW catalog, flaky 정책, 금지 패턴. 목표 설계라 코드와 다르면 코드가 맞다.
- `docs/design/2026-07-26-frontend-platform-testing-strategy-design.md` — 위험 기반 계층, query·mutation·form 시나리오, MSW catalog, flaky 정책, 금지 패턴. 목표 설계라 코드와 다르면 코드가 맞다.
- `.claude/rules/tests.md` — 시험 파일을 열 때마다 지킬 것.
- `vitest.config.ts`(수집 범위, `.only` 금지, 전역 timeout), `scripts/run-vitest.ts`(runner), `tests/setup.ts`(공통 대기), `scripts/check-test-evidence.ts`(quarantine 조건), `config/testing/risk-coverage.json`(위험별 커버리지).
- 빠른 층에는 quarantine이 없다(소유자 결정 2026-11-03, `docs/work/reference/testing.md` 5절).
+15 -15
View File
@@ -27,11 +27,11 @@ paths:
1. 템플릿을 잘못 고른다. 목록과 상세를 한 페이지에 섞는다. 화면의 주된 일 하나로 고르고 라우트를 나눈다. 검사가 잡지 못한다. — `docs/manual/02-decision-tables.md` 6절
2. 저장 중 버튼을 `disabled`로 바꾼다. 꺼진 버튼은 키보드 포커스를 잃는다. `pending`을 쓴다. `FormPage`에 `feedbackId`를 넘겨야 필드 오류가 아닌 실패(결과 불명, 429)로 포커스가 간다. — 같은 절
3. 캐시된 데이터가 있는데 다시 받는 동안 전체 skeleton으로 바꾸거나, 배경 오류 때문에 내용을 지운다. — `docs/architecture/routing-pages-and-patterns.md` 6.1·11절
4. 모든 실패를 redirect나 전체 오류 화면으로 처리한다. 실패마다 표면이 다르다: 권한 없음, 없음, 검증은 오류 요약 + 필드, 충돌은 입력 유지 + 행동, 429는 다시 시도 시각. — `docs/architecture/typescript-state-and-data-flow.md` 7.2절, routing 11절
5. 서버 오류 원문(본문·stack·내부 field path·URL)이나 백엔드 message를 화면 문구로 쓴다. 알려진 field만 필드에 보이고 나머지는 폼 수준 실패다. 401·403·429·404는 `FormFailureStatus`다. — `docs/architecture/typescript-state-and-data-flow.md` 7.2·8절
6. 화면에 글자를 직접 쓰거나 문장을 문자열 덧셈으로 만든다. `lint`는 JSX 글자와 표시 속성의 literal만 잡는다. 템플릿 리터럴·삼항·객체 prop 안의 글자는 리뷰가 잡는다. ko-KR·en-US 키는 둘 다 있어야 한다. — `eslint.config.ts`의 화면 문구 규칙 주석, `docs/styling/design-system-platform.md` 13절, `docs/manual/reference/patterns.md` 「화면」
7. 한국어로만 배치를 맞춘다. 영어로 바꾸거나 긴 문구가 오면 잘리거나 넘친다. — `PRODUCT.md` 원칙 5, `docs/styling/design-system-platform.md` 12절 국제화
3. 캐시된 데이터가 있는데 다시 받는 동안 전체 skeleton으로 바꾸거나, 배경 오류 때문에 내용을 지운다. — `docs/design/2026-07-26-routing-pages-and-patterns-design.md` 6.1·11절
4. 모든 실패를 redirect나 전체 오류 화면으로 처리한다. 실패마다 표면이 다르다: 권한 없음, 없음, 검증은 오류 요약 + 필드, 충돌은 입력 유지 + 행동, 429는 다시 시도 시각. — `docs/design/2026-07-26-typescript-state-and-data-flow-design.md` 7.2절, routing 11절
5. 서버 오류 원문(본문·stack·내부 field path·URL)이나 백엔드 message를 화면 문구로 쓴다. 알려진 field만 필드에 보이고 나머지는 폼 수준 실패다. 401·403·429·404는 `FormFailureStatus`다. — `docs/design/2026-07-26-typescript-state-and-data-flow-design.md` 7.2·8절
6. 화면에 글자를 직접 쓰거나 문장을 문자열 덧셈으로 만든다. `lint`는 JSX 글자와 표시 속성의 literal만 잡는다. 템플릿 리터럴·삼항·객체 prop 안의 글자는 리뷰가 잡는다. ko-KR·en-US 키는 둘 다 있어야 한다. — `eslint.config.ts`의 화면 문구 규칙 주석, `docs/design/2026-07-26-design-system-platform-design.md` 13절, `docs/manual/reference/patterns.md` 「화면」
7. 한국어로만 배치를 맞춘다. 영어로 바꾸거나 긴 문구가 오면 잘리거나 넘친다. — `PRODUCT.md` 원칙 5, `docs/design/2026-07-26-design-system-platform-design.md` 12절 국제화
8. 결과 불명 쓰기에 확인·다시 보내기 화면이 없다. `AsyncSurface`에 코디네이터의 `state`가 아니라 손으로 만든 상태를 넘기면 다시 보내기 버튼이 그려지지 않는다. — `docs/manual/01-add-a-feature.md` 8단계
9. 서비스 종류(업무 도구·일반 서비스·랜딩)마다 컴포넌트를 복제하거나 브랜드 값을 컴포넌트에 넣는다. 밀도와 표현 폭은 토큰과 페이지 템플릿에서 조절한다. — `PRODUCT.md` 원칙 2·3
10. 실패·복구 전이 뒤 안내와 포커스를 페이지마다 복사한다. 한 전이에서만 고쳐 다른 전이에서 사용자가 위치를 잃었다. 공용 폼 hook 안에서 한다. — `docs/work/reference/structure.md` 7절, `docs/work/reference/defect-patterns.md` C11
@@ -43,28 +43,28 @@ paths:
- [ ] 라우트마다 `h1` 하나가 catalog 제목과 같고, 주요 행동 하나가 먼저 보인다. — `docs/accessibility/manual-checklist.md`, 일반 원칙
- [ ] 페이지는 `src/presentation/templates/page-templates.tsx`의 다섯 템플릿 중 하나다. 템플릿은 데이터를 가져오지 않고 props로 받는다(`page-templates-own-layout-only`). — `docs/manual/02-decision-tables.md` 6절
- [ ] 위험한 작업은 `DetailPage`의 `destructiveAction` 자리와 확인 dialog를 쓴다. — 같은 절, `docs/architecture/routing-pages-and-patterns.md` 6.4절
- [ ] 위험한 작업은 `DetailPage`의 `destructiveAction` 자리와 확인 dialog를 쓴다. — 같은 절, `docs/design/2026-07-26-routing-pages-and-patterns-design.md` 6.4절
상태
- [ ] 로딩·빈·오류·배경 갱신은 `AsyncSurface`, 로그인 필요·권한 없음·없음·점검은 `StatusPage`와 상태 화면이다. — `src/presentation/components/async-surface.tsx`, `src/presentation/components/state-surfaces.tsx`
- [ ] loading surface가 실제 내용 모양(collection·detail·form)을 따른다. reduced-motion에서 skeleton 움직임을 줄인다. — `docs/architecture/routing-pages-and-patterns.md` 6.1절
- [ ] loading surface가 실제 내용 모양(collection·detail·form)을 따른다. reduced-motion에서 skeleton 움직임을 줄인다. — `docs/design/2026-07-26-routing-pages-and-patterns-design.md` 6.1절
- [ ] 예상 못 한 오류는 안전한 일반 문구 + 지원 참조(build id와 incident id)다. — 같은 문서 6.2절
문구
- [ ] 모든 글자가 `message(key)`다. 날짜·숫자·목록은 locale formatter를 쓴다. — `docs/manual/reference/patterns.md` 「화면」, `docs/styling/design-system-platform.md` 12절
- [ ] 모든 글자가 `message(key)`다. 날짜·숫자·목록은 locale formatter를 쓴다. — `docs/manual/reference/patterns.md` 「화면」, `docs/design/2026-07-26-design-system-platform-design.md` 12절
- [ ] 버튼은 무엇을 하는지 동사로, 오류는 무엇이 틀렸고 어떻게 고치는지 쓴다. — 일반 원칙
폼
- [ ] label·설명·오류가 연결되고, 제출 실패 시 오류 요약으로 포커스가 가며, 요약 항목은 그 필드로 간다. — `docs/styling/design-system-platform.md` 8.3절
- [ ] 409를 검증 오류로 위장하지 않는다. 이탈 확인(`useDirtyNavigationGuard`)은 성공 저장 뒤 풀고 이동한다. — `docs/architecture/typescript-state-and-data-flow.md` 8절, routing 6.4절
- [ ] label·설명·오류가 연결되고, 제출 실패 시 오류 요약으로 포커스가 가며, 요약 항목은 그 필드로 간다. — `docs/design/2026-07-26-design-system-platform-design.md` 8.3절
- [ ] 409를 검증 오류로 위장하지 않는다. 이탈 확인(`useDirtyNavigationGuard`)은 성공 저장 뒤 풀고 이동한다. — `docs/design/2026-07-26-typescript-state-and-data-flow-design.md` 8절, routing 6.4절
- [ ] 자동 완성·IME·붙여넣기·비밀번호 관리자를 막지 않는다. 입력을 loading skeleton으로 덮지 않는다. — data-flow 8절
반응형
- [ ] 320px에서 양방향 스크롤이 없다. compact에서 내비게이션은 drawer다. 터치 목표는 44×44 CSS px를 목표로 한다. — `docs/styling/design-system-platform.md` 8.1절, `tests/e2e/responsive.spec.ts`
- [ ] 320px에서 양방향 스크롤이 없다. compact에서 내비게이션은 drawer다. 터치 목표는 44×44 CSS px를 목표로 한다. — `docs/design/2026-07-26-design-system-platform-design.md` 8.1절, `tests/e2e/responsive.spec.ts`
- [ ] 라이트·다크 둘 다 본다. — `tests/e2e/theme.spec.ts`
## 검증
@@ -80,8 +80,8 @@ pnpm·브라우저는 desktop에서만 돈다(`docs/work/operate.md` 4.1절).
- `PRODUCT.md` — 사용자 둘(템플릿 개발자, 파생 서비스 최종 사용자), 브랜드 중립, 원칙 다섯, WCAG 2.2 AA.
- `docs/manual/02-decision-tables.md` 6절 — 페이지 템플릿 다섯과 고르는 기준.
- `docs/architecture/routing-pages-and-patterns.md` — loading·error·포커스·스크롤·dirty form, 템플릿, 금지 패턴.
- `docs/architecture/typescript-state-and-data-flow.md` 7.2·8절 — 실패에서 화면 표면으로, 폼 표준.
- `docs/styling/design-system-platform.md` 8·9·12·13절 — 접근성·국제화 계약, 완료 기준, 금지 패턴.
- `docs/design/2026-07-26-routing-pages-and-patterns-design.md` — loading·error·포커스·스크롤·dirty form, 템플릿, 금지 패턴.
- `docs/design/2026-07-26-typescript-state-and-data-flow-design.md` 7.2·8절 — 실패에서 화면 표면으로, 폼 표준.
- `docs/design/2026-07-26-design-system-platform-design.md` 8·9·12·13절 — 접근성·국제화 계약, 완료 기준, 금지 패턴.
- `docs/manual/reference/patterns.md` 「화면」 — 템플릿·`AsyncSurface`·폼·문구의 정의 위치.
- `docs/architecture/decisions/VD-04-native-form-facade.md`(폼 엔진), `docs/architecture/decisions/VD-06-intl-typed-message-catalog.md`(문구 catalog).
- `docs/adr/VD-04-native-form-facade.md`(폼 엔진), `docs/adr/VD-06-intl-typed-message-catalog.md`(문구 catalog).