수정 경로와 가드레일

# 수정 경로와 가드레일 에이전트와 작업을 시작할 때 가장 걱정되는 것: **"내가 뭘 잘못 건드려서 시스템이 망가지면 어떡하지?"** ClinicOS는 **레이어(층)** 구조로 나뉩니다. 어느 층을 바꾸는지 알면 필요한 확인 수준도 함께 정할 수 있습니다. --- ## 건물 비유로 이해하기 ``` ┌─────────────────────────────────────────┐ │ 가건물 (플러그인) │ ← 옆에 붙이는 별채 │ 본관과 분리해 영향을 좁히는 구조 │ ├─────────────────────────────────────────┤ │ 가구 배치 (데이터) │ ← 인테리어 │ 소파 옮기고 커튼 바꾸는 건 자유 │ ├─────────────────────────────────────────┤ │ 콘크리트 구조 (코어 코드) │ ← 기둥, 벽, 배관 │ 건드리면 건물이 흔들릴 수 있음 │ └─────────────────────────────────────────┘ ``` --- ## 레이어 1: 콘크리트 구조 (코어 코드) 건물의 기둥, 벽, 배관 같은 것들. 없으면 건물 자체가 안 서는 핵심 구조물입니다. ### Clinic-OS에서는 - `src/pages/api/` - 핵심 API 로직 - `src/lib/` - 공통 유틸리티 - `migrations/` - 데이터베이스 스키마 - 인증/권한 관련 코드 ### 하지 마세요 | 행동 | 이유 | |------|------| | 기존 테이블 컬럼 삭제/수정 | 기존 데이터가 깨짐 | | API 응답 형식 변경 | 프론트엔드가 깨짐 | | 인증 로직 수정 | 보안 문제 발생 가능 | ### 꼭 필요하다면? AI에게 먼저 **대안이 있는지** 물어보세요: ``` 코어 코드 수정이 필요한 것 같아요. 현재 이런 상황인데, 다른 방법은 없을까요? [상황 설명] ``` 대부분 데이터나 플러그인 레이어에서 해결됩니다. --- ## 레이어 2: 가구 배치 (데이터) 건물 안의 가구, 커튼, 인테리어 소품에 가깝습니다. 코어 코드보다 영향 범위가 좁지만, 예약·가격처럼 운영에 연결되는 값은 변경 전후를 확인해야 합니다. ### Clinic-OS에서는 - 상품/서비스 등록 - 직원/의사 정보 - 프로모션/캠페인 설정 - 알림 템플릿 수정 - 운영 시간 변경 ### 해도 되는 것 | 행동 | 안심 포인트 | |------|------------| | 새 상품 추가 | 기존 상품 노출과 충돌하는지 확인 | | 가격 수정 | 과거 결제 기록과 표시 가격을 함께 확인 | | 템플릿 문구 수정 | 미리보기와 실제 발송 대상을 확인 | | 스케줄 변경 | 기존 예약과 충돌하는지 확인 | --- ## 레이어 3: 가건물 (플러그인) 본관 옆에 짓는 별채, 컨테이너, 창고 같은 것들입니다. 코어와 분리해 영향 범위를 줄이지만, 데이터와 공용 화면을 연결하는 플러그인은 테스트가 필요합니다. ### Clinic-OS에서는 - `src/plugins/` 폴더의 모든 것 - 플러그인 전용 테이블 (`custom_` 접두사) - 플러그인 API (`/api/hub/{plugin}/`) - 플러그인 페이지 (`/admin/hub/{plugin}/`) ### 해도 되는 것 | 행동 | 안심 포인트 | |------|------------| | 플러그인 설치/삭제 | 연결 화면과 데이터 의존성 확인 | | 플러그인 코드 수정 | 해당 기능과 공용 화면을 함께 테스트 | | custom_ 테이블 추가 | 코어 테이블과 분리해 관리 | | 플러그인 API 추가 | `/api/hub/` 경로와 권한을 확인 | --- ## 실전 의사결정 플로우 새 기능이 필요할 때, 이 순서로 생각하세요: ``` 1. 데이터만 추가하면 되나요? YES → 관리자 화면에서 설정 (가장 안전) 2. 별도 기능/화면이 필요한가요? YES → 플러그인으로 구현 (안전) 3. 코어 로직 수정이 꼭 필요한가요? YES → AI에게 대안 먼저 질문 (신중하게) ``` --- ## 레이어별 요청 예시 ### 데이터 레이어 (가구) ``` 신규 서비스 "두피 케어 패키지"를 추가하고 싶어요. 가격은 150,000원이고, 시술 시간은 60분입니다. ``` ### 플러그인 레이어 (가건물) ``` 고객 리뷰 관리 기능을 추가하고 싶어요. - 시술 후 3일 뒤 자동으로 리뷰 요청 문자 발송 - 리뷰 작성하면 포인트 적립 - 관리자가 리뷰 목록을 볼 수 있는 페이지 기존 코드는 건드리지 않고 플러그인 형태로 만들어주세요. ``` --- ## 요약 | 레이어 | 위험도 | 비유 | 접근 방법 | |-------|-------|------|----------| | 코어 코드 | 높음 | 콘크리트 | 먼저 대안 검토 | | 데이터 | 비교적 낮음 | 가구 | 변경 전후 확인 | | 플러그인 | 비교적 낮음 | 가건물 | 미리보기와 테스트 후 적용 | **"어디까지 확인해야 하지?"**가 핵심입니다. 데이터와 플러그인으로 영향 범위를 좁히고, 미리보기·백업·테스트를 거쳐 적용하세요. --- ## 관련 콘텐츠 - 🎯 **직원 투어**: 관리자 패널에서 **설정** 투어를 시작하세요 - [백업과 이력 관리](/guides/agent-history) - [플러그인 확장하기](/guides/agent-plugins)

수정 경로와 가드레일

이 페이지에서 확인할 내용