Files
clean-architecture-frontend…/tasks/plan.md
T
DongHyeonkaandClaude Opus 5.5 ea0f01ff05 docs: plan fixes for src review critical and required findings
SPEC.md lists the 47 requirements (R-0, R-1.1..R-9.3) and decisions D-1..D-7.
tasks/plan.md and tasks/todo.md break them into 50 tasks across 9 lanes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-24 11:48:19 +09:00

5.6 KiB
Raw Blame History

Implementation Plan: src 리뷰 긴급·필수 항목 수정

Overview

SPEC.md의 요구사항 47개(R-0 + R-1.1 ~ R-9.3)를 작업 50개로 나눠 고친다. R-3.2, R-6.3, R-8.3은 각각 두 작업으로 쪼갰다. 작업마다 실패하는 테스트를 먼저 쓰고, 고치고, 전체 게이트를 돌리고, 커밋 하나를 만든다. 작업 목록과 완료 조건은 tasks/todo.md에 있다.

  • 브랜치: fix/src-review-2026-09-24
  • 기준 커밋: b04d570

Architecture Decisions

  • 결정 D-1 ~ D-7은 SPEC.md "결정" 표를 따른다.
  • 공용 로직은 src/adapters/platform/(kernel) 또는 src/contracts/에 둔다. 새로운 파일 단위 예외 규칙은 만들지 않는다.
  • 공개 포트는 추가만 한다. 기존 시그니처는 깨지 않는다.
  • 버그를 정상 동작으로 고정한 기존 테스트는 같은 커밋에서 고친다. 해당 테스트: tests/unit/legacy-and-optional-network-remediation.test.ts:136, tests/unit/release-mismatch-recovery.test.ts:64 부근, tests/platform/telemetry/telemetry-pipeline.test.ts:93.

실행 방식

  1. Phase 0 (순차): T01(R-0)을 먼저 끝낸다. 이게 끝나야 모든 작업에서 게이트를 돌릴 수 있다.
  2. Phase 1 (병렬 레인 9개): 영역별 레인을 독립 git worktree에서 서브에이전트가 진행한다. 각 레인은 fix/src-review-2026-09-24 HEAD(T01 반영 후)에서 갈라진다. 레인 안의 작업은 todo 순서대로 하나씩 RED → GREEN → 게이트 → 커밋한다.
  3. 통합 (순차): 레인 브랜치를 하나씩 fix/src-review-2026-09-24에 rebase·병합한다. 레인마다 병합한 뒤 전체 게이트를 돌린다(체크포인트).
  4. 최종 체크포인트: 전체 게이트, build, 깨끗한 체크아웃 재현(src/.generated 삭제 후 게이트)을 확인한다.
레인 영역 작업
A browser-transfer T02–T05
B browser-files / cache / cross-context T06–T10
C http / query-cache / auth T11–T16
D realtime T17–T20
E storage T21–T25
F service-worker / web-push T26–T33
G contracts T34–T38
H presentation T39–T47
I bootstrap / platform T48–T50

레인끼리는 파일이 거의 겹치지 않는다. 겹칠 수 있는 곳은 docs/reviews/adapters/INVENTORY.md(adapter 파일 추가 시)와 src/bootstrap/(H의 T45와 I)이다. 통합 단계에서 해결한다.

Task List (요약 — 상세는 tasks/todo.md)

Phase 0: 기반

  • T01 R-0 깨끗한 체크아웃에서 게이트 동작

Checkpoint 0

  • src/.generated 삭제 후 arch/types/lint/unit/component/verify:documentation 통과

Phase 1: 레인 A–I (병렬)

  • 레인 A: T02–T05
  • 레인 B: T06–T10
  • 레인 C: T11–T16 (고위험 T12, T13, T15 포함)
  • 레인 D: T17–T20
  • 레인 E: T21–T25 (고위험 T21, T22, T24, T25 포함)
  • 레인 F: T26–T33 (고위험 T33 포함)
  • 레인 G: T34–T38 (고위험 T37 포함)
  • 레인 H: T39–T47
  • 레인 I: T48–T50 (고위험 T50 포함)

Checkpoint 레인별 (통합할 때마다)

  • check:architecture, check:types:app, check:types:test, lint, test:unit, test:component 통과
  • adapter 파일을 바꿨으면 check:adapter-inventory 통과

Checkpoint 최종

  • 위 게이트 + corepack pnpm build 통과
  • 깨끗한 체크아웃 재현 통과
  • 리뷰 문서의 해당 항목 47개에 해결 커밋을 대응(todo 체크)

고위험 작업 (계획 승인 = 이 작업들의 사전 승인)

작업 이유 안전장치
T12, T13 (R-3.2) 세션·캐시 fence 동작이 바뀜 상태가 실제로 바뀌면 여전히 fence됨을 테스트로 고정
T15 (R-3.4) 자격증명 헤더 검증 기존 정상 토큰 통과 테스트 유지
T21, T22, T24 (R-5.1, R-5.2, R-5.4) 삭제 경로 참조 중 청크와 다른 파티션 행은 절대 지우지 않음을 테스트로 고정
T25 (R-5.5) 저장 데이터 판독 규칙 기존 manifest 객체가 정책 변경 뒤에도 읽힘을 테스트로 고정
T33 (R-6.7) 푸시 동의 크래시 복구(local ACTIVE) 재등록은 유지됨을 테스트로 고정
T37 (R-7.4) CSRF 규칙 강화 설치된 기존 operation이 모두 통과함을 확인
T50 (R-9.3) 리댁션 정상 텔레메트리 값(enum, id)이 가려지지 않음을 테스트로 고정

모두 코드 변경이라 git revert로 되돌릴 수 있다. 배포, 데이터 마이그레이션, 비밀값 변경은 없다.

Risks and Mitigations

Risk Impact Mitigation
worktree마다 node_modules가 없음 Med 레인 시작 시 corepack pnpm install --frozen-lockfile --prefer-offline
레인 9개가 동시에 테스트를 돌려 느려짐 Low 레인 안에서는 관련 테스트만, 커밋 전에만 전체 unit/component
INVENTORY.md 병합 충돌 Low 통합 단계에서 수동 병합 후 check:adapter-inventory
브라우저에서만 재현되는 항목(T06, T09, T26, T29, T31, T32, T44) Med fake로 조건을 재현. 실제 브라우저 확인은 "미검증"으로 최종 보고
T20 성능 요구(10배)는 CI에서 측정하기 불안정 Low 정확성 테스트는 자동, 성능은 벤치 스크립트 수동 측정값을 커밋 메시지에 기록
R-0 방식이 pnpm pre/post 훅에 의존하면 환경마다 다름 Med 훅에 의존하지 않고 진입점에서 명시적으로 생성

Open Questions

  • 없음. 방향이 여러 개인 항목은 SPEC.md의 D-1 ~ D-7로 정했다. 승인하면 그대로 진행한다.