English · Español

Guía de estilo¶

Por §0.2 de LYNX_CORTEX.md. Este es el contrato al que se ciñen el código, las matemáticas, los diagramas y los logs de cada fase.

Código¶

Python 3.11. Tipado (typing), linted (ruff), formateado (ruff format), testeado (pytest).
Las funciones y módulos públicos llevan docstrings; los helpers internos pueden quedar escuetos.
Nada de comentarios que repitan el código. Reserva los comentarios para el por qué no obvio — una restricción oculta, un invariante sutil, un workaround para un bug específico.
El README.md por módulo (bajo src/<module>/) cubre: propósito, API pública, notas de diseño, notas de rendimiento.
Imports: librería estándar → terceros → local; ordenados alfabéticamente dentro del grupo; ruff lo impone.

LaTeX en los notebooks markdown; usa $...$ inline y $$...$$ para displayed.
Cada fórmula lleva una glosa de una línea en lenguaje llano justo debajo.
Vectores: bold minúscula \mathbf{x}. Matrices: bold mayúscula \mathbf{A}. Tensores de rango ≥ 3: caligráfica \mathcal{T}.
Índices: i, j, k para espaciales; t, s para posición de secuencia; b para batch; h para head.
Probabilidades: p para el modelo, q para los datos (evita la ambigüedad habitual p_model vs p_data).

Flujo / arquitectura: mermaid (*.mmd), renderizados a SVG y commiteados.
Tensores / distribuciones / curvas de entrenamiento: matplotlib, exportados como PNG.
Grafos de cómputo: graphviz (*.dot), renderizados a SVG.

JSON estructurado vía structlog. Una clave por hecho; nada de blobs formateados como string.
A partir de la Fase 30, emitir también el formato de exposición de Prometheus para métricas de runtime.

Cada script acepta --seed, --log-dir, --config <yaml> (o usa valores por defecto razonables).
Cada checkpoint lleva un side-car .json con SHA de git, hash de configuración, hash del manifiesto de datos, versiones de librerías.

Atómicos por concepto. Un concepto = un commit (o un PR si hay branch).
Título en modo imperativo. El cuerpo explica el por qué y cualquier número medido.