내 조건에 맞는 아파트를 찾습니다

같은 거래의 면적·가격과 주변 거리 조건으로 단지를 검색합니다.

이어갈 프로젝트 · apartment-explorer

6장의 두 API 연결과 응답 처리 Test가 있습니다.

이번 장의 준비와 서비스

필요한 도구 · TypeScript · 기존 Test

이미 준비한 계정과 기능은 그대로 이어갑니다.

data-go-kr 준비 안내 →kakao 준비 안내 →

웹 UI를 만들거나 현재 매물·투자 추천·종합 순위·미래 가격 예측을 추가하지 않습니다.

순서대로 입력하는 커맨드

현재 단계와 입력 위치를 확인한 뒤 하나씩 복사하세요.

01시작 전 확인

Claude Code·Codex에 입력튜터 요청

7장을 처음 시작하거나 현재 장의 시작 조건을 확인해 달라고 요청할 때

먼저 확인 · 6장의 두 API 연결과 응답 처리 Test가 있습니다. 이미 확인된 장·프로젝트는 다시 묻지 않고 현재 기록과 실제 상태를 대조합니다.

7장 시작해.

02우리가 정한 대로 만들어달라고 합니다

Claude Code·Codex에 입력실습

검색 단위와 거래·가격·면적·거리·주소 기준을 정한 뒤 기능을 만들 때

먼저 확인 · 6장의 두 실제 API 연결과 저장 응답 Test를 확인합니다. 단지 단위·최근 1년·해제 제외·같은 거래의 면적과 가격·직선거리라는 본문 범위를 읽었는지 봅니다.

이 프로젝트에 연결해둔 국토교통부 아파트 매매 실거래가 API와
Kakao Local API를 이용해서 내 조건에 맞는 아파트를 찾는 기능을 만들어줘.

사용자가 지역, 전용면적의 최소값과 최대값, 실거래 가격의 최소값과
최대값, 지하철역과 초등학교의 거리 기준을 입력할 수 있게 해줘.

검색 결과의 단위는 아파트 단지야. 현재 매물이나 동·호수를 찾는 기능은
아니야.

실행일 기준 최근 1년의 정상 거래만 사용하고 거래 해제 건은 제외해줘.
면적과 실거래 가격은 사용자가 입력한 최소값 이상, 최대값 이하를 모두
포함해줘.

지정한 면적 범위에서 정상 거래가 없는 아파트는 제외하고, 지정한 실거래
가격 범위의 정상 거래가 최근 1년 동안 한 건 이상 있는 아파트만 결과에
포함해줘.

두 조건은 같은 거래를 기준으로 봐줘. 지정한 면적 범위의 정상 거래만
모은 다음 그중에서 가격 범위에 드는 거래를 찾고, 아파트별로 보여주는
건수와 가격 범위, 가장 최근 거래도 그 면적 범위의 거래로 계산해줘.

아파트별로 최근 1년 정상 거래 건수, 정상 거래 전체 가격 범위, 가장
최근 거래가격과 거래일, 지정한 실거래 가격 범위 안의 거래 건수를
보여줘.

지역은 사용자가 평소 쓰는 방식으로 입력할 수 있게 해줘.

`서울 강남구 대치동` 같은 법정동 이름뿐 아니라 `서울 송파구 잠실2동`
같은 행정동 이름이나 `서울 송파구 올림픽로 300` 같은 도로명주소를
입력할 수도 있어.

입력한 주소를 실제 주소 정보로 확인해서 국토교통부 실거래가 조회에
필요한 지역과 법정동코드로 안전하게 연결해줘.

동 이름에서 숫자를 지우거나 비슷한 지역을 추측해서 연결하지 마. 하나의
지역으로 확실하게 정할 수 없다면 임의로 선택하지 말고 사용자가 더
정확한 주소를 입력할 수 있게 알려줘.

지하철역과 초등학교는 사용자가 입력한 거리 기준을 모두 만족하는
아파트만 찾아줘. 거리는 직선거리라는 것을 결과에서 알 수 있게 해줘.

현재 매물을 찾거나 아파트 가격을 하나로 단정하지 마. 종합점수나 순위를
만들지 말고 매수·투자 추천, 저평가·고평가 판단, 미래 가격이나 수익률
예측도 하지 마.

정상적으로 검색했지만 조건에 맞는 아파트가 없는 경우와 지역 입력을
확인할 수 없는 경우, 입력 범위가 잘못된 경우, 외부 데이터를 정상적으로
가져오지 못한 경우를 서로 구분해줘.

위에서 정한 검색 규칙이 제대로 동작하는지 확인할 Test도 만들어줘.

지금은 브라우저에서 쓸 웹 화면은 만들지 마. 기능과 Test까지만 만들어줘.

기존 프로젝트를 최대한 재사용하고, 구현이 끝나면 새로 만든 Test와 이번
변경에 관련된 기존 Test를 실행해 모두 통과한 뒤 결과를 알려줘.

03만든 기능에 이름을 붙입니다

Claude Code·Codex에 입력실습

완성한 검색 기능을 아파트 찾기라는 이름으로 재사용하게 할 때

먼저 확인 · 기존 검색 구현과 관련 Test 통과를 확인합니다.

지금 만든 아파트 검색 기능을 앞으로 '아파트 찾기'라고 부를게.
이후 내가 아파트 찾기를 요청하면 새로 만들지 말고 지금 만든 기존 검색
기능을 사용하도록 이 프로젝트의 규칙에 반영해줘.

04실제 조건으로 찾아봅니다

Claude Code·Codex에 입력실습

아파트 찾기의 실제 대치동 조건 검색을 확인할 때

먼저 확인 · 기능·Test와 아파트 찾기 이름 연결이 확인됐는지 봅니다. 코드 입력창에서 기존 기능을 사용하는 요청이며 서비스 웹 화면은 아직 없습니다.

아파트 찾기로 검색해줘. 지역은 서울 강남구 대치동, 전용면적은 최소
80㎡, 최대 90㎡야. 실거래 가격은 최소 20억원, 최대 30억원으로 찾아줘.
지하철역은 800m 이내, 초등학교는 1km 이내로 찾아줘. 조건을 만족하는
아파트가 여러 곳이면 모두 보여줘. 순위를 매기거나 추천하지 말고 각
아파트의 실제 거래와 생활조건 근거를 함께 보여줘.

5. 실제 조건으로 찾아봅니다 선택·문제 발생 시

Claude Code·Codex에 입력선택·문제 발생 시

실제 검색 결과 중 한 단지의 거래 근거를 더 보고 싶을 때

먼저 확인 · 직전 실제 검색에 결과 단지가 있는지 확인합니다. 정상 0건이면 존재하지 않는 단지를 고르지 않습니다.

아파트 찾기 결과에 나온 아파트 중 하나를 골라서
그 아파트의 최근 1년 80~90㎡ 정상 거래 내역을 보여줘.

06실제 조건으로 찾아봅니다

Claude Code·Codex에 입력실습

실제 조건 검색과 근거 확인 후 작업을 마무리할 때

먼저 확인 · 새 검색과 기존 응답 처리 Test, 실제 검색 결과를 구분하고 apartment-explorer 저장소를 확인합니다.

이번 작업을 마무리하고
GitHub 저장소에도 보내줘.

07이 장을 마쳤는지 확인합니다

Claude Code·Codex에 입력튜터 요청

7장의 실습 결과를 장별 완료 조건과 대조할 때

먼저 확인 · 앞 단계 실행 결과와 사람이 직접 확인할 항목을 확인합니다. 요청문을 보여주거나 실행했다고 완료로 세지 않습니다.

장 완료 확인해줘.

이 장에서 막혔을 때

디버깅 → 내 정상 기록으로 복구 → 장별 Source로 재시작

Git 명령을 외우거나 직접 입력할 필요는 없습니다. 아래 요청문을 그대로 붙여넣으면 Claude Code가 확인하고 처리합니다.

1. 디버깅 — 먼저 무엇이 어긋났는지 그대로 말하고 고쳐봅니다. 대부분 여기서 해결됩니다.

지금 작업이 책과 다르게 진행됐어.
현재 상태와 화면에 나온 문제를 확인하고 원인을 찾아서 고쳐줘.

이 장에서 특히 자주 막히는 자리는 지역을 입력했는데 조회 지역으로 연결되지 않는 경우입니다.

내가 입력한 지역이 실거래가 조회 지역으로 연결되지 않았어.
입력한 주소를 어떻게 해석했는지 단계별로 보여주고
어디에서 확인에 실패했는지 알려줘.

2. 내 정상 기록으로 복구 — 해결되지 않으면 실습하면서 내 프로젝트에 남겨둔 정상 기록으로 돌아갑니다. 지금까지 한 작업은 먼저 따로 보존합니다.

현재 작업은 잃지 않도록 먼저 별도로 보존해줘.
이 프로젝트에서 마지막으로 정상 동작했던 상태를 찾아 안전하게 복구해줘.

3. 장별 Source로 재시작 — 그래도 이어갈 수 없을 때 사용합니다. 7장의 남은 실습은 건너뛰게 되므로 마지막 수단입니다.

내 현재 작업을 먼저 안전하게 보존해줘.
아래 7장 완성 Source에서 다시 시작해줘.
https://github.com/buildyourownai-lab/develop-like-a-pro-with-ai/tree/main/chapters/ch07/source/apartment-explorer
내 두 개의 키를 입력할 자리를 알려주고
준비가 끝나면 7장을 마친 상태인지 확인해줘.

방향부터 확인하고, 더 필요할 때 다음 힌트를 펼치세요.

가격 조건과 표시 범위가 다름

1단계 — 방향

단지 선택과 결과 요약은 범위가 다를 수 있습니다.

2단계 — 범위

면적 범위 안 전체 거래와 가격 조건에 맞는 건수를 나눕니다.

3단계 — 위치·원인 후보

최신 가격·최저최고값이 어느 집합에서 계산됐는지 확인합니다.

정답을 요청했을 때

같은 면적범위 거래를 기준으로 요약하고 가격 조건 건수만 따로 셉니다. 예시 숫자를 억지로 맞추지 않습니다.

검증 주의

이 설명만으로 원인이 확인됐거나 수정됐다고 말하지 않습니다. 현재 프로젝트의 근거를 먼저 대조합니다.

검색 0건

1단계 — 방향

0건과 조회 실패부터 구분합니다.

2단계 — 범위

주소가 확정됐는지, API 응답이 성공했는지 봅니다.

3단계 — 위치·원인 후보

면적·가격·역·학교 조건에서 어떤 단계가 후보를 줄였는지 확인합니다.

정답을 요청했을 때

정상 조회 후 조건에 맞는 단지가 없으면 0건이 맞습니다. 지역을 추측하거나 조건을 몰래 완화하지 않습니다.

검증 주의

이 설명만으로 원인이 확인됐거나 수정됐다고 말하지 않습니다. 현재 프로젝트의 근거를 먼저 대조합니다.

디버깅 → 정상 기록 복구 → 장별 소스로 재시작 →

이번 장의 완료 체크리스트

검색 기준단지·최근 1년·정상 거래·포함 경계 정의
주소 확인행정동·법정동·도로명주소를 추측 없이 연결
같은 거래면적 범위 거래 중 가격 조건을 판단
결합·거리단지 식별과 직선거리 조건을 적용
집계·예외전체 면적범위 집계와 가격건수·0건·오류를 구분
실제 검색실제 자료의 결과와 검증 범위를 기록

장 완료 확인해줘.

실제 프로젝트에서 튜터와 확인합니다. 사이트를 열어본 기록은 학습 완료가 아닙니다.

장별 소스와 저자 검증 기록

저자는 6장 도착점에서 시작해 7장 요청문만으로 아파트 찾기와 Test까지 갔습니다. 이 장에서 새로 생긴 Test 13개를 포함해 프로젝트 전체 Test 24개가 통과했고, 실제 데이터로 서울 강남구 대치동을 검색해 조건에 맞는 아파트 단지를 확인했습니다. 근거는 verification/chapter-07/에 있습니다.

7장 완성 소스 ↗저자 검증 상세 기록 ↗

장별 소스는 해당 장까지의 기준 상태입니다. 정상 실습은 내 프로젝트를 이어가고, 완성 소스는 비교·복구할 때 사용합니다.

자료 판본 1c784213

이 장의 개발 용어

API: 프로그램이 다른 서비스와 정해진 방식으로 요청·응답을 주고받는 연결 방법.
Test: 정한 완료 조건을 반복 확인하는 검사. 검사하지 않은 전체 정확성을 보증하지 않습니다.

튜터 사용 안내 실습 자료 업데이트

이 프로젝트에 연결해둔 국토교통부 아파트 매매 실거래가 API와 Kakao Local API를 이용해서 내 조건에 맞는 아파트를 찾는 기능을 만들어줘. 사용자가 지역, 전용면적의 최소값과 최대값, 실거래 가격의 최소값과 최대값, 지하철역과 초등학교의 거리 기준을 입력할 수 있게 해줘. 검색 결과의 단위는 아파트 단지야. 현재 매물이나 동·호수를 찾는 기능은 아니야. 실행일 기준 최근 1년의 정상 거래만 사용하고 거래 해제 건은 제외해줘. 면적과 실거래 가격은 사용자가 입력한 최소값 이상, 최대값 이하를 모두 포함해줘. 지정한 면적 범위에서 정상 거래가 없는 아파트는 제외하고, 지정한 실거래 가격 범위의 정상 거래가 최근 1년 동안 한 건 이상 있는 아파트만 결과에 포함해줘. 두 조건은 같은 거래를 기준으로 봐줘. 지정한 면적 범위의 정상 거래만 모은 다음 그중에서 가격 범위에 드는 거래를 찾고, 아파트별로 보여주는 건수와 가격 범위, 가장 최근 거래도 그 면적 범위의 거래로 계산해줘. 아파트별로 최근 1년 정상 거래 건수, 정상 거래 전체 가격 범위, 가장 최근 거래가격과 거래일, 지정한 실거래 가격 범위 안의 거래 건수를 보여줘. 지역은 사용자가 평소 쓰는 방식으로 입력할 수 있게 해줘. `서울 강남구 대치동` 같은 법정동 이름뿐 아니라 `서울 송파구 잠실2동` 같은 행정동 이름이나 `서울 송파구 올림픽로 300` 같은 도로명주소를 입력할 수도 있어. 입력한 주소를 실제 주소 정보로 확인해서 국토교통부 실거래가 조회에 필요한 지역과 법정동코드로 안전하게 연결해줘. 동 이름에서 숫자를 지우거나 비슷한 지역을 추측해서 연결하지 마. 하나의 지역으로 확실하게 정할 수 없다면 임의로 선택하지 말고 사용자가 더 정확한 주소를 입력할 수 있게 알려줘. 지하철역과 초등학교는 사용자가 입력한 거리 기준을 모두 만족하는 아파트만 찾아줘. 거리는 직선거리라는 것을 결과에서 알 수 있게 해줘. 현재 매물을 찾거나 아파트 가격을 하나로 단정하지 마. 종합점수나 순위를 만들지 말고 매수·투자 추천, 저평가·고평가 판단, 미래 가격이나 수익률 예측도 하지 마. 정상적으로 검색했지만 조건에 맞는 아파트가 없는 경우와 지역 입력을 확인할 수 없는 경우, 입력 범위가 잘못된 경우, 외부 데이터를 정상적으로 가져오지 못한 경우를 서로 구분해줘. 위에서 정한 검색 규칙이 제대로 동작하는지 확인할 Test도 만들어줘. 지금은 브라우저에서 쓸 웹 화면은 만들지 마. 기능과 Test까지만 만들어줘. 기존 프로젝트를 최대한 재사용하고, 구현이 끝나면 새로 만든 Test와 이번 변경에 관련된 기존 Test를 실행해 모두 통과한 뒤 결과를 알려줘.

지금 만든 아파트 검색 기능을 앞으로 '아파트 찾기'라고 부를게. 이후 내가 아파트 찾기를 요청하면 새로 만들지 말고 지금 만든 기존 검색 기능을 사용하도록 이 프로젝트의 규칙에 반영해줘.

아파트 찾기로 검색해줘. 지역은 서울 강남구 대치동, 전용면적은 최소 80㎡, 최대 90㎡야. 실거래 가격은 최소 20억원, 최대 30억원으로 찾아줘. 지하철역은 800m 이내, 초등학교는 1km 이내로 찾아줘. 조건을 만족하는 아파트가 여러 곳이면 모두 보여줘. 순위를 매기거나 추천하지 말고 각 아파트의 실제 거래와 생활조건 근거를 함께 보여줘.

내가 입력한 지역이 실거래가 조회 지역으로 연결되지 않았어. 입력한 주소를 어떻게 해석했는지 단계별로 보여주고 어디에서 확인에 실패했는지 알려줘.

내 현재 작업을 먼저 안전하게 보존해줘. 아래 7장 완성 Source에서 다시 시작해줘. https://github.com/buildyourownai-lab/develop-like-a-pro-with-ai/tree/main/chapters/ch07/source/apartment-explorer 내 두 개의 키를 입력할 자리를 알려주고 준비가 끝나면 7장을 마친 상태인지 확인해줘.