---
name: principle-sequence-verifiable-units
description: 검증 가능한 단위로 시퀀싱하기
---

# 원칙: 검증 가능한 단위로 시퀀싱하기

작업을 개별적으로 빌드, 테스트 및 커밋할 수 있는 단계로 분해하세요. 큰 변경 사항을 한꺼번에 푸시하지 마세요. 대신, 각각 독립적으로 검증할 수 있는 일련의 작은 단계로 진행하세요.

## 이유

- **더 빠른 피드백**: 각 단계 후에 오류를 발견합니다
- **더 쉬운 디버깅**: 무엇이 잘못되었는지 정확히 알 수 있습니다
- **더 나은 리뷰 가능성**: 리뷰어가 한 번에 하나의 논리적 변경을 볼 수 있습니다
- **롤백 가능**: 문제가 발생하면 마지막 좋은 상태로 돌아갈 수 있습니다
- **진행 상황 추적**: 무엇이 완료되었고 무엇이 남았는지 명확합니다

## 방법

1. 큰 작업을 논리적 단계로 나누세요 (리팩토링, 기능 추가, 테스트 작성)
2. 각 단계를 완료한 후:
   - 빌드가 통과하는지 확인
   - 테스트를 실행
   - 커밋
3. 다음 단계로 진행

각 커밋은 빌드 가능하고 테스트 가능해야 합니다. "나중에 수정" 커밋을 남기지 마세요.

## 예시

**나쁜 예** (큰 원자적 변경):

```
1. API 리팩토링, 100개의 호출자 업데이트, 새 기능 추가, 테스트 작성
   → 하나의 거대한 커밋, 무엇이 실패하면 디버깅하기 어려움
```

**좋은 예** (시퀀싱된 단계):

```
1. 기존 테스트로 새 API 추가 → 커밋, 빌드 통과
2. 10개의 호출자를 새 API로 마이그레이션 → 커밋, 테스트 통과
3. 나머지 호출자 마이그레이션 → 커밋, 테스트 통과
4. 레거시 API 삭제 → 커밋, 빌드 통과
5. 새 기능 추가 → 커밋, 테스트 작성 및 통과
```

각 단계는 독립적이며, 한 단계에서 실패하면 그 단계로 돌아갑니다.

## 좋은 단계란 무엇인가

- **빌드 가능**: 컴파일되고 타입 체크를 통과합니다
- **테스트 가능**: 기존 테스트가 통과하거나 새 테스트가 추가됩니다
- **논리적으로 원자적**: 하나의 명확한 목적 (리팩토링, 버그 수정, 기능 추가)
- **격리됨**: 다른 단계와 독립적으로 검토 또는 되돌릴 수 있습니다

단계가 너무 크면 더 작게 나누세요. 너무 작으면 (단일 줄 변경) 괜찮습니다 — 다음 커밋에서 스쿼시할 수 있습니다.

## 대규모 리팩토링

수백 개의 파일이 영향을 받는 경우:

1. 새 API/인터페이스를 추가하고 테스트합니다
2. 호출자를 배치로 마이그레이션합니다 (모듈 또는 레이어당)
3. 각 배치 후에 커밋하고 빌드합니다
4. 모든 호출자가 마이그레이션되면 레거시를 삭제합니다

grep 또는 타입 체커를 사용하여 각 단계를 확인하세요.

## 관련 원칙

- **migrate-callers-then-delete-legacy-apis**: 리팩토링을 2단계 시퀀스로 만듭니다
- **prove-it-works**: 각 단계는 작동한다는 증거를 생성합니다
- **make-operations-idempotent**: 시퀀싱된 단계는 멈추고 재시작할 수 있습니다