DMF_Crawler/docs/research/11-tdd-red-and-design-audit-theory.md

TDD · E2E RED · 디자인 감사 이론 조사 정본

이 문서는 DMF Crawler 의 TDD/RED/디자인 감사 이론 SSOT 다.
프로젝트 적용 규칙은 docs/design/07-tdd-red-system.md 가 정본이고, 이 문서는 그 근거 아카이브다.

작성/검색 기준: 2026-09-03 KST
근거 채택 기준: (A) 2026년 9월 기준 최근 6개월 내 자료, 또는 (B) Kent Beck·W3C·NN/g·Playwright·Testing Library·Google Testing Blog·GDS 같은 권위 자료, 또는 (C) 유명 책·논문·체계적 문헌고찰·arXiv/IEEE/ACM/ScienceDirect 계열 연구
원문 아카이브: docs/research/_raw/tdd-red/

---

0. 결론 12개

1. TDD 의 핵심은 테스트가 아니라 설계 루프다. Kent Beck 의 두 규칙은 “자동화 테스트가 실패할 때만 새 코드를 쓴다”와 “중복을 제거한다”다. Red-Green-Refactor 는 이 두 규칙을 실행하는 리듬이다.
2. RED 는 반드시 실제로 실패해야 한다. 즉시 통과하는 테스트는 새 행동을 규정하지 못했거나, 기존 테스트의 중복이거나, 주장이 약하다. 그런 테스트는 RED 로 인정하지 않는다.
3. Green 은 최소 구현이다. 미래 추상화·범용화·과잉 구조는 Refactor 단계 전까지 금지한다.
4. Refactor 는 Green 상태에서만 한다. 실패 중인 테스트를 둔 채 구조 변경을 하면 실패 원인이 행동 변경인지 리팩터링 사고인지 분리할 수 없다.
5. 테스트는 구현 세부가 아니라 관찰 가능한 행동을 검증해야 한다. Testing Library 의 “The more your tests resemble the way your software is used, the more confidence they can give you.” 원칙과 Playwright 의 사용자 관찰 출력 중심 원칙이 같은 결론을 낸다.
6. E2E 는 TDD 의 전부가 아니다. 빠른 단위/통합 테스트가 대부분을 맡고, E2E 는 핵심 사용자 여정·회귀 위험·시각/접근성 감사에 집중한다. 느린 E2E 를 무한 증식시키면 TDD 가 아니라 병목이 된다.
7. AI 에이전트에게 “TDD 해”라고만 말하면 충분하지 않다. 2026 TDAD 논문은 단순 TDD prompting 이 회귀를 늘릴 수 있고, 코드-테스트 영향 분석을 함께 줬을 때 회귀를 크게 줄였다고 보고한다. 에이전트는 “어떤 테스트가 무엇을 보호하는지” 알아야 한다.
8. AI 가 만든 테스트는 자동으로 가치 있지 않다. 2026 “Rethinking the Value of Agent-Generated Tests” 계열 연구는 에이전트 작성 테스트가 종종 관찰/디버깅 피드백에 머물고, 강한 검증으로 작동하지 않을 수 있음을 경고한다.
9. 테스트 스위트는 확장만 하지 않는다. 의미 없는 RED, 같은 결함을 여러 번 검사하는 중복 RED, 구현에 묶인 brittle RED 는 통폐합·삭제한다. 단, 삭제는 대체 근거와 사용자 위험 분석이 있어야 한다.
10. 디자인 감사도 RED 로 만든다. “예쁘다/별로다” 같은 감상이 아니라, 대비·정렬·레이아웃 overflow·폼 라벨·키보드 포커스·입력 시나리오·버튼 클릭·엑셀 시트 구조·컨테이너 경계 같은 실패 조건을 자동화 가능한 주장으로 바꾼다.
11. 자동 접근성 검사는 필요하지만 충분하지 않다. WCAG/W3C/axe 는 contrast·label·ARIA 오류를 잘 잡지만, 레이블 의미·초점 순서·문구 이해성·시각적 균형·사용자 흐름은 수동/시나리오 테스트와 결합해야 한다.
12. 이 프로젝트의 디자인 감사 대상은 웹만이 아니다. DMF Crawler 는 tkinter GUI 와 xlsx 리포트가 핵심 UI 이므로, Playwright/axe 원칙을 그대로 베끼지 말고 tkinter 위젯 트리 검사와 xlsx zip/XML 검사로 변환해야 한다.

---

1. 원문 아카이브 인덱스

파일	출처	채택 사유	검증 상태
google-testing-blog-way-of-tdd-2026.raw.html	Google Testing Blog, “The Way of TDD”, 2026-03	최근 6개월 경계 내 최신 실무 권위 블로그	원문 저장 성공
gds-way-test-driven-development.raw.html	UK Government Digital Service, TDD standard	정부 디지털 서비스 표준, Red-Green-Refactor 설명	원문 저장 성공
informit-kent-beck-tdd-by-example.raw.html	Kent Beck, Test Driven Development: By Example 출판사 페이지	TDD 고전/권위 책	원문 저장 성공
testing-library-guiding-principles.raw.html	Testing Library Guiding Principles	사용자 행동과 닮은 테스트 원칙의 대표 출처	원문 저장 성공
playwright-best-practices.raw.html	Playwright Best Practices	E2E 테스트 공식 권위 문서	원문 저장 성공
wcag22.raw.html	W3C WCAG 2.2 Recommendation	접근성 공식 표준	원문 저장 성공
vercel-web-interface-guidelines-command.raw.md	Vercel Web Interface Guidelines	AI agent UI 코드 감사 체크리스트	원문 저장 성공
nng-good-visual-design.raw.html	NN/g, Good Visual Design, Explained	시각 디자인 권위 자료	원문 저장 성공
nng-web-form-design.raw.html	NN/g, Website Forms Usability	폼 UX 권위 자료	원문 저장 성공
nng-form-placeholders.raw.html	NN/g, Placeholders in Form Fields Are Harmful	placeholder-only label 금지 근거	원문 저장 성공
nng-form-white-space.raw.html	NN/g, Group Form Elements Effectively Using White Space	라벨/입력 proximity·white space 근거	원문 저장 성공
arxiv-2312-04687-llm4tdd.raw.html	LLM4TDD	LLM + TDD 초기 연구	원문 저장 성공
arxiv-2505-09027-tests-as-prompt.raw.html	Tests as Prompt / WebApp1K	테스트를 prompt/spec 으로 쓰는 최신 연구	원문 저장 성공
arxiv-2506-09289-utboost.raw.html	UTBoost	기존 테스트 부족·에이전트 패치 오판 경고	원문 저장 성공
arxiv-2602-07900-agent-generated-tests.raw.html	Rethinking Agent-Generated Tests	에이전트 생성 테스트의 한계 경고	원문 저장 성공
arxiv-2603-08806-test-driven-ai-agent-definition.raw.html	Test-Driven AI Agent Definition	prompt/agent behavior 자체를 TDD 로 검증	원문 저장 성공
arxiv-2603-17973-tdad.raw.html	TDAD: Test-Driven Agentic Development	AI coding agent 회귀 감소·impact analysis 근거	원문 저장 성공
ieee-what-do-we-know-tdd.raw.html	IEEE Xplore, “What Do We Know about TDD?”	체계적 문헌고찰로 검색 확인	원문 0 bytes — 원문 인용 금지, DOI/검색 근거만 사용

원문 저장 성공은 “페이지가 로컬에 저장됐다”는 뜻이지, 모든 주장을 자동 승인한다는 뜻이 아니다. 프로젝트 규칙으로 승격하려면 docs/design/07-tdd-red-system.md 의 사용자 위험/검증 가능성 필터를 통과해야 한다.

---

2. TDD 정통 이론

2.1 Kent Beck: 두 규칙과 Red-Green-Refactor

Kent Beck 의 Test Driven Development: By Example 는 이 프로젝트에서 TDD 의 최고 권위 근거로 취급한다. 출판사/요약 기준으로 핵심은 다음이다.

• 새 코드는 자동화 테스트가 실패할 때만 작성한다.
• 중복을 제거한다.
• Red: 아주 작은 실패 테스트를 작성한다.
• Green: 빨리 통과시킨다. 일시적으로 못생긴 코드도 허용된다.
• Refactor: 테스트가 계속 통과하는 상태에서 중복·이름·구조를 정리한다.

DMF Crawler 에서의 해석:

원칙	이 프로젝트 적용
failing automated test first	src/ 변경 전 tests/ 에 실패하는 주장 추가. 문서만 바꾸는 경우도 문서 링크/정책 테스트 또는 체크리스트를 추가한다.
do the simplest thing	API/DB/리포트가 통과할 최소 구현 우선. 미래 웹 UI·브라우저 수집 추상화는 테스트 없이 만들지 않는다.
eliminate duplication	테스트 중복도 제거 대상. 같은 실패를 여러 파일에서 반복하면 하나의 강한 시나리오로 합친다.
refactor only when green	compileall, import, 관련 pytest 가 실패하는 동안 구조 변경 금지. 먼저 RED 를 Green 으로 만든다.

2.2 GDS/Google: TDD 는 설계 품질과 피드백 루프

GDS Way 의 TDD 표준은 Red-Green-Refactor 를 “작은 실패 테스트 → 전체 테스트 통과 → 설계 반복” 루프로 설명한다. Google Testing Blog 의 2026 글도 TDD 를 품질·재사용·자신감의 도구로 설명하되, 은탄환은 아니라고 본다.

프로젝트 적용:

• TDD 는 “테스트 파일을 많이 만든다”가 아니라 “작은 행동 단위로 설계를 밀어낸다”다.
• 실패가 너무 크면 원인을 알 수 없다. RED 는 한 번에 하나의 행동/위험만 드러내야 한다.
• 리포트/GUI 디자인처럼 주관이 섞이는 영역도 측정 가능한 실패 조건으로 쪼갠다.

2.3 체계적 문헌고찰: 품질 이점은 있으나 생산성은 혼합

IEEE/ScienceDirect 계열 체계적 문헌고찰들은 대체로 TDD 가 외부 품질·내부 품질에 긍정 효과를 줄 수 있지만, 생산성 효과는 맥락별로 혼합이라고 요약된다. 따라서 이 프로젝트는 “TDD 를 신처럼 여긴다”는 사용자 방침을 따르되, 무의미한 테스트 팽창은 TDD 가 아니라 비용으로 본다.

프로젝트 적용:

• 테스트 작성 자체를 산출물로 착각하지 않는다.
• 테스트가 결함을 막지 못하면 약한 테스트다.
• 너무 느려 자주 못 돌리는 테스트는 TDD inner loop 에 맞지 않으므로 nightly/E2E 계층으로 내린다.

---

3. AI coding agent 와 TDD

3.1 LLM4TDD: 테스트가 prompt 와 검증 장치가 될 수 있다

LLM4TDD 는 LLM 을 테스트 주도 방식으로 반복 유도하는 연구다. 핵심 함의는 “자연어 요구만으로 구현을 맡기지 말고, 테스트가 요구를 실행 가능한 형태로 제한해야 한다”다.

DMF Crawler 적용:

• 에이전트에게 “DMF API 구현해”라고 시키지 않는다.
• 먼저 tests/test_source_mfds.py 에 fixture 기반 실패를 만든다.
• 그 테스트 이름과 실패 로그를 에이전트 지시의 중심에 둔다.

3.2 Tests as Prompt / WebApp1K: 테스트 자체가 스펙이다

Tests as Prompt 는 테스트 케이스가 prompt 이자 verification 역할을 하는 벤치마크를 제안한다. 중요한 관찰은 TDD 성공이 일반 코딩 능력보다 instruction following 과 in-context learning 에 크게 좌우된다는 점이다.

DMF Crawler 적용:

• AGENTS.md 는 “어떤 테스트를 왜 돌리는지”를 명확히 적는다.
• 테스트 이름은 요구사항 번호와 위험을 포함한다. 예: test_r2_2_rejects_full_withdrawal_on_empty_success_body.
• 장문 프롬프트에 모든 문서를 집어넣기보다, 해당 테스트와 관련 SSOT 문서만 읽게 한다.

3.3 TDAD: agent 에게 영향 테스트 지도를 줘야 한다

2026 TDAD 논문은 AI coding agent 가 기존 테스트를 깨뜨리는 회귀를 자주 만든다고 지적하고, 코드-테스트 의존 지도/impact analysis 를 제공하면 회귀가 크게 감소한다고 보고한다. 단순히 “TDD 로 해”라고 prompting 하는 것만으로는 충분하지 않거나 해로울 수 있다는 점이 핵심이다.

DMF Crawler 적용:

• 파일을 바꾸기 전 “영향 테스트 목록”을 적는다.
• 예시:
  • normalize.py → tests/test_normalize.py, tests/test_diff.py, tests/test_integrity.py, report data tests
  • storage/repo.py → migration tests, pipeline smoke, report data tests
  • report/* → xlsx zip/XML tests, visual/layout audit tests
  • gui/* → tkinter structure/a11y tests, text input/button scenario tests
• 에이전트는 관련 테스트만 먼저 돌린 뒤 전체 smoke 로 확장한다.

3.4 Agent-generated tests 경고: 얕은 테스트는 통과 장식이 된다

2026 “Rethinking the Value of Agent-Generated Tests” 는 에이전트가 작성한 테스트가 최종 문제 해결률을 자동으로 높인다고 볼 수 없으며, 디버깅 관찰 수단에 머무는 경우가 많다고 경고한다. UTBoost 도 기존 테스트가 부족하면 잘못된 패치가 통과한다고 보여준다.

DMF Crawler 적용:

• 에이전트가 만든 테스트는 반드시 실패 확인을 거친다.
• 실패 이유가 “모듈 없음/오타”뿐이면 행동 RED 로 약하다. 실제 요구 위반까지 도달하도록 보강한다.
• “현재 구현을 그대로 assert” 하는 회고성 테스트는 거부한다.
• 과거 버그가 있으면 그 버그를 재현하는 fixture 를 먼저 만든다.

3.5 Test-Driven AI Agent Definition: 지침서도 테스트 대상이다

Test-Driven AI Agent Definition 은 agent prompt/behavior 를 실행 가능한 테스트로 검증하는 방법론을 제안한다. visible/hidden test split, mutation testing, spec evolution 이 핵심이다.

DMF Crawler 적용:

• AGENTS.md 자체가 정책 SSOT 를 참조한다.
• 에이전트 지침 변경 시 다음을 검증한다.
  • “테스트 없이 코드 변경 금지” 문구가 있는가.
  • “RED 삭제/완화 금지” 문구가 있는가.
  • “디자인 감사 RED”가 구체 항목을 포함하는가.
  • “실패를 숨기지 말 것” 규칙이 있는가.

---

4. E2E/사용자 행동 테스트 이론

4.1 Testing Library: 사용자와 닮은 테스트

Testing Library 의 대표 문장:

The more your tests resemble the way your software is used, the more confidence they can give you.

실무 규칙:

• CSS 클래스나 내부 함수명보다 사용자에게 보이는 텍스트/역할/라벨을 우선한다.
• 폼은 label 로 찾는다.
• 버튼은 role/name 으로 찾는다.
• 테스트 ID 는 마지막 수단이다.

DMF Crawler 변환:

• 웹 프론트가 아니어도 “사용자와 닮은 테스트” 원칙은 그대로 쓴다.
• CLI: 실제 python -m dmf_crawler doctor 출력과 종료 코드를 검사한다.
• GUI: 실제 tkinter 위젯에 텍스트를 입력하고 버튼 command 를 호출한다.
• xlsx: 실제 파일을 zip 으로 열고 workbook/sheet XML 을 검사한다.

4.2 Playwright: E2E 는 관찰 가능한 출력과 격리

Playwright 공식 best practices 의 핵심은 다음으로 요약된다.

• 사용자가 보는/상호작용하는 출력 중심으로 테스트한다.
• 테스트는 독립적이어야 한다.
• 안정적인 locator 를 사용한다.
• E2E 는 중요한 흐름에 집중한다.
• 시각 회귀는 OS/browser 환경을 고정해야 한다.

DMF Crawler 적용:

• 브라우저 수집 경로가 들어오면 “엑셀 다운로드 버튼 클릭 → 파일 생성 → .crdownload 사라짐 → xlsx 구조 검증”을 E2E 로 둔다.
• 공공 사이트 실접속은 기본 테스트에서 제외하고 fixture/mock 서버를 사용한다.
• 실제 nedrug 접속은 사용자가 승인한 수동 smoke 로만 둔다.

---

5. 디자인 감사 이론

5.1 W3C/WCAG 2.2: 접근성 최소선

DMF Crawler 디자인 RED 는 최소 WCAG 2.2 AA 를 기준으로 삼는다.

영역	기준	자동화 가능한 RED
텍스트 대비	1.4.3, 일반 4.5:1 / 큰 글자 3:1	팔레트 HEX 대비 계산 테스트
비텍스트 대비	1.4.11, UI 경계/상태 3:1	input border/focus/아이콘 상태색 대비 계산
색 단독 전달 금지	1.4.1	상태가 색+라벨+기호로 표현되는지 검사
키보드 접근	2.1.1	모든 버튼/입력의 tab/focus 가능성 검사
초점 표시	2.4.7, 2.4.11	focus style 또는 tkinter highlight/focus 이동 검사
라벨/지시	3.3.2	입력마다 visible label/help/error 연결 검사
오류 식별	3.3.1/3.3.3	빈 입력 제출 시 오류 문구+복구 버튼 검사

5.2 NN/g: 폼·정렬·시각 계층

NN/g 자료는 다음 UX 결정을 뒷받침한다.

• 폼은 가능하면 단일 컬럼.
• 라벨은 입력 가까이에 둔다.
• placeholder 를 label 대체로 쓰지 않는다.
• 관련 필드는 white space 와 섹션 제목으로 묶는다.
• 시각 디자인은 grid alignment, typographic hierarchy, intentional color, consistency 가 핵심이다.

DMF Crawler 적용:

• 온보딩 GUI 는 “중앙 정렬된 큰 덩어리”가 아니라 좌측 라벨/상태/행동 버튼의 스캔 가능한 구조를 기본으로 한다.
• 입력창 내부 padding, 버튼 높이, 아이콘과 텍스트 baseline 정렬은 테스트 대상이다.
• 오류 문구는 [무엇]/[왜]/[어떻게]/[다음] 4요소를 강제한다.

5.3 Vercel Web Interface Guidelines: agent 가 잡아야 할 UI 결함 목록

Vercel 의 command.md 는 AI agent 가 UI 코드를 감사할 때 잡아야 할 항목을 구체적으로 제시한다. 이 프로젝트는 웹 UI 가 아니더라도 항목을 일반화해 쓴다.

• 접근성: icon-only button label, form label, semantic control, alt/decorative distinction, live region.
• focus: outline 제거 금지, focus visible, sticky/overlay 가 focus 를 가리지 않음.
• forms: autocomplete/name/type, paste 차단 금지, clickable label, inline errors, first error focus.
• typography: ... 대신 …, tabular numbers, heading wrapping.
• content handling: long text overflow, flex child min-width, empty state.
• layout: unwanted scrollbar, content overflow, safe area.
• interaction: hover/focus/active feedback, destructive action confirmation/undo.
• anti-patterns: transition: all, outline: none, div click handler, unlabeled inputs/icons, hardcoded date/number format.

DMF Crawler 변환:

Web guideline	tkinter/xlsx 변환
form controls need label	Entry/Combobox 옆/위에 명시 텍스트 존재
icon-only button aria-label	아이콘 버튼은 텍스트 라벨 또는 tooltip/help text 존재
focus visible	버튼/입력의 focus highlight 또는 순서 검사
long content handling	한글 긴 성분명/업체명 fixture 로 clipping/overflow 검사
tabular numbers	xlsx 수치 열의 number format, CLI 표 정렬 검사
empty states	변경 0건/워치리스트 0건/AI 없음 상태 시 깨진 표 금지
URL reflects state	GUI 복구 모드는 --focus <check_key> 로 상태 직접 진입 가능

---

6. 이 프로젝트의 “빡센 디자인 RED” 범위

디자인 RED 는 다음을 반드시 잡는다.

6.1 정렬/레이아웃

• 의미 없는 전체 중앙 정렬 금지. 제목·KPI 처럼 의도 있는 중앙 정렬만 허용.
• 폼 라벨과 입력은 grid 에 맞고 서로 가까워야 한다.
• 버튼 그룹은 같은 높이/간격/정렬선을 가져야 한다.
• 아이콘과 텍스트는 vertical center/baseline 이 맞아야 한다.
• 컨테이너보다 큰 요소, 잘리는 텍스트, 가로 스크롤 발생을 실패로 본다.
• flex/grid 류 레이아웃에서는 긴 텍스트가 줄바꿈/말줄임/폭 축소를 할 수 있어야 한다. 웹이면 min-width: 0 류를 검사한다.

6.2 타이포그래피

• 최소 본문 크기: GUI 10pt, xlsx 본문 10pt, 각주 9pt 이하 남용 금지.
• 정보 계층: 제목/섹션/본문/도움말/오류가 크기·굵기·색으로 구분돼야 한다.
• 숫자 열은 정렬과 number format 이 안정적이어야 한다.
• 한국어 긴 문자열이 폭 255 같은 비정상 Excel 열폭을 만들면 실패.

6.3 폼/입력

• placeholder-only label 금지.
• 실제 입력 테스트 필수: API 키 붙여넣기, 잘못된 키, 빈 값, 긴 값, 한글/영문 혼합.
• paste 차단 금지.
• 오류 시 첫 오류로 포커스 이동 또는 명확한 안내.
• input 내부 padding/버튼과의 간격이 최소값 이상이어야 한다.

6.4 접근성/상태 표현

• 색만으로 신규/변경/취하/경고를 표현하면 실패.
• 상태는 라벨+기호+색+서식(취하는 취소선 등) 4중 이상 표현.
• 포커스 가능한 요소는 키보드로 접근 가능해야 한다.
• 모달은 닫기/나중에/복구 액션이 명확해야 한다.

6.5 xlsx 리포트 디자인

• 시트 순서: 00_대시보드, 01_오늘변경분, 02_전체현황, 03_성분별, 04_업체별, 05_워치리스트(조건부), 06_추이, 99_메타.
• 대시보드 첫 화면 무스크롤 목표: 1366×768 노트북에서 90% zoom 기준.
• 틀 고정/자동필터/조건부서식/내부 링크/출처 문구가 없으면 실패.
• 파일은 zip/xlsx 구조 검증을 통과해야 한다.
• openpyxl 에 의존하지 않는다. 검증도 stdlib zipfile/XML 로 한다.

---

7. RED 확장·통폐합·삭제 원칙

1. 사용자 유즈케이스 없는 RED 금지. “있으면 좋음”만으로 테스트를 추가하지 않는다.
2. 같은 위험을 검사하는 RED 는 통합한다. 중복은 실행 시간을 늘리고 실패 원인을 흐린다.
3. brittle selector/좌표 테스트는 금지한다. 사용자 의미(role/label/text), xlsx 구조, 위젯 역할 중심으로 검사한다.
4. 테스트 삭제는 허용된다. 단, 다음 중 하나가 문서화돼야 한다.
   • 더 강한 통합/시나리오 테스트가 같은 위험을 덮는다.
   • 요구사항이 삭제됐다.
   • 테스트가 구현 세부에 묶여 리팩터링을 방해했다.
   • flaky 원인이 환경이며 안정화 비용이 가치보다 크다.
5. 테스트 완화는 삭제보다 위험하다. 임계값을 낮추거나 assert 를 약하게 바꾸려면 실패 스크린샷/로그와 사용자 영향 분석이 필요하다.

---

8. 프로젝트 적용 문서

이 연구 정본의 적용 규칙은 다음 문서가 담당한다.

• docs/design/07-tdd-red-system.md — 프로젝트 TDD/RED 운영 체계 SSOT
• AGENTS.md — AI coding agent 작업 규칙
• CLAUDE.md — Claude Code 진입용 얇은 포인터

---

9. 미해결·추가 검증 항목

• IEEE/ScienceDirect 논문 원문은 접근 제한/빈 응답이 있어 직접 인용을 하지 않았다. 필요 시 DOI 기반 서지 정보만 별도 표로 확정한다.
• google-testing-blog-way-of-tdd-2026.raw.html 은 원문 저장은 됐으나 HTML 정제 후 핵심 문구를 별도 발췌하는 작업이 남았다.
• GUI screenshot 기반 pixel diff 는 현재 런타임 의존성 3개 원칙과 충돌한다. dev 의존성으로 둘지, tkinter geometry 검사로만 갈지 결정해야 한다.
• 브라우저 수집 경로가 구현되면 Playwright/axe 를 쓸지, Chrome DevTools Protocol 직접 검사로 충분한지 결정해야 한다.