지역 분석 문서 만들기 2차 시도 - 이번엔 잘할줄 알았다.

**바쁘시면 이것만 읽어도 돼요:**
- 🎯 **목표**: 지역분석조서(지역 통계 보고서)를 자동으로 생성하는 시스템 구축
- 📊 **사용한 도구**: Claude Code (AI 코딩 도구)
- 🔗 **기술 도전**: 5개의 공공데이터 API를 한 플랫폼에서 통합 (데이터 포맷, 지역코드 등이 모두 다름)
- ⚡ **해결 방법**: Claude에게 각 API별로 단계적으로 설명하고, 데이터를 한 가지 형식으로 정규화
- 🔄 **재사용성**: 지역과 조회기간만 바꾸면 언제든 새로운 보고서 즉시 생성 가능
- 📚 **배운 교훈**: "API 설명서만으로는 부족하다. 직접 확인하거나 물어봐야 한다"

---

## 🎯 이런 분들께 도움돼요

- 📊 **지역 분석, 통계 담당자** — 반복적으로 여러 데이터를 모아 보고서를 만드는 업무를 하는 분
- 🤖 **AI 도구를 처음 써보는 사람** — Claude Code가 어떻게 복잡한 업무를 자동화할 수 있는지 궁금한 분
- 💻 **코딩을 모르는 실무자** — 개발자 없이 AI의 도움으로 업무 자동화를 시도해본 경험을 알고 싶은 분

---

## 😫 문제 상황 (Before)

### 지역분석조서, 매번 수동으로 만들고 있었다

**지역분석조서**는 특정 지역의 인구, 주택, 교육, 의료, 지가 등 다양한 통계 정보를 한 문서에 정리한 보고서입니다. 

매번 이 보고서를 만들 때마다:

1. **부동산원 웹사이트** → 지가 정보 다운로드
2. **행정안전부 API** → 인구 통계 조회
3. **학교정보 서비스** → 학교 현황 수집
4. **의료기관 정보** → 병원·의원 현황 찾기
5. **사업체 통계** → 지역 내 사업체 수 확인
6. **엑셀에서 정리** → 표 작성, 차트 만들기
7. **Word 문서 작성** → 형식 맞춰서 수동 작성

가장 답답했던 건:
- 지역이 바뀌거나 조회 기간이 달라지면 **처음부터 다시** 해야 함
- 각 데이터 출처마다 **형식이 다름** (엑셀도 있고, 웹사이트도 있고, API도 있고...)
- 데이터를 정리하다 보면 **실수하기 쉬움**
- 같은 '지역'인데도 **지역코드가 제각각** (어떤 곳은 서울시, 어떤 곳은 11000으로 표기)

---

## 🛠️ 사용한 도구

- **Claude Code**: AI 코딩 어시스턴트 (Claude Opus 4.5 모델)
- **공공데이터 API 5개**:
  - 한국부동산원 Open API (지가 정보)
  - 행정안전부 주민등록 인구 API (인구 통계)
  - 학교정보 API (학교 현황)
  - HIRA 병의원 정보 API (의료기관 현황)
  - 공공데이터포털 지방자치단체 통계 API (지역 정보)

---

## 🔧 작업 과정

### 1단계: 어떤 데이터가 필요한지 정리하기

가장 먼저 한 일은 **"지역분석조서에 들어가야 할 데이터가 정확히 뭔지 정의하기"**였습니다.

지역분석조서 샘플을 Claude Code에 보여주고 물어봤어요:

```
지역분석조서.md 문서를 읽고 실행 계획을 세워줘.
```

Claude는 몇 초 만에:
- 필요한 섹션 (인구, 주택, 의료, 교육 등) 파악
- 각 섹션별 데이터 소스 제안
- 어떤 API를 써야 할지 정리

**느낀 점**: AI는 문서를 순식간에 분석하고, 빠진 부분까지 지적해줍니다.

---

### 2단계: 문제 발견 — "API 명세가 불명확해요"

실제 구현을 시작하려니 문제가 생겼어요.

**"데이터를 가져와야 하는데 API가 없는 건 없어??"** 라고 물었을 때, Claude는 솔직했습니다:

> 일부 데이터(주택수, 미분양 현황 등)에 대해 API 문서가 없습니다. 
> 어떻게 처리할까요? API를 찾아줄까요, 아니면 수동으로 입력할까요?

이때 저는 "주택수와 미분양 현황은 부동산원 API에 있으니 그걸 써"라고 답했고, Claude는 바로:

```
부동산원 통계표 코드에서 해당 항목을 확인하겠습니다.
```

라며 구체적인 코드를 찾아주려고 했어요. 하지만 명세서에는 코드가 명확히 없었어요.

**여기서 배운 교훈**: API 설명서만으로는 부족합니다. 직접 확인하거나, 모르면 **물어봐야 합니다.**

---

### 3단계: 가장 힘들었던 부분 — 5개 API 한 번에 연동하기

각각의 API를 하나씩 테스트하는 것은 괜찮았어요. 하지만 **5개를 모두 함께 사용하려니 문제가 터졌습니다.**

#### 문제 1: 데이터 포맷이 제각각

- **부동산원 API** → JSON 형식, 숫자형 지역코드
- **행정안전부 인구 API** → XML 형식, 문자형 지역코드  
- **학교정보 API** → 또 다른 JSON 구조
- **의료기관 정보** → 다시 다른 포맷

같은 "지역"인데도 **포맷이 5가지**였어요.

#### 문제 2: 지역코드가 제각각

- 어떤 API는 "서울시 강남구"라고 표기
- 어떤 API는 "11680" (지역코드)로 표기
- 또 어떤 API는 "강남구" 만으로 표기

**같은 지역을 5가지 방식으로 표현했습니다.**

---

### 4단계: Claude가 단계적으로 해결해줬어요

이때 Claude Code의 가장 좋은 점을 느껴요. 바로 **"복잡한 것을 단순하게 쪼개는 능력"**입니다.

Claude는 다음과 같이 진행했어요:

**Step 1: API 1개 연동 → 데이터 정규화**
```
한국부동산원 API에서 지가 정보를 받아와서, 
"지역명(지역코드)" 형식으로 통일하기
```

**Step 2: API 2개 추가 → 지역코드 통일**
```
행정안전부 API는 다른 지역코드를 사용하니까,
부동산원 코드로 변환하는 매핑 테이블 만들기
```

**Step 3: 나머지 API 3개 순차적으로 추가**
```
각 API의 응답을 같은 형식으로 변환하는 함수들 작성
```

이런 식으로 **한 번에 하나씩 해결**했어요. 만약 처음부터 "모든 API를 동시에 연동해"라고 했다면 엄청 복잡했을 텐데, **작은 단위로 나눠서** 각각 확인하니까 오류가 적고 빠르게 진행됐습니다.

**느낀 점**: AI와 협업할 때는 "큰 요청을 작은 단위로 쪼개달라"고 하는 게 핵심입니다.

---

### 5단계: Word 문서 자동 생성

모든 데이터를 수집하고 정규화했으니, 이제 **Word 문서를 자동으로 만드는 부분**이 남았어요.

```
이제 수집된 데이터를 Python으로 Word 문서에 넣어줘.
표도 자동으로 만들고, 차트도 넣어줘.
```

Claude는:
- Word 문서 생성 라이브러리 선택
- 표 형식 설정
- 차트 이미지로 변환해서 삽입

이 모든 걸 몇 시간 안에 구현해줬습니다.

---

## ✅ 결과 (After)

### Before vs After

| 항목 | Before | After |
|------|--------|-------|
| **소요 시간** | 5-6시간 (수동 작업) | 1분 미만 (자동 생성) |
| **오류 가능성** | 높음 (수동 정리, 데이터 누락) | 거의 없음 (자동화) |
| **지역 변경** | 처음부터 다시 시작 | 지역명 입력만 변경 |
| **조회 기간 변경** | 모든 데이터 재수집 | 기간만 변경 |
| **일관성** | 매번 다름 (사람이 하니까) | 항상 동일한 형식 |

### 최종 결과물

이제 다음과 같이 실행하면:

```
지역: "청주시 서원구"
조회 기간: 2022년 1월 ~ 2025년 2월
```

**2초 안에** Word 문서가 생성되고, 여기에는:
- ✅ 인구 변동 그래프
- ✅ 주택 공급률 표
- ✅ 지역 내 학교 목록
- ✅ 의료기관 현황
- ✅ 지가 변동 차트

모두 **자동으로** 포함됩니다.

---

## 💬 이 과정에서 배운 AI 활용 팁

### ✨ 효과적이었던 것

1. **복잡한 것을 작은 단위로 쪼개기**
   - "5개 API를 다 해줘" ❌
   - "API 1개 먼저 테스트하고, 그 다음 2개..." ✅

2. **API 명세가 불명확할 때는 "직접 물어보기"**
   - 무작정 구현하지 말고, 모르는 부분을 Claude에게 물으면 해결책을 제시합니다.

3. **단계별 결과 확인하기**
   - 각 단계마다 "이게 맞나?"라고 확인 → 오류 조기 발견

4. **에러 메시지를 Claude에 복사-붙여넣기**
   - 뭔가 안 되면 에러 메시지를 Claude에 보내면, 원인과 해결책을 즉시 제시합니다.

### ⚠️ 이렇게 하면 안 돼요

1. **모든 걸 한 번에 요청하기**
   - "5개 API를 통합해서 Word 문서 만들고 배포까지 해줘" → 실패율 높음

2. **API 명세를 확인하지 않고 구현 요청하기**
   - 명세 없이 구현하면 시간만 낭비

3. **오류가 나도 "뭔가 안 돼"라고만 말하기**
   - 구체적인 오류 메시지를 보여주면 Claude가 훨씬 빨리 해결합니다.

4. **완성된 코드를 무조건 믿기**
   - 작은 데이터로 먼저 테스트해보고, 실제 데이터로 확인하기

---

## 🌍 다른 업무에 적용한다면?

이런 방식은 **지역분석조서뿐만 아니라** 다양한 곳에 적용할 수 있습니다:

- 📊 **정기 보고서 자동화** — 매월/매분기 같은 형식의 보고서가 필요한 경우
- 📈 **통계 대시보드** — 여러 소스의 데이터를 한 곳에서 시각화
- 📋 **합동 신청서** — 여러 기관의 데이터를 모아서 하나의 문서로 작성
- 🏢 **정부 관련 서류** — 공공데이터를 활용하는 모든 업무

---

## 🚀 앞으로의 계획

현재는 기본 구조가 완성된 상태입니다. 앞으로 가져온 데이터 집계해서 표와 그래프를 넣어야해요.

## 📋 재사용 가능한 프롬프트

### 프롬프트 1: 새로운 API 추가할 때

> API 명세는 [API 명세 URL 또는 파일명]입니다.
> 이 API의 응답을 다음 형식으로 정규화해줘:
> - 지역명: "시도 시군구"
> - 데이터: [원하는 필드명들]
> - 예시 응답을 보여주고 테스트해줘

**수정할 부분**: [API 명세 URL], [원하는 필드명들]을 본인 상황에 맞게 변경하세요.

### 프롬프트 2: 5개 이상 API를 통합할 때

> 다음 API들을 통합해야 합니다:
> 1. API A (지역코드: 11680)
> 2. API B (지역명: 강남구)
> 3. API C (코드 형식: 다름)
> 
> 먼저 API 1개만 테스트해서 데이터를 받아보자.
> 그 다음에 지역코드 매핑 테이블을 만들어서 
> 나머지 API들을 하나씩 추가하는 방식으로 진행해줘.

**수정할 부분**: API 이름과 지역코드 형식을 본인 API로 변경하세요.

### 프롬프트 3: 데이터 정규화할 때

> 이 API 응답들을 보자:
> - API A 응답: [샘플 데이터 1]
> - API B 응답: [샘플 데이터 2]
> 
> 이걸 다음 공통 형식으로 변환해주는 함수를 만들어줘:
> ```
> {
>   "region": "지역명",
>   "data": {...}
> }
> ```


## 마지막으로
아직 완성을 못했어요.... 열심히 마무리 해볼께요.