# 05 · 실행 프레임워크 (Framework) — v1.1 (레드팀 반영)

**TDD-RED 프레임워크 v1.1** — Sep 2026 기준. 원론(Beck/Fowler)·증거·2026 에이전트 시대 합의 + **레드팀 검증(5방면) 반영**.
핵심 변화(v1.0 대비): ① 루프를 **2계층**(내부 루프 + 외부 게이트)으로 분리해 단계 순서 모순 해소, ② '숨김'→'보호'로 다운그레이드, ③ FREEZE를 루프 단계가 아닌 **상비 인프라**로 이동, ④ 뮤테이션을 내부 루프에서 제거·주기 게이트로, ⑤ 인용·수치 오류 전수 교정.

---

## 1. 제어 구조 — 2계층 (정본, 모든 문서의 기준)

```
[외부] SPEC ── 프로젝트별 사양(수용 기준/긴 시나리오) + 수용 테스트는 보호 경로로
              │
[내부 루프 ×N] RED → GREEN → (REFACTOR)   ← 초 단위, 에이전트 로컬, "가장 단순한 변경"
              │
[외부] GATE ── VERIFY(기계 검사) + REVIEW(테스트 diff) + DONE(결정적 완료 판정)
```

- **내부 루프**는 Beck 원형 그대로 초 단위로 회복한다. 실패 증거 → 최소 구현 → 선택 리팩터.
- **외부 게이트**는 PR/CI 단위. 기계 검사·테스트 diff 리뷰·완료 판정을 한 게이트로 통합.
- 하나의 8단계 번호 목록을 폐기한다 — 단계 수가 문서마다 4~9로 갈라지던 원인.

### 세부 절차

| 단계 | 내용 | 수준 |
|---|---|---|
| **SPEC** | 요구를 관찰 가능한 수용 기준(긴 시나리오)으로. 이 프로젝트는 `docs/design/*` 을 정본으로 그로부터 Gherkin을 파생(충돌 시 design이 우선). 수용 테스트는 보호 경로에 1회 배치(상비 인프라, 매 루프 아님) | 외부 |
| **RED** | 행위 하나를 의미 있는 테스트로, 구현 전 **예상된 이유로 실패함을 증명**. 단위 계층은 실패 증거를 먼저 | 내부 |
| **GREEN** | 가장 단순한 변경. 실패한 테스트를 수정/약화/삭제/스킵하지 말 것 | 내부 |
| **REFACTOR** | 행위 불변 구조 정리(선택). 내부 루프 내에서 수행 | 내부 |
| **VERIFY** | 기계 검사: 영향받은 워크스페이스 스위트+타입체크+린트+보안. **풀 스위트는 CI 전담**. 증분 뮤테이션(변경 파일만, 주기/게이트) | 게이트 |
| **REVIEW** | **테스트 파일부터** 리뷰 — 약화·삭제·스킵·하드코딩·무관변경 탐지. 독립 모델/신선 컨텍스트 권장 | 게이트 |
| **DONE** | 결정적 검사 통과 시에만 완료 인정. 에이전트 "완료" 주장 불신 | 게이트 |

---

## 2. 보호(Protected) 수용 테스트 — '숨김'의 현실적 다운그레이드 (레드팀 공격 2·3 반영)

**문제**: "숨김(held-out) 수용 테스트를 에이전트 컨텍스트 밖에"는 솔로+에이전트 환경에서 **실행 불가** —
같은 repo면 Grep으로 읽히고, 별도 repo는 유지비가 가치를 초과하며, 추적성(매트릭스 공개)과 상호모순.

**해법 — '숨김' → '보호': 목표를 "읽지 못하게"가 아니라 "**고치지 못하게**"로 재정의.**

구현(1회 설정, 상비 인프라):
1. `tests/acceptance/**` 에 대해 Claude/Codex 거버넌스 `deny` 규칙(Edit/Write 차단).
2. CODEOWNERS + 브랜치 보호로 해당 경로 변경 시 인간 승인 강제.
3. CI에서 "acceptance 경로 diff가 있고 스펙 커밋 태그가 없으면 실패" 검사.
4. 보호 경로 무결성 체크를 게이트에 포함.

범위 차등화: 임계 여정 3~5개(라이선스, 결제/정산 등)만 보호, 나머지는 일반 스위트.
추적성 규칙: 보호 테스트는 T-### 매트릭스에 **존재·ID만** 기록하고 Then 상세는 기록하지 않는다.

---

## 3. 의미 있는 RED 스펙 (단일 테스트 최소 기준)

| 항목 | 실제 값 |
|---|---|
| 이름 | `동작_시나리오_기대결과` (예: `Withdraw_BalanceInsufficient_Throws`) |
| 구조 | AAA 또는 Given-When-Then |
| 단정 | 결함-검출 가능, 관찰 결과만 (내부 X) |
| 계층 | 최저 충분 계층 (E2E는 임계 여정만) |
| 결정성 | 시간·랜덤·네트워크·DB 주입/제어, 저비용 |
| 실패 이유 | "행위 부재 **또는 결함 재현**" 하나만 (회귀·특성화 예외 포함) |

**판정**: 테스트 별개 유형이 아니라 **5축(행위·단정·실패이유·결정성·의도, +계층 경제성) 충족 여부**로 판정하며,
아래 12가지는 이 5축을 충족하는 **패턴 카탈로그**(상호배타 분류가 아님)다.

**의미 있는 RED 패턴 카탈로그 (KEEP 12)**: 행위 우선 · 경계·엣지 · 회귀(결함 재현) · 인터페이스 설계 · 삼각측량 ·
결함-검출 잠재력 · 외부 강제 수용 · 블랙박스 · Traceable · 설명력 · 독립 검증 · 특성화(레거시 전처리 예외).

**의미 없는 RED (DELETE)**: 가짜(단정 없음 `expect(true)`) · 사소 · 구현-세부 · 전부 목 인공화 · 복붙 기대값 ·
커버리지 채움 · 의례적(단위 계층 한정; 수용 계층 사전 작성은 예외) · 비결정/flaky · 전 계층 중복 ·
에이전트 약화/과잉 구현(+프로세스 금지 행동 2종 분리).

> 특성화 RED는 엄밀히 "RED 이전의 레거시 안전망(전처리)"이다 — 기존 동작 캡처로 **즉시 통과**하므로
> "행위 부재로 실패" 정의의 예외로 처리한다.

---

## 4. 뮤테이션 정책 (레드팀 공격 4 반영)

- **내부 루프에서 제거.** RED 1건마다 뮤테이션은 비용이 10~100배 과소평가(파일당 뮤턴트 30~200 × 수십 초).
- **주기 게이트로 이동**: PR 게이트에서 **변경된 파일만** 증분 뮤테이션(`--mutate` diff 스코프, incremental), 전체는 nightly.
- **적용 범위**: vitest/Jest 워크스페이스에 한정, .NET(Stryker.NET)·Deno는 도구 성숙도로 **명시 제외**.
- §8 지표 철학과 정합: 뮤테이션은 "측정 도구"지 "완료 게이트"가 아니다. §3 최소 기준의 뮤테이션 행 삭제 —
대신 리뷰에서 단정이 상수 교체·경계 반전을 잡는지 **눈으로 검사**하는 저비용 대체.

---

## 5. 긴 시나리오 → 테스트 매트릭스 (구현 주문)

```gherkin
Feature: 계정 잠금
  Scenario: 반복 실패 후 잠금
    Given 활성 계정 And 시도 4회 실패
     When 잘못된 비밀번호 1개 더 제출
     Then 인증 실패 And 15분 잠금 And 보안 이벤트 기록
```

| Scenario | 계층 | RED | ID |
|---|---|---|---|
| 반복 실패 잠금 | 단위 | 카운터·임계 | T-110 |
| 반복 실패 잠금 | 통합 | 보안 이벤트 기록 | T-210 |
| 정상 로그인 | E2E | 로그인 여정 | T-410 |

ID 규칙: 백의 자리=계층(1단위 2통합 3계약 4E2E), 십의 자리=시나리오. 정본 매트릭스는 `04-long-scenarios.md`에
있으며(05는 발췌·확장), 같은 시나리오를 전 계층에 중복하지 않는다.

---

## 6. 2026 에이전트 보강

- **보호 수용 테스트**를 에이전트가 수정 못 하게 강제 (§2).
- **독립 검증**: 테스트 작성/리뷰는 구현과 다른 모델·신선 컨텍스트 권장(조용히 동시 작성은 금지 — 단위 RED 생성 후
  GREEN 수행하는 표준 플로우는 실패 증거만 먼저 제시하면 허용).
- **추가 검증 보강**: 프로퍼티(넓이) · 계약(경계, Pact S-96) · 뮤테이션(단정 강도) 필요 시.
- **TDD 위반 도구 강제** (Probity/TDD Guard류): 스킵·과잉구현·테스트 약화 자동 감지.
- **에이전트 생성 테스트 = 초안**: 인간 리뷰 필수.

> 주의: 2026 신호는 방향이 **수렴만**이 아니다. Meta JiTTests(항목 71)는 "전통 테스트의 죽음 → 유지보수 없는
> 즉시생성 테스트"로 **반대 방향**이다. 이 프레임워크는 그중에서도 "인간이 결정한 수용 기준을 게이트로"라는
> 견해를 선택한 것임을 명시한다(증거 등급: TDD-Agent/+9.8pp/TDFlow 등은 2026-08 사전인쇄·n=1·2차 인용 — 피어리뷰
> 연구와 별개 등급으로 취급).

---

## 7. TRIAGE — 모든 변경이 RED 대상인가? (선별 규칙, 계약 0단계)

"모든 행위 변경에 강제"라는 무조건 문구를 폐기하고, 아래 선별 표를 AGENTS.md 첫 항목으로 둔다.

| 상황 | 방법 |
|---|---|
| 행위 명확·구현 어려움 | TDD-RED (내부 루프) |
| 프로덕션 버그 | 실패하는 회귀 RED 먼저 |
| 안정 도메인 규칙 | RED/예제 우선 |
| 설계·기술 미지 | 스파이크 후 정리하고 테스트 |
| 시각 UI 탐색 | test-last(컴포넌트·접근성·E2E 강조) |
| **린트/타입으로 집행되는 정적 규칙 준수 변경** (console.log 제거, 토큰 교체 등) | RED 면제 — VERIFY(린트)만 통과 (D3RO 규칙) |
| AI가 코드·테스트 둘 다 생성 | 독립 테스트 + 리뷰 + 뮤테이션/프로퍼티 |
| 레거시 대규모 변경 | 특성화(characterization) 우선 |
| 네이티브/프로세스 경계 서비스 (Electron 메인, STT/TTS) | 어댑터 계약 테스트(경계만 목) + 스모크 — "전부 목 금지"는 순수 로직 계층에만 적용 |
| UI 텍스트 단정 | t-key 수준에서 (i18n SSOT 하의 '관찰 가능한 결과' 대리자) |
| 싱글톤/EventEmitter 서비스 | Determinism 위해 설계서 차원의 `resetForTest()` 훅 추가 |

---

## 8. AGENTS.md 정책 (저장소 계약 — 2계층 + 게이트 반영)

```markdown
# TDD-RED 정책 (v1.1)

## 원칙
- 테스트는 행위(behavior)를 검증한다. 구현 세부·프라이빗·호출순서·데이터 구조는 금지.
- RED는 "테스트가 이미 구현된 상태에서 통과하거나, 예상된 이유 외로 실패해도" 무효.
- 같은 턴에서 테스트와 구현을 "조용히 동시에" 쓰는 것을 금지 — 반드시 실패 증거를 먼저 제시.
- 특성화(레거시)·회귀(결함)는 RED 정의의 명시적 예외.

## TRIAGE (0단계): §7 선별 표에 따라 이 변경이 RED 대상인지 판단.
- 린트/타입으로 집행되는 규칙 준수 변경·시각 UI 탐색 등은 RED 면제(사유 기록).

## 프로세스
1. SPEC  : 요구를 Given/When/Then 수용 시나리오로. docs/design이 정본이면 그로부터 파생.
2. RED   : 행위 하나를 의미 있는 테스트로. 실행해 예상된 이유로 실패함을 출력으로 증명.
3. GREEN : 가장 단순한 변경. 실패한 테스트를 수정/약화/삭제/스킵하지 말 것.
4. REFACTOR: 행위 보존, 영향받은 스위트 초록 유지.
5. GATE  :
   a. VERIFY: 영향받은 워크스페이스 스위트+타입체크+린트+보안 (풀 스위트는 CI 전담). 증분 뮤테이션(변경 파일만, 게이트).
   b. 보호 경로(`tests/acceptance/**`) 무결성 — 에이전트는 해당 경로를 수정·삭제 금지.
   c. REVIEW: 테스트 파일부터 diff 리뷰(약화·삭제·스킵·하드코딩·무관변경 확인).
   d. DONE : 결정적 검사 통과 시에만. "완료" 주장은 검사 없이는 인정 안 됨.
6. REPORT: 변경 파일 / 실행 명령 / 구현 전 실패 증거 / 최종 결과 / 미해결 위험·가정.

## 금지(가드레일)
- 기존 테스트 삭제·스킵·비활성·광범위 목 대체. 보호 경로 수정.
- 참조되지 않는(과잉) 구현 추가. `expect(true)` 식 단정, 복붙 기대값.
- "완료" 주장 — 결정적 검사 통과만 인정.
```

---

## 9. 성공 기준 (ROI / 품질)

실증 코어(34, 36, 37, 42 계열): TDD는 "품질 향상은 확률적, 생산성은 맥락 의존". **절대 수치가 아닌 내부 파일럿**으로 ROI 판단.
- 결함-검출 능력(뮤테이션 점수) · 회귀 미검출 · flaky율 · 리드타임 · 리뷰 시간 단축을 측정.
- 커버리지% 가 아니라 "이 테스트가 뮤턴트를 죽이는가"를 **측정 지표**로(게이트는 아님).
- 특정 벤더·개인 수치(Kiro, Red Hat, n=1)는 2차·마케팅 증거로 무게 차등.

---

## 부록 · 즉시 적용용 미니 프롬프트

```
지시: 작업을 2계층 TDD로 수행. (RED 대상이면)
1. 저장소 컨벤션·테스트 명령 확인.
2. 요구를 observable 수용 기준으로 재진술 (docs/design이 정본이면 그로부터 파생).
3. RED: 테스트 하나 추가하고 실행 → 예상된 이유로 실패함을 보여라.
4. GREEN: 가장 단순한 최소 변경. 테스트를 수정/약화/삭제하지 말 것.
5. REFACTOR: 행위 불변.
6. GATE: 영향받은 스위트+타입+린트 실행 → 보호 경로(tests/acceptance) 미접촉 확인 → 테스트 diff 리뷰 → 결정적 완료.
7. 보고: 변경 파일/명령/구현 전 실패 증거/최종 결과/위험·가정.
```