스캐폴드 (Scaffold)
일반적인 프로젝트 유형에 대한 모범 사례 기본값을 포함한 프로젝트 스캐폴딩 템플릿 및 보일러플레이트 생성 도구입니다.
프로젝트 유형 결정 트리
무엇을 구축하고 있나요?
│
├─ API / 백엔드 서비스
│ ├─ REST API
│ │ ├─ Python → FastAPI (비동기, OpenAPI 자동 문서화)
│ │ ├─ Node.js → Express 또는 Fastify (성능을 위해 Fastify 권장)
│ │ ├─ Go → Gin (사용하기 쉬움) 또는 Echo (미들웨어 풍부)
│ │ └─ Rust → Axum (tower 생태계, 비동기 우선)
│ ├─ GraphQL API
│ │ ├─ Python → Strawberry + FastAPI
│ │ ├─ Node.js → Apollo Server 또는 Pothos + Yoga
│ │ ├─ Go → gqlgen (코드 우선)
│ │ └─ Rust → async-graphql + Axum
│ └─ gRPC 서비스
│ ├─ Python → grpcio + protobuf
│ ├─ Go → google.golang.org/grpc
│ └─ Rust → tonic
│
├─ 웹 애플리케이션
│ ├─ SSR (서버 사이드 렌더링) 풀스택
│ │ ├─ React 생태계 → Next.js 14+ (App Router)
│ │ ├─ Vue 생태계 → Nuxt 3
│ │ ├─ Svelte 생태계 → SvelteKit
│ │ └─ 콘텐츠 중심 / 다중 프레임워크 → Astro
│ ├─ SPA (클라이언트 전용)
│ │ ├─ React → Vite + React + React Router
│ │ ├─ Vue → Vite + Vue + Vue Router
│ │ └─ Svelte → Vite + Svelte + svelte-routing
│ └─ 정적 사이트
│ ├─ 블로그 / 문서 → Astro 또는 VitePress
│ └─ 마케팅 / 랜딩 페이지 → Astro 또는 Next.js (정적 내보내기)
│
├─ CLI 도구
│ ├─ Python → Typer (간단) 또는 Click (복잡)
│ ├─ Node.js → Commander + Inquirer
│ ├─ Go → Cobra + Viper
│ └─ Rust → Clap (derive API)
│
├─ 라이브러리 / 패키지
│ ├─ npm 패키지 → TypeScript + tsup + Vitest
│ ├─ PyPI 패키지 → uv + pyproject.toml + pytest
│ ├─ Go 모듈 → go mod init + go test
│ └─ Rust 크레이트 → cargo init --lib + cargo test
│
└─ 모노레포
├─ JavaScript/TypeScript → Turborepo + pnpm workspaces
├─ 풀스택 JS → Nx
├─ Go → Go workspaces (go.work)
├─ Rust → Cargo workspaces
└─ Python → uv workspaces 또는 hatch
스택 선택 매트릭스
| 프로젝트 유형 | 언어 | 프레임워크 | 데이터베이스 | ORM/쿼리 | 배포 대상 |
|---|---|---|---|---|---|
| REST API | Python | FastAPI | PostgreSQL | SQLAlchemy + Alembic | Docker / AWS ECS |
| REST API | Node.js | Fastify | PostgreSQL | Prisma 또는 Drizzle | Docker / Vercel |
| REST API | Go | Gin | PostgreSQL | sqlx (raw) 또는 GORM | Docker / Fly.io |
| REST API | Rust | Axum | PostgreSQL | sqlx | Docker / Fly.io |
| 웹 앱 | TypeScript | Next.js 14+ | PostgreSQL | Prisma 또는 Drizzle | Vercel / Docker |
| 웹 앱 | TypeScript | Nuxt 3 | PostgreSQL | Prisma | Vercel / Netlify |
| 웹 앱 | TypeScript | Astro | SQLite / 없음 | Drizzle | Cloudflare / Netlify |
| CLI 도구 | Python | Typer | SQLite | sqlite3 stdlib | PyPI |
| CLI 도구 | Go | Cobra | SQLite / BoltDB | sqlx | GitHub Releases |
| CLI 도구 | Rust | Clap | SQLite | rusqlite | crates.io |
| 라이브러리 | TypeScript | tsup | 해당 없음 | 해당 없음 | npm |
| 라이브러리 | Python | hatch/uv | 해당 없음 | 해당 없음 | PyPI |
빠른 스캐폴드 명령어
Python (API)
# FastAPI with uv
mkdir my-api && cd my-api
uv init --python 3.12
uv add fastapi uvicorn sqlalchemy alembic psycopg2-binary pydantic-settings
uv add --dev pytest pytest-asyncio httpx ruff mypy
Node.js (웹 앱)
# Next.js 14+
npx create-next-app@latest my-app --typescript --tailwind --eslint --app --src-dir --import-alias "@/*"
# Vite + React
npm create vite@latest my-app -- --template react-ts
Go (API)
mkdir my-api && cd my-api
go mod init github.com/user/my-api
go get github.com/gin-gonic/gin
go get github.com/jmoiron/sqlx
go get github.com/lib/pq
Rust (CLI)
cargo init my-cli
cd my-cli
cargo add clap --features derive
cargo add serde --features derive
cargo add anyhow tokio --features tokio/full
모노레포 (Turborepo)
npx create-turbo@latest my-monorepo
# 또는 수동:
mkdir my-monorepo && cd my-monorepo
npm init -y
npm install turbo --save-dev
mkdir -p apps/web apps/api packages/shared
API 프로젝트 템플릿
디렉토리 구조 (FastAPI 예제)
my-api/
├── src/
│ └── my_api/
│ ├── __init__.py
│ ├── main.py # FastAPI 앱, 수명 주기, 미들웨어
│ ├── config.py # pydantic-settings 설정
│ ├── database.py # SQLAlchemy 엔진, 세션
│ ├── dependencies.py # 공유 FastAPI 의존성
│ ├── routers/
│ │ ├── __init__.py
│ │ ├── health.py # 헬스 체크 엔드포인트
│ │ └── users.py # 사용자 CRUD 엔드포인트
│ ├── models/
│ │ ├── __init__.py
│ │ └── user.py # SQLAlchemy 모델
│ ├── schemas/
│ │ ├── __init__.py
│ │ └── user.py # Pydantic 요청/응답 스키마
│ └── services/
│ ├── __init__.py
│ └── user.py # 비즈니스 로직
├── alembic/
│ ├── alembic.ini
│ ├── env.py
│ └── versions/
├── tests/
│ ├── conftest.py # Fixture: 테스트 DB, 클라이언트, 팩토리
│ ├── test_health.py
│ └── test_users.py
├── pyproject.toml
├── Dockerfile
├── docker-compose.yml
├── .env.example
├── .gitignore
└── .dockerignore
디렉토리 구조 (Express/Fastify 예제)
my-api/
├── src/
│ ├── index.ts # 진입점, 서버 시작
│ ├── app.ts # Express/Fastify 앱 설정
│ ├── config.ts # zod 검증을 사용한 환경 설정
│ ├── database.ts # Prisma 클라이언트 또는 Drizzle 설정
│ ├── middleware/
│ │ ├── auth.ts
│ │ ├── error-handler.ts
│ │ └── request-logger.ts
│ ├── routes/
│ │ ├── health.ts
│ │ └── users.ts
│ ├── services/
│ │ └── user.service.ts
│ └── types/
│ └── index.ts
├── prisma/
│ └── schema.prisma
├── tests/
│ ├── setup.ts
│ └── routes/
│ └── users.test.ts
├── package.json
├── tsconfig.json
├── Dockerfile
├── docker-compose.yml
├── .env.example
└── .gitignore
웹 앱 프로젝트 템플릿
디렉토리 구조 (Next.js App Router)
my-app/
├── src/
│ ├── app/
│ │ ├── layout.tsx # 루트 레이아웃
│ │ ├── page.tsx # 홈 페이지
│ │ ├── loading.tsx # 전역 로딩 UI
│ │ ├── error.tsx # 전역 에러 경계
│ │ ├── not-found.tsx # 404 페이지
│ │ ├── globals.css # 전역 스타일 + Tailwind
│ │ ├── (auth)/
│ │ │ ├── login/page.tsx
│ │ │ └── register/page.tsx
│ │ ├── dashboard/
│ │ │ ├── layout.tsx
│ │ │ └── page.tsx
│ │ └── api/
│ │ └── health/route.ts
│ ├── components/
│ │ ├── ui/ # 재사용 가능한 기본 컴포넌트
│ │ └── features/ # 기능별 컴포넌트
│ ├── lib/
│ │ ├── db.ts # 데이터베이스 클라이언트
│ │ ├── auth.ts # 인증 헬퍼
│ │ └── utils.ts # 공유 유틸리티
│ └── types/
│ └── index.ts
├── public/
│ └── favicon.ico
├── tests/
│ ├── setup.ts
│ └── components/
├── next.config.ts
├── tailwind.config.ts
├── tsconfig.json
├── package.json
├── .env.local.example
└── .gitignore
CLI 도구 프로젝트 템플릿
디렉토리 구조 (Python / Typer)
my-cli/
├── src/
│ └── my_cli/
│ ├── __init__.py
│ ├── __main__.py # python -m my_cli 진입점
│ ├── cli.py # Typer 앱, 명령 그룹
│ ├── commands/
│ │ ├── __init__.py
│ │ ├── init.py # my-cli init
│ │ └── run.py # my-cli run
│ ├── config.py # 설정 파일 로딩 (TOML/YAML)
│ └── utils.py
├── tests/
│ ├── conftest.py
│ └── test_commands.py
├── pyproject.toml # [project.scripts] 진입점
├── .gitignore
└── README.md
디렉토리 구조 (Go / Cobra)
my-cli/
├── cmd/
│ ├── root.go # 루트 명령, 전역 플래그
│ ├── init.go # my-cli init
│ └── run.go # my-cli run
├── internal/
│ ├── config/
│ │ └── config.go # Viper 설정 로딩
│ └── runner/
│ └── runner.go # 핵심 로직
├── main.go # 진입점, cmd.Execute() 호출
├── go.mod
├── go.sum
├── Makefile
└── .gitignore
라이브러리 프로젝트 템플릿
디렉토리 구조 (npm 패키지)
my-lib/
├── src/
│ ├── index.ts # 공개 API 내보내기
│ ├── core.ts # 핵심 구현
│ └── types.ts # 공개 타입 정의
├── tests/
│ └── core.test.ts
├── package.json # "type": "module", exports 맵
├── tsconfig.json # declaration: true, declarationMap: true
├── tsup.config.ts # 빌드 설정: cjs + esm
├── vitest.config.ts
├── .npmignore
├── .gitignore
├── CHANGELOG.md
└── LICENSE
디렉토리 구조 (PyPI 패키지)
my-lib/
├── src/
│ └── my_lib/
│ ├── __init__.py # 공개 API, __version__
│ ├── core.py
│ └── py.typed # PEP 561 마커
├── tests/
│ ├── conftest.py
│ └── test_core.py
├── pyproject.toml # 빌드 시스템, 메타데이터, 도구 설정
├── .gitignore
├── CHANGELOG.md
└── LICENSE
모노레포 템플릿
Turborepo + pnpm Workspaces
my-monorepo/
├── apps/
│ ├── web/ # Next.js 프론트엔드
│ │ ├── src/
│ │ ├── package.json # @repo/shared에 의존
│ │ └── tsconfig.json # ../../tsconfig.base.json 확장
│ └── api/ # Fastify 백엔드
│ ├── src/
│ ├── package.json
│ └── tsconfig.json
├── packages/
│ ├── shared/ # 공유 타입, 유틸리티, 유효성 검사기
│ │ ├── src/
│ │ ├── package.json # "name": "@repo/shared"
│ │ └── tsconfig.json
│ ├── ui/ # 공유 React 컴포넌트
│ │ ├── src/
│ │ └── package.json # "name": "@repo/ui"
│ └── config/ # 공유 설정
│ ├── eslint/
│ ├── typescript/
│ └── package.json
├── turbo.json # 파이프라인: build, test, lint
├── pnpm-workspace.yaml # packages: ["apps/*", "packages/*"]
├── package.json # 루트 devDeps: turbo
├── tsconfig.base.json # 공유 TypeScript 설정
├── .gitignore
└── .npmrc
Cargo Workspaces (Rust)
my-workspace/
├── crates/
│ ├── my-core/ # 핵심 라이브러리
│ │ ├── src/lib.rs
│ │ └── Cargo.toml
│ ├── my-cli/ # CLI 바이너리
│ │ ├── src/main.rs
│ │ └── Cargo.toml # my-core에 의존
│ └── my-server/ # API 바이너리
│ ├── src/main.rs
│ └── Cargo.toml
├── Cargo.toml # [workspace] members = ["crates/*"]
├── Cargo.lock
├── .gitignore
└── rust-toolchain.toml
일반적인 추가 항목 체크리스트
프로젝트 설정이 완료되었나요? 다음을 추가하세요:
│
├─ 버전 관리
│ ├─ [ ] .gitignore (언어별)
│ ├─ [ ] .gitattributes (줄 끝, 바이너리 파일)
│ └─ [ ] 브랜치 보호 규칙
│
├─ CI/CD
│ ├─ [ ] GitHub Actions 워크플로우 (PR에서 테스트, 병합 시 배포)
│ ├─ [ ] 매트릭스 테스트 (OS, 런타임 버전)
│ └─ [ ] 릴리스 자동화
│
├─ Docker
│ ├─ [ ] 멀티 스테이지 Dockerfile
│ ├─ [ ] docker-compose.yml (앱 + 데이터베이스 + 캐시)
│ ├─ [ ] .dockerignore
│ └─ [ ] 헬스 체크 엔드포인트
│
├─ 코드 품질
│ ├─ [ ] 린터 (ESLint, Ruff, golangci-lint, Clippy)
│ ├─ [ ] 포매터 (Prettier, Black/Ruff, gofmt, rustfmt)
│ ├─ [ ] Pre-commit 훅 (Husky, pre-commit)
│ └─ [ ] 타입 체킹 (TypeScript strict, mypy, go vet)
│
├─ 테스트
│ ├─ [ ] 테스트 프레임워크 설정 (Vitest, pytest, go test)
│ ├─ [ ] 커버리지 보고
│ ├─ [ ] 테스트 데이터베이스 설정
│ └─ [ ] CI 테스트 파이프라인
│
├─ 에디터
│ ├─ [ ] .editorconfig
│ ├─ [ ] .vscode/settings.json
│ └─ [ ] .vscode/extensions.json
│
└─ 문서
├─ [ ] README.md (프로젝트 설명, 설정, 사용법)
├─ [ ] CONTRIBUTING.md
└─ [ ] API 문서 (OpenAPI, godoc, rustdoc)
설정 파일 템플릿
.editorconfig (범용)
root = true
[*]
indent_style = space
indent_size = 2
end_of_line = lf
charset = utf-8
trim_trailing_whitespace = true
insert_final_newline = true
[*.{py,rs}]
indent_size = 4
[*.go]
indent_style = tab
[*.md]
trim_trailing_whitespace = false
[Makefile]
indent_style = tab
pyproject.toml (Python)
[project]
name = "my-project"
version = "0.1.0"
requires-python = ">=3.12"
[tool.ruff]
target-version = "py312"
line-length = 88
[tool.ruff.lint]
select = ["E", "F", "I", "UP", "B", "SIM"]
[tool.pytest.ini_options]
testpaths = ["tests"]
asyncio_mode = "auto"
[tool.mypy]
strict = true
tsconfig.json (TypeScript - Strict)
{
"compilerOptions": {
"target": "ES2022",
"module": "NodeNext",
"moduleResolution": "NodeNext",
"strict": true,
"esModuleInterop": true,
"skipLibCheck": true,
"forceConsistentCasingInFileNames": true,
"resolveJsonModule": true,
"declaration": true,
"declarationMap": true,
"sourceMap": true,
"outDir": "./dist",
"rootDir": "./src"
},
"include": ["src"],
"exclude": ["node_modules", "dist"]
}
일반적인 실수와 방지법
| 실수 | 발생 원인 | 방지법 |
|---|---|---|
| 잘못된 언어별 .gitignore | 일반 템플릿 사용, 언어별 항목 누락 | 스택에 맞는 gitignore.io 또는 GitHub 템플릿 사용 |
| .env.example 누락 | 팀원이 필요한 환경 변수를 알 수 없음 | 프로젝트 시작 시 모든 변수(값은 비워둠)와 함께 .env.example 생성 |
| lock 파일 커밋 안 함 | 환경 간 일관되지 않은 의존성 버전 | package-lock.json, uv.lock, go.sum, Cargo.lock 커밋 |
| 코드에 포트/호스트 하드코딩 | 로컬에서는 작동하지만 Docker/클라우드에서 문제 발생 | 항상 적절한 기본값과 함께 환경 변수에서 읽기 |
| 실제 데이터베이스에 결합된 테스트 | 실행 중인 DB 없으면 테스트 실패, CI 설정 복잡 | 단위 테스트를 위해 테스트 컨테이너 또는 인메모리 SQLite 사용 |
| 헬스 체크 엔드포인트 누락 | 배포 오케스트레이터가 준비 상태를 확인할 수 없음 | 프로젝트 시작 시 /health 엔드포인트 추가, DB 연결 확인 |
| Prisma/Drizzle 없이 직접 SQL 작성 | 유지보수 어려움, 타입 안전성 부족, 마이그레이션 관리 안 됨 | 처음부터 ORM 설정 |
| CI 환경 변수 누락 | CI에서 테스트 실패, 배포 시 비밀 값 누락 | 조직 수준의 CI 비밀/변수 사용, .env.ci.example 제공 |
| 다중 스테이지 빌드 없는 Dockerfile | 이미지 크기 큼, 빌드 도구 포함 | 프로덕션 이미지에는 빌드 종속성 제외 |
| 타입 정의 없이 JS로만 npm 패키지 릴리스 | 사용자에게 자동 완성 및 타입 검사 없음 | TypeScript 사용, package.json에 types 필드 포함 |
| Go, Rust, Python 프로젝트에서 테이블 대신 공백 사용 | 언어별 포맷팅 규칙 위반 | 프로젝트별 .editorconfig로 일관성 확보 |
대화형 시작 명령어
AI 지원 IDE를 위한 명령어 (예: Claude Code에서 /scaffold).
/scaffold api python fastapi my-project
/scaffold web nextjs my-app
/scaffold cli rust my-cli
AI 에이전트는 이 스킬의 SKILL.md를 참조하여 프로젝트 초기화를 위한 최신 보일러플레이트 생성 지침을 찾아야 합니다.