Files
clean-architecture-frontend…/docs/work/reference/decisions.md
T
DongHyeonka 18ea5e939b docs(work): cold-read 시험에서 막힌 곳과 사실과 다른 곳을 고친다
이 대화를 모르는 서브에이전트에게 AGENTS.md부터 읽혀 두 일(새 기능
만들기, diff 리뷰)의 절차를 쓰게 했다. 막힌 곳 16, 사실과 다른 곳 5가
나왔다. 고친 것:

- new-feature: 생성·기준선 다시 쓰기를 desktop에서 하고 --apply-back으로
  받는다. FE-GATE-020은 제품 기능을 지우지 않으므로 그 기능의 제거
  드릴을 따로 돌린다(사실과 달랐다). 생성 명령이 만드는 첫 context는
  중간이다. 새 기능은 FE-GATE-026도 돌린다. 매뉴얼 예시 이름이 오면
  묻는다. 초기 JS 기록의 파일을 적는다.
- gates·improve·AGENTS: FE-GATE-013 결정 대기 동안의 merge 판정 문구,
  PR·diff 리뷰도 merge 단계 전부를 돌린다, diff 리뷰의 base·head 규칙과
  ID 체계와 둘 곳, 라운드 세는 법, "빠른 게이트 8개"를 "검사 8개
  (package script)"로.
- review-criteria: 발견 한 개의 칸(가이드 36.3절 줄임)과 통제 M0~M4·
  증거 E0~E4의 뜻을 옮긴다. 가이드 없이 판정할 수 있다는 문장을 맞춘다.
- README·CLAUDE·decisions·rules/docs·skills: 최근 리뷰 README의 실제 절
  이름, 사고 순서 흔적의 여섯 칸과 design-docs 위치, 보고 칸과 말투의
  정본, `docs/work/README.md`를 가리키게, 리뷰 README 조치 절 예외,
  스킬의 새 명령 모양.

고치지 않은 것: 세션에 주입된 옛 CLAUDE.md(시험 세션이 이 브랜치 전에
시작했다).

검증: scripts/verify.sh docs rc=0, scripts/verify.sh hooks 통과.
2026-11-08 17:53:36 +09:00

11 KiB

결정 색인

결정은 한 번 하고, 한 곳에 적고, 다시 묻지 않는다. 이 repo의 결정은 리뷰 README·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절
구조·기술 결정 기록 2026-07-26~ VD-01~(빈 번호 있음) docs/architecture/decisions/

3. 결정 대기 쓰는 법

못 고치는 발견은 이 형식으로 남긴다. 이 형식을 채우지 못하면 결정 대기가 아니라 미완이다.

칸 내용
번호·관련 발견 예: D8, 1105/12-01
왜 고치지 못하나 예: 러너 전제를 바꾸는 일이라 소유자 결정이 필요하다
선택지 권하는 안을 먼저. 각 안의 비용과 위험
결정할 사람 프론트 소유자 / 두 repo 소유자 / 프론트 소유자 + reviewer 등
결정 전까지 임시 처리와 보고 방법(예: gates.md 3절의 FE-GATE-013 기록 방법)
재검토 조건 어떤 규모·버전·계약 변화가 결론을 바꾸나

결정 표에 들어갈 것: 고른 것과 이유(무엇을 지키는지로), 버린 대안과 버린 이유, 확인한 사실 / 기록된 의도 / 추론의 구분, 재검토 조건.

3.1 지금 열린 결정 대기

2026-11-06 리뷰(1106) 시점이다. 다음 라운드가 닫거나 새로 열면 이 표를 고친다.

번호 결정 관련 결정할 사람 출처
D1 운영 advisory 2건(zod·react-router). zod 갱신은 초기 JS를 약 7 KB 늘린다 1103/13-03 프론트 소유자 + reviewer 1106 README 7절
D2 플랫폼 구성 화면을 진단 화면으로 인정할지, 기능으로 옮기고 다시 잴지 1103/09-04 프론트 소유자 같음
D3 백엔드 생성기의 목록 GET 1103/03-07 두 repo 소유자 같음
D8 FE-GATE-013을 멈춤 기준에서 어떻게 셀지(호스트 제약 실패로 제외 / 다른 러너에서 통과할 때까지 미충족) 1105/12-01 소유자 같음
D11 생성 기능 설치 상태의 브라우저 merge 게이트 1105/16-03 템플릿 담당 같음
D6(1105) 실행 격리: 실행별 출력·빈 포트, 또는 "한 checkout 한 실행" 명시. ci:gate 두 실행은 아직 같은 dist·artifacts/를 쓴다 1105/12-04 프론트 소유자 1105 README 7절, 1106 README 2.3절

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절의 칸을 쓰고 「위험과 영향」과 「검증」은 비우지 않는다. 병합은 소유자가 한다.