Generador de Documentación de Proyectos
Genera documentación estructurada de proyectos analizando el código base. Produce documentación que refleja el código real, no la arquitectura aspiracional.
Cuándo Usarlo
- Un proyecto nuevo necesita documentación inicial
- La documentación falta o está desactualizada
- Al incorporar a alguien al código base
- Actualización de documentación después de una refactorización
Flujo de Trabajo
1. Detectar el Tipo de Proyecto
Escanea la raíz del proyecto para determinar qué tipo de proyecto es:
| Indicador | Tipo de Proyecto |
|---|---|
wrangler.jsonc / wrangler.toml | Cloudflare Worker |
vite.config.ts + src/App.tsx | React SPA |
astro.config.mjs | Sitio Astro |
next.config.js | Aplicación Next.js |
package.json con hono | API Hono |
src/index.ts con Hono | Servidor API |
drizzle.config.ts | Tiene capa de base de datos |
schema.ts o schema/ | Tiene esquema de base de datos |
pyproject.toml / setup.py | Proyecto Python |
Cargo.toml | Proyecto Rust |
2. Preguntar Qué Generar
¿Qué documentación debo generar?
1. ARCHITECTURE.md — visión general del sistema, pila, estructura de directorios, flujos clave
2. API_ENDPOINTS.md — rutas, métodos, parámetros, formas de respuesta, autenticación
3. DATABASE_SCHEMA.md — tablas, relaciones, migraciones, índices
4. Todo lo anterior
Solo ofrece documentación que coincida con el proyecto. No ofrezcas API_ENDPOINTS.md para un sitio estático. No ofrezcas DATABASE_SCHEMA.md si no hay base de datos.
3. Escanear el Código Base
Para cada documento solicitado, lee los archivos fuente relevantes:
ARCHITECTURE.md — escanea:
package.json/pyproject.toml(pila, dependencias)- Puntos de entrada (
src/index.ts,src/main.tsx,src/App.tsx) - Archivos de configuración (
wrangler.jsonc,vite.config.ts,tsconfig.json) - Estructura de directorios (primeros 2 niveles)
- Módulos clave y sus exportaciones
API_ENDPOINTS.md — escanea:
- Archivos de rutas (
src/routes/,src/api/, o en línea en index) - Archivos de middleware (autenticación, CORS, registro)
- Tipos de solicitud/respuesta o esquemas Zod
- Patrones de manejo de errores
DATABASE_SCHEMA.md — escanea:
- Archivos de esquema Drizzle (
src/db/schema.ts,src/schema/) - Archivos de migración (
drizzle/,migrations/) - Archivos SQL sin procesar si están presentes
- Archivos de seed si están presentes
4. Generar Documentación
Escribe cada documento en docs/ (crea el directorio si no existe). Si el proyecto ya tiene documentación allí, ofrécete a actualizarla en lugar de sobrescribirla.
Para proyectos pequeños sin directorio docs/, escribe en la raíz del proyecto.
Plantillas de Documentos
ARCHITECTURE.md
# Arquitectura
## Visión General
[Un párrafo: qué hace este proyecto y cómo está estructurado]
## Pila Tecnológica
| Capa | Tecnología | Versión |
|-------|------------|---------|
| Entorno de ejecución | [ej. Cloudflare Workers] | — |
| Framework | [ej. Hono] | [versión] |
| Base de datos | [ej. D1 (SQLite)] | — |
| ORM | [ej. Drizzle] | [versión] |
| Frontend | [ej. React 19] | [versión] |
| Estilos | [ej. Tailwind v4] | [versión] |
## Estructura de Directorios
[Árbol anotado — primeros 2 niveles con comentarios de propósito]
## Flujos Clave
### [Flujo 1: ej. "Autenticación de Usuario"]
[Paso a paso: solicitud → middleware → manejador → base de datos → respuesta]
### [Flujo 2: ej. "Pipeline de Procesamiento de Datos"]
[Paso a paso a través del sistema]
## Configuración
[Archivos de configuración clave y qué controlan]
## Despliegue
[Cómo desplegar, variables de entorno necesarias, comandos de compilación]
API_ENDPOINTS.md
# Endpoints de la API
## URL Base
[ej. `https://api.example.com` o relativo `/api`]
## Autenticación
[Método: token Bearer, cookie de sesión, clave API, ninguno]
[De dónde vienen los tokens, cómo obtenerlos]
## Endpoints
### [Grupo: ej. Usuarios]
#### `GET /api/users`
- **Autenticación**: Requerida
- **Parámetros**: `?page=1&limit=20`
- **Respuesta**: `{ users: User[], total: number }`
#### `POST /api/users`
- **Autenticación**: Requerida (admin)
- **Cuerpo**: `{ name: string, email: string }`
- **Respuesta**: `{ user: User }` (201)
- **Errores**: 400 (validación), 409 (correo duplicado)
[Repetir para cada endpoint]
## Formato de Error
[Forma de respuesta de error estándar]
## Límites de Velocidad
[Si aplica]
DATABASE_SCHEMA.md
# Esquema de Base de Datos
## Motor
[ej. Cloudflare D1 (SQLite), PostgreSQL, MySQL]
## Tablas
### `users`
| Columna | Tipo | Restricciones | Descripción |
|---------|------|---------------|-------------|
| id | TEXT | PK | UUID |
| email | TEXT | UNIQUE, NOT NULL | Correo del usuario |
| name | TEXT | NOT NULL | Nombre para mostrar |
| created_at | TEXT | NOT NULL, DEFAULT now | Marca de tiempo ISO |
### `posts`
[Mismo formato]
## Relaciones
[Claves foráneas, patrones de unión, reglas de cascada]
## Índices
[Índices no primarios y por qué existen]
## Migraciones
- Generar: `npx drizzle-kit generate`
- Aplicar local: `npx wrangler d1 migrations apply DB --local`
- Aplicar remoto: `npx wrangler d1 migrations apply DB --remote`
## Datos de Seed
[Referencia al script de seed si existe]
Reglas de Calidad
- Documenta lo que existe, no lo planeado — lee el código real, no inventes endpoints ni tablas
- Incluye versiones — extráelas de package.json/archivos de bloqueo, no de memoria
- Muestra formas de respuesta reales — copia los tipos de TypeScript o esquemas Zod del código
- Mantenlo escaneable — tablas en lugar de párrafos, bloques de código en lugar de prosa
- No dupliques CLAUDE.md — si la información de arquitectura ya está en CLAUDE.md, muévela a ARCHITECTURE.md o haz referencia a ella
- Señala vacíos — si encuentras rutas no documentadas o tablas sin un propósito claro, anótalas con
<!-- TODO: documentar propósito -->
Actualizar Documentación Existente
Si ya existen documentos:
- Lee el documento existente
- Compara con el código base actual
- Muestra al usuario qué ha cambiado (nuevos endpoints, tablas eliminadas, pila actualizada)
- Aplica actualizaciones preservando cualquier nota o sección escrita a mano
Nunca sobrescribas silenciosamente contenido personalizado que el usuario haya agregado a sus documentos.