# 에이전트 요청과 문서 참조 규칙
좋은 요청은 “명령어”가 아니라 **의도, 현재 상태, 원하는 결과**를 전달합니다.
Clinic-OS에서는 특히 이 점이 중요합니다. 같은 "`npm run ...`"이라도 설치본 상태에 따라 정답이 달라지기 때문입니다.
---
## 먼저 기억할 원칙
### 1. 명령어보다 목적을 말하세요
좋은 예:
```text
설치 상태를 진단하고, 지금 가장 안전한 경로로 진행해줘.
```
좋지 않은 예:
```text
npm run setup 쳐봐
```
### 2. 관리자 반영 문제는 "데이터 흐름"까지 같이 말하세요
좋은 예:
```text
관리자에서 바꾼 병원 전화번호가 퍼블릭 푸터와 SEO에는 예전 값으로 남아 있어.
저장 위치와 퍼블릭 반영 경로를 같이 확인해줘.
```
### 3. 복원/업데이트 문제는 예전 폴더나 백업 존재 여부를 알려주세요
좋은 예:
```text
새 스타터킷을 받으면서 예전 설치본 폴더가 다른 이름으로 남아 있어.
신규 설치 후 이관이 맞는지, 복원할 항목이 뭔지 먼저 판단해줘.
```
---
## 에이전트가 먼저 읽어야 하는 문서
Clinic-OS는 에이전트가 읽을 문맥이 정리돼 있습니다.
기본 순서:
1. `CLAUDE.md`
2. `.agent/runtime-context.json`
3. `.agent/manifests/change-strategy.json`
4. `.agent/manifests/local-workspaces.json`
5. `.agent/manifests/admin-public-bindings.json`
6. `.agent/manifests/command-safety.json`
7. `.agent/manifests/lifecycle-scenarios.json`
설치/업데이트/복원 문제라면 이어서:
- `npm run agent:doctor -- --json`
- `npm run agent:lifecycle -- --json`
- 필요 시 `npm run agent:restore -- --dry-run --json`
즉, 좋은 에이전트는 답하기 전에 **레포를 먼저 읽고 현재 상태를 구조화**합니다.
---
## 권장 에이전트
| 유형 | 권장 |
|------|------|
| 기본 추천 | **Claude Code** |
중요한 것은 다음 네 가지입니다.
- 프로젝트 파일을 읽을 수 있는가
- 터미널 명령을 실행할 수 있는가
- diff와 검증 결과를 설명할 수 있는가
- 위험한 작업은 먼저 제안하는가
---
## 요청 패턴 예시
### 설치/업데이트
```text
이 프로젝트 상태를 먼저 진단하고,
신규 설치 / 설치 재개 / 인플레이스 업데이트 / 신규 재설치 이관 중 어디인지 판단해줘.
안전한 명령은 직접 실행하고, 위험한 작업은 이유를 설명하고 제안해줘.
```
### 관리자 변경이 퍼블릭에 안 먹을 때
```text
관리자에서 수정한 값이 퍼블릭 페이지에 반영되지 않아.
저장 위치, 로더, 퍼블릭 소비 경로를 먼저 확인하고
로컬 수정인지 중앙 패치인지 판단해줘.
```
### 디자인/기능 작업
```text
이 요청이 관리자 화면으로 가능한지 먼저 보고,
코드 수정이 필요하면 안전한 경로에서 작업해줘.
작업 후 로컬 검증까지 해줘.
```
### 스킨 작업
```text
우리 사이트를 더 차분한 회복형 분위기로 바꾸고 싶어.
스킨 팩 경로로 진행하고, 코어 프리셋 중 가까운 기반을 골라
skin:create -> skin:check -> /admin/design preview -> 실제 퍼블릭 확인 순서로 진행해줘.
```
### 복원/마이그레이션
```text
예전 설치본이 다른 폴더로 남아 있어.
복원 가능한 코드 local 수정본, 이미지, data, 로컬 R2, DB 백업이 무엇인지 먼저 정리해줘.
DB는 자동으로 덮어쓰지 말고 선택지로 제안해줘.
```
### 배포
```text
배포 전에 설치 상태, 버전, 배포 대상 드리프트를 먼저 확인해줘.
문제 없으면 로컬 검증 후 배포까지 진행하고, 위험하면 이유를 설명해줘.
```
---
## 피해야 할 요청
| 좋지 않은 요청 | 이유 | 더 좋은 요청 |
|---------------|------|-------------|
| "`npm run setup` 쳐" | 상태 진단 없이 특정 명령 고정 | "설치 상태를 보고 가장 안전한 경로로 진행해줘" |
| "DB에 직접 넣어" | 설치본/권한/반영 계약을 깨뜨릴 수 있음 | "관리자/API/로컬 데이터 중 어디서 처리할지 먼저 판단해줘" |
| "코어 파일 바로 수정해" | 다음 업데이트 때 유실될 수 있음 | "로컬 수정인지 중앙 패치인지 먼저 판단해줘" |
| "그냥 최신화해" | 구형 설치본은 재설치 이관이 더 안전할 수 있음 | "업데이트 가능한 상태인지 먼저 봐줘" |
---
## 에이전트에게 기대해야 하는 답변
좋은 에이전트 답변은 보통 아래 순서를 따릅니다.
1. 현재 상태 요약
2. 어떤 경로로 해결할지 판단
3. 직접 실행할 것과 제안할 것을 구분
4. 변경 후 검증 결과 보고
예:
```text
현재 설치본은 구형이라 인플레이스 업데이트보다 신규 설치 후 이관이 안전합니다.
자동 백업 후보 3개를 찾았고, local 코드/이미지/data는 복원 계획에 포함할 수 있습니다.
DB는 자동 덮어쓰지 않고 별도 옵션으로 제안하겠습니다.
```
---
## 요약
- 명령어보다 목적을 말하세요.
- 에이전트가 먼저 레포와 문맥을 읽게 하세요.
- 안전한 명령은 에이전트가 직접 실행해야 합니다.
- 위험한 작업은 이유와 영향이 같이 설명되어야 합니다.
다음으로는 [에이전트 드리븐 시작하기](/guide#vibe-start)와 [배포 워크플로](/guide#deployment-workflow)를 함께 읽는 것을 권장합니다.
---
## 관련 콘텐츠
- 📹 **관련 영상**: 커리큘럼 0-7. 에이전트에게 말하는 법
- 📋 **커리큘럼**: Stage 1 M0에서 다룸