# 설치와 시작 가이드
Clinic-OS는 **에이전트(Claude Code)가 설치를 진행**합니다. 사용자는 환경을 열고, 에이전트에게 "설치해줘"라고 요청하면 됩니다.
> **총 소요 시간**: 처음부터 기본 홈페이지 확인까지 **약 7~10분**
---
## 시작하기 전에
설치를 시작하기 전에 아래 4가지를 준비하세요.
| 준비물 | 설명 | 주소 |
|--------|------|------|
| **GitHub 계정** | 스타터킷 다운로드, Codespaces 사용 (무료) | [github.com](https://github.com) |
| **Cloudflare 계정** | 사이트 배포용 (무료 티어) | [dash.cloudflare.com/sign-up](https://dash.cloudflare.com/sign-up) |
| **Claude Max 요금제** | Claude Code 에이전트 사용 — **$100/월 (개발 기간 필수)**, 워크숍 종료 후 Pro $20 다운그레이드 가능 | [claude.ai](https://claude.ai) |
| **한의원 기본 정보** | 상호, 주소, 전화, 진료시간, 의료진 프로필 | — |
> 설치 시간: **Codespaces 7~10분** / macOS 로컬 20분 / Windows 로컬은 Codespaces 강력 권장
---
## 개발 환경 선택하기
### 추천: GitHub Codespaces
**설치할 것이 없습니다.** 브라우저만 있으면 됩니다. 클라우드에 Node.js와 개발 도구가 이미 준비된 환경이 2~3분 안에 만들어집니다.
**Windows 사용자는 Codespaces를 강력 추천합니다.**
#### 1단계 · 내 레포 만들기 (30초)
브라우저에서 워크숍 템플릿 저장소에 접속:
**`github.com/xulfereht/clinic-os-workshop`**
상단의 초록색 **"Use this template"** 버튼 → **"Create a new repository"** 선택 → 본인 GitHub 계정에 새 레포 생성:
- Repository name: `clinic-os-{내한의원이름}` (예: `clinic-os-baekrokdam`)
- **Public / Private**: **Private 권장** (한의원 데이터 보호)
> ⚠️ **워크샵 템플릿 레포에서 직접 Codespace를 만들지 마세요.** 그러면 작업을 `git push`로 백업할 수 없습니다. 반드시 위 단계로 **내 레포**를 먼저 만들고 거기서 Codespace를 여세요.
#### 2단계 · 내 레포에서 Codespace 열기 (2~3분)
방금 만든 **내 레포**로 이동 → 초록색 **`< > Code`** 버튼 → **Codespaces** 탭 → **Create codespace on main** 클릭.
2~3분 대기. 자동 설치:
- Node.js 22
- Cloudflare Wrangler CLI
- **Claude Code (AI 에이전트) — 최신 버전 자동 설치 (`@latest`)**
- Astro
#### 3단계 · Claude Code 실행 + 로그인 (1분)
Codespace 터미널에서:
```
claude
```
첫 실행 시 Anthropic 로그인 화면이 뜹니다:
1. 터미널에 표시되는 링크 클릭 → 브라우저에서 Claude 로그인
2. 인증 완료 후 터미널로 돌아오면 에이전트 준비 완료
#### 4단계 · 스타터킷 다운로드 + HQ 인증 (3~5분)
에이전트에게 이렇게 말하세요:
```
스타터킷 받아서 설치해줘
```
에이전트가 다음 명령을 실행합니다 (원장님이 직접 입력해도 동일):
```bash
curl -fsSL https://clinic-os-hq.pages.dev/cos-setup.sh | bash
```
##### 4-1. 인증 코드 입력 (브라우저)
스크립트가 실행되면 터미널에 **인증 코드 박스**가 표시됩니다:
```
╔══════════════════════════════════════╗
║ 브라우저에서 아래 코드를 입력하세요: ║
║ ║
║ ABCD-1234 ║
╚══════════════════════════════════════╝
URL: https://clinic-os-hq.pages.dev/auth/device
```
동시에 **브라우저가 자동으로 열립니다.** 박스에 표시된 코드(`ABCD-1234`)를 브라우저 화면에 입력하고 **HQ 계정으로 로그인**하세요.
> HQ 계정이 없으면 강사가 사전에 발급해드린 계정 정보를 사용하세요.
>
> 브라우저가 자동으로 열리지 않으면 터미널에 표시된 URL을 직접 방문하면 됩니다.
>
> 인증 시간은 최대 15분입니다. 그 안에 브라우저 인증을 완료하세요.
##### 4-2. 인증 완료 → 자동 다운로드
브라우저 인증을 마치면 스크립트가 자동으로 진행:
1. **인증 완료 메시지** 표시 (예: `✓ 인증 완료! (백록담한의원)`)
2. **내 한의원 전용 스타터킷** zip 다운로드 (개별 `clinic.json` + 라이선스 키 포함, Bearer 토큰 인증)
3. 압축 해제 → `clinic-os/` 폴더 생성
##### 4-3. 의존성 설치 + 초기 셋업
에이전트가 이어서:
```bash
cd clinic-os
npm install
npm run setup:agent
```
완료되면 개발 서버가 실행되고 포트 4321이 자동 포워딩되어 브라우저에서 한의원 기본 홈페이지를 확인할 수 있습니다.
> **Cloudflare 연결은 별도 단계입니다.** 워크숍 후반(보통 3주차)에 진행합니다. Codespaces 환경에서는 `wrangler login` OAuth가 불안정하므로 **API Token 방식**을 사용합니다. 자세한 발급/적용 방법: **[Cloudflare 셋업 가이드](/guide#cloudflare-setup)** 참조.
---
### macOS 로컬 (20분)
Mac은 Unix 기반이라 별도 설정이 거의 없습니다. **로컬 환경은 과금이 없는 장점이 있습니다.**
**필요한 것:**
- macOS 12 이상
- Homebrew (없으면 에이전트가 설치 안내)
- Node.js 20+ (없으면 에이전트가 설치 안내)
시작 방법:
1. 터미널에서 스타터킷 다운로드 스크립트 실행:
```bash
curl -fsSL https://clinic-os-hq.pages.dev/cos-setup.sh | bash
```
2. 터미널에 표시되는 **인증 코드**(예: `ABCD-1234`)를 자동으로 열린 브라우저에서 입력 + HQ 계정 로그인.
3. 인증 완료 시 스타터킷 zip이 자동 다운로드 → `clinic-os/` 폴더 생성.
4. `cd clinic-os` 후 Claude Code 실행 (`claude`) → 에이전트에게: **"설치 상태 진단하고 설치 진행해줘"**
에이전트가 환경을 진단하고 의존성 설치부터 초기 설정까지 진행합니다.
> **Cloudflare 연결**: macOS 로컬에서는 `wrangler login` OAuth도 정상 작동하므로, API Token 방식과 OAuth 둘 다 가능합니다. 자세한 내용: **[Cloudflare 셋업 가이드](/guide#cloudflare-setup)** 참조.
> 스타터킷을 수동으로 받고 싶다면 HQ 대시보드에서 zip 파일을 다운로드할 수도 있습니다.
---
### Windows 로컬 (Codespaces 강력 권장)
**Windows 사용자는 위의 Codespaces 방법을 따르세요.** WSL 설치, Node 설치, 권한 설정 등 변수가 너무 많아 1기 워크숍에서 가장 큰 병목이었습니다.
오프라인 작업 등 꼭 로컬이 필요한 경우 워크숍 단톡방에 문의하세요.
---
## ⚠️ Codespace 관리 규칙 (필독)
### 핵심: Codespace를 **삭제하지 마세요** — 프로덕션 배포 전에는 치명적
Codespace를 삭제하면 `.gitignore`에 포함된 파일(= GitHub에 푸시되지 않는 것)이 **전부 소실**됩니다.
| 항목 | GitHub에 푸시되나? | Codespace 삭제 시 |
|------|--------------------|-------------------|
| 소스 코드, 설정 파일 | ✅ | 복구 가능 (`git clone`) |
| 업로드한 이미지 (`public/local/images/`) | ✅ | 푸시했으면 복구 |
| **로컬 D1 DB** (환자 데모, 포스트 초안, 설정) | ❌ `.gitignore` | **완전 증발** |
| API 키, 비밀번호 (`.env.local`) | ❌ `.gitignore` | **재발급 필요** |
| `node_modules` | ❌ `.gitignore` | 재설치 3~5분 |
워크숍 초반 1~2주 동안 원장님이 에이전트와 대화하며 입력한 **한의원 소개, 환자 데모, 블로그 초안, 프로그램 정보**는 모두 **로컬 D1 파일에만** 있다가 Cloudflare 배포 시점에 원격으로 복사됩니다. 배포 전 삭제하면 처음부터 다시 입력해야 합니다.
### ✅ 해야 할 것
- **매일 작업 끝날 때 `git push`** — 커밋 가능한 모든 변경사항 백업
- 에이전트에게 "오늘 작업 커밋하고 푸시해줘"라고 하면 자동 처리
- **작업 중단 시 그냥 브라우저 닫기** — 30분 idle 후 자동 정지 (VM 과금 멈춤, 스토리지 유지)
### ❌ 절대 하지 말 것
- **Codespace 삭제** — 프로덕션 배포(보통 3주차) 전까지 치명적
- 워크숍 전 기간(약 5주) 동일 Codespace 유지
### 📅 재접속 방법
언제든 내 레포 → Code → Codespaces → 기존 Codespace 클릭 → 다시 열림 (정지 상태였으면 30초 내 부팅).
### 🛡️ 프로덕션 배포 후
Cloudflare D1에 데이터가 원격 저장되므로 Codespace를 삭제해도 실제 한의원 데이터는 안전합니다. 다만 로컬 개발환경 복구에 시간이 걸리므로 여전히 삭제 비추천.
---
## 과금 예상 (4주 워크숍 기준)
| 항목 | 비용 |
|------|------|
| Claude Max | $100/월 × 1~2개월 (개발 기간) |
| GitHub Codespaces | **무료** (2코어 60시간/월 한도 내) |
| Codespace 스토리지 | ~$2/월 ($0.07/GB × 30GB) |
| Cloudflare | **무료** (Pages + D1 기본 플랜) |
---
## 설치 진행하기
환경이 준비되면 에이전트에게 이렇게 요청하세요:
> **"이 프로젝트를 읽고 설치 상태를 진단한 다음, 설치를 진행해줘."**
에이전트가 자동으로 처리하는 것:
- 현재 상태 진단 (신규/재개/업데이트 판별)
- 의존성 설치
- 데이터베이스 초기화
- 빌드 검증
- 설치 완료 시 health 점수 표시
사용자가 설치 중에 하는 일:
- **HQ 인증** — 터미널에 표시된 device-code(예: `ABCD-1234`)를 자동으로 열린 브라우저에 입력 + HQ 계정 로그인
- **Cloudflare 토큰 적용** — 배포 단계(보통 워크숍 3주차)에 발급한 API Token을 환경변수로 등록 (Codespaces 환경 필수, macOS 로컬은 OAuth 가능)
- **기본 정보 제공** — 한의원 이름 등 에이전트가 물어보는 항목에 답변
- **위험한 작업 승인** — 에이전트가 이유를 설명하고 제안하면 확인
---
## 문제 해결
### Claude Code가 오래된 버전일 때 (버그 등)
```
npm install -g @anthropic-ai/claude-code@latest
```
이후 `claude` 재실행.
### Codespace 부팅이 너무 느릴 때
네트워크 재시도. 안 되면 Codespaces → 해당 Codespace → **"Rebuild container"** (삭제 아님, 재빌드).
### 작업 내용이 사라진 것 같을 때
- 에이전트에게 "`git status`, `git log`, `git reflog` 보여줘" 요청
- 로컬 DB 내용이 증발했으면 → 안타깝게도 재입력 필요 (이래서 삭제 금지)
### 설치가 꼬였을 때
무작정 다시 설치하지 마세요. 에이전트에게 이렇게 요청하세요:
> **"설치가 꼬인 것 같아. 현재 상태를 진단하고 이어서 갈지 새로 할지 판단해줘."**
에이전트가 상태를 진단하고 가장 안전한 복구 경로를 제안합니다.
### HQ 응답이 없을 때
워크숍 단톡방에 "HQ 다운" 공지. 강사가 대응합니다.
---
## 관련 콘텐츠
- 📹 **관련 영상**: 커리큘럼 0-3b. [Mac] 로컬 환경에서 시작하기
- 📋 **커리큘럼**: Stage 1 M0에서 다룸
- 🎯 **직원 투어**: 관리자 패널에서 **설정** 투어를 시작하세요
설치가 완료되면 에이전트에게 **"온보딩 시작해"**라고 요청하세요. 한의원 정보 입력부터 홈페이지 구성까지 에이전트가 안내합니다.
- [에이전트와 처음 만나기](/guide#agent-start) — 에이전트 사용법 안내
- [에이전트에게 효과적으로 요청하기](/guide#ai-effective-requests) — 좋은 요청 패턴
- [Cloudflare 셋업 가이드](/guide#cloudflare-setup) — 도메인 연결, 추가 설정