누구나 사용할 수 있는 아파트 찾기 서비스를 만듭니다

검색 기능을 웹 화면에 연결하고 실제 인터넷 주소에서 확인합니다.

이어갈 프로젝트 · apartment-explorer

7장의 검색 기능과 Test가 있으며 웹 화면은 아직 없습니다.

이번 장의 준비와 서비스

필요한 도구 · Next.js · 브라우저

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

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

검색 규칙을 디자인에 맞춰 바꾸거나 Secret을 브라우저에 전달하지 않습니다.

순서대로 입력하는 커맨드

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

01시작 전 확인

Claude Code·Codex에 입력튜터 요청

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

먼저 확인 · 7장의 검색 기능과 Test가 있으며 웹 화면은 아직 없습니다. 이미 확인된 장·프로젝트는 다시 묻지 않고 현재 기록과 실제 상태를 대조합니다.

8장 시작해.

02아파트 찾기 화면을 만듭니다

Claude Code·Codex에 입력실습

7장의 검색 기능에 처음 웹 화면을 붙일 때

먼저 확인 · apartment-explorer의 기존 아파트 찾기 기능과 Test를 확인합니다. 검색 규칙은 유지합니다.

지금 만든 아파트 찾기 기능을 다른 사람도 브라우저에서 사용할 수 있게
웹 화면을 만들어줘.

기존 검색 기능을 새로 만들지 말고 지금 프로젝트에 있는 기능을 그대로
사용해줘.

사용자가 지역, 최소 전용면적, 최대 전용면적, 최소 실거래 가격, 최대
실거래 가격, 지하철역 거리, 초등학교 거리를 입력하고 `아파트 찾기`
버튼을 누를 수 있게 해줘.

지역은 `서울 강남구 대치동` 같은 법정동 이름뿐 아니라 행정동 이름이나
도로명주소로도 입력할 수 있다는 것을 화면에서 알려줘.

실거래 가격은 최근 1년 동안 선택한 면적에서 실제 거래된 가격을
검색하기 위한 범위라는 것을 화면에서 알 수 있게 해줘. 현재 매물 가격을
의미하지 않는다는 것도 알려줘.

결과에서는 아파트명, 최근 1년 정상 거래 건수, 정상 거래 전체 가격
범위, 지정한 실거래 가격 범위 안의 거래 건수, 가장 최근 거래가격과
거래일, 가장 가까운 지하철역과 거리, 가장 가까운 초등학교와 거리를
보여줘.

특정 아파트를 선택하면 검색의 근거가 된 실제 거래 내역도 확인할 수
있게 해줘.

정상적으로 검색했지만 조건에 맞는 아파트가 0개인 경우, 지역을 확인할
수 없는 경우, 입력 범위가 잘못된 경우, 국토교통부 데이터를 가져오지
못한 경우, Kakao 데이터를 가져오지 못한 경우, 예상하지 못한 서버
오류를 서로 구분해서 보여줘.

국토교통부와 Kakao에 보내는 요청이 응답 없이 멈추는 경우도 처리해줘.
정해진 시간과 횟수 안에서만 다시 시도해줘.
그 시간이 지나도 응답이 없으면 검색 조건 문제가 아니라 어느 쪽 데이터를
가져오지 못한 것인지 구분해서 보여줘. 서버 기록에는 어느 API에 보낸
요청이 무엇 때문에 실패했는지 비밀값 없이 남겨줘.

사용자에게 개발자용 오류 메시지나 내부 정보를 그대로 보여주지 말고
무엇이 문제인지 이해할 수 있게 알려줘.

제작 도구의 기본 화면을 그대로 두지 마. 입력하는 곳과 결과를 흰 카드로
나누고 카드 사이에 여백을 줘. 누르는 곳에는 강조색을 하나만 정해서 쓰고,
같은 정보를 한 화면에 여러 번 반복하지 마.

앞에서 정한 검색 규칙은 바꾸지 말고 기존 Test도 계속 통과하게 해줘.

웹 화면에 필요한 Test도 추가하고, 관련 Test를 모두 통과한 뒤
완료했다고 알려줘.

03아파트 찾기 화면을 만듭니다

Claude Code·Codex에 입력실습

웹 화면 구현 후 로컬 실행 주소를 받을 때

먼저 확인 · 화면 구현과 관련 Test 결과를 확인합니다.

지금 만든 웹 화면을 내 컴퓨터에서 실행해줘.
브라우저에서 열 주소도 알려줘.

04API Key는 브라우저로 보내지 않습니다

Claude Code·Codex에 입력실습

로컬 화면을 직접 사용한 뒤 서버와 브라우저의 비밀값 경계를 검사할 때

먼저 확인 · 독자가 로컬 주소에서 검색과 결과 화면을 직접 확인했는지 봅니다.

국토교통부 서비스키와 Kakao REST API 키가 브라우저로 전달되지 않고
서버에서만 사용되는지 확인해줘. 실제 키 값은 출력하지 마.

웹 화면에 필요한 Test와 기존 Test를 실행한 뒤 문제가 없는지 알려줘.

05이제 인터넷에 공개합니다

Claude Code·Codex에 입력실습

로컬 검사를 마친 웹 프로젝트를 Vercel 연결 전에 GitHub로 보낼 때

먼저 확인 · apartment-explorer의 로컬 검색·Secret·관련 Test 결과와 연결한 비공개 저장소를 확인합니다.

`apartment-explorer`를 인터넷에 공개할 준비를 해줘.

관련 Test와 빌드를 확인하고, GitHub에 올리면 안 되는 비밀값이나 파일이
없는지도 확인해줘.

문제가 없다면 현재 상태를 Git으로 기록해 GitHub에 올려줘. 로그인이나
승인처럼 내가 직접 해야 하는 단계가 나오면 알려줘.

06Vercel에도 Secret을 등록합니다

Claude Code·Codex에 입력실습

Vercel에 가져온 프로젝트의 환경변수 이름을 확인할 때

먼저 확인 · 독자가 Vercel에 로그인하고 필요한 apartment-explorer 저장소만 접근 허용한 뒤 Import했는지 확인합니다. 로컬 Secret은 자동 전송되지 않습니다.

Vercel에 등록할 환경변수 이름을 알려줘.
이 프로젝트가 사용하는 이름만 알려주고 실제 키 값은 출력하지 마.

07GitHub에 올리면 새 버전이 자동으로 배포됩니다

Claude Code·Codex에 입력실습

첫 공개 검색을 확인한 뒤 작은 안내 문구 변경으로 재배포를 연습할 때

먼저 확인 · 독자가 환경변수 입력 후 Deploy하여 Ready와 공개 주소를 확인했는지 봅니다. Settings→Functions→Function Region에서 Seoul을 선택하고 실제 주소의 검색·0건·오류를 확인합니다.

아파트 찾기 화면에서 실거래 가격 범위가 현재 매물 가격이 아니라고
알려주는 안내 문구를 조금 더 이해하기 쉽게 수정해줘.
검색 규칙과 API 동작은 바꾸지 마.

수정한 뒤 관련 Test를 실행하고 모두 통과하면 Git에 기록해서 GitHub에
올려줘.

08자동 배포에서 CI/CD를 만납니다

Claude Code·Codex에 입력실습

안내 문구 변경의 새 배포를 확인한 뒤 작업을 정리할 때

먼저 확인 · 새 배포에서 수정 문구와 실제 검색이 확인됐는지 봅니다. 추가 변경과 원격 기록 상태를 확인합니다.

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

9. 기본값 바꾸기 · 선택 선택·문제 발생 시

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

독자가 기본 동네 또는 종목을 바꾸고 싶을 때만

먼저 확인 · 기본 실습을 마친 뒤 독자가 선택한 변경인지 확인. 이 변경 없이도 다음 장으로 진행할 수 있음.

화면을 열면 지역 칸에 내가 사는 동네가 미리 들어가 있게 해줘. 서울 마포구
성산동이야. 나머지 조건의 초기값은 바꾸지 마.

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

Claude Code·Codex에 입력튜터 요청

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

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

장 완료 확인해줘.

이 장에서 막혔을 때

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

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

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

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

이 장에서 특히 자주 막히는 자리는 내 컴퓨터에서는 검색되는데 공개된 주소에서는 실패하는 경우입니다. 두 곳이 사용하는 키 이름이 다를 때 이렇게 됩니다.

내 컴퓨터에서는 검색되는데 공개된 주소에서는 실패해.
이 프로젝트가 사용하는 환경변수 이름을 알려주고
Vercel에 등록한 이름과 같은지 확인하는 방법을 알려줘.
실제 키 값은 출력하지 마.

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

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

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

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

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

로컬은 되는데 배포 후 실패

1단계 — 방향

같은 코드라도 실행 환경의 설정은 별개입니다.

2단계 — 범위

Vercel 프로젝트·적용 환경·현재 배포를 확인합니다.

3단계 — 위치·원인 후보

코드가 읽는 변수 이름과 Vercel Name이 같은지 봅니다.

정답을 요청했을 때

실제 값은 공식 화면에 직접 넣고 새 배포 후 각 API가 필요한 검색을 다시 확인합니다.

검증 주의

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

화면만 열리고 검색 안 됨

1단계 — 방향

페이지 표시와 기능 성공은 별개입니다.

2단계 — 범위

검색 요청이 서버까지 가는지 먼저 확인합니다.

3단계 — 위치·원인 후보

브라우저 오류·서버 오류·외부 응답 오류를 구분합니다.

정답을 요청했을 때

실패 구간을 고친 뒤 입력부터 결과까지 다시 실행합니다. Ready 표시만으로 장 완료라 하지 않습니다.

검증 주의

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

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

이번 장의 완료 체크리스트

화면 연결입력과 검색 결과를 기존 기능에 연결
상태 구분로딩·0건·입력 오류·외부 오류 구분
서버 경계Secret과 외부 API 호출이 서버에 남음
배포 설정대상 저장소와 코드 변수명을 Vercel에 대응
운영 검증실제 주소에서 전체 검색 흐름 확인
변경 재배포작은 변경을 검사하고 새 배포를 다시 확인

장 완료 확인해줘.

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

장별 소스와 저자 검증 기록

저자는 7장 도착점에서 시작해 8장 요청문만으로 아파트 찾기 화면까지 갔습니다. 이 장에서 새로 생긴 Test 19개를 포함해 프로젝트 전체 Test 43개가 통과했고, 브라우저가 받아가는 파일에 두 키의 이름과 값이 없는 것을 확인했습니다. 근거는 verification/chapter-08/에 있습니다.

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

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

자료 판본 1c784213

이 장의 개발 용어

API: 프로그램이 다른 서비스와 정해진 방식으로 요청·응답을 주고받는 연결 방법.
환경변수: 코드와 별도로 실행 환경에서 이름으로 읽는 설정. 이름과 실제 값은 다릅니다.
Test: 정한 완료 조건을 반복 확인하는 검사. 검사하지 않은 전체 정확성을 보증하지 않습니다.

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

지금 만든 아파트 찾기 기능을 다른 사람도 브라우저에서 사용할 수 있게 웹 화면을 만들어줘. 기존 검색 기능을 새로 만들지 말고 지금 프로젝트에 있는 기능을 그대로 사용해줘. 사용자가 지역, 최소 전용면적, 최대 전용면적, 최소 실거래 가격, 최대 실거래 가격, 지하철역 거리, 초등학교 거리를 입력하고 `아파트 찾기` 버튼을 누를 수 있게 해줘. 지역은 `서울 강남구 대치동` 같은 법정동 이름뿐 아니라 행정동 이름이나 도로명주소로도 입력할 수 있다는 것을 화면에서 알려줘. 실거래 가격은 최근 1년 동안 선택한 면적에서 실제 거래된 가격을 검색하기 위한 범위라는 것을 화면에서 알 수 있게 해줘. 현재 매물 가격을 의미하지 않는다는 것도 알려줘. 결과에서는 아파트명, 최근 1년 정상 거래 건수, 정상 거래 전체 가격 범위, 지정한 실거래 가격 범위 안의 거래 건수, 가장 최근 거래가격과 거래일, 가장 가까운 지하철역과 거리, 가장 가까운 초등학교와 거리를 보여줘. 특정 아파트를 선택하면 검색의 근거가 된 실제 거래 내역도 확인할 수 있게 해줘. 정상적으로 검색했지만 조건에 맞는 아파트가 0개인 경우, 지역을 확인할 수 없는 경우, 입력 범위가 잘못된 경우, 국토교통부 데이터를 가져오지 못한 경우, Kakao 데이터를 가져오지 못한 경우, 예상하지 못한 서버 오류를 서로 구분해서 보여줘. 국토교통부와 Kakao에 보내는 요청이 응답 없이 멈추는 경우도 처리해줘. 정해진 시간과 횟수 안에서만 다시 시도해줘. 그 시간이 지나도 응답이 없으면 검색 조건 문제가 아니라 어느 쪽 데이터를 가져오지 못한 것인지 구분해서 보여줘. 서버 기록에는 어느 API에 보낸 요청이 무엇 때문에 실패했는지 비밀값 없이 남겨줘. 사용자에게 개발자용 오류 메시지나 내부 정보를 그대로 보여주지 말고 무엇이 문제인지 이해할 수 있게 알려줘. 제작 도구의 기본 화면을 그대로 두지 마. 입력하는 곳과 결과를 흰 카드로 나누고 카드 사이에 여백을 줘. 누르는 곳에는 강조색을 하나만 정해서 쓰고, 같은 정보를 한 화면에 여러 번 반복하지 마. 앞에서 정한 검색 규칙은 바꾸지 말고 기존 Test도 계속 통과하게 해줘. 웹 화면에 필요한 Test도 추가하고, 관련 Test를 모두 통과한 뒤 완료했다고 알려줘.

국토교통부 서비스키와 Kakao REST API 키가 브라우저로 전달되지 않고 서버에서만 사용되는지 확인해줘. 실제 키 값은 출력하지 마. 웹 화면에 필요한 Test와 기존 Test를 실행한 뒤 문제가 없는지 알려줘.

`apartment-explorer`를 인터넷에 공개할 준비를 해줘. 관련 Test와 빌드를 확인하고, GitHub에 올리면 안 되는 비밀값이나 파일이 없는지도 확인해줘. 문제가 없다면 현재 상태를 Git으로 기록해 GitHub에 올려줘. 로그인이나 승인처럼 내가 직접 해야 하는 단계가 나오면 알려줘.

아파트 찾기 화면에서 실거래 가격 범위가 현재 매물 가격이 아니라고 알려주는 안내 문구를 조금 더 이해하기 쉽게 수정해줘. 검색 규칙과 API 동작은 바꾸지 마. 수정한 뒤 관련 Test를 실행하고 모두 통과하면 Git에 기록해서 GitHub에 올려줘.

내 컴퓨터에서는 검색되는데 공개된 주소에서는 실패해. 이 프로젝트가 사용하는 환경변수 이름을 알려주고 Vercel에 등록한 이름과 같은지 확인하는 방법을 알려줘. 실제 키 값은 출력하지 마.

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