Editar un generador de documentos con agentes de IA sin confundir su pila actual y la heredada

## Buscar primero en el código los comandos de inicio y la configuración reales Empieza por los metadatos del paquete, los puntos de entrada de consola, los cargadores de configuración, el manejo de variables de entorno y el código que crea espacios de trabajo durante la ejecución. Cuando entran en conflicto con la documentación, estos elementos ejecutables tienen prioridad. - Confirma qué comando inicia la aplicación principal. - Confirma qué comando expone cualquier servicio heredado o compatible con MCP. - Sigue cada comando hasta su módulo y función reales. - Localiza las plantillas de configuración y el comportamiento predeterminado del espacio de trabajo. - Verifica que todas las rutas mencionadas existan en la copia de trabajo actual. Trata cualquier descripción general obsoleta como contexto histórico, no como prueba de la ruta de inicio actual. ## Decidir si el cambio corresponde a la pila actual o a la heredada Un repositorio puede distribuir una pila de producto actual junto con una biblioteca de una generación anterior que aún presta servicio a un punto de acceso especializado. Antes de editar, identifica qué pila es responsable. La pila actual puede ser responsable de: - la interfaz de línea de comandos y el flujo de incorporación; - la orquestación y la ejecución multiagente; - los agentes de investigación, generación y diseño; - las herramientas al estilo MCP para búsqueda, reflexión, conversión y gestión de tareas; - las utilidades de configuración, registro y espacios de trabajo; - la conversión de HTML mediante navegador y un módulo auxiliar de Node; - las pruebas orientadas a la integración. La pila heredada puede seguir siendo responsable de la generación basada en plantillas, la inducción de diseños, el análisis, la evaluación y un servidor de compatibilidad. No supongas que cambiar un concepto compartido en una pila actualiza la otra. ## Mantener un diseño simple con menos casos especiales y funciones cortas Prefiere diseños que conviertan los casos límite en casos normales, en lugar de acumular ramas condicionales. Resuelve el problema real del repositorio, no un problema de arquitectura hipotético. - Elige una solución directa y operativamente ligera cuando satisfaga el requisito real. - Mantén las funciones cortas, enfocadas y con nombres claros. - Trata la complejidad innecesaria como un defecto. - Más de 3 niveles de sangría indican que se debe reestructurar el código. - No ocultes el flujo de control normal dentro de manejadores de excepciones amplios sin un modo de fallo concreto. - Mantén las críticas en el plano técnico y dirígelas al código, el diseño o los supuestos, no a las personas. El buen criterio se manifiesta en menos casos especiales, superficies más pequeñas y comportamientos fáciles de verificar. ## Añadir anotaciones de tipo y reducir las dependencias al mínimo Aplica convenciones coherentes en toda la pila mantenida: - añade anotaciones de tipo a las funciones y los métodos; - redacta la documentación técnica y los comentarios del código en el idioma definido por el repositorio; - usa el gestor de dependencias, las herramientas de búsqueda del repositorio, las funciones del lenguaje y las API de biblioteca compatibles que estén vigentes; - prefiere las interfaces actuales de serialización y validación a las formas obsoletas; - reduce al mínimo las dependencias y la cantidad total de código; - mantén la definición del paquete raíz centrada en el producto principal; - coloca las dependencias de los subproyectos realmente aislados en sus archivos de dependencias locales. No traslades una dependencia solo por orden. Sepárala únicamente cuando exista una frontera real de ejecución y mantenimiento. ## Seguir un cambio por todas las partes conectadas, incluidos Python y Node Examina toda la ruta responsable del comportamiento que se va a cambiar: - para el comportamiento de línea de comandos, examina en conjunto las definiciones de comandos, los módulos auxiliares compartidos y la carga de configuración; - para la orquestación, examina el coordinador principal y la implementación del agente pertinente; - para el comportamiento de MCP, decide si la responsabilidad corresponde a los servidores de herramientas actuales o al servidor de compatibilidad heredado; - para la exportación y la conversión, examina tanto el lado de orquestación en Python como el lado de conversión en Node; - para los conceptos de generación duplicados, cambia solo la pila responsable, a menos que la tarea abarque explícitamente ambas. Mantén acotado el cambio. No refactorices ambas pilas solo porque aparezcan nombres parecidos en cada una. ## Conservar los nombres de configuración y las ubicaciones de workspace existentes Las claves de configuración, las variables de entorno, el comportamiento de incorporación, las configuraciones de ejemplo y las ubicaciones de los espacios de trabajo existentes forman un contrato de ejecución. Conserva sus nombres salvo que la tarea incluya explícitamente una migración. Las dependencias de navegador y contenedor pueden ser requisitos normales de ejecución para las rutas de conversión, y no extras opcionales de desarrollo. Las herramientas de conversión nativas, las credenciales de modelos, la automatización del navegador y las imágenes de contenedor también pueden determinar qué pruebas de integración se pueden ejecutar. Al cambiar una ruta de ejecución: 1. Identifica todas las fuentes de configuración y los valores predeterminados. 2. Sigue cómo el proceso de incorporación y los ejemplos rellenan esos valores. 3. Comprueba el componente que realiza la llamada en Python y cualquier módulo auxiliar de conversión externo. 4. Conserva la compatibilidad o proporciona una ruta de migración explícita. ## Comprobar los documentos viejos con el código y clasificar las pruebas por lo que necesitan Antes de confiar en lo que afirma la documentación, contrástalo con el árbol de archivos actual y los puntos de entrada ejecutables. Los documentos antiguos pueden seguir explicando conceptos útiles aunque mencionen archivos eliminados o flujos de inicio obsoletos. Clasifica las pruebas según sus requisitos: - pruebas unitarias para lógica aislada; - pruebas de analizadores o pruebas marcadas para rutas de datos especializadas; - pruebas de integración para herramientas de entorno aislado, conversión mediante navegador o a PDF, procesamiento de imágenes y utilidades externas; - pruebas respaldadas por modelos que requieren credenciales o servicios en red. La ausencia de un navegador, una imagen de contenedor, un conversor nativo o credenciales de modelos es una limitación de la validación, no una prueba de que un código ajeno esté roto. ## Ejecutar las pruebas mínimas útiles e informar lo que no se pudo ejecutar Sigue una secuencia de cambios bien acotada: 1. Confirma qué pila y qué punto de entrada son responsables del comportamiento. 2. Edita la superficie completa más pequeña. 3. Ejecuta el subconjunto de pruebas significativo más reducido. 4. Amplía el alcance únicamente a rutas de Python, Node, navegador, contenedor o compatibilidad que estén acopladas directamente. 5. Informa de cualquier dependencia o requisito del entorno que haya impedido la validación. Revisa las diferencias finales para detectar cambios accidentales en la otra pila, contratos de configuración renombrados, referencias a documentación obsoleta, refactorizaciones ajenas y fronteras multilingües sin probar. Informa de qué cambió, qué ruta se ejercitó, qué comprobaciones se superaron y cuáles no pudieron ejecutarse. No afirmes que la validación está completa cuando no esté disponible una dependencia necesaria para la ejecución.