Esta semana ha vuelto a la portada de Hacker News un artículo de febrero de 2024 que ya va por 2.544 puntos. Se llama Airfoil y va de cómo vuela un avión. Lo abrí por curiosidad y me quedé una hora dándole a los sliders. No es un vídeo, no es un paper: es una explicación donde tú mueves el aire y ves qué pasa.
Lo que hace distinto a Airfoil
Bartosz Ciechanowski publica un artículo cada muchos meses, y se nota por qué. Cada demostración está construida a mano: flechas de velocidad, campos de presión, capas de aire que se despegan del ala, viscosidad. Tú cambias el ángulo de ataque y miras.
Hay un detalle que me pareció un golpe de oficio. Al principio te enseña el avión desde el suelo, con la cámara fija. No se entiende nada: el avión se sale del encuadre en dos segundos. Luego mueve la cámara y la ata al avión, y de repente el aire viene hacia ti ordenado, y todo encaja. No te explica el sistema de referencia. Te deja ver lo inútil que es el equivocado.
Y mi momento favorito: a mitad del artículo monta un campo de presión inventado, fruto de veinte párrafos de trabajo previo, y demuestra que las partículas de aire lo atraviesan como si el ala no existiera. "Esto está claramente mal", escribe. Te enseña el modelo roto a propósito, para que entiendas por qué el bueno es como es.
La parte que me llevo a mi trabajo
Casi todas mis explicaciones son adjetivos. "El agente es autónomo", "la skill se invoca a demanda", "el cron corre los miércoles". Adjetivos que el otro puede repetir pero no puede tocar. Con los agentes pasa igual: si en la documentación no hay un ejemplo ejecutable, el modelo improvisa y tú te enteras tres días después.
Lo de Ciechanowski es otra cosa. Cada vez que afirma algo, pone un mando para que lo verifiques. La afirmación y la prueba van en el mismo bloque.
Cuando empecé a reescribir mis propios flujos, cambié párrafos por ejemplos. Nada de "sé conciso": un bloque con la respuesta buena y la mala. Nada de "no uses curl en cron": el script que sí funciona y una línea explicando por qué el otro se queda colgado. Funciona mejor por una razón simple: deja de haber interpretación.
Y aprender a cambiar de cámara. El mismo sistema visto desde el prompt, desde el log o desde la factura de la API cuenta tres historias distintas. Si solo miras una, arreglas la mitad.
Si una pieza de tu sistema la lees tú o la lee un agente más de dos veces por semana, merece una demostración, no una descripción.
Lo que cuesta (y por qué no siempre toca)
Ese nivel de detalle no se hace en una tarde. Hace falta una simulación de verdad y muchas horas de front. Nadie documenta así todo su sistema, ni debería intentarlo.
El criterio es el uso, no la elegancia. Lo que se explica una vez al mes aguanta con tres líneas bien puestas. Lo que se repite cada semana —o lo que un agente relee en cada tarea— justifica el trabajo. Y hay otra razón por la que me interesa: una demostración manipulable es también un test. Si no puedes montar un caso mínimo donde se vea funcionar, probablemente no entiendes tu propio sistema, solo lo has visto pasar.
Cierre
Explicar bien no es un adorno de blog, es ingeniería. Un sistema que no sabes explicar es un sistema que no controlas, y con agentes de por medio esa factura llega todos los días.
Volví al artículo sin entender de aerodinámica y salí con ganas de reescribir mis skills. Y el avión, por cierto, sigue volando.