Crear una biblioteca de datos con API fáciles de encontrar y pruebas con valores reales

## Oculta los datos de origen complejos tras objetos sencillos Oculta la complejidad del formato de origen detrás de objetos de dominio intuitivos sin esconder capacidades importantes. Permite realizar directamente las operaciones habituales y presenta de forma progresiva las funciones especializadas de análisis, generación de informes e inspección cuando los usuarios las necesiten. Lee antes de escribir. Antes de modificar código, examina las abstracciones existentes, los patrones de nomenclatura, los límites entre módulos y las pruebas cercanas. Amplía el diseño actual salvo que una incompatibilidad concreta exija un patrón nuevo. ## Antes de editar, traza qué módulo se encarga de cada tarea Mantén un mapa de navegación conciso que conecte las necesidades de los usuarios con los módulos responsables y las clases de dominio principales. Incluye los puntos de entrada públicos para localizar registros, cargar entidades, analizar datos estructurados, construir estados, leer notas, abrir documentos y crear informes tipados. Antes de editar, sigue de principio a fin flujos de datos representativos. Acompaña una solicitud desde su punto de entrada público a través de la obtención, el análisis, los objetos tipados, los estados, las notas, los informes y la extracción de documentos. Confirma qué capa es responsable de cada transformación y desde dónde deben profundizar los usuarios para consultar los detalles que la respaldan. Usa el mapa para elegir el módulo responsable más pequeño. No coloques un comportamiento en un archivo conveniente cuando otra capa ya sea responsable de él. ## Lee los archivos grandes por partes y limita los cambios a lo necesario Trata los módulos de más de 30 KB como varios contextos locales, en vez de leerlos o reescribirlos como un solo bloque. Busca el símbolo pertinente, examina la clase o función que lo contiene y lee después suficiente código adyacente para comprender las invariantes y los lugares desde los que se invoca. Antes de cambiar un archivo grande, localiza las pruebas, importaciones, subclases y referencias públicas relacionadas. Mantén el parche acotado, conserva las convenciones del entorno y evita cambios de formato o reestructuraciones ajenos que oculten el cambio funcional. ## Registra y actualiza el trabajo en el sistema de incidencias Usa el sistema de incidencias del proyecto como registro duradero del trabajo activo. Revisa los elementos abiertos y en curso, selecciona la incidencia correspondiente y pásala al estado activo antes de implementar. Registra los defectos o tareas recién descubiertos con un título, un tipo y una prioridad claros, en lugar de dejarlos solo en comentarios o conversaciones. Actualiza la misma incidencia cuando cambien el alcance, los bloqueos o las conclusiones. Ciérrala solo después de completar la verificación necesaria. Conserva los estados definidos para el trabajo `open`, `in-progress`, `blocked` y `closed`. Cuando el sistema use una escala de prioridad de cinco niveles, mantén `0` para el trabajo crítico y `4` para el backlog, en vez de inventar etiquetas improvisadas. ## Comprueba que la biblioteca cumple lo que promete su documentación La verificación pregunta si la biblioteca cumple lo prometido en su documentación, no solo si el código interno se ejecuta. Aplica tres principios rectores: 1. La documentación es la especificación, por lo que todo ejemplo documentado debe poder verificarse. 2. La exactitud de los datos es esencial, por lo que las comprobaciones deben afirmar valores esperados concretos y no limitarse a confirmar que algo existe. 3. La API debe permitir resolver el problema, por lo que los usuarios y los agentes deben poder avanzar desde una pregunta hasta el objeto, el método y las pruebas de respaldo adecuados. Usa estos principios para evaluar conjuntamente el diseño de la función, la documentación, los casos de prueba y el comportamiento ante fallos. ## Da a cada función nueva una prueba con valores reales y un ejemplo ejecutable en la documentación Toda función nueva orientada al usuario debe incluir: - una aserción de referencia basada en un valor concreto de un registro de origen real que se haya comprobado de forma independiente; - un ejemplo documentado que también se ejecute como verificación automatizada; - una comprobación contra fallos silenciosos que demuestre que una entrada no válida o ausente produce un error útil, no un valor vacío ni un fallo sin aviso; - una actualización que facilite su descubrimiento, para que la función aparezca en la navegación del proyecto, el catálogo de capacidades o las instrucciones para agentes. La función está incompleta si falta cualquiera de estos elementos, aunque funcione la implementación de su ruta normal. ## Ejecuta primero las pruebas locales rápidas y las de red de una en una Proporciona comandos distintos para la verificación local rápida, la verificación con red, la verificación de regresión y los informes de cobertura. Ejecuta primero la comprobación local pertinente más pequeña y amplía el alcance solo cuando pase ese resultado focalizado. Paraleliza únicamente las pruebas rápidas que no contacten con servicios externos. Ejecuta la verificación con red de forma secuencial y respeta los límites de solicitudes del servicio. Usa fixtures de respuestas registradas cuando permitan que el comportamiento externo sea rápido y determinista sin ocultar el contrato que se verifica. Coloca las regresiones en un área específica con nombres estables que vinculen cada caso con el defecto que lo originó. Trata la cobertura como prueba complementaria, no como sustituto de las aserciones sobre comportamiento y datos. ## Comprueba valores exactos y errores claros con datos de origen variados Afirma valores de dominio exactos, estructuras normalizadas y mensajes de error significativos. Una aserción que solo comprueba que existe un resultado es insuficiente cuando la exactitud depende del propio valor. Diversifica los registros de origen entre distintas organizaciones, industrias, formatos y periodos de información, en lugar de depender de un único ejemplo conocido. Prueba explícitamente entradas mal formadas, incompletas y no compatibles. Confirma que los fallos devuelven mensajes que indican cómo actuar y que nunca se degradan silenciosamente a un resultado vacío. Cuando se necesiten datos externos, conserva fixtures deterministas y documenta cómo se establecieron sus valores esperados. Actualiza un fixture de forma deliberada cuando cambie el contrato ascendente; no lo renueves únicamente para hacer que pase una comprobación fallida. ## Mantén la versión y la documentación al día con el código que funciona Lee la versión del proyecto desde el archivo de metadatos designado y evita duplicarla en módulos no relacionados. Mantén la navegación del repositorio, las guías de verificación, los ejemplos públicos y los catálogos de capacidades sincronizados con el comportamiento compatible. Cuando cambie una ruta de la API, actualiza la documentación y los ejemplos ejecutables dentro del mismo elemento de trabajo. Una ruta documentada que ya no se ejecuta constituye un contrato roto con el usuario, aunque la implementación que la sustituye sea correcta.