본문으로 건너뛰기

개발자 온보딩

너홀로프로에 처음 합류하시는 분을 위한 30분 셋업 가이드입니다. 설치 → 로컬 실행 → 코드 탐색 → 핵심 규칙 파악까지 한 번에.

이 문서의 위상

본 문서는 "지금 손에 넣고 할 일" 에 집중합니다. 구체적 파일 경로·함수명·긴급 대응은 리포지토리 루트의 CLAUDE.md 참조. 각 영역의 설계 근거는 제품, 기술 아키텍처, AI 파이프라인.

1. 사전 준비​

도구버전비고
Node.js≥ 20 LTSnvm use 권장
pnpm10.33.0corepack enable 로 자동 고정 (루트 package.json#packageManager)
Firebase CLI최신npm i -g firebase-tools — Cloud Functions 배포·에뮬레이터용
gh최신GitHub CLI — PR 생성
corepack

corepack enable 만 실행해두면 리포지토리 진입 시 자동으로 pnpm 10.33.0 을 사용합니다. 개별 npm i -g pnpm 불필요.

2. 저장소 클론 + 의존성 설치​

gh repo clone hwondev/neohollo-pro
cd neohollo-pro
pnpm install

pnpm install 은 루트 workspace 를 통해 apps/web · apps/ops · apps/docs · packages/* 의존성을 한 번에 설치합니다. functions/ 는 별도 npm workspace 이므로 Cloud Functions 작업 시에만 별개 설치:

cd functions && npm install

3. 환경변수 설정​

apps/web 만 환경변수가 필요합니다 (apps/ops 는 client SDK 만, apps/docs 는 없음).

cp apps/web/.env.example apps/web/.env.local

Firebase 콘솔 · Vertex AI · Resend 등 각 값의 발급처·용도는 환경변수 가이드 참조. 개발 중엔 Firebase 에뮬레이터를 써서 실 프로젝트 건드리지 않기 를 기본으로.

4. 로컬 실행​

# 전체 앱 동시 실행 (포트 3000, 3001, 3002)
pnpm dev

# 개별 앱만
pnpm dev --filter=@neohollo/web      # 포트 3000
pnpm dev --filter=@neohollo/ops       # 포트 3001 (운영팀 콘솔)
pnpm dev --filter=@neohollo/docs      # 포트 3002 (본 사이트)
주소역할
http://localhost:3000메인 서비스 — 변호사 대시보드 + 의뢰인 포털
http://localhost:3001Master Admin 콘솔 (masterAdmins 화이트리스트 필요)
http://localhost:3002본 Docusaurus 문서 사이트

apps/ops 로그인 시 본인 이메일을 Firestore masterAdmins/{email} 에 먼저 등록해야 접근됩니다 (기술 아키텍처 > masterAdmins 컬렉션).

5. 코드 탐색 — 어디에 뭐가 있나​

neohollo-pro/
├── apps/
│   ├── web/               ← 메인 서비스 (대부분의 작업은 여기)
│   │   ├── app/
│   │   │   ├── (auth)/        로그인·회원가입
│   │   │   ├── (setup)/       온보딩 마법사
│   │   │   ├── (workspace)/       변호사 대시보드 (owner/staff)
│   │   │   └── (portal)/      의뢰인 포털 (4자리 접속 코드)
│   │   ├── lib/               재사용 모듈 (firebase, ai, notifications …)
│   │   └── __tests__/         Vitest
│   ├── ops/               ← 운영팀 콘솔 (별도 앱)
│   └── docs/              ← 이 사이트
├── packages/
│   ├── types/             ← 공유 타입 (UserPlan, ServerSession 등)
│   └── ui/                ← 공유 UI 유틸 (cn 등)
└── functions/             ← Cloud Functions (별도 npm workspace)
apps/* 간 import 금지

apps/web ↔ apps/ops ↔ apps/docs 는 서로 참조할 수 없습니다. 각 앱은 독립 배포 단위. 공유가 필요하면 packages/ 로 승격하거나 각 앱에 복제하세요. ESLint 가 강제합니다.

6. 핵심 명령어​

pnpm dev                 # 전체 dev 서버
pnpm build               # 프로덕션 빌드
pnpm lint                # ESLint
pnpm type-check          # TypeScript 검증 (next build 보다 엄격)
pnpm test                # Vitest (web + docs)
pnpm e2e                 # Playwright E2E (web 빌드 후)
pnpm storybook           # Storybook (포트 6006)
PR 푸시 전 루틴

로컬에서 최소 pnpm type-check + pnpm lint + 변경 영역 pnpm test 돌리고 푸시합니다. type-check 는 next build 보다 엄격하므로 Zod 4 · ActionResult discriminated union 등 타입 실수를 먼저 걸러줍니다.

7. 처음 읽어볼 것​

작업 시작 전 다음 4개를 30분 안에 훑어보세요:

  1. CLAUDE.md — 앱 구조·의존 규칙·코딩 규칙·금지사항. 위반 시 pnpm lint 실패. 앱 메타데이터 4곳 + Firestore 동기화 규약도 여기 참조.
  2. AI 파이프라인 — 새 AI 기능 추가할 때 필수. (A) 자동 갱신형 vs (B) 사용자 트리거형 구분.
  3. 데이터 모델 — Firestore 컬렉션 구조, 경로 기반 멀티테넌시.

8. 첫 PR 체크리스트​

  • feature 브랜치 (feat/ · fix/ · refactor/ · docs/ · chore/) — main 직접 push 금지
  • Conventional Commits (feat: · fix: · ...)
  • 작업 단위별 PR 분리 — 한 PR 에 섞지 말기
  • pnpm type-check + pnpm lint 통과
  • UI 수정 시 Storybook · E2E 동기화
  • CLAUDE.md / docs 규칙 위반 없음 (리뷰어가 확인)

9. 막히면​

  • Firebase 에뮬레이터 이상: firebase emulators:start 포트 충돌 확인, .firebaserc 프로젝트 매핑 확인
  • Custom Claims 반영 안 됨: 브라우저 강제 로그아웃 → 재로그인으로 토큰 갱신
  • Firestore Rules 차단: 에뮬레이터 Rules 탭에서 쿼리 로그 확인
  • CSP 위반: apps/web/lib/security/csp-headers.ts 의 getCspDirectives() 에만 추가. 테스트는 apps/web/__tests__/next-config-headers.test.ts.

그래도 해결 안 되면 팀 채널에 파일 경로 + 증상 + 시도한 것 3줄로 공유.