👥 SaaS 팀 온보딩(Onboarding) 가이드 완성편

👥 SaaS 팀 온보딩(Onboarding) 가이드 완성편

– 신입/주니어/외주 개발자가 “하루 만에” 프로젝트에 합류하는 문서 –
(NestJS + Next.js + AI SaaS 실무 기준)

---

솔직히 말해서,
내가 겪어본 프로젝트 중 문서가 제대로 된 팀은 거의 없었다.

“이거 어디 코드야?”
“이건 누가 관리해?”
“왜 이렇게 배포됐는지 아는 사람 있어요?”

그래서 이번 글은 개발을 잘하는 법이 아니라,
팀이 망가지지 않게 하는 법에 가깝다.

이 문서 하나로

• 신입 개발자는 길을 잃지 않고
• 시니어는 같은 설명을 10번 반복하지 않아도 되고
• 외주/프리랜서는 실수 없이 일할 수 있다.

우리가 만든 SaaS 프로젝트 기준으로
실제 회사에서 바로 쓰는 온보딩 문서 템플릿을 완성해보자.

---

🧭 이 문서의 목적

“처음 들어온 사람이
질문하지 않고도
혼자서 개발을 시작할 수 있게 만든다”

이를 위해 온보딩 문서는 아래 순서를 따른다.

1. 프로젝트 전체 이해 (What & Why)
2. 기술 스택과 책임 범위
3. 로컬 개발 환경 세팅
4. 코드 구조 읽는 법
5. 개발/배포 규칙
6. 첫 번째 실습 태스크
7. 자주 터지는 실수 모음

---

1️⃣ 프로젝트 한 줄 요약 (가장 중요)

이 프로젝트는 “AI 기능이 포함된 구독형 SaaS”이며,
NestJS 백엔드와 Next.js 프론트엔드, Stripe 결제,
RAG 기반 AI 검색 기능을 제공한다.

이 문장은 모든 온보딩의 출발점이다.
이걸 이해 못 하면, 아래는 다 의미 없다.

---

2️⃣ 시스템 전체 구조 빠르게 보기

반응형

Frontend (Next.js, Cloudflare Pages)
   ↓ HTTPS
Backend API (NestJS, K8s)
   ├─ Auth / Billing (Stripe)
   ├─ AI / RAG / VectorDB(Qdrant)
   ├─ Redis Cache
   └─ MySQL (Prisma)
Infra
   ├─ GitHub Actions
   ├─ ArgoCD (GitOps)
   ├─ Terraform (IaC)
   └─ Cloudflare (CDN/DNS)

👉 포인트

• 프론트는 “보여주는 역할”
• 백엔드는 “판단과 규칙의 중심”
• 인프라는 “사람 대신 일하는 자동화”

---

3️⃣ 기술 스택 & 책임 범위

📦 기술 스택 요약

영역 기술

Frontend	Next.js (App Router), SWR
Backend	NestJS, Prisma
AI	OpenAI / RAG / Qdrant
Auth	JWT
Billing	Stripe Subscription
Infra	AWS, Cloudflare
CI/CD	GitHub Actions + ArgoCD
Observability	Sentry, Prometheus

---

👤 역할별 책임

프론트엔드

• UI/UX 구현
• API 연동
• 에러 핸들링 (Sentry)
• 인증 상태에 따른 화면 분기

백엔드

• 비즈니스 로직
• 인증/권한
• AI 호출 제한
• Stripe Webhook 처리

인프라

• 배포 자동화
• 장애 대응
• 모니터링/알림

---

4️⃣ 로컬 개발 환경 세팅 (진짜 중요)

1. 필수 설치

node >= 20
docker
docker-compose

---

2. 프로젝트 실행

git clone https://github.com/your-org/saas-project
cd saas-project

# 백엔드
cd backend
cp .env.example .env
docker compose up -d

# 프론트엔드
cd ../frontend
npm install
npm run dev

👉 접속

• 프론트: http://localhost:3000
• 백엔드: http://localhost:3001
• Swagger: http://localhost:3001/docs

---

3. 환경변수 주의사항

• 절대 커밋 금지
• .env는 개인별로 다름
• Stripe / OpenAI 키는 회사에서 지급

OPENAI_API_KEY=xxxx
STRIPE_SECRET_KEY=xxxx
DATABASE_URL=mysql://...

---

5️⃣ 코드 구조 읽는 법 (길 잃지 않기)

Backend (NestJS)

src/
 ├─ auth/        # 로그인, JWT
 ├─ billing/     # Stripe, 구독
 ├─ ai/          # LLM, RAG
 ├─ user/        # 사용자 도메인
 ├─ common/      # Guard, Filter
 └─ main.ts

👉 규칙

• 컨트롤러는 얇게
• 비즈니스 로직은 Service
• 공통 로직은 common

---

Frontend (Next.js)

app/
 ├─ (auth)/login
 ├─ (billing)/pricing
 ├─ dashboard/
 └─ api/

👉 규칙

• 페이지 = 사용자 행동 단위
• API 호출은 한 곳에서 관리
• 상태는 SWR 기준

---

6️⃣ 개발 & 커밋 규칙

브랜치 전략

main        → 운영
develop     → 통합
feature/*   → 기능 개발
hotfix/*    → 긴급 수정

---

커밋 메시지 규칙

feat: AI 검색 결과 캐시 추가
fix: Stripe webhook 중복 처리 수정
refactor: Auth Guard 구조 정리

커밋 메시지는 나중의 나에게 쓰는 메모다.

---

7️⃣ 배포 흐름 (건들지 말아야 할 것)

1. main 브랜치 push
2. GitHub Actions 실행
3. Docker 이미지 빌드
4. ArgoCD 자동 배포
5. Slack 알림

👉 주의

• 서버에 직접 SSH 접속 ❌
• 운영 DB 직접 수정 ❌
• ArgoCD 상태 이상 시 즉시 공유

---

8️⃣ 첫 번째 실습 태스크 (신입용)

미션: “AI 요청 히스토리 API 만들기”

요구사항

• 로그인 유저 기준
• 최근 AI 요청 10개 조회
• 관리자만 전체 조회 가능

힌트

• AiUsage 테이블 사용
• Guard로 role 체크
• Swagger에 문서화

👉 이 미션을 끝내면
프로젝트 구조 70%를 이해한 상태가 된다.

---

9️⃣ 자주 터지는 실수 TOP 5

1. AI 호출 제한 Guard 안 거치고 호출
2. Stripe Webhook 로컬 테스트 안 함
3. env 값 잘못 설정
4. Redis 캐시 무효화 누락
5. ArgoCD 상태 무시하고 배포

👉 이 5개만 피해도
“신입 티”는 바로 벗는다.

---

🎯 이 온보딩 문서의 진짜 목적

이 문서는

• 친절하려고 만든 게 아니다
• 완벽하려고 만든 것도 아니다

“팀의 시간을 아끼기 위해” 만든 문서다.

질문이 줄어들고
실수가 줄어들고
개발 속도가 눈에 띄게 빨라진다.

---

✅ 온보딩 체크리스트 (마지막)

• 로컬 환경 실행 완료
• Swagger에서 API 호출 성공
• Stripe 테스트 결제 이해
• AI Guard 로직 이해
• 첫 실습 태스크 완료

여기까지 왔다면,
당신은 이제 이 팀의 개발자다.

---

 

온보딩문서, 개발자온보딩, SaaS팀, NestJS, Next.js, DevOps, 팀문화, 기술문서, 스타트업개발, 백엔드온보딩

---