Skip to content

AI_SETUP_GUIDE.md

Latest commit

 

History

History
123 lines (93 loc) · 5.83 KB

AI_SETUP_GUIDE.md

File metadata and controls

123 lines (93 loc) · 5.83 KB
Raw

AI 설정 가이드

이 문서는 Basic Website CMS를 세팅하는 AI 코딩 도우미를 위한 안내서입니다.

목표는 모든 기술을 감추는 것이 아닙니다. 사용자가 웹개발자가 아니어도, 자기 사이트가 어떤 부품으로 조립되는지 이해하면서 AI와 함께 진행하게 만드는 것입니다.

제품 의도

Basic Website CMS는 AI-ready 웹사이트 CMS 스타터 키트입니다.

AI는 사용자가 다음 일을 할 수 있도록 도와야 합니다.

  1. GitHub 저장소를 만들거나 복사하기
  2. 로컬 개발 도구 설치 확인하기
  3. Vercel 연결하기
  4. Neon 데이터베이스 만들기
  5. GCP에서 Google OAuth 인증정보 만들기
  6. 로컬과 배포 환경변수 채우기
  7. 프로젝트를 로컬에서 실행하기
  8. 공개 사이트와 관리자 콘솔을 배포하기
  9. 안전한 영역부터 커스터마이즈하기

이 저장소는 단순한 웹사이트 껍데기가 아니라, AI와 함께 웹개발을 진행하기 위한 키트입니다.

먼저 부품을 설명하세요

명령어를 실행하기 전에 네 가지 외부 서비스를 쉬운 말로 설명하세요.

서비스 이렇게 설명하세요
GitHub 코드 창고입니다. 프로젝트 코드와 변경 기록을 보관합니다.
Vercel 포장·배송 센터입니다. GitHub의 코드를 실제 웹사이트로 포장하고 인터넷 주소로 배송합니다.
Neon 데이터 금고입니다. 관리자에 의해 바뀔 수 있는 게시글, 일정, 설정을 안전하게 저장합니다.
GCP / Google OAuth 관리자 출입증 발급소입니다. 관리자 콘솔을 Google 로그인으로 보호하기 위한 출입증을 만듭니다.

이 설명을 대충 넘기지 마세요. 사용자가 “뭔지 모르겠지만 그냥 시키는 대로 클릭했다”는 느낌을 받지 않게 해야 합니다.

AI가 보통 도와줄 수 있는 일

AI는 보통 다음 일을 도울 수 있습니다.

  • Node.js, npm, GitHub CLI, Vercel CLI, Neon CLI, gcloud CLI 설치 여부 확인
  • 필요한 CLI 설치 안내
  • GitHub 저장소 생성 또는 복사
  • 로컬 설치, 타입체크, 빌드 명령 실행
  • GitHub, Vercel, Neon 브라우저 로그인 흐름 안내
  • Vercel 프로젝트 생성 안내
  • Neon 프로젝트와 데이터베이스 생성 안내
  • 환경변수 이름과 위치 설명
  • 로컬 URL과 배포 URL 확인
  • 오류 원인 설명과 다음 행동 제안

사용자가 직접 해야 하는 일

아래 작업은 사용자가 직접 해야 합니다.

  • GitHub, Vercel, Neon, Google 계정 로그인
  • 계정, 팀, 프로젝트 이름 선택
  • 비용이나 과금과 관련될 수 있는 클라우드 리소스 생성 확인
  • Google Cloud Console에서 OAuth 인증정보 만들기
  • 비밀값을 .env.local 또는 Vercel 환경변수에 직접 입력하기
  • 브랜드, 문구, 이미지, 색상, 메뉴, 페이지 이름 결정하기

비밀값을 채팅에 그대로 붙여넣으라고 요구하지 마세요. 가능하면 사용자가 로컬 env 파일이나 서비스 대시보드에 직접 넣게 안내하세요.

권장 설정 순서

  1. AGENTS.md, CLAUDE.md, GEMINI.md, .github/copilot-instructions.md, README.md, 이 문서, AI_RESPONSE_GUIDE.md, FIRST_RUN_CHECKLIST.md, ENVIRONMENT_VARIABLES.md, GOOGLE_OAUTH_SETUP.md, DEPLOYMENT_VERIFICATION.md, SERVICE_SETUP_NOTES.md, CUSTOMIZATION_BOUNDARIES.md, SAFE_CUSTOMIZATION_RECIPES.md를 읽습니다.
  2. git status로 현재 저장소 상태를 확인합니다.
  3. 네 가지 서비스 역할을 쉬운 말로 설명합니다.
  4. 로컬 도구를 확인합니다.
    • node --version
    • npm --version
    • git --version
    • gh --version
    • vercel --version
    • neonctl --version
    • gcloud --version
  5. 로그인 상태를 확인합니다.
    • gh auth status
    • vercel whoami
    • neonctl me --output json
    • gcloud config get-value account
  6. .env.example을 바탕으로 로컬 환경변수를 채웁니다.
  7. 데이터베이스를 준비합니다.
  8. apps/admin과 apps/site를 로컬에서 실행합니다.
  9. Vercel에서 apps/admin, apps/site 프로젝트를 각각 만듭니다.
  10. Vercel production 환경변수를 채웁니다.
  11. 배포하고 실제 URL을 확인합니다.
  12. 그 다음 커스터마이즈를 시작합니다.

각 단계의 자세한 체크리스트는 아래 문서를 따르세요.

  • docs/FIRST_RUN_CHECKLIST.md
  • docs/ENVIRONMENT_VARIABLES.md
  • docs/GOOGLE_OAUTH_SETUP.md
  • docs/DEPLOYMENT_VERIFICATION.md
  • docs/SAFE_CUSTOMIZATION_RECIPES.md

localhost 설명은 로컬 실행 단계에서만

localhost는 로컬 개발을 설명할 때만 소개하세요.

추천 설명:

localhost는 내 컴퓨터 안에서만 열리는 임시 웹사이트 주소입니다. Vercel이 인터넷에 배송하기 전에 미리 테스트할 때 씁니다.

GitHub, Vercel, Neon, GCP를 처음 설명하는 단계에서는 localhost를 먼저 꺼내지 않는 것이 좋습니다. 초심자에게 새 개념이 한꺼번에 너무 많이 들어갑니다.

AI 행동 규칙

  • 행동하기 전에 설명하세요.
  • 작업 계획을 보이게 유지하세요.
  • 의미 있는 단계마다 현재 단계, 사용자가 직접 할 일, 확인 근거, 남은 일을 보고하세요.
  • 표준적인 서비스 흐름을 우선하세요.
  • 사용자가 명확히 요청하지 않는 한 백엔드 구조를 다시 설계하지 마세요.
  • 데이터베이스 스키마를 가볍게 바꾸지 마세요.
  • 인증, 업로드, 캐시, HTML 정화, 보안 헤더를 약화하지 마세요.
  • 큰 UI/UX 변경 전에는 사용자의 의도를 확인하세요.
  • 각 단계는 실제 명령 출력이나 live URL로 확인하세요.
  • 배포가 목표라면 로컬 성공에서 멈추지 마세요.

자세한 말하기 규칙은 docs/AI_RESPONSE_GUIDE.md를 따르세요.