에이전트와 함께 일하는 흐름

에이전트와 함께 일하는 흐름을 이해하려면

Clinic-OS를 시작한 순간, 원장님에게는 AI 에이전트 파트너가 생겼습니다. 이 에이전트는 코드를 쓰고, 데이터를 관리하고, 홈페이지를 업데이트합니다. 원장님은 "뭘 하고 싶은가"를 말하면 됩니다.

이 가이드는 에이전트와의 협업이 실제로 어떻게 돌아가는지 , 전체 그림을 보여줍니다.

핵심 구조: 코어와 내 영역의 분리

Clinic-OS는 코어 코드(본부에서 관리)와 내 영역(원장님의 데이터와 커스터마이징)을 분리합니다. 이 구조 덕분에 본부의 업데이트를 받으면서도 내 설정은 안전하게 보존됩니다.

┌────────────────────────────────────────┐
│           Clinic-OS 본부 (HQ)           │
│                                        │
│   새 기능 개발 → 코어 업데이트 배포       │
│               ↓                        │
└───────────────┼────────────────────────┘
                ▼
┌────────────────────────────────────────┐
│            내 한의원                    │
│                                        │
│   코어 영역 (업데이트 대상)              │
│   └── 기능, 페이지, DB 스키마, 스킬      │
│                                        │
│   내 영역 (업데이트 전 보존 여부 확인)    │
│   ├── 환경 설정 (.env)                  │
│   ├── 배포 설정 (wrangler.toml)         │
│   ├── 경영 데이터 (DB)                  │
│   ├── 커스텀 페이지 (_local/)            │
│   └── 플러그인 (plugins/local/)          │
└────────────────────────────────────────┘

핵심: 코어 업데이트 전에는 내 데이터와 설정, 커스터마이징이 보존되는지 확인하고 복원 지점을 준비합니다.

코어 업데이트 받기

에이전트에게 간단히 요청합니다:

코어를 최신 버전으로 업데이트해줘

에이전트가 자동으로:

최신 코어 버전 확인
새 코드 다운로드
의존성 설치
DB 마이그레이션 적용 (새 테이블, 새 필드)
테스트 실행

코어 업데이트에는 새 스킬이 포함될 수 있습니다. 업데이트 후 에이전트가 더 많은 일을 할 수 있게 됩니다.

내 한의원을 꾸미는 3가지 방법

1. 데이터로 커스터마이징 (가장 쉬움)

관리자 화면에서 직접 설정:

서비스/프로그램 등록
의사 정보 수정
캠페인 설정
알림 템플릿 수정

코드를 건드릴 필요가 없습니다. 에이전트에게 말로 요청해도 됩니다.

2. 플러그인으로 기능 추가 (안전)

에이전트에게 새 기능을 요청합니다:

포인트 적립 기능 만들어줘.
결제 완료 시 금액의 1% 적립하고, 관리자 페이지에서 내역 볼 수 있게.

에이전트가 플러그인 형태로 만들어주며, 코어와 완전히 분리되어 업데이트에 영향을 받지 않습니다.

3. 페이지 오버라이드 (고급)

특정 페이지를 완전히 다르게 만들고 싶을 때, _local/ 폴더에 커스텀 버전을 만듭니다. 코어의 원본 파일은 건드리지 않으면서 내 버전이 우선 적용됩니다.

에이전트에게 말하는 법

에이전트와의 협업은 의도를 전달하고 → 결과를 확인하고 → 다시 요청하는 반복입니다.

하고 싶은 일	에이전트에게 하는 말
코어 업데이트	"코어를 최신으로 업데이트해줘"
배포	"배포해줘"
DB 문제 해결	"DB 상태 확인하고 문제 있으면 고쳐줘"
새 기능	"예약 알림 문자 보내는 기능 만들어줘"
페이지 수정	"의사 소개 페이지 레이아웃 바꿔줘"
현재 상태	"지금 시스템 상태 보여줘"

코드나 명령어를 외울 필요가 없습니다. 뭘 하고 싶은지만 말하면 됩니다.

문제가 생겼을 때

업데이트 후 에러

대부분 마이그레이션 미적용이 원인입니다:

마이그레이션 적용해줘

내 커스터마이징이 사라졌을 때

코어 영역을 직접 수정한 경우 업데이트 시 덮어쓰일 수 있습니다. 다음번에는 _local/ 또는 plugins/local/에서 작업하세요.

이전 버전으로 돌아가고 싶을 때

이전 버전으로 롤백해줘

핵심 원칙

에이전트는 파트너입니다. 명령이 아니라, 의도를 전달하세요.
코어는 건드리지 마세요. 데이터 추가 또는 플러그인으로 해결하세요.
업데이트를 받으세요. 새 스킬, 새 기능이 자동으로 추가됩니다.
실험은 로컬에서. 프로덕션에 영향 없이 마음껏 시도하세요.