문제: 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.
14 KiB
14 KiB
구조 기준 — 폴더·모듈·코드
폴더 구조와 import의 규칙은 이미 코드와 게이트에 있다. 이 문서는 구조를 바꿀 때 어느 정본을 같이 고쳐야 하는지, 리뷰에서 구조 결함으로 볼 것과 보지 않을 것, 그리고 게이트가 지키지 못해 반복된 코드 결함을 막는 기준을 적는다. 괄호 안 결함 패턴 X0은 defect-patterns.md의 행이다.
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의 고정 전제
- 확장 지점은 남긴다. 소비자 없는 코드와 빈 레지스트리는 다운스트림용이다. 죽은 코드로 보고 지우지 않는다(소유자 결정 2026-09-16).
- 갈라진 중복 복사본은 하나로. 같은 일을 하는 코드가 두 벌이고 서로 달라지기 시작했으면 결함이다(결함 패턴 S3). 합칠 곳은 kernel(
src/adapters/platform/)이나src/contracts/다. - 배럴이 공개 경계다. 그룹 바깥(
src/bootstrap,src/features,src/presentation)은 그룹의index.ts만 import한다. 배럴 폐지안은 2026-09-16에 기각됐다. 2단계index.ts는 공개 배럴이 아니다(예외:storage/indexeddb,storage/opfs서브배럴). - kernel 예외는 셋뿐이다.
src/adapters/platform/폴더 전체,src/adapters/browser-file-storage/result.ts,src/adapters/cross-context-invalidation/index.ts. 새 파일 단위 예외를 제안하지 않는다. 새 공유 프리미티브는src/adapters/platform/에 넣는다. 폴더 전체가 예외라 규칙을 바꿀 필요가 없다. - 실행 형태는 브라우저 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.md1절 지도), 설계서는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.refusedBeforeWritecode 목록으로만 선언한다. - 결과 불명 쓰기를 다시 보내는 모든 입구를 함께 본다. 재전송 버튼, hook 재제출, 실행기 재시도, poll 재시도, 업로드 재시도. 하나를 막으면 다른 입구에서 다시 나왔다. 키 없는 쓰기(
NEVER)는 결과 불명 뒤 재전송하지 않는다. 키 있는 쓰기는 같은 키로만 다시 보낸다(결함 패턴 C2). - 판정 규칙의 경계를 테스트로 고정한다. 경계 하나를 바꾸는 변이가 게이트에서 실패해야 한다(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는 지우고
srcport를 다시 내보낸다. - 두 템플릿 사이: 짝 백엔드의 프로토콜·오류 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 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).
- 이 변경이 새로 가정하는 상태(빈 제품 파일, CI env 없음, 객체 하나, 기능 0개 등).
- 그 가정이 깨지는 지원 구성에서 한 번 돌렸는가(../improve.md 4.2절 6단계).
- 이 변경이 다른 검사를 약하게 했는가. 경로를 백틱 밖으로 옮겨 문서 검사를 피한 수정이 그 경로를 검사 밖으로 냈다. 위험을 커밋 본문에 적고도 테스트하지 않아 다운스트림 게이트가 항상 실패한 수정도 있다.
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에서 잠금 아래 돌린다.