OMS의 쇼핑몰 API 변경 검토, Claude Cowork 스킬로 자동화하기

한 줄 요약

여러 쇼핑몰에 흩어져 있는 API 변경 공지를 자동으로 모으고, 그 변경이 우리 OMS 연동 코드에 영향을 주는지까지 대조하는 Claude Cowork 스킬을 만들었다. 확인과 대조는 AI가, 결정과 수정은 사람이 맡는다.

왜 쇼핑몰 API 변경 검토를 자동화했나

내가 현재 개발·운영하고 있는 서비스는 OMS(Order Management System)로 여러 쇼핑몰의 주문을 한곳으로 모으고, 상품·배송·취소·반품 같은 업무를 통합해서 처리할 수 있도록 돕는다.

현재 우리 서비스는 네이버, 쿠팡, SSG, 카카오, 11번가, 지마켓을 비롯한 다수의 쇼핑몰과 오픈마켓에 연동되어 있다. 연동 채널이 많을수록 고객이 관리하기는 편해지지만, 개발팀이 계속 살펴봐야 할 외부 변화도 함께 늘어난다.

쇼핑몰은 API와 운영 정책을 수시로 바꾼다.

• 기존 API 종료 또는 신규 버전 전환
• 요청 필수 필드 추가
• 코드값(enum) 변경
• 응답 구조 변경

이런 변경을 놓치면 주문 수집이나 상품·배송 상태 연동에 문제가 생길 수 있기 때문에 변경 공지를 수시로 확인하고, 연동 코드에 영향이 있는지 판단하는 일이 필요하다.

문제는 공지 전달 방식이 쇼핑몰마다 다르다는 점이었다.

어떤 쇼핑몰은 변경 내용을 메일로 보내지만, 어떤 쇼핑몰은 개발자센터 공지사항이나 릴리즈노트에만 등록한다. 즉, 담당자가 메일도 확인하고 여러 사이트를 직접 찾아다니며 새 공지가 있는지 확인해야 했다.

이번에 자동화한 것은 바로 이 과정이다.

흩어진 쇼핑몰 변경 공지를 수집하고, OMS 연동 코드에 미치는 영향까지 확인한다.

목차

1. 기존 방식 — 메일함과 공지사항을 직접 돌아다니기
2. Cowork 스킬이 처리하는 4단계
3. 스킬 구조 — 공통 절차와 몰별 설정 분리
4. 점검 리포트 — 대응할 API와 확인할 코드 위치
5. 자동화의 범위 — AI가 하는 일과 사람이 하는 일
6. 자동화 전후의 변화
7. 남은 과제
8. 마치며 — 확인과 대조는 자동화, 결정은 사람

기존 방식 — 메일함과 공지사항을 직접 돌아다니기

기존 업무는 다음과 같은 순서로 진행됐다.

메일로 도착한 변경 안내 확인 및 쇼핑몰별 공지사항·릴리즈노트 직접 방문
  → 연동과 관련된 변경인지 판단
  → 우리 OMS가 해당 API를 사용하는지 코드 검색
  → 대응이 필요한 위치와 내용을 정리

단순히 공지를 읽는 것으로 끝나지 않는다.

예를 들어 반품 접수 API에 필수 필드가 추가된다는 공지가 올라오면, 우리 서비스가 그 API를 실제로 호출하는지, 어느 코드에서 요청을 만드는지까지 찾아야 비로소 영향 여부를 알 수 있다.

이 방식에는 세 가지 문제가 있었다.

1. 공지가 여러 곳에 흩어져 있다

메일로 오는 공지는 메일함에서 확인할 수 있지만, 공지사항에만 올라오는 변경은 담당자가 직접 찾아야 한다. 확인할 쇼핑몰이 늘어날수록 방문해야 할 사이트도 함께 늘어난다.

2. 확인해야 할 공지는 많고, 실제 영향 건은 적다

이벤트, 프로모션, 시스템 점검처럼 연동 코드와 무관한 공지도 많다. 관련 없는 내용인지 알기 위해서라도 사람이 먼저 열어보고 분류해야 했다.

3. 영향 판단에는 코드 검색이 필요하다

API 변경 공지를 찾은 뒤에는 연동 레포에서 사용 여부와 위치를 다시 확인해야 한다. 이 과정을 놓치거나 늦게 처리하면 주문·상품 연동 장애로 이어질 수 있다.

결국 사람이 많은 시간을 쓴 곳은 최종 판단이 아니라, 판단해야 할 공지를 찾고 관련 코드를 대조하는 과정이었다.

Cowork 스킬이 처리하는 4단계

Claude Cowork 스킬은 변경 공지 확인부터 코드 영향 점검까지 네 단계로 수행한다.

1단계 — 공지 수집

메일로 수신한 변경 안내와 주요 쇼핑몰의 개발자센터 공지사항·릴리즈노트를 정해진 기간 기준으로 수집한다. 각 쇼핑몰마다 공지가 올라오는 위치가 다르기 때문에, 스킬에 점검 대상과 수집 경로를 명시했다.

그런데 위치만 적어두는 걸로는 부족했다. 쇼핑몰마다 페이지가 만들어지는 방식이 다르다. 어떤 곳은 HTML을 그대로 내려주지만, 어떤 곳은 화면을 자바스크립트로 그린다. 후자는 URL만 가져와봐야 빈 껍데기가 돌아오고, 이걸 모르면 “이 몰은 최근 공지가 없다”는 잘못된 결론이 나온다.

그래서 몰별로 직접 확인한 접속 방식을 표로 못 박아뒀다.

주소 자체에도 함정이 있었다. 어떤 몰은 게시판 번호만 넣은 짧은 주소로는 응답이 오지 않고, 제목 문자열까지 포함된 전체 주소를 넣어야만 동작했다.

# 응답 없음
https://<개발자센터>/hc/ko/sections/360004133493

# 정상 동작 — 제목 문자열까지 포함
https://<개발자센터>/hc/ko/sections/360004133493-공지사항

문서에는 없고 직접 해봐야 아는 정보다. 그래서 이런 건 확인한 날짜와 함께 기록하게 했다. 사이트가 개편되면 어느 정보가 오래된 것인지 판단할 수 있어야 하기 때문이다.

2단계 — 연동 영향 공지 선별

수집한 공지 중 연동에 영향을 줄 수 있는 변경만 남긴다.

• 엔드포인트 종료와 버전 전환
• 요청 필수 필드 추가·변경
• 코드값 변경
• 응답 필드와 구조 변경
• 인증 방식·도메인 변경
• 호출량 제한(rate limit) 변경 — 배치 주기에 영향

이벤트나 프로모션, 일반 시스템 점검 안내처럼 연동 코드와 무관한 공지는 제외한다.

여기서 스킬에 넣은 규칙 두 가지가 정확도를 크게 바꿨다.

목록 요약만 보고 판정하지 않는다. 후보는 상세 페이지를 열어 확인한다.

목록 화면은 내용이 잘려 있고 항목 사이의 경계도 뭉개진다. 같은 날 배포된 공지가 여러 건이면 목록에서 뽑은 텍스트는 이렇게 이어붙어 보인다.

2026-06-15 배포  신규  고객 그룹 조회 API 추가
2026-06-15 배포  개선  품목 조회 응답 필드 추가 / 취소 접수 파라미터 변경

한 덩어리로 읽으면 어느 API가 어느 변경에 속하는지 섞인다. “고객 그룹 API의 파라미터가 바뀌었다”처럼 실제로는 없는 변경을 만들어낼 수도 있다. 상세를 열어야 대상 API 경로·변경 필드·시행일이 분리되어 나오고, 목록에는 없는 최종 갱신일(배포 후 내용이 수정된 경우)도 확인할 수 있다.

공지일이 조회 기간을 벗어났더라도, 시행일이 기간 안이거나 임박하면 별도로 보고한다.

공지는 두 달 전에 났는데 시행이 이번 주인 변경이 있다. 공지일만 보고 자르면 이미 시행됐거나 곧 시행될 변경을 그대로 놓친다. 놓쳤을 때 가장 아픈 유형이라 예외 규칙으로 넣었다.

3단계 — OMS 연동 코드 대조

선별한 공지의 API 경로, 필드명, 코드값 등을 기준으로 연동 레포를 검색한다. 우리 OMS가 해당 API를 실제로 사용하는지 확인하고, 영향 가능성이 있는 파일과 위치를 찾는다.

이 단계가 가장 많이 틀렸던 곳이고, 그래서 규칙도 제일 많이 붙었다.

정의되어 있다고 사용 중인 것은 아니다.
우리 코드는 몰별 API를 enum에 모아 관리하는데, 선언되어 있다고 실제로 호출되는 건 아니다. 예전에 만들어두고 쓰지 않는 항목도 남아 있다. 그래서 enum 정의를 찾는 것으로 끝내지 않고 호출 매핑에 활성 등록되어 있는지까지 확인하게 했다.

진짜 소스가 최신 모듈이 아닐 수 있다.
v2 모듈이 있다고 호출 경로가 전부 v2에 있는 건 아니었다. 일부 몰은 여전히 레거시 모듈의 상수 파일이 실제 호출 주소를 들고 있다. 최신 모듈만 뒤지면 “미연동”이라는 틀린 답이 나오기 때문에, 몰별로 어느 파일이 단일 소스인지를 설정에 적어뒀다.

검색 범위를 좁힌다.
src/main 경로만 근거로 인정하고, 테스트나 보관용 디렉터리(src/test/java/old/...)의 매칭은 제외한다. 안 쓰는 코드를 근거로 “사용 중” 판정이 나오는 걸 막기 위해서다.

응답 필드 종료는 파싱 코드까지 열어본다.
“응답에서 특정 필드가 제거됩니다”라는 공지가 와도, 그 API를 호출한다고 무조건 영향이 있는 건 아니다. 응답을 받되 그 필드를 파싱하지 않으면 영향이 없다. 실제로 열어보니 이전 담당자가 이미 대응해둔 흔적이 주석에 남아 있던 건도 있었다.

이 네 가지는 결국 경험 있는 담당자가 머릿속으로 하던 확인 절차다. 자동화하면서 이걸 글로 옮겨 적는 작업이 가장 오래 걸렸고, 효과도 가장 컸다.

4단계 — 점검 리포트 작성

결과를 다음 네 가지로 분류한다.

• 영향 — 현재 코드에서 해당 API를 사용하며 대응이 필요한 경우
• 영향 가능성 — 사용 중이지만 추가 판단이 필요한 경우
• 확인 불가 — 공지 내용만으로 결론을 내릴 수 없는 경우
• 스킵 — 연동과 무관해 제외한 경우

이 자동화에서 가장 중요한 원칙은 추측하지 않는 것이다.

영향 여부를 확정할 근거가 부족하면 괜찮을 것이라고 넘기지 않고 확인 불가로 분리한다. 그래야 담당자가 추가로 확인해야 할 항목이 명확해지고, 리포트 전체를 다시 검증하는 일을 줄일 수 있다.

스킬 구조 — 공통 절차와 몰별 설정 분리

처음에는 스킬 문서 하나에 전부 적었다. 절차도, 몰별 주소도, 코드 검색 단서도 한 파일에. 몰이 두세 개일 때는 괜찮았는데 다섯 개가 되니 몰 하나를 추가할 때마다 문서 전체를 건드리게 됐다.

그래서 공통 절차와 몰별 설정을 분리했다.

api-change-checker/
├── SKILL.md              # 공통 절차 · 판단 기준 · 리포트 양식
└── references/
    ├── _template.md      # 새 몰 추가용 템플릿
    ├── smartstore.md     # 네이버 스마트스토어
    ├── coupang.md
    ├── ssg.md
    ├── kakao.md
    └── cafe24.md

SKILL.md에는 기간을 어떻게 자르는지, 어떤 변경을 영향으로 볼지, 결과를 어떤 양식으로 낼지처럼 모든 몰에 공통인 것만 남긴다. 몰별로 다른 것은 전부 references/ 아래로 뺐고, 점검 대상이 정해지면 해당 파일부터 읽고 그 단서대로 진행한다.

reference 파일은 이런 구성이다. (실제 값은 사내 정보라 형태만 옮겼다)

# 네이버 스마트스토어 설정

## 1. 접근성
- 공지 목록 외부 접근: 가능
- 렌더링 방식: 정적 조회 가능, 빈 결과면 브라우저로 전환

## 2. 공지 목록
- 목록 URL: <릴리즈노트 URL>, <공지사항 URL>   ← 두 곳 모두 확인
- 게시일 표기: 목록의 작성일, 상세는 제목 아래

## 3. 레포 호출부 단서
- base URL 설정 키: ${oms.smartstore.host}
- 엔드포인트 단일 소스: interfaces/v2/smartstore/SmartstoreApis.java
  → enum 에 (IF명, path, HttpMethod, 응답타입) 정의
- 경로 패턴: /external/v1/..., /external/v2/..., /partner/v1/...
- IF 코드 예: SMARTSTORE_BA001 / IF명(한글)도 enum 첫 인자

## 4. 알려진 주의점
- 경로에 버전 표기 → v1→v2 전환 공지 주의
- 토큰 기반 전자서명 인증 → 인증 방식 변경 공지면 서명 모듈 영향
- 주석에 sandbox 주소가 남아 있음 → 운영 주소만 쓰는지 확인

이렇게 나눠놓으니 새 몰 추가가 파일 하나 채우는 작업이 됐다. 템플릿을 복사해 네 항목만 채우면 되고, 공통 절차는 손댈 필요가 없다.

특히 4. 알려진 주의점이 유용했다. 어떤 몰은 인증 방식이 특이하다거나, 문서와 실제 동작이 다르다거나 하는 원래 사람 머릿속에만 있던 예외 사항을 적어두는 자리다. 자동화를 하려니 결국 꺼내서 적어야 했고, 적고 나니 신규 입사자에게 설명할 문서도 같이 생겼다.

점검 리포트 — 대응할 API와 확인할 코드 위치

리포트의 목적은 공지를 요약하는 데 있지 않다.

담당자가 어떤 변경에 대응할지, 그리고 코드를 어디서 확인할지 바로 알 수 있어야 한다.

공지 기반 연동 점검 리포트
기간 2026-06-13 ~ 2026-07-13

대상 5개 몰 | 신규 공지 18 | 영향 3 | 영향 가능성 2 | 확인 불가 1

[영향] [쿠팡] 반품접수 API 필수 필드 추가
· 변경      claimType 필드 필수화
· 우리 사용  사용함 — <반품 처리 서비스>:214
· 점검      요청 데이터에 claimType 전송 로직 추가 필요

[영향] [SSG] 취소신청 목록조회 API v2 전환
· 우리 사용  사용함 — <취소 조회 서비스>:88
· 점검      종료 일정 전 v2 엔드포인트 전환 필요

[영향 가능성] [네이버] 정산 응답 구조 변경
· 사유      응답 필드 재편에 따른 파싱 영향 추가 확인 필요

스킵 13건 — 이벤트·시스템 점검 등 연동과 무관한 공지

위 내용은 리포트 형식을 설명하기 위한 예시다.

실제 리포트에는 공지 출처와 변경 내용, 사용 여부, 확인할 파일과 위치, 필요한 대응 방향을 담는다. 코드 본문이나 인증 정보는 포함하지 않는다.

스킵 건수도 함께 남긴다. 결과에 영향 건만 있으면 전체 공지를 제대로 확인한 것인지 알기 어렵다. 제외한 건수를 보여주면 누락한 것이 아니라 확인 후 제외했다는 사실을 알 수 있다.

같은 이유로 리포트 마지막에 확인한 공지 소스를 넣었다. 어느 몰의 어느 페이지를 봤고, 그중 최신 공지가 며칠 자였는지를 함께 적는다.

확인한 공지 소스
· 쿠팡              <공지사항 목록 URL>   — 최신 07-02
· SSG               <공지사항 목록 URL>   — 최신 06-28
· 네이버 스마트스토어  <릴리즈노트 URL>      — 최신 06-20

영향 0건인 주에 특히 중요하다. “정말 변경이 없었던 것”과 “수집이 실패한 것”은 겉으로 똑같아 보인다. 최신 공지 날짜가 찍혀 있으면 제대로 확인한 결과라는 근거가 된다.

각 항목에 공지 상세 링크를 반드시 다는 것도 같은 맥락이다. 링크가 없으면 담당자가 원문을 보려고 다시 검색하게 되고, 그러면 자동화한 의미가 줄어든다.

자동화의 범위 — AI가 하는 일과 사람이 하는 일

이번 자동화는 공지를 찾고 영향 가능성이 있는 코드를 알려주는 데까지만 담당한다.

코드는 읽기 전용으로 검색하며, 자동으로 수정하거나 커밋하지 않는다. 공지와 코드만으로 판단할 수 없는 내용도 사람이 확인하도록 남겨둔다.

OMS의 주문·배송·정산 연동은 잘못 수정했을 때 영향이 크다. 그래서 반복적인 확인과 대조는 자동화하되, 실제 변경에 대한 결정과 수정은 사람이 담당하도록 범위를 나눴다.

자동화 전후의 변화

가장 큰 변화는 시간 절감이 아니라, 사람이 업무를 시작하는 지점이 달라졌다는 것이다.

이전에는 새 공지가 있는지 찾는 일부터 시작했다면, 이제는 정리된 영향 후보를 보고 대응 여부를 판단하는 일부터 시작한다.

남은 과제

• 쇼핑몰별 공지 형식과 수집 경로를 정리해 점검 대상을 확대한다.
• 자동 실행과 담당자 알림을 연결해 확인 주기를 안정화한다.
• 누락과 오분류를 기록해 자동화 정확도를 측정한다.
• 리포트 이력을 쌓아 쇼핑몰별 변경 빈도와 대응 내역을 관리한다.

다수의 연동 쇼핑몰을 한 번에 모두 자동화하기보다, 주요 쇼핑몰부터 정확도를 확인하며 단계적으로 확대할 계획이다.

마치며 — 확인과 대조는 자동화, 결정은 사람

이번에 자동화한 핵심은 쇼핑몰의 변경 자체가 아니라, 그 변경을 찾아 OMS에 미치는 영향을 검토하는 과정이다.

여러 외부 쇼핑몰과 연결되는 OMS에서는 API 변경을 피할 수 없다. 하지만 메일함과 공지사항을 돌아다니며 변경을 찾고, 관련 코드를 반복해서 검색하는 일까지 계속 사람이 할 필요는 없다.

공지는 AI가 모으고, 연동 영향 후보도 AI가 대조한다. 사람은 근거가 정리된 결과를 바탕으로 결정하고 수정한다.

확인과 대조는 자동화하고, 결정은 사람에게 남기는 것. 이번 자동화에서 정한 가장 중요한 기준이다.

피드백은 언제나 환영입니다.