문제: docs/architecture의 현재 계약 문서 가운데 scale-architecture.md, starter-experience.md, capability-consumer-experience.md, contract-ownership.md, static-delivery.md, review-evidence.md는 본문이 영어이고, backend-api-and-server-state-contract.md와 optional-adapter-recipes.md에는 영어 문단이 남아 있다. 고른 방법: 뜻을 바꾸지 않고 옮긴다. 백틱 안, 링크 대상, 절 번호(코드 주석이 `scale-architecture.md §N`으로 인용한다), 표 구조, 코드 블록은 그대로 둔다. 문서를 읽는 테스트와 절 이름을 인용한 곳을 같은 변경에서 고친다. - tests/unit/feature-tracked-files.test.ts: starter-experience.md 표를 자르는 시작·끝 문장과 표 행마다 찾는 낱말(`병합 충돌`) - 「Ownership declarations」「Adding a feature」를 인용한 주석 (create-feature.ts, generate-product-feature-index.ts, app-module.ts)과 docs/manual의 절 이름 인용 - optional-adapter-recipes.md의 recipe 개수 복사를 카탈로그를 가리키게 바꾼다(number 검사) 위험: create-feature.ts 417줄은 생성하는 context-module.ts의 JSDoc이라 새로 만드는 기능의 주석 글자가 바뀐다. 그 글자를 비교하는 테스트는 없다. review-evidence.md는 산문만 옮겼고 해시·점수 칸은 그대로다. 검증: 백틱 span·링크 대상·코드 블록·번호 제목을 옮기기 전과 python으로 비교해 같다. 문서 검사의 language 줄이 이 문서들에서 0이 되어 예외 목록에서 지웠다.
7.2 KiB
capability 소비자 경험 기준선
재사용 capability 안이 올바르다는 것만으로는 부족하다. 플랫폼은 그 올바름을 쓰려고 보통의 feature 개발자가 얼마나 많이 알아야 하는지로도 평가받는다.
이 측정값은 기준선이지 점수 목표가 아니다. 줄 수가 적어도 업무 의미를 숨기거나 만능 repository 추상화를 만든다면, 저절로 더 좋은 것이 아니다.
시나리오 A — REST feature
REST 소비자는 corepack pnpm create:feature <id> --with-create가
쓰는 feature다(2026-11-07까지는 템플릿의 참조 샘플이 이 역할을 했다).
목록·상세·생성 동작, 매핑, 타입이 있는 operation 입력, application port를 다룬다.
feature가 소유한 경계 코드와 application 코드는 다음 네 파일이다.
application/<base>-feature-api.tscontracts/<base>-mapper.tsadapters/<base>-http-gateway.tsadapters/create-<base>-feature-input.ts
이 문서는 이 파일들의 줄 수를 적어 두지 않는다. 손으로 적은 줄 수가 코드와 어긋난 적이 있다(리뷰 14-07).
생성한 feature에서 이 네 파일에 wc -l을 돌려 잰다.
중요한 경계 지표는 단순 합계가 아니다. 이 파일들이 플랫폼에 대해 무엇을 알아야 하는지다.
지금 결과:
- feature adapter 계층에서 HTTP 플랫폼을 import하는 파일: 2개
- 두 파일이 쓰는 정식 import 경로:
src/adapters/http/index.ts http-execution-v3.ts, retry scheduler, 응답 reader, 인증 승인(auth admission), effect-certainty 내부 모듈을 직접 import하는 곳: 0- 전송 실패를 변환(projection)하는 일을 feature gateway가 맡는 곳: 0
- feature gateway가 operation ID, route ID, 정확한 입력·값 타입, mapper를 고르는가: 예
- 중앙 설치 파일이 feature 전용 adapter·runtime 연결을 소유하는가: 아니오. feature가 소유한 contribution을 중앙에서 모을 뿐이다.
실행 결과를 정규화하는 일은 이제 재사용 HTTP capability가
createFeatureHttpBinding으로 맡는다.
재사용 계약이 업무 요구에 맞지 않으면, feature는 여전히 자기 application port 뒤에 직접 만든 outbound adapter를 둘 수 있다.
시나리오 B — IndexedDB 로컬 초안
실행되는 소비자 탐침(probe)은 다음이다.
tests/contract/consumer-experience/indexeddb-local-draft.test.ts
이 테스트는 Local Draft 구현 하나를 실행하고 읽는다. 그 구현은 테스트 fixture
tests/fixtures/indexeddb-consumer다. 예전에 src/features/ 아래 있던 템플릿의 local-draft 샘플인데,
제품 feature가 아니라서 이리로 옮겼다.
예전에 따로 떼어 둔 복사본은 이 구현과 어긋나서 지웠다(09-12).
소비자는 Local Draft의 domain·application API를 소유한다.
그리고 repository에서 자기가 부르는 부분(slice)을 선언한다
(tests/fixtures/indexeddb-consumer/adapters/local-draft-indexeddb-store.ts의 LocalDraftRepository).
host는 indexedDb capability로 IndexedDbRepositoryPort<LocalDraft, never>를 넘겨준다.
이 port는 구조적 타입으로 그 slice를 만족한다.
capability를 가로지르는 조립 계약은 다음에 있다.
tests/contract/reusable-capability/feature-adapter-composition.test.ts
이 테스트는 HTTP만 쓰는 contribution 하나와 IndexedDB만 쓰는 Local Draft contribution을 같은 범용 카탈로그 경로로 조립한다.
브라우저 수준의 조립 증명은 다음에 있다.
tests/browser-capabilities/local-draft-composition.spec.ts
이 테스트는 브라우저의 실제 IndexedDB에서 돈다. 먼저 플랫폼의
createIndexedDbRuntime을 만들고, 타입이 있는
createIndexedDbRepositoryProvider로 그 runtime을 내놓는다. 그다음
LOCAL_DRAFT_FEATURE_ADAPTER_CONTRIBUTION을 조립하고, feature API로 Local Draft의
저장·조회·삭제를 실행한다. 그래도 Local Draft feature는 IndexedDB runtime이나 브라우저 기본 API를 import하지 않는다.
Local Draft 소비자가 아직 src/features/ 아래 있을 때 잰 값(09-12):
| 지표 | 결과 |
|---|---|
feature LOC (모든 .ts 파일) |
295 |
feature 밖으로 나가는 import 문(contracts/errors, contracts/result, application-api, feature-adapter-contribution) |
7 |
| 브라우저 기본 IndexedDB API 참조 | 0 |
src/adapters/storage/indexeddb/** import |
0 |
src/application/ports/browser-file-storage/** import |
0 |
이 feature는 storage runtime도 그 port도 import하지 않는다.
그래서 브라우저 file/storage runtime을 지워도(test:browser-file-storage-removal) 계속 컴파일된다.
계약 테스트는 다음에 손대는 feature 코드를 거부한다.
globalThis.indexedDB, IDBFactory, IDBDatabase, IDBTransaction,
IDBObjectStore, 구체 IndexedDB adapter 디렉터리, browser-file-storage port다.
이것이 증명하는 것과 증명하지 않는 것
계약 탐침은 IndexedDbRepositoryPort가 조립되고 나면
feature 업무 코드에 브라우저 기본 IndexedDB 지식이 필요 없다는 것을 확인한다.
브라우저 capability 증명은 하나를 더 확인한다.
그 port 뒤에 이 repo의 실제 createIndexedDbRuntime과 브라우저 기본 IndexedDB 구현이 있어도,
같은 feature contribution이 동작한다는 것이다.
createIndexedDbRuntime을 조립하는 비용이 싸다는 것은 증명하지 않는다.
이 생성 함수는 여전히 상당한 인프라 정책을 갖고 있다.
- dataset 범위와 저장 정책
- 물리 store 관리
- 보존·멱등성(idempotency) store
- schema 마이그레이션
- codec과 조회 정책
- 수명 주기 권한(lifecycle authority)
- 내구성, 스케줄링, 관측
이 복잡함은 feature가 아니라 조립·플랫폼 경계에 둔다.
Local Draft 세로 slice는 이제 두 번째 구체 소비자다.
이 소비자는 안정된 연결 지점(seam)이 타입이 있는 repository provider와,
feature가 소유한 repository 식별자라는 것을 확인한다.
dataset 범위, 보존, 마이그레이션, codec, 수명 주기 권한 설정을 만능
create...Repository<T> factory 하나로 안전하게 합칠 수 있다는 것은 보여 주지 않는다.
그래서 편의 프로필은 IndexedDB를 쓰는 다른 제품 feature가 같은 인프라 정책을 되풀이한 뒤에만 들인다. 두 feature가 같은 repository port를 쓴다는 이유만으로 들이지 않는다.
소비자 품질 검토 체크리스트
새 제품 feature마다 다음을 기록한다.
- feature가 소유한 adapter LOC
- 플랫폼 연결 코드(glue) LOC
- 바뀐 파일
- 중앙 카탈로그 수정
- capability 내부 모듈 직접 import
- 브라우저·네트워크 기본 API 참조
- 중복된 실패·retry·수명 주기 정책
건강한 feature 경로는 다음 모양이다.
- domain 타입과 불변식
- use case
- 업무 port
- feature가 소유한 mapper·codec과 정책
- capability 전용 binding
- presentation controller·페이지
feature는 다음을 알 필요가 없어야 한다. retry scheduler, abort 소유, effect-certainty 장치, IndexedDB transaction 수명 주기, OPFS journal, 재연결 coordinator, provider 프로세스 모델이다.