diff --git a/MANUAL.md b/MANUAL.md
new file mode 100644
index 0000000..7a1a93b
--- /dev/null
+++ b/MANUAL.md
@@ -0,0 +1,173 @@
+# 개발환경 사용 매뉴얼 (Coder)
+
+사내 개발은 **Coder**(웹 기반 개발 워크스페이스)에서 합니다. 브라우저만 있으면 됩니다.
+DB·MinIO·AI(LiteLLM)·Git(Gitea)·배포(Coolify)가 미리 연결돼 있어, 로그인 후 바로 코딩할 수 있습니다.
+
+---
+
+## 0. 준비물
+- 사내망에서 접속 가능한 브라우저 (Chrome/Edge 권장)
+- 본인 사번
+
+---
+
+## 1. Coder 로그인
+
+1. 브라우저에서 **https://coder.bokdev.in** 접속
+2. 로그인
+   - **Username**: 본인 사번 (예: `0310700`)
+   - **Password**: `bok1234!!` + 본인 사번 (예: `bok1234!!0310700`)
+   - > 최초 로그인 후 비밀번호를 바꾸는 것을 권장합니다. (우측 상단 계정 메뉴 → Account)
+
+---
+
+## 2. 워크스페이스 만들기 (최초 1회)
+
+워크스페이스 = 본인 전용 개발용 컨테이너(VS Code + 각종 도구가 깔린 PC).
+
+1. 로그인하면 **Workspaces** 화면. **`Create Workspace`** 클릭 (또는 **Templates → `aidev`** 선택)
+2. 설정값 입력
+   - **Name**: 워크스페이스 이름 (예: `ws-aidev-<사번>` 또는 자유롭게)
+   - **CPU / Memory / Home disk size**: 기본값(2 Core / 4 GiB / 10 GiB)으로 두면 됩니다. 필요하면 나중에 늘릴 수 있습니다.
+3. **`Create Workspace`** 클릭
+4. 워크스페이스가 빌드됩니다 (**처음엔 이미지 다운로드로 2~5분** 걸릴 수 있습니다. 기다리세요).
+   - 상태가 **Running** 이 되면 준비 완료.
+
+> 한 번 만들면 계속 재사용합니다. 다음부터는 만들 필요 없이 **Start** 만 누르면 됩니다.
+
+---
+
+## 3. VS Code 열기
+
+1. 워크스페이스 화면에서 **`VS Code Web`** 버튼 클릭
+2. 브라우저에 VS Code가 열리고, 자동으로 **`/home/coder/projects`** 폴더가 열립니다.
+3. 그 안에 **`starter`** 폴더가 이미 있습니다 — 표준 프로젝트 골격입니다.
+
+> 작업 파일은 반드시 **`/home/coder/projects`** 아래에 두세요. 이 폴더만 영구 보존됩니다.
+> (워크스페이스를 stop/재시작해도 유지. 그 밖의 위치는 사라질 수 있습니다.)
+
+---
+
+## 4. 미리 연결된 것들 (별도 설정 불필요)
+
+새 워크스페이스에는 아래가 자동으로 준비돼 있습니다.
+
+| 항목 | 내용 |
+|---|---|
+| **개발 도구** | Java(JDK)/Maven, Node 22, Python 3.12, git, psql |
+| **컨테이너** | `podman` (그리고 `docker` 명령도 동일하게 동작 — podman 별칭) |
+| **DB** | 본인 전용 Postgres 스키마에 자동 연결 (`$DATABASE_URL`) |
+| **VS Code 확장** | Claude Code, Codex (이미 설치됨) |
+| **AI CLI** | `claude`, `codex`, `gemini` (LiteLLM 게이트웨이 연동, 아래 5번 참고) |
+
+---
+
+## 5. AI 에이전트 사용 설정 (최초 1회) — LiteLLM 키 입력
+
+Claude Code / Codex / Gemini 가 사내 AI 게이트웨이를 쓰려면 **본인 LiteLLM virtual key**가 필요합니다.
+키는 **한 곳에만** 넣으면 모든 도구(CLI·확장)가 공유합니다.
+
+1. 터미널 열기: VS Code 상단 메뉴 **Terminal → New Terminal**
+2. 발급받은 본인 키를 아래처럼 한 줄 넣기 (`sk-...` 부분을 본인 키로):
+   ```bash
+   echo 'sk-여기에-본인-LiteLLM-키' > ~/.config/litellm/key
+   ```
+3. 적용을 위해 터미널을 새로 엽니다 (또는 `source ~/.bashrc`).
+4. 확인:
+   ```bash
+   echo $ANTHROPIC_BASE_URL   # https://litellm.bok.or.kr 가 나오면 정상
+   claude                     # Claude Code CLI 실행
+   ```
+
+> 키는 본인 워크스페이스 안에만 저장되고, 코드/깃에는 올라가지 않습니다.
+> 게이트웨이 주소(`https://litellm.bok.or.kr`)는 이미 설정돼 있으니 건드릴 필요 없습니다.
+
+---
+
+## 6. Git(Gitea) 사용 — 최초 1회 승인
+
+코드 저장소는 사내 **Gitea**(https://gitea.bokdev.in)입니다. 토큰 입력 없이 자동 인증됩니다.
+
+1. 터미널에서 처음 `git clone` / `git push` 등을 하면, **Gitea 승인 화면**으로 안내됩니다.
+   - 또는 Coder 화면의 **`Gitea`** external auth 항목에서 **Authorize** 를 미리 눌러도 됩니다.
+2. 한 번 **Authorize(승인)** 하면, 이후로는 비밀번호 입력 없이 clone/push 가 됩니다.
+
+예:
+```bash
+cd ~/projects
+git clone https://gitea.bokdev.in/<org>/<repo>.git
+```
+
+---
+
+## 7. 표준 프로젝트로 개발 시작하기 (starter)
+
+`~/projects/starter` 는 바로 돌려볼 수 있는 Node 예제입니다.
+
+```bash
+cd ~/projects/starter
+npm install
+npm run dev            # http://localhost:3000 에서 실행
+```
+동작 확인 엔드포인트:
+- `GET /healthz` — 살아있는지
+- `GET /db` — 내 DB(Postgres) 연결 확인
+- `GET /s3` — MinIO(파일 저장소) 연결 확인
+
+> MinIO 키는 `starter/.env` 에 이미 채워져 있습니다.
+> 새 프로젝트는 이 starter를 복사하거나, 같은 구조(Dockerfile + .env)를 따르면 배포까지 매끄럽습니다.
+
+### 내 DB 직접 접속
+```bash
+psql "$DATABASE_URL"      # 본인 전용 스키마로 바로 접속됨
+```
+
+---
+
+## 8. 컨테이너로 실행 (podman)
+
+로컬에서 컨테이너로 돌려보기 (실제 런타임은 rootless podman, `docker` 명령도 동일):
+```bash
+cd ~/projects/starter
+podman build -t myapp .
+podman run --rm -p 3000:3000 --env-file .env -e DATABASE_URL="$DATABASE_URL" myapp
+# 또는
+podman compose up --build
+```
+
+---
+
+## 9. 배포하기 (Coolify)
+
+운영 배포는 **Coolify**가 담당합니다. 흐름은 "**Gitea에 push → Coolify가 Dockerfile로 자동 빌드·배포**" 입니다.
+
+1. 프로젝트를 Gitea repo에 push (위 6번 인증 후 `git push`).
+2. **Coolify**(https://coolify.bokdev.in) 로그인.
+3. 새 리소스 생성 → **Git 기반(해당 Gitea repo 연결)** → 빌드 방식 **Dockerfile**.
+4. Coolify의 **Environment Variables** 에 앱이 쓰는 값 입력
+   - `DATABASE_URL`, `S3_ENDPOINT`, `S3_BUCKET`, `S3_ACCESS_KEY_ID`, `S3_SECRET_ACCESS_KEY` 등
+   - (로컬 `.env`에 있던 키들과 동일하게)
+5. 배포(Deploy). 이후 push 하면 자동 재배포됩니다.
+
+> 컨테이너 포트는 `3000` 입니다. Coolify에서 도메인/포트를 매핑하세요.
+
+---
+
+## 10. 워크스페이스 켜고 끄기
+
+- **그만 쓸 때**: Coder 워크스페이스 화면 → **Stop** (자원 절약. 파일은 보존됩니다.)
+- **다시 쓸 때**: **Start** (수십 초 내 기동)
+- **업데이트 안내가 뜨면**(`Update` 버튼): 눌러서 최신 환경으로 갱신하세요. `~/projects` 파일은 유지됩니다.
+
+---
+
+## 자주 묻는 것
+- **Q. 파일이 사라졌어요** → `~/projects` 밖에 저장했을 가능성. 작업물은 항상 `~/projects` 아래에.
+- **Q. AI 도구가 인증 오류** → `~/.config/litellm/key` 에 본인 키가 들어있는지, 터미널을 새로 열었는지 확인 (5번).
+- **Q. git push가 인증을 물어봐요** → Gitea Authorize를 한 번도 안 했을 때. 6번 참고.
+- **Q. DB가 비어있어요** → 정상입니다. 본인 전용 빈 스키마가 제공됩니다. 테이블은 직접 만들면 됩니다.
+- **Q. K8s(쿠버네티스)는 어떻게 봐요?** → 직원은 K8s에 직접 접근하지 않습니다. DB/스토리지/배포는 위 도구들로 충분합니다.
+
+---
+
+문의: 인프라 담당자