# 07 · TDD 체계 개편 계획 (Plan v2.0) > 작성: 2026-11-05 · 갱신: 2026-11-08 · 상태: **Phase 0·1 완료 / Phase 2~5 계획** > 선행 정본: `docs/tdd-red/00`~`06`(프레임워크 v1.1, 2026-11-04) · `AGENTS.md §3` · `.claude/skills/refactor-wave/SKILL.md` > 본 문서는 v1.1을 **폐기하지 않는다.** v1.1이 문서로만 선언한 것을 **측정·게이트·자동화로 승격**하는 계획이다. --- ## 1. 현행 체계 (2026-11 현재 실측) | 축 | 현재 | 정본 | |---|---|---| | 원칙 | 5축(행위·단정·실패이유·결정성·의도) + 12 패턴 / 10 안티패턴 | `02` | | 실행 | 2계층(내부 루프 RED→GREEN→REFACTOR · 외부 GATE=VERIFY+REVIEW+DONE) | `05 §1` | | TRIAGE | 변경별 RED 면제/필수 선별표 | `05 §7` | | 위생 게이트 | `npm run test:hygiene` (8규칙 + `--self-test`) | `scripts/ci/check-test-hygiene.mjs` | | 포트폴리오 | 정적/단위/서비스통합/계약/E2E 4계층, E2E는 임계 여정 6파일 | `06 §2`, `§5` | | 통합 게이트 | `npm run verify:all` + CI 5잡(quality/build/mobile/edge/api) | `package.json`, `.forgejo/workflows/ci.yml` | | 보호 경로 | `CODEOWNERS` 6경로 | `06 §5` | **측정된 규모** (`docs/tdd-red/metrics/2026-11-08.md`, `npm run test:metrics`): 테스트 파일 **407** · 케이스 **3,498** · 단정 8,958 (desktop 2,075 / core 547 / mobile 509 / edge 263 / web 46 / api-client 31 / xUnit 27) · 약한 단정 **128** · ambient 시계/난수 **203** · skip/todo 3 · i18n 2,753키 × 12로케일. **현재 게이트 전부 GREEN** — typecheck, lint(`--max-warnings=0`), test:hygiene, contract/version/design. --- ## 2. 진단 — "문서는 있는데 강제되지 않는 것" 10개 | # | 갭 | 실측 증거 | 결과 | |---|---|---|---| | **G1** | 보호 경로가 **문서와 코드에서 다르고, 게이트가 없다** | `05 §2`/`06 §5`는 `tests/acceptance/**`를 보호경로라 하지만 실제 보호 대상은 `apps/*/tests/e2e/*.spec.ts`. `grep -rn "tests/acceptance" scripts/ci` → **0**. `CODEOWNERS`는 존재하나 CI 검사 없음 | 에이전트가 보호 여정의 단정을 약화·삭제해도 **초록** | | **G2** | 결함-검출 강도 지표 없음 | 커버리지 설정 1개(`apps/desktop/vitest.config.ts` → `src/main/services/**` 한정), 실행·게이트 없음. 뮤테이션 도구 **미설치**(Stryker 없음, `05 §4`는 "도입 여부 결정"으로 미결) | 단정이 약해져도 알 방법이 없다 | | **G3** | 약한 단정이 게이트를 통과 | `toBeDefined()/toBeTruthy()/not.toBeNull()` **128건**(2026-11-08 실측). hygiene 규칙은 "항상 참"(`expect(true)`)만 막는다 | 커버리지는 오르고 검출력은 0인 테스트가 합법 | | **G4** | 결정성 정책 부재 | 테스트 내 `Date.now()`/`Math.random()`/`performance.now()` **203건**, `setTimeout` 38건. `Clock`/`Random` 포트 없음 | flaky가 나도 원인 귀속 규칙이 없다 | | **G5** | flaky 격리·재시도 정책 없음 | CI에 재실행/격리 목록 없음. `05 §8`의 "zero-tolerance"는 선언뿐 | 재현 안 되는 실패가 "그냥 다시 돌리기"로 처리됨 | | **G6** | 테스트 선택 실행 없음 | 로컬·CI 모두 전체 스위트. 영향 분석 없음(3,380 케이스) | 에이전트 루프가 느려져 TDD 자체가 회피된다 | | **G7** | 포트폴리오 편중 | `apps/web` 24케이스(페이지 18개, 결제/Payple 흐름 포함) · `packages/ui` **0** · `packages/ui-native` **0** · `packages/i18n` **0** | 계약(DS/i18n) 계층이 비어 있음 | | **G8** | 추적성(T-ID)이 문서에만 | `04-long-scenarios.md`의 T-101/T-210 표는 예시. 코드/테스트에 ID 없음, 매트릭스 생성 스크립트 없음 | 요구 → 테스트 추적 불가. SDD 이점 미확보 | | **G9** | 계약 테스트가 i18n·디자인 토큰을 안 덮음 | 2,753키 × 12 로케일. 로케일 parity 검사 없음(수동 sync 스크립트가 값까지 하드코딩), 고아 후보 **798** | 번역 누락/드리프트가 조용히 배포 | | **G10** | 보호 여정이 CI에서 **실행되지 않음** | 데스크톱 E2E는 러너 X 디스플레이 없음 → 릴리스 전 로컬 수동(`06 §6`) | "보호"가 실제로는 "미실행" | 한 줄 결론: **v1.1은 사양으로는 충분하고, 집행 수단이 없다.** 그래서 2.0의 주제는 "새 원칙"이 아니라 **"원칙을 스크립트로 옮기기"**다. --- ## 3. 개편 목표 구조 (v2.0) 2계층 루프는 유지하고, 외부 GATE에 **4개 기둥**을 추가한다. ``` [SPEC] 수용 시나리오(+T-ID) ── 보호 경로 │ [내부 루프] RED → GREEN → REFACTOR ← 로컬, test:affected 로 60초 이내 │ [GATE] ├─ VERIFY : affected 스위트 + typecheck + lint + hygiene (기존) ├─ CONTRACT : 보호경로 무결성 + i18n parity + DS 토큰 계약 (신규 ★) ├─ STRENGTH : 증분 뮤테이션(핵심 도메인) + 약한 단정 0 (신규 ★) ├─ REVIEW : 테스트 diff 먼저, 약화/삭제/스킵/무관변경 탐지 (기존) └─ DONE : 결정적 통과 + flaky 재시도 3회 규칙 (강화 ★) ``` ### 3-1. 신규 스크립트 (모두 `--self-test` 동반 = `test:hygiene` 패턴 준수) | 스크립트 | 역할 | 최초 규칙 | |---|---|---| | `scripts/ci/check-protected-tests.mjs` | 보호 경로 diff 검사 | (a) 보호 파일에서 `it/test` 개수 **감소** 시 실패 (b) `expect(` 감소 시 실패 (c) `.skip/.only` 추가 시 실패 (d) 커밋 본문/PR 라벨에 `allow-protected-change:` 마커 + 사유가 없으면 실패 | | `scripts/ci/check-test-quality.mjs` | **래칫** 게이트(파일별 기준선 동결) | `weak-assertion`(`toBeDefined/toBeTruthy/toBeFalsy/toBeNull`), `ambient-time`(무주입 `Date.now/Math.random/performance.now`). 기준선 `scripts/ci/test-quality-baseline.json` | | `scripts/ci/check-i18n-contract.mjs` | 로케일 계약 | 키 집합 동일성(12개), `t('…')` 리터럴이 ko에 존재, 고아 키 리포트(게이트 아님 → 임계치 초과 시 실패) | | `scripts/ci/check-ds-contract.mjs` | DS 계약 | `packages/ui` DS 컴포넌트가 role/aria 최소 계약을 export하고 테스트가 참조하는지 | | `scripts/ci/test-metrics.mjs` | 지표 산출(게이트 아님) | 스위트별 케이스/시간/약한 단정/flaky 후보/뮤테이션 점수 → `docs/tdd-red/metrics/YYYY-MM-DD.md` | | `scripts/ci/run-affected-tests.mjs` | 영향 선택 실행 | 변경 파일 → 워크스페이스·테스트 디렉터리 매핑 후 해당 스위트만 실행(안전 기본값: 매핑 실패 시 전체) | ### 3-2. 측정 항목 (게이트 아닌 지표, `05 §9` 정합) - 결함-검출력: 증분 뮤테이션 점수(핵심 도메인만) - flaky율: 3회 재실행 불일치 수 - 리드타임: `test:affected` 소요(목표 **< 60초**), CI full suite 소요 - 약한 단정 잔량(파일 단위 추세) - 보호경로 무결성 위반 수(0 유지) --- ## 4. 로드맵 (Phase 0~5) ### Phase 0 — 기준선 (✅ 완료 2026-11-08) - `scripts/ci/test-metrics.mjs` (+ 공용 헬퍼 `scripts/ci/lib/test-files.mjs`) 작성. - 산출: `docs/tdd-red/metrics/2026-11-08.md` — 파일 407 · 케이스 3,498 · 단정 8,958 · 약한 단정 128 · ambient 203 · i18n 2,753키×12. - **Exit 충족**: 지표 문서 + `npm run test:metrics` / `test:metrics:write` 등록. ### Phase 1 — 집행 수단 1: 보호경로·품질 래칫 (✅ 완료 2026-11-08) - `scripts/ci/check-protected-tests.mjs` — 보호 6경로 diff 검사: 테스트/스텝 블록 감소 · `expect` 감소 · `.only` 추가 · `skip/todo` 추가 → 실패. 정당한 변경은 커밋 본문 `allow-protected-change: <사유>` 또는 `--reason` 으로만 통과. CI `quality` 잡이 `--base HEAD^` 로 실행(체크아웃 depth 2). 얕은 클론에서는 SKIP 사유를 출력. - `scripts/ci/check-test-quality.mjs` + `scripts/ci/test-quality-baseline.json` — 래칫 게이트. 오늘 수치(weak 128 / ambient 203)를 파일별로 동결하고 **증가만** 막는다. `--update` 는 사람 리뷰 후에만. - `npm run verify:all` 에 두 게이트 편입. - **Exit 충족**: `.only` 를 보호 여정에 넣으면 CI/로컬이 빨강(수동 검증 완료), 새 약한 단정을 넣으면 `test:quality` 가 빨강(수동 검증 완료). ### Phase 2 — 집행 수단 2: 계약·i18n·DS (2~3일) - `packages/i18n/__tests__/locale-contract.test.ts`: 12로케일 키 집합 동일, `{placeholders}` 정합, 값이 비어있지 않음. - `check-i18n-contract.mjs`: 코드의 `t('literal')` 키 존재 검사 + 고아 리포트(임계치: 신규 고아 0). - `packages/ui/__tests__/ds-contract.test.tsx`: DS 컴포넌트별 role/aria 최소 계약(스냅샷 금지, `06 §3` 정합). - `scripts/ci/sync-i18n-locales.mjs` 정리: 하드코딩 번역값을 `locales/*.json`으로 이동, `--check`만 남김. - **Exit**: 로케일 키 하나를 지우면 CI 빨강. i18n 고아 수가 지표로 고정. ### Phase 3 — 피드백 속도: 영향 선택 실행 (1주) - `run-affected-tests.mjs` + `npm run test:affected`. - 매핑 규칙: `packages/core/**` → core+desktop+web+mobile / `apps/desktop/src/main/**` → `--mode service` / renderer → renderer+E2E(spec 선택) / `server/**` → deno / `apps/mobile-rn/**` → jest. - 안전장치: 매핑 미스 시 전체 실행, CI는 **항상 full**. - **Exit**: 로컬 affected 실행 < 60초(중앙값), CI full 유지. ### Phase 4 — 강도: 증분 뮤테이션 + 결정성 포트 (1~2주) - `Clock`/`Random` 포트를 `packages/core`에 추가(생성자/옵션 주입, 기본값은 실제 시계) → 신규 테스트는 주입 사용. - Stryker(또는 vitest-mutation 계열) 도입을 **desktop main/services + packages/core 핵심 모듈**로 한정, PR에서는 변경 파일 증분만, nightly는 전체. - 대상 도메인(사용자·돈·보안): `license`, `billing/plan-catalog`, `ads`, `dictionary-policy`, `entitlement`, `transcript-correction`. - **Exit**: 해당 6개 모듈 뮤테이션 점수 기준선 기록, 목표 ≥ 60% (게이트 아닌 리포트). ### Phase 5 — 보호 여정의 실제 실행 (1주, 인프라) - `release.yml` 태그 잡에 Windows 러너 E2E(`test:acceptance:desktop`) 추가, 실패 시 릴리스 중단. - 웹은 `E2E_NO_SERVER=1` 스모크 + Payple 계약 스펙을 CI 잡으로. - 설치 산출물 스모크(설치 → 기동 → 여정 1개) — `R7` 런타임 게이트와 연결. - **Exit**: 보호 6경로가 태그 릴리스에서 실제 실행되고 결과가 릴리스 증거에 남는다. --- ## 5. 게이트 커맨드 (개편 후 최종형) ```bash # 커밋 전 (목표 < 90초) — Phase 0·1 반영 npm run test:hygiene:test && npm run test:hygiene npm run check:protected-tests:test && npm run check:protected-tests npm run test:quality:test && npm run test:quality npm run test:affected # Phase 3 # PR / 통합 npm run verify:all # 위 두 게이트 포함 npm run check:i18n && npm run check:ds-contract # Phase 2 npm run test:metrics:write # 지표 스냅샷(게이트 아님) # 야간 npm run test:mutation -- --full # 릴리스 전 npm run test:acceptance:desktop # Windows 러너 또는 로컬(GUI 세션) npm run test:acceptance:web ``` --- ## 6. 하지 않을 것 (비목표) - 커버리지 **퍼센트 게이트** 도입 금지 (`05 §9`: 커버리지는 지표, 게이트 아님). - E2E 확대 금지 — 여전히 임계 여정 3~5개 + 웹 스모크(`06 §4`). - 스냅샷/픽셀 비교 도입 금지(이 저장소에 시각 회귀 인프라 없음). - `.NET`/Deno/모바일 Jest에 뮤테이션 적용 금지(`05 §4` 명시 제외 유지). - 테스트를 통과시키기 위한 리팩터 금지 — 약화 발견 시 **테스트 보강 또는 스펙 재합의**만. --- ## 7. 리스크와 완화 | 리스크 | 완화 | |---|---| | 새 게이트가 기존 3,380 테스트를 대량으로 빨강으로 만든다 | Phase 1의 `weak-assertion`/`ambient-time`은 **변경 파일 한정**으로 시작, baseline 파일 목록을 `docs/tdd-red/metrics/`에 동결 | | 보호경로 게이트가 정당한 스펙 변경을 막는다 | `allow-protected-change:` 마커 + 사유 요구(사람 리뷰), 마커 사용 이력은 월 1회 리뷰 | | 뮤테이션 도구가 느려 개발 루프를 막는다 | PR은 증분·핵심 6모듈만, nightly 전체, 내부 루프에서 제외(`05 §4`) | | 영향 선택 실행이 회귀를 놓친다 | 매핑 미스 = 전체 실행, CI는 항상 full, `packages/**` 변경은 광범위 매핑 | | i18n 고아 798 삭제가 런타임 키를 지운다 | 동적 키(`t(\`settings.${x}\`)`) 화이트리스트를 게이트에 내장, 삭제는 Wave 5 G5와 분리 | --- ## 8. 완료 정의 (v2.0) - [x] Phase 0 완료: 지표 기준선(`docs/tdd-red/metrics/2026-11-08.md`) + `test:metrics` - [x] Phase 1 완료: 보호경로·품질 래칫이 실제로 빨강을 낸다(self-test 6+6 케이스) - [ ] Phase 2 완료: i18n·DS 계약 게이트가 CI에서 실제로 빨강을 낸다 - [ ] `test:affected` 로컬 중앙값 < 60초 - [ ] 핵심 6모듈 뮤테이션 점수 기준선 + 추세 기록 - [ ] 보호 6경로가 릴리스 태그에서 실행되고 증거가 남는다 - [~] `docs/tdd-red/00`~`06`이 실행 결과와 일치 — `06 §5·§6` 갱신 완료, §2/§4는 Phase 2 에서 - [x] `docs/map/02-infrastructure.md` §10 테스트 인프라 행 갱신 (Phase 0·1 게이트)