El ZeroClaw Maturity Framework

Una carta para quien encuentre esto.

Si estás leyendo esto, has llegado a una carpeta que representa algo de lo que este equipo está genuinamente orgulloso, no porque los documentos aquí sean perfectos, sino porque son honestos.

ZeroClaw comenzó como algo accidental. Se desarrolló a partir de una base de código existente, moldeada por herramientas de IA que trabajaban más rápido de lo que cualquiera podía comprender completamente, y creció hasta convertirse en una base de código impresionante y funcional, pero con una arquitectura no planificada. Nadie eligió ese resultado. Se acumuló. La mayoría del software lo hace.

Lo que sucedió después es menos común. Un equipo pequeño, muchos de ellos estudiantes, ingenieros en las primeras etapas de su carrera y personas que aprendían en público por primera vez, eligió detenerse y mirar con claridad lo que habían construido, y luego eligió construir de manera diferente. No descartando el trabajo anterior, sino haciendo crecer la intención a su alrededor. Estos documentos son el registro de esa elección.

La serie se llama Maturity Framework porque eso es exactamente lo que es: un conjunto de documentos fundamentales que describen cómo este equipo piensa sobre la construcción de software en conjunto. No son reglas que seguir, sino pensamiento que interiorizar. No es un proceso que cumplir, sino un conjunto de modelos mentales que te acompañan, a través de cada lenguaje, cada herramienta, cada equipo al que te unas, porque tratan sobre el oficio, el criterio y el esmero, no sobre ninguna tecnología específica.

Fueron escritas para un equipo de personas con un amplio rango de experiencia. Algunas aportaban décadas de práctica profesional. Algunas estaban escribiendo su primer código de producción. Todas trabajaban en un momento en que las herramientas de IA se estaban volviendo lo suficientemente poderosas como para cambiar lo que era posible, y en que la pregunta de cómo trabajar bien junto a esas herramientas estaba genuinamente abierta. Fueron escritas por personas que creían que invertir en las personas era una mejor inversión que invertir en el código, porque las personas llevan consigo lo que aprenden, y el código no.

Léelos en este orden si es posible. Cada documento se basa en los anteriores, y la secuencia cuenta una historia. Puedes entrar en cualquier punto y aprender algo útil, pero leerlos desde el principio te da la visión completa: desde la forma de la arquitectura, hasta cómo registramos, coordinamos, enviamos y colaboramos, hasta lo que significa escribir bien el código a nivel de oración.

Si estás intentando decidir qué base aplica a un cambio específico, comienza con el mapa de arquitectura y contribución.

Los primeros cinco documentos responden preguntas estructurales y humanas. El sexto responde la pregunta que subyace en todas ellas: dada la estructura, dado el equipo, dadas las herramientas: ¿qué significa escribir bien el código?

Cada documento de esta serie comenzó como un issue de GitHub, un RFC, abierto a discusión, cuestionamiento y refinamiento por parte de todo el equipo. Los hilos de discusión enlazados arriba son el registro vivo de ese proceso: las preguntas planteadas, las objeciones presentadas y el razonamiento que dio forma al resultado final.

Los archivos en esta carpeta son las versiones ratificadas, documentos que el equipo discutió, respaldó y decidió llevar adelante como referencias canónicas. Residen en este repositorio, versionados junto con el código, porque el pensamiento que representan influye en cada decisión que se toma dentro de él. Un asistente de IA que lea esta base de código, un nuevo colaborador que esté dando sus primeros pasos o un mantenedor que revise una decisión tomada hace dos años deberían poder trazar una línea desde el código hasta el razonamiento que le dio forma.

Los issues de GitHub permanecen abiertos como registros permanentes de discusión. Si tienes una pregunta, un desacuerdo o una perspectiva que estos documentos no recogen, el lugar adecuado para ello es uno de esos hilos o, si estás leyendo esto mucho después de que esas conversaciones se cerraran, una nueva discusión en la comunidad. Estos documentos son referencias, no veredictos. La conversación que iniciaron está pensada para continuar.

Es posible que te unas a este proyecto años después de que se escribieron. Las herramientas habrán cambiado. La base de código se verá diferente. Algunas de las cosas descritas aquí habrán sido superadas, refinadas o reemplazadas por documentos posteriores.

El criterio que estos documentos intentan desarrollar en ti no ha cambiado, y no cambiará. Las preguntas que plantean: qué debería suceder cuando esto falla, qué promete esta interfaz, qué demuestra realmente mi prueba, qué necesitaría saber la persona que herede este problema, no son preguntas de Rust ni preguntas de software. Son preguntas sobre cómo construir cosas en las que otras personas puedan confiar. Esas preguntas son las mismas en cada lenguaje, cada sistema y cada disciplina en la que llegues a trabajar. Se acumulan silenciosamente, en segundo plano, durante todo el tiempo que practiques hacerlas.

Esa es la inversión que esta serie está haciendo en ti. Bienvenido al equipo.

El ZeroClaw Maturity Framework es un cuerpo de trabajo en constante evolución. Se agregan nuevos documentos cuando el equipo ha aprendido algo que vale la pena preservar. Cada uno comienza como una discusión pública de RFC y gana su lugar aquí a través del mismo proceso que los seis anteriores: conversación abierta, desacuerdo honesto y la decisión colectiva del equipo de llevarlo adelante.