프로젝트 폴더 세팅 — haru-market 폴더 만들기

한 줄 요약

나눠 드린 haru-market.zip을 문서(Documents) 폴더에 풀어, 문서/haru-market을 이 과정의 프로젝트 폴더로 만듭니다. 24장까지 모든 파일은 이 폴더 안에 만듭니다.

이 절이 2장에서 가장 중요합니다. 폴더 위치와 이름이 다르면 이후 모든 명령이 어긋납니다.

1. 압축을 어디에 푸는가

운영체제	프로젝트 폴더의 최종 위치
Windows	`C:\Users\사용자명\Documents\haru-market`
macOS	`/Users/사용자명/Documents/haru-market`

지켜 주세요.

폴더 이름은 haru-market 그대로 둡니다. 교재의 모든 명령이 이 이름을 기준으로 적혀 있습니다.
바탕화면·다운로드 폴더에 두지 않습니다. 문서 폴더에 둡니다.
문서 폴더가 OneDrive나 iCloud로 동기화되고 있다면, 동기화되지 않는 위치(예: C:\haru-market)에 두는 것이 안전합니다. 실습 중에 생기는 파일이 동기화와 충돌할 수 있습니다. 이 경우 교재의 ~/Documents/haru-market을 본인 위치로 바꿔 읽으면 됩니다.

2. 압축 풀기

Windows

haru-market.zip을 문서 폴더로 옮깁니다.
파일을 마우스 오른쪽 버튼으로 눌러 압축 풀기를 고릅니다.
풀린 폴더를 열어 봅니다. 안에 data 폴더와 config.py가 바로 보여야 합니다.

폴더가 두 겹이 되었는지 확인하세요. haru-market 안에 또 haru-market이 들어 있는 경우가 있습니다(문서\haru-market\haru-market\data). 그렇다면 안쪽 폴더를 문서 폴더로 꺼내고 바깥 빈 폴더는 지웁니다. 문서\haru-market\data가 되어야 합니다.

한글 파일 이름이 깨져 보인다면 data 폴더의 PDF 이름이 이상한 글자로 보일 수 있습니다. 반디집이나 7-Zip 같은 압축 프로그램으로 다시 풀어 보세요.

macOS

haru-market.zip을 문서 폴더로 옮깁니다.
파일을 더블클릭하면 같은 위치에 haru-market 폴더가 생깁니다.

macOS에서는 .env.example 파일이 Finder에 안 보입니다. 이름이 점(.)으로 시작하는 파일은 숨김 파일이기 때문입니다. 정상입니다. Finder에서 Cmd + Shift + .을 누르면 보입니다. VS Code에서는 처음부터 보입니다.

3. VS Code로 프로젝트 폴더 열기

VS Code를 실행합니다.
메뉴에서 파일(File) → 폴더 열기(Open Folder…) 를 고릅니다.
문서 폴더 안의 haru-market을 선택하고 폴더 선택(열기) 을 누릅니다.
"이 폴더의 작성자를 신뢰합니까?"라고 물으면 예, 신뢰합니다를 누릅니다.

왼쪽 탐색기에 다음과 같이 보이면 제대로 연 것입니다.

haru-market/
├── app/
│   └── frontend/
│       ├── admin.html       상담원 화면 (24장에서 사용)
│       └── index.html       고객 채팅 화면 (24장에서 사용)
├── data/
│   ├── customers.csv        고객 20명
│   ├── inquiries.csv        상담 문의 로그 40건
│   ├── orders.csv           주문 80건
│   ├── products.csv         상품 30종
│   ├── 질문셋.md             표준 질문 12개
│   ├── 하루마켓_멤버십정책.pdf
│   └── 하루마켓_반품교환환불정책.pdf
├── .env.example             API 키를 넣을 파일의 양식
├── config.py                (제공) 공통 설정 — 고치지 않아도 됩니다
├── README.md                폴더 안내
└── requirements.txt         설치할 라이브러리 목록

반드시 "폴더째로" 엽니다. 파일 하나만 열면 터미널의 위치가 프로젝트 폴더가 아니어서 실행이 실패합니다.

4. 터미널의 위치 확인

VS Code에서 Ctrl + `로 터미널을 열고 다음을 입력합니다.

$ pwd

/c/Users/사용자명/Documents/haru-market

경로의 끝이 haru-market이면 됩니다. (macOS는 /Users/사용자명/Documents/haru-market으로 나옵니다.)

이어서 안에 무엇이 있는지 봅니다.

$ ls

README.md  app  config.py  data  requirements.txt

config.py와 data가 보이면 프로젝트 폴더 세팅이 끝난 것입니다.

왼쪽 탐색기에 있던 .env.example은 여기에 나오지 않습니다. 이름이 점(.)으로 시작하는 숨김 파일이라 ls가 보여 주지 않을 뿐, 빠진 것이 아닙니다. ls -a를 입력하면 함께 나옵니다.

터미널을 따로 열었다면 먼저 프로젝트 폴더로 이동합니다.

$ cd ~/Documents/haru-market

5. 제공된 파일과 앞으로 만들 파일

지금 폴더에 들어 있는 것은 코드로 만들 수 없는 재료와 공통 설정뿐입니다.

제공된 것	내용
`data/`	하루마켓 실습 데이터
`app/frontend/index.html`	24장에서 쓰는 고객 채팅 화면
`app/frontend/admin.html`	24장에서 쓰는 상담원 화면. 에이전트가 올린 환불·주문 취소 요청을 승인하고, 넘겨받은 문의를 봅니다
`config.py`	API 키를 읽고 Gemini에 연결해 주는 공통 설정. 모든 실습 파일이 이 파일을 불러 씁니다
`.env.example`, `requirements.txt`	API 키 양식, 설치 목록

나머지 실습 파일은 여러분이 각 장에서 직접 만듭니다. 방법은 매번 같습니다.

VS Code 탐색기에서 새 파일을 만든다. (파일 이름은 교재가 알려 줍니다)
교재의 코드 블록 오른쪽 위 복사 버튼을 눌러 코드 전체를 복사한다.
새 파일에 붙여 넣고 저장한다. (Ctrl + S)
터미널에서 실행한다.

과정이 끝나면 폴더는 이런 모습이 됩니다.

haru-market/
├── config.py                          (제공)
├── lesson02_first_call.py             2장에서 만듭니다
├── lesson03_prompt.py                 3장
├── ...
├── haru_tools.py                      8장 — 도구 모음
├── haru_actions.py                    21장 — 처리 도구
├── haru_agents.py                     21장 — 전문 에이전트 셋
├── haru_supervisor.py                 22장 — Supervisor
└── app/
    ├── main.py                        24장 — 서버
    └── frontend/
        ├── admin.html                 (제공)
        └── index.html                 (제공)

핵심 정리

haru-market.zip을 문서 폴더에 풀어 문서/haru-market을 만듭니다. 이름은 바꾸지 않습니다.
폴더가 두 겹이 되지 않았는지 확인합니다. haru-market 바로 안에 data와 config.py가 있어야 합니다.
VS Code에서 폴더째로 열고, 터미널에서 pwd와 ls로 위치를 확인합니다.
실습 파일은 각 장에서 새 파일 만들기 → 코드 복사 → 붙여 넣기 → 저장 → 실행으로 만듭니다.