본문으로 건너뛰기

신규 개발자 onboarding

GenD 코드에 기여하려는 신규 개발자용 종합 가이드. 사용자/평가자용 10분 퀵스타트 와 별개.

1. 사전 요구사항​

도구버전비고
macOS / Linux—Apple Silicon (ARM64) 지원
Python3.12+API 백엔드
Node20+UI 빌드
pnpm9+UI 패키지 매니저 (npm/yarn 금지)
Docker20+Kind 클러스터 + 이미지 빌드
kind0.20+로컬 Kubernetes
kubectl1.31+K8s 클라이언트
helm3.14+차트 배포
jq1.6+JSON 처리 (스크립트)
gh CLI2.40+PR / 이슈 자동화 (선택)
az CLI최신AKS prod 접속 (선택, 권한자 한정)

설치 (macOS):

brew install python@3.12 node@20 pnpm docker kind kubectl helm jq gh
# AKS 접근 권한자만:
brew install azure-cli

2. 로컬 환경 셋업 (15분)​

2.1 repo clone + 의존성​

git clone https://github.com/genonai/DataX.git
cd DataX

# API
cd apps/api
python3.12 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

# UI
cd ../../ui
pnpm install

2.2 Kind 클러스터 + seed​

# 루트 디렉토리(DataX)로 이동 — 2.1 에서 ui/ 로 이동한 상태
cd ..

# 1) Kind 클러스터 + 전체 스택 생성 (최초 1회)
bash infra/scripts/00-setup-all.sh
# 2) 클러스터가 Running 이면 데모 데이터 시드 (Bronze 소스 + Medallion 백필)
make seed-demo

make seed-demo 는 실행 중인 클러스터에만 시드한다 (클러스터를 생성하지 않음). 클러스터 생성은 infra/scripts/00-setup-all.sh (→ 01-create-cluster.sh).

기대 결과 — Kind 클러스터 gend-local + namespace gend 에 Trino / PostgreSQL / Keycloak / Vault / SeaweedFS / gend-api / gend-ui Pod 모두 Running.

2.3 로컬 실행 (선택)​

Kind cluster 의 gend-api/gend-ui 를 그대로 쓰거나, 로컬 hot-reload 가 필요하면:

# API (kubectl port-forward 로 Trino + PG 접근)
kubectl port-forward svc/trino 30080:8080 -n gend &
kubectl port-forward svc/postgresql 5432:5432 -n gend &

cd apps/api
source .venv/bin/activate
export GEND_DATABASE_URL=postgresql+asyncpg://gend:gend@localhost:5432/gend
export GEND_TRINO_HOST=localhost
export GEND_TRINO_PORT=30080
uvicorn gend_api.main:app --reload --port 8000

# UI (별 터미널)
cd ui
pnpm dev   # http://localhost:5173

자세한 env 변수: apps/api/README.md 의 Quick Start.

3. 개발 워크플로우​

3.1 branch + commit​

  • branch prefix: feature/ / fix/ / refactor/ / infra/ / docs/
  • slug: kebab-case, 이슈 제목 요약 (예: feature/auth-google-sso)
  • commit: Conventional Commits
    • feat(scope): summary — 신규 기능
    • fix(scope): summary — 버그 수정
    • docs(scope): summary — 문서만
    • refactor(scope): summary — 동작 변경 X
    • infra(scope): summary — K8s / 배포 자산

3.2 PR + 리뷰​

  1. issue 발행 (gh issue create 또는 GitHub UI)
  2. branch 생성 + 커밋 + push
  3. gh pr create 또는 GitHub UI — 본문에 Closes #<issue> 포함
  4. 자동 리뷰 봇 (Copilot / CodeRabbit / Gemini) 대응:
    • 인라인 코멘트는 머지 전 모두 reply (수정 완료 / 스코프 밖 / 의도적 등)
    • reply 없이 머지 금지 — claude code 의 /review-pr 워크플로우가 자동 점검
  5. CI 전건 green 후 squash merge

3.3 worktree-ship 워크플로우 (선택, claude code)​

복잡한 multi-file 작업은 claude code 의 /worktree-ship <issue-no> 사용 — worktree 생성 → 구현 → PR → CI 대기 → 머지 → 정리까지 자동.

3.4 릴리스 (제품 버전 출하)​

main 머지는 prod 에 자동 배포되지만(CI/CD), 제품 버전 출하는 별도 행위다 — VERSION bump + 릴리스 노트 작성 후 vX.Y.Z 태그를 push 하면 release.yml 이 정확 태그 이미지 4종과 GitHub Release 를 발행한다 (ADR-0036). claude code 에서는 /release <버전> 으로 전 절차 수행. 증분 판단 기준은 지원 정책, 오프라인 사이트 반입은 에어갭 반입 참조.

4. 코드 컨벤션​

Python (apps/api)​

  • 포맷터: ruff (pyproject.toml 의 [tool.ruff])
  • 타입 힌트 강제: from __future__ import annotations
  • async/await: SQLAlchemy 2.0 async + asyncpg
  • 모든 라우터 endpoint: try/except + logger.error + HTTPException 패턴
  • 식별자 이스케이핑: _escape_identifier() (SQL injection 방지)
  • 보안 가드레일: ContextGateway (요청 전처리) + SqlGuard (SQL 검증)

TypeScript (ui)​

  • 빌드: Vite 6 + React 19 + TypeScript 5.6
  • UI: Tailwind CSS v4 + shadcn/ui (New York)
  • 상태: zustand 16 스토어 — immer 미사용 (Plain setters)
  • 라우팅: react-router-dom 45 라우트
  • 인증: oidc-client-ts (Keycloak SSO + JWT 자동 첨부)
  • Path alias: @/ → src/
  • 다국어: react-i18next (ko/en)

YAML / K8s​

  • 매니페스트: infra/ 하위, 환경별 overlay (infra/<comp>/overlays/<env>/)
  • StorageClass: prod 는 managed-csi-tagged (StandardSSD + Azure policy 자동 tag) — managed-premium 등 untagged 차단
  • Azure Resource tag: Owner / Department / CostCenter / Environment 4개 강제

자세한 패턴: 루트 CLAUDE.md 참조.

5. 테스트​

영역명령통과 기준
API 단위 + 통합cd apps/api && .venv/bin/python -m pytest tests/ -v --timeout=30988+ tests
UI 단위cd ui && pnpm test -- --run219 test files (vitest)
E2E (Playwright)cd ui && pnpm exec playwright test80 spec files
Pipeline (Dagster)cd pipelines && .venv/bin/python -m pytest tests/ -v69 test files
Seed (시드 스크립트)cd apps/api && .venv/bin/python -m pytest ../../scripts/test_seed*.py -v128 tests

5.1 회귀 가드 (lint job)​

.github/workflows/test.yml 의 Lint X (#issue 회귀 가드) job 들 — 청산된 자산 / 폐기된 패턴이 다시 추가되지 않도록 negative assertion. 새 PR 머지 전 자동 통과 필요.

예시:

  • Lint Vault prod install permanence (#1172 회귀 가드) — Vault prod 자산 영구 보존
  • Lint ESO cleanup permanence (#1107 회귀 가드) — sealed-secrets 청산 영구성
  • Lint Deployment strategy (#905 회귀 가드) — RWO PVC Deployment 의 strategy 강제

6. 시크릿 관리 (Vault + External Secrets Operator)​

GenD prod 는 sealed-secrets → ExternalSecret + Vault 로 전환됨 (Epic #1107 / #1172, 2026-05-28 완료). 신규 시크릿 추가 / 회전 절차는:

금지 패턴:

  • sealed-secrets 새 추가 (회귀 가드 차단)
  • kubectl create secret 으로 prod 시크릿 직접 생성 (IaC 단절)
  • vault kv put K=V argv 사용 (process list 평문 노출)

7. 배포 (개발자 관점)​

  • API 변경: main 머지 → GH Actions Build & Deploy → ACR push → kubectl set image → AKS prod rollout (자동)
  • UI 변경: 동일 (gend-ui 이미지)
  • docs/ 변경: main 머지 → docs-deploy workflow → Azure SWA (gend-docs.genon.ai)
  • infra/ 변경: main 머지 → ArgoCD sync (자동 또는 수동 트리거)

운영자 직접 명령은 docs/admin-ops/dev-deploy/README.md §3 참조.

8. 채널​

  • GitHub Issues: 버그 / 기능 / 작업 추적
  • Slack: #genon-gend-베타테스트 (베타 피드백), 사내 채널 (TBD)
  • AKS prod 접근 권한: Azure RBAC rg-genos-prod Owner — 권한자만, 인계 시 부여

9. FAQ / 트러블슈팅​

현상원인대응
Kind 재시작 후 seed 휘발docker desktop 재기동 → DB 데이터 손실make seed-demo 재실행
Vite dev → prod URL 호출 (Mixed Content)VITE_* env 의 default 가 prod URL--build-arg VITE_*=http://localhost:... 명시
pnpm 외 npm/yarn 사용pnpm-lock.yaml 만 진실pnpm install 만 사용
ExternalSecret Ready=Falseeso-reader policy path 누락 또는 Vault path 미시드vault policy read eso-reader + vault kv get secret/<ns>/<name>
PVC Pending — RequestDisallowedByPolicyprod StorageClass tag 누락managed-csi-tagged 사용 (untagged SC 차단됨)
Test API 실패 (CI) — Gitea 503GEND_GITEA_ADMIN_TOKEN CI env 누락known pre-existing — 해당 잡 re-run 후 auto-merge 대기 (admin merge 불필요)
다른 세션과 worktree 충돌 (concurrent-session: ... stash)동일 working tree race별도 git worktree 사용 권장

더 많은 패턴: 루트 CLAUDE.md + claude code memory 의 feedback_* 항목 (claude code 사용 시 자동 로드).

10. 다음 단계​