Files
clean-architecture-frontend…/docs/manual/03-outside-feature-folder.md
T
donghyeon.kang 79dc945a67 refactor(layout): 루트 경로 목록을 등록부 하나에서 고르고 schemas/를 옮긴다
루트 항목 하나를 옮기려면 코드 7곳의 루트 경로 목록을 같이 고쳐야
했다(복사 대상, 비밀값 검사 범위, 공급망 시험의 필수 입력, 이력 문서
검사, 규모 입력, vite 입력, TS 전용 규칙). 서로 다른 부분집합이고 한
곳에서 선언하지 않았다. 목록이 갈라져 공급망 생성이 깨진 적도 있다
(removal-fixture.ts 주석). 루트에는 JSON Schema 5개만 담은 `schemas/`가
`config/` 옆에 따로 있었다. `artifacts/`(출력 폴더)에는 사람이 쓴 수동
a11y 기록이, `config/hosting/`(호스트 계약)에는 시험 fixture가 섞였다.

고른 방법(design-docs repo-structure/04-frontend-layout.md 9.2절 3단계,
11절 R1·R2, 소유자 승인 2026-11-07):
- `config/repository-layout.json`이 루트 항목마다 종류·역할·읽는 곳과
  들어가는 목록(`sets`, 항목 안 경로는 `setPaths`)을 적는다.
  `scripts/lib/repository-layout.ts`가 읽고 검증한다. 6곳은 이름 붙은
  집합을 고른다. JSON인 비밀값 검사 정책은 집합의 사본을 두고 시험이
  같은지 본다(정책 파일은 릴리스 후보에 실려 형식을 바꾸지 않았다).
  공급망 시험의 필수 입력 목록은 그 시험으로 대신한다.
- `tests/unit/repository-layout.test.ts`: 등록부에 없는 루트 항목이
  추적되면 실패(R1). 7곳이 등록부 모듈을 쓰고 루트 이름 둘 이상의
  문자열 배열을 갖지 않는지(R2).
- `schemas/artifacts/` → `config/schemas/artifacts/`, recipe 카탈로그
  스키마 → `config/schemas/recipes/`. 정책 입력 순서(ASCII)에 맞춰
  `config/schemas/`가 `config/security/` 앞에 온다.
- 수동 a11y 기록 3개 → `docs/accessibility/route-reviews/`. `artifacts/`는
  `.gitkeep`만 추적한다. 기록은 단위 시험이 읽어서 drill 사본에도
  복사한다(`fixture-copy` 집합의 `docs/accessibility/route-reviews`).
- `config/hosting/response-headers.fixture.json` →
  `tests/fixtures/hosting/response-headers.json`.

버린 것: 비밀값 검사 정책이 집합 이름을 참조하게 바꾸는 방법. 정책
파일은 릴리스 후보와 로컬 증거 평가가 읽는 형식이라 바꾸면 릴리스
증거 계약이 바뀐다. 루트 항목이 지워졌는데 등록부에 남는 경우는
시험하지 않았다. drill 사본은 일부만 복사해 그 방향을 볼 수 없다.
그런 항목은 그 집합을 쓰는 곳(복사, 비밀값 검사)에서 실패한다.

위험: 하네스 작업(fe-c)이 더할 `AGENTS.md`·`.claude/`를 미리 등록했다
(optional). 등록부가 이력 문서(`SPEC.md`)와 `CLAUDE.md` 이름을 적어서
이력 문서 검사에서 등록부 파일은 뺐다. 다운스트림은 자기 루트 항목을
등록부에 더해야 한다(CHANGELOG). CI 계약 기준선을 다시 받았다(a11y
기록 산출물 id·경로).

검증(desktop): 아래 4단계 커밋까지 쌓은 트리에서 test:unit,
check:types, check:ci, lint, verify:documentation을 돌렸다(그 커밋에
적음). 이 커밋 단독으로 test:unit·check:ci·check:types를 돌렸다.

Refs: design-docs repo-structure/04-frontend-layout.md 2.4·9.2·11절, README.md 3.4절
2026-11-08 17:41:07 +09:00

16 KiB

03. 기능 폴더 밖 파일

핵심: 기능 하나에 필요한 파일은 거의 모두 src/features/<id>/와 tests/features/<id>/ 안에 있다. 폴더 밖 파일은 네 묶음으로 나뉜다.

기능 폴더 밖 파일
  ├─ A. 생성 명령이 만든다          → 사람은 확인만
  ├─ B. 사람이 꼭 해야 한다         → a11y 서명, 자리표시자 교체
  ├─ C. 조건이 맞을 때만 사람이 고친다 → 레이아웃, 새 capability, 제품 인증 프로필 등
  └─ D. 고치지 않는다               → 중앙 카탈로그, governance, 공유 mock 등

정본 표: 파일마다 "언제 고치나"와 "안 고치면 무엇이 실패하나"는 docs/architecture/starter-experience.md의 "Adding a feature" 절 표(File | When | What fails without it)가 정본이다. 이 문서는 그 표를 복사하지 않는다. 그 표에 없는 것만 더한다. 누가 하는지, 왜 폴더 밖인지, 사람이 하는 절차.

링크: starter-experience.md "Adding a feature"


A. 생성 명령이 만든다

corepack pnpm create:feature가 새로 만드는 폴더 밖 파일은 둘이다. 있는 파일은 덮어쓰지 않는다. 이미 있는 추적 파일 중 다시 쓰는 것은 아래 "기능마다 바뀌는 템플릿 추적 파일"에 있다.

  • src/contexts/<context>/context-module.ts
    • 새 context일 때만 만든다. --context를 주면 만들지 않는다.
    • 왜 밖인가: context는 여러 기능이 함께 쓰는 소속 선언이다. 기능 하나가 갖지 않는다.
  • docs/accessibility/route-reviews/<ROUTE_ID>.md
    • 라우트마다 하나. Status: pending-manual-review로 만든다.
    • 왜 밖인가: 수동 접근성 검토 기록은 라우트 단위로 한 폴더에 모은다. 릴리스 검토자가 한 곳에서 서명한다.
    • pending 기록은 merge 게이트를 통과하고 릴리스 게이트를 넘지 못한다(원칙 7).

src/.generated/도 기능 폴더 밖이다. 생성기가 매번 다시 만든다. 손으로 고치지 않는다.

기능마다 바뀌는 템플릿 추적 파일 (1105/16-01)

새 파일 말고도, 기능 하나를 더하면 이미 있는 추적 파일 두 개가 바뀐다. 둘 다 명령이 쓰고, 기능과 같은 커밋에 넣는다.

파일 누가 쓰나 다시 쓰는 명령 안 넣으면
public/release-manifest.json (dev server의 manifest) create:feature가 생성 뒤 바로 쓴다. 설치된 계약 패키지 목록(packages)과 그 다이제스트(setDigest) node scripts/write-dev-release-manifest.ts test:unit(tests/unit/dev-release-manifest.test.ts)이 다시 쓰는 명령을 말하며 실패한다. dev server가 CONTRACT_SET_PACKAGE_MISSING으로 부팅하지 못한다
config/scale/feature-shape-ceilings.json의 initialJavascript (초기 JS 기록) 사람이 명령으로 쓴다. 기능을 더하거나 뺄 때마다 바뀐다 node scripts/scale/measure-feature-shape-growth.ts --initial-baseline --write test:unit이 빌드와 대조해 실패한다
  • 브랜치 둘이 충돌한다. setDigest는 설치된 패키지 전체의 해시 한 줄이고, initialJavascript는 빌드 전체의 합계다. 기능을 하나씩 더한 두 브랜치는 같은 줄을 다른 값으로 바꾼다. 둘째 브랜치를 합칠 때 텍스트 충돌이 난다.
  • 충돌하면 손으로 값을 합치지 않는다. 아무 쪽이나 고른 뒤 위 명령을 다시 돌려 그 결과를 커밋한다. 두 기능이 다 들어간 상태의 값이 나온다. 손으로 합친 값이 틀리면 test:unit이 같은 명령을 말하며 실패한다.
  • 레지스트리 기준선(config/contracts/registry-baseline.json)은 기능을 더하기만 하면 바뀌지 않는다(아래 C).

B. 사람이 꼭 해야 한다

수동 접근성 검토 서명

create:feature가 pending 기록을 만든다
  → merge: 형식만 본다 (review:a11y-manual -- --format-only, FE-GATE-009)
  → 릴리스 후보가 나온다
  → 사람이 그 후보로 라우트를 검토하고 기록에 서명한다
  → release: 서명을 본다 (review:a11y-manual, FE-GATE-028)

할 일:

  1. 릴리스 후보 하나를 띄운다.
  2. docs/accessibility/manual-checklist.md의 M1~M7과 스크린 리더 항목을 그 라우트에서 확인한다.
  3. docs/accessibility/route-reviews/<ROUTE_ID>.md를 채운다.
    • Status: reviewed, Release ID, Reviewer, Reviewed at, Signature, Attestation: accepted
    • 항목마다 pass 또는 not-applicable (<구체적 이유>)
  4. 모든 라우트 기록의 Release ID가 같아야 한다.

안 하면: FE-GATE-028이 Manual accessibility evidence is incomplete:로 릴리스를 막는다.

생성 명령이 서명까지 하지 않는 이유: 자동으로 "검토함"을 쓰면 서명이 아무 뜻이 없어진다(원칙 7).

자리표시자 계약 신원 교체

패키지 인자 없이 만든 기능은 자리표시자 신원을 쓴다. staging·production에 내보내기 전에 바꾼다.

백엔드가 @org-contracts/<service> 패키지를 배포한다
  → 패키지를 제품 의존성으로 더한다
  → 의존성 변경 증거를 적는다
  → 기능 계약의 신원 네 필드를 바꾼다
  → 계약 기여가 패키지의 descriptor를 쓰게 바꾼다
  → 승인 검사로 확인한다

할 일:

  1. 패키지를 production 의존성으로 더한다. package.json과 lockfile이 바뀐다.
  2. config/security/dependency-change-evidence.json에 add:<name>@<version> 항목을 더한다(owner, reviewer, reason, rollback).
    • 안 하면: generate:supply-chain(check:bundle, FE-GATE-012 안에서 돈다)이 high-risk dependency missing review: add:<name>@<version>로 실패한다.
  3. src/features/<id>/contracts/<base>-feature-contract.ts의 <BASE>_CONTRACT_PACKAGE에서 네 필드를 함께 바꾼다.
    • packageId, version(정확한 SemVer), digest(sha256: + 소문자 hex 64자리), sourceRevision(hex 7~64자리)
    • 자리표시자 상수 import를 지운다.
  4. src/features/<id>/contracts/<base>-contract-contribution.ts가 로컬 descriptor 대신 패키지의 descriptor를 쓰게 바꾼다.
    • @org-contracts/* import는 이 파일에서만 된다(external-contract-package-single-import-path).
  5. 공개 대상으로 승인 검사를 돌린다.
    • APP_PROFILE=staging으로 빌드한 뒤 APP_PROFILE=staging RELEASE_TARGET=staging corepack pnpm check:release-admission(FE-GATE-027)을 돌린다.
    • 검사는 빌드 결과 dist/config.json을 읽는다. 빌드 변수는 루트 README.md의 "Runtime configuration" 절에 있다.

안 하면: FE-GATE-027이 거절한다.

release admission refused for staging:
  contractPackages.@org-contracts/<service>: pins the placeholder identity create:feature writes; pin the published package's version, digest and revision

생성 명령이 실제 신원을 만들지 않는 이유: 어느 백엔드 버전과 맞춰 빌드했는지는 사람이 정해야 한다(원칙 2).


C. 조건이 맞을 때만 사람이 고친다

언제와 실패 메시지는 정본 표에 있다. 여기에는 무엇을 위해 고치는지만 적는다.

  • src/contexts/<context>/context-layout.tsx: context가 AppShell 대신 자기 틀을 쓸 때. 예제: tests/helpers/fixture-layout-product.tsx.
  • tests/e2e/accessibility.spec.ts: 기능마다 고치지 않는다. 경로 파라미터와 API 응답을 설치된 라우트·descriptor에서 만든다. 보호 페이지가 설치된 GET이 아닌 요청을 그리기 전에 보낼 때만 손본다. 자세한 동작은 01 문서 6단계.
  • src/features/product-capabilities.ts: needs에 템플릿이 만들지 않는 capability를 적었을 때. 그 capability의 타입을 ProductFeaturePlatformCapabilities에 적는다.
    • product-composition.ts 안에서 FeaturePlatformCapabilities를 보강(declare module)하면 check:types:node가 그 키를 보지 못한다.
  • src/bootstrap/product-composition.ts: 위 capability의 값을 돌려줄 때. 제품 인증 프로필의 자격 증명도 여기서 준다.
    • 로그아웃·계정 전환 때 닫아야 하는 것(파일 runtime 등)은 scopeParticipants로 돌려준다. 예제: recipes/frontend-capabilities/browser-file-session-capability.ts.
      • label은 browser-files 같은 소문자 kebab-case 토큰으로 쓴다. 다른 형식이면 조립이 TypeError로 멈춘다.
      • close가 던지면 scope가 FAILED에 머물고 모든 서버 요청이 SCOPE_FENCED로 막힌다. 진단 cache.operation.failed에 reason: PARTICIPANT_FAILED와 scope_participant: <label>이 남으니 그 기록으로 원인 closer를 찾는다.
    • 템플릿 파일 src/bootstrap/runtime-adapters.ts는 고치지 않는다.
    • 실시간 갱신: 짝 백엔드의 실시간 출구(STOMP·NDJSON)와 프론트 realtime 어댑터(SSE·realtime.v1 WebSocket)는 그대로 연결되지 않는다. 지금 되는 경로는 bounded polling이다. 대응표: realtime 설계 0.1절.
  • src/contracts/product-contracts.ts: 제품 인증 프로필이나 제품 런타임 설정 키가 필요할 때.
    • 템플릿 파일 src/contracts/rest-profiles.ts는 고치지 않는다.
    • 설정 키 이름에 TOKEN·COOKIE·SECRET·PASSWORD 같은 조각(src/contracts/env.ts의 FORBIDDEN_CONFIG_NAME_FRAGMENTS, 대소문자 무관)을 넣지 않는다. 부팅이 CONFIG_SECRET_NAME_REJECTED로 멈추고, 오류 화면의 "잘못된 설정 키"에 그 키 이름(값은 아님. 중첩 키는 CAPABILITY_OVERRIDES.AUTH_TOKEN처럼 경로)이 나온다. test:unit의 env-registry-coverage가 먼저 Forbidden client configuration key: <키>로 실패한다.
    • FE-REG-ENV 행의 required·defaultValue는 zod 필드가 키가 없을 때 하는 것과 같게 적는다. 기본값이 없으면 defaultValue: null이다. 같은 테스트가 대조한다.
  • config/runtime/<profile>.json: 환경별로 기능을 끄고 싶을 때(FEATURE_OVERRIDES).
  • src/features/product-capabilities.ts의 선택 런타임(PRODUCT_RUNTIME_CAPABILITY_SELECTION): Service Worker를 켤 때. 아래 "SW 켜기"를 본다.
  • config/ci/product-gates.json: 배포 job(deployment)을 채우거나 제품 전용 merge 검사(PRODUCT-GATE-NNN)를 더할 때. 템플릿 파일 config/ci/gates.json은 고치지 않는다. 형식은 ci-quality-gates.md에 있다.
  • package.json, lockfile, config/security/dependency-change-evidence.json: 계약 패키지를 더할 때(B절).

정본 표에 없는 것:

  • config/contracts/registry-baseline.json과 승인 파일: 레지스트리 행을 빼거나 바꿀 때만. 더하기만 하면 고치지 않는다. 절차는 01 문서 9단계.
  • config/testing/risk-coverage.json의 criticalModules: 기능 파일에 따로 커버리지 하한을 걸고 싶을 때(선택). 제거 드릴이 기능 폴더를 가리키는 행을 지운다.
  • tests/e2e/<spec>.spec.ts: 기능 전용 브라우저 테스트가 필요할 때. Playwright는 tests/e2e만 읽어서 기능 폴더 안에 둘 수 없다.

왜 이것들이 기능 폴더 밖인가: 제품 전체가 하나만 갖는 파일이다. 템플릿은 이 자리를 제품 소유로 비워 두었다. 템플릿을 동기화해도 제품의 내용과 충돌하지 않는다.

SW 켜기

Service Worker는 기본으로 꺼져 있다. 켜는 것은 제품 소유 파일 하나만 고치는 일이다.

src/features/product-capabilities.ts (SERVICE_WORKER = ACTIVE)
  → src/features/installed-runtime-capabilities.ts (템플릿: 검사하고 그대로 투영)
  → scripts/build-frontend.ts (worker 빌드를 한 번 더 돈다)
  → createOptionalRuntimeHost (부팅 때 worker를 등록한다)
  1. src/features/product-capabilities.ts의 SERVICE_WORKER를 바꾼다.

    const SERVICE_WORKER: InstalledServiceWorkerSelection | null = {
      mode: "ACTIVE",
      scriptPath: "service-worker.js",
      handlers: ["PWA_STATIC_ASSETS"],
    };
    
  2. corepack pnpm build로 dist/service-worker.js가 생기는지 본다.

  3. 운영에서 끄려면 런타임 설정 CAPABILITY_OVERRIDES.SERVICE_WORKER를 쓴다. 런타임 설정은 끄기만 한다. 켜는 것은 이 파일뿐이다.

  4. 지우려면 한 번에 null로 가지 않는다. REMOVE_REGISTRATION → PURGE_OWNED_RESOURCES → null 순서로 릴리스한다. 이미 설치된 브라우저의 worker를 먼저 내려야 한다.

  • 고치지 않는다: src/features/installed-runtime-capabilities.ts(템플릿 소유, D절).

  • 저장하지 않은 편집이 있는 탭의 활성화 거절(blockers)과 page controller의 observe는 제품 소유 src/bootstrap/product-composition.ts에서 잇는다. composeProduct가 serviceWorker를 돌려주면 템플릿 조립이 그대로 넘긴다(1103/09-05). observe가 던져도 worker 흐름은 바뀌지 않는다.

    export function composeProduct(context: ProductCompositionContext) {
      return {
        capabilities: {},
        credentialProviders: {},
        serviceWorker: {
          blockers: [() => hasUnsavedEdits()],
          observe: (observation) => reportServiceWorker(observation),
        },
      } satisfies ProductComposition;
    }
    
  • 템플릿이 아직 연결하지 않은 것: 활성화 화면(onUpdateWaiting·requestActivation()). 확인할 것 목록은 docs/architecture/optional-adapter-recipes.md의 "Service Worker를 켤 때 확인할 것"에 있다.

  • realtime·Web Worker·오프라인 명령을 고르면 조립이 Selected optional capabilities have no runtime to start them로 거절한다. 템플릿 조립에 아직 그 런타임이 없다.


D. 고치지 않는다

기능을 더할 때 아래는 고치지 않는다. 고쳐야 할 것 같으면 무언가 잘못 고른 것이다.

  • src/features/installed-*.ts (중앙 카탈로그): 기능 폴더를 glob으로 읽는다.
  • config/contracts/registry-governance.json: 라우트의 스키마·로딩 화면 값을 허용 목록으로 갖지 않는다.
  • config/contracts/registry-baseline.json: 더하기만 하는 변경은 additive다.
  • README.md, docs/accessibility/manual-checklist.md: route ID 목록을 갖지 않는다. 라우트별 기록 파일이 검사 대상이다.
  • tests/mocks/ 아래 공유 파일: 기능 테스트는 createHttpScenarioHandler에 기능 계약을 넘긴다. 공유 시나리오 카탈로그는 바뀌지 않는다.
  • src/bootstrap/runtime-adapters.ts, src/contracts/rest-profiles.ts: 템플릿 소유. 제품은 C절의 제품 소유 파일을 쓴다.

기능을 지울 때

corepack pnpm test:sample-removal -- --feature=<id>는 복사본에서 지워 보고 게이트를 돈다. 실제 저장소에서 지울 때는 아래를 함께 지운다.

  • src/features/<id>/, tests/features/<id>/
  • 그 context의 마지막 기능이면 src/contexts/<context>/
  • docs/accessibility/route-reviews/<ROUTE_ID>.md (라우트마다)
    • 남아도 검사는 실패하지 않는다. 검사는 등록된 라우트의 기록만 읽는다. 그래서 잊기 쉽다.
  • 기능 전용 tests/e2e/ spec
  • config/runtime/<profile>.json의 FEATURE_OVERRIDES 키
  • config/testing/risk-coverage.json에서 그 기능을 가리키는 행
  • 그 기능만 쓰던 제품 capability, 제품 인증 프로필, 계약 패키지 의존성

그다음 dev manifest(public/release-manifest.json)의 계약 패키지를 node scripts/write-dev-release-manifest.ts로 다시 쓰고, 초기 JS 기록(config/scale/feature-shape-ceilings.json)도 node scripts/scale/measure-feature-shape-growth.ts --initial-baseline --write로 다시 쓴다(위 A의 표). 그리고 레지스트리 기준선을 다시 찍는다. 행을 빼는 것은 breaking 변경이다.

REGISTRY_BASELINE_OWNER=<담당> REGISTRY_BASELINE_REASON="<id> removed" corepack pnpm update:registry-baseline