# 에이전트와 함께 일하는 흐름을 이해하려면
Clinic-OS를 시작한 순간, 원장님에게는 **AI 에이전트 파트너**가 생겼습니다. 이 에이전트는 코드를 쓰고, 데이터를 관리하고, 홈페이지를 업데이트합니다. 원장님은 "뭘 하고 싶은가"를 말하면 됩니다.
이 가이드는 **에이전트와의 협업이 실제로 어떻게 돌아가는지** — 전체 그림을 보여줍니다.
---
## 핵심 구조: 코어와 내 영역의 분리
Clinic-OS는 **코어 코드**(본부에서 관리)와 **내 영역**(원장님의 데이터와 커스터마이징)을 분리합니다. 이 구조 덕분에 본부의 업데이트를 받으면서도 내 설정은 안전하게 보존됩니다.
```
┌────────────────────────────────────────┐
│ Clinic-OS 본부 (HQ) │
│ │
│ 새 기능 개발 → 코어 업데이트 배포 │
│ ↓ │
└───────────────┼────────────────────────┘
▼
┌────────────────────────────────────────┐
│ 내 한의원 │
│ │
│ 코어 영역 (업데이트 대상) │
│ └── 기능, 페이지, DB 스키마, 스킬 │
│ │
│ 내 영역 (절대 덮어쓰지 않음) │
│ ├── 환경 설정 (.env) │
│ ├── 배포 설정 (wrangler.toml) │
│ ├── 경영 데이터 (DB) │
│ ├── 커스텀 페이지 (_local/) │
│ └── 플러그인 (plugins/local/) │
└────────────────────────────────────────┘
```
**핵심**: 코어를 업데이트해도 내 데이터, 설정, 커스터마이징은 안전합니다.
---
## 코어 업데이트 받기
에이전트에게 간단히 요청합니다:
```
코어를 최신 버전으로 업데이트해줘
```
에이전트가 자동으로:
1. 최신 코어 버전 확인
2. 새 코드 다운로드
3. 의존성 설치
4. DB 마이그레이션 적용 (새 테이블, 새 필드)
5. 테스트 실행
> 코어 업데이트에는 **새 스킬**이 포함될 수 있습니다. 업데이트 후 에이전트가 더 많은 일을 할 수 있게 됩니다.
---
## 내 한의원을 꾸미는 3가지 방법
### 1. 데이터로 커스터마이징 (가장 쉬움)
관리자 화면에서 직접 설정:
- 서비스/프로그램 등록
- 의사 정보 수정
- 캠페인 설정
- 알림 템플릿 수정
**코드를 건드릴 필요가 없습니다.** 에이전트에게 말로 요청해도 됩니다.
### 2. 플러그인으로 기능 추가 (안전)
에이전트에게 새 기능을 요청합니다:
```
포인트 적립 기능 만들어줘.
결제 완료 시 금액의 1% 적립하고, 관리자 페이지에서 내역 볼 수 있게.
```
에이전트가 플러그인 형태로 만들어주며, 코어와 완전히 분리되어 업데이트에 영향을 받지 않습니다.
### 3. 페이지 오버라이드 (고급)
특정 페이지를 완전히 다르게 만들고 싶을 때, `_local/` 폴더에 커스텀 버전을 만듭니다. 코어의 원본 파일은 건드리지 않으면서 내 버전이 우선 적용됩니다.
---
## 에이전트에게 말하는 법
에이전트와의 협업은 **의도를 전달하고 → 결과를 확인하고 → 다시 요청하는** 반복입니다.
| 하고 싶은 일 | 에이전트에게 하는 말 |
|-------------|------------------|
| 코어 업데이트 | "코어를 최신으로 업데이트해줘" |
| 배포 | "배포해줘" |
| DB 문제 해결 | "DB 상태 확인하고 문제 있으면 고쳐줘" |
| 새 기능 | "예약 알림 문자 보내는 기능 만들어줘" |
| 페이지 수정 | "의사 소개 페이지 레이아웃 바꿔줘" |
| 현재 상태 | "지금 시스템 상태 보여줘" |
코드나 명령어를 외울 필요가 없습니다. **뭘 하고 싶은지**만 말하면 됩니다.
---
## 문제가 생겼을 때
### 업데이트 후 에러
대부분 마이그레이션 미적용이 원인입니다:
```
마이그레이션 적용해줘
```
### 내 커스터마이징이 사라졌을 때
코어 영역을 직접 수정한 경우 업데이트 시 덮어쓰일 수 있습니다.
다음번에는 `_local/` 또는 `plugins/local/`에서 작업하세요.
### 이전 버전으로 돌아가고 싶을 때
```
이전 버전으로 롤백해줘
```
---
## 핵심 원칙
- **에이전트는 파트너입니다.** 명령이 아니라, 의도를 전달하세요.
- **코어는 건드리지 마세요.** 데이터 추가 또는 플러그인으로 해결하세요.
- **업데이트를 받으세요.** 새 스킬, 새 기능이 자동으로 추가됩니다.
- **실험은 로컬에서.** 프로덕션에 영향 없이 마음껏 시도하세요.
---
## 관련 콘텐츠
- 📹 **관련 영상**: 커리큘럼 2-2. 콘텐츠 분석 — 우리 한의원의 특징 파악
- 📋 **커리큘럼**: Stage 2 M2에서 다룸
- 🎯 **직원 투어**: 관리자 패널에서 **대시보드** 투어를 시작하세요
- [Clinic-OS란 무엇인가](/guide#overview)
- [관리자 패널 vs 에이전트 — 언제 뭘 쓸까](/guide#when-to-use-what)