문제: 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.
정리 4단계의 R2 검사는 등록부를 쓰는 7곳만 봤다. 그 밖에 루트 이름을
담은 목록이 코드 15파일에 19개 따로 있어, 루트 항목 하나를 옮기면
여전히 여러 곳을 같이 고쳐야 했다.
- 등록부에 집합 12개를 더했다. 사본 복사에서 건너뛰는 항목 셋
(checkout·provider·공급망 fixture), fixture 코드 범위, pnpm 매니페스트,
Playwright 설정, visual 증거, 문서 입력, 에이전트 하네스, tsconfig
묶음 셋. 각 집합 설명에 읽는 파일을 적었다.
- 사본이 건너뛰는 node_modules·dist·.tmp 같은 추적 안 하는 항목은
종류 untracked(optional)로 적는다. 추적 파일이 있으면 시험이 실패한다.
- 19개 목록이 모두 집합을 고른다. 집합의 원소는 전과 같아 동작은
바뀌지 않는다.
- R2 시험이 추적되는 코드 파일 전체를 본다. 루트 항목(이나 그 안
경로)만 담은 문자열 배열에 추적되는 루트 이름이 둘 이상이면 실패.
인자 목록은 `--` 뒤만 본다. main의 옛 목록 18개를 이 검사가 잡는
것을 확인했다.
- 집합마다 selectRepositoryPaths·selectRepositoryEntries로 고르는 코드가
있는지 본다. 문서를 복사하지 않는 제거 drill(FE-GATE-020)은 문서
시험(REMOVAL_FIXTURE_DOCUMENT_TESTS)을 지우는데, 집합 셋
(agent-harness·documentation-inputs·feature-typecheck)은 그 시험만
읽는다. 시험이 이 셋을 적어 두고, 문서 시험이 지워진 사본에서만 셋이
비는 것을 허용한다. 셋이 바뀌면 전체 checkout에서 실패한다.
- 파서가 kinds·sets 설명과 코드의 목록이 같은지 본다.
- .gitignore 주석이 a11y 기록을 아직 artifacts/ 아래라고 적던 것을
고쳤다(정리 3단계에서 docs/로 옮김).
검증(desktop): test:unit, check:types, check:ci, lint, verify:documentation.
repository-layout 시험을 문서 없는 제거 사본과 feature-scaffold 사본에서도
돌렸고, 집합 하나의 읽는 곳을 지우면 두 곳 모두 실패한다.
루트 항목 하나를 옮기려면 코드 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절