Files
DongHyeonka 7ed0af3d29 ci(gates): merge job 셋이 의존성 캐시에서 설치를 시작하고 main만 저장한다
문제: merge job 셋은 runner의 새 컨테이너에서 매번 Node(GitHub
다운로드), corepack의 pnpm, 패키지 404개를 내려받고, pnpm 11은 lockfile
542개 항목의 공급망 정책을 레지스트리에 물어 검증한다. run 169에서 job마다
setup-node 11~18초, 설치 12~29초였고 설치 시간의 대부분은 정책 검증의
메타데이터 요청이었다(10.1~27.9초). FE-GATE-013의 시스템 컨테이너는 같은
설치를 한 번 더 한다. merge 25분 목표에 0.8분 모자랐다.

고친 것(권하는 안으로 정함 2026-11-13, 총괄):
- job 단계 `dependency-cache`를 더한다. setup-node 앞에서 Node toolcache와
  `/tmp/fe-dependency-cache`(corepack, pnpm store, pnpm 메타데이터 캐시)를
  `.nvmrc`·`pnpm-lock.yaml` 해시 키로 복원한다. main run은 actions/cache로
  복원·저장하고, 그 밖의 ref는 actions/cache/restore로 복원만 한다. pin은
  짝 백엔드의 JDK·Gradle·Trivy 캐시와 같다(v4.3.0).
- 생성기가 그 job에 `COREPACK_HOME`·`PNPM_CONFIG_STORE_DIR`·
  `PNPM_CONFIG_CACHE_DIR`를 주어 job의 모든 pnpm 호출이 같은 곳을 본다.
  frozen install 단계는 그대로이고 캐시와 관계없이 돈다.
- PR run은 main이 저장한 항목을 같은 키로 읽기만 한다. 저장할 수 있는
  actions/cache 단계는 `refs/heads/main` 조건 아래에만 있고, 그 밖의 ref가
  타는 actions/cache/restore에는 저장하는 post 단계가 없다(시험으로 고정).
- 계약: merge job 셋만 이 단계를 가진다(release·promotion·provider·main
  job은 거절, 단계 순서 고정에 반영). 그 env를 job이 따로 묶으면 거절한다.
  키 입력은 `config/repository-layout.json`의 새 집합
  `dependency-cache-key`(`.nvmrc`, `pnpm-lock.yaml`)에서 고른다.
- `scripts/run-in-system-container.sh`가 그 env가 있으면 store와 메타데이터
  캐시를 같은 경로로 컨테이너에 넘긴다. 없으면(desktop) 지금과 같다.
- 결정 색인, ci-quality-gates.md, O1 출처 문구를 총괄이 정한 말로 맞춘다.

버린 대안:
- CI 이미지에 의존성 굽기: 레지스트리 쓰기 토큰이 든다.
- 브랜치 run도 저장하기: 캐시 항목은 다음 run이 믿는 입력이다. pnpm은
  같은 lockfile의 공급망 검증 기록이 캐시에 있으면 다시 검증하지 않으므로,
  브랜치가 쓴 항목이 main의 검증을 건너뛰게 할 수 있다.
- `cache-hit`일 때 설치를 건너뛰기: 결과가 캐시 상태에 달린다.
- apt 글꼴 캐시: 캐시가 없을 때 새 패키지 버전이 깔려 시각 결과가 달라질
  수 있다.

위험·한계:
- PR run은 main이 같은 키(또는 restore-keys로 앞 항목)를 저장한 뒤에야
  hit한다. 이 PR 자신의 run은 비어서 시작한다.
- runner 캐시 저장소(5GB)는 짝 백엔드와 같이 쓴다. 항목 하나는 Node·store·
  메타데이터로 압축 전 약 0.7GB다. lockfile이 바뀔 때마다 새 항목이 생긴다.
- Node toolcache 경로(`/opt/hostedtoolcache`)가 job 이미지와 다르면 그
  부분만 효과가 없고 setup-node가 내려받는다.

검증(desktop):
- 설치 실험(같은 lockfile, 새 폴더): 빈 캐시 13.9·17.2초, 캐시 있음 1.6초,
  store 파일 40개·메타데이터 40개를 망가뜨린 캐시 3.6초(27개만 다시 받음).
  다섯 번 모두 node_modules 트리 해시가 같다. pnpm 11은 대문자
  `PNPM_CONFIG_STORE_DIR`·`PNPM_CONFIG_CACHE_DIR`를 읽는다.
- FE-GATE-013 흐름을 캐시 env로 재현: 빈 캐시 설치 13.7초, 캐시 설치
  2.6초, 시스템 컨테이너 안 설치 1.5초(`Recreating node_modules` 없음, 지금은
  31.3초). 그 실행의 FE-GATE-013은 provider 묶음 시험 하나가 손 timeout
  30초에 걸려 실패했다(캐시와 무관, PR #39가 고치는 문제).
- RED: 계약·생성기를 둔 채 gates.json에서 캐시 단계를 빼면 새 시험 6개
  실패. 키 입력을 코드에 직접 적은 첫 판은 repository-layout R2 시험이
  잡았다. GREEN: repository-layout·ci-workflow-generation 456개 통과,
  check:ci·check:types·eslint rc=0, verify:documentation rc=0, 노트북
  `scripts/verify.sh docs` OK.
2026-11-13 08:26:13 +09:00

121 lines
14 KiB
Markdown

# 구조 기준 — 폴더·모듈·코드
폴더 구조와 import의 규칙은 이미 코드와 게이트에 있다. 이 문서는 **구조를 바꿀 때 어느 정본을 같이 고쳐야 하는지**, **리뷰에서 구조 결함으로 볼 것과 보지 않을 것**, 그리고 **게이트가 지키지 못해 반복된 코드 결함을 막는 기준**을 적는다. 괄호 안 `결함 패턴 X0`은 [defect-patterns.md](defect-patterns.md)의 행이다.
```text
src/ 최상위 폴더 ── 역할: docs/architecture/layers.md 표
│ 규칙: .dependency-cruiser.json (check:architecture, FE-GATE-010)
├─ adapters/<그룹>/index.ts ── 공개 경계(배럴)
│ └─ platform/** 등 kernel 3곳만 그룹을 넘어 import 가능
├─ features/<id>/ ── 지울 수 있는 기능 하나 (제거 드릴, FE-GATE-020)
└─ contexts/, apps/ ── 기능 묶음과 배포 단위
```
## 1. 정본
| 무엇 | 정본 | 검사 |
| --- | --- | --- |
| 최상위 `src/` 폴더와 각 역할 | `docs/architecture/layers.md` 표 | `verify:documentation`이 폴더 목록·설명 일치를 본다 |
| import 규칙 | `.dependency-cruiser.json` `forbidden`, 설명은 `docs/architecture/layers.md` | `check:architecture` |
| adapter kernel | `docs/architecture/layers.md`, 규칙 `adapters-do-not-know-other-concrete-adapters` | `check:architecture` |
| 규칙 예외의 이유·담당·재검토 조건 | 그 규칙의 `comment` | 사람이 본다 |
| adapter 그룹의 공개 경계 | 규칙 `adapter-groups-are-reached-through-their-barrel` | `check:architecture`, 고정 fixture `tests/fixtures/architecture/dependency-graph/barrel` |
| adapter 파일 목록 | `docs/reviews/adapters/INVENTORY.md` | `check:adapter-inventory`(FE-GATE-010) |
| 공유 타입·프리미티브를 어디에 둘지 | `docs/architecture/contract-ownership.md` 「판단 규칙」 | 사람이 본다 |
| 기능 폴더의 모양 | `docs/manual/01-add-a-feature.md`, `create:feature`가 만드는 파일 | FE-GATE-020의 `test:feature-scaffold` |
| 재시도 의미, 결과 불명, 인증, 업로드의 판단 기준 | `docs/manual/02-decision-tables.md` | 사람이 본다 |
| 오류·재시도·실패 경계·trace 모델 | `docs/architecture/scale-architecture.md`(코드 주석의 `scale-architecture.md §N`) | 사람이 본다 |
| 짝 백엔드 쓰기 응답의 판정 표 | `src/adapters/http/backend-envelope.ts`의 `REFUSED_BEFORE_WRITE`, 근거 `docs/architecture/backend-api-and-server-state-contract.md` 6.1절 | 짝 계약 대조 테스트 |
## 2. 이 repo의 고정 전제
1. **확장 지점은 남긴다.** 소비자 없는 코드와 빈 레지스트리는 다운스트림용이다. 죽은 코드로 보고 지우지 않는다(소유자 결정 2026-09-16).
2. **갈라진 중복 복사본은 하나로.** 같은 일을 하는 코드가 두 벌이고 서로 달라지기 시작했으면 결함이다(결함 패턴 S3). 합칠 곳은 kernel(`src/adapters/platform/`)이나 `src/contracts/`다.
3. **배럴이 공개 경계다.** 그룹 바깥(`src/bootstrap`, `src/features`, `src/presentation`)은 그룹의 `index.ts`만 import한다. 배럴 폐지안은 2026-09-16에 기각됐다. 2단계 `index.ts`는 공개 배럴이 아니다(예외: `storage/indexeddb`, `storage/opfs` 서브배럴).
4. **kernel 예외는 셋뿐이다.** `src/adapters/platform/` 폴더 전체, `src/adapters/browser-file-storage/result.ts`, `src/adapters/cross-context-invalidation/index.ts`. 새 파일 단위 예외를 제안하지 않는다. 새 공유 프리미티브는 `src/adapters/platform/`에 넣는다. 폴더 전체가 예외라 규칙을 바꿀 필요가 없다.
5. **실행 형태는 브라우저 SPA + 정적 호스팅 + Service Worker다.** 서버 메모리 상태·다중 인스턴스 경쟁 기준은 적용하지 않는다. 탭 사이 경쟁은 적용한다.
## 3. 바꿀 때 같이 고칠 것
| 바꾸는 것 | 같은 커밋에서 고칠 것 |
| --- | --- |
| 최상위 `src/` 폴더 추가·삭제 | `docs/architecture/layers.md` 표 한 행. 같은 설명 문장을 루트 `README.md`, `docs/architecture/overview.md`, `docs/architecture/frontend-application-foundation.md`에 그대로(`verify:documentation`이 대조한다) |
| import 규칙 추가·이름 변경 | `.dependency-cruiser.json`, `docs/architecture/layers.md` 규칙 표의 행 |
| 규칙 예외 | 그 규칙의 `pathNot`과 `comment`(이유·담당·재검토 조건). 파일 단위 kernel 예외는 만들지 않는다 |
| adapter 파일 추가·이동·삭제 | `docs/reviews/adapters/INVENTORY.md` |
| adapter 그룹 공개 표면 | 그 그룹의 `index.ts` |
| 기능·context 경계 | `src/features/<id>/`와 `tests/features/<id>/`. 기능끼리, context끼리 import하지 않는다 |
| 지울 수 있는 단위(기능, recipe, 선택 runtime) | 그 단위의 제거 드릴이 함께 지울 목록(`scripts/test-sample-removal.ts` 머리말) |
## 4. 문서 위치와 지워도 되는 문서
- 지금 코드가 지키는 규칙은 제자리의 살아 있는 문서(`docs/README.md` 1절 지도), 설계서는 `docs/design/`, 결정 기록은 `docs/adr/`, 계획·증거는 `docs/history/`, 리뷰는 `docs/reviews/`(앞 둘은 복사한 프로젝트가 지울 수 있다), 새 기능 절차는 `docs/manual/`, 작업 절차는 `docs/work/`, 여러 repo에 걸친 설계는 repo 밖 design-docs다.
- 코드·테스트·스크립트·설정은 지워도 되는 문서(루트 `README.md`의 지워도 되는 파일 표)를 읽지 않는다. 예외는 `docs/reviews/adapters/INVENTORY.md` 하나다. `tests/unit/deletable-history-documents.test.ts`가 검사한다. 테스트가 리뷰 문서를 열어 제거 드릴 셋을 깨뜨린 일이 있다.
- 루트 `AGENTS.md`·`CLAUDE.md`, `.claude/`, `docs/work/`는 지워도 되는 문서가 아니다. 복사한 프로젝트가 받는 템플릿 계약이다(소유자 결정 2026-11-07).
- 현재 계약 문서는 작업 이력 문서에 기대지 않는다.
## 5. 리뷰에서 구조 결함으로 보는 것
| 결함으로 본다 | 결함으로 보지 않는다 |
| --- | --- |
| 갈라진 중복 복사본(결함 패턴 S3) | 소비자 없는 확장 지점, 빈 레지스트리 |
| 같은 사실을 여러 곳에 손으로 다시 적는다(결함 패턴 S1) | 인터페이스가 많다는 사실만으로 |
| 문서가 없는 폴더·규칙을 말한다 | kernel 폴더가 크다는 사실만으로 |
| 템플릿 파일을 고쳐야 기능을 더하거나 지울 수 있다(결함 패턴 S4) | 다운스트림이 쓰지 않는 선택 runtime |
| 지울 수 있다고 한 단위를 지우면 게이트가 실패한다 | |
## 6. 코드 기준 — 판정 규칙은 한 곳에
- **실패 분류는 status 하나로 하지 않는다.** status와 code를 함께 본다. 표 밖의 값은 안전한 쪽(결과 불명)으로 둔다. 업무 거절이 결과 불명으로, 일시 오류가 무결성 실패로 분류되는 결함이 여러 영역에서 났다(결함 패턴 C1).
- **짝 백엔드 쓰기 응답의 판정 표는 `REFUSED_BEFORE_WRITE` 하나다.** 실행 경로가 둘이어도 같은 표를 읽는다. operation 단위 예외는 descriptor의 `commandEffect.refusedBeforeWrite` code 목록으로만 선언한다.
- **결과 불명 쓰기를 다시 보내는 모든 입구를 함께 본다.** 재전송 버튼, hook 재제출, 실행기 재시도, poll 재시도, 업로드 재시도. 하나를 막으면 다른 입구에서 다시 나왔다. 키 없는 쓰기(`NEVER`)는 결과 불명 뒤 재전송하지 않는다. 키 있는 쓰기는 같은 키로만 다시 보낸다(결함 패턴 C2).
- **판정 규칙의 경계를 테스트로 고정한다.** 경계 하나를 바꾸는 변이가 게이트에서 실패해야 한다([testing.md](testing.md) 3절).
## 7. 코드 기준 — 실패는 드러나게
- **원인과 추적값을 싣는다.** 실패 객체·진단에 effect, reason, `traceId`, 어느 참여자인지를 싣는다. 서로 다른 실패를 같은 reason으로 남기지 않는다. 진단 reason은 이 repo가 소유한 닫힌 목록이고 서버 code를 그대로 넣지 않는다. 서버 code는 실패의 `AppFailure.code`에 남는다. 새 adapter도 같은 기준으로 리뷰한다(결함 패턴 C6).
- **오지 않을 신호를 기다리지 않는다.** 모든 대기에는 끝나는 조건(예산 소진, 마감, 취소)이 있다 **[제안]**(결함 패턴 C3).
- **손상 한 건이 전체를 멈추지 않게 한다.** 손상 행은 건너뛰고 수를 보고한다(결함 패턴 C4).
- **결과를 사실대로 보고한다.** 다 하지 못했으면 `COMPLETED`·`verified`·`active`를 보고하지 않는다. 읽은 시점과 보고 시점 사이에 다른 작업(다른 탭의 put, release)이 끼어들 수 있으면, 같은 잠금 아래에서 다시 대조하거나 끝난 뒤 한 번 더 센다. 테스트는 객체 셋 이상으로 한다(결함 패턴 C5).
- **실패·복구 전이 뒤 화면이 다음 행동을 남긴다.** 실패 표시에서 고친 포커스·안내를 복구 성공, 확인, 진행 중 전이에도 쓴다. 페이지마다 복사하지 않고 공용 폼 hook 안에서 한다(결함 패턴 C11).
- **확인하지 못한 판정은 `PASS`가 아니라 `UNVERIFIED`다.** 코드에 상수 `true` 판정을 두지 않는다.
## 8. 코드 기준 — 같은 사실은 한 곳에
- **repo 안:** 스키마 메타, 레지스트리 행, 허용 키 목록, 빌드 입력 목록, 저장 키를 원본(zod 스키마, descriptor, registry)에서 뽑는다. 손으로 다시 적어야 하면 원본과 대조하는 테스트를 같이 둔다. 두 검사기가 같은 산출물을 다른 키 목록으로 읽어 merge 게이트가 항상 실패한 일이 있다(결함 패턴 S1).
- **이미 갈라진 복사본은 하나로 합친다.** 갈라진 recipe port는 지우고 `src` port를 다시 내보낸다.
- **두 템플릿 사이:** 짝 백엔드의 프로토콜·오류 code·응답 모양·생성기 규칙을 옮길 때는 백엔드 문서만 보지 않고 **코드까지 따라간다**(백엔드 생성기, 프론트 폼까지). 판정 표를 백엔드 계약 문서만으로 정해 High를 만든 일이 있다. 옮긴 사실은 기준 커밋(`config/contracts/backend-contract-pin.json`)과 대조 테스트로 묶는다. drift 검사(`check:backend-contract-drift`)는 계약 문서 글자, 답 표 JSON(pin 사본과), 생성기 원본 파일이 pin 뒤에 바뀌었는지를 본다. 옮긴 사실의 내용 자체는 대조하지 않는다(결함 패턴 S2).
- 짝 백엔드 repo는 읽기만 한다. 백엔드가 바꿔야 할 것은 "백엔드에 넘길 것"으로 적는다.
## 9. 코드 기준 — 지우거나 바꿀 때
- **그 코드가 지키던 것을 찾는다.** 실행 동작만 옮기면 지운 행·테스트·분기가 지키던 규칙이 조용히 사라진다. 지우기 전에 그 코드를 읽는 테스트와 검사를 `git grep`으로 찾고, 각각이 지키던 규칙이 새 경로에도 있는지 적는다(결함 패턴 T10).
- **이름을 바꿀 때는** 새 이름을 내고 옛 이름은 한 릴리스 동안 `@deprecated` 별칭으로 남긴다. 이름 하나가 여러 뜻을 가지거나 한 뜻이 여러 이름을 가지면 결함이다(결함 패턴 C10).
- **공개 포트는 추가만 한다.** 깨야 하면 결정 표에 적고 BREAKING으로 커밋한다.
## 10. 코드 기준 — 설정·환경, 동시성, 확장 지점
- **같은 설정을 경로마다 다르게 읽지 않는다.** 번들, 빌드 스크립트, Service Worker 빌드가 같은 출처에서 읽는다(결함 패턴 C8).
- **URL은 router base path를 따른다.** `/`부터 직접 조립하지 않는다. 기본 게이트가 루트 경로만 돌아 드러나지 않는다. 하위 경로 빌드 테스트로 확인한다(결함 패턴 C7).
- **테스트가 띄우는 빌드·서버의 env는 테스트가 정한다**([gates.md](gates.md) 4절).
- **환경 가정은 적고, 확인하고, 없으면 이유를 말하며 실패한다.** 글꼴, user namespace, 옆 checkout(결함 패턴 G6).
- **여러 탭이 같은 저장소·구독·잠금을 건드리는 경로**는 Web Locks로 직렬화하거나 잠금 없이도 안전한 이유를 적는다. 잠금을 기다리는 작업에는 abort와 상한이 있다(결함 패턴 C9).
- **제품마다 다른 것은 제품 소유 파일에 둔다.** 제품이 템플릿 소유 파일을 고쳐야 하면 결함이다. 동기화마다 같은 파일이 충돌한다. 제품 소유 자리의 예: `src/bootstrap/product-composition.ts`, `src/contracts/product-contracts.ts`, `config/ci/product-gates.json`. 효과는 다음 동기화 충돌 수로 잰다(결함 패턴 S4).
- **경계 예외는 실제 쓰임만큼만 연다.** kernel 폴더에는 공유 메커니즘만 둔다(결함 패턴 S5).
- **두 모듈이 이어지는 곳을 지나는 테스트를 둔다.** 한쪽이 보내는 결과를 다른 쪽이 다른 뜻으로 받는 결함은 연결 지점에서만 보인다(결함 패턴 S6).
## 11. 고칠 때 — 수정이 새로 가정하는 것
2026-11-05 리뷰의 새 발견 48건 중 22건은 원인이 지난 수정이었다. 수정 커밋마다 본문 「위험·한계」에 적는다(결함 패턴 G13).
1. 이 변경이 새로 가정하는 상태(빈 제품 파일, CI env 없음, 객체 하나, 기능 0개 등).
2. 그 가정이 깨지는 지원 구성에서 한 번 돌렸는가([../improve.md](../improve.md) 4.2절 6단계).
3. 이 변경이 다른 검사를 약하게 했는가. 경로를 백틱 밖으로 옮겨 문서 검사를 피한 수정이 그 경로를 검사 밖으로 냈다. 위험을 커밋 본문에 적고도 테스트하지 않아 다운스트림 게이트가 항상 실패한 수정도 있다.
## 12. 제거 가능성
지울 수 있는 단위는 드릴이 지킨다. 기능 드릴(샘플 제거, 생성 기능의 scaffold·제거)은 merge 게이트 FE-GATE-020, 선택 runtime 제거 드릴 셋(optional recipe, browser file/storage, realtime)은 main 단계 FE-GATE-030이다(권하는 안으로 정함 2026-11-12, 총괄). 드릴 목록은 `config/ci/gates.json`의 두 게이트 `commandIds`다. 선택 runtime을 바꾼 PR은 merge에서 FE-GATE-030이 돌지 않으니 `scripts/verify.sh gate FE-GATE-030`을 직접 돌린다.
- 구조를 바꾸면 드릴을 돌린다. 드릴 fixture가 복사하는 목록(`scripts/lib/removal-fixture.ts`, 이 목록 하나만 쓴다)이 바뀐 구조를 아는지 본다. 그 목록에 `README.md`·`CHANGELOG.md`가 없어 드릴 넷 중 셋이 항상 실패한 일이 있다(결함 패턴 G11).
- 드릴은 오래 걸린다(desktop 2026-11-13 실측: FE-GATE-020과 FE-GATE-030 합쳐 약 10분 30초). desktop에서 잠금 아래 돌린다.