Files
clean-architecture-frontend…/docs
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
..

docs

저장소의 문서는 이 폴더 아래에 있다(루트 README.md, CHANGELOG.md 등 몇 개는 밖에 있다). 이 README는 두 가지를 정한다.

  • 어떤 문서가 어느 폴더에 있나: 1절 「문서 지도」. 지금 있는 모든 문서 폴더를 덮는다.
  • 문서의 수명에 따라 무엇을 어떤 언어로 어떻게 고치나: 2절부터.

규칙의 정본은 design-docs 저장소의 conventions/docs-system.md다. 이 README는 그 규칙을 이 repo에 적용한 내용이고, 이 템플릿을 복사한 프로젝트도 이 README를 따른다. 파일 목록과 개수는 여기에 적지 않는다. 적으면 다음 문서가 더해지는 순간 틀린 글이 된다. 파일은 폴더를 직접 읽는다.

문서와 코드가 다르면 코드가 맞다.

1. 문서 지도

  • 표의 첫 칸이 폴더다(docs/ 기준 경로).
  • 새 문서 폴더를 만들면 같은 변경에서 이 지도에 행을 더한다. 폴더를 지우거나 옮기면 그 행도 고친다.
  • 문서 검사의 map이 지도에 없는 폴더와, 지도에 있지만 없는 폴더를 막는다(5절).

처음 읽을 문서

문서 정하는 것
../AGENTS.md 규칙의 정본과 지도: 꼭 지킬 것, 맡은 일마다 읽을 playbook, 검증 진입점 scripts/verify.sh
work/, work/reference/ 작업 매뉴얼: 맡은 일마다의 playbook과 기준(완료 기준은 work/improve.md 5절)
README.md 프로젝트 구조, 시작하기, 런타임 설정과 배포 변수, 기능 켜고 끄기와 지원 범위, 검증과 CI, 새 서비스로 시작하기, 원본 업데이트 반영
architecture/frontend-application-foundation.md 이 repo의 역할(스타터 + 재사용 capability)과 기본·선택의 경계
architecture/layers.md, architecture/overview.md 계층과 import 방향. check:architecture가 검사한다
architecture/starter-experience.md 기본 라우트, 인증 모드, 기능 추가·제거 절차
manual/ 새 기능을 더하는 순서와 판단 기준, create:feature(manual/reference/)
operations/ci-quality-gates.md, testing/taxonomy.md 게이트, 테스트 계층, 새 프로젝트가 초기화할 기준선

매뉴얼

일하는 순서와 판단 지점이다. 사람과 AI 세션이 같이 쓴다.

폴더 무엇
work/ 작업 매뉴얼: 새 기능, 리뷰·수정·리팩터링, 조사·설계, 문서, 운영, 일 나누기의 playbook. work/reference/에 게이트·구조·테스트·리뷰 기준과 결정 색인, work/evidence.md에 매뉴얼 규칙의 근거 기록
manual/ 개발 매뉴얼: 새 기능 하나를 더하는 0~11단계, 결정표, 기능 폴더 밖 파일, 짝 백엔드에 붙이기. manual/reference/에 명령 인자, 전역 ID, 패턴, 오류 메시지
ledger/ 작업 예측·실측 장부(ledger/estimates.jsonl, 형식은 ledger/README.md)

현재 계약

지금 코드가 지키는 규칙이다. 코드와 같은 변경에서 고친다.

폴더 무엇
architecture/ 계층과 import 규칙(architecture/layers.md), 플랫폼의 역할, 스타터, recipe 절차, 정적 배포, 계약 소유, 규모 설계(architecture/scale-architecture.md, 코드 주석의 scale-architecture.md §N이 가리킨다), 짝 백엔드 계약(architecture/backend-api-and-server-state-contract.md 4.1·6·6.1절이 실행 규칙. 기준 커밋은 config/contracts/backend-contract-pin.json), 2026-07-18 도식 리뷰 기록의 사본(architecture/review-evidence.md, architecture/review-ledger.json)
contracts/ 계약 호환 규칙(읽는 쪽을 먼저 배포한다)
security/ 브라우저 보안 경계와 공급망
styling/ 디자인 토큰
accessibility/ 수동 접근성 검토 체크리스트와 라우트별 검토 기록(accessibility/route-reviews/)
testing/ 테스트 계층(taxonomy)과 새 프로젝트가 초기화할 기준선

운영

폴더 무엇
operations/ CI 품질 게이트, capability별 복구 절차, 릴리스·캐시 롤백, 성능 증거, 2026-08-14 adapter 재검토의 처리 원장(operations/adapter-remediation-ledger.md)
runbooks/ 오류 code별 장애 대응 runbook(FE-RB-00N). 등록은 config/runbooks/runbooks.json

결정 기록

폴더 무엇
adr/ 결정 기록(VD). 번호는 옮기기 전과 같다(VD-NN-<주제>.md). 2026-11-08에 architecture 아래 decisions 폴더에서 옮겼다

설계와 기록

설계서와 기록은 쓴 때의 글이다. 지금 동작을 설명하지 않는다. 그래서 살아 있는 문서와 다른 폴더에 둔다.

폴더 무엇
design/ 설계서. YYYY-MM-DD-<주제>-design.md. 2026-11-08에 옛 superpowers 폴더의 specs와 architecture/의 목표 설계를 옮겼다
history/plans/ 계획서. 2026-09-25 리뷰 수정 라운드의 요구사항(SPEC.md)과 작업 목록도 여기 있다
history/evidence/ 작업 단계의 증거·체크포인트
reviews/ 리뷰 결과. 라운드마다 폴더 하나(README가 결정과 남은 것을 적는다) 또는 리뷰 문서 하나. 리뷰 가이드와 실행 체크리스트는 design-docs 저장소로 옮겼고, 여기에는 정본 위치를 알려 주는 포인터 둘이 있다
  • 계획서 본문에는 그때 계획한 경로와 명령이 그대로 남아 있다. 계획서를 나중에 고치지 않는 이유는, 고치면 계획의 기록이 아니라 결과를 계획처럼 보이게 만든 글이 되기 때문이다.
  • history/와 reviews/는 복사한 프로젝트가 지워도 된다(루트 README.md 「복사한 뒤 지워도 되는 것」). 예외는 reviews/adapters/다: reviews/adapters/INVENTORY.md는 check:adapter-inventory(FE-GATE-010)가 src/adapters와 대조하는 살아 있는 목록이다.
  • design/과 adr/은 코드 주석이 근거로 가리키므로 지우지 않는다.

폴더 밖 문서

문서 무엇
../README.md 루트 README. 6절의 필수 절을 가진다
../CHANGELOG.md 템플릿 버전 사이의 변경. 지난 상태를 적는 문서라 문서 검사의 참조·숫자 검사는 보지 않는다
../AGENTS.md 규칙의 정본과 지도. src/ 계층 폴더마다 지역 규칙 AGENTS.md가 있다
루트 CLAUDE.md AGENTS.md를 가져오고 Claude Code 전용 줄만 둔다. 경로별 규칙·스킬·서브에이전트는 .claude/
vision.md, problem-statement.md 비전과 문제 정의. 소유자가 채우는 양식이다
루트 PRODUCT.md 디자인 도구가 읽는 제품 맥락
../src/adapters/browser-transfer/image-cdn/README.md Image CDN adapter의 모듈 README

게이트가 읽는 파일

지우거나 옮기면 게이트가 실패한다.

파일 읽는 명령
이 파일, architecture/review-ledger.json, architecture/review-evidence.md verify:documentation (FE-GATE-017)
라우트별 수동 접근성 기록(accessibility/route-reviews/<ROUTE_ID>.md) verify:documentation (FE-GATE-017), review:a11y-manual (FE-GATE-009, FE-GATE-028)
reviews/adapters/INVENTORY.md check:adapter-inventory (FE-GATE-010)
operations/adapter-remediation-ledger.md, operations/adapter-remediation-dispositions.json check:remediation-ledger (게이트 밖. 이유는 config/ci/ungated-scripts.json)
architecture/backend-api-and-server-state-contract.md 6.1절 표 tests/unit/backend-contract-pin-document.test.ts (FE-GATE-005)
architecture/starter-experience.md의 기능 폴더 밖 파일 표, manual/03-outside-feature-folder.md A절 tests/unit/feature-tracked-files.test.ts (FE-GATE-005)
manual/의 표시한 코드 블록과 manual/04-paired-backend-session.md 3.2절 tests/unit/manual-code-blocks.test.ts, tests/unit/manual-paired-backend-settings.test.ts (FE-GATE-005)

2. 문서 수명과 언어

수명 문서 위치 언어 고치는 법
살아 있음 README, AGENTS.md(루트와 src/ 계층 폴더), CLAUDE.md, .claude/의 규칙·스킬, 매뉴얼(work/, manual/), 장부(ledger/), vision.md·problem-statement.md, 현재 계약(architecture/, contracts/, security/, styling/, accessibility/, testing/), 운영(operations/, runbooks/), reviews/adapters/INVENTORY.md, 모듈 README, CHANGELOG.md 제자리 한국어 코드와 같은 변경에서 고친다(4절)
결정 결정 기록(VD) adr/ 한국어 본문은 고치지 않는다. 일부가 바뀌면 상태를 「채택(보완)」으로 하고 맨 아래에 날짜가 있는 「보완」 절을 덧붙인다. 크게 바뀌면 새 VD를 쓰고 옛 VD를 「대체됨」으로 한다
기록 설계서, 계획서, 증거, 리뷰 design/, history/, reviews/ 머리 블록은 한국어, 본문은 쓴 때의 원문 머리 블록의 칸만 고친다
  • 살아 있는 문서와 결정 기록의 본문은 한국어로 쓴다. 설정 파일의 사람이 읽는 설명 칸(recipe 카탈로그, runbook 등록)도 한국어다.
  • 원문으로 두는 것: 코드 식별자, 명령, 경로, 설정 키, 오류 코드, 로그·출력 인용, 외부 문서 인용, 제품 이름.
  • 용어는 자연스러운 한국어 → 한국어(영어) → 영어 그대로 순으로 고른다. 처음 나올 때 한 번 병기한다. 이 repo가 영어로 쓰는 말(adapter, port, capability, recipe, feature, context, slice, registry, gate 등)은 영어로 둔다.
  • 문체는 「~한다」다. 한 문서 안에서 「~합니다」와 섞지 않는다.
  • 2026-11-08에 살아 있는 문서를 모두 한국어로 옮겼다. 문서 검사의 예외 목록은 비어 있다(5절).
  • accessibility/route-reviews/의 라우트별 기록은 문서가 아니라 정해진 영어 키 형식의 게이트 입력이다(scripts/lib/manual-a11y-evidence.ts). 문서 검사가 보지 않는다.

3. 기록 문서의 머리 블록

design/, history/, adr/의 .md 파일은 맨 위에 이 블록을 둔다. 블록을 빼면 원문 그대로다(옮길 때 깨진 상대 링크의 대상만 고쳤다).

<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
> **기록 · 설계서** 본문은 쓴 때의 원문이다. 지금 동작은 「현재 정본」을 읽는다.

- 상태: 구현됨
- 작성일: 2026-08-01
- 요약: 한국어 한 문장
- 현재 정본: `docs/architecture/layers.md`
- 대체됨: `docs/design/<대체한 문서>.md`
<!-- 머리 블록 끝 -->
  • 종류는 폴더가 정하고 둘째 줄에 굵게 적는다: design/ 설계서, history/plans/ 계획서, history/evidence/ 증거. 결정 기록(adr/)의 둘째 줄은 > **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.다. VD는 처음부터 한국어로 썼고 번역하지 않았다. 나중에 본문을 번역하면 「원문이다」 대신 「내용이다(번역은 뜻을 바꾸지 않았다)」로 쓴다.

  • 상태는 종류마다 고정 어휘다.

    종류 상태
    설계서 제안 · 채택 · 구현됨 · 보류 · 폐기 · 대체됨 · 확인 안 함
    결정 기록 제안 · 채택 · 채택(보완) · 폐기 · 대체됨
    계획서 실행 중 · 끝남 · 중단 · 대체됨 · 확인 안 함
    증거 보관
  • 「현재 정본」은 지금 동작을 설명하는 살아 있는 문서나 코드의 경로다. 여럿이면 쉼표로 잇고, 없으면 「없음 — 이유」로 쓴다.

  • 「대체됨」은 상태가 대체됨일 때 대체한 문서의 경로다. 이 문서가 다른 문서를 대체했으면 「대체」 칸에 그 경로를 쓴다.

  • 상태는 그 결정을 바꾼 변경이 같이 바꾼다. 기능을 지우는 커밋이 그 기능의 설계서를 「폐기」나 「대체됨」으로 바꾼다. 새 설계서·결정 기록은 처음부터 블록을 달고 쓴다(보통 「제안」).

  • 2026-11-08에 처음 단 상태는 원래 상태 줄을 기계로 바꾼 값이다: Accepted·Approved·확정·승인·정본 → 채택, Superseded → 대체됨, Proposed → 제안, implemented → 구현됨, 날짜가 붙은 보완 메모가 본문에 있는 VD → 채택(보완). 상태 줄이 없던 설계서와 체크 상자가 모두 표시되지 않은 계획서는 「확인 안 함」이다.

  • .md가 아닌 파일(레인 준비 셸 스크립트)에는 달지 않는다. 같은 폴더 문서의 블록이 그 파일을 설명한다.

  • 리뷰(reviews/)는 아직 머리 블록을 요구하지 않는다.

4. 문서와 코드를 같은 변경에서 고친다

  • 코드나 규칙을 바꾸는 변경이 그것을 설명하는 살아 있는 문서도 고친다. 찾는 법: git grep -n '<바꾼 이름>' -- '*.md'.
  • 살아 있는 문서는 지금 있는 것만 쓴다. 지운 타입·경로·명령은 CHANGELOG.md에 쓴다. 살아 있는 문서 안에서 꼭 써야 하면 > 이력 으로 시작하는 인용 블록 안에 쓴다. 문서 검사는 그 블록의 문체를 보지 않는다.
  • 숫자·버전을 복사하지 않는다. 프레임워크 버전은 package.json과 .nvmrc, 게이트 목록은 config/ci/gates.json, recipe 목록은 config/recipes/frontend-capability-recipes.json, adapter 파일 목록은 reviews/adapters/INVENTORY.md를 가리킨다.
  • 루트 README는 「프로젝트 구조」와 「문서 지도」 절을 반드시 둔다. 전체 절 목록과 순서의 정본은 design-docs conventions/docs-system.md 6.1절이고, 문서 검사의 readme가 그 목록(scripts/lib/docs-system.ts의 README_SECTIONS)을 본다.

5. 문서 검사

verify:documentation(FE-GATE-017)이 위 규칙 중 기계로 볼 수 있는 것을 본다. 하나라도 걸리면 실패한다. 경로 필터가 없다: 코드에서 파일이나 script를 지우는 변경이 그 변경과 상관없는 문서를 낡게 만든다.

  • pull request에서 실패하게 하는 곳은 merge 단계 FE-GATE-005다. 그 안의 tests/unit/documentation-readiness.test.ts가 이 repo를 그대로 두고 verify:documentation을 한 번 돌린다. FE-GATE-017 job 자체는 documentation 단계를 고른 workflow_dispatch에서만 돈다(config/ci/gates.json의 documentation_gate).
검사 보는 것
language 살아 있는 문서와 결정 기록 본문이 한국어인가. 코드·명령·경로·링크·인용은 세지 않고, 영어 낱말 3개 이상이면서 한글 덩어리 비율 0.3 미만이면 영어다(보고 언어 훅 H11과 같은 판정)
head 기록과 결정 기록 맨 위의 머리 블록: 칸, 상태 어휘, 날짜, 한국어 요약, 현재 정본·대체됨 경로가 지금 있는지
document references 살아 있는 문서의 인라인 코드·셸 코드 블록 안 repo 경로, 마크다운 링크 대상, package script 이름, FE-GATE ID가 지금 있는가. 짝 백엔드 경로는 config/contracts/backend-contract-pin.json이 고정한 커밋의 트리에서 찾는다
number 살아 있는 문서가 프레임워크 버전이나 게이트·recipe·adapter 개수를 복사했는가. 결정 기록, 기록, CHANGELOG.md는 보지 않는다
map 이 README의 1절 지도가 docs/ 아래 모든 폴더를 덮는가(표 첫 칸의 폴더/). 파일 없이 폴더만 가진 묶음 폴더(history/)는 그 바로 아래 폴더가 대신한다. 지도에 있지만 없는 폴더도 실패다
readme 루트 README가 첫 줄 제목, 그 아래 한 문단, 정해진 ## 절을 정해진 순서로 가지는가
style 살아 있는 문서와 결정 기록의 문장 끝이 높임(「~합니다」「~하세요」)이 아닌가. 코드, 따옴표·낫표 안 인용, > 이력 블록은 보지 않는다
  • 그 밖에 같은 명령이 루트 README의 런타임 변수 표, 입구 문서의 src/ 폴더 설명(architecture/layers.md 표와 글자가 같아야 한다), 수동 접근성 기록의 범위, 2026-07-18 도식 리뷰 사본 둘의 일치를 본다.
  • 규칙과 판정의 정본은 scripts/lib/docs-system.ts(검사 여섯)와 scripts/verify-documentation-readiness.ts(참조와 그 밖의 검사)다. 백엔드 템플릿의 문서 검사기(그 repo의 check-docs.py)를 같은 이름·문턱으로 옮긴 것이다.
  • 검사 자신의 시험: tests/unit/docs-system.test.ts, tests/unit/documentation-readiness.test.ts.
  • 예외 목록 scripts/docs-system-exceptions.txt는 비어 있고 줄기만 한다. 목록에 새 줄을 더하면 실패한다(줄마다 scripts/lib/docs-system.ts의 FROZEN에 지문이 있어야 하는데, FROZEN이 비어 있다). 기준선을 늘리는 것은 규칙을 바꾸는 일이라 소유자 결정이 필요하다.
  • 복사한 프로젝트가 지운 기록(history/, reviews/)과 지운 샘플 기능의 경로는 없어도 된다. git이 무시하는 생성 산출물도 없어도 된다.
  • 설명·수치가 코드와 맞는지는 검사하지 않는다. 리뷰가 표본으로 대조한다.