docs(#918): Error 표면 준수 결정문 + 세션 인계 (#921/#922 grilling 산출)

[thxforall]

요약

#918 Error page wayfinder 맵의 결정 티켓 2개(#921 경계 정책 · #922 스타일 준수)를 grilling으로 해소하고, 결정을 서면화한 docs-only PR이다. 코드 변경 0.

결정 본문은 #921/#922 코멘트에도 전문이 있지만, 발행한 6개 구현 티켓(#1055~#1060)이 결정문 파일 경로를 참조하므로 dev에 랜딩시킨다.

감사 정정 2건

맵 #918 Notes의 원본 감사(2026-07-11)에 사실 오류가 있어 코드로 재확인해 정정했다.

맵 기재	실제
"shared/ErrorState 미사용"	소비자 0의 dead export. shared/index.ts가 export하지만 import 0건. admin=AdminEmptyState, explore=CatalogEmptyState, profile=자체 EmptyState — 3계열 병존
"404 → nav 없는 헐벗은 블록"	shell 경로에서만 참. /ko/asdf는 isShellRoute=false라 레거시 SmartNav+MobileHeader가 붙음 → 현재 404가 경로에 따라 두 얼굴

추가로 decoded/[id]는 실재하지 않고(index 페이지뿐), cody/looks/[slug]는 (shell) 밖이며, 루트 app/loading.tsx가 전 라우트 폴백인데 내용은 홈 전용 스켈레톤이라는 점이 새로 드러났다.

결정을 가른 Next 16.2.1 제약

1. (shell)/error.tsx → AppShell 안에서 렌더
2. (shell)/not-found.tsx → 명시적 notFound() 호출만 잡음
3. 매칭 없는 URL의 404는 nested not-found를 건너뛰고 무조건 루트로 — in-shell 하려면 [...rest] catch-all shim이 별도 필요
4. locale prefix 없는 /asdf는 [locale] 트리 밖이라 shim으로도 못 잡음 → 완전 통일이 구조적으로 불가

결정 (D1~D9)

#921 경계 정책

• D1 shell 500 = in-shell 유지((shell)/error.tsx)
• D2 404는 엔티티 없음만 in-shell. catch-all shim 기각 — 신규 라우트를 조용히 삼킬 위험 + /asdf는 어차피 못 잡아 통일 불가
• D3 not-found는 공용 1개로 시작, 엔티티별 오버라이드는 나중
• D4 admin도 동일 패턴 — 현재 사이드바도 nav도 없는 완전 백지
• D5 shell 밖 라우트(cody·search·login…) 제외 — 레거시 nav가 이미 붙고, cody는 🗺️ [wayfinder] 백그라운드 잡 UX — TryOn+StyleDNA 장기 실행 (progress·완료·복귀·간섭제약) #919/🗺️ [wayfinder] TryOn 모바일 UX/UI — 진입·모달·카메라/갤러리·아이템노출 (QA-first) #920 재편 중

#922 스타일 준수

• D6 not-found·loading 시맨틱 토큰 마이그레이션. --primary가 이미 그 라임이라 브랜드 포기가 아니다(라이트 대비는 --primary-strong). shell.md R4가 이미 회귀로 규정. 스코프는 2파일 + 새 경계 4개까지
• D7 새 경계 4개 = shared/ErrorState·EmptyState 조합(dead export가 첫 소비자를 얻음), 루트 404는 bespoke 유지(외부 유입 착지 표면)
• D8 react-error-boundary 도입하되 dynamic() 6곳 한정. 청크 로드 실패는 error.tsx가 못 잡음. 전역 래핑 금지
• D9 루트 loading.tsx 오적용 포함

발행한 슬라이스 (전부 ready-for-agent)

#	슬라이스	Blocked by	리스크
#1055	[prefactor] shared/ErrorState·EmptyState 보강	없음	R4
#1056	(shell) 에러 경계 — 500·엔티티 404가 AppShell 유지	#1055	R1·R2
#1057	admin 에러 경계 — AdminAppShell 유지	#1055 (권장 #1056 후)	R5
#1058	루트 404 토큰 마이그레이션 (bespoke 유지)	없음	R3
#1059	루트 loading.tsx 오적용 수정 + 토큰	없음	—
#1060	lazy/dynamic 위젯 클라 ErrorBoundary	없음	—

#1056을 #1057보다 먼저 두는 이유: R1(루트 not-found.tsx 주석에 남은 "@modal parallel route + auto not-found → React.Children.only" 회귀 이력, @modal 슬롯이 양쪽 트리에 존재)이 거기서 처음 드러나며, 해소책이 필요했다면 #1057 범위가 달라진다.

미검증으로 남긴 것

#1059의 전제("루트 loading.tsx가 전 라우트 전환에 홈 스켈레톤을 띄운다")는 코드 구조에서 추론한 것이고 브라우저 재현은 하지 않았다. 정적/ISR 프리렌더(#942)에선 Suspense 폴백이 기대만큼 안 뜰 수 있다. 티켓 AC에 재현 검증을 걸어 뒀고, 재현이 안 되면 폐기가 아니라 "root loading이 홈 전용인 것 자체를 중립화"로 리프레임하도록 명시했다.

검증

코드 변경 0 → 빌드/테스트 해당 없음. 감사 사실은 전부 코드로 재확인했다: 라우트 트리 · ConditionalNav/AppShell/AdminLayout 구현 · notFound() 호출처 5곳 · shared/* import 0건 · --primary 토큰 값 · dynamic() 6곳 · react-error-boundary 미설치.

Closes #921
Closes #922
Refs #918

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
decoded-app	Ready	Preview, Comment	Jul 22, 2026 10:07am