표지판을 먼저 쓰고 출발하기 | 성공 기준과 TDD

Overview

앞 레슨에서 테스트가 AI 자율 루프의 확인 단계를 채운다는 점을 봤습니다. 다만 기능을 다 만든 뒤 테스트를 추가하면, AI가 자기 코드에 맞춰 테스트를 만들어 빈틈이 같이 생긴다는 허점도 드러났습니다.

이번 레슨의 핵심은 코드를 먼저 쓰는 것이 아니라 검증 기준을 먼저 고정하는 것입니다. 성공 기준을 테스트로 바꾸고, Red와 Green을 한 항목씩 확인하며 기능을 완성하는 흐름을 다룹니다.

학습 목표

• 검증 가능한 성공 기준(Acceptance Criteria)의 역할과 작성법을 설명할 수 있습니다.
• 성공 기준을 테스트로 먼저 쓰는 이유를 설명할 수 있습니다.
• Red Green Refactor 사이클을 실천할 수 있습니다.
• Plan → Execute → Discover → Replan 사이클을 설명할 수 있습니다.

검증 가능한 성공 기준

"필터링 기능을 추가하라"라는 계획을 받은 AI는 코드를 작성할 수 있지만, 완성 후 할 수 있는 건 "추가했습니다"라고 보고하는 것뿐입니다. 실제로 동작하는지는 AI도 알 수 없습니다.

택시에 빗대 보겠습니다. 손님이 "강남역 가주세요" 라고만 말하면, 기사님은 같은 이름의 다른 역으로 갈 수도 있고, 같은 서울 강남역이라도 어느 출구에 세울지 판단할 근거가 없습니다. 반면 "강남역 2번 출구 앞 횡단보도"까지 정해두면 기사님이 창밖을 보며 스스로 "여기 맞다/아니다"를 판정할 수 있습니다.

계획에 "이 조건이 충족되면 완료"라는 구체적 체크리스트를 포함하면, AI는 코드 작성 후 그 조건을 직접 확인하고 스스로 루프를 돌 수 있습니다. 이것이 검증 가능한 성공 기준(Acceptance Criteria)입니다.

좋은 성공 기준 vs 나쁜 성공 기준

나쁜 예: "필터링이 잘 동작해야 한다"

AI는 "잘"이 무엇인지 판단할 수 없습니다. 코드를 작성하고 "잘 동작할 것으로 보입니다"라고 보고할 뿐입니다.

좋은 예: "Todo 5개 (완료 2, 미완료 3) 상태에서 '완료' 선택 → 2개 표시, 모두 완료 항목"

초기 상태(5개, 완료 2/미완료 3), 액션('완료' 선택), 기대 출력(2개, 모두 완료)이 모두 숫자로 특정되어 있습니다. 구체적인 입력과 기대 출력이 있어야 AI가 검증 루프를 돌 수 있습니다.

계획의 세 요소

요구사항 형식("사용자가 ~하면, 시스템이 ~한다")과 범위 제한에 성공 기준을 붙입니다.

요구사항·성공 기준·범위 제한 세 가지를 갖춘 계획이 AI가 가장 잘 실행하는 계획입니다. 요구사항은 무엇을, 성공 기준은 어떻게 검증할지, 범위 제한은 무엇을 안 할지 답합니다. 성공 기준 하나를 구체적으로 쓰는 3분이 AI가 생성하는 코드 수십 줄의 방향을 결정합니다.

성공 기준을 테스트로 바꾸는 시점

성공 기준을 코드 작성 전에 테스트로 쓰느냐, 후에 쓰느냐에 따라 결과가 완전히 달라집니다.

점검 기준이 정비사 머릿속에 있는 것과, 작업 전에 받은 점검표에 미리 적혀 있는 것의 차이입니다. 같은 차를 다뤄도 기준이 어디에 있느냐에 따라 빠진 항목을 가릴 수 있는지가 달라집니다.

Test-Last

AI가 코드를 먼저 쓰고, 자기가 쓴 코드를 보고 테스트를 만듭니다. 정비 비유로 보면 정비사의 머릿속 점검과 같습니다.

정비사가 작업을 마치며 말합니다. "이상 없습니다." 그런데 사이드 미러 각도가 어긋난 채로 마무리됐습니다. 판정 기준이 정비사 머릿속에만 있으니 "내가 만진 부품 = 점검 대상"으로 좁게 해석됩니다. 다른 부품의 상태는 기준에 없습니다.

코드로 돌아오면, AI가 "우선순위를 선택하지 않았을 때" 처리를 빠뜨린 채 테스트를 작성하면 그 케이스는 테스트에도 들어있지 않습니다. 테스트는 전부 초록색이지만 버그는 그대로 남습니다. 이를 자기 점검 편향이라고 합니다. 자기가 쓴 코드에 맞춰 테스트를 만들다 실수를 함께 놓치는 현상입니다.

Test-First

성공 기준에서 테스트를 먼저 만듭니다. 정비 비유로 보면 작업 전 점검표를 손에 드는 것과 같습니다.

점검표에 적혀 있습니다. "브레이크 패드 두께 4mm 이상, 사이드 미러 좌우 정렬, 와이퍼 양쪽 작동." 정비사가 사이드 미러를 그대로 두고 마무리해도 점검표 기준으로 대조하면 '사이드 미러 정렬' 항목이 통과하지 못합니다. 정비사가 점검표를 자기가 고칠 권한이 없으니, 사이드 미러를 다시 잡아야 비로소 통과입니다.

코드로 돌아오면, "우선순위 미선택 시 기본값이 '보통'이어야 한다"는 테스트가 먼저 존재하면, AI는 그 테스트를 통과시키기 위해 빈 값 처리를 반드시 구현합니다. 테스트가 코드보다 먼저 존재하면, AI가 자기 실수를 가릴 수 없습니다.

Red Green Refactor: 기준 하나씩 통과하기

이 Test-First 워크플로우에는 이름이 있습니다. Red Green Refactor, TDD(Test-Driven Development)의 핵심 사이클입니다.

1. Red: 실패하는 테스트를 작성합니다 (테스트 실행 → 빨간색)
2. Green: 테스트를 통과시키는 최소한의 구현을 작성합니다 (테스트 실행 → 초록색)
3. Refactor: 테스트가 통과하는 상태에서 코드를 정리합니다

AI와 함께 TDD를 할 때 중요한 것은 성공 기준 목록 전체를 한 번에 구현하려 하지 않는 것입니다. 성공 기준 목록은 먼저 만들되, 그중 지금 구현할 가장 작은 동작 하나만 실행할 수 있는 테스트로 바꿉니다.

테스트가 실패하는지 확인한 뒤, 그 테스트를 통과할 만큼만 구현합니다. 이때 Green은 기능 전체가 끝났다는 뜻이 아니라, 선택한 기준 하나가 통과했다는 뜻입니다. 같은 과정을 반복해 모든 기준을 통과시킨 뒤, 마지막으로 실제 사용자 흐름을 확인합니다.

[미션] TDD로 Todo 필터링 구현하기

ch05-03 브랜치가 이 미션의 시작점입니다. 앞 레슨에서 테스트 환경을 셋업해 둔 상태입니다.

git fetch origin
git checkout ch05-03

Shift+Tab 으로 Plan Mode에 진입하고 아래 프롬프트를 전달합니다.

아래 요구사항대로 필터링 기능을 추가해줘.
Red Green Refactor 사이클을 따라줘. 성공 기준을 한 번에 모두 구현하지 말고, 하나씩 테스트로 바꿔 Red와 Green을 확인해줘.

## 기능: Todo 필터링

### 요구사항
1. 사용자가 '전체' 필터를 선택하면, 모든 항목이 표시된다
2. 사용자가 '진행중' 필터를 선택하면, 미완료 항목만 표시된다
3. 사용자가 '완료' 필터를 선택하면, 완료 항목만 표시된다
4. 현재 선택된 필터가 시각적으로 구분된다

### 성공 기준
- Todo 5개 (완료 2, 미완료 3) 상태에서 '전체' 선택 -> 5개 표시
- 같은 상태에서 '진행중' 선택 -> 3개 표시, 모두 미완료 항목
- 같은 상태에서 '완료' 선택 -> 2개 표시, 모두 완료 항목
- Todo가 0개일 때 '진행중' 선택 -> '할 일이 없습니다' 메시지 표시
- '완료' 필터 선택 중 Todo를 미완료로 변경 -> 해당 항목이 목록에서 사라짐
- 현재 필터 버튼에 active 스타일 적용

### 범위 제한
- 필터 상태는 URL 파라미터로 저장하지 않는다
- 필터 조합(완료 + 특정 카테고리)은 구현하지 않는다
- 필터 애니메이션은 구현하지 않는다

AI가 코드베이스를 탐색한 뒤 구현 계획을 제안합니다. 이때 AI의 계획이 성공 기준(점검표)을 담았는지 다음 항목으로 확인합니다.

• 성공 기준의 모든 항목이 계획에 반영되었는가
• 범위 제한을 넘어서는 구현이 포함되지 않았는가
• AI가 미해결 질문을 던졌다면 답변

계획을 승인하면 AI가 성공 기준 목록을 확인하고, 그중 하나를 실행할 수 있는 테스트로 변환합니다. 테스트가 통과하면 다음 기준으로 넘어갑니다. 모든 성공 기준이 통과하면 실제 사용자 흐름을 확인한 뒤 커밋합니다.

실행 후 발견과 재계획

필터링을 직접 써 보면 처음 계획에 없던 요구사항이 떠오릅니다 (예: "버튼에 개수 표시"). 새 요구사항은 크기에 따라 다르게 처리합니다.

• 작은 변경은 성공 기준 한 항목만 추가해 같은 세션에서 이어갑니다.
• 큰 변경은 새 세션·새 계획으로 분리합니다. 기존 계획에 섞이면 AI가 우선순위를 잃습니다.

핵심 포인트 정리

1. 구체적인 입력과 기대 출력: 성공 기준은 "잘 동작한다"가 아니라 "5개 중 완료 2개 → '완료' 필터 → 2개 표시"처럼 AI가 pass/fail을 판단할 수 있는 형태로 작성합니다. "강남역"이 아니라 "강남역 2번 출구 앞 횡단보도"까지 구체적으로 정해야 합니다.
2. Test-First: 성공 기준(점검표)이 코드보다 먼저 존재하면, AI가 그 기준을 고칠 수 없어서 누락 없이 구현합니다. 코드 후에 테스트를 쓰면(정비사의 머릿속 점검) 자기 코드의 빈틈이 테스트에도 그대로 남습니다.
3. 작은 검증 단위: 성공 기준 목록은 먼저 정리하되, 실행할 수 있는 테스트는 하나씩 작성합니다. Green은 기능 완성이 아니라 선택한 기준 하나의 통과를 뜻합니다. 모든 기준이 통과하면 실제 사용자 흐름을 확인합니다.
4. 계획은 반복: 실행하면 계획 단계에서 보이지 않던 것이 보입니다. 작은 변경은 같은 세션에서 이어가고, 큰 변경은 새 세션에서 새 계획으로 다시 세웁니다.

Tip: 매번 "테스트를 먼저 작성해줘"라고 프롬프트에 쓰는 대신, CLAUDE.md에 한 번 명세하면 모든 세션에 자동 적용됩니다.

## Development Workflow

- Red Green Refactor 사이클을 따른다
- 성공 기준 목록을 먼저 정리한다
- 실행할 수 있는 테스트는 한 번에 하나씩 작성한다
- 새 테스트가 실패하는 것을 확인한 뒤(Red), 그 테스트를 통과할 만큼만 구현한다(Green)
- 하나의 Green은 기능 완성이 아니라 선택한 기준 하나의 통과로 본다
- 모든 기준이 통과하면 실제 사용자 흐름을 확인한다
- 하나의 기능이 끝날 때마다 커밋한다

FAQ

이어서 배울 내용

성공 기준이 포함된 계획을 세우고 Red Green Refactor로 실행하는 워크플로우를 배웠습니다. 하지만 계획에 기능이 7개, 10개씩 들어가면 context window가 가득 차고, auto-compact로 구조 정보가 유실될 수 있습니다. 다음 레슨에서는 긴 계획이 context 안에서 흐려지는 문제를 줄이기 위해, 작업을 Task로 나눠 AI가 순서와 진행 상태를 따라가게 만드는 방법을 배웁니다.

• auto-compact에도 유실되지 않는 Task 시스템
• blockedBy/blocks로 작업 순서 관리하기