Este proyecto propone un sistema ligero de documentación dentro del propio repositorio, pensado como una base de conocimiento compartida entre personas desarrolloras y agentes de IA que programan código. La idea central es que ambos trabajan mejor cuando el contexto es local, duradero y fácil de localizar: sin documentación persistente, cualquier cambio obliga a deducir el comportamiento del producto, los límites del sistema, la terminología del dominio y las restricciones arquitectónicas a partir de archivos sueltos, comentarios, incidencias e instrucciones puntuales, lo que ralentiza las contribuciones y aumenta el riesgo de romper suposiciones implícitas.
El sistema se apoya en dos pilares. El primero es un archivo AGENTS.md en la raíz del repositorio, que actúa como índice y guía operativa para los agentes: explica que la documentación detallada vive en la carpeta docs/, remite a esa carpeta y a sus secciones (sistemas, flujos, arquitectura, glosario) y establece reglas como leer los documentos relevantes antes de modificar un sistema y actualizarlos cuando cambie el comportamiento. El segundo pilar es la propia carpeta docs/, organizada en archivos Markdown revisados junto al código y estructurada en áreas bien diferenciadas.
La carpeta docs/ se divide en varias secciones. En docs/systems/ se documenta cada sistema del proyecto (autenticación, facturación, notificaciones, trabajos en segundo plano, búsqueda, etc.) explicando los archivos fuente clave, conceptos, puntos de entrada, dependencias, invariantes, modos de fallo y notas de depuración. En docs/flows/ se recogen los comportamientos que cruzan varios sistemas o que tienen suficiente entidad propia (verificación de correo, renovación de suscripciones, procesamiento de webhooks, onboarding), con sus disparadores, pasos, cambios de estado, errores y observabilidad. En docs/architecture/ se describen patrones transversales, límites entre sistemas y decisiones técnicas duraderas, incluyendo registros de decisiones arquitectónicas (ADR) en docs/architecture/decisions/, con estados Proposed, Accepted o Superseded. Además existen docs/glossary.md para fijar la terminología, docs/STYLE.md para imponer un estilo de redacción coherente y docs/templates/ con plantillas reutilizables para documentar sistemas, flujos y ADR.
El sistema no necesita herramientas de generación de documentación, infraestructura de publicación ni plataformas externas: se basa en archivos de texto plano versionados junto al código. Cualquier cambio relevante en el comportamiento, las responsabilidades, los flujos, las invariantes o las suposiciones debe arrastrar una actualización de la documentación correspondiente en la misma revisión, de modo que ambos crezcan juntos. AGENTS.md se mantiene deliberadamente breve como capa de enrutamiento; la explicación detallada de cómo funciona la aplicación vive en docs/.