¿Qué hace Scaffold?
Plantillas de proyectos y generación de código repetitivo para tipos de proyecto comunes con valores predeterminados basados en las mejores prácticas.
Árbol de Decisión para el Tipo de Proyecto
¿Qué estás construyendo?
│
├─ API / Servicio Backend
│ ├─ API REST
│ │ ├─ Python → FastAPI (asíncrono, documentación OpenAPI automática)
│ │ ├─ Node.js → Express o Fastify (Fastify para rendimiento)
│ │ ├─ Go → Gin (ergonómico) o Echo (rico en middleware)
│ │ └─ Rust → Axum (ecosistema tower, asíncrono primero)
│ ├─ API GraphQL
│ │ ├─ Python → Strawberry + FastAPI
│ │ ├─ Node.js → Apollo Server o Pothos + Yoga
│ │ ├─ Go → gqlgen (código primero)
│ │ └─ Rust → async-graphql + Axum
│ └─ Servicio gRPC
│ ├─ Python → grpcio + protobuf
│ ├─ Go → google.golang.org/grpc
│ └─ Rust → tonic
│
├─ Aplicación Web
│ ├─ Full-stack con SSR
│ │ ├─ Ecosistema React → Next.js 14+ (App Router)
│ │ ├─ Ecosistema Vue → Nuxt 3
│ │ ├─ Ecosistema Svelte → SvelteKit
│ │ └─ Contenido pesado / multi-framework → Astro
│ ├─ SPA (solo cliente)
│ │ ├─ React → Vite + React + React Router
│ │ ├─ Vue → Vite + Vue + Vue Router
│ │ └─ Svelte → Vite + Svelte + svelte-routing
│ └─ Sitio Estático
│ ├─ Blog / docs → Astro o VitePress
│ └─ Marketing / landing → Astro o Next.js (exportación estática)
│
├─ Herramienta CLI
│ ├─ Python → Typer (simple) o Click (complejo)
│ ├─ Node.js → Commander + Inquirer
│ ├─ Go → Cobra + Viper
│ └─ Rust → Clap (API derive)
│
├─ Librería / Paquete
│ ├─ Paquete npm → TypeScript + tsup + Vitest
│ ├─ Paquete PyPI → uv + pyproject.toml + pytest
│ ├─ Módulo Go → go mod init + go test
│ └─ Caja 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 o hatch
Matriz de Selección de Stack
| Tipo de Proyecto | Lenguaje | Framework | Base de Datos | ORM/Query | Destino de Despliegue |
|---|
| API REST | Python | FastAPI | PostgreSQL | SQLAlchemy + Alembic | Docker / AWS ECS |
| API REST | Node.js | Fastify | PostgreSQL | Prisma o Drizzle | Docker / Vercel |
| API REST | Go | Gin | PostgreSQL | sqlx (raw) o GORM | Docker / Fly.io |
| API REST | Rust | Axum | PostgreSQL | sqlx | Docker / Fly.io |
| App Web | TypeScript | Next.js 14+ | PostgreSQL | Prisma o Drizzle | Vercel / Docker |
| App Web | TypeScript | Nuxt 3 | PostgreSQL | Prisma | Vercel / Netlify |
| App Web | TypeScript | Astro | SQLite / ninguno | Drizzle | Cloudflare / Netlify |
| Herramienta CLI | Python | Typer | SQLite | sqlite3 stdlib | PyPI |
| Herramienta CLI | Go | Cobra | SQLite / BoltDB | sqlx | GitHub Releases |
| Herramienta CLI | Rust | Clap | SQLite | rusqlite | crates.io |
| Librería | TypeScript | tsup | n/a | n/a | npm |
| Librería | Python | hatch/uv | n/a | n/a | PyPI |
Comandos Rápidos de Inicialización
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 (App 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
Plantilla de Proyecto API
Estructura de Directorios (Ejemplo FastAPI)
my-api/
├── src/
│ └── my_api/
│ ├── __init__.py
│ ├── main.py # App FastAPI, lifespan, middleware
│ ├── config.py # Configuración con pydantic-settings
│ ├── database.py # Motor SQLAlchemy, sesión
│ ├── dependencies.py # Dependencias compartidas de FastAPI
│ ├── routers/
│ │ ├── __init__.py
│ │ ├── health.py # Endpoint de verificación de salud
│ │ └── users.py # Endpoints CRUD de usuarios
│ ├── models/
│ │ ├── __init__.py
│ │ └── user.py # Modelos SQLAlchemy
│ ├── schemas/
│ │ ├── __init__.py
│ │ └── user.py # Schemas Pydantic de solicitud/respuesta
│ └── services/
│ ├── __init__.py
│ └── user.py # Lógica de negocio
├── alembic/
│ ├── alembic.ini
│ ├── env.py
│ └── versions/
├── tests/
│ ├── conftest.py # Fixtures: BD de prueba, cliente, fábricas
│ ├── test_health.py
│ └── test_users.py
├── pyproject.toml
├── Dockerfile
├── docker-compose.yml
├── .env.example
├── .gitignore
└── .dockerignore
Estructura de Directorios (Ejemplo Express/Fastify)
my-api/
├── src/
│ ├── index.ts # Punto de entrada, inicio del servidor
│ ├── app.ts # Configuración de la app Express/Fastify
│ ├── config.ts # Configuración de entorno con validación zod
│ ├── database.ts # Cliente Prisma o configuración 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
Plantilla de Proyecto de App Web
Estructura de Directorios (Next.js App Router)
my-app/
├── src/
│ ├── app/
│ │ ├── layout.tsx # Layout raíz
│ │ ├── page.tsx # Página de inicio
│ │ ├── loading.tsx # UI de carga global
│ │ ├── error.tsx # Límite de error global
│ │ ├── not-found.tsx # Página 404
│ │ ├── globals.css # Estilos globales + Tailwind
│ │ ├── (auth)/
│ │ │ ├── login/page.tsx
│ │ │ └── register/page.tsx
│ │ ├── dashboard/
│ │ │ ├── layout.tsx
│ │ │ └── page.tsx
│ │ └── api/
│ │ └── health/route.ts
│ ├── components/
│ │ ├── ui/ # Primitivas reutilizables
│ │ └── features/ # Componentes específicos de funcionalidad
│ ├── lib/
│ │ ├── db.ts # Cliente de base de datos
│ │ ├── auth.ts # Ayudantes de autenticación
│ │ └── utils.ts # Utilidades compartidas
│ └── types/
│ └── index.ts
├── public/
│ └── favicon.ico
├── tests/
│ ├── setup.ts
│ └── components/
├── next.config.ts
├── tailwind.config.ts
├── tsconfig.json
├── package.json
├── .env.local.example
└── .gitignore
Plantilla de Proyecto de Herramienta CLI
Estructura de Directorios (Python / Typer)
my-cli/
├── src/
│ └── my_cli/
│ ├── __init__.py
│ ├── __main__.py # python -m my_cli entrada
│ ├── cli.py # App Typer, grupos de comandos
│ ├── commands/
│ │ ├── __init__.py
│ │ ├── init.py # my-cli init
│ │ └── run.py # my-cli run
│ ├── config.py # Carga de archivo de configuración (TOML/YAML)
│ └── utils.py
├── tests/
│ ├── conftest.py
│ └── test_commands.py
├── pyproject.toml # Punto de entrada [project.scripts]
├── .gitignore
└── README.md
Estructura de Directorios (Go / Cobra)
my-cli/
├── cmd/
│ ├── root.go # Comando raíz, flags globales
│ ├── init.go # my-cli init
│ └── run.go # my-cli run
├── internal/
│ ├── config/
│ │ └── config.go # Carga de configuración con Viper
│ └── runner/
│ └── runner.go # Lógica principal
├── main.go # Punto de entrada, llama a cmd.Execute()
├── go.mod
├── go.sum
├── Makefile
└── .gitignore
Plantilla de Proyecto de Librería
Estructura de Directorios (Paquete npm)
my-lib/
├── src/
│ ├── index.ts # Exportaciones de la API pública
│ ├── core.ts # Implementación principal
│ └── types.ts # Definiciones de tipos públicos
├── tests/
│ └── core.test.ts
├── package.json # "type": "module", mapa de exports
├── tsconfig.json # declaration: true, declarationMap: true
├── tsup.config.ts # Configuración de compilación: cjs + esm
├── vitest.config.ts
├── .npmignore
├── .gitignore
├── CHANGELOG.md
└── LICENSE
Estructura de Directorios (Paquete 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 compilación, metadatos, config herramienta
├── .gitignore
├── CHANGELOG.md
└── LICENSE
Plantilla de Monorepo
Turborepo + pnpm Workspaces
my-monorepo/
├── apps/
│ ├── web/ # Frontend Next.js
│ │ ├── src/
│ │ ├── package.json # depende de @repo/shared
│ │ └── tsconfig.json # extiende ../../tsconfig.base.json
│ └── api/ # Backend Fastify
│ ├── src/
│ ├── package.json
│ └── tsconfig.json
├── packages/
│ ├── shared/ # Tipos, utilidades, validadores compartidos
│ │ ├── src/
│ │ ├── package.json # "name": "@repo/shared"
│ │ └── tsconfig.json
│ ├── ui/ # Componentes React compartidos
│ │ ├── src/
│ │ └── package.json # "name": "@repo/ui"
│ └── config/ # Configuraciones compartidas
│ ├── eslint/
│ ├── typescript/
│ └── package.json
├── turbo.json # Pipeline: build, test, lint
├── pnpm-workspace.yaml # packages: ["apps/*", "packages/*"]
├── package.json # DevDeps raíz: turbo
├── tsconfig.base.json # Configuración TypeScript compartida
├── .gitignore
└── .npmrc
Cargo Workspaces (Rust)
my-workspace/
├── crates/
│ ├── my-core/ # Librería principal
│ │ ├── src/lib.rs
│ │ └── Cargo.toml
│ ├── my-cli/ # Binario CLI
│ │ ├── src/main.rs
│ │ └── Cargo.toml # depende de my-core
│ └── my-server/ # Binario API
│ ├── src/main.rs
│ └── Cargo.toml
├── Cargo.toml # [workspace] members = ["crates/*"]
├── Cargo.lock
├── .gitignore
└── rust-toolchain.toml
Lista de Verificación de Adiciones Comunes
¿Configuración del proyecto completada? Añade estos:
│
├─ Control de Versiones
│ ├─ [ ] .gitignore (específico del lenguaje)
│ ├─ [ ] .gitattributes (saltos de línea, archivos binarios)
│ └─ [ ] Reglas de protección de ramas
│
├─ CI/CD
│ ├─ [ ] Flujo de trabajo de GitHub Actions (pruebas en PR, despliegue en merge)
│ ├─ [ ] Pruebas matriciales (SO, versiones de runtime)
│ └─ [ ] Automatización de releases
│
├─ Docker
│ ├─ [ ] Dockerfile multi-etapa
│ ├─ [ ] docker-compose.yml (app + base de datos + caché)
│ ├─ [ ] .dockerignore
│ └─ [ ] Endpoint de verificación de salud
│
├─ Calidad de Código
│ ├─ [ ] Linter (ESLint, Ruff, golangci-lint, Clippy)
│ ├─ [ ] Formateador (Prettier, Black/Ruff, gofmt, rustfmt)
│ ├─ [ ] Hooks de pre-commit (Husky, pre-commit)
│ └─ [ ] Verificación de tipos (TypeScript strict, mypy, go vet)
│
├─ Pruebas
│ ├─ [ ] Framework de pruebas configurado (Vitest, pytest, go test)
│ ├─ [ ] Reporte de cobertura
│ ├─ [ ] Configuración de base de datos de pruebas
│ └─ [ ] Pipeline de pruebas en CI
│
├─ Editor
│ ├─ [ ] .editorconfig
│ ├─ [ ] .vscode/settings.json
│ └─ [ ] .vscode/extensions.json
│
└─ Documentación
├─ [ ] README.md (descripción del proyecto, configuración, uso)
├─ [ ] AGENTS.md — generado a partir del skill repo-doctor
│ assets/AGENTS-template.md (la sección de Obstáculos es obligatoria;
│ doctrina: rules/agentic-quality.md)
├─ [ ] CONTRIBUTING.md
└─ [ ] Documentación de la API (OpenAPI, godoc, rustdoc)
Plantillas de Archivos de Configuración
.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 - Estricto)
{
"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"]
}
Errores Frecuentes Comunes
| Error | Por qué Ocurre | Prevención |
|---|
| .gitignore incorrecto para el lenguaje | Se usó una plantilla genérica, faltan entradas específicas del lenguaje | Usa gitignore.io o las plantillas de GitHub para tu stack |
| Olvidó .env.example | Los miembros del equipo no saben qué vars de entorno son necesarias | Crea .env.example con cada var (valores vacíos) al inicio del proyecto |
| Sin archivo de bloqueo en el repositorio | Versiones de dependencias inconsistentes entre entornos | Confirma package-lock.json, uv.lock, go.sum, Cargo.lock |
| Puerto/host hardcodeado en el código | Funciona localmente, se rompe en Docker/nube | Siempre lee desde una variable de entorno con un valor predeterminado sensato |
| Pruebas acopladas a la base de datos real | Las pruebas fallan sin una BD en ejecución, la configuración de CI es compleja | Usa una base de datos en memoria o un contenedor de prueba; mockea la capa de datos |
| Dependencias faltantes en el Dockerfile | La imagen no incluye herramientas de compilación (gcc, python-dev) | Usa una imagen base completa; prueba la compilación de Docker localmente |
| Sin política de CORS configurada | Las solicitudes del frontend son bloqueadas por el navegador | Configura CORS explícitamente en el backend; usa variables de entorno para orígenes |
| Archivos de test por defecto no eliminados | Se dejaron tests de ejemplo de create-next-app | Elimina los archivos de test de ejemplo y escribe tests reales para el dominio de la aplicación |
| Sin verificación de tipos en CI | TypeScript/mypy puede quejarse solo localmente | Añade verificación de tipos como un paso separado en el pipeline de CI |