setup-md-edit

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 초안 작성 전 반드시 확인:

1. "이 문서의 첫 단계를 실행하는 사람은 무엇을 갖고 있는가?" — clone 전인지 후인지
2. "각 단계는 Claude Code가 자동으로 실행할 수 있는가?" — 수동 단계 없는지
3. "경로나 값이 하드코딩되어 있는가?" — 없어야 함