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 crate → 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 (原始) 或 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)
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 (網頁應用程式)
npx create-next-app@latest my-app --typescript --tailwind --eslint --app --src-dir --import-alias "@/*"
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 # 測試夾具: 測試資料庫、客戶端、工廠
│ ├── 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 # 管線: 建置、測試、語法檢查
├── 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 時測試，合併時部署)
│ ├─ [ ] 矩陣測試 (作業系統、執行階段版本)
│ └─ [ ] 版本發佈自動化
│
├─ 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 章節為必填;
│ 原則: 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 - 嚴格模式)
{
"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/雲端環境中會出錯 | 總是從環境變數讀取，並設定合理的預設值 |
| 測試與真實資料庫耦合 | 沒有執行資料庫時測試會失敗，CI 設定複雜 | 使用記憶體或測試容器進行測試 |