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