7칸을 다 채웠는데 한 칸이 빠져있었다 — source_unavailable 추가기
2026.08.11

들어가며
설계 계약을 완성했다고 생각했습니다.
Goal, Trigger, Context, Tree/Route, Criteria, Approval, Repair — 7칸 다 채웠어요.
근데 실제로 실행하려는 순간, 한 가지가 빠져있었다는 걸 알았습니다.
Repair 규칙에 "소스 자체가 사라지는 상황"이 없었어요.
found, not_found, out_of_range는 있었는데 source_unavailable은 없었습니다. 잘 될 때의 흐름만 설계하고, 데이터 소스가 막히는 상황은 상정하지 않은 거였어요.
이 글은 그 빠진 한 칸을 발견하는 과정입니다.
1. 무슨 업무인가
네이버 쇼핑에서 키워드 순위를 매일 눈으로 확인하는 게 너무 비효율적이었습니다.
어제 몇 위였는지 기억에 의존하고, 키워드가 여러 개면 비교도 어렵고, 순위가 안 보여도 밀려난 건지 못 찾은 건지 알 수 없었어요.
그래서 이걸 하네스로 만들어보려 했습니다. 매일 같은 기준으로 자동 추적하고, 전일 대비 변화량을 기록으로 남기는 구조요.
2. 설계 계약
Goal : 키워드별 순위를 매일 같은 기준으로 추적하고
날짜별 스냅샷 저장 + 전일 대비 변화량 출력
Trigger : 매일 오전 9시 cron 또는 수동 호출
중복 실행 방지 — 같은 날 이미 실행됐으면 no-start
Context : 네이버 Search API 응답값
productId (상품 식별 기준)
기준 시각 (항상 고정)
저장 위치 data/rank-snapshots.md
Tree/Route: Intake → Query → Match → Persist → Compare → Report
순서 고정, 저장 없이 완료 없음
Criteria : found / not_found / out_of_range 상태값 구분
저장 완료 확인 시 완료
source_unavailable 발생 시 완료 아님
Approval : 데이터 소스 변경 시 사람이 승인
자동 대체 금지
Repair : source_unavailable 발생 시
이전 스냅샷 보존
중단 후 사람에게 알림
소스 변경은 승인 후에만
3. 어디서 막혔나
설계는 다 됐다고 생각했어요. Intake부터 Report까지 6단계 구조로 잡고, 저장을 완료 조건으로 못박고, 상태값도 세 가지로 구분했습니다.
근데 막상 실행하려는 순간 네이버 쇼핑 Search API가 중단됐습니다.
스킬은 완성됐는데 데이터 소스 자체가 사라진 거예요.
그리고 이때 설계에서 빠진 게 보였습니다.
source_unavailable 상태가 없었어요.
found / not_found / out_of_range는 있었는데, API 자체가 막혔을 때 어떻게 할지는 정해두지 않았던 거였습니다. 잘 될 때의 흐름만 설계하고, 소스가 사라지는 상황은 상정하지 않았어요.
4. 무엇을 바꿨나
Repair 규칙에 아래 내용을 추가했습니다.
source_unavailable 발생 시:
- 이전 스냅샷 덮어쓰지 않고 보존
- 자동으로 대체 소스 전환 금지
- 중단 후 사람에게 소스 변경 승인 요청
- 승인 후에만 다음 실행 허용
스터디장님 피드백에서도 짚어주셨는데, 두 후보 소스(브라우저 방식, 판매자 어드민)가 기존 스냅샷과 같은 의미로 비교 가능한지 아직 미검증이기 때문에 자동 대체보다 사람이 승인하는 지점을 먼저 설계하는 게 맞는 방향이었습니다.
5. 실행 영수증
Trace : Intake 완료 → Query 단계에서 API 호출
→ source_unavailable 반환 → 이후 단계 중단
Proof : 에러 메시지 캡처
"주요 기사를 확보하지 못했습니다"
→ API 정상 응답 없음 확인
Verdict : 기준 미충족
저장 미완료 → 완료 아님
source_unavailable 상태 대응 규칙 없음 확인
Repair : Repair 규칙에 source_unavailable 추가
이전 스냅샷 보존 + 사람 승인 지점 설계
대안 소스 검토 중 (브라우저 방식 / 판매자 어드민)
6. 무엇이 달라졌나
Before
found / not_found / out_of_range세 가지 상태만 있었음데이터 소스가 막히면 어떻게 할지 규칙 없음
잘 될 때의 흐름만 설계된 반쪽짜리 하네스
After
source_unavailable상태 추가Repair 규칙에 중단 조건 + 사람 승인 지점 설계
소스가 바뀌어도 이전 스냅샷은 보존되는 구조
다음에 개선할 한 가지
브라우저 방식과 판매자 어드민, 두 후보 중 하나로 키워드 하나 · 상품 하나를 테스트해서 기존 스냅샷과 같은 의미로 비교 가능한지 확인하는 것. 숫자가 나오는 게 성공이 아니라, 기존 기록과 이어 붙일 수 있는지가 기준입니다.



일곱 칸을 채운 설계가 실제 첫 실행에서야 `source_unavailable`을 만나 반쪽이었다고 드러난 과정이 솔직했습니다. `found / not_found / out_of_range`는 상품을 찾는 결과만 설명할 뿐, 네이버 쇼핑 Search API 자체가 중단된 상태는 표현하지 못했죠.
새 상태를 추가한 뒤에는 이전 스냅샷을 덮어쓰지 않고 실행을 멈추며, 브라우저 방식이나 판매자 어드민으로 자동 전환하지 않도록 Repair를 바꿨습니다. 대체 소스는 사람이 승인한 뒤에만 다음 실행을 허용해, 숫자가 이어져 보인다는 이유만으로 서로 다른 관측을 같은 시계열에 붙이는 일을 막았어요.
마지막에 적은 다음 검증 기준도 구체적입니다. 키워드 하나·상품 하나로 두 후보를 시험하되 ‘숫자가 나오는가’가 아니라 기존 스냅샷과 같은 의미로 비교 가능한지를 보겠다고 했습니다. 멈춘 실행이 곧바로 대체 구현으로 뛰지 않고 비교 가능성 확인으로 이어집니다.
소스가 사라진 날을 외부 장애로만 넘기지 않고 하네스의 누락 상태로 되돌린 판단이 좋았어요. 이전 기록 보존과 사람 승인이라는 두 경계가 이 순위 추적의 연속성을 지켰습니다.