readme-for-developers

# README for Developers **개발자를 위한 README**는 마케팅 문서가 아니라 **'인계인수서'**입니다. 이 문서 하나만 보고도 신규 개발자가 로컬 서버를 띄우고, 코드 흐름을 머릿속에 그릴 수 있어야 합니다. ## Core Principle > **"README = 지도, 디테일은 docs/로 링크"** > > 정보를 한 파일에 다 넣지 말고, README가 전체 지도를 제공하고 세부는 링크로 내려가게 한다. ## README 품질 체크리스트 README만 읽고 새 개발자가 아래 질문에 답할 수 있으면 합격: - [ ] 이 시스템의 **목표/비목표**는? - [ ] 데이터는 어디에 저장되고, **핵심 식별자**는? - [ ] **핵심 플로우 2~3개**는 어떻게 동작하는가? - [ ] **엔트리포인트 파일 3개**는 어디인가? - [ ] 자주 터지는 버그의 **관측 지점**은? - [ ] **CI는 무엇을 어떤 순서로** 강제하는가? - [ ] **배포/롤백**은 어떻게 하는가? - [ ] **로컬 실행 3단계**는? --- ## 필수 섹션 구조 ### 0) New Engineer Fast Path (30분 코스) ```markdown ## 0) New Engineer Fast Path - ✅ 1) 시스템 한 장 요약 → '1) System at a glance' - ✅ 2) 로컬 실행 → '4) Local Dev' - ✅ 3) 핵심 플로우 2개 → '2) Core Flows' - ✅ 4) 디버깅 포인트 → '8) Debugging' - ✅ 5) 첫 작업 가이드 → '10) Working Agreement' ``` ### 1) System at a glance ```markdown ## 1) System at a glance ### What / Why - **목표**: - **비목표** (안 하는 것): - **사용자/고객**: - **성공지표**: ### Architecture (Mermaid 다이어그램 또는 이미지) ### Design Principles (3~5개) - SSOT 우선 - 안전 기본값 - 점진적 로드 - 결정 기록 (ADR) ``` ### 2) Core Flows (핵심 동작 2~3개) ```markdown ## 2) Core Flows ### Flow A: <예: Preview Render> - **입력**: - **처리 단계**: - **출력**: - **주요 코드 위치**: - **자주 터지는 지점**: ### Flow B: <예: Video Export> (동일 포맷) ``` ### 3) Repo Map (폴더 구조) ```markdown ## 3) Repo Map \`\`\` /app # Next.js App Router /src # 소스 코드 /components # 공용 UI 컴포넌트 /features # 기능별 모듈 /lib # 유틸리티 /scripts # 빌드/배포 스크립...