1. 전체 로드맵
처음부터 끝까지는 아래 6단계로 보면 가장 명확합니다.
2. Windows 개발환경 세팅
OpenAI 문서 기준으로 Windows에서 Codex를 쓰는 가장 쉬운 방법은 Codex App입니다. 다만 VS Code 확장과 CLI는 WSL2 기반 구성이 더 안정적입니다. 따라서 Windows 개발 환경은 아래처럼 구성하는 것이 좋습니다.
Git, Python, Node.js/npm, VS Code, WSL2(Ubuntu), DB Browser for SQLite(선택), Chrome
코드 저장소는 가급적 Git으로 관리하고, Windows 드라이브와 WSL 경로를 혼동하지 않도록 프로젝트별 기준 경로를 정해두는 것이 좋습니다.
2.1 WSL2 설치
Microsoft 문서 기준으로 관리자 PowerShell에서 다음 명령으로 WSL을 설치할 수 있습니다.
wsl --install
설치 후 재부팅하고 Ubuntu 계정을 생성합니다. 이후 wsl -l -v로 버전을 확인합니다.
2.2 Git 설치
Git for Windows는 winget으로 설치할 수 있습니다.
winget install --id Git.Git -e --source winget
2.3 Python 설치
Python 공식 문서 기준으로 Microsoft Store 또는 python.org에서 설치할 수 있습니다. 설치 후에는 다음으로 확인합니다.
python --version pip --version
2.4 Node.js와 npm 준비
React, Vite, Codex CLI는 Node.js/npm이 필요합니다. 설치 후 다음 명령으로 확인합니다.
node -v npm -v
3. 주요 기술 스택 개념 정리
이 튜토리얼에서 다루는 핵심 스택은 프론트엔드, 백엔드, 패키지 관리, 로컬 데이터베이스, 배포로 나뉩니다.
| 항목 | 역할 | 왜 쓰는가 | 권장 위치 |
|---|---|---|---|
| npm | Node 패키지 관리자 | React, Vite, Codex CLI 같은 자바스크립트 툴 설치와 스크립트 실행 | Windows 또는 WSL2 |
| React | 프론트엔드 UI 라이브러리 | 컴포넌트 단위로 복잡한 화면 구성에 적합 | 프론트엔드 |
| TypeScript | 타입이 있는 JavaScript | 에러를 미리 잡고 대형 프로젝트 유지보수를 쉽게 함 | 프론트엔드 / Node |
| Vite | 프론트엔드 빌드 도구 | 빠른 개발 서버와 간단한 배포 빌드 | 프론트엔드 |
| FastAPI | Python 백엔드 프레임워크 | 빠르고 문서화가 강하며 AI/데이터 작업과 연결이 좋음 | 백엔드 |
| SQLite | 파일 기반 DB | 설치가 거의 필요 없고 로컬/파일럿에 매우 적합 | 백엔드와 같은 머신 |
3.1 프론트엔드와 백엔드의 차이
사용자가 브라우저에서 보는 화면입니다. 버튼, 차트, 폼, 지도, 카드, 인터랙션을 담당합니다. React + TypeScript가 여기에 해당합니다.
데이터 저장, 인증, 계산, 외부 API 호출, 파일 업로드, 비즈니스 로직을 담당합니다. FastAPI가 여기에 해당합니다.
3.2 SQLite를 언제 쓰고 언제 바꿔야 하나
SQLite는 in-process, serverless, zero-configuration 구조라서 로컬 개발과 프로토타입에 매우 유리합니다. 다만 여러 머신이 동시에 같은 DB 파일에 접근하거나, 동시 쓰기와 운영 복잡도가 커지는 경우에는 PostgreSQL 같은 클라이언트/서버 DB가 더 적합합니다.
4. ChatGPT Codex 사용법
현재 Codex는 크게 App, CLI, IDE Extension, Cloud 경로로 사용할 수 있습니다. 인증은 ChatGPT 로그인 또는 API key 두 방식이 있고, Cloud는 ChatGPT 로그인 방식이 필요합니다.
Windows 네이티브 앱으로 프로젝트를 넘나들며 병렬 에이전트 작업을 보기 좋게 관리하기에 적합합니다.
터미널에서 직접 코드 읽기·수정·실행을 시킬 수 있습니다. 반복 작업 자동화에 강합니다.
VS Code 안에서 사이드바/컴포저 형태로 Codex를 바로 쓰는 방식입니다. 가장 일반적인 실전 개발 흐름입니다.
4.1 Windows에서 Codex를 시작하는 3가지 방법
4.2 Codex CLI 설치
npm i -g @openai/codex codex
처음 실행하면 ChatGPT 계정 또는 API key로 로그인할 수 있습니다. ChatGPT 로그인을 쓰면 구독 기반으로, API key를 쓰면 사용량 기반으로 과금됩니다.
4.3 Windows에서 특히 중요한 포인트
- App 경로: Windows 네이티브 사용 가능
- CLI/IDE 경로: WSL 기반 실행이 일반적으로 더 안정적
- 보안: Codex는 파일 수정과 명령 실행이 가능하므로 Git 체크포인트를 자주 찍는 것이 좋음
4.4 Codex에 잘 먹히는 프롬프트
# 프로젝트 파악 이 프로젝트 구조를 설명하고, 실행에 필요한 최소 절차를 정리해줘. # 기능 개발 React + TypeScript 프론트엔드와 FastAPI 백엔드를 연결해 로그인 없는 CRUD 예제를 추가해줘. 변경 파일 목록과 실행 명령도 함께 정리해줘. # 버그 수정 현재 에러의 재현 경로를 찾아서 원인을 설명하고, 영향 범위를 최소화하는 방식으로 수정해줘. 수정 후 테스트 명령도 제안해줘. # 디자인 개선 이 화면을 Linear 또는 Stripe처럼 정돈된 느낌으로 리디자인해줘. 색상 토큰, 타이포 스케일, spacing scale도 같이 제안해줘.
Windows 추천 사용 패턴
초기에는 Codex App으로 전체 구조를 잡고, 본격 구현부터는 VS Code Extension으로 세부 작업을 하고, 배치성 반복 작업이나 대량 수정은 CLI로 처리하는 조합이 효율적입니다.
5. Antigravity와 Codex를 연결해 사용하는 법
Antigravity 공식 문서는 에디터가 VS Code codebase 기반이라고 설명하고, 핵심 모델은 Google Vertex Model Garden 계열을 중심으로 제시합니다. 따라서 현재 시점에서 가장 안정적인 Codex 연동 방식은 Antigravity 안의 터미널에서 Codex CLI를 쓰는 것입니다.
5.1 가장 안정적인 방법: Antigravity 터미널에서 Codex CLI 실행
npm i -g @openai/codex → codexnpm i -g @openai/codex codex
5.2 조금 더 편한 방법: Antigravity에서 Codex용 작업 규칙 만들기
Antigravity는 Rules/Workflows와 Skills/MCP 같은 구조를 지원하므로, Codex CLI를 보조 도구처럼 쓸 때 다음 규칙을 만들어 두면 좋습니다.
- 프론트엔드는 React + TypeScript + Vite만 사용 - 백엔드는 FastAPI만 사용 - 데이터베이스는 초기엔 SQLite, 운영 확장 시 Postgres 고려 - 모든 변경은 작은 단위 커밋 기준으로 제안 - 디자인은 card, spacing, typography token을 먼저 정의한 뒤 구현 - 파괴적 명령은 실행 전 설명
5.3 실험 경로: Codex IDE 확장을 Antigravity에 붙이기
Antigravity가 VS Code 기반이므로 일부 환경에서는 확장 호환 방식으로 시도할 수 있지만, 이 경로는 빌드 정책과 확장 마켓 지원 여부에 따라 달라질 수 있습니다. 따라서 실무 튜토리얼에서는 CLI 경로를 기본 경로로 보는 것이 안전합니다.
6. VS Code에 Codex 연결하여 사용하는 방법
VS Code는 Codex를 가장 편하게 쓰기 좋은 환경입니다. 다만 Windows에서는 WSL 연동을 켜는 것이 중요합니다.
6.1 설치 절차
6.2 Windows 전용 핵심 설정
OpenAI 문서에는 다음 설정이 명시되어 있습니다.
chatgpt.runCodexInWindowsSubsystemForLinux
이 설정은 WSL이 가능할 때 Codex를 WSL에서 실행하도록 하며, 문서상 보안과 성능 면에서 권장됩니다. 또한 현재 Windows의 Codex agent mode는 이 설정이 사실상 핵심입니다.
6.3 추천 작업 흐름
- 탐색: “이 프로젝트 구조를 요약해줘”
- 구현: “이 폴더에 FastAPI CRUD 라우트를 추가해줘”
- 리팩터링: “중복 컴포넌트를 공통 Button/Card로 통합해줘”
- 검증: “변경 후 실행 명령과 테스트 포인트를 정리해줘”
6.4 VS Code + Codex + WSL 추천 세팅 예시
# WSL Ubuntu에서 프로젝트 생성 mkdir my-service && cd my-service # 프론트엔드 npm create vite@latest frontend -- --template react-ts # 백엔드 python -m venv .venv source .venv/bin/activate pip install fastapi uvicorn sqlmodel # Codex 실행 codex
7. 주요 서비스를 벤치마크해 세련된 디자인을 적용하는 방법
실무에서는 “그대로 복제”보다 디자인 시스템을 추출해 자기 서비스에 재조합하는 방식이 바람직합니다. 즉, 로고·문구·화면 구조를 베끼는 것이 아니라 색·간격·타이포·그리드·카드 구조를 분석해 자체 토큰으로 만드는 방식입니다.
7.1 가장 먼저 보는 5가지
배경색, 포인트색, 경계선, 상태색을 분리합니다.
제목, 본문, 캡션의 크기·행간·굵기 체계를 잡습니다.
8px 또는 4px 단위 scale로 일관성을 만듭니다.
카드의 둥근 정도와 그림자 강도를 토큰화합니다.
콘텐츠 폭, 섹션 간격, 카드 배치 밀도를 정합니다.
hover, transition, skeleton, loading의 톤을 통일합니다.
7.2 디자인 토큰 예시
:root {
--bg: #f7f8fb;
--surface: #ffffff;
--text: #121826;
--muted: #667085;
--primary: #4f46e5;
--border: #e5e7eb;
--radius-xl: 24px;
--radius-lg: 16px;
--shadow-soft: 0 10px 30px rgba(0,0,0,0.08);
--space-1: 4px;
--space-2: 8px;
--space-3: 12px;
--space-4: 16px;
--space-5: 24px;
--space-6: 32px;
}
7.3 Codex에 디자인 개선을 맡기는 프롬프트
이 서비스의 UI를 현대적인 SaaS 스타일로 개선해줘. 요구사항은 다음과 같아. - white/gray 기반의 깔끔한 배경 - 명확한 정보 위계 - 카드 중심 레이아웃 - 일관된 typography scale - 버튼, 입력창, 카드에 공통 design token 적용 - 모바일 반응형 포함 - 기존 기능은 유지하고 시각적 품질만 개선 먼저 color palette, typography, spacing, radius, shadow token을 제안하고, 그 다음 컴포넌트별 변경안을 반영해줘.
7.4 벤치마크를 실제 구현으로 바꾸는 순서
8. React + TypeScript + FastAPI + SQLite로 웹서비스를 개발하는 기본 흐름
이 조합은 AI 코딩에 특히 잘 맞습니다. 프론트엔드는 Vite로 빠르게 시작하고, 백엔드는 FastAPI로 API를 만들고, 데이터는 SQLite 파일에 저장하면 됩니다.
8.1 프로젝트 구조 예시
my-service/ ├─ frontend/ # React + TypeScript + Vite ├─ backend/ │ ├─ app/ │ │ ├─ main.py # FastAPI entry │ │ ├─ models.py # SQLModel models │ │ ├─ routers/ │ │ └─ db.py │ └─ requirements.txt ├─ .env └─ README.md
8.2 프론트엔드 시작
npm create vite@latest frontend -- --template react-ts cd frontend npm install npm run dev
Vite는 기본적으로 빠른 개발 서버를 제공하고, 프로덕션 시 vite build로 정적 배포용 번들을 생성합니다. 기본 출력은 dist입니다.
8.3 백엔드 시작
cd backend python -m venv .venv source .venv/bin/activate # Windows PowerShell이면 다른 활성화 명령 사용 pip install fastapi uvicorn sqlmodel uvicorn app.main:app --reload
8.4 최소 FastAPI 예시
from fastapi import FastAPI
app = FastAPI()
@app.get("/")
def root():
return {"message": "hello"}
8.5 SQLite 연동 전략
초기 버전에서는 app.db 같은 파일 하나로 시작하면 충분합니다. SQLModel을 쓰면 FastAPI와 잘 맞고, 나중에 PostgreSQL로 옮길 때도 구조 전환이 비교적 수월합니다.
8.6 Codex에 맡기면 좋은 작업
- REST API CRUD 라우트 생성
- Pydantic/SQLModel 모델 생성
- React 폼, 테이블, 필터 패널 생성
- 상태 관리 정리와 API 연결
- CSS 토큰과 공통 컴포넌트 정리
- README, 실행 스크립트, .env.example 생성
9. 서비스 개발 후 실제 서비스용 클라우드 서버 만들고 배포하는 방법
FastAPI 문서도 배포 전략은 여러 방식이 가능하다고 설명합니다. 실제 선택은 비용, 설정 난이도, 운영 편의성, 향후 확장성의 균형 문제입니다.
9.1 가장 현실적인 세 가지 경로
| 옵션 | 구성 | 장점 | 단점 | 추천 상황 |
|---|---|---|---|---|
| A. 가장 쉬운 관리형 | Vercel(프론트) + Railway 또는 Render(백엔드) | 배포가 빠르고 DevOps 부담이 낮음 | 서비스가 커지면 비용이 서서히 올라갈 수 있음 | 교수님 개인 서비스, 파일럿, MVP |
| B. 가장 싼 단일 서버 | AWS Lightsail 또는 DigitalOcean Droplet 한 대 | 고정비가 명확하고 저렴함 | 운영, 보안, 백업, 배포를 직접 챙겨야 함 | 내부용 서비스, 실험 서비스, 예산 최소화 |
| C. 확장 전제형 | 프론트 정적 호스팅 + 컨테이너 기반 백엔드 + Postgres | 구조가 깔끔하고 확장성이 좋음 | 초기 구성 복잡도 증가 | 외부 공개 서비스로 확장 예상 |
9.2 경제적인 옵션 정리
Hobby 플랜은 무료로 시작할 수 있어 프론트엔드 정적 배포에 가장 편한 편입니다.
개인 프로젝트용 무료/저비용 시작이 가능하지만, 무료 인스턴스는 프로덕션 용도가 아니라는 제한을 명확히 봐야 합니다.
사용량 기반 구조라 초기엔 부담이 낮고 FastAPI 배포 가이드도 잘 정리되어 있습니다.
월 고정비가 명확합니다. Linux 인스턴스는 월 3.50 USD부터 제시됩니다.
저가형 Droplet이 월 4 USD부터 시작합니다. 직접 서버 운영이 가능한 사용자에게 유리합니다.
초기 MVP는 Vercel + Railway/Render, 장기적으로는 VPS 또는 Postgres 포함 구조로 이동하는 방식이 무난합니다.
9.3 프론트와 백엔드를 분리해 배포하는 절차
npm run build로 dist 생성9.4 단일 VPS에 올리는 절차
# 서버 접속 후 sudo apt update && sudo apt upgrade -y sudo apt install python3-pip python3-venv nginx git -y # 앱 배포 git clone YOUR_REPO_URL cd YOUR_REPO python3 -m venv .venv source .venv/bin/activate pip install -r requirements.txt # FastAPI 실행 예시 uvicorn app.main:app --host 0.0.0.0 --port 8000
실서비스라면 여기서 끝내지 말고 Nginx reverse proxy, systemd 서비스 등록, HTTPS, 백업, 로그 회전을 함께 구성해야 합니다.
9.5 SQLite를 클라우드에서 쓸 때의 판단
10. 바로 실행할 수 있는 체크리스트
한 줄 추천
11. 참고 자료
아래 자료를 기준으로 최신 제품 경로, 설치 방식, 배포 옵션, 가격 정보를 정리했습니다.