FE-GATE-028이 대조할 후보 ID를 정했다. 처음 생각한 후보 release manifest의 releaseId는 FE-GATE-028(release_gate) 때 후보가 아직 없고 run마다 달라 쓸 수 없다(w2-fe-2 지적). 원 발견의 권하는 방향대로 릴리스 태그를 release 단계 env RELEASE_TAG로 받고, 비면 실패한다. 검사는 그룹 A5, workflow는 w2-fe-2가 맞춘다. Refs: 1112/05-01
19 KiB
결정 색인
결정은 한 번 하고, 한 곳에 적고, 다시 묻지 않는다. 이 repo의 결정은 리뷰 README·docs/history/plans/2026-09-25-review-fix-round/SPEC.md(2026-09-25 수정 라운드의 기본값)·결정 기록에 흩어져 있다. 이 문서는 그 결정들의 색인이다. 원문은 옮기지 않고 출처만 단다(원문을 옮겨 쓰면 갈라진 복사본이 된다).
리뷰가 선택지를 낸다 → 리뷰 README 「결정이 필요한 것」
소유자가 고른다 → 같은 README 「조치」의 결정 표 (또는 SPEC.md 「결정」, 결정 기록)
이 색인에 한 줄 → 다음 작업은 여기부터 찾는다
1. 결정을 다시 묻지 않는 규칙
- 결정이 필요해 보이면 먼저 2절 색인과 가장 최근 리뷰 README의 결정 절을 찾는다.
- 이미 정했으면 따른다. 상황이 바뀌어 뒤집어야 하면 새 결정으로 적고 옛 결정을 가리킨다. 옛 기록을 고치지 않는다.
- 정한 적이 없으면 3절 형식으로 결정 대기를 만든다. 스스로 정하지 않는다. 다만 소유자가 위임한 범위 안에서는 총괄이 정하고 그 위임 문장을 출처로 적는다.
- 다시 열 수 있는 것은 결정의 전제가 틀렸다는 새 증거가 있을 때뿐이다. 그 증거와 재검토 조건을 함께 적는다.
2. 색인
「출처」의 리뷰 README는 docs/reviews/<날짜>-maturity-review/README.md다. 「repo 밖」은 소유자 지시가 세션 기록과 작업 메모에만 있던 것이다. 이 매뉴얼의 해당 절이 그 규칙의 repo 안 기록이다.
2.1 작업 방식 (소유자 지시)
| # | 날짜 | 결정 | 출처 | 이 매뉴얼 |
|---|---|---|---|---|
| O-1 | 2026-09-16 | 이 repo는 템플릿이다. 소비자 없는 코드와 빈 레지스트리는 확장 지점이지 죽은 코드가 아니다 | 옛 루트 CLAUDE.md 리뷰 전제 |
AGENTS.md 첫 문단, structure.md 2절 |
| O-2 | 2026-09-16 | adapter 배럴을 공개 경계로 만든다(배럴 폐지안 기각) | 옛 CLAUDE.md, docs/architecture/layers.md |
꼭 지킬 것 1 |
| O-3 | 2026-09-16 | 갈라진 IndexedDB 복사본은 kernel(src/adapters/platform/)로 모은다. 새 파일 단위 예외를 만들지 않는다 |
옛 CLAUDE.md, SPEC.md 공통 완료 기준 6 |
꼭 지킬 것 2 |
| O-4 | 2026-11-01 | 커밋·PR은 design-docs conventions/commit-and-pr.md를 따른다. AI 꼬리말은 어디에도 넣지 않는다 |
repo 밖 | docs/work/README.md 4절 |
| O-5 | 2026-11-03 | merge 가능 판정은 ci:gate로 merge 단계 전부를 workflow env로 돌려서 한다. 고른 스크립트 목록으로 판정하지 않는다 |
repo 밖. 실행 기록은 1103 README 14.5절 | gates.md 3절 |
| O-6 | 2026-11-03~05 | 리뷰 발견은 Low까지 고쳐 "남은 문제 0"으로 보고한다. 못 고치는 것은 결정 대기로 이유와 함께 남긴다 | repo 밖 | improve.md 4.5절 |
| O-7 | 2026-11-03~05 | 리뷰·수정에 스킬을 쓴다 | repo 밖 | improve.md 3절 |
| O-8 | 2026-11-03~05 | 총괄 세션은 하위 세션에 일을 맡긴다 | repo 밖 | delegate.md |
| O-9 | 2026-11-04 | 수정 → 리뷰를 반복한다. 새 High 0·새 P1 0·merge 단계 통과면 그 라운드의 Medium·Low를 고치고 멈춘다. 1103 수정 라운드 뒤로 세 라운드를 더 돌아도 닿지 않으면 멈추고 이유를 보고한다 | repo 밖 | improve.md 4.5절 |
| O-10 | 2026-11-05 | 테스트·게이트는 노트북에서 돌리지 않고 desktop에서 돌린다 | repo 밖 | operate.md 4.1절 |
| O-11 | 2026-11-05 | 리뷰 중 실행은 게이트를 한 번 돌리고 산출물을 함께 읽는다. 추가 실험은 목록으로 모아 같은 명령은 한 번만, 실험마다 작업 폴더를 되돌리며 일괄로. 작업 폴더 복제본을 늘려 해결하지 않는다 | 1105 README 11.4절 | delegate.md 4.2절 |
| O-12 | 2026-11-05 | 백엔드와 다른 종료 조건을 각자 유지한다(「각자 유지」). 백엔드는 발견 0까지 확인 리뷰를 반복하고, 프론트는 O-9대로 한다 | repo 밖(백엔드 총괄 전달) | improve.md 4.5절 |
| O-13 | 상시 | 짝 백엔드 repo는 읽기만 한다. stage·commit·push하지 않는다 | 1103 README 14.2절 D1 「이유」 | delegate.md 4.3절 |
| O-14 | 상시 | 리뷰에서는 코드를 고치지 않는다 | 옛 CLAUDE.md |
review-criteria.md 1절 |
| O-15 | 2026-11-05 | 수정 결과의 「고침」을 그대로 믿지 않는다. 다음 리뷰에서 ID별로 다시 판정한다 | repo 밖. 근거 사례 1105 README 3.1절 | improve.md 4.5절 |
| O-16 | 2026-11-05 | 큰 라운드는 작은 PR로 나눈다(커밋 규칙 5.1절). 소유자가 PR을 merge한다 | repo 밖 | improve.md 4.4절 |
| O-17 | 2026-11-07 | Claude Code 하네스를 자료(제작 책임자가 권하는 방식)대로 적용한다: 루트 AGENTS.md 정본(40줄 이하) + CLAUDE.md가 가져오기, 경로별 규칙 .claude/rules/, 모델이 부르는 스킬(설명에 발동 조건), repo 훅은 넛지 위주, 검증 진입점 scripts/verify.sh, 장부 docs/ledger/estimates.jsonl |
design-docs harness/01-harness-design.md 13절 |
이 매뉴얼 전체 |
| O-18 | 2026-11-07 | Agent 금지를 두지 않는다. 결과만 받는 일(검색, 구조 리뷰, 실행 검증, 단순화 제안)은 서브에이전트, 파일을 바꾸고 소유자가 열어 보고 멈출 수 있어야 하는 위임은 하위 세션이다 | 같은 문서 13절 Q5 | delegate.md 4.3절 |
| O-19 | 2026-11-07 | 루트 AGENTS.md·CLAUDE.md(와 .claude/, docs/work/)는 템플릿 계약이다. 복사한 프로젝트가 받는다. 지워도 되는 문서 목록에 넣지 않는다 |
같은 문서 13절 Q4 | structure.md 4절, operate.md 4.4절 |
| O-20 | 2026-11-08 | 프론트 편집 훅은 노트북에서 표준 라이브러리 정적 검사만 한다. 포맷·린트·타입은 desktop scripts/verify.sh에서 돈다. 설계 13절 Q6(편집 훅에서 한 파일 포맷·린트)과 다른 점은 프론트 린터가 pnpm·node_modules를 써서 "pnpm은 desktop에서만"(O-10)과 부딪치기 때문이다 |
하네스 적용 brief(백엔드 총괄, 2026-11-08) | scripts/hooks/README.md |
2.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 「결정」(문서 체계 정리 뒤에는 docs/history/로 옮겨진다) |
| 0929 결정이 필요한 것 7건 | 2026-09-29 | 확장 지점 범위, 409 분류, x-correlation-id, fanout 검사, remediation 원장, cross-context kernel 예외, 리뷰 게이트 목록에 test:system |
0929 README |
| 1101 결정 표 | 2026-11-03 | 확장 지점을 템플릿이 연다, design-system side effect 없음, raw mutation 입력을 공개 훅에서 뺌(BREAKING), 빠른 계층 quarantine 없음 유지, OPFS 여러 페이지 purge 등 24행 | 1101 README 14절 |
| V2 HTTP 경로 삭제 | 2026-11-03 | HTTP 실행은 V3 하나. 지운 V2 동작의 판정 | 1101 README, 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 「조치」 |
| WebKit preload 경고(1103/11-09) | 2026-11-05 | 경고 문구 하나만 무시하고 preload 사용을 세 엔진에서 직접 검사한다 | 1103 README 14.7절 |
| 1105 결정 D7 | 2026-11-05 | 초기 JS 예산을 204,800 B에서 206,848 B로 올린다 | 1105 README 16.2절 |
| 1106 결정 D9·D10 | 2026-11-06 | 초기 JS 예산 206,848 B를 그대로 두고 근거·되돌림 규칙을 docs/operations/performance-evidence.md에 둔다(D9). 결과 불명 KEYED 재전송이 쓰기 전 거절로 끝나도 훅이 결과 불명과 키를 지킨다. 재전송의 거절이 결과 불명을 푸는 것은 짝 백엔드 표의 code뿐이다(D10과 보완 둘, 판정 src/contracts/errors.ts isRefusedOnEveryAttempt) |
1106 README 16.2절 |
| 결정 D8 FE-GATE-013 판정 | 2026-11-12 | desktop에서 FE-GATE-013의 실패가 사전 점검의 user namespace 제한(bwrap) 하나뿐이고 scripts/verify.sh parts FE-GATE-013의 뒤 명령이 모두 rc=0이면, merge 판정에서 그 실패를 호스트 원인으로 빼고 센다. 게이트 「충족」은 조건을 갖춘 runner에서 FE-GATE-013이 통과한 것으로만 센다. 버린 안: runner에서 통과할 때까지 merge 판정을 미충족으로 두기(그 runner가 아직 없어 모든 PR의 merge 판정이 막힌다). 재검토: 조건을 갖춘 runner가 merge 단계를 돌게 되면 desktop 예외가 아직 필요한지 다시 본다. 판정 방법은 gates.md 3절 |
소유자 결정 e(2026-11-11, 「그 조건이 되는 실행 환경을 찾아 초록으로」)에 따라 총괄이 권하는 안으로 정함(2026-11-12, repo 밖). 관련 발견 1105/12-01 |
| 검사기 자기 시험의 단계 | 2026-11-07 | 검사기 자기 시험(*:fixture 15개)과 check:ci:gating을 merge에서 main 단계 FE-GATE-029로 옮기고, CI 계약 기준선 파일을 지운다. 버린 안: merge에 두기(PR마다 같은 자기 시험을 돈다). 위험: 검사기를 깨는 PR이 main에서야 빨개진다. 그래서 검사 script를 고치면 merge에 더해 FE-GATE-029를 돌린다(.claude/rules/gates-and-budgets.md) |
소유자 승인, 커밋 f6b2b96c 본문, docs/operations/ci-quality-gates.md 머리, round9 1112/08-14 |
| round9 R9-D1 결과 불명 상태의 소유 | 2026-11-12 | 권하는 안으로 정함(2026-11-12, 총괄). useAppForm이 코디네이터의 결과 불명 상태를 받는 선택 옵션을 갖고(추가만), 생성 작성 페이지가 그것을 쓴다. 이미 생성한 기능은 CHANGELOG 이행 안내. 버린 안: 문서로만 |
round9 README 7절, 1112/01-01 |
| round9 R9-D2 업로드 401 | 2026-11-12 | 권하는 안으로 정함(2026-11-12, 총괄). 템플릿 조립이 업로드 capability를 감싸 401을 V3와 같은 onCredentialRejected로 보낸다(추가만). JWT bearer는 제품 조합 계약에 선택 함수 하나. 버린 안: 매뉴얼 문장만 |
같음, 1112/07-01 |
| round9 R9-D3 파일 단위 예외 | 2026-11-12 | 권하는 안으로 정함(2026-11-12, 총괄). .dependency-cruiser.json의 파일 단위 예외를 실제 쓰임으로 좁힌다(지금 위반 0). 버린 안: 그대로 |
같음, 1112/02-02·02-03, 0929/12-03 |
| round9 R9-D4 짝 계약 pin | 2026-11-12 | 권하는 안으로 정함(2026-11-12, 총괄). pin을 짝 백엔드 main으로 옮기고 drift 5건을 대조한다. 버린 안: 문서만 pin 기준으로 | 같음, 1112/02-05·08-18 |
round9 R9-D5 loadingSurface |
2026-11-12 | 권하는 안으로 정함(2026-11-12, 총괄). 계약 값은 그대로, 매뉴얼·렌즈 문장을 실제 동작(로딩 모양을 고르지 않는 이름표)에 맞춘다. 버린 안: 닫힌 union으로 계약 변경 | 같음, 1112/04-04 |
round9 R9-D6 primitive className·style |
2026-11-12 | 권하는 안으로 정함(2026-11-12, 총괄). 공개 props는 그대로 두고 check:design-system이 호출부의 날 색·간격을 잡는다(비파괴). 버린 안: style 제거(BREAKING) |
같음, 1112/04-14 |
| round9 R9-D7 수동 접근성 후보 ID | 2026-11-12 | 권하는 안으로 정함(2026-11-12, 총괄). FE-GATE-028이 기록의 Release ID를 release 후보 ID와 대조한다. 후보 ID는 릴리스 태그다(2026-11-13 세부: release 단계 env RELEASE_TAG, 비면 실패. 빌드의 releaseId는 run마다 달라 쓰지 않는다). workflow 쪽은 CI 세션이 맞춘다. 버린 안: 그대로 |
같음, 1112/05-01 |
| round9 R9-D8 시각 골든 허용치 | 2026-11-12 | 권하는 안으로 정함(2026-11-12, 총괄). 실험으로 흔들림 없는 값을 재서 낮춘다(검사 강화). 버린 안: 그대로 | 같음, 1112/04-11 |
| round9 R9-D9 WCAG 2.2 | 2026-11-12 | 권하는 안으로 정함(2026-11-12, 총괄). axe wcag22aa 태그를 더하고, 수동 기록 양식에 2.4.11·2.5.8 칸을 더한다(생성 출력이 바뀐다, CHANGELOG 안내). 버린 안: 태그만 |
같음, 1112/05-05 |
| round9 R9-D10 예산과 advisory | 2026-11-12 | 권하는 안으로 정함(2026-11-12, 총괄). D1을 먼저 정한다: zod·react-router 갱신이 지금 초기 JS 예산 안에 들어가므로 갱신하고, 드릴을 다시 재서 D9 규칙으로 예산을 정한다. 버린 안: 예산만 먼저 내림 | 같음, 1106/15-01, 1103/13-03 |
round9 R9-D11 @a11y 두 번 실행 |
2026-11-12 | 권하는 안으로 정함(2026-11-12, 총괄). 그대로 둔다. 게이트마다 증거를 새로 만드는 계약이다. 결함 아님으로 닫는다. 버린 안: FE-GATE-009가 FE-GATE-008 결과를 쓰기 | 같음, 1112/03-10 |
| round9 R9-D12 CSS·라우트 lazy 합 예산 | 2026-11-12 | 권하는 안으로 정함(2026-11-12, 총괄). 지금 값을 기록만 하고 예산은 두지 않는다. 다시 볼 때: 첫 공개 기능 라우트 lab. 버린 안: 예산 신설 | 같음, 1101/15-03 |
| 결정 p 선택 runtime 제거 드릴을 main 단계로 | 2026-11-12 | FE-GATE-020의 선택 runtime 제거 드릴 셋(optional recipe, browser file/storage, realtime)을 새 게이트 FE-GATE-030으로 떼어 main 단계(main_gate)에서 돌린다. 기능 드릴(샘플 제거, scaffold)은 merge에 남는다. 이유: runner PR 1회 약 30분 가운데 7분쯤이고, worker를 늘리지 않고 merge 25분 목표에 닿는 길이 이것뿐이었다. 대가: 그 셋의 회귀를 병합 뒤 main run에서 본다. main이 빨강이면 다음 PR이 고친다. 짝 백엔드가 무거운 lane을 nightly로 옮긴 것과 같은 모양이다. 재검토: runner가 늘거나 드릴이 빨라져 merge에 다시 넣어도 25분 안이면 되돌린다 |
소유자 결정 p(2026-11-12, design-docs template-program/README.md 5절, W2-FE의 O1 권하는 안 채택) |
| 구조·기술 결정 기록 | 2026-07-26~ | VD-01~(빈 번호 있음) |
docs/adr/ |
3. 결정 대기 쓰는 법
못 고치는 발견은 이 형식으로 남긴다. 이 형식을 채우지 못하면 결정 대기가 아니라 미완이다.
| 칸 | 내용 |
|---|---|
| 번호·관련 발견 | 예: D8, 1105/12-01 |
| 왜 고치지 못하나 | 예: 러너 전제를 바꾸는 일이라 소유자 결정이 필요하다 |
| 선택지 | 권하는 안을 먼저. 각 안의 비용과 위험 |
| 결정할 사람 | 프론트 소유자 / 두 repo 소유자 / 프론트 소유자 + reviewer 등 |
| 결정 전까지 | 임시 처리와 보고 방법(예: gates.md 3절의 FE-GATE-013 기록 방법) |
| 재검토 조건 | 어떤 규모·버전·계약 변화가 결론을 바꾸나 |
결정 표에 들어갈 것: 고른 것과 이유(무엇을 지키는지로), 버린 대안과 버린 이유, 확인한 사실 / 기록된 의도 / 추론의 구분, 재검토 조건.
3.1 지금 열린 결정 대기
2026-11-12 리뷰(round9) 시점이다. 다음 라운드가 닫거나 새로 열면 이 표를 고친다. D8은 2026-11-12에 정해 2.2절로 옮겼다. 아래 「1106 이전 결정 대기」 행은 지난 리뷰들이 결정 대기로 남겼는데 이 색인에 없던 것이다(round9 1112/10-02). 각 행의 선택지와 권하는 안은 출처의 영역 문서에 있다.
| 번호 | 결정 | 관련 | 결정할 사람 | 출처 |
|---|---|---|---|---|
| D1 | 운영 advisory 2건(zod·react-router). zod 갱신은 초기 JS를 약 7 KB 늘린다. 2026-11-12 R9-D10(2.2절)으로 「갱신한다」로 정했다. 갱신이 들어가면 이 행을 지운다 | 1103/13-03 | 프론트 소유자 + reviewer | 1106 README 7절 |
| D2 | 플랫폼 구성 화면을 진단 화면으로 인정할지, 기능으로 옮기고 다시 잴지 | 1103/09-04 | 프론트 소유자 | 같음 |
| D3 | 백엔드 생성기의 목록 GET | 1103/03-07 | 두 repo 소유자 | 같음 |
| D11 | 생성 기능 설치 상태의 브라우저 merge 게이트 | 1105/16-03 | 템플릿 담당 | 같음 |
| D6(1105) | 실행 격리: 실행별 출력·빈 포트, 또는 "한 checkout 한 실행" 명시. ci:gate 두 실행은 아직 같은 dist·artifacts/를 쓴다 |
1105/12-04 | 프론트 소유자 | 1105 README 7절, 1106 README 2.3절 |
| R9-D13 | 매뉴얼 02 7절 업로드 예: capability 타입을 src/features/product-capabilities.ts에 적으라는 규칙(매뉴얼 03)과, 그 파일이 src/adapters/를 import하지 못하는 규칙(feature-and-app-roots-do-not-reach-adapters)이 부딪친다. 권하는 안: feature-adapter-contribution.ts(이미 type-only 예외)가 adapter 의존 타입을 다시 내보내고 product-capabilities.ts가 그것을 쓴다 |
1112/09-01 | 프론트 소유자(총괄) | round9 README 7절, 공유 노트 r9-fe-fix-plan.md |
| 1106 이전 결정 대기 | Service Worker 없는 빌드의 hosting probe 범위 | 1105/06-02 | 프론트 소유자 | 1106 README 13.4절, round9 영역 10 |
| 같음 | 500 IDEMPOTENCY_RECOVERY_REQUIRED 뒤 재전송, 선언한 409를 필드 오류로 보일 때 VD-04 결정 5의 보완 |
1103/03-01 | 프론트 소유자 | 같음 |
| 같음 | 캐시 inspect()의 signal과 "판정 불가"·"손상" 구분 |
0929/02-02 | 프론트 소유자 | 같음 |
| 같음 | 파일 정책이 media type과 확장자 짝을 볼지 | 1101/02-02 | 프론트 소유자 | 같음 |
| 같음 | .dependency-cruiser.json의 kernel 예외가 배럴 전체를 여는 것(쓰는 것은 import type 하나) |
0929/02-06 | 프론트 소유자 | 같음 |
| 같음 | SSE EOF 분류 | 0929/04-02 | 프론트 소유자 | 같음 |
| 같음 | SSE parser 동작이 설계 5.3·6.3과 다른 것 | 0929/04-03 | 프론트 소유자 | 같음 |
| 같음 | 다운스트림(memento) 모양의 check:registries와 자리 없는 파일을 템플릿에 들일지 |
1103/14-02 | 두 repo 소유자 | 1106 README 13.4절, round9 영역 11 |
| 같음 | 화면이 읽지 않는 라우트 title·navigationLabel 칸 정리 |
1103/16-06 | 프론트 소유자 | 같음 |
| 같음 | 다운스트림이 찾은 템플릿 결함 후보를 받는 곳(이슈·FOLLOW-UP)과 상태 칸 | 0929/14-06 | 프론트 소유자 | 같음 |
| 같음 | 도구·import 없는 unit 시험의 층(tests/unit 시간 대부분) |
1101/10-05 | 프론트 소유자 | 같음 |
| 같음 | 한 merge에 tests/unit이 여러 번 도는 것 |
1101/10-06 | 프론트 소유자 | 같음 |
| 같음 | 시험 helper 사본(scopeSnapshot 4벌, as never, deferred())을 모을지 |
1101/10-08 | 프론트 소유자 | 같음 |
| 같음 | ungated 목록에 owner·다시 볼 조건 칸을 둘지 | 0929/12-07 | 프론트 소유자 | 같음 |
| 같음 | lab의 기능 라우트 진입 두 묶음(생성 라우트가 모두 session-required라 lab 대상이 못 된다) |
1105/15-04 | 프론트 소유자 | 같음 |
4. 커밋·PR
정본은 repo 밖 design-docs conventions/commit-and-pr.md다. 이 repo에서 덧붙이는 것은 review-criteria.md 11절(발견 ID 꼬리말, CHANGELOG 리뷰 ID, BREAKING)과 ../README.md 4절이다. PR 본문은 그 문서 5.3절의 칸을 쓰고 「위험과 영향」과 「검증」은 비우지 않는다. 병합은 소유자가 한다.