Files
clean-architecture-frontend…/docs/manual/03-outside-feature-folder.md
T
donghyeon.kang e902e657d1 test(layout): 저장소 배치 규칙 R3~R9를 검사로 두고 매뉴얼에 적는다
소유자가 2026-11-07에 지적한 것(매뉴얼이 생긴 뒤에도 남은 샘플, 역할이
겹치는 루트 폴더, 0파일 검사, 문서 속 인프라 설정)은 매뉴얼과 리뷰가
먼저 잡아야 했다. 지금은 그 규칙이 글로도 검사로도 없다. 그래서 같은
지적이 다시 나와도 게이트가 모른다.

고른 방법(design-docs repo-structure/04-frontend-layout.md 11절, 기계
검사가 「예」인 규칙을 표의 게이트 칸대로):
- R4·R5 `tests/unit/example-feature-rules.test.ts`(FE-GATE-005): 샘플
  목록은 FE-GATE-020의 `test:sample-removal`(인자 없이, 빌드와 test:all
  포함)이 증명한다. 목록 샘플의 기능 ID·라우트가 visual·e2e의 `goto`,
  gates.json 산출물 경로, `config/scale/`에 나오면 실패한다. 템플릿
  목록은 비어 있어 가짜 샘플로 판정 함수를 시험한다.
- R6·R7(문서) `verify:documentation`(FE-GATE-017): `docs/manual/`이 목록
  샘플 경로를 가리키면, 현재 문서에 ```nginx```·```hcl``` 블록이나
  `kind: Deployment` 같은 매니페스트 줄이 있으면 실패한다. 이력 폴더는
  보지 않는다. 산출물 `documentation-review.json`에
  `layoutRuleViolations`를 더했다.
- R7(파일)·R9 `tests/unit/repository-layout.test.ts`(FE-GATE-005):
  nginx·Terraform·Helm·Kustomize 파일과 Kubernetes 매니페스트 YAML이
  추적되면 실패. 옵션이 같은 tsconfig 쌍이 있으면 실패.
- R3은 `tests/unit/tracked-artifacts.test.ts`, R8은 앞 커밋의
  `check-typecheck-inputs.ts`·`check-type-fixtures.ts`가 맡는다. R10의
  기계 몫(루트 *.md 등록)은 R1이다.
- 매뉴얼 03에 E절(R1~R10 규칙과 검사, 루트 항목을 더하는 순서)과 C절
  「Web Worker를 들일 때 tsconfig 더하기」(결정 D4)를 더했다.

위험: R5는 문자열 검색이라 샘플 ID를 다르게 쓴 대상(예: 라우트 경로를
조립하는 spec)은 놓친다. R7 문서 검사는 코드 블록 언어 태그와 매니페스트
줄로만 본다. R13(리뷰 가이드)은 design-docs 몫이라 넣지 않았다.

검증(desktop): 이 커밋에서 test:unit, check:types, check:ci, lint,
verify:documentation, check:architecture를 돌렸다.

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

22 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로 거절한다. 템플릿 조립에 아직 그 런타임이 없다.

Web Worker를 들일 때 tsconfig 더하기

템플릿에는 Web Worker 코드가 없다. 그래서 Worker용 tsconfig도 없다. 빈 tsconfig는 0파일을 검사하고 통과한다(아래 E절 R8). 2026-11-08에 지웠다. Worker 코드를 처음 넣는 변경에서 아래를 함께 한다.

  1. Worker 코드를 src/adapters/web-worker/에 둔다. 그 폴더의 index.ts가 배럴이다.

  2. 루트에 tsconfig.web-worker.json을 만든다. lib가 WebWorker이고 DOM이 없어서, Worker 코드가 document·window를 쓰면 실패한다. tsconfig.service-worker.json과 같은 이유다.

    {
      "extends": "./tsconfig.base.json",
      "compilerOptions": { "lib": ["ES2022", "WebWorker"], "types": [], "skipLibCheck": false },
      "include": ["src/adapters/web-worker"],
      "exclude": ["src/adapters/web-worker/index.ts"]
    }
    
  3. Worker 진입 파일을 tsconfig.app.json의 exclude에 더한다. 배럴처럼 페이지가 import하는 파일은 app 프로그램에 남긴다.

  4. tsconfig.json의 references에 { "path": "./tsconfig.web-worker.json" }을 더한다. 편집기가 Worker 파일에 이 설정을 쓴다.

  5. package.json에 "check:types:web-worker": "tsc --project tsconfig.web-worker.json"을 더하고 check:types 사슬에 잇는다. 사슬 끝의 node scripts/check-typecheck-inputs.ts가 이 tsconfig의 입력이 0개면 실패시킨다.

  6. config/repository-layout.json에 tsconfig.web-worker.json 항목을 더한다(E절 R1). sets는 tsconfig.service-worker.json과 같게 fixture-copy·secret-scan이다. config/security/secret-scan-policy.json의 trackedRoots에도 같은 이름을 더한다(R2).

  7. scripts/verify-documentation-readiness.ts의 NOT_CREATED에서 src/adapters/web-worker를 뺀다.


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절의 제품 소유 파일을 쓴다.

E. 저장소 배치 규칙 (R1~R10)

기능 밖의 루트 폴더·설정·검사를 더하거나 옮길 때 지킨다. 2026-11-07 소유자 지적(샘플이 남아 있음, 역할이 겹치는 루트 폴더, 0파일 검사, 문서 속 인프라 설정)이 다시 나오지 않게 하는 규칙이다. 설계와 근거는 design-docs repo-structure/04-frontend-layout.md 11절이다.

ID 규칙 검사
R1 루트 항목은 모두 config/repository-layout.json에 있다. 항목마다 종류(source·tool-convention·gate-input·document·history·output), 역할, 읽는 곳을 적는다 tests/unit/repository-layout.test.ts(FE-GATE-005). 등록부에 없는 루트 항목이 추적되면 실패
R2 루트 경로 목록은 등록부의 이름 붙은 집합(sets, 하위 경로는 setPaths)에서만 고른다. 목록을 코드에 새로 적지 않는다. JSON 정책 파일(config/security/secret-scan-policy.json)은 그 집합의 사본을 갖고 시험이 같은지 본다 같은 시험. 목록을 쓰던 곳이 scripts/lib/repository-layout.ts를 import하는지, 루트 이름 두 개 이상의 문자열 배열이 없는지
R3 추적 파일은 읽는 곳이 있다. artifacts/는 출력 전용이라 .gitkeep만 추적한다. 사람이 쓴 기록은 docs/ 아래에 둔다(수동 a11y 기록은 docs/accessibility/route-reviews/) tests/unit/tracked-artifacts.test.ts(FE-GATE-005). config/ 아래 고아 JSON은 리뷰가 본다
R4 템플릿이나 제품이 넣은 샘플 기능은 scripts/lib/removable-template-features.ts 목록에 있고, 복사본에서 지우고 빌드·시험하는 drill로 증명한다. 문서 검사만으로는 안 된다 tests/unit/example-feature-rules.test.ts(FE-GATE-005). FE-GATE-020이 test:sample-removal을 목록 전체로 도는지
R5 게이트의 검사 대상(visual 골든, e2e 라우트, 게이트 증거 목록, 규모 측정)은 플랫폼 화면·시험 fixture·생성기 출력이다. 지울 샘플 기능이 아니다 같은 시험. 샘플의 기능 ID·라우트가 visual·e2e의 goto, config/ci/gates.json 산출물 경로, config/scale/에 나오면 실패
R6 매뉴얼의 예제 위치는 create:feature 출력이나 매뉴얼 안 코드 조각을 가리킨다. 지울 샘플 기능의 경로를 가리키지 않는다 verify:documentation(FE-GATE-017). docs/manual/에 목록 샘플의 경로가 나오면 실패
R7 이 repo에 둘 수 있는 실행 환경 파일은 개발 의존 서비스용 compose와 개발 Dockerfile뿐이다. nginx·Kubernetes·Helm·Terraform 설정은 인프라 repo에 두고 링크한다. 호스트에 요구하는 것은 계약(config/hosting/)과 검사(FE-GATE-019)로 둔다 파일: tests/unit/repository-layout.test.ts(FE-GATE-005). 문서: verify:documentation(FE-GATE-017)이 현재 문서의 ```nginx·```hcl 블록과 kind: Deployment 같은 매니페스트 줄을 막는다. 이력 폴더(docs/history/, docs/reviews/, docs/superpowers/)는 기록이라 보지 않는다
R8 검사 대상이 0개인 게이트 명령은 실패하거나 SKIP을 출력한다. 통과로 보이면 안 된다 FE-GATE-003: scripts/check-typecheck-inputs.ts(package script가 tsc에 넘기는 tsconfig마다 이 repo 파일이 1개 이상), scripts/check-type-fixtures.ts(fixture 0개면 실패)
R9 tsconfig는 lib·types·모듈 해석 중 하나가 다를 때만 새로 만든다. 옵션이 같고 파일만 다르면 실행기 하나로 돈다(예: 음성 타입 fixture는 check:types:fixtures 하나) tests/unit/repository-layout.test.ts(FE-GATE-005). 옵션이 같은 tsconfig 쌍이 있으면 실패
R10 이력 문서(끝난 라운드의 계획·작업 목록·보고)는 루트나 숨김 폴더에 두지 않고 이력 폴더 한 곳에 둔다. 정본으로 쓰이는 부분은 이력에 두지 않는다 루트 *.md는 R1 등록부에 종류와 함께 있어야 한다. "정본으로 쓰이는가"는 리뷰가 본다

루트 항목을 더하거나 옮길 때의 순서:

  1. config/repository-layout.json에 항목을 더하거나 고친다. 종류·역할·읽는 곳을 적는다(R1).
  2. 그 항목이 들어갈 집합을 sets(항목 전체)나 setPaths(항목 안 경로)에 적는다. 집합의 뜻은 파일 머리의 sets 설명에 있다(R2).
  3. secret-scan 집합을 바꿨으면 config/security/secret-scan-policy.json의 trackedRoots도 같게 고친다.
  4. 새 tsconfig라면 R9를 먼저 본다. 다른 tsconfig와 옵션이 같으면 만들지 않는다.

기능을 지울 때

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