로컬 실행, 테스트, 구조 이해를 위한 개발자 문서 허브입니다. 루트 README.md는 제품 개요이고, 세부 절차는 이 디렉터리에 있습니다.
- 처음 작업할 때: project-map.md에서 source of truth 우선순위, 코드 지형, 변경 유형별 읽는 순서, 검증 선택표를 봅니다.
- 새로 합류했을 때: new-developer-onboarding-guide.md에서 제품 표면, 저장소 구조, frontend/BFF/backend/DB/Redis/Kafka 흐름을 한 번에 봅니다.
- risk evidence 선택: acceptance-matrix.md에서 selected row와 인접 high-risk 제외 사유를 고르고 handoff에 남깁니다.
- 여러 표면을 함께 바꿀 때: frontend, BFF, server API, auth, persistence, public-safety가 겹치면 vertical-slice-checklist.md로 범위를 먼저 정합니다.
- 경계의 기준: frontend route-first 경계, 멀티 클럽 context, 서버 내부 구조, Optional Redis 계층, 세션 lifecycle과 공개 범위, 피드백 문서 흐름, 세션 기록 JSON 가져오기, AI-assisted 콘텐츠 운영, 이메일 알림과 호스트 운영은 모두 architecture.md의 같은 이름 섹션이 기준입니다.
- UI 품질 증거: Lighthouse diagnostic은 public/member/host/admin dev-seed route의 비차단 baseline입니다. 시각 회귀는 props만으로 검증할 수 있는 route-critical UI 조각을 Docker renderer baseline으로 관리합니다. 명령은 test-guide.md에 있습니다.
- 기술 선택 배경: technical-decisions.md와 adr/README.md를 봅니다.
- 버전: 제품 버전은 Git tag
vMAJOR.MINOR.PATCH하나입니다. 기준은 versioning.md입니다. - 작업 규칙: full source checkout에 repository-local contributor guidance가 있으면 먼저 확인합니다. 공개 artifact에서는 이 문서와 실제 코드·테스트·scripts로 표면과 검증을 고릅니다.
- 과거 기록:
docs/superpowers와docs/reports는 과거 기록입니다. 현재 동작 기준은 이 디렉터리와 코드, 테스트, 배포 스크립트입니다.
- 개발 문서는 한국어가 기본입니다. 명령어, 경로, 환경 변수, API path, 기술명은 코드 표기를 그대로 씁니다.
- 운영 secret, 실제 멤버 데이터, DB dump, 배포 상태, 로컬 절대 경로는 넣지 않습니다.
- 직접 backend/API origin 예시는
https://api.example.com같은 placeholder만 씁니다. - 배포 상세 runbook은
docs/deploy에 두고, 여기서는 개발자가 알아야 할 연결점만 다룹니다.
- 코드, 설정, 테스트, 스크립트와 맞는 사실만 현재 동작으로 씁니다.
docs/superpowers의 과거 계획은 맥락으로만 보고 현재 기준으로 올리지 않습니다.- 배포, public release, secret 처리를 설명하면 관련
docs/deploy와scripts/README.md도 함께 확인합니다. - 바꾼 문서에
git diff --check -- <changed-docs>를 실행하고, targeted safety scan이나 공개 릴리즈 후보 점검을 했는지 적습니다.