English · Español

Motivación — por qué higiene antes que IA (AI)

La trampa

Cada currículo de aprendizaje automático (machine learning) que se salta la Fase 0 acaba igual: alguien consigue un resultado, no puede reproducirlo a la mañana siguiente, y dedica dos días a rehacer la semana anterior. O peor — produce un resultado que nadie puede verificar, declara que es "suficientemente bueno" y entrega un modelo con una regresión silenciosa. La disciplina de reproducibilidad, higiene y tooling consciente de amenazas es lo único que nos permite confiar en las siguientes 40 fases.

No estamos aprendiendo tooling de Python porque sí. Lo aprendemos para que las preguntas que un yo-futuro hará — "¿por qué la pérdida saltó en la época 7?", "¿esta ejecución usó bf16 o fp32?", "¿cuál era la semilla?" — tengan respuestas que podamos leer del disco, no adivinar.

La fase 0 no va de Python. Va de poder responder, a la mañana siguiente, qué exactamente corrí ayer. Si no puedo, no puedo iterar.

Qué te compra esta fase

Al final de la Fase 0, cada script que ejecutemos en este repo va a:

1. Sembrar todos los RNG al entrar (seed_everything(seed) desde src/utils/seeding.py).
2. Persistir {seed, versions, config, git sha, hardware} en experiments/<date>-<topic>/manifest.json.
3. Estar tipado (mypy --strict sobre src/).
4. Pasar el linter (ruff check + ruff format).
5. Ser testeable (pytest, determinista, con el fixture autouse de seed).
6. Tener un árbol de dependencias auditado (uv.lock, escaneado por pip-audit, y el fuente escaneado por bandit).
7. Tener sus outputs eliminados de los notebooks (nbstripout + nbqa-ruff + nbqa-mypy vía pre-commit).
8. Correr dentro de una sesión de Claude Code personalizada que carga CLAUDE.md y usa los slash commands + subagentes del proyecto.

Si alguno de estos se rompe, el ritual por fase se detiene hasta arreglarlo. Ese es el objetivo.

Qué no cubre esta fase

• Nada de NumPy. Nada de mates. Nada de modelos. Nada de tokenizers. Nada de código fuera de src/utils/.
• Nada de "fijemos también MLflow / DVC / marimo / quarto". Están en pyproject.toml como grupos opt-in, instalados solo cuando llegue su fase motriz (según PROPOSAL_REVIEW.md §6).
• Nada de UI web para el espacio del learner. Solo estructura de directorios — learners/<name>/ funciona para un learner y para N learners por igual. Sin auth, sin DB, sin servicio hosteado.

El contrato pedagógico que estás aceptando

La Fase 0 es la primera vez que firmas el contrato de LYNX_CORTEX.md §0.1 con acciones, no solo con palabras. El contrato tiene seis cláusulas; la más violada es cláusula 2: construye antes de abstraer. Te tentará en la Fase 4 "importar SciPy para el SVD" — y tendrás razón en que sería más rápido. Pero el contrato dice: escribe primero las rotaciones de Jacobi a mano, después compara contra SciPy. La Fase 0 es donde conectas las puertas que hacen esa comparación auditable.

Por qué cada herramienta de abajo es innegociable

Herramienta	Qué previene
uv + uv.lock	"funciona en mi máquina" — distintas deps transitivas producen distinta numérica
seed_everything	Curvas de pérdida no reproducibles, tests inestables, regresiones "fantasma"
ruff (lint + format)	Debates de estilo en commits; bugs sutiles (imports muertos, defaults mutables)
mypy --strict	Bugs de forma de tensor, mal manejo de Optional, propagación silenciosa de Any
pytest + autouse seed	Tests que pasan una vez y fallan mañana
pre-commit	"Lo arreglo después" — el después nunca llega
bandit	pickle.load(untrusted), subprocess(shell=True, user_input), criptografía débil
pip-audit	CVEs conocidas en deps transitivas que viajan en nuestro lockfile
nbstripout	Diffs de notebooks que son 99% ruido de output; secretos filtrados en outputs de celda
CLAUDE.md + .claude/	Cada sesión futura de Claude Code olvida las reglas sin esto

Si un revisor de la Fase 0 no puede auditar tus scripts y reproducirlos mañana, la Fase 0 no está hecha.

Siguiente lectura

→ 01-reproducibility.md — la mecánica de seeds, lockfiles y manifiestos.