c3ddd36c6f
Some checks failed
deploy-site / deploy (push) Failing after 40s
Release notes for 1.1.0 were split between an Unreleased section and the version section, so the published notes would have omitted the update-feed and desktop changes. Everything shipping in this version now sits under one `## [1.1.0]` heading. `docs/map/` becomes the entry point for what infrastructure exists per platform and how far each feature is developed, with a documented update protocol so feature work and this map do not drift apart again. The release guide now states that installer binaries live in the update feed rather than the repository.
201 lines
12 KiB
Markdown
201 lines
12 KiB
Markdown
# 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. 보고: 변경 파일/명령/구현 전 실패 증거/최종 결과/위험·가정.
|
||
```
|