1. 개발환경 만들기
프로젝트마다 따로 쓰는 작업실
이 차시를 마치면
가상환경을 만들고 VS Code 가 그것을 쓰게 맞춥니다.
프로젝트마다 독립된 파이썬 환경을 만들고, VS Code가 그 환경을 쓰도록 맞춥니다.
가상환경이란 무엇인가
개념. 가상환경은 프로젝트 폴더 안에 만드는 별도의 파이썬 실행 환경입니다.
특성. 이 안에 설치한 패키지는 이 폴더 밖에 영향을 주지 않습니다. 반대로 시스템에 깔린 패키지도 이 안으로 들어오지 않습니다.
역할. 프로젝트별 패키지 충돌을 막습니다. A 프로젝트가 langchain 1.3을, B 프로젝트가 1.1을 써야 할 때 둘을 함께 둘 수 있습니다.
보안 관점의 역할. 프로젝트 밖 패키지와 자료가 같은 공간을 쓰지 않게 합니다. 분석
비유
가상환경은 프로젝트마다 따로 쓰는 공구함입니다. 공용 창고에서 공구를 꺼내 쓰면 편하지만, 누가 무엇을 바꿔 놨는지 알 수 없습니다. 공구함을 따로 두면 이 프로젝트가 어떤 공구를 어떤 크기로 쓰는지 목록이 분명해집니다.
폴더 만들기
mkdir langgraph-study
cd langgraph-study
code .
code . 명령이 동작하지 않으면 VS Code에서 직접 폴더를 열어도 됩니다.
가상환경 생성
macOS 와 Linux
python3 -m venv .venv
source .venv/bin/activate
Windows PowerShell
py -3.11 -m venv .venv
.\.venv\Scripts\Activate.ps1
VS Code 가 이 환경을 쓰게 만들기
- Command Palette 열기
Python: Select Interpreter실행.venv선택
선택된 interpreter는 VS Code 상태바에서 확인할 수 있습니다.
왜 이 확인이 보안 점검이기도 한가 분석
터미널 왼쪽에 (.venv) 표시가 있어야 가상환경이 켜진 상태입니다. 이 표시가 없는 상태에서 pip install을 하면 시스템 전역에 패키지가 설치되고, 다른 프로젝트의 자료와 같은 공간을 쓰게 됩니다. 설치가 끝난 뒤에도 이 표시를 매번 확인하는 습관이 필요합니다.
권장 VS Code 확장
필수: Python (Microsoft), Pylance
권장: Ruff, GitLens, Docker(Docker를 쓸 때), Jupyter(노트북을 쓸 때)
기본 프로젝트 구조
langgraph-study/
├─ .venv/
├─ .env
├─ .env.example
├─ .gitignore
├─ requirements.txt
├─ src/
│ ├─ __init__.py
│ ├─ agent.py
│ ├─ graph.py
│ ├─ state.py
│ ├─ tools.py
│ └─ prompts.py
├─ tests/
│ ├─ test_tools.py
│ └─ test_graph.py
└─ README.md
분리 기준
| 파일 | 역할 |
|---|---|
state.py | 상태 스키마 |
tools.py | 외부 기능 |
graph.py | Node, Edge, Graph |
agent.py | 고수준 Agent 진입점 |
prompts.py | prompt 관리 |
tests/ | 단위 테스트 |
이 구조를 왜 이렇게 나누는지는 3번 트랙 "코드 구조화"에서 자세히 다룹니다.
.gitignore
.venv/
__pycache__/
*.pyc
.env
.DS_Store
.pytest_cache/
.ruff_cache/
API 키가 들어 있는 .env는 Git에 올리지 않습니다. 이 파일을 가장 먼저 만드는 이유는 앞 차시에서 다뤘습니다.