Scaffold
Templates de scaffolding de projetos e geração de boilerplate para tipos comuns de projetos com padrões recomendados.
Árvore de Decisão de Tipo de Projeto
O que você está construindo?
│
├─ API / Serviço Backend
│ ├─ API REST
│ │ ├─ Python → FastAPI (assíncrono, documentação OpenAPI automática)
│ │ ├─ Node.js → Express ou Fastify (Fastify para performance)
│ │ ├─ Go → Gin (ergonômico) ou Echo (rico em middleware)
│ │ └─ Rust → Axum (ecossistema tower, assíncrono-primeiro)
│ ├─ API GraphQL
│ │ ├─ Python → Strawberry + FastAPI
│ │ ├─ Node.js → Apollo Server ou Pothos + Yoga
│ │ ├─ Go → gqlgen (code-first)
│ │ └─ Rust → async-graphql + Axum
│ └─ Serviço gRPC
│ ├─ Python → grpcio + protobuf
│ ├─ Go → google.golang.org/grpc
│ └─ Rust → tonic
│
├─ Aplicação Web
│ ├─ Full-stack com SSR
│ │ ├─ Ecossistema React → Next.js 14+ (App Router)
│ │ ├─ Ecossistema Vue → Nuxt 3
│ │ ├─ Ecossistema Svelte → SvelteKit
│ │ └─ Conteúdo pesado / multi-framework → Astro
│ ├─ SPA (somente cliente)
│ │ ├─ React → Vite + React + React Router
│ │ ├─ Vue → Vite + Vue + Vue Router
│ │ └─ Svelte → Vite + Svelte + svelte-routing
│ └─ Site Estático
│ ├─ Blog / docs → Astro ou VitePress
│ └─ Marketing / landing → Astro ou Next.js (exportação estática)
│
├─ Ferramenta CLI
│ ├─ Python → Typer (simples) ou Click (complexo)
│ ├─ Node.js → Commander + Inquirer
│ ├─ Go → Cobra + Viper
│ └─ Rust → Clap (API derive)
│
├─ Biblioteca / Pacote
│ ├─ Pacote npm → TypeScript + tsup + Vitest
│ ├─ Pacote PyPI → uv + pyproject.toml + pytest
│ ├─ Módulo Go → go mod init + go test
│ └─ Crate Rust → cargo init --lib + cargo test
│
└─ Monorepo
├─ JavaScript/TypeScript → Turborepo + pnpm workspaces
├─ Full-stack JS → Nx
├─ Go → Go workspaces (go.work)
├─ Rust → Cargo workspaces
└─ Python → uv workspaces ou hatch
Matriz de Seleção de Stack
| Tipo de Projeto | Linguagem | Framework | Banco de Dados | ORM/Query | Alvo de Deploy |
|---|
| API REST | Python | FastAPI | PostgreSQL | SQLAlchemy + Alembic | Docker / AWS ECS |
| API REST | Node.js | Fastify | PostgreSQL | Prisma or Drizzle | Docker / Vercel |
| API REST | Go | Gin | PostgreSQL | sqlx (raw) or GORM | Docker / Fly.io |
| API REST | Rust | Axum | PostgreSQL | sqlx | Docker / Fly.io |
| Aplicação Web | TypeScript | Next.js 14+ | PostgreSQL | Prisma or Drizzle | Vercel / Docker |
| Aplicação Web | TypeScript | Nuxt 3 | PostgreSQL | Prisma | Vercel / Netlify |
| Aplicação Web | TypeScript | Astro | SQLite / nenhum | Drizzle | Cloudflare / Netlify |
| Ferramenta CLI | Python | Typer | SQLite | sqlite3 stdlib | PyPI |
| Ferramenta CLI | Go | Cobra | SQLite / BoltDB | sqlx | GitHub Releases |
| Ferramenta CLI | Rust | Clap | SQLite | rusqlite | crates.io |
| Biblioteca | TypeScript | tsup | n/a | n/a | npm |
| Biblioteca | Python | hatch/uv | n/a | n/a | PyPI |
Comandos Rápidos de Scaffold
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 (Aplicação Web)
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
Monorepo (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
Template de Projeto API
Estrutura de Diretórios (Exemplo FastAPI)
my-api/
├── src/
│ └── my_api/
│ ├── __init__.py
│ ├── main.py # Aplicação FastAPI, lifespan, middleware
│ ├── config.py # Configuração pydantic-settings
│ ├── database.py # Engine SQLAlchemy, sessão
│ ├── dependencies.py # Dependências compartilhadas do FastAPI
│ ├── routers/
│ │ ├── __init__.py
│ │ ├── health.py # Endpoint de health check
│ │ └── users.py # Endpoints CRUD de usuários
│ ├── models/
│ │ ├── __init__.py
│ │ └── user.py # Modelos SQLAlchemy
│ ├── schemas/
│ │ ├── __init__.py
│ │ └── user.py # Schemas Pydantic de requisição/resposta
│ └── services/
│ ├── __init__.py
│ └── user.py # Lógica de negócio
├── alembic/
│ ├── alembic.ini
│ ├── env.py
│ └── versions/
├── tests/
│ ├── conftest.py # Fixtures: DB de teste, cliente, factories
│ ├── test_health.py
│ └── test_users.py
├── pyproject.toml
├── Dockerfile
├── docker-compose.yml
├── .env.example
├── .gitignore
└── .dockerignore
Estrutura de Diretórios (Exemplo Express/Fastify)
my-api/
├── src/
│ ├── index.ts # Ponto de entrada, inicialização do servidor
│ ├── app.ts # Configuração da aplicação Express/Fastify
│ ├── config.ts # Configuração de ambiente com validação zod
│ ├── database.ts # Cliente Prisma ou configuração 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
Template de Projeto de Aplicação Web
Estrutura de Diretórios (Next.js App Router)
my-app/
├── src/
│ ├── app/
│ │ ├── layout.tsx # Layout raiz
│ │ ├── page.tsx # Página inicial
│ │ ├── loading.tsx # UI de carregamento global
│ │ ├── error.tsx # Boundary de erro global
│ │ ├── not-found.tsx # Página 404
│ │ ├── globals.css # Estilos globais + Tailwind
│ │ ├── (auth)/
│ │ │ ├── login/page.tsx
│ │ │ └── register/page.tsx
│ │ ├── dashboard/
│ │ │ ├── layout.tsx
│ │ │ └── page.tsx
│ │ └── api/
│ │ └── health/route.ts
│ ├── components/
│ │ ├── ui/ # Primitivas reutilizáveis
│ │ └── features/ # Componentes específicos de funcionalidades
│ ├── lib/
│ │ ├── db.ts # Cliente do banco de dados
│ │ ├── auth.ts # Helpers de autenticação
│ │ └── utils.ts # Utilitários compartilhados
│ └── types/
│ └── index.ts
├── public/
│ └── favicon.ico
├── tests/
│ ├── setup.ts
│ └── components/
├── next.config.ts
├── tailwind.config.ts
├── tsconfig.json
├── package.json
├── .env.local.example
└── .gitignore
Template de Projeto de Ferramenta CLI
Estrutura de Diretórios (Python / Typer)
my-cli/
├── src/
│ └── my_cli/
│ ├── __init__.py
│ ├── __main__.py # Entrada python -m my_cli
│ ├── cli.py # Aplicação Typer, grupos de comandos
│ ├── commands/
│ │ ├── __init__.py
│ │ ├── init.py # my-cli init
│ │ └── run.py # my-cli run
│ ├── config.py # Carregamento de arquivo de configuração (TOML/YAML)
│ └── utils.py
├── tests/
│ ├── conftest.py
│ └── test_commands.py
├── pyproject.toml # Ponto de entrada [project.scripts]
├── .gitignore
└── README.md
Estrutura de Diretórios (Go / Cobra)
my-cli/
├── cmd/
│ ├── root.go # Comando raiz, flags globais
│ ├── init.go # my-cli init
│ └── run.go # my-cli run
├── internal/
│ ├── config/
│ │ └── config.go # Carregamento de configuração Viper
│ └── runner/
│ └── runner.go # Lógica principal
├── main.go # Ponto de entrada, chama cmd.Execute()
├── go.mod
├── go.sum
├── Makefile
└── .gitignore
Template de Projeto de Biblioteca
Estrutura de Diretórios (Pacote npm)
my-lib/
├── src/
│ ├── index.ts # Exportações da API pública
│ ├── core.ts # Implementação principal
│ └── types.ts # Definições de tipos públicos
├── tests/
│ └── core.test.ts
├── package.json # "type": "module", mapa de exports
├── tsconfig.json # declaration: true, declarationMap: true
├── tsup.config.ts # Configuração de build: cjs + esm
├── vitest.config.ts
├── .npmignore
├── .gitignore
├── CHANGELOG.md
└── LICENSE
Estrutura de Diretórios (Pacote PyPI)
my-lib/
├── src/
│ └── my_lib/
│ ├── __init__.py # API pública, __version__
│ ├── core.py
│ └── py.typed # Marcador PEP 561
├── tests/
│ ├── conftest.py
│ └── test_core.py
├── pyproject.toml # Sistema de build, metadados, configurações de ferramentas
├── .gitignore
├── CHANGELOG.md
└── LICENSE
Template de Monorepo
Turborepo + pnpm Workspaces
my-monorepo/
├── apps/
│ ├── web/ # Frontend Next.js
│ │ ├── src/
│ │ ├── package.json # depende de @repo/shared
│ │ └── tsconfig.json # extends ../../tsconfig.base.json
│ └── api/ # Backend Fastify
│ ├── src/
│ ├── package.json
│ └── tsconfig.json
├── packages/
│ ├── shared/ # Tipos, utilitários e validadores compartilhados
│ │ ├── src/
│ │ ├── package.json # "name": "@repo/shared"
│ │ └── tsconfig.json
│ ├── ui/ # Componentes React compartilhados
│ │ ├── src/
│ │ └── package.json # "name": "@repo/ui"
│ └── config/ # Configurações compartilhadas
│ ├── eslint/
│ ├── typescript/
│ └── package.json
├── turbo.json # Pipeline: build, test, lint
├── pnpm-workspace.yaml # packages: ["apps/*", "packages/*"]
├── package.json # devDeps raiz: turbo
├── tsconfig.base.json # Configuração TypeScript compartilhada
├── .gitignore
└── .npmrc
Cargo Workspaces (Rust)
my-workspace/
├── crates/
│ ├── my-core/ # Biblioteca principal
│ │ ├── src/lib.rs
│ │ └── Cargo.toml
│ ├── my-cli/ # Binário CLI
│ │ ├── src/main.rs
│ │ └── Cargo.toml # depende de my-core
│ └── my-server/ # Binário API
│ ├── src/main.rs
│ └── Cargo.toml
├── Cargo.toml # [workspace] members = ["crates/*"]
├── Cargo.lock
├── .gitignore
└── rust-toolchain.toml
Checklist de Adições Comuns
Configuração do projeto concluída? Adicione estas:
│
├─ Controle de Versão
│ ├─ [ ] .gitignore (específico da linguagem)
│ ├─ [ ] .gitattributes (fim de linha, arquivos binários)
│ └─ [ ] Regras de proteção de branch
│
├─ CI/CD
│ ├─ [ ] Workflow GitHub Actions (testar no PR, implantar no merge)
│ ├─ [ ] Teste em matriz (SO, versões do runtime)
│ └─ [ ] Automação de releases
│
├─ Docker
│ ├─ [ ] Dockerfile multi-estágio
│ ├─ [ ] docker-compose.yml (aplicação + banco de dados + cache)
│ ├─ [ ] .dockerignore
│ └─ [ ] Endpoint de health check
│
├─ Qualidade de Código
│ ├─ [ ] Linter (ESLint, Ruff, golangci-lint, Clippy)
│ ├─ [ ] Formatador (Prettier, Black/Ruff, gofmt, rustfmt)
│ ├─ [ ] Ganchos de pré-commit (Husky, pre-commit)
│ └─ [ ] Verificação de tipos (TypeScript strict, mypy, go vet)
│
├─ Testes
│ ├─ [ ] Framework de testes configurado (Vitest, pytest, go test)
│ ├─ [ ] Relatório de cobertura
│ ├─ [ ] Configuração de banco de dados de teste
│ └─ [ ] Pipeline de teste no CI
│
├─ Editor
│ ├─ [ ] .editorconfig
│ ├─ [ ] .vscode/settings.json
│ └─ [ ] .vscode/extensions.json
│
└─ Documentação
├─ [ ] README.md (descrição do projeto, configuração, uso)
├─ [ ] AGENTS.md — propagar a partir de assets/AGENTS-template.md da skill repo-doctor
│ (seção "Landmines" é obrigatória;
│ doutrina: rules/agentic-quality.md)
├─ [ ] CONTRIBUTING.md
└─ [ ] Documentação da API (OpenAPI, godoc, rustdoc)
Templates de Arquivos de Configuração
.editorconfig (Universal)
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"]
}
Armadilhas Comuns
| Armadilha | Por Que Ocorre | Prevenção |
|---|
| .gitignore errado para a linguagem | Usou template genérico, faltando entradas específicas da linguagem | Use gitignore.io ou os templates do GitHub para sua stack |
| Esqueceu .env.example | Membros da equipe não sabem quais variáveis de ambiente são necessárias | Crie .env.example com cada var (valores vazios) no início do projeto |
| Nenhum arquivo de lock enviado | Versões de dependências inconsistentes entre ambientes | Envie package-lock.json, uv.lock, go.sum, Cargo.lock |
| Porta/host fixos no código | Funciona localmente, quebra em Docker/cloud | Sempre leia de variável de ambiente com valor padrão sensato |
| Testes acoplados a banco de dados real | Testes falham sem banco de dados rodando, configuração de CI é complexa | Use banco de dados em memória (SQLite) ou contêiner de teste (testcontainers) |
| Nenhum script de desenvolvimento | Cada desenvolvedor configura manualmente, retrabalho | Adicione scripts de dev no package.json (build, test, lint, dev) |
| Nenhum Makefile ou task runner | Comandos longos e complexos são esquecidos/digitados errados | Encapsule comandos em make, npm scripts, ou Taskfile |
| Cobertura de teste muito baixa | Sem cultura de teste, CI não reforça cobertura | Defina limite mínimo de cobertura no CI (70%+), falhe no build se abaixo |
| Sem healthcheck | Orquestrador não sabe se o app está pronto, reinicializações desnecessárias | Adicione endpoint GET /health que verifique dependências (banco, cache) |
[truncated for translation]