Files
clean-architecture-frontend…/docs/adr/VD-10-optional-capability-recipes.md
T
DongHyeonka 75fad73a7d docs(records): 기록·설계서·결정 기록 67개에 한국어 머리 블록을 단다
문제: 옮긴 기록은 지금 동작을 설명하는지, 상태가 무엇인지, 지금
정본이 어디인지 알 길이 없다. 설계서·계획서 27개와 docs/architecture
목표 설계 16개에는 상태 칸이 없고, VD는 「상태: Accepted」 같은 영어
값을 쓴다.

고른 방법: docs-system.md 4절 형식으로 맨 위에 머리 블록을 달고 본문은
한 글자도 고치지 않는다. 상태는 기계 변환이다.
- 설계서: Accepted·확정·정본·설계 완료 → 채택, 상태 줄이 없으면
  확인 안 함 (채택 4, 확인 안 함 21)
- 계획서: 체크 상자가 모두 표시됐으면 끝남, 아니면 확인 안 함. SPEC.md는
  같은 폴더 plan.md와 같은 근거(0.2.0으로 끝난 라운드)로 끝남 (끝남 5,
  확인 안 함 14. 이미 블록이 있던 5개는 그대로)
- 결정 기록: Accepted → 채택, 날짜가 붙은 뒤늦은 보완 메모가 본문에
  있으면 채택(보완) (채택 14, 채택(보완) 9). 프론트 VD는 처음부터
  한국어로 썼고 번역하지 않으므로 둘째 줄은 「원문이다」 문구다.
- 작성일: 파일 이름 날짜 → 본문 날짜 줄(VD는 `결정일:`) → git 첫 추가일.

위험: VD-09·11·13은 git으로 보면 결정 뒤 본문이 그 자리에서
고쳐졌지만 본문에 날짜 표시가 없어 기계 규칙대로 채택으로 두었다.
보완으로 올릴지는 사람이 정한다. 「현재 정본」은 지금 있는 살아 있는
문서나 코드 경로만 쓴다.

검증: 블록과 그 뒤 빈 줄 하나를 빼면 72개 모두 `git show HEAD:`와 바이트가
같다. 뒤 커밋의 문서 검사 head 규칙으로 돌려 문제 0건.
2026-11-08 17:25:41 +09:00

6.6 KiB

결정 기록 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.

  • 상태: 채택(보완)
  • 작성일: 2026-07-26
  • 요약: realtime·offline·PWA 같은 선택 기능 12개를 recipe catalog로 두고, 실제 제품 요구가 생기기 전에는 설치하지 않는다는 결정이다.
  • 현재 정본: config/recipes/frontend-capability-recipes.json, docs/architecture/optional-adapter-recipes.md

VD-10: 선택형 frontend capability recipe

  • 상태: Accepted
  • 결정일: 2026-07-26
  • 적용 브랜치: feature-frontend-optional-adapter-recipes
  • 현재 선택 capability: 없음
  • 재검토: 실제 프로젝트가 realtime, offline, PWA, file, generated API, feature flag, worker, multi-tab, browser permission, client workflow, large-data UI 또는 production analytics/error provider를 요구할 때

배경

서버의 PostgreSQL, MongoDB, Redis, Kafka, MinIO 같은 기술을 브라우저가 직접 소비하지는 않는다. 프론트의 변화 지점은 권한 있는 HTTP/BFF, push event, offline persistence, file protocol, browser runtime, 사용자 동의와 UI 성능 경계다. 이 capability를 “언젠가 필요할 수 있다”는 이유로 모두 설치하면 초기 bundle, 공급망, runtime config, 보안 표면과 업데이트 비용만 늘어난다.

반대로 문서에 이름만 적으면 실제 프로젝트에서 port 위치, cancellation, fallback, fake와 제거 기준을 다시 설계해야 한다. 따라서 production runtime에 아무것도 설치하지 않되 검증 가능한 vendor-neutral recipe를 저장소 밖이 아닌 별도 opt-in 경계에 유지한다.

결정

  1. config/recipes/frontend-capability-recipes.json이 12개 recipe의 선택 기준, 금지 조건, port/fake, failure matrix, lifecycle cleanup, owner, security/privacy, gzip budget, fallback, server-state 정책과 제거 절차의 machine-readable SSOT다.
  2. 현재 실제 소비 요구와 project owner가 없으므로 12개 상태는 모두 RECIPE_AVAILABLE이며 INSTALLED가 아니다. production runtime dependency와 composition registration은 0개다.
  3. recipes/frontend-capabilities의 TypeScript port와 fake/unavailable adapter는 실행 가능한 설계 예시다. src 또는 production entry가 이 디렉터리를 import할 수 없다.
  4. 프로젝트가 capability를 선택하면 필요한 최소 contract를 application-owned output port 또는 presentation facade로 이동하고, concrete vendor adapter는 local adapter 경계에 둔다. recipe 디렉터리를 production에서 그대로 import하지 않는다.
  5. WebSocket/SSE처럼 연결은 outbound이고 수신 event는 inbound인 양방향 기술도 한 종류의 “adapter”로 뭉개지 않는다. 연결·credential·reconnect 정책과 event validation·input invocation을 분리한다.
  6. Zustand/Redux Toolkit/state machine은 실제 cross-page client-only workflow가 확인된 경우 하나만 선택한다. URL, component state, Context, TanStack Query가 이미 소유한 상태를 복제하지 않는다.
  7. browser credential은 localStorage, URL, recipe store, telemetry 또는 BroadcastChannel에 넣지 않는다. 브라우저가 database/object store에 직접 접속하는 recipe도 금지한다.
  8. lifecycle이 있는 capability는 unsubscribe, close, unregister, dispose, cancel 또는 AbortSignal을 계약과 contract test에 포함해야 한다.
  9. 선택하지 않은 recipe sentinel이나 reference runtime source, vendor dependency가 production bundle에 들어가면 gate를 실패시킨다. referenceRuntime이 있는 recipe는 catalog sourceRoots 전체를 별도의 production-mode synthetic entry로 deterministic하게 bundle/minify하되 tree-shaking을 끄고, 모든 출력의 gzip 합계가 recipe budget을 넘으면 production composition 여부와 무관하게 실패시킨다. 2026-07-28 최초 실측에서 offline-indexeddb가 32,930 bytes였으므로 측정 없이 선언됐던 8,000 bytes를 약 9% headroom의 36,000 bytes로 교정했으며 다른 budget은 자동 인상하지 않는다.
  10. recipe 전체를 제거한 임시 worktree에서 base typecheck, architecture, unit/component/integration test와 production build가 통과해야 한다.

선택과 설치 절차

measured product/runtime need
  -> project owner + security/privacy classification
  -> recipe trigger/forbidden/fallback review
  -> VD-10 amendment with one selected capability
  -> application port or presentation facade copied into src
  -> one concrete adapter under local adapter boundary
  -> composition-only wiring
  -> contract/failure/cleanup/integration tests
  -> bundle + dependency baseline approval
  -> INSTALLED only after all evidence passes

도입 커밋에는 owner, 선택 이유, 대안, gzip 차이, runtime config, browser support, failure UX, observability, rollback과 제거 명령을 기록한다. vendor가 필요한 behavior를 fake만으로 확인하고 INSTALLED로 바꾸지 않는다.

증적

  • catalog: config/recipes/frontend-capability-recipes.json
  • contracts/fakes: recipes/frontend-capabilities
  • 상세 runbook: docs/architecture/optional-adapter-recipes.md
  • file/IndexedDB/OPFS/Cache 심층 결정: docs/architecture/decisions/VD-11-browser-file-and-origin-storage.md
  • browser data 상세 설계: docs/architecture/browser-file-and-origin-storage.md
  • realtime/Web Push/Polling 심층 설계와 결정: docs/architecture/realtime-events-web-push-and-bounded-polling.md, docs/architecture/decisions/VD-28-realtime-events-web-push-and-bounded-polling.md
  • contract test: tests/recipes/optional-capability-contracts.test.ts
  • negative fixture: tests/fixtures/optional-recipes/forbidden
  • validation: scripts/check-optional-recipes.ts
  • removal: scripts/test-optional-recipe-removal.ts
  • evidence: artifacts/quality/optional-recipes.json, artifacts/quality/optional-recipe-fixtures.json, artifacts/tests/optional-recipes.xml, artifacts/tests/optional-recipe-removal.xml

Rollback

현재 branch는 runtime dependency나 production composition을 바꾸지 않으므로 recipe catalog, example과 gate를 함께 revert하면 RP-11 상태로 돌아간다. 실제 프로젝트에서 선택한 capability는 그 capability의 port/adapter/composition/ dependency commit만 revert한다. 여러 vendor 도입을 하나의 되돌릴 수 없는 commit으로 묶지 않는다.