En enero de este año nos fuimos a vivir a una casona en Puerto Varas todos los miembros del Proyecto AFP por 50 días.
Al comienzo de dicho periodo, tomamos una decisión que cambió totalmente la manera en que cada miembro del equipo trabaja. Dicha decisión está relacionada con el uso de inteligencia artificial.
Quiero contarles cómo partió y cómo ha evolucionado el uso de IA para construir una AFP.
Primera etapa: la apuesta
Durante la primera semana de trabajo tomamos la siguiente decisión:
La IA es first-class citizen en este proyecto. Todas las herramientas que usemos y la metodología de trabajo serán AI-first o AI-friendly.
Así como escuchaste.
En enero de 2026 la IA ya estaba mostrándose muy efectiva en la generación de código. Rondaban artículos de desarrolladores que afirmaban que ya no escribían el código por sí mismos. Esta vez no era hype.
Había ocurrido hace muy poco un punto de inflexión. Y decidimos que aquello que veíamos era evidencia de que había que apostar muy fuerte en esa dirección.
El proyecto que queremos construir es realmente titánico. Y no solo es un proyecto grande, es un problema muy pocas veces resuelto. Por ejemplo, considera cuántas AGF existen: son más de 50 AGF vigentes versus 7 AFP. Existen más bancos que AFP, más aseguradoras que AFP, más corredoras que AFP. Y por último, existe solo un proveedor de software en el mercado para operar una AFP.
Entonces no podíamos permitirnos no considerar seriamente el uso en profundidad de herramientas de IA.
¿Y ahora qué?, ¿qué hace uno luego de decidir que usará IA en profundidad?
La primera consecuencia de la decisión anterior fue comenzar a documentar y diseñar todo en Markdown*
Y como consecuencia de ello matamos Notion**. De inmediato y para siempre. Notion fue por años la herramienta donde escribimos documentos y colaboramos. Y, dejando de lado otros problemas que tiene, no es AI-friendly a pesar de que se marketea como que sí lo es.
No podíamos esperar a que Notion eventualmente mejorara. Entonces buscamos varias alternativas, pero ninguna nos convenció. Así que decidimos apostar por la herramienta más básica posible para hablar con máquinas: texto plano.
Rápidamente vimos que era una buena idea: al usar Markdown simple, dentro de un repositorio de código conectado a Claude Code, teníamos la capacidad de interactuar fácilmente con lo escrito, generar diagramas y analizar varios archivos.
Estábamos contentos con el resultado. Pero fue la siguiente etapa la que convenció a todos de que la apuesta era correcta.
Segunda etapa: la regulación
El Compendio de Normas del Sistema de Pensiones es un conjunto de normas, leyes y reglas que definen cómo deben funcionar los actores de la industria. Define, entre otras cosas, cómo funciona una AFP.
Construir una AFP requiere, naturalmente, leer todo el Compendio.
Como ya estábamos interactuando con archivos Markdown y documentando todo dentro de nuestro repositorio, decidimos que el siguiente paso lógico era descargar todo el Compendio y dejarlo como Markdown dentro del proyecto.
Así que eso hicimos.
Benja Kramm y yo (ambos ingenieros de software del Proyecto AFP) trabajamos en la misma tarea en nuestro tiempo libre, usando un scraper para descargar el Compendio. Posteriormente, Benja me ganó un cachipún y usamos el suyo. Y así, todos tuvimos una copia del Compendio en nuestro computador.
Tener el Compendio dentro del repositorio abrió la posibilidad a que la IA lo tuviese a su alcance fácilmente. Por ejemplo, podía pasarle un listado de capítulos y pedirle un diagrama que explicara todo, o un resumen, o que simplemente me ayudara a entender un párrafo que no lograba interpretar.
Tuvimos un par de ideas a través de los días sobre cómo sacarle provecho a esto.
Sin embargo, la idea que cambió todo fue una de Benja: construyó un mecanismo para hacer búsqueda semántica sobre el Compendio.
Hay muchas herramientas que soportan búsqueda. Existe software como Google Docs donde usando Cmd + f (o Ctrl + f en Windows) abre una caja de texto donde escribes una palabra y te dice en qué parte de la pantalla aparece dicha palabra. Normalmente resaltándola en otro color.
La búsqueda semántica es distinta. Porque no busca por palabra, sino que por significado. Entonces, si buscas una palabra como "queso", no solo encontrarás documentos con dicha palabra, encontrarás también documentos que contengan "mozzarella", "havarti", "parmigiano reggiano" e incluso "tofu". Porque todos esos resultados tienen, hasta cierto punto, una similitud semántica.
Si conocen a Benja, sabrán que obviamente no terminó allí. Luego hizo una herramienta para que Claude Code tuviese acceso directo a hacer búsqueda semántica. Y esto cambió para siempre nuestra visión acerca de cuánto hay que apostar por la IA.
Mira el siguiente video:
En ese video:
- Le dije a Claude Code: según el compendio qué cuentas debe ofrecer una AFP.
- Claude Code decide que puede usar una tool (esa que construyó Benja) para buscar en el compendio.
- Claude Code inicia la búsqueda.
- Claude Code lee todos los resultados retornados.
- Claude Code responde.
¿Recuerdas la primera vez que usaste ChatGPT? Esa mezcla de sorpresa y fascinación ante una tecnología que parece magia. Volvimos a sentir lo mismo al usar esta tool. Maravilloso.
Esta nueva herramienta cimentó nuestra manera de trabajar. Ahora teníamos un asistente sumamente rápido y extraordinariamente inteligente ayudándonos a evaluar nuestros diseños. Podíamos buscar argumentos en la regulación a favor o en contra de nuestras ideas. Recabar información se volvió más sencillo. Y generar diagramas o cualquier otro elemento para ayudarnos a entender lo que leíamos era simple.
Tercera etapa: estructurar la nueva capa de comunicación con las máquinas
Este fue, más o menos, el momento donde nos dividimos y cada miembro del Proyecto AFP comenzó a estudiar a fondo un dominio en particular.
A mí me tocó iniciar con Afiliación y Traspaso de Afiliados.
Lo primero que hicimos, obviamente, fue continuar leyendo el Compendio. Pero mucho más enfocados en el tema asignado. La idea era entender cada tema y lograr diseñar una solución.
En algún momento de nuestro trabajo, llegamos a tener un modelo de datos, que básicamente describe qué entidades y qué información están involucradas en cada dominio de la AFP. Luego tuvimos algunos diseños de API, que describen qué acciones permite cada dominio (por ejemplo: generar un certificado). Y eventualmente llegamos a escribir algo de código.
Si bien diseñar un software antes de escribir el código siempre ha sido una buena idea, hoy en día los modelos de IA son muy buenos traduciendo diseños a código. Así que los incentivos para tener muy buenos diseños son bastante grandes.
Ser meticuloso, estructurado, agregar restricciones y proveer de herramientas a la IA tienen como consecuencia que interprete mejor los diseños, generando un mejor código.
Así, empezamos a intuir que la capa de abstracción, aquella que entienden tanto humanos como máquinas, ya no era el código mismo. Dicha capa ahora eran los diseños en Markdown.
Hicimos entonces varias cosas a continuación.
Escribimos mucha documentación sobre todo tipo de temas: cuáles son los principios que debemos seguir para diseñar una base de datos, principios para diseñar componentes de backend, principios para escribir tests, cómo crear commits, cómo escribir pull requests.
Diseñamos convenciones para citar al Compendio y creamos una herramienta para convertir documentos como PDF a Markdown.
Agregamos herramientas para analizar los archivos Markdown y que todos sigan las mismas convenciones. Agregamos también herramientas para encontrar links rotos. Y además, una herramienta para mostrar toda la documentación en un sitio web interno.
Todo con la intención de hacer más uniforme, predecible y accesible esta nueva capa de abstracción.
Trabajar de cerca con estas herramientas nos permitió ver otros problemas. Les contaré de uno que personalmente me hizo sufrir mucho.
Los textos que genera la IA no siempre son fáciles de entender
Personalmente, tengo ideas muy arraigadas acerca de cómo debe estar escrito un documento técnico para entenderlo. Y los textos producidos por IA se alejan bastante de mi modelo mental.
Por lo anterior, me encontré muchas veces gastando energía solamente para entender la forma en que algo está estructurado. Y ni hablar del fondo.
Entonces, tuve un periodo de introspección, preguntándome qué estaba haciendo mal. Y así me di cuenta de un par de cosas.
En primer lugar, estaba escribiendo documentos grandes, de cientos o miles de líneas. Y si bien estaban bien estructurados, con secciones apropiadas, usar archivos Markdown grandes es problemático.
¿Por qué?
Un documento grande en Markdown es difícil de abordar para un humano. Se necesita bastante scroll para saber qué contiene. Si le pides a una IA revisar contra la regulación lo que escribiste, posiblemente te dejará un par de comentarios. Y unas 2 o 3 iteraciones de revisión de un documento de miles de líneas te dejan exhausto.
Además, cuando un documento contiene muchas secciones, la IA tiene la mala costumbre de proponer cambios en secciones no relacionadas, propagando cambios en varios lugares que luego hay que revisar. Y ya establecimos que revisar unas cuantas veces es agotador.
Así fue que decidí implementar la siguiente restricción: todo archivo Markdown debe ser pequeño. 50 líneas es ideal, 100 líneas es excelente, 200 líneas es bueno, 300 líneas es aceptable. Cualquier archivo que pasa las 200 líneas es candidato a ser dividido en múltiples archivos. Y sobre 300 líneas es seguro que será dividido. Obviamente, existen algunas excepciones a lo anterior: por ejemplo, un documento con una transcripción de una conversación o un documento que describe una API, cosas de ese estilo.
Además de lo anterior, decidí numerar los directorios y archivos. Porque en mi modelo mental, hay que entender cuáles cosas deben ser leídas primero y cuáles después. Uno no es adivino para saber con qué archivo comenzar.
Esta idea no es nueva. Sucede también en el código. Los problemas se dividen hasta tener unidades que quepan en el stack mental de una persona.
Estas nuevas restricciones y estructura me ayudaron mucho. Estaba muy contento con este resultado. Pero mis problemas no terminaron allí.
Cuarta etapa: traje a la medida
Me encontré con otro problema aún peor bajo esta nueva solución.
A diferencia del código de programación, el cual tiene una estructura formal y tests, el texto plano no tiene pruebas ni tampoco permite análisis estático para saber si acaso todo sigue funcionando.
¿Qué significa esto?
Si bien ahora tenía archivos pequeños y fáciles de revisar, frecuentemente me encontré con casos donde un cambio en un archivo provocaba cambios en otros archivos. Y cambios en dichos archivos provocaban cambios en otra capa de archivos. Recursivamente.
Entonces ahora mi stack mental no era capaz de mantener ese árbol de cambios para revisarlo.
Pensé por varios días en este problema. Porque me seguían llegando documentos con aclaraciones, nueva información y contexto adicional que cambia distintos aspectos del diseño. Y siendo meticuloso, me costaba incorporar dichos cambios.
Sufrí un buen rato, hasta que decidí que tenía que hacer una herramienta para abordarlo.
En mi mente de desarrollador pensé:
Necesito una herramienta donde cada cambio esté representado por un nodo de un árbol. Donde cada arco entre los nodos A y B signifique: el cambio B existe debido a que cambió A.
Quiero poder ver ese árbol. Necesito poder hacer click en cada nodo y decidir qué hacer: aceptar el cambio, ignorarlo o pedir cambios. Necesito que los cambios que ya validé correctos dejen el nodo en verde.
Si logro revisar los cambios en un árbol así, y el árbol está completamente verde, significa que revisé y validé todo.
Luego de escribir el problema y cómo imaginaba la solución, le pasé a Codex lo anterior. Y después de unas iteraciones logré llegar a lo siguiente:
Es una aplicación que contiene un DAG (un árbol es un tipo de DAG). El DAG me permite de manera interactiva entender cómo y por qué se propagó un cambio desde un lugar del diseño hacia otro.
Al hacer click en un nodo, puedo ver el contexto, en qué consiste el cambio, y por qué exactamente se propagó hasta allí.
Tengo opciones para decidir qué hacer con un cambio en particular.
Y abajo hay un Git diff (herramienta usada por desarrolladores) donde puedo agregar comentarios en cada línea. Similar a GitHub.
Y lo más importante: Claude Code y/o Codex tienen acceso a todo lo que hago en dicha web de manera estructurada.
Algunos podrán pensar qué interesante la herramienta y otros qué mala la herramienta.
Sin embargo, lo realmente importante es: vivimos en una época donde tenemos la capacidad de fabricar este tipo de tecnología simplemente describiendo qué deseamos. Podemos crear tecnología que se ajusta 100 % a nuestro modelo mental. No dependemos de que una empresa o la comunidad se anime a hacerlo. Cada uno puede fabricar la herramienta que necesita. Como un traje a la medida.
Yo no sé si en 2 meses o un año más seguiré usando este DAG.
Pero sé que, sea lo que sea que necesite en el futuro, podré construirlo.
Si tienes ideas sobre cómo usar IA para mejorar la industria previsional, o si tienes preguntas sobre esta entrada de la bitácora, por favor escríbenos proyectoafp@fintual.com.
*Markdown es un formato de texto plano que permite definir elementos como títulos, enlaces o tablas, de forma fácil de leer para humanos (y máquinas).
**Notion es una aplicación de espacio de trabajo tipo todo en uno. Combina documentos, wikis, bases de datos y gestión de proyectos en bloques editables.
