Onboarding PIVOT

Cómo llevar un proyecto Flask hecho con IA desde 'sin versionar' hasta aprobado por el DTI: versionado seguro, exploración con Claude Code, revisión contra el checklist técnico e informe de salida que genera el backlog de mejoras.

Caso de uso — Proyecto Flask desarrollado con IA, en el PC de un usuario, que necesita integrarse a la infraestructura institucional.

Esta guía usa PIVOT como ejemplo, pero el flujo aplica a cualquier desarrollo emergente con IA que llega al DTI. La meta es concreta: pasar de un proyecto no conforme (🔴) a uno aprobado (🟢) según el checklist técnico de la política de desarrollos externos a la DTI.

0. Contexto realista

Antes de “ordenar el código” hay que entender el punto de partida. Un proyecto típico hecho con IA llega así:

No está versionado. No hay repositorio Git: todo vive en una carpeta del PC del desarrollador.
Es un monolito Flask. Un app.py enorme, decenas de .py planos, frontend en un solo archivo JS gigante. Modularización incompleta o inexistente.
Base de datos embebida. SQLite en un archivo (*.db) junto al código, sin ORM: consultas SQL crudas dispersas.
Secretos y basura en el árbol. Archivos .env, certificados (*.pem), respaldos .db de decenas de MB, carpetas outputs/ y uploads/. Si haces git add . sin preparar, todo eso queda en el historial para siempre.
Corre en un PC. App de escritorio / bandeja del sistema, HTTPS autofirmado, respaldos a un Drive personal.
Maneja datos sensibles. Si integra un sistema contable, de RRHH o financiero, su nivel de riesgo es ALTO o CRÍTICO y los controles del Anexo D no son opcionales.

Nada de esto descalifica al proyecto. La política contempla exactamente este escenario. Lo que sigue es el camino ordenado para sanearlo sin perder trabajo.

🔴 No conforme            🟡 Con condiciones           🟢 Aprobado
  sin git, secretos    →   versionado, sin secretos  →   dockerizado en
  expuestos, SQLite        propuestas en curso           infra DTI, integrado

1. Requisitos previos

Instala en tu máquina de desarrollo:

Git — control de versiones del DTI. macOS: brew install git · Windows: git-scm.com · Linux: sudo apt install git
Python 3.10+ — verifica con python3 --version. Linux: sudo apt install python3 python3-venv python3-pip
Node.js 20+ — necesario para Claude Code y OpenSpec. Verifica con node --version.

La instalación detallada de VS Code, Git, OpenSpec y Claude Code está en la Guía de Herramientas. Aquí solo lo específico de PIVOT.

2. Fase 0 — Entorno y versionado seguro

Esta es la fase más urgente y donde más se equivoca la gente. El orden importa: el .gitignore va antes que git init.

2.1 Instalar las herramientas de IA

# Claude Code (agente de desarrollo)
npm install -g @anthropic-ai/claude-code

# OpenSpec (gestión de cambios del DTI)
npm install -g @fission-ai/openspec
openspec --version    # debe responder 1.x o superior

El paquete correcto es @fission-ai/openspec. El paquete openspec a secas en npm es un stub vacío (v0.0.0) — no lo instales.

2.2 Blindar el repositorio ANTES de inicializarlo

Crea el .gitignore en la raíz del proyecto primero. Esto evita filtrar datos financieros, certificados y respaldos al historial de Git:

# Bases de datos y respaldos
*.db
*.db.*
*.sqlite3
backups/

# Secretos y certificados
.env
.env.*
!.env.example
*.pem
*.key

# Artefactos generados
outputs/
uploads/
*.log

# Python
__pycache__/
*.pyc
.venv/
.pytest_cache/

2.3 Inicializar Git y verificar que NO hay secretos

cd /ruta/al/proyecto

git init
git add .

# GATE: revisar qué quedaría rastreado ANTES del primer commit
git status
git ls-files | grep -E '\.(db|pem|key|env|log)$|backups/|outputs/|uploads/'

Si el grep devuelve cualquier línea, el .gitignore no está cubriendo algo: corrígelo y vuelve a git add . antes de continuar. Solo cuando ese comando no devuelve nada:

git commit -m "chore: estructura inicial versionada (sin secretos ni datos)"

2.4 Publicar en GitLab institucional

git remote add origin [email protected]:dti/<proyecto>.git
git branch -M main
git push -u origin main

El repositorio debe ser privado. La gestión de credenciales (token / SSH) y la configuración de ramas la coordina el DTI.

2.5 Aprovechar el `CLAUDE.md` existente

Si el proyecto ya tiene un CLAUDE.md en la raíz (PIVOT lo tiene), no lo reescribas desde cero: es la memoria del agente. Claude Code lo lee al inicio de cada sesión. Tu trabajo es mantenerlo actualizado cuando cambien stack, convenciones o integraciones. Si no existe, créalo siguiendo la estructura de la Guía de Inicio.

3. Fase 1 — Exploración asistida por IA

Antes de proponer cambios hay que entender qué hay. Desde Claude Code, dentro del repo, usa estos prompts.

Prompt de mapeo del proyecto:

Explora la estructura de este proyecto y genera un reporte en
docs/exploration-report.md con:
1. Módulos/archivos principales y su responsabilidad
2. Rutas/endpoints y a qué módulo pertenecen
3. Esquema de la base de datos: tablas, relaciones y campos sensibles
4. Integraciones externas (sistemas, tipo de conexión, credenciales usadas)
5. Deuda técnica: duplicación, archivos muertos, acoplamientos
6. Riesgos de seguridad evidentes
No modifiques código todavía. Solo el reporte.

Prompt de evaluación contra el checklist técnico (Anexo D):

Evalúa este proyecto contra el checklist de evaluación técnica del
Anexo D de la política de desarrollos externos a la DTI (áreas:
Seguridad, Código, Datos, Operabilidad, Integraciones).
Para cada control indica: cumple / no cumple / parcial, con la
evidencia concreta del repo. Marca cuáles son CRÍTICOS.
Escribe el resultado en docs/autoevaluacion-anexo-d.md.

El resultado es una autoevaluación. No reemplaza la revisión del Mentor DTI, pero le da contexto y acelera la Fase 2.

4. Fase 2 — Revisión del Mentor DTI e informe de salida

El Mentor Técnico DTI revisa el proyecto aplicando el checklist del Anexo D y entrega un informe de salida. Este informe es el entregable clave: clasifica el proyecto y, sobre todo, genera el backlog de mejoras.

Resultado global posible:

Estado	Criterio	Acción
🟢 Verde	Todos los CRÍTICOS cumplidos	Dockerización e integración a infra DTI
🟡 Amarillo	Sin CRÍTICOS incumplidos, con ALTOS pendientes	Lista de correcciones (plazo acordado)
🔴 Rojo	Al menos un CRÍTICO incumplido	Escala a decisión formal del DTI

Plantilla del informe de salida (una fila por hallazgo):

#	Hallazgo	Control Anexo D	Severidad	Propuesta de mejora
1	Secretos en el árbol del repo	S-01 / C-02	🔴 Crítico	`pivot-git-y-secretos`
2	Corre solo en PC del usuario	O-02	🔴 Crítico	`pivot-dockerizar-infra-dti`
3	BD embebida SQLite, sin ORM	Stack D.1	🟡 Alto	`pivot-sqlite-a-postgres`
4	Auth local sin SSO institucional	Stack D.1	🟡 Alto	`pivot-auth-sso-unach`
5	Monolito `app.py`, capas mezcladas	C-06	🟡 Medio	`pivot-modularizar-app`

El informe de salida con datos reales del proyecto (hallazgos concretos, integraciones, responsables) es un documento interno, no se publica en esta wiki.

5. Fase 3 — Del informe a propuestas OpenSpec

Cada hallazgo del informe se convierte en una propuesta OpenSpec independiente y rastreable. No se “arregla todo de una”: cada propuesta sigue su ciclo completo.

explore  →  propose  →  apply  →  verify  →  archive
 (pensar)  (proponer)  (aplicar) (verificar) (cerrar)

Desde Claude Code, para cada hallazgo:

# 1. Pensar el problema (no implementa)
/opsx:explore pivot-sqlite-a-postgres

# 2. Crear la propuesta con sus artefactos
/opsx:propose pivot-sqlite-a-postgres

# 3. Implementar las tareas
/opsx:apply pivot-sqlite-a-postgres

# 4. Verificar contra el spec
/opsx:verify pivot-sqlite-a-postgres

# 5. Archivar el cambio completado
/opsx:archive pivot-sqlite-a-postgres

Cada cambio entra a main por un Merge Request revisado por el Mentor DTI — nunca commits directos. El flujo de ramas y PRs está en la Guía de Contributing.

Ejemplos de propuestas derivadas del informe

pivot-git-y-secretos — purgar secretos del historial si se filtraron, rotar credenciales/certificados, consolidar .env.example.
pivot-sqlite-a-postgres — migrar a PostgreSQL e introducir una capa ORM (p. ej. SQLAlchemy), reemplazando el SQL crudo de forma incremental.
pivot-dockerizar-infra-dti — empaquetar para correr en infraestructura DTI, no en el PC de un usuario. El detalle de Dockerfile y pipeline está en la Guía de Docker y CI/CD.
pivot-auth-sso-unach — reemplazar la autenticación local por SSO institucional @unach.cl.
pivot-modularizar-app — separar el monolito en capas (presentación / lógica / acceso a datos), continuando la modularización propia del proyecto.

Decisión abierta: ¿Flask se mantiene o se migra?

El stack institucional preferente es Python/Django o Node/NestJS. Un proyecto Flask maduro (decenas de miles de líneas) plantea dos caminos legítimos:

Excepción documentada — se mantiene Flask; el Mentor DTI registra la justificación (madurez, costo de reescritura) y se refuerzan los controles del Anexo D.
Migración — Flask se trata como deuda y se planifica el cambio de framework como una propuesta más.

Esta guía no decide por ti. La elección la toma el informe de salida del Mentor DTI según la madurez y criticidad del proyecto.

6. Referencias

Guía de Inicio — conceptos e integración de proyectos IA al DTI
Guía de Herramientas — instalación de VS Code, Git, OpenSpec y Claude Code
Guía de Contributing — ramas, Merge Requests y templates de prompts
Guía de Docker y CI/CD — dockerizar Flask y pipeline GitLab
Lineamientos Técnicos — Variables de Entorno — manejo de .env y secretos
Lineamientos Técnicos — Seguridad — controles de seguridad esperados