Andy-zch/agent-skills

Mapa Lógico del Proyecto

Ayuda a los mantenedores y a la IA a responder: qué cambiar, dónde impacta, qué no se debe romper y cómo verificar.

Elegir el Alcance de la Tarea

• Generación inicial: A partir de los requisitos y la evidencia del código, generar un mapa de relaciones en Markdown. Cuando el usuario necesite una vista visual o ya exista un HTML, generar o mantener simultáneamente el diagrama visual.
• Actualización incremental: Conservar los identificadores estables, actualizar solo los hechos, relaciones, estados y diagramas que cambien. Verificar las referencias a nodos eliminados.
• Análisis de impacto: En torno a un cambio dado, rastrear entradas, consumidores, estados, ramas excepcionales, restricciones y validaciones; cuando el usuario solo solicite el análisis, no implementar cambios.

Priorizar el uso de archivos e identificadores existentes del proyecto. Para proyectos nuevos, el valor predeterminado es generar docs/LOGIC_MAP.md; la versión visual predeterminada es docs/logic-map.html. Se da prioridad a nombres existentes o ubicaciones especificadas por el usuario.

Primero Investigar, Luego Construir Relaciones

Leer las convenciones del proyecto, la línea base de requisitos, los puntos de entrada clave, las páginas/espacios de trabajo, el estado y almacenamiento, los flujos de negocio, las pruebas y los registros de publicación. Recorrer el código necesario a lo largo de las tareas principales del usuario, sin necesidad de examinar exhaustivamente cada archivo del repositorio.

Distinguir claramente: compromisos de requisitos, implementación real, evidencia de verificación automatizada, verificación del entorno de ejecución y auditoría externa. Los registros antiguos deben marcarse con la fecha y el alcance de la evidencia; las comprobaciones no ejecutadas no deben documentarse como aprobadas.

Enfoque de seguimiento:

• Si múltiples puntos de entrada realmente comparten la misma cadena de procesamiento y cuáles omiten ciertos pasos.
• Quién crea, posee, consume, sobrescribe, libera los datos, y si estos se persisten o salen de la máquina local.
• Cómo terminan cada uno de los casos: cancelación, datos vacíos, rechazo, exceder límites, fallo de análisis.
• Si las actualizaciones de alta frecuencia, lotes, umbrales, etc., conllevan invariantes específicas del proyecto.

Cuando se encuentren conflictos entre la documentación y el código, registrar ambos por separado, sin fusionarlos forzosamente para que el diagrama se vea bien. Si se detectan riesgos en el código, se pueden registrar como brechas, sin expandir automáticamente la tarea para repararlos.

Construir un Modelo Trazable

Leer references/model.md y adoptar sus campos de nodo, relación y evidencia; simplificar o ajustar según la numeración existente del proyecto.

Primero escribir la definición de una oración de la tarea principal y la cadena principal, luego completar las ramas normal y excepcional, el estado entre páginas, interfaces, restricciones y validaciones. En el diagrama, adyacencia no implica relación; cada borde debe poder explicar su significado y fundamento.

Estructura de entrega predeterminada:

1. Resumen de capacidades: Permitir que el lector sepa primero qué puede hacer el producto. Agrupar según tareas reales de usuario; no equiparar la cantidad de diagramas técnicos con la cantidad de capacidades, ni fijarse en los cinco grupos de este ejemplo.
2. Flujo de capacidades individuales: Desplegar puntos de entrada, acciones, procesamiento, estado y salidas, marcando las condiciones de ramificación.
3. Descripción de nodos y evidencia: Responsabilidad, relaciones directas, ubicación de implementación, restricciones, validación y estado.
4. Índice de impacto de cambios: Correspondencia entre cambios comunes y nodos, archivos y comprobaciones.

El resumen puede omitir relaciones secundarias, pero el modelo completo o la descripción de nodos debe poder recuperarlas. El documento de requisitos sigue siendo responsable de la decisión de los requisitos; el mapa no debe establecer una nueva línea base de requisitos.

Entrega Visual HTML

Cuando se necesite HTML, leer references/visual.md. Si se requiere una referencia específica, consultar references/wechat-example.html; es un ejemplo de un proyecto implementado, no una plantilla de diseño genérica o fija.

Permitir que los nodos y los bordes semánticos compartan un mismo conjunto de datos. Las coordenadas de vista, la ruta y el tema se gestionan por separado; Markdown y HTML utilizan el mismo ID. Para proyectos simples, se puede mantener directamente una estructura de datos pequeña, sin forzar la introducción de un generador o una biblioteca de gráficos.

Conservar la dirección visual ya confirmada por el usuario. El diseño predeterminado es: centrado con ancho limitado, entrada al resumen de capacidades, navegación por flujo de capacidades individuales, descripción debajo del diagrama y temas claro y oscuro. La cantidad de nodos y la forma de dividir los diagramas se determinan por la densidad del contenido.

No copiar la terminología específica de WeChat, umbrales de tamaño, estado pendiente de verificación o coordenadas manuales del ejemplo a otros proyectos. Cuando la agrupación raíz del producto sea solo para mostrar la estructura, marcarla claramente y no tratarla como una nueva capacidad de negocio.

Verificación y Entrega

Contenido y estructura:

• Los ID son únicos; los extremos de los bordes existen; las capacidades clave tienen puntos de entrada de profundización; no hay referencias colgantes a nodos eliminados.
• Inclusión, flujo de datos, dependencias, restricciones y validación tienen cada una su semántica, sin mezclarlas como orden de ejecución.
• El ciclo de vida del almacenamiento, las salidas excepcionales, las ubicaciones de implementación y los estados pueden ser respaldados por evidencia.
• Preguntarse una vez por un cambio específico, por ejemplo, "¿cambiar el diseño de la página qué afecta?", el mapa debería poder rastrear hasta los estados, consumidores y validaciones relevantes.

La versión visual también debe verificarse abriendo realmente el navegador:

• El resumen muestra simultáneamente todas las capacidades principales, el texto es claro, las flechas no atraviesan nodos ni texto.
• Abrir los flujos de capacidades uno por uno, verificar la profundización, las relaciones entre diagramas, el estado de selección y la deselección.
• Verificar el texto, nodos, líneas, flechas y descripciones en los temas claro y oscuro; capturar capturas de pantalla.
• Verificar la integridad del resumen en el tamaño de escritorio objetivo; en ventanas estrechas, mantener un tamaño de letra legible, permitir el desplazamiento dentro del diagrama o dividir en subdiagramas.

Las comprobaciones estáticas de sintaxis o estructura no pueden reemplazar la verificación visual. Cuando el navegador no esté disponible, entregar los archivos y marcar claramente las comprobaciones incompletas; no usar capturas de pantalla antiguas para hacerse pasar por el resultado actual.

Entregar enlaces, cambios principales en las relaciones, resultados de verificación reales y brechas restantes. Guardar el trabajo según las convenciones Git del proyecto; no publicar sitios web por cuenta propia ni instalar Skills globales.