Files
clean-architecture-frontend…/docs/work/reference/decisions.md
T
DongHyeonka 5757742ed0 docs(work): 하네스 문서를 새 문서 위치와 검사 범위에 맞춘다
문제: 하네스 PR #13이 더한 작업 매뉴얼·규칙은 이 브랜치가 바꾼 문서
체계의 옛 모습을 적는다.
- 옛 경로: `docs/architecture/decisions/`, `docs/superpowers/`, 루트
  `SPEC.md`, 목표 설계였던 `docs/testing/frontend-platform-testing-strategy.md`
- 옛 검사 범위: 「docs/README.md 1절이 링크한 문서, 폴더 링크는 바로 아래
  .md만」. 지금 verify:documentation은 살아 있는 문서 전부를 보고 언어·
  문체·숫자·머리 블록도 본다
- 옛 docs/README.md 절(1절 묶음 / 2절 목표 설계 / 3절 작업 이력)과 README
  절 이름(「Support scope」, 「Updating a copied project」)
- #13의 template-contract-documents 시험은 README 지워도 되는 표를
  `docs/superpowers/` 행으로 찾는데, 그 행은 이제 없다

고른 방법: 그 줄만 새 위치·새 절 이름·새 범위로 고친다(.claude/rules/docs.md,
docs/work의 docs-writing·operate·research-design·reference 다섯,
docs/problem-statement.md). 시험은 `docs/history/` 행으로 표를 찾는다.
docs/work/evidence.md는 백엔드처럼 매뉴얼 규칙의 근거 기록이라 고치지 않고
`HISTORY_HOLDERS`에 넣어 참조·숫자 검사에서 뺀다.

위험: 하네스 문서의 다른 문장은 건드리지 않았다. 하네스 세션이 쓴 뜻을
바꾸지 않으려는 것이다.

검증: 문서 검사 여섯이 0건, `git grep -n -E 'docs/superpowers|architecture/decisions'`가
기록·CHANGELOG·출처 표시 밖에서 0건.
2026-11-11 20:55:32 +09:00

11 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절
구조·기술 결정 기록 2026-07-26~ VD-01~(빈 번호 있음) docs/adr/

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