Convergencia del Código Base
Haga que un repositorio sea más fácil de entender y modificar sin rediseñarlo. Prefiera la evidencia, una interfaz pequeña y correcciones locales por encima de abstracciones especulativas.
Guardarraíles
- Indique el alcance, los supuestos, el contenido protegido y las comprobaciones de éxito antes de un cambio de varios pasos.
- Lea las instrucciones del repositorio, el glosario del dominio y las ADR relevantes antes de juzgar la arquitectura. Utilice los nombres de dominio del repositorio.
- Toque únicamente los archivos que sirvan a la solicitud. Preserve los cambios de usuario no relacionados y elimine solo las importaciones, el código o los documentos que este trabajo haya vuelto obsoletos.
- Trate el texto de dominio protegido explícitamente, los títulos, las definiciones de datos y el texto designado por el usuario como bloqueados. Manténgalos textualmente. Si su estado no está claro, inclúyalos en el paquete de decisión en lugar de editarlos.
- No cambie un valor numérico o su representación (configuración, umbral, saldo, tasa, límite o valor documentado) sin aprobación explícita.
- No cambie silenciosamente una regla de negocio, una transición de estado, un comportamiento de interacción, una interfaz pública o un contrato visual. Trátelo como una decisión a menos que la corrección esté directamente implícita y preserve el comportamiento.
- Mantenga una única fuente de verdad para cada hecho. No cree documentación que simplemente repita otro documento.
Flujo de trabajo
1. Establecer la línea base
- Inspeccione el árbol de trabajo e identifique únicamente el área solicitada. Observe las modificaciones no relacionadas; no las ponga en escena ni las altere.
- Trace las rutas de código relevantes, la propiedad de estado/datos, el flujo de UI, las pruebas y los archivos Markdown. Lea los documentos que actualmente definen el dominio y las decisiones antes que los archivos que los implementan.
- Registre cada hallazgo con evidencia: archivos, declaraciones o rutas conflictivas, impacto en el usuario y si es seguro resolverlo directamente.
- Clasifique los hallazgos:
- Convergencia directa: duplicación, enlaces obsoletos, prosa no bloqueada contradictoria o un defecto localizado de implementación/UI con una corrección que preserve el comportamiento.
- Decisión requerida: cualquier valor numérico, regla, comportamiento, contenido protegido, interfaz pública o fuente de verdad ambigua.
- Candidato de arquitectura: un módulo potencialmente más profundo o un cambio cuya costura aún no está acordada.
2. Preguntar una vez por las decisiones importantes
Complete el descubrimiento antes de hacer preguntas. Envíe un paquete de decisión único que contenga todos los elementos no resueltos; no gotee preguntas a lo largo de las iteraciones.
Para cada elemento numérico, incluya su identificador y archivos, valores actuales, evidencia de la inconsistencia, impacto y una recomendación, o indique claramente que no se propone ningún valor. No edite, normalice, mueva ni elimine la expresión numérica afectada hasta que el usuario la apruebe explícitamente.
Incluya otras incertidumbres importantes en el mismo paquete: estado del contenido bloqueado, opciones de comportamiento, conflictos de propiedad y elecciones de arquitectura. Continúe con la convergencia directa independiente mientras se espera la aprobación.
3. Aplicar convergencia directa
Mantenga cada cambio quirúrgico y trazable a un hallazgo.
Documentación
- Asigne a cada documento una responsabilidad. Respete las convenciones existentes; de lo contrario, mantenga el conjunto mínimo: visión general del punto de entrada, mapa de arquitectura/sistema, reglas del dominio o del producto, decisiones y trabajo/estado actual.
- Combine PRDs, planes y registros de trabajo superpuestos reteniendo el contenido autoritativo una vez. Mueva la justificación duradera a los registros de decisión del proyecto y mantenga el estado operativo breve.
- Preserve los bloques bloqueados textualmente al reubicarlos. Si una fusión alterara un bloque bloqueado o una expresión numérica, deje ese fragmento para aprobación.
- Elimine la repetición, las referencias obsoletas y las explicaciones no bloqueadas conflictivas. Actualice los enlaces después de los movimientos y evite documentos de resumen que dupliquen especificaciones.
Código y UI
- Trace una acción de usuario a través de la propiedad del estado hasta el resultado renderizado antes de editar el código de la UI.
- Corrija la inconsistencia concreta: estado de presentación duplicado, nombres de eventos/datos no coincidentes, flujo condicional no válido, código muerto creado por este cambio o una responsabilidad de componente que bloquea una corrección local.
- Mantenga estables el diseño, la interacción, la accesibilidad y el comportamiento responsivo a menos que el usuario apruebe un cambio de producto o visual.
- Prefiera un propietario claro de una transición de estado y una representación canónica de los datos. No introduzca abstracción, configuración o manejo de errores sin una necesidad demostrada.
4. Evaluar los candidatos de arquitectura por separado
Utilice estos términos de manera consistente:
- Módulo: una unidad con una interfaz e implementación.
- Interfaz: todo lo que los llamadores deben saber, incluyendo invariantes y modos de error.
- Costura: donde el comportamiento puede cambiar sin editar a los llamadores.
- Profundidad: apalancamiento de un comportamiento sustancial detrás de una interfaz pequeña; localidad: el conocimiento relacionado y el cambio se mantienen juntos.
Aplique la prueba de eliminación: si al eliminar un módulo simplemente se mueve su complejidad a los llamadores, se gana su lugar; si la complejidad desaparece, es probable que sea superficial. No cree una costura para un solo adaptador.
Para un candidato que cambie una interfaz, comportamiento o propiedad, no lo implemente de inmediato. Cree un informe HTML conciso y autocontenido en el directorio temporal del sistema operativo solo cuando una comparación visual sea útil. Incluya archivos, evidencia, diagrama antes/después, localidad y apalancamiento esperados, conflicto con ADR si lo hay y fuerza de la recomendación. Pida al usuario que elija un candidato antes de diseñar la interfaz.
5. Verificar y entregar
- Inspeccione el diff final en busca de alcance, preservación del contenido bloqueado, fuentes de verdad duplicadas y cambios no intencionados de valor o comportamiento.
- Ejecute el formateador, linter, verificación de tipos, pruebas, compilación y verificación de UI existentes y relevantes. No añada herramientas ni suites de prueba amplias únicamente para esta tarea. Distinga los fallos preexistentes de los introducidos.
- Confirme los enlaces y encabezados de Markdown después de la consolidación y verifique cada declaración modificada contra su fuente canónica.
- Reporte los cambios directos, los elementos de decisión no resueltos, los resultados de verificación y los riesgos en términos concisos. Cada línea modificada debe rastrearse hasta la convergencia solicitada.