0xDarkMatter/claude-mods

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 워크스페이스 (go.work)
   ├─ Rust → Cargo 워크스페이스
   └─ Python → uv 워크스페이스 또는 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)

# uv를 사용한 FastAPI
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 (프로젝트 설명, 설정, 사용법)
   ├─ [ ] AGENTS.md — repo-doctor 스킬의
   │      assets/AGENTS-template.md 에서 시드 (Landmines 섹션은 필수;
   │      doctrine: rules/agentic-quality.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 생성
잠금 파일 커밋 안 함	환경 간 일관성 없는 종속성 버전	package-lock.json, uv.lock, go.sum, Cargo.lock 커밋
코드에 하드코딩된 포트/호스트	로컬에서는 작동하지만 Docker/클라우드에서 중단	항상 적절한 기본값으로 환경 변수에서 읽기
실제 데이터베이스에 결합된 테스트	실행 중인 DB 없이 테스트 실패, CI 설정이 복잡

…

[번역을 위해 잘림]