# Trade Stats Lookup

> HS코드별·국가별 수출입 실적과 시계열 추이를 조회하고 어느 시장부터 뚫을지 우선순위를 산출한다. 바이어 발굴 이전 단계인 시장 선정 도구다. 바이어·수입업체 기업명은 제공하지 않지만(관세법상 비공개), "바이어를 어떻게 찾느냐"는 질문 자체는 이 스킬이 받는 범위이고 못 드리는 이유부터 답한다. 사용자가 HS코드, 수출, 수입, 무역통계, 해외시장, 시장조사, 신규 수출국 발굴, 수출국 비교, 경쟁국 점유율, 시장 규모, 단가 추이, 시장성, "어느 나라에 팔지", "이 품목 수출 어때", "어디부터 뚫어야 해" 같은 말을 하면 반드시 이 스킬을 사용하세요. '무역통계'라는 단어를 직접 쓰지 않아도 되고, 품목명만 말해도(예를 들어 "화장품 중동 시장 어때", "폴리에스터 수지 베트남") 이 스킬로 처리하세요. 반대로 국가만 정하고 품목을 못 정한 질문("싱가포르에 뭘 팔면 좋을까", "베트남 유망 품목", "1인 무역 아이템")도 역방향 품목 조회로 처리합니다. 관세 질문("베트남 관세 몇 %", "FTA 혜택 있어?", "중국산보다 유리해?")도 상대국이 한국산에 적용하는 세율 조회로 처리합니다. 한국이 아직 수출하지 않는 나라까지 포함해 전 세계에서 신규 시장을 찾는 발굴 조회도 지원합니다("어디 새로 뚫을까", "안 가본 시장", "신규 시장 찾아줘", "유망한 나라"). 핵심 기능은 인증키 없이 UN Comtrade·World Bank WITS 공개 데이터로 동작합니다. HSK 10단위·관세청·'더 최신 데이터'·'우리 제품만 정확히'·단가 변동 원인을 사용자가 직접 물으면 관세청 정밀 조회로 처리하되, 그때만 인증키 발급을 안내합니다(무료).

- Skill: `bonghyunyang/trade-stats-lookup` (Agent Skill, multi-file: 19 files)
- Install (CLI): `npx skillmds@latest add bonghyunyang/trade-stats-lookup`
- Raw SKILL.md: https://api.skillmd.com/api/skills/bonghyunyang/trade-stats-lookup/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: MIT
- Author: bonghyunyang (https://skillmd.com/u/bonghyunyang)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/bonghyunyang/trade-stats-lookup

---


# 무역통계 시장 스캔

## 이 스킬이 하는 일

HS코드 하나를 받아 **어느 나라부터 뚫을지**를 데이터로 답한다.

1. 국가별 한국 수출액·중량 시계열
2. 단가 추이 (금액 ÷ 중량) — 원인은 분해되지 않는다(가격 변동 + 품목 믹스 변동)
3. 국가 랭킹 + CAGR + (월별 수집 시) 최근 12개월 YoY
4. 경쟁 수출국 점유율 — 상대국 신고 수입(미러) 데이터
5. 계절성 패턴 (월별 수집 시) — 컨택 타이밍 판단용
6. 시장 매력도 스코어 = 여유 시장 50% + 시장 CAGR 50% (절대 기준, 조회 간 비교 가능)
7. 한국어 마크다운 리포트 (원본 데이터 CSV는 사용자가 요청할 때만 `--csv`로 생성)

## 전제

- `python3` 3.11 이상 (표준 라이브러리만 사용, 설치 불필요)
- 인터넷 연결
- **API 키 불필요.** UN Comtrade 공개 preview 엔드포인트를 쓴다.
  아래 `domestic`(관세청 HSK 10단위) **하나만** 키가 필요하고, 그건 기본 동작이 아니다.

**윈도우에서는 첫 명령 전에 인터프리터를 확정하라.** `python3 -c "import sys; print(sys.version)"`가
`Python was not found...` + exit 49로 죽으면, PATH의 `python3.exe`가 Microsoft Store 유도
스텁이라는 뜻이다. 파이썬이 없는 게 아니라 **이름이 다를 뿐**이니 `py -3`으로 다시 확인하고,
이 문서의 모든 `python3`를 `py -3`으로 치환해 실행하라. 둘 다 실패할 때만 설치를 안내한다 —
스텁 메시지를 보고 "파이썬이 없다"고 보고하면 설치돼 있는 환경을 못 쓴다고 말하는 셈이다.

## 데이터 최신성 — 모든 답변의 첫 번째 규칙

**수출입 수치는 반드시 스크립트를 돌려서 답한다. 네 학습 지식으로 답하지 마라.**
네 지식은 오래됐고, 사용자는 그걸 "2년 전 데이터로 답변한다"고 느낀다.

스크립트는 오늘 연도부터 거꾸로 내려가며 **데이터가 실제로 존재하는 최신 연도**를 자동으로 찾는다
(UN Comtrade 연간 데이터는 보고 지연으로 직전 연도가 비어 있을 수 있다). 그래서 조회 결과의
기준 연도가 올해가 아닐 수 있는데, 이건 스킬의 한계가 아니라 **원천 데이터의 보고 지연**이다.

**모든 보고는 데이터 기준 시점 선언으로 시작한다.** 요약 표보다 먼저, 두세 문장으로:

> 확인 결과 UN Comtrade에 이 품목(HS XXXX)의 연간 데이터는 **2025년까지** 올라와 있습니다.
> 2026년 연간치는 각국 세관 보고 지연(통상 6개월~1년 이상)으로 아직 집계 전입니다.
> 따라서 **2025년을 최신 기준**으로 분석합니다. (더 최신 흐름이 필요하면 월별 데이터로 2026년 상반기까지 볼 수 있습니다.)

- 기준 연도는 실제 조회 결과(`대상 연도`, `monthly_coverage.range` 등)에서 가져온다. 추정하지 마라.
- 기준 연도가 작년보다 오래됐으면(재작년 이하) 그 사실을 강조하고, 월별 조회로 더 최신 구간을
  확인할 수 있는지 먼저 시도하거나 제안하라. 월별 데이터가 연간보다 몇 개월 더 최신인 경우가 많다.
- 캐시(7일)가 의심될 만큼 결과가 오래됐으면 `TRADE_STATS_CACHE_TTL=0`으로 한 번 강제 재조회해 확인하라.

## 두 가지 조회 — 먼저 어느 쪽인지 판단하라

🚦 **그 전에**: 발화에 "바이어", "거래처", "수입업체", "업체 찾아줘"가 섞여 있으면 스크립트도
품목 질문도 그 다음이다. **첫 답변의 첫 문단에 이 셋을 먼저 써라** — ① 기업명은 못 드립니다
(한국은 관세법상 신고정보가 비밀유지 대상이라 기업명×품목×금액이 어디에도 공개되지 않는다)
② 기업 단위가 필요하면 B/L 공개국(미국·인도)의 유료 데이터(Panjiva·ImportYeti·Volza)
③ 대신 어느 나라로 갈지는 지금 정할 수 있습니다 — 그러고 나서 품목과 명령을 묻는다.
빼먹고 조회부터 돌리면 사용자는 원한 걸 못 받은 채 10분을 기다린다. 말이 먼저, 조회가 나중이다.

| 사용자가 원하는 것 | 명령 | 대상국 | 소요 |
|---|---|---|---|
| **이미 아는 나라들 중 어디부터** | `market` | 지정 또는 한국 교역 상위 10개국 | 3~5분 |
| **안 가본 나라까지 포함해 새로 발굴** | `discover` | 전 세계 225개 보고국 | 1~2분 |
| 우리 제품 라인을 HSK 10단위로 정밀하게 | `domestic` | 지정 국가 | 10초~1분 · **키 필요** |

`market`의 기본 대상은 한국 교역 상위 10개국이다. **그 10개국은 정의상 이미 팔고 있는
나라라서 거기서는 신규 시장이 나오지 않는다.** "새로 뚫을 데", "안 가본 시장", "유망한 나라"
같은 질문에 `market`을 돌리면 이미 아는 답만 나온다 — 그때는 `discover`를 써라.

⏱ **첫 조회 1~2분**(실측 HS3304 96초, 9콜). 두 연도를 전량 훑는데도 이 정도인 건 집계
시리즈만 요청해 배치 하나에 50개국이 들어가기 때문이다. `timeout`은 300000으로 준다.

```bash
python3 analyze.py discover --hs 3304   # timeout: 300000
```

두 연도 모두 전량 훑는다 — 최신 연도는 전 보고국, 과거 연도는 여유 시장 하한을 넘긴
나라 전부다. 결과의 `method_note`에 이 범위가 담겨 있으니 그대로 전달하라.
JSON 요약과 함께 `~/trade-stats-out/hs<코드>_discover.md`가 남는다. **경로를 알려줘라.**

결과에는 국가별로 태그가 붙는다 — `미개척`(한국 점유율 1% 미만), `초기진입`(5% 미만),
`고성장`(시장 CAGR 10% 이상), `시장축소`(CAGR 음수), `집계주의`.

⚠️ **`집계주의` 태그가 붙은 나라는 그 숫자를 단독으로 인용하지 마라.** 그 나라가 집계행
없이 내역행만 신고해서 총수입이 과대·과소집계일 수 있다는 뜻이다. 보고할 때 "이 나라는
통계 신고 형식 때문에 총액이 정확하지 않을 수 있다"고 덧붙이고, 후보로 살릴 거면
`market --countries <그 나라>`로 다시 확인하라.

`discover`는 **경쟁 구도를 모른다.** 1위 공급국·과점 여부·한국 수출 추이는 이 스캔에
없다. 후보가 2~5개국으로 좁혀지면 반드시 `market --hs <코드> --countries <국가들>`로
넘어가라 — 그게 이 스킬의 본 워크플로다.

## 기본 동작 — 이대로 하면 된다

사용자가 품목/HS코드를 말하면:

```bash
cd <스킬 경로>/scripts
python3 analyze.py market --hs 3907
```

기본값이 **한국 전체 교역 상위 10개국**(중국·미국·베트남·대만·홍콩·일본·싱가포르·인도·호주·말레이시아)이다.
사용자가 특정 국가를 지목하지 않았으면 이 기본값으로 먼저 돌린다.

⏱ **캐시가 비어 있으면 3~5분 걸린다** (10개국 = 약 35콜, 콜당 2초 + 429 발생 시 자동 감속).
**Bash 기본 타임아웃(120초)으로는 반드시 죽는다 — `timeout`을 600000(10분)으로 지정해 실행하라.**
같은 조회 재실행은 캐시로 1초 안에 끝난다. 조회 전에 사용자에게 소요 시간을 말해둬라.

stdout으로 JSON 요약이, `~/trade-stats-out/hs<코드>_report.md`에 리포트가 나온다.
**JSON 요약만 읽고 사용자에게 설명하라.**

**CSV는 사용자가 원본 데이터·엑셀 파일을 요청할 때만 만든다.** 그때 `--csv`를 붙여 같은 명령을
다시 돌리면 캐시 덕에 즉시 끝나고 CSV가 생성된다. 요청 없이 미리 만들거나 경로를 안내하지 마라.
**재실행 시 1회차와 완전히 동일한 옵션 전체(`--countries`, `--top`, `--monthly`, `--years`)를
그대로 반복하고 `--csv`만 추가하라.** 하나라도 빠뜨리면 대상국·월별 데이터가 달라진 리포트가
기존 리포트를 조용히 덮어쓴다.

CSV에는 수치만이 아니라 **근거 컬럼이 함께 들어간다** — 각 수치의 기준 연도, 성장률 계산 구간,
상대국 통계가 최신이 아니면 그 사실(`partner_import_lagged`), 비고, 출처, 조회일. 컬럼 뜻을
설명하는 `hs<코드>_columns.md`도 같이 생성된다. **CSV를 건넬 때 답변에 이걸 명시하라**:
근거 컬럼이 포함돼 있다는 것, 설명 파일이 있다는 것, 그리고 특히 기준 연도가 다른 컬럼이
섞여 있으면(예: 한국 수출은 2025년인데 상대국 수입 통계는 2024년) 그 사실을 실무자 언어로.
"미러", "stale", "후퇴 조회" 같은 내부 용어를 답변에 쓰지 마라 — "그 나라가 아직 최신 연도
통계를 안 올려서 한 해 전 기준입니다"처럼 풀어 써라.

⚠️ **백그라운드로 돌리지 마라.** 몇 분이 길어 보여 `run_in_background`를 쓰고 싶겠지만,
셸이 중간에 종료되면서 출력 폴더가 만들어지지 않는 사례가 반복 확인됐다. 포그라운드로 기다려라.
출력은 기본이 `~/trade-stats-out`이다. **스킬 폴더 안에 쓰지 마라** — 플러그인을 업데이트하면
날아가고 사용자가 찾지도 못한다. 조회를 여러 번 겹쳐 돌릴 때만 `--outdir`로 갈라라.

### 국가를 지정할 때

```bash
python3 analyze.py market --hs 3304 --countries KZ,UZ,KG --years 3
```

`--countries`는 한글명도 받는다: `--countries 카자흐스탄,우즈베키스탄`

### 월별 시계열·계절성이 필요할 때

```bash
python3 analyze.py market --hs 3304 --countries VN --monthly 24
```

`--monthly N`은 **국가당 N콜 + 최신월 탐색 몇 콜**이라 느리다(콜당 약 2초). 24개월 × 3개국 = 약 3분.
국가를 2~3개로 좁힌 뒤에만 쓴다. 전체 상위 10개국에 붙이지 마라 — 10분 넘게 걸린다.

- **`--monthly 24` 미만을 쓰지 마라.** YoY는 24개월, 계절성은 각 달 2회 이상 관측이 필요하다.
  모자라면 스크립트가 계산하지 않고 이유를 `yoy_note`/`seasonality`에 담아준다. 그대로 전달하라.
- 월별 보고는 2~6개월 지연된다. 스크립트가 **데이터가 실제로 있는 최신 월을 먼저 찾고** 거기서부터
  N개월을 뒤로 잡는다. 그래서 "최근 24개월"은 오늘 기준이 아니라 보고 기준이다.
  `monthly_coverage.range`에 실제 구간이 들어 있으니 사용자에게 이 구간을 말해줘라.

### 국가는 정했는데 품목을 모를 때 — 역방향 조회

"싱가포르에 뭘 팔면 좋을까", "유망 품목이 뭐야" 같은 질문이면 HS코드를 묻지 말고 이걸 돌려라:

```bash
python3 analyze.py products --to 싱가포르
```

한국이 그 나라에 **이미 팔고 있는** 전 품목을 챕터(HS2)·품목(HS4) 단위로 훑어
규모 상위와 성장 상위(기본: 최신연도 vs 2년 전, 수출액 $1M 이상)를 JSON으로 준다.
한국 수출 실적은 "수요가 검증됐다"의 근거이지, 그 물량을 신규 진입자가 가져올 수 있다는
뜻이 아니다 — 이 구분을 답변에 항상 포함하라.

보고할 때:

- **사용자의 체급에 맞춰 걸러라.** 1인 상사·중소기업이면 반도체(85)·석유(27)·선박(89)·
  기계(84)·귀금속(71) 같은 대기업 영역 챕터는 표에서 빼고 그 사실을 한 줄로 밝힌다.
  소비재·경량 품목(화장품 33, 식품 16–22, 생활화학 34, 과일 07–08 등) 위주로 추린다.
- 성장 상위 목록에는 급성장했지만 절대액이 작은 품목이 섞인다. 규모 표와 성장 표를
  분리해서 보여주고, `hs4_declining`의 감소세 품목도 "피할 품목" 표로 알려준다.
- HS4 상세(규모·성장·감소 표)는 수출액 상위 챕터만 조회한 것이다. `hs4_coverage.note`에
  커버리지 %가 들어 있으니 보고에 그대로 전달하라. 챕터(HS2) 표만 전 품목 기준이다 —
  관심 챕터가 커버 목록에 없으면 그 챕터를 지목해 다시 조회하면 된다.
- 후보 품목이 1~2개로 좁혀지면 그 HS코드로 `market`을 돌려 경쟁 구도·주변국 비교로
  넘어간다 — 그게 이 스킬의 본 워크플로다.

## 주요 옵션

| 옵션 | 기본 | 설명 |
|---|---|---|
| `--hs` | (필수) | HS 2/4/6 단위 |
| `--countries` | - | 쉼표 구분, ISO2·한글명·숫자코드 모두 가능 |
| `--preset` | `kr-top` | `kr-top`=한국 전체 교역 상위국 / `hs-top`=이 HS의 한국 수출 상위국 |
| `--top` | 10 | 대상국 수 |
| `--years` | 3 | 연간 시계열 길이 |
| `--monthly N` | - | 최근 N개월 월별 수집 (국가당 N콜) |
| `--no-competitors` | - | 미러 조회 생략. **매력도 점수도 안 나온다** (아래 참조) |
| `--csv` | - | 원본 데이터 CSV도 저장. **사용자가 요청할 때만** 붙인다 |
| `--outdir` | `~/trade-stats-out` | 출력 폴더. 스킬 폴더 안으로 돌리지 마라 |

## 관세청 정밀 조회 (`domestic`) — 기본이 아니다, 먼저 꺼내지 마라

**이 스킬은 키 없이 쓰는 도구다.** `market`, `discover`, `products`, `hs-search`, 관세율은
전부 키 없이 돈다. `domestic` 하나만 관세청 인증키가 필요하고, **먼저 권하지 마라.**

사용자가 아래를 **직접 물었을 때만** 꺼낸다. 그때 `references/customs-hsk.md`를 읽고 따른다.

- HS 6단위로 우리 제품이 특정되지 않을 때 ("우리는 그 코드 안에서 OO만 만든다")
- 단가가 오르내린 **원인**을 물을 때 (HS6는 분해 불가, HSK 10단위는 가능)
- 더 최신 숫자를 요구할 때 ("올해 것 없어?") — 관세청은 익월 공표다
- HSK, 10단위, 관세청을 사용자가 직접 언급할 때

시장 규모, 경쟁국 점유율, 매력도, "어느 나라부터"는 이걸로 답할 수 없다. 상대국 신고
통계라서 관세청에 아예 없다. 그런 질문에 `domestic`을 꺼내지 마라.

키가 없으면 명령이 발급 안내를 그대로 뱉는다. **그 안내문을 전달하되, 키 없이 지금
답할 수 있는 부분을 먼저 답하라.** 사용자가 "됐고"라고 하면 다시 권하지 않는다.

## 발굴 조회 옵션

| 옵션 | 기본 | 설명 |
|---|---|---|
| `--hs` | (필수) | HS 2/4/6 단위 |
| `--top` | 20 | 결과로 낼 상위 국가 수 |
| `--min-market` | 1천만 달러 | 여유 시장 하한. 이 밑은 "규모 미달"로 제외. 소량·고단가 품목이면 낮춰라 |
| `--years-gap` | 2 | 성장률 비교 간격 |

## 보조 명령

HS코드를 모를 때 — **한국어 품목명을 그대로 넣어라.** 번역하지 마라.

```bash
python3 fetch_comtrade.py hs-search "화장품"
python3 fetch_comtrade.py hs-search "이차전지"
python3 fetch_comtrade.py hs-search "자동차부품" --level 4
```

한국어 색인(챕터 96개 + 주요 품목 123개)이 내장돼 있다. 결과의 `matched` 필드가
`ko`면 한국어 색인이 잡은 것이고 `ko_keyword`에 걸린 단어가 담긴다 — 사용자에게 이걸 보여주고 확인받아라.

한국어로 안 잡히면 그때 영어로 재검색한다. 번역 힌트는 `references/hs-codes.md`.

```bash
python3 fetch_comtrade.py hs-search "polyethylene terephthalate"
```

국가 코드 확인:

```bash
python3 fetch_comtrade.py country-search 카자흐
```

단발 조회 (리포트 없이):

```bash
python3 fetch_comtrade.py rank --hs 3907 --year 2025          # 전체 상대국 랭킹, 1콜
python3 fetch_comtrade.py mirror --hs 3907 --importer VN --year 2024
python3 fetch_comtrade.py series --hs 3907 --partner US --from 2024-01 --to 2025-12
```

## 관세율 조회 — 상대국이 한국산에 무는 세율

"베트남 관세 몇 %야", "FTA 혜택 있어?", "중국보다 유리해?" 같은 질문이면
`references/tariff.md`를 읽고 따른다. World Bank WITS 데이터라 인증키는 필요 없다.
한국 관세청 세율(한국이 수입할 때)이 아니라 **상대국이 한국산에 적용한 세율**이고,
**느리다 — 단독 2~5분, `--compare` 3개국이면 5~10분이라 `timeout` 600000이 필요하다.**
기준 연도 고지와 TradeNavi 재확인 안내를 포함해 상세 규칙은 참조 파일에 있다.
시장 보고의 ③ 다음 단계에서 제안하기 좋다 — 점유율 격차의 원인이 관세인 경우가 많다.

## 워크플로

1. 사용자가 품목명만 말했으면 `hs-search`에 **한국어 그대로** 넣어 후보를 찾고,
   **어느 코드로 볼지 먼저 확인받는다.** 잘못된 코드로 만든 리포트는 숫자가 그럴듯해서 더 위험하다.
   기본은 HS 4단위, 제품이 특정되면 6단위를 쓴다. 갈리는 코드면 스크립트가 멈춘다(종료코드 3).
   후보를 보여줄 때는 코드·설명·걸린 한국어 키워드를 같이 보여준다.
2. 사용자가 HS 8/10단위를 줬으면 앞 6자리로 자른다고 **명시적으로 말하고** 진행한다.
   (UN Comtrade는 6단위까지만 있다.)
3. 국가 지정이 없으면: **"새로 뚫을 데"를 묻는 질문이면 `discover`**, 아니면 상위 10개국
   기본값으로 `analyze.py market`을 돌린다. 판단이 애매하면 사용자에게 한 줄로 물어라 —
   "이미 거래 중인 나라들 중에서 볼까요, 안 가본 나라까지 찾아볼까요?"
4. JSON 요약을 읽고 **아래 "보고 형식"대로** 한국어로 보고한다. 줄글로 풀어쓰지 마라.
5. 관심 국가가 2~3개로 좁혀지면 `--monthly 24`로 다시 돌려 계절성·YoY를 본다.
6. 사용자가 원본 데이터·엑셀 파일을 원하면 그때 `--csv`로 재실행해(캐시라 즉시 끝난다)
   경로를 알려준다. 엑셀에서 바로 열린다(UTF-8 BOM). 근거 컬럼·설명 파일이 포함됐음을
   답변에 명시한다(위 "기본 동작"의 CSV 규칙 참조).

## 보고 형식 — 표 먼저, 근거는 그 다음

결과 보고는 반드시 이 순서다. 그 외의 서론·배경 설명으로 시작하지 마라.

**⓪ 데이터 기준 시점 (두세 문장).** 위 "데이터 최신성" 규칙대로 — 어느 시점까지의 데이터가
확보됐고, 왜 그게 최신이며, 이걸 기준으로 분석한다는 선언. 이것만 표보다 앞에 온다.

**① 요약 표.** 조회된 전 국가를 한 표에 담는다. 열 구성:

| 순위 | 국가 | 매력도 | 시장규모(총수입) | 시장 CAGR | 한국 수출액 | 한국 수출 CAGR | 한국 점유율(수입 기준) | 1위 공급국(점유율) |
|---|---|---|---|---|---|---|---|---|

- 금액은 `$1.2B`, `$340M`처럼 축약하고 연도를 열 머리에 명시한다 (예: "한국 수출액(2025)").
- 순위 제외 국가도 표에서 빼지 말고 매력도 칸에 `제외(데이터 부족)`처럼 **세 단어 이내**로
  넣는다. `score_note` 전문은 표 한 칸에 안 들어가니 표 아래 각주로 옮겨라. 측정 불가 ≠ 나쁜 시장.
- 값이 없는 칸은 `-`로 두고 추정으로 채우지 않는다.
- 표 바로 아래에 결론 한두 문장: 어느 나라부터, 왜.

**② 표 근거 — 정량 데이터는 전부 표로.** 표의 판단이 어떤 숫자에서 나왔는지를 보여준다.
**수치가 2개 이상 나열되는 항목은 줄글·불릿이 아니라 표로 만든다.** 불릿은 표 아래
한 줄 해석에만 쓴다. 형용사("빠르게 성장", "점유율이 높다")만 쓰지 말고 반드시 수치를 병기하라.

- **경쟁 구도 표**: 국가별 상위 공급국과 점유율 %, 한국 순위·%를 표로.
  `dominated`가 true면 과점 시장이라고 표 아래에 명시.
- **CAGR 격차 표**: 국가별로 시장 CAGR | 한국 수출 CAGR | 격차(%p)를 표로.
  격차가 음수면 점유율을 잃는 중이라고 해석을 붙인다.
- **단가 표** (여러 국가·연도가 있으면): 변화폭 %만 제시하고 원인은 단정하지 않는다
  ("프리미엄화" 금지 — 품목 믹스 변동일 수 있다).
- **상위 3개국 해석**: 어느 축(규모/성장/여유) 때문에 올라왔는지를 축별 수치로 한 줄씩.
  예: "베트남 — 시장규모 $2.1B(조회국 중 1위), 시장 CAGR +14%, 한국 점유율 8% → 여유 축 상위"
- **실측 가중치**: 명목 가중치(40/35/25)가 아니라 리포트가 출력한 실측 비중으로 어느 축이 순위를 갈랐는지.
- **데이터 공백**: 비어 있는 국가·연도는 비어 있다고 명시. `stale`, `score_basis`, 각종
  `*_note`의 **내용은 빠짐없이 전달하되**, 필드명·영문 키 자체는 노출하지 말고 실무자
  언어로 풀어 쓴다(위 "기본 동작"의 용어 규칙과 같은 원칙).

**③ 다음 단계 제안 (짧게).** 월별 추이·계절성까지 볼 후보 국가 제안, **상위 후보국 시장 동향
브리핑 제안**(아래 "시장 브리핑" 참조). 원본 데이터가 필요하면 엑셀용 CSV로 뽑아줄 수 있다고
한 줄만 언급한다 — 경로는 실제 요청받아 생성한 뒤에 알려준다.

월별 조회 결과도 같은 원칙: YoY·계절성을 월별 수치 표로 먼저, 해석은 그 아래.

**명령어·플래그를 답변에 노출하지 마라.** 사용자는 해외영업 실무자이지 개발자가 아니다.
`--monthly 24`, `analyze.py market` 같은 것은 네가 내부에서 쓰는 도구일 뿐이다.
"월별 추이를 이어서 볼까요? 베트남·인도 2개국이면 3분쯤 걸립니다"처럼 자연어로 제안하고,
사용자가 하겠다고 하면 네가 알아서 돌려라. 옵션 선택이 필요하면 옵션명이 아니라
그 옵션이 답하는 질문("최근 2년 월별로 볼까요, 연간 추이만 볼까요?")으로 물어라.

## 시장 브리핑 — 통계 다음의 옵트인 단계

통계 표를 받은 사용자의 다음 질문은 "그래서 그 나라 시장이 지금 어떤데?"다. Comtrade 숫자에
없는 것(규제·관세 변화, 현지 수요 트렌드, 최근 업계 동향)은 웹 검색으로 보완할 수 있다.

**기본은 끈다. 자동으로 붙이지 마라.** 통계 보고의 ③ 다음 단계에서
"1~2위 국가의 시장 동향 브리핑을 이어서 볼까요?"처럼 제안만 하고, 사용자가 원할 때만 진행한다.
매 조회마다 자동으로 붙이면 응답이 길고 느려진다.

진행할 때는 상위 1~2개국으로 좁혀 WebSearch로 조사한다. 조사 축: ① 해당 품목 관련 규제·관세·
인증 변화 ② 현지 수요·트렌드 ③ 주요 경쟁사·업계 최근 동향. 오래된 기사보다 최근 1년 내 출처를
우선하고, 언제 시점의 정보인지 밝힌다.

**정량과 정성을 절대 섞지 마라.**

- 브리핑은 통계 보고와 **별도 섹션**("○○ 시장 브리핑 — 웹 검색 기반")으로 분리한다.
  Comtrade 수치는 검증 가능한 데이터고 웹 브리핑은 출처 신뢰도가 제각각이다. 섞으면
  리포트 전체의 신뢰성이 가장 약한 출처 수준으로 떨어진다.
- 브리핑의 모든 주장에는 **출처 링크**를 단다. 출처를 못 찾은 내용은 쓰지 않는다.
- 브리핑 내용으로 매력도 순위나 표의 수치를 수정하지 않는다. 순위는 통계만으로 산출된 것이다.
  브리핑이 순위와 다른 방향을 가리키면(예: 통계상 1위인데 규제 강화 소식) 둘 다 제시하고
  판단 재료로 넘긴다.

## "바이어 찾아줘"라는 요청을 받으면

이 스킬은 바이어 실명을 줄 수 없다. 그런데 사용자는 결국 이걸 묻는다. **얼버무리지 말고
먼저 못 한다고 말한 다음, 할 수 있는 걸로 연결하라.** 순서를 바꾸면 안 된다.

1. **왜 없는지 한 문장으로.** "한국은 관세법상 신고정보가 비밀유지 대상이라 기업명×품목×금액이
   어디에도 공개되지 않습니다. 관세청도 무역협회도 마찬가지입니다." — 도구의 한계가 아니라
   법적 제약이라는 점이 중요하다. 그래야 다른 무료 도구를 더 찾아 헤매지 않는다.
2. **유료 경로.** B/L 공개국만 기업 단위가 나온다 — 미국·인도 등. Panjiva / ImportYeti / Volza.
3. **질문을 뒤집어 제안한다.** "대신 어느 나라에 바이어를 찾으러 갈지는 지금 정할 수 있습니다."
   바이어 발굴의 앞 단계다. 품목을 물어보고 진행하라. 사과는 한 번이면 된다.

## 데이터가 부실할 때 스크립트가 하는 일

자동으로 처리되므로 **네가 재시도할 필요 없다.** 다만 결과에 담긴 사유는 사용자에게 그대로 전달하라.

| 상황 | 스크립트 동작 | 결과에 담기는 것 |
|---|---|---|
| 최신 연도 데이터 없음 | 최대 4년 후퇴 | 실제 사용 연도 |
| 상대국 미러 데이터 없음 | 최대 3년 후퇴 | `stale: true` |
| 상대국이 비보고국 | 순위에서 제외 | `score_basis: unscored` + 사유 |
| 관세청 인증키 없음 | `domestic`만 중단, 나머지는 정상 | `customs_key_missing` + 발급 안내 |
| 관세청 응답이 잘림 | 총계 행과 대조해 즉시 실패 | `customs_error` 무결성 검증 실패 |
| 여유 시장이 하한 미만 | 순위에서 제외(측정 불가와 구분) | `score_basis: below_floor` |
| 발굴 스캔 응답이 500행에서 잘림 | 못 받은 국가만 재조회, 1개국까지 줄여도 잘리면 상대국별 분리 조회 | (자동 복구) |
| 집계행 없이 내역행만 신고하는 나라 | 합산값을 쓰되 표시 | `tags: 집계주의` |
| 시장 CAGR 산출 불가 | 최대 3년 더 거슬러 탐색, 그래도 없으면 순위 제외 | `market_growth_note` |
| 공급국 목록이 잘려 한국이 안 보임 | 점유율을 0이 아니라 '모름'으로 처리 → 순위 제외 | 여유 축 만점 오인 방지 |
| 국가 하나 조회 실패 | 그 국가만 degrade, 나머지 리포트는 생성 | `competitor_note: 조회 실패...` |
| 500행 상한 초과 | World 행과 대조해 실제 누락 측정 | `partner_coverage_pct`, `competitor_warning` |
| 월별 보고 지연 | 데이터 있는 최신월부터 역산 | `monthly_coverage.range` |
| 월수 부족 | YoY·계절성 계산 안 함 | `yoy_note`, `seasonality` 에 사유 |
| 429 | 대기 후 재시도 + **남은 조회 간격을 자동 상향**(최대 15초) | (자동 복구, 뒤로 갈수록 느려짐) |
| 5xx | 지수 백오프 재시도 | (자동 복구) |
| 네트워크 끊김 | 즉시 중단 | "인터넷 연결을 확인하세요" |
| 존재하지 않는 HS | 즉시 중단 | 상위 코드 제안 |

**순위에서 제외된 국가는 "그 시장이 나쁘다"는 뜻이 아니다.** 측정이 안 됐다는 뜻이다.
사용자에게 이 구분을 반드시 말하라. 이런 국가는 한국 수출 실적만 별도로 보여준다.

`--no-competitors`를 쓰면 시장 규모를 모르게 되므로 **전 국가가 순위 제외**된다.
점수가 필요하면 이 옵션을 쓰지 마라.

## 매력도 스코어를 설명할 때

**점수 = 여유 시장 50% + 시장 CAGR 50%.**

**여유 시장 = 그 나라 총수입 × (1 − 한국 점유율).** 아직 한국 몫이 아닌 수입액이다.
"시장이 큰가"와 "들어갈 자리가 있는가"를 한 개의 달러 금액으로 합친 값이고, 실무 언어로는
**지금 테이블에 남아 있는 돈**이다. 사용자에게 점수를 설명할 때는 이 금액을 먼저 말하라 —
"베트남은 남은 파이가 $1.8억이고 그게 연 15%씩 크고 있습니다"가 "75.3점"보다 훨씬 낫다.

**두 축 모두 절대 기준이다.**

- 여유 시장: $1천만 이하 0점, $100억 이상 만점 (그 사이는 로그)
- 시장 성장률: 연 −10% 이하 0점, +20% 이상 만점

그래서 **어느 나라를 함께 조회하든 같은 나라는 같은 점수가 나오고, 다른 조회에서 나온
점수와도 비교할 수 있다.** 비교군을 바꿔 여러 번 돌릴 필요가 없다 — 예전 버전은 상대
점수여서 그렇게 안내했지만 지금은 아니다. 국가 하나만 조회해도 점수가 나온다.

상한을 두는 이유를 물으면: 상한이 없으면 규모가 순위를 지배해서 점수가 그냥 "수입액 큰
나라 순"이 된다(실측 Spearman +0.89). $75억 시장과 $130억 시장의 차이는 중소 수출기업이
어느 쪽을 먼저 갈지를 바꾸지 않는다.

성장 축은 **그 나라의 총수입 성장률**이다. 한국 수출 성장률이 아니다. 둘은 다른 질문에
답한다 — 리포트가 두 열을 나란히 보여주니 **격차를 읽어라.** 시장은 크는데 한국 수출이
줄면 점유율을 잃는 중이고, 시장이 죽는데 한국 수출만 늘면 중계무역 경유일 가능성이 있다.

명목 가중치(50/50)와 **실제로 순위를 움직인 비중은 다르다.** 여러 나라가 여유 시장 상한에
걸려 나란히 만점이면 그 축은 순위를 못 가른다. 리포트가 실측 비중을 같이 출력하니 그걸
근거로 설명하라.

**순위에서 빠진 국가는 두 종류이고 뜻이 정반대다. 절대 뭉뚱그리지 마라.**

| 표시 | 뜻 | 사용자에게 |
|---|---|---|
| `측정불가` | 시장 규모·한국 점유율·시장 성장률 중 하나라도 없음 | "데이터가 없어 비교를 못 했다" — 나쁜 시장이 아니다 |
| `규모 미달` | 여유 시장이 $1천만 미만 | "데이터는 있고, 실제로 작은 시장이다" |

`규모 미달` 기준이 사업 규모에 안 맞으면(1인 무역상, 고단가 소량 품목) `--min-market`을
낮춰 다시 돌려라. 사용자가 "이렇게 작은 시장도 우리한테는 크다"고 하면 이걸 제안하라.

"여유 시장"은 아직 안 뚫린 몫이라는 뜻이지 뚫기 쉽다는 뜻이 아니다. 1위 공급국이 60%
이상 쥔 과점 시장이면 여유 금액이 커도 그 자리는 이미 남이 앉아 있다 — 리포트의 ⚠️ 표시를
같이 전달하라. 반대로 한국 점유율이 이미 높은 시장은 여유 금액이 작아도 제품 적합성이
이미 입증된 시장이다.

## 반드시 지킬 데이터 한계

사용자가 물으면 얼버무리지 말고 이대로 답한다. 자세한 내용은 `references/data-notes.md`.

- **점유율은 "수입 중 점유율"이지 "시장 점유율"이 아니다.** 미러 데이터에는 현지 제조사가
  통째로 빠져 있다. "베트남 라면 한국 점유율 53%"는 수입되는 라면 중 53%라는 뜻이고,
  현지 Acecook·Masan이 가져가는 내수는 안 잡힌다. 사업적으로 완전히 다른 결론이므로
  **점유율을 말할 때마다 "수입 기준"임을 명시하라.** 식품·자동차·철강·화장품처럼 현지 생산이
  강한 조합에서 특히 위험하다. 같은 이유로 "현지 총수입"은 그 나라의 시장 규모가 아니다.
- **기업 단위 데이터는 없다.** 한국은 관세법상 신고정보가 비밀유지 대상이라 기업명 × 품목 × 금액이
  공개되지 않는다. 관세청도 무역협회도 제공하지 않는다. "어느 회사가 수출하는지"는 이 스킬로 답할 수 없다.
  바이어 실명이 필요하면 B/L을 공개하는 나라(미국·인도 등)의 유료 데이터(Panjiva/ImportYeti/Volza)가 필요하다.
- **HS 6단위까지만.** 10단위는 관세청 오픈API가 필요하다(인증키 발급 필요, 이 스킬 범위 밖).
- 한국 수출액은 FOB, 상대국 수입액은 CIF 기준이라 같은 거래도 금액이 다르게 잡힌다. 점유율은 미러 데이터
  안에서만 비교하고 두 소스를 섞어 계산하지 마라.
- 미러 데이터는 UN Comtrade 보고국만 나온다. 미보고국은 경쟁국 점유율이 비어 있다.
- 최신 데이터는 보고 지연으로 2~6개월 비어 있을 수 있다. 스크립트가 자동으로 뒤로 물러나 조회한다.
- 대만은 Comtrade에서 `Other Asia, nes`(코드 490)로 잡힌다. 리포트에는 "대만"으로 표시된다.

## 캐시와 레이트리밋

- 응답은 `~/.cache/trade-stats-lookup/`에 7일 캐시된다. 같은 조회를 다시 돌리면 즉시 끝난다.
- 무료 공개 티어라 스크립트가 요청 간격을 두고 호출한다. 429가 오면 서버가 지정한 대기 시간을
  따르고 **남은 조회의 간격을 자동으로 올린다**(최대 15초). 그래서 뒤로 갈수록 느려질 수 있는데
  정상이다. **직접 재시도하지 마라.**
- 그래도 429로 실패하면 `TRADE_STATS_MIN_INTERVAL=6`을 주고 다시 돌려라. 국가 수 × 연도 수가
  크면(예: 5개국 × 4년) 기본 간격으로 부족할 수 있다. 캐시 덕에 이미 성공한 콜은 재사용된다.
- 환경변수: `TRADE_STATS_MIN_INTERVAL`(기본 2.0초, 1초 미만 불가 — 늘리는 용도),
  `TRADE_STATS_CACHE_TTL`(기본 604800), `TRADE_STATS_CACHE_DIR`.
- 여러 명이 같은 IP를 쓰는 사내 환경이면 간격을 늘려 쓰기를 권한다.

## 실패 대응

| 증상 | 대응 |
|---|---|
| **종료코드 3 (섞인 4단위)** | 실패가 아니다. 출력된 6단위 구성비를 그대로 보여주고 어느 제품인지 물어라. `--hs4-ok`는 사용자가 "묶음 전체로 보겠다"고 했을 때만 붙인다. 상세: `references/data-notes.md` |
| `comtrade_error` + HS 자릿수 | 6단위로 잘라 재시도하고 사용자에게 알린다 |
| 국가 조회 실패 | `country-search`로 정확한 코드를 찾아 재시도 |
| 특정 국가만 결과 0 | 해당 국가가 그 HS를 신고하지 않은 것. 없다고 말한다 |
| 전 국가 결과 0 | HS코드가 잘못됐을 가능성. `hs-search`로 재확인 |
| 500행 상한 경고 | 하위 국가가 잘렸을 수 있음을 사용자에게 알린다 |

## 참조 파일

필요할 때만 읽어라.

- `references/hs-codes.md` — 한국어 품목명 → 영어 검색어 힌트, 주요 수출품 HS코드
- `references/country-codes.md` — 국가 코드·별칭 규칙, Comtrade 표기 함정
- `references/data-notes.md` — 데이터 출처·한계·다음 단계(Phase 0/2/3) 상세
- `references/customs-hsk.md` — 관세청 HSK 10단위 조회(`domestic`). 키가 필요할 때만 읽어라
- `references/tariff.md` — 관세율 조회 상세 규칙. 관세 질문을 받았을 때만 읽어라

## 완료 기준

- 보고가 **데이터 기준 시점 선언**으로 시작했다 — 어느 시점까지의 데이터인지, 왜 그게 최신인지.
- 이어서 요약 표가 나오고, 표 아래에 정량 근거가 붙어 있다. 수치 2개 이상인 근거는 표로 제시했다.
- 사용자가 "어느 나라부터"에 대한 답을 순위와 근거로 받았다.
- 매력도를 점수가 아니라 **여유 시장 금액과 성장률**로 먼저 설명했다.
- `측정불가`와 `규모 미달`을 구분해 전달했다.
- 경쟁 구도(1위 공급국·한국 순위)를 알았다.
- 데이터가 없는 부분은 없다고 명시했다. 추정으로 채우지 않았다.
- CSV는 사용자가 요청한 경우에만 생성해 경로를 안내했다.