tdd-workflow

name	tdd-workflow
description	RED → GREEN → REFACTOR 사이클을 절차로 강제하는 스킬. snapmany의 어떤 코드든 새로 작성하거나 수정할 때 반드시 이 절차를 따른다. 컴포넌트, route handler, lib wrapper, config — 예외 없음. "테스트 작성", "TDD", "구현 추가", "기능 추가", "리팩터링", "버그 픽스" 같은 요청이 들어오면 무조건 이 스킬을 트리거한다.

TDD Workflow

코드를 한 줄이라도 새로 쓰거나 고치기 전에 이 절차를 따른다. 이유: 테스트가 먼저 있으면 구현이 검증 가능한 모양으로 수렴한다. 테스트가 나중이면 "통과하도록" 사후 조정되어 본래 의도가 흐려진다.

절차

1. RED — 실패하는 테스트를 먼저 쓴다

• 단위 테스트 파일을 만들거나 기존 테스트에 케이스를 추가한다 (Vitest 기준).
• 아직 존재하지 않는 함수/컴포넌트를 import해서 호출하거나 렌더한다.
• npm run test를 돌려 테스트가 실패하는지 확인한다. 실패 메시지가 "module not found" 같은 import 에러여도 OK — "기능이 없어서 실패"이면 RED 통과.
• 통과하면 안 된다. 통과한다면 테스트가 무엇도 검증하지 않는다는 뜻이다.

2. GREEN — 최소 구현으로 테스트를 통과시킨다

• 가장 단순한 구현으로 테스트를 통과시킨다. 일반화는 다음 단계에서.
• 다른 곳을 만지지 않는다. 테스트가 요구하는 인터페이스와 동작만 구현.
• npm run test로 해당 테스트가 통과하는지 확인.

3. REFACTOR — 풀 파이프라인 게이트

GREEN 직후 반드시 아래 4개 명령을 순서대로 모두 통과시킨다. 하나라도 실패하면 다음 단계로 가지 않는다.

npm run typecheck
npm run lint
npm run test
npm run build

이 게이트는 양보 불가다. "내 코드는 동작하니까 typecheck 에러는 무시"는 금지. typecheck 에러는 빌드 실패로 이어지고, 빌드 실패는 Cloudflare 배포 실패로 이어진다.

모듈 완성의 정의

QA 에이전트가 모듈을 "완성됐다"고 인정하는 기준:

• RED 테스트가 존재했고, 지금 GREEN 상태다
• 풀 파이프라인 4개 명령이 모두 0 에러로 통과한다
• 테스트 케이스가 정상 경로 + 에러 경로를 최소 1개씩 다룬다

이 셋 중 하나라도 빠지면 모듈은 미완성이다.

TDD가 어려운 경우 처리법

상황	대처
UI 시각 디자인	Playwright로 스냅샷/시각 회귀 대신 동작 단위 테스트 — 버튼 disabled, 클릭 시 dispatch, 폼 검증 메시지 등
외부 API 호출 (Replicate)	client wrapper를 mock으로 주입, 실제 호출은 별도 통합 테스트에서만
환경변수 의존	vi.stubEnv로 테스트 격리
Firebase Remote Config	RC 모듈 자체를 mock, default fallback 분기 테스트는 RC를 throw하도록

일반화 원칙

테스트 케이스를 좁게 (특정 입력값에만 통과하도록) 작성하면 구현이 하드코딩으로 통과해 버린다. 테스트는 속성 기반으로 작성한다:

• "10MB를 넘으면 에러" (정확히 10MB+1 바이트가 아니라)
• "jpg/png/webp가 아니면 에러" (gif 케이스 하나만이 아니라 매트릭스)
• "styleIds가 알려진 집합에 없으면 에러" (특정 ID 하나가 아니라)

안티패턴

• 구현을 다 짠 후 통과하는 테스트만 작성 (이미 결론이 정해져 있어 검증력 없음)
• 단언이 없는 테스트 (expect 호출 없이 render만)
• 모든 케이스에 mock만 두고 실제 로직을 호출하지 않는 테스트
• console.log로 통과 확인 (단언으로 표현 가능하면 단언으로)