본문으로 건너뛰기

실패 대응 규칙 없는 스킬은 반쪽짜리다 — 네이버 쇼핑 API 중단 경험기

hyeok9

2026.08.04

소개

스킬을 만들었습니다. 잘 설계했다고 생각했어요.

근데 막혔습니다. 네이버 쇼핑 API 제공이 중단됐거든요.

처음엔 솔직히 많이 당황했어요. 스킬 설계에 꽤 공을 들였거든요. Intake부터 Report까지 6단계 구조로 잡고, 저장 방식도 정하고, 상태값도 세 가지로 구분했는데 막상 실행하려는 순간 데이터 소스 자체가 사라진 거였습니다.

근데 잠깐 생각해보니까 이게 오히려 이번 스터디에서 배우는 것과 딱 맞는 상황이었어요.

스킬이 실패했을 때 하네스는 어떻게 대응하는가.

이게 진짜 하네스의 역할이고, 제가 지금 그 상황을 직접 경험하고 있는 거였습니다.


어떤 스킬을 만들었냐면

네이버 쇼핑 키워드 순위를 매일 자동으로 추적하는 스킬이었어요.

스킬 이름은 naver-shopping-rank-tracker입니다. 운영 절차는 6단계로 잡았어요.

① Intake — 조회 시작 전에 추적 키워드, 상품 식별값, 기준 시각, 저장 위치를 먼저 고정합니다. 저장 위치가 없으면 조회 자체를 시작하지 않아요.

② Query — 각 키워드로 네이버 공식 Search API를 호출해 쇼핑 검색 결과 목록을 받습니다. 정렬 조건과 조회 범위는 스냅샷 간 비교가 깨지지 않도록 고정해요.

③ Match — productId 기준으로 우리 상품을 찾습니다. 이름만 보고 찾으면 유사 상품이 섞이기 쉬워서, 식별값 매칭을 원칙으로 잡았어요.

④ Persist — 조회만 하고 저장하지 않으면 작업이 끝난 게 아닙니다. date / keyword / rank / delta / status / productId / source / note 필드를 실행 즉시 기록해요.

⑤ Compare — 전일 기록과 비교해서 ▲n / ▼n / - 로 변화량을 계산합니다.

⑥ Report — 사람이 바로 읽을 수 있는 문장으로 요약합니다.

설계 자체는 꽤 탄탄하게 잡았다고 생각했어요. 상태값도 found / not_found / out_of_range 세 가지로 구분해서 미노출과 범위 밖을 따로 처리하도록 했고, 기준 시각 고정, productId 매칭 원칙 등 흔한 함정들도 미리 문서에 못박아뒀습니다.


근데 API가 막혔다

실행하려는 순간 네이버 쇼핑 Search API가 제공 중단됐다는 걸 알게 됐습니다.

스킬은 완성됐는데 핵심 데이터 소스가 사라진 거예요.

처음엔 스킬 설계 어딘가에 문제가 있는 건 줄 알았어요. 이것저것 다시 들여다봤는데 스킬 자체는 문제가 없었고, API 자체가 막힌 거였습니다. 아무리 잘 만든 스킬도 외부 데이터 소스가 사라지면 그 순간 실행이 불가능해져요.

이 상황에서 선택할 수 있는 건 두 가지였습니다.

  1. 그냥 포기하고 다른 스킬을 만든다

  2. 대안 소스를 찾아서 스킬을 수정한다

하네스 관점에서 보면 답은 명확했어요. 실패 시 수정 규칙이 있어야 한다. 3주차에서 배우는 내용이기도 하고, 결국 하네스가 하는 일이 바로 이거니까요. 실패했을 때 무너지지 않고 다음 행동으로 이어지는 구조를 만드는 것.


왜 이게 하네스 문제인가

이번에 제 스킬에서 빠져있던 게 하나 있었어요.

api_error 상태가 났을 때 어떻게 대응할지를 미리 정해두지 않았다는 점입니다.

스킬 안에 found / not_found / out_of_range 상태값은 넣었는데, API 자체가 막혔을 때의 대응 규칙은 없었어요. 외부 소스가 사라지는 상황을 상정하지 않은 거였습니다.

하네스 설계에서 중요한 게 바로 이 부분이에요. 잘 될 때의 흐름만 설계하는 게 아니라, 실패했을 때 어디서 멈추고, 어떤 대안을 시도하고, 어떻게 사람에게 알릴지까지 같이 정해둬야 한다는 거요.

이번 경험 덕분에 스킬에 뭐가 빠져있는지 명확하게 보였습니다.


어떻게 대응할지 검토 중인 것들

현재 세 가지 방향을 검토하고 있어요.

① 브라우저 하네스 활용

API 대신 실제 네이버 쇼핑 검색 결과 페이지를 브라우저 하네스로 직접 읽는 방식이에요. API가 없는 상황에서 가장 현실적인 대안이지만, 페이지 구조가 바뀌면 다시 흔들릴 수 있다는 단점이 있습니다. 안정성 면에서는 API보다 약하지만, 지금 당장 쓸 수 있는 방법이에요.

② 스마트스토어 판매자 어드민 데이터 활용

네이버 스마트스토어 판매자 어드민에서 키워드 노출 관련 데이터를 가져오는 방식이에요. 공식 경로라는 장점이 있고 데이터 신뢰도도 높지만, 접근 방식과 제공 데이터 범위를 더 확인해봐야 합니다.

③ 스킬 자체를 재정의

순위 추적 대신 헤르메스가 직접 처리할 수 있는 다른 운영 업무로 스킬을 전환하는 방향이에요. API 의존도를 줄이고 더 안정적으로 운영할 수 있는 구조로 바꾸는 방식입니다. 다만 이 경우엔 처음부터 다시 설계해야 해서 시간이 걸려요.

아직 어떤 방향으로 갈지 결정하지 못했습니다. 이 부분에서 스터디원 분들의 경험이나 의견이 있으시면 댓글로 공유해 주시면 정말 감사할 것 같아요.


이번에 배운 것들

1. 스킬이 실패하는 이유는 설계가 나빠서만이 아니다

이번 케이스는 스킬 설계 자체의 문제가 아니었어요. 외부 데이터 소스가 사라진 거였습니다. 아무리 잘 만든 스킬도 데이터 소스가 바뀌면 흔들릴 수 있어요. 스킬 설계 안에 외부 의존성이 어디에 있는지를 명시하고, 그게 막혔을 때의 대응까지 같이 정해둬야 한다는 걸 배웠습니다.

2. 하네스에 실패 대응 규칙이 반드시 있어야 한다

잘 될 때의 흐름만 설계하면 반쪽짜리 하네스예요. 실패했을 때 어디서 멈추고, 어떤 대안을 시도하고, 어떻게 사람에게 알릴지까지 같이 있어야 진짜 하네스입니다. 이번에 그게 빠져있었다는 걸 실패하고 나서야 알았어요.

3. 막힌 지점이 다음 스킬 개선의 출발점이다

완성됐다고 생각한 스킬이 실제로 돌아가는 순간 막혔어요. 근데 그 막힘 덕분에 스킬에 뭐가 빠져있는지 명확하게 보였습니다. 순조롭게 돌아갔다면 몰랐을 것들이에요. 에이전트 하네스 스터디에서 배우는 것처럼 막힌 지점을 기록하고 다음 개선으로 연결하는 게 하네스를 키우는 방법이라는 걸 이번에 몸으로 배웠습니다.

4. 외부 소스 의존 스킬은 항상 플랜 B가 필요하다

API, 외부 서비스, 크롤링 등 외부 소스에 의존하는 스킬은 언제든 막힐 수 있어요. 플랜 B를 미리 스킬 안에 명시해두는 게 필요합니다. 이번에 그게 없었던 게 가장 크게 아쉬운 부분이에요.


앞으로 할 것

  • 세 가지 대안 중 방향 결정

  • 스킬에 api_error 대응 규칙 추가

  • 외부 소스 의존성을 스킬 문서에 명시

  • 데이터 소스가 바뀌어도 구조가 유지되도록 스킬 수정

  • 수정된 스킬로 재실행 후 결과 공유


마치며

솔직히 API가 막혔을 때 당황했습니다.

공들여 만든 스킬이 첫 실행도 못 해보고 막힌 거니까요. 근데 돌아보면 이게 오히려 하네스 스터디에서 제일 중요한 걸 배운 순간이었어요.

스킬은 완성되는 게 아니라 실패하면서 더 단단해지는 거다. 그리고 하네스는 잘 될 때만 작동하는 게 아니라, 막혔을 때도 다음 행동으로 이어지는 구조여야 한다.

대안 소스 찾아서 스킬 고치고, 결과 나오면 2편으로 돌아오겠습니다.

2

함께 이야기해요 2

로그인하고 댓글을 남겨 주세요

Giacomo 프로필 이미지
Giacomo2026.08.06

hyeok9님, 첫 실행 직전에 데이터 소스가 사라졌다면 공들여 만든 여섯 단계가 한순간에 무효가 된 것처럼 느껴졌을 것 같아요. 그런데 설계를 버리는 대신 found·not_found·out_of_range만 있고 ‘소스 자체를 쓸 수 없음’ 상태가 빠져 있었다고 찾아낸 순간, 이 글은 실패담에서 운영 규칙을 고치는 기록으로 바뀌었습니다.

Intake에서 기준 시각과 저장 위치를 고정하고, productId로 매칭하고, 조회 즉시 스냅샷을 남기려 했던 구조는 여전히 유효합니다. 지금 확인된 것은 그 흐름이 실제 순위 조회까지 성공했다는 결과가 아니라, 글에서 사용하려던 API가 중단되어 첫 실행이 막혔고 대체 소스의 접근 범위와 값은 아직 확인 중이라는 상태예요. 이 경계를 솔직하게 적어주신 덕분에 ‘스킬 완성’과 ‘운영 가능’이 다른 단계라는 점이 잘 보입니다.

세 방향 중 무엇을 고를지는 먼저 ‘무슨 순위를 의사결정에 쓸 것인가’로 나누는 편이 맞아 보여요. 공개 검색 화면에서 사용자가 마주치는 위치가 목표라면 브라우저 방식이 같은 질문에 가깝습니다. 판매자 어드민의 값이 실제 운영 판단과 일치하는 경우에는 그 경로가 더 직접적일 수 있고요. 다만 두 후보가 같은 지표를 준다는 점은 아직 미검증이므로 자동 대체시키기보다, source_unavailable에서 멈춰 이전 스냅샷을 보존하고 사람이 소스 변경을 승인하게 두는 것이 안전합니다. 둘 다 원래 질문과 다르다면 그때 순위 추적 자체를 재정의하는 순서가 자연스러워요.

가장 작은 결정 장면은 고정된 키워드와 상품 하나를 두 후보 경로에서 확인해, 각각 어떤 값·기준 시각·식별값을 제공하는지 비교표 한 줄로 남기는 것입니다. 성공 신호는 어느 경로든 숫자가 나오는 것이 아니라, 기존 스냅샷과 같은 의미로 비교 가능한지 또는 다른 지표라서 재설계가 필요한지가 분명해지는 것입니다.

막힌 사실을 감추지 않고 세 대안을 열어 둔 채, 자신의 설계에서 빠진 실패 상태와 사람에게 알릴 지점을 찾아낸 태도가 참 좋았어요. 첫 실행의 중단을 ‘중단 뒤의 행동을 정하는 규칙’으로 바꿔 공유한 덕분에 외부 소스 의존 스킬을 보는 기준이 한층 현실적으로 남았습니다.

자연어회계처리 프로필 이미지

잘 돌아갈 때의 흐름만 신경 쓰기 쉽고 외부 의존성이 깨졌을 때 당황하기 바쁜데 잘 대처가 되시는거 같습니다 ㅎㅎ

필요한 AI 정보만
메일함에 쏙쏙 넣어드려요.

지금 핫한 AI 소식부터 직접 해 본 사례까지, 월요일마다 무료로 받아보세요

이런 사례도 있어요

사례 전체 보기