리뷰 온도계

© 2026 김연지. All rights reserved. 수강생 개인 학습용 · 무단 강의·복제·배포·수정 금지 · LICENSE.md

이 문서는 수업 저장소의 첫 화면입니다. 무엇을 만드는지, 어떤 명령을 복사해 쓰는지, 다른 문서가 어디 있는지 적었습니다.

가상 쇼핑몰 하루마켓의 리뷰 한 건과 별점을 넣으면, 긍정/부정과 리뷰 온도(0~100℃), 별점과 내용이 반대인지 알려 주는 API와 화면입니다. 하루마켓은 수업용 가상 서비스입니다.

• 개발요청서: REQUEST.md
• 공식 명세서(무엇을 만들지 적은 문서): SPEC.md (1차), SPEC_COUPON.md (2차, 쿠폰 명세서. 세션 4에서 직접 씁니다)

Python, VS Code 확장, agy는 세션 1에서 설치합니다. 순서는 docs/01-setup-card.md B절을 따릅니다. 설치가 끝나면 블록 ①로 확인합니다.

오늘 만드는 순서

매 세션 같은 순서로 일합니다.

flowchart LR
    A["명세 SPEC.md"] --> B["테스트 작성<br/>Red: 실패"]
    B --> C["구현<br/>Green: 통과"]
    C --> D["수정 범위 확인"]
    D --> E["commit / push"]

세션 3에서는 이 순서에 "MCP·스킬을 찾아 붙이기"를 더합니다. 세션 4에서는 명세를 직접 쓰는 것부터 시작합니다.

안전 규칙

• AI 채팅에 비밀번호, API 키, 실제 고객 정보, 회사 코드는 넣지 않습니다.
• agy 로그인 때 Google 비밀번호는 로그인 화면에만 입력합니다. AI 채팅에는 넣지 않습니다.
• 결제 수단은 어디에도 등록하지 않습니다.
• MCP 서버를 켤 때 뜨는 신뢰 확인 창에서는 명령이나 주소를 읽습니다. 내가 직접 넣은 것만 허락하고, 처음 보는 것은 허락하지 않습니다.

로컬 실행

처음이라면 docs/01-setup-card.md를 순서대로 따라 합니다. 요약은 아래와 같습니다.

• 파이썬은 3.11 이상(3.12 권장)이 필요합니다. python.org에서 설치하고(Windows는 Add python.exe to PATH 체크), python --version(Mac은 python3 --version)으로 확인합니다.
• VS Code를 처음 열면 "이 폴더를 신뢰합니까?" 창이 뜹니다. Yes, I trust를 누르고, 추천 확장 알림은 닫습니다.
• VS Code에 확장 두 개가 필요합니다. 왼쪽 Extensions(네모 4개 아이콘)에서 Python(Microsoft)과 GitHub Copilot Chat을 검색해 Install 합니다.
• Mac은 편집기 단축키에서만 Ctrl 대신 Cmd를 씁니다. 터미널의 서버 종료 Ctrl+C는 Mac도 Ctrl입니다.
• 내 PC에서는 MODEL_REPO를 입력하지 않습니다. 모델 저장소 이름은 코드(app/sentiment.py)에 들어 있습니다.

(.venv)는 가상환경(이 프로젝트만 쓰는 파이썬 상자)이 켜졌다는 표시입니다.

macOS:

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
uvicorn app.main:app --reload

Windows PowerShell:

Set-ExecutionPolicy -Scope CurrentUser RemoteSigned
python -m venv .venv
.venv\Scripts\Activate.ps1
pip install -r requirements.txt
uvicorn app.main:app --reload

• Set-ExecutionPolicy는 한 번만 합니다. 묻는 창에는 Y를 씁니다.
• Activate.ps1이 안 되면 터미널 오른쪽 위 ▼ → Command Prompt를 열고 .venv\Scripts\activate.bat를 칩니다.
• Windows에서 python을 치면 Microsoft Store가 열릴 때는 py를 씁니다.

브라우저에서 http://localhost:8000 을 엽니다. API 문서는 http://localhost:8000/docs 입니다.

Copilot Chat은 VS Code 맨 위 가운데 검색창 옆의 채팅 아이콘으로 엽니다. 단축키는 Windows Ctrl+Alt+I, Mac Ctrl+Cmd+I입니다. 모드 드롭다운은 입력창 아래에 있습니다. Ask와 Agent가 보이면 성공입니다(Plan은 버전에 따라 보입니다).

agy는 프로젝트 폴더의 터미널에서 agy를 입력해 켭니다. 처음 켤 때 본인 Google 계정으로 로그인합니다.

git 이메일: Public 저장소에서는 commit에 이메일이 보입니다. 원하지 않으면 GitHub Settings → Emails의 noreply 주소를 씁니다.

테스트

review-thermo 폴더에서 실행합니다.

pytest -v

테스트는 가짜 AI 부품을 쓰므로 모델도 인터넷도 필요 없습니다. pytest가 처음이라면 docs/02-pytest.md를 먼저 읽습니다.

명령 복사 블록

GitHub 화면에서 코드 블록 오른쪽 위의 복사 버튼으로 복사해 터미널에 붙여 넣습니다. 번호는 수업 슬라이드의 "README ⑥ 복사" 표시와 같습니다. ⑫⑮는 세션 3에서, ⑭⑯은 세션 4에서, ⑰은 선택 과제에서 새로 쓰는 블록입니다. 꺾쇠 < >는 빼고 내 값으로 바꿉니다. 예: <내아이디>는 haru123.

① 설치 확인 (Mac은 python --version 대신 python3 --version)

python --version
git --version
code --version
agy --version

①-2 agy 설치 · Windows PowerShell (끝나면 새 터미널에서 agy --version)

irm https://antigravity.google/cli/install.ps1 | iex

①-2 agy 설치 · macOS

curl -fsSL https://antigravity.google/cli/install.sh | bash

② 저장소 받기 (<내아이디> 자리에 내 GitHub 아이디를 씁니다)

git clone https://github.com/<내아이디>/review-thermo.git
cd review-thermo
code -r .

③ Git 이름 설정 (처음 한 번만)

git config --global user.name "내 이름"
git config --global user.email "GitHub 가입 이메일"

④ 가상환경 · macOS

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

⑤ 가상환경 · Windows PowerShell

python -m venv .venv
.venv\Scripts\Activate.ps1
pip install -r requirements.txt

uv나 Poetry를 쓰는 경우 (선택)

④⑤의 python -m venv와 pip install 대신 uv나 Poetry로 같은 환경을 만들 수 있습니다. 어느 쪽을 쓰든 결과는 같고, 처음 쓰는 분은 ④⑤만 따라 해도 됩니다. 설치가 끝나면 새 터미널을 엽니다.

uv 설치 · Windows PowerShell

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

uv 설치 · macOS

curl -LsSf https://astral.sh/uv/install.sh | sh

uv로 패키지 설치와 실행 (Windows · macOS 공통)

uv sync
uv run uvicorn app.main:app --reload
uv run pytest -v

Poetry 설치 · Windows PowerShell

(Invoke-WebRequest -Uri https://install.python-poetry.org -UseBasicParsing).Content | py -

Poetry 설치 · macOS

curl -sSL https://install.python-poetry.org | python3 -

Poetry로 패키지 설치와 실행 (Windows · macOS 공통)

poetry install
poetry run uvicorn app.main:app --reload
poetry run pytest -v

• uv sync와 poetry install은 .venv 폴더를 만들고 패키지를 설치합니다. 가상환경을 켜는 Activate 명령은 필요 없습니다.
• 이후 단계의 python, pytest, uvicorn 명령 앞에 uv run(또는 poetry run)을 붙입니다.
• VS Code에서 인터프리터는 .venv를 고릅니다(세 방법 모두 .venv를 만듭니다).
• 패키지 목록은 requirements.txt(pip)와 pyproject.toml(uv·Poetry) 두 곳에 있습니다.

⑥ 서버 켜기 (브라우저에서 http://localhost:8000)

uvicorn app.main:app --reload

⑦ 테스트

pytest -v

⑧ 수정 범위 확인 (git restore는 tests/나 SPEC.md가 바뀌었을 때만)

git diff --stat
git status
git restore tests/ SPEC.md

⑨ 저장하고 올리기 ("메시지" 자리에 내 설명을 적습니다)

git add .
git commit -m "메시지"
git push

⑩ 따라잡기 (<브랜치> 자리에 수업에서 알려 주는 이름을 씁니다. 예: cp3-tdd)

git fetch origin
git checkout origin/<브랜치> -- .

⑪ 공식 명세 받기

git fetch origin
git checkout origin/cp2-spec -- SPEC.md

⑫ MCP 서버 추가 (세션 3)

Context7은 npx로 내 PC에서 돌리는 방식과 인터넷의 서버에 접속하는 http 방식이 있습니다. 두 방식을 모두 붙여 봅니다. 먼저 npx가 필요하므로 Node.js를 설치합니다(18 이상).

Windows PowerShell:

winget install OpenJS.NodeJS.LTS

설치가 끝나면 터미널(VS Code 포함)을 모두 닫았다가 다시 엽니다.

macOS:

brew install node

Homebrew가 없으면 https://nodejs.org 에서 LTS 설치 파일을 받아 설치합니다. 설치 뒤 터미널(VS Code 포함)을 다시 엽니다.

확인(공통). 둘 다 버전 숫자가 나오면 됩니다.

node -v
npx -v

PowerShell에서 npx가 실행 정책 오류를 내면 세션 1에서 한 Set-ExecutionPolicy -Scope CurrentUser RemoteSigned를 다시 실행합니다.

VS Code에서 서버를 추가하는 방법은 두 가지입니다. 편한 쪽을 하나 고릅니다.

방법 1. 메뉴로 추가합니다.

여기까지가 README 앞부분입니다. 나머지는 원문에서 읽을 수 있습니다. README 전문 보기 ↗