| name | incremental-verification |
| description | 작업 결과가 불확실할 때 적용하세요 — 외부 API, 브라우저 자동화, 셸 이스케이프, 익숙지 않은 라이브러리, 데이터 파이프라인. 전체 스크립트를 짜서 대규모로 한 번에 돌리지 말고, 가장 작은 검증 단위로 쪼개 각 단계의 실제 출력을 확인한 뒤 다음 단계를 쌓으세요. |
불확실한 작업의 점진적 검증
작업 결과가 불확실할 때 — 외부 API, 브라우저 자동화, 셸 이스케이프, 익숙지 않은 라이브러리 — 일을 가장 작은 검증 단위로 쪼개고 각 단계를 확인한 뒤 넘어가세요.
패턴
- 가능한 가장 작은 단위로 시작하라. API 호출 하나, 레코드 하나 추출, DB에 한 행 쓰기. 스크립트나 함수를 짜기 전에 인라인(예:
node -e "...")으로 해보세요.
- 출력을 명시적으로 검증하라. 결과를 출력하고, DB를 확인하고, 데이터 모양을 점검하세요. "에러 없이 돌았다"는 검증이 아닙니다 — 실제 출력을 보세요.
- 한 번에 한 겹씩 쌓아라. N단계가 성공한 뒤에야 N+1단계를 추가하세요. N+1이 실패하면 고치고 1단계부터 다시 검증하세요 — 변경 후에도 앞 단계가 여전히 잘 돈다고 가정하지 마세요.
- 스크립트 변환은 맨 마지막에. 전체 사슬이 인라인으로 돌아가면, 검증된 코드를 스크립트 파일로 옮기세요. 스케일을 올리기 전에 작은 입력(1~2개)으로 스크립트를 돌려보세요.
- 점진적으로 키워라. 5개로 돌리고, 그다음 50개, 그다음 전체 데이터셋. 각 규모마다 결과를 확인하세요.
이유
전체 스크립트를 먼저 짜서 수천 개에 돌리면 실패를 진단하기가 비쌉니다:
- 에러 메시지가 화면 밖으로 스크롤되거나 로그에 묻힌다
- 여러 실패 모드가 겹겹이 쌓인다
- 디버깅하려면 느린 파이프라인 전체를 다시 돌려야 한다
- "내 컴퓨터에선 됐는데" 식 가정이 규모에 비례해 불어난다
작은 인라인 테스트는 빨리, 싸게 실패하고, 명확한 에러 메시지를 냅니다.
예시
나쁨: 250줄짜리 크롤링 스크립트를 짠다 → 10개국 × 20개 키워드에 돌린다 → DB에 undefined가 들어온다 → 이스케이프 문제를 디버깅하느라 30분을 쓴다
좋음:
Step 1: agent-browser eval 'single JS expression' → JSON 출력 검증
Step 2: node -e "fetch embedding API with one title" → 1536 차원 검증
Step 3: node -e "insert one row into the database" → DB에 행 들어왔는지 검증
Step 4: node -e "step 1 + 2 + 3 together for 1 item" → end-to-end 검증
Step 5: 검증된 코드로 스크립트 작성 → 5개 항목에 돌린다 → DB 확인
Step 6: 전체 규모로 실행
언제 적용하나
- 외부 시스템 연동(API, DB, 브라우저 자동화)
- 셸 명령 조합(이스케이프, 파이프, 서브셸)
- 데이터 파이프라인 구축(extract → transform → load)
- 정확히 그 코드 경로를 한 번도 돌려본 적 없는 모든 작업
