diff --git a/.env.example b/.env.example
new file mode 100644
index 0000000..5712b3d
--- /dev/null
+++ b/.env.example
@@ -0,0 +1,16 @@
+# Variet Agent 환경 설정
+# .env.example → .env 로 복사 후 토큰 입력
+
+DISCORD_BOT_TOKEN=여기에_디스코드_봇_토큰_입력
+API_HOST=0.0.0.0
+API_PORT=8000
+
+# Gitea
+GITEA_URL=https://git.variet.net
+GITEA_TOKEN=여기에_Gitea_토큰_입력
+GITEA_REPO=Variet/variet-agent
+
+# Vikunja
+VIKUNJA_URL=https://plan.variet.net
+VIKUNJA_TOKEN=여기에_Vikunja_토큰_입력
+VIKUNJA_PROJECT_ID=7
diff --git a/README.md b/README.md
index 6d8f6ea..2bb3994 100644
--- a/README.md
+++ b/README.md
@@ -24,9 +24,25 @@ sessions/       # 작업 로그
 docs/           # 설계 문서
 ```
 
+## AI Agent Roles
+
+Variet Agent는 세 가지 전문화된 역할을 통해 협업합니다:
+
+- **Planner (`prompts/planner.md`)**: 사용자의 추상적 요청을 분석하여 구체적이고 실행 가능한 태스크들로 분해합니다. 수정이 필요한 파일을 식별하고 작업의 우선순위와 리스크를 평가합니다.
+- **Coder (`prompts/coder.md`)**: Planner가 생성한 태스크와 관련 소스 코드를 바탕으로 실제 변경 사항을 구현합니다. 기존 스타일을 준수하며 완성된 파일 전체를 출력합니다.
+- **Reviewer (`prompts/reviewer.md`)**: 구현된 코드가 요구사항을 충족하는지, 버그나 엣지 케이스는 없는지 검토합니다. 코드 품질을 평가하고 승인(Pass) 여부와 개선 의견을 제시합니다.
+
 ## 환경
 
-- Python 3.12 (`C:\ProgramData\miniforge3\envs\quant`)
+- Python 3.12+
 - Gemini CLI v0.32+ (AI Ultra)
 - Gitea: git.variet.net
 - Vikunja: plan.variet.net/projects/7
+
+## 시작
+
+```bash
+pip install -r requirements.txt
+cp .env.example .env   # 토큰 설정
+python main.py          # API + Discord Bot 실행
+```
diff --git a/docs/design_document.md b/docs/design_document.md
index 60a0751..614db59 100644
--- a/docs/design_document.md
+++ b/docs/design_document.md
@@ -1,6 +1,6 @@
 # AI Agent Team — 최종 설계서
 
-`C:\Users\CafeVariet-GL552VW\Desktop\source_diff`
+
 
 ---
 
@@ -180,7 +180,7 @@ API Server에 `mode` 파라미터:
 ## 5. 디렉토리 구조
 
 ```
-source_diff/
+<project_root>/
 ├── main.py                      # 진입점
 ├── config.py                    # 설정
 ├── requirements.txt             # fastapi, discord.py, httpx, pydantic, rich