| name | setup-md-edit |
| description | SETUP.md 작성/수정 시 준수할 원칙 — fresh install 기준, Claude Code 실행 지시서 형태 |
| triggers | ["SETUP.md","setup 문서","설정 가이드","설치 가이드","온보딩 문서"] |
SETUP.md 작성/수정 원칙
대상 독자
clone 전 상태의 사용자 — 개발 환경이 구성되어 있지 않거나 레포를 처음 접하는 사람.
절대로 "이미 clone 완료" 또는 "개발자 환경 갖춤" 을 전제하지 말 것.
형식 원칙
SETUP.md는 Claude Code가 top-to-bottom으로 실행하는 지시서 형태여야 한다.
- 각 단계는 Claude Code가 직접 실행 가능한 명령어로 작성
- 사람이 수동으로 편집하거나 복사-붙여넣기해야 하는 단계 금지
- "터미널을 열고 다음을 입력하세요" 같은 수동 안내 금지 — 대신
AskUserQuestion으로 입력 수집 후 자동화
금지 패턴
/Users/username/... 같은 하드코딩된 절대 경로 — 상대 경로 또는 환경변수 사용
- "복사해서 붙여넣기" 단계
- IDE/에디터를 직접 열어 수동으로 편집하라는 지시
- clone 이후를 전제한 "이미 프로젝트 폴더 안에 있다고 가정" 서술
필수 패턴
- 입력이 필요한 값(API 키, 프로젝트명 등)은
AskUserQuestion으로 먼저 수집
- 환경변수는
.env 파일 자동 생성 또는 vercel env pull 등 CLI로 처리
- 각 단계 완료 후 검증 명령어 포함 (예:
pnpm dev 후 http://localhost:3000 응답 확인)
- 멱등성 보장 — 이미 완료된 단계를 다시 실행해도 부작용 없어야 함
작성 순서 검증
SETUP.md 초안 작성 전 반드시 확인:
- "이 문서의 첫 단계를 실행하는 사람은 무엇을 갖고 있는가?" — clone 전인지 후인지
- "각 단계는 Claude Code가 자동으로 실행할 수 있는가?" — 수동 단계 없는지
- "경로나 값이 하드코딩되어 있는가?" — 없어야 함