docs(improvement): 검증 위치·merge 판정 방법과 결정 색인을 적는다

문제: "merge 가능" 판정을 고른 스크립트 목록이나 CI=true 없는 env로
해서 실제 러너에서 항상 실패하는 게이트를 놓친 적이 있다. 테스트를
어디서 돌리는지(desktop, 잠금, 되돌림)는 사용자 지시로만 있다. 소유자
결정이 리뷰 README·SPEC.md·ADR·세션 기록에 흩어져 다시 묻게 된다.

고른 방법: 07장에 때별로 돌릴 것, ci:gate로 merge 단계 14개를
workflow env로 돌리는 방법, 가끔 떨어지는 게이트의 기록법, desktop의
FE-GATE-013 처리, CI env에서만 나는 실패, PASS 뒤 실패, 문서 검사의
범위와 도는 곳, 소유자 환경을 적는다. 08장에 결정을 적는 곳, 다시
묻지 않는 규칙, 작업 방식 결정 O-1~O-14와 기술 결정 묶음의 색인,
결정 대기 형식과 지금 열린 D1~D6, 커밋·PR에서 이 repo가 덧붙이는
것을 적는다. 결정 원문은 옮기지 않는다.

위험·한계: 열린 결정 표는 4라운드 시점이다. 다음 라운드가 닫으면
고쳐야 한다. CLAUDE.md 27줄의 리뷰 게이트 목록이 merge 단계와 다르다는
발견(1105/12-03)은 고치지 않고 07장이 merge 단계를 함께 돌리라고만
적는다.

검증: 로컬 정적 대조. desktop 검사는 연결 커밋 뒤.
This commit is contained in:
DongHyeonka
2026-11-05 22:15:44 +09:00
parent 40e3b2f814
commit 402fe12231
2 changed files with 300 additions and 0 deletions
+177
View File
@@ -0,0 +1,177 @@
# 07. 검증과 게이트
## 핵심
무엇을 돌릴지는 **언제인지**로 정한다. 작업 중에는 바뀐 테스트 파일만, 커밋 전에는 빠른 게이트 8개, 통합 때는
5개를 더, merge 가능을 말할 때는 merge 단계 14개를 CI와 같은 env로 돌린다.
```text
작업 중 바뀐 테스트 파일 하나 (1절)
커밋 전 빠른 게이트 8개 (2절, SPEC.md 31줄)
레인 끝·통합 + 5개 (2절, SPEC.md 32줄)
merge 판정 ci:gate로 merge 단계 14개, workflow env (3절)
리뷰 시작 CLAUDE.md 목록 11개 + merge 단계 14개 (3절)
```
게이트 ID·단계·명령의 정본은 `config/ci/gates.json`이다. 이 장은 그 목록을 다시 적지 않는다.
## 1. 명령 규칙
- 패키지 스크립트는 `corepack pnpm <script>`로 돌린다. `npm run`으로 돌리면 제거 드릴이 `npm_execpath`를 pnpm으로
가정해 모든 검사가 `Unknown command`로 실패한다(1103 README 10.4절).
- 테스트 파일 하나는 `node scripts/run-vitest.ts run <file>`로 돌린다. 이 runner가 `src/.generated/`를 먼저 만든다.
`pnpm exec vitest run <file>`은 그 단계를 건너뛰어 import 오류로 실패하고, `pnpm test:unit -- <file>`은 범위를
좁히지 않는다(`docs/testing/taxonomy.md` 42~53줄).
- 실패를 경고로 낮추지 않는다. `continue-on-error`나 경고만 내는 스크립트를 쓰지 않는다(`docs/testing/taxonomy.md`
3~4줄).
## 2. 언제 무엇을
| 때 | 돌릴 것 | 근거 |
| --- | --- | --- |
| 작업 중 | 바뀐 테스트 파일. 브라우저 테스트는 그 spec 하나 | 1절 |
| 커밋 전(작업마다) | `check:architecture`, `check:types`, `lint`, `test:unit`, `test:component`, `test:integration`, `test:contract`, `test:runtime-schema` | `SPEC.md` 31줄 |
| 레인 끝·통합 | 위에 더해 `check:ci`, `check:adapter-inventory`, `verify:documentation`, `test:sample-removal`, `build` | `SPEC.md` 32줄 |
| 브랜치를 합칠 때마다 | 커밋 전 8개. 합친 뒤에만 생긴 실패는 기록한다 | 1103 README 14.1·14.3절 |
| merge 가능이라고 말하기 전 | merge 단계 14개(3절) | 사용자 지시 |
| 리뷰 시작 | `CLAUDE.md` 27줄의 11개와 merge 단계 14개 | `CLAUDE.md` 27줄, 1103 README 10.5절 |
| 라우트 로딩·청크·초기 화면을 바꿀 때 | merge 단계에 더해 `check:bundle`(FE-GATE-012)과 lab 게이트 `test:performance`(FE-GATE-026) | 06장 2절 |
| 공급망·release 경로를 바꿀 때 | release 단계 게이트(`config/ci/gates.json`의 `stages` 중 `release`) | 4절 |
release 단계 게이트는 merge 단계에 없다. 그래서 lab 게이트 회귀가 147커밋 동안 아무 게이트에도 걸리지 않았다
(1103/15-01, 1103 README 5절 원인 2). 바꾼 것이 release 단계 게이트가 지키는 것에 닿으면 그 게이트도 돌린다.
## 3. merge 가능 판정
"merge 가능"은 다음 방법으로만 말한다(사용자 지시). 고른 스크립트 목록이 다 통과했다는 것은 merge 가능의 근거가
아니다. 스크립트를 골라 "23개 통과"라고 보고했지만 merge 게이트 셋이 실패하던 적이 있다(2026-11-03).
1. **대상:** `config/ci/gates.json`의 `stages` 중 `merge`의 `gateIds` 14개(FE-GATE-001~013, FE-GATE-020).
2. **명령:** 게이트마다 `corepack pnpm ci:gate -- FE-GATE-0NN`. workflow도 같은 명령을 쓴다
(`.gitea/workflows/quality-gates.yml` 74줄).
3. **env:** workflow의 전역 env(`.gitea/workflows/quality-gates.yml` 25~31줄)를 그대로 준다.
| 변수 | 값 |
| --- | --- |
| `CI` | `true`. 빼지 않는다. 이 값이 있어야 빌드 식별값을 엄격하게 검사한다 |
| `VITE_COMMIT_SHA` | 40자리 커밋 SHA |
| `VITE_BUILD_ID` | `gitea-<run>-<attempt>` 꼴 |
| `RELEASE_ID` | `<ref>-<run>-<attempt>` 꼴 |
| `CI_RUNNER_IMAGE` | `<image>@sha256:<64자리>` 꼴 digest |
`CI=true` 없이 "14개 통과"라고 했다가, 넣자 FE-GATE-005·008·020이 실패한 적이 있다(1103 README 14.5절 끝 문단,
1103/11-08).
4. **작업 폴더:** 깨끗한 checkout. 노트북 main checkout은 `.claude/worktrees/`를 품고 있어 `test:system`의 repo 복사와
vite 파일 감시가 깨진다. desktop checkout에는 이 폴더가 없다(7절).
5. **한 게이트 안의 명령:** `ci:gate`는 그 게이트의 명령 중 첫 실패에서 멈춘다. 뒤 명령의 결과가 필요하면 따로 돌린다.
4라운드는 FE-GATE-013의 `test:system` 뒤 명령 7개를 따로 돌렸다(1105 README 11.1절).
6. **기록:** 게이트마다 결과·시간·핵심 숫자(테스트 수, 초기 JS 바이트, 파일 수)와 실행 시점의 부하를 표로 남긴다.
게이트 로그는 `artifacts/quality/gates/FE-GATE-0NN.txt`에 쌓인다. 실패를 고칠 때마다 다시 돌리고 회차를 남긴다
(1103 README 14.5절 표).
### 3.1 가끔 떨어지는 게이트
- **다시 돌려 통과시킨 결과를 "통과"로 쓰지 않는다.** 실패한 회차를 그대로 적고 원인을 찾는다(05장 5절).
1103 조치에서 FE-GATE-008이 "세 번째 실행에서 통과"로 적혔던 두 실패는 둘 다 테스트 결함이었다(1103/11-09,
1103/11-10).
- 원인을 고친 뒤에는 같은 게이트를 연속으로 여러 번 돌려 실패 0을 적는다. FE-GATE-008은 연속 3회였다(1103 README
14.5절 12~14회차).
### 3.2 desktop에서 FE-GATE-013
desktop에서는 FE-GATE-013의 `test:system` 중 provider 테스트 18건이 호스트 원인으로 실패한다. ssh 셸에서 비특권
user namespace가 막혀 `bwrap --unshare-net`이 실패한다. 사전 점검은 이 조건을 보지 않고 PASS를 낸다(1105/12-01).
- 러너 전제를 어떻게 할지는 **결정 대기**다(1105 README 7절 D4). 결정 전까지 merge 판정 보고에는 FE-GATE-013을
"환경 실패"로 적고, 실패 18건이 모두 그 원인인지와 뒤 명령 7개의 결과를 함께 적는다(1105 README 11.1절 표).
- 시스템 설정은 바꾸지 않는다.
## 4. CI env에서만 나는 실패
로컬 env로 통과해도 workflow env에서 실패하는 결함이 반복됐다(부록 P-05).
| 발견 | 모양 |
| --- | --- |
| 1103/11-06 | e2e가 build id를 `"local-build"`로 고정했다. workflow는 `VITE_BUILD_ID`를 넣으므로 FE-GATE-008이 실제 CI에서 항상 실패 |
| 1103/11-07 | workflow 전역 env의 빌드 식별값이 vitest와 dev server로 새어, merge 게이트 다섯 개가 실제 CI에서 항상 실패 |
| 1103/11-08 | `CI=true`가 테스트 안의 로컬 빌드까지 release 빌드로 검사되게 해, merge 게이트 셋이 workflow env에서 실패 |
기준:
- merge 판정은 3절 env로만 한다.
- 테스트는 바깥 env에서 무엇을 물려받는지 고정한다. 테스트가 직접 띄우는 빌드·서버의 env는 테스트가 정한다
(04장 6절).
## 5. 검사가 PASS인데 그 뒤가 실패
사전 점검·준비 단계가 "통과"를 내고, 그 뒤 실제 단계가 원인 없는 원문 오류로 실패하는 결함이다(부록 P-07).
- 1105/12-01: `scripts/check-system-test-prerequisites.ts`가 실행 파일·cgroup·systemd bus만 보고 bwrap을 실제로
돌리지 않는다. 그래서 PASS 뒤 provider 테스트가 bwrap 원문 오류로 떨어진다.
- 1103/11-04: `test:system`이 git worktree에서 `.git` 때문에 실패하는데 사전 점검은 PASS를 낸다.
기준: 사전 점검은 **본 단계가 쓰는 것과 같은 방법으로** 한 번 실행해 본다. 실패하면 원인 이름을 붙여 멈춘다.
존재 여부만 보는 점검은 PASS가 아니라 "확인 안 함"으로 적는다(`SPEC.md` 「결정」 D-14의 `UNVERIFIED` 원칙).
## 6. 문서 검사
`verify:documentation`(FE-GATE-017, documentation 단계)이 문서를 검사하는 범위와 방법의 정본은
`scripts/verify-documentation-readiness.ts`와 `docs/README.md` §1 끝 문단이다.
- **범위:** `docs/README.md`와, 그 §1이 링크한 문서. 폴더 링크는 그 폴더 바로 아래 `.md`만 본다. 이 매뉴얼은 §1에서
링크되어 범위 안이다(README 결정 M-3).
- **보는 것:** 백틱 안의 repo 경로(`:줄` 꼬리는 떼고 본다), 셸 코드 블록과 백틱 안 명령의 경로 인자, 마크다운 링크,
`corepack pnpm <script>`와 백틱 안 `<prefix>:<name>` 꼴의 package script, `FE-GATE-0NN` ID가 실제로 있는가.
- **보지 않는 것:** 설명·수치가 코드와 맞는가.
- **예외:** git이 무시하는 생성 산출물, 복사한 프로젝트가 지운 작업 이력(루트 `README.md` 「Files you can delete after
copying」의 경로)은 없어도 된다.
- **짝 백엔드 경로:** `clean-architecture-backend-template/<경로>` 꼴의 경로와 그 repo로 나가는 링크는 옆 checkout이
있을 때만 확인한다. 없으면 실패가 아니라 "확인 못 함"으로 남긴다. 옆 checkout이 다른 커밋이면 실패한다. desktop의 옆
백엔드 checkout은 pin과 다른 커밋이라, desktop에서는 백엔드 참조 몇 곳 때문에 실패할 수 있다(1105 README 11.1절,
1105/12-02). 그때는 실패가 그 참조뿐인지 확인해 적는다.
- **도는 곳:** FE-GATE-017은 documentation 단계라 merge 체인 밖이다. 그러나 같은 검사가 merge 게이트 안에서도 돈다.
`tests/unit/documentation-readiness.test.ts`가 문서를 복사해 검사를 돌리고(FE-GATE-005), 기능을 지우거나 더한 사본을
만드는 FE-GATE-020의 두 드릴(`test:sample-removal`, `test:feature-scaffold`)도 문서를 복사해 돌린다
(`scripts/lib/removal-fixture.ts` 50~60줄). 그래서 §1 문서의 경로 하나가 틀리면 merge가 막힌다.
- **샘플과 함께 지워지는 경로는 새 문서에서 이름으로 쓰지 않는다.** 참조 기능 폴더, 그 기능의 테스트, 기능 모양
기준선 파일과 측정 스크립트 같은 것이다(목록: `scripts/test-sample-removal.ts`의 머리말과 `SAMPLE_EXTRAS`). 백틱으로
쓰면 샘플 제거 사본에서 "없는 경로"가 되어 FE-GATE-020이 실패한다. 백틱을 빼면 그 경로가 검사 밖으로 나간다. 1103
조치가 참조 기능 경로 26줄을 백틱 밖으로 옮긴 것이 검사 약화로 기록됐다(1105/14-03, Low·P3, 미조치). 그래서 그
경로를 소유한 문서의 절을 가리킨다(예: 06장 1절).
- **돌리는 법:** `corepack pnpm verify:documentation`. 옆 checkout 없는 임시 worktree에서 `pnpm`으로 돌리면 pnpm이
`node_modules` 재설치를 시도하다 멈춘다. 그런 곳에서는 `node scripts/verify-documentation-readiness.ts`로 직접
돌린다(1105 README 11.5절).
- 문서 관련 unit 테스트: `tests/unit/documentation-readiness.test.ts`, `tests/unit/deletable-history-documents.test.ts`,
`tests/unit/changelog-review-ids.test.ts`.
## 7. 소유자 환경
이 절은 이 repo 소유자의 기계에 묶인 규칙이다. 복사한 프로젝트는 이 절을 자기 환경으로 바꾼다(README 결정 M-4).
출처: 2026-11-05 사용자 지시와 그날의 실행 기록(1105 README 11절).
- **테스트·게이트는 노트북에서 돌리지 않는다.** 노트북은 다른 작업과 함께 돌아 전체 테스트에 죽는다. `ssh desktop`의
/home/donghyeon/workspace/clean-architecture-frontend-template 에서 돌린다.
- **변경은 git으로 보낸다.** push하지 않은 브랜치는 노트북에서 직접 보낸다. remote는 더하지 않는다.
```bash
git push desktop:/home/donghyeon/workspace/clean-architecture-frontend-template <branch>:refs/heads/<branch>
```
보내기 전에 desktop에서 `git status`가 비었는지 본다. 바뀐 파일이 있으면 덮어쓰지 말고 먼저 확인한다.
- **PATH.** 비대화형 ssh에는 node가 없다. `export PATH=$HOME/.nvm/versions/node/v24.14.0/bin:$PATH`를 먼저 한다.
- **잠금.** 무거운 실행은 `flock /tmp/claude-gates/heavy.lock`으로 감싸 하나씩 돌린다. 백엔드 세션도 같은 desktop에서
같은 잠금을 쓴다.
- **merge 단계 runner.** desktop의 /tmp/claude-gates/run-merge-stage.sh 가 3절의 env를 넣고 게이트마다 잠금 아래
`ci:gate`를 돌려 `summary.txt`와 게이트별 로그를 남긴다. `GATES="005 008"`처럼 일부만 돌릴 수 있다. 오래 걸리므로
`nohup setsid`로 띄우고 끝나기를 기다린다.
- **끝나면 되돌린다.** 다른 세션도 같은 checkout을 쓴다. 실행이 끝나면 checkout을 처음 브랜치로 되돌리고
`git status`가 비었는지 본다.
- **노트북에서 꼭 돌려야 하면** main checkout이 아니라 깨끗한 복제본(`git clone --no-hardlinks`, 그 뒤
`corepack pnpm install --frozen-lockfile --offline`)에서 돌린다. 노트북은 inotify 감시가 부족해 vite가 들어가는
게이트에 `CHOKIDAR_USEPOLLING=1`을 준다. 시스템 한도는 바꾸지 않는다.
## 지금 이해하면 되는 것
- 커밋 전 8개, 통합 때 5개 더, merge 판정은 `ci:gate`로 14개를 workflow env(`CI=true` 포함)로.
- 다시 돌려 통과한 것은 통과가 아니다. 원인을 찾고, 고친 뒤 연속 실행으로 확인한다.
- 실행은 desktop에서, 잠금 아래에서, 끝나면 checkout을 되돌린다.
+123
View File
@@ -0,0 +1,123 @@
# 08. 결정과 기록
## 핵심
결정은 **한 번 하고, 한 곳에 적고, 다시 묻지 않는다.** 이 repo의 결정은 리뷰 README·`SPEC.md`·ADR에 흩어져 있다.
이 장은 그 결정들의 **색인**이다. 원문은 옮기지 않고 출처만 단다(README 결정 M-6).
```text
리뷰가 선택지를 낸다 → 리뷰 README 「결정이 필요한 것」
소유자가 고른다 → 같은 README 「조치」의 결정 표 (또는 SPEC.md 「결정」, ADR)
이 장의 색인에 한 줄 → 다음 작업은 여기부터 찾는다
```
## 1. 결정을 적는 곳
| 결정의 종류 | 적는 곳 | 형식 |
| --- | --- | --- |
| 리뷰 중 나온 선택 | 리뷰 README 「결정이 필요한 것」 | 번호·결정·선택지·관련 발견·결정할 사람(1103 README 6절, 1105 README 7절) |
| 그 선택을 고른 것 | 같은 README 「조치」 절의 결정 표 | 번호·고른 것·이유(1103 README 14.2절). 버린 대안이 있으면 함께(1101 README 14.1절) |
| 수정 라운드 전체의 기본값 | `SPEC.md` 「결정」 표 | ID·대상·결정(`SPEC.md` 39~63줄) |
| 오래 가는 구조·기술 선택 | `docs/architecture/decisions/VD-*.md` | 상태·결정일·맥락·결정·대안 |
| 규칙의 예외 | 그 규칙의 `comment`(이유·담당·재검토 조건) | `docs/architecture/layers.md` 104~117줄 |
| 다운스트림에 보이는 변경 | `CHANGELOG.md` 미출시 절 | 동기화 단위의 순 변경 요약(1103 README 14.2절 D5) |
| 한 커밋 안의 선택 | 커밋 본문 「고른 방법과 버린 대안」 | 커밋 규칙 3.3절 |
| 이 매뉴얼을 만들며 정한 것 | 이 매뉴얼 README 「결정 기록」 | M-1~ |
## 2. 결정 표에 들어갈 것
- **고른 것과 이유.** 이유는 "더 낫다"가 아니라 무엇을 지키는지로 쓴다.
- **버린 대안과 버린 이유.** 다음 사람이 같은 대안을 다시 꺼내지 않게 한다.
- **확인한 사실 / 기록된 의도 / 추론을 나눈다**(가이드 41.3절). 확인하지 않은 것은 "미확인"이라고 쓴다. 다운스트림
파일을 열지 않고 이름으로 추정한 문장이 CHANGELOG에 틀린 이행 안내로 남은 적이 있다(1103/14-02).
- **재검토 조건.** 어떤 규모·버전·계약 변화가 결론을 바꾸는지.
## 3. 결정을 다시 묻지 않는다
1. 결정이 필요해 보이면 먼저 아래 4절 색인과 가장 최근 리뷰 README의 결정 절을 찾는다.
2. 이미 정했으면 따른다. 상황이 바뀌어 뒤집어야 하면 새 결정으로 적고 옛 결정을 가리킨다. 옛 기록을 고치지 않는다.
3. 정한 적이 없으면 5절 형식으로 결정 대기를 만든다. 스스로 정하지 않는다. 다만 사용자가 위임한 범위 안에서는
총괄이 정하고 그 위임 문장을 출처로 적는다(예: 1101 README 14절 머리말 "결정 대기 부분을 지금 바로 결정하고
처리").
## 4. 결정 색인
「출처」의 리뷰 README는 `docs/reviews/<날짜>-maturity-review/README.md`다. 「repo 밖」은 소유자 지시가 세션 기록과
작업 메모에만 있던 것이다. 이 매뉴얼의 해당 장이 그 규칙의 repo 안 기록이 된다.
### 4.1 작업 방식 (소유자 지시)
| # | 날짜 | 결정 | 출처 | 이 매뉴얼 |
| --- | --- | --- | --- | --- |
| O-1 | 2026-09-16 | 이 repo는 템플릿이다. 소비자 없는 코드와 빈 레지스트리는 확장 지점이지 죽은 코드가 아니다 | `CLAUDE.md` 19줄 | 03장 2절 |
| O-2 | 2026-09-16 | adapter 배럴을 공개 경계로 만든다(배럴 폐지안 기각) | `CLAUDE.md` 20줄, `docs/architecture/layers.md` 119줄 | 03장 2절 |
| O-3 | 2026-09-16 | 갈라진 IndexedDB 복사본은 kernel(`src/adapters/platform/`)로 모은다. 새 파일 단위 예외를 만들지 않는다 | `CLAUDE.md` 21줄, `SPEC.md` 34줄 | 03장 2절 |
| O-4 | 2026-11-01 | 커밋·PR은 커밋 규칙 문서를 따른다. AI 꼬리말(`Co-Authored-By: Claude`, 세션 링크, "Generated with Claude Code")은 어디에도 넣지 않는다 | 커밋 규칙 0·3.4절(repo 밖) | 5절 |
| O-5 | 2026-11-03 | merge 가능 판정은 `ci:gate`로 merge 단계 14개를 workflow env로 돌려서 한다. 고른 스크립트 목록으로 판정하지 않는다 | repo 밖. 실행 기록은 1103 README 14.5절 | 07장 3절 |
| O-6 | 2026-11-03~05 | 리뷰 발견은 Low까지 고쳐 "남은 문제 0"으로 보고한다. 못 고치는 것은 결정 대기로 이유와 함께 남긴다 | repo 밖 | 09장 5.3절 |
| O-7 | 2026-11-03~05 | 리뷰·수정에 스킬을 쓴다 | repo 밖 | 01장 0절 |
| O-8 | 2026-11-03~05 | 총괄 세션은 하위 세션에 일을 맡긴다 | repo 밖 | 09장 1절 |
| O-9 | 2026-11-04 | 수정 → 리뷰를 반복한다. 새 High 0·새 P1 0·merge 게이트 14개 통과면 그 라운드의 Medium·Low를 고치고 멈춘다. 세 라운드를 더 돌아도 닿지 않으면 멈추고 이유를 보고한다 | repo 밖 | 09장 5절 |
| O-10 | 2026-11-05 | 테스트·게이트는 노트북에서 돌리지 않고 desktop checkout에서 돌린다 | repo 밖 | 07장 7절 |
| O-11 | 2026-11-05 | 리뷰 중 실행은 게이트를 한 번 돌리고 산출물을 함께 읽는다. 추가 실험은 목록으로 모아 같은 명령은 한 번만, 실험마다 작업 폴더를 되돌리며 일괄로. 작업 폴더 복제본을 늘려 해결하지 않는다 | 1105 README 11.4절 | 09장 4절 |
| O-12 | 2026-11-05 | 멈춤 기준은 repo마다 자기 정본을 따른다(「각자 유지」) | repo 밖(백엔드 세션 전달) | 09장 5.2절 |
| O-13 | 상시 | 짝 백엔드 repo는 읽기만 한다. stage·commit·push하지 않는다 | 1103 README 14.2절 D1 「이유」 | 09장 1절 |
| O-14 | 상시 | 리뷰에서는 코드를 고치지 않는다 | `CLAUDE.md` 15줄 | 01장 1절 |
### 4.2 기술 결정 (리뷰 라운드)
| 묶음 | 날짜 | 무엇을 정했나 | 출처 |
| --- | --- | --- | --- |
| 0925 수정 라운드 기본값 D-1~D-19 | 2026-09-25 | 결과 불명 intent 보관과 같은 키 재전송(D-1), 효과 분류 선택 필드(D-2), Web Lock 직렬화(D-3·D-4), 확인 못 한 판정은 `UNVERIFIED`(D-14), 문서 색인(D-16), 규모 측정은 실제 모양 기능 25·100개(D-18) 등 | `SPEC.md` 45~63줄 |
| 0929 결정이 필요한 것 7건 | 2026-09-29 | 확장 지점 범위, 409 분류, `x-correlation-id`, fanout 검사, remediation 원장, cross-context kernel 예외, 리뷰 게이트 목록에 `test:system`. 그 라운드에서는 정하지 않았다 | 0929 README 111~121줄 |
| 1101 결정 표 | 2026-11-03 | 확장 지점을 템플릿이 연다, design-system side effect 없음, raw mutation 입력을 공개 훅에서 뺌(BREAKING), 빠른 계층 quarantine 없음 유지(10-04), OPFS 여러 페이지 purge 등 24행 | 1101 README 414~445줄 |
| V2 HTTP 경로 삭제 | 2026-11-03 | HTTP 실행은 V3 하나. 지운 V2 동작의 판정 | 1101 README 602~627줄, 1103 README 3절 |
| 1103 결정 D1~D6 | 2026-11-04 | 짝 업로드는 Fileserver multipart client(D1), 업무 거절은 operation 단위 `refusedBeforeWrite` code 목록(D2), 시각 테스트는 기능 영역을 가리고 찍음(D3), 접근성 e2e 응답 모양(D4), CHANGELOG는 순 변경 요약(D5), 짝 계약은 pin 파일 + 답 표 대조 + drift 검사(D6) | 1103 README 507~516줄 |
| WebKit preload 경고(1103/11-09) | 2026-11-05 | 경고 문구 하나만 무시하고 preload 사용을 세 엔진에서 직접 검사한다(선택지 C) | 커밋 `aad005cb`, 1103 README 14.7절 |
| 구조·기술 ADR | 2026-07-26~28 | `VD-01`~`VD-30`(빈 번호 있음) | `docs/architecture/decisions/` |
## 5. 결정 대기 쓰는 법
못 고치는 발견은 이 형식으로 남긴다. 이 형식을 채우지 못하면 결정 대기가 아니라 미완이다.
| 칸 | 내용 |
| --- | --- |
| 번호·관련 발견 | 예: D4, 1105/12-01 |
| 왜 고치지 못하나 | 예: 러너 전제를 바꾸는 일이라 소유자 결정이 필요하다 |
| 선택지 | 권하는 안을 먼저. 각 안의 비용과 위험 |
| 결정할 사람 | 프론트 소유자 / 두 repo 소유자 / 백엔드 소유자 + reviewer 등 |
| 결정 전까지 | 임시 처리와 보고 방법(예: 07장 3.2절의 FE-GATE-013 기록 방법) |
### 5.1 지금 열린 결정 대기
4라운드 리뷰(1105) 시점이다. 다음 라운드가 닫거나 새로 열면 이 표를 고친다.
| 번호 | 결정 | 관련 | 결정할 사람 | 출처 |
| --- | --- | --- | --- | --- |
| D1 | 운영 advisory 2건(zod·react-router). zod 갱신은 초기 JS 예산을 넘긴다 | 1103/13-03, 1105/13-01 | 프론트 소유자 + reviewer | 1103 README 14.7절, 1105 README 7절 |
| D2 | 플랫폼 구성 화면을 진단 화면으로 인정할지, 기능으로 옮기고 다시 잴지 | 1103/09-04 | 프론트 소유자 | 같음 |
| D3 | 백엔드 생성기의 목록 GET | 1103/03-07 | 두 repo 소유자 | 같음 |
| D4 | FE-GATE-013의 러너 전제(비특권 user namespace) | 1105/12-01 | 프론트 소유자 | 1105 README 7절 |
| D5 | 제품 merge 검사와 release의 관계 | 1105/13-02 | 프론트 소유자 | 같음 |
| D6 | 실행 격리: 실행별 출력·빈 포트, 또는 "한 checkout 한 실행" 명시 | 1105/12-04 | 프론트 소유자 | 같음 |
## 6. 커밋·PR
정본은 repo 밖 `design-docs/conventions/commit-and-pr.md`다. 이 repo에서 덧붙이는 것만 적는다.
- **제목:** `type(scope): 설명`. 설명은 한국어 현재형 "~한다", 마침표 없이, 72자 이하(커밋 규칙 3.2절). 작업 단계 이름
(`라운드 4`, `wave 1`)은 scope로 쓰지 않는다.
- **발견 ID:** 커밋 메시지에 발견 ID를 적는다(`SPEC.md` 36줄). 꼬리말 `Refs: 1103/11-07`처럼 라운드 접두어를 붙인다
(커밋 규칙 3.4절, 가이드 36.3절).
- **CHANGELOG의 리뷰 ID**도 `MMDD/NN-MM` 꼴이어야 한다. `tests/unit/changelog-review-ids.test.ts`가 검사한다.
- **호환을 깨는 변경:** type 뒤 `!`와 `BREAKING CHANGE:` 꼬리말(커밋 규칙 3.2절).
- **본문:** 문제 → 고른 방법과 버린 대안 → 위험·한계 → 검증(커밋 규칙 3.3절). 결함 수정은 「위험·한계」에 그 수정이 새로
가정하는 것을 적는다(01장 2절).
- **AI 꼬리말 금지:** 4.1절 O-4.
- **push·PR:** 수정 세션은 하지 않는다. 총괄이나 리뷰를 맡긴 세션이 한다(09장 6절).
## 지금 이해하면 되는 것
- 결정이 필요해 보이면 이 장 4절과 최근 리뷰 README부터 찾는다. 이미 정한 것은 다시 묻지 않는다.
- 못 고치는 발견은 5절 형식의 결정 대기로 남긴다. 형식을 못 채우면 미완이다.
- 커밋에는 `Refs: MMDD/NN-MM`, AI 꼬리말은 없다.