Files
clean-architecture-frontend…/docs/work/reference/decisions.md
T
DongHyeonka 372b5237c1 docs(decisions): round9 결정과 색인 밖 결정 대기를 결정 색인에 적는다
결정 색인(docs/work/reference/decisions.md)에 빠진 것이 셋이다.

- 2026-11-07 소유자가 승인한 「검사기 자기 시험과 check:ci:gating을 main
  단계 FE-GATE-029로, CI 계약 기준선 파일 삭제」는 커밋 f6b2b96c 본문과
  ci-quality-gates.md 머리에만 있다(1112/08-14).
- 지난 리뷰가 결정 대기로 남긴 15행(1105/06-02, 1103/03-01, 0929/02-02,
  1101/02-02, 0929/02-06, 0929/04-02, 0929/04-03, 1103/14-02, 1103/16-06,
  0929/14-06, 1101/10-05, 1101/10-06, 1101/10-08, 0929/12-07, 1105/15-04)이
  3.1절 표에 없다. 그 문서 3절 규칙으로는 결정 대기가 아니라 미완이다
  (1112/10-02).
- round9가 낸 결정 R9-D1~D12는 2026-11-12 총괄이 권하는 안으로 정했다
  (소유자 상시 지시 「중간 확인 없이 권하는 안으로」). 새 결정 대기
  R9-D13이 있다.

고른 방법: 2.2절에 FE-GATE-029 단계 결정과 R9-D1~D12를 「권하는 안으로
정함(2026-11-12, 총괄)」으로 한 행씩 둔다. 3.1절에 R9-D13과 지난 15행을
더한다. D1에는 R9-D10으로 「갱신한다」로 정했다고 적는다. 선택지 원문은
옮기지 않고 출처를 단다.

위험·한계: 지난 15행은 결정이 아직 없다. 색인에 올렸을 뿐 고치지 않았다.

검증: scripts/verify.sh docs(노트북) 통과. desktop verify:documentation은
PR 본문에 적는다.

Refs: 1112/08-14, 1112/10-02
2026-11-13 00:30:19 +09:00

18 KiB

결정 색인

결정은 한 번 하고, 한 곳에 적고, 다시 묻지 않는다. 이 repo의 결정은 리뷰 README·docs/history/plans/2026-09-25-review-fix-round/SPEC.md(2026-09-25 수정 라운드의 기본값)·결정 기록에 흩어져 있다. 이 문서는 그 결정들의 색인이다. 원문은 옮기지 않고 출처만 단다(원문을 옮겨 쓰면 갈라진 복사본이 된다).

리뷰가 선택지를 낸다      → 리뷰 README 「결정이 필요한 것」
소유자가 고른다           → 같은 README 「조치」의 결정 표 (또는 SPEC.md 「결정」, 결정 기록)
이 색인에 한 줄           → 다음 작업은 여기부터 찾는다

1. 결정을 다시 묻지 않는 규칙

  1. 결정이 필요해 보이면 먼저 2절 색인과 가장 최근 리뷰 README의 결정 절을 찾는다.
  2. 이미 정했으면 따른다. 상황이 바뀌어 뒤집어야 하면 새 결정으로 적고 옛 결정을 가리킨다. 옛 기록을 고치지 않는다.
  3. 정한 적이 없으면 3절 형식으로 결정 대기를 만든다. 스스로 정하지 않는다. 다만 소유자가 위임한 범위 안에서는 총괄이 정하고 그 위임 문장을 출처로 적는다.
  4. 다시 열 수 있는 것은 결정의 전제가 틀렸다는 새 증거가 있을 때뿐이다. 그 증거와 재검토 조건을 함께 적는다.

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와 대조한다. 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
구조·기술 결정 기록 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절의 칸을 쓰고 「위험과 영향」과 「검증」은 비우지 않는다. 병합은 소유자가 한다.