7칸을 다 채웠는데 한 칸이 빠져있었다

들어가며

설계 계약을 완성했다고 생각했습니다.

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 규칙에 중단 조건 + 사람 승인 지점 설계
소스가 바뀌어도 이전 스냅샷은 보존되는 구조

다음에 개선할 한 가지

브라우저 방식과 판매자 어드민, 두 후보 중 하나로 키워드 하나 · 상품 하나를 테스트해서 기존 스냅샷과 같은 의미로 비교 가능한지 확인하는 것. 숫자가 나오는 게 성공이 아니라, 기존 기록과 이어 붙일 수 있는지가 기준입니다.

😈 정말 찐찐찐 마지막 할인가!!! 24기 AI 스터디 😈

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