Mapear la propiedad en un repositorio desconocido

2140. Identidad de la lección

Módulo

5.6 — Estrategia para bases de código grandes

Lección

Mapear la propiedad en un repositorio desconocido

Tipo académico

Sistemas

Tipo de esquema

texto

Orden

1

Tiempo estimado

35–45 minutos, incluida la práctica

2141. Objetivo de aprendizaje

Al terminar esta lección, podrás producir un mapa del repositorio que identifique los sistemas relevantes, los puntos de entrada, los responsables de los datos, los límites de dependencia, una ubicación segura para el cambio y los riesgos principales de modificarla.

2142. Por qué importa

Un repositorio desconocido no presenta su arquitectura en el orden que necesitas. Un archivo que parece adecuado puede ser el lugar equivocado porque otro sistema es dueño del estado, otra capa controla el ciclo de vida o varios consumidores dependen de la misma interfaz. Mapear la propiedad convierte la exploración del repositorio en una decisión técnica con límites claros. También te permite preparar un encargo preciso para evaluar antes de pedirle a una herramienta de IA que sugiera o implemente un cambio.

2143. Conocimientos previos

Debes poder inspeccionar un cambio propuesto, revisar la diferencia real, validar el resultado y recuperar el estado cuando el resultado no sea seguro. Esta lección continúa directamente 5.5 L2 — Inspeccionar, validar y recuperar. También necesitas conocer el lenguaje principal del proyecto, su estructura básica de carpetas y sus comandos habituales de validación.

2144. Concepto central

La idea central es determinar la propiedad antes de modificar.

Para cualquier cambio solicitado, distingue cuatro elementos:

1. Sistema: ¿Qué subsistema realiza este comportamiento?
2. Punto de entrada: ¿Dónde comienza el comportamiento o dónde entra la solicitud relevante al sistema?
3. Responsable de los datos: ¿Qué componente crea, almacena o modifica el estado que constituye la fuente de verdad?
4. Límite: ¿Qué interfaces, eventos, servicios, escenas, módulos o consumidores deben seguir siendo compatibles?

Un archivo que muestra un valor no necesariamente es su dueño. Una función que recibe un evento no necesariamente define la regla que hay detrás. Una utilidad central puede parecer fácil de editar, pero ser peligrosa porque muchos sistemas no relacionados dependen de la misma interfaz. La ubicación segura es el componente más acotado que tiene autoridad sobre el estado y satisface la solicitud sin cruzar un límite innecesario.

2145. Modelo mental

Usa el mapa S-E-D-B. La sigla conserva la mnemotecnia inglesa —System, Entry point, Data owner, Boundary—, mientras que en español empleamos Sistema, Punto de entrada, Responsable de los datos y Límite:

Después añade una línea de decisión:

Comportamiento solicitado → evidencia S-E-D-B → ubicación más segura → riesgos probables → evidencia de validación

No trates el mapa como un diagrama completo de la arquitectura. Es un mapa de decisión para un cambio concreto. Su valor está en registrar evidencias e incertidumbres, no en dibujar todas las dependencias del repositorio.

2146. Ejemplo concreto

Supón que la solicitud es: «Cuando una tarea completada otorgue una recompensa, hay que impedir que la recompensa se otorgue dos veces».

Una orientación débil podría elegir la pantalla que muestra la recompensa y añadir allí una protección. Esa pantalla observa el resultado, pero no necesariamente es la responsable.

Un mapa S-E-D-B más sólido podría verse así:

La candidata más segura es la ruta con autoridad sobre la concesión de la recompensa, siempre que la evidencia confirme que todas las fuentes de finalización pasan por ella. La capa visual sigue siendo una superficie de riesgo: modificarla podría ocultar recompensas duplicadas sin impedir que se concedan. Otros riesgos incluyen reintentos, tareas completadas que se cargan desde un guardado y llamadores que evitan el punto de entrada supuesto.

El ejemplo demuestra el razonamiento, no una implementación específica del proyecto. Debes verificar cada hallazgo en el repositorio antes de modificar el código.

2147. Error común

El error más frecuente es confundir visibilidad con propiedad. Es habitual escoger el archivo donde se muestra, registra o recibe inicialmente un valor porque es fácil de localizar. Esto puede duplicar reglas, dejar sin protección otras rutas de entrada o producir una corrección que solo funciona para un llamador.

Otro error es construir un mapa de dependencias solo a partir de los nombres de archivo. Los nombres son pistas. Las importaciones, las referencias, los lugares donde se invocan símbolos, las mutaciones de estado, los eventos, las pruebas y la configuración de ejecución ofrecen evidencia más sólida.

2148. Práctica guiada y evaluación práctica

Usa la siguiente instantánea acotada de un repositorio desconocido. La solicitud es: «Una tarea completada no debe aplicar su recompensa más de una vez». No propongas ni escribas una implementación.

Instantánea del repositorio

src/tasks/TaskCompletionService.ts
src/rewards/RewardLedger.ts
src/ui/RewardToast.ts
src/save/SaveCodec.ts
config/event-bindings.json
tests/TaskCompletionService.test.ts
tests/RewardLedger.test.ts

La evidencia proporcionada contiene estos extractos:

• config/event-bindings.json: dirige task_finished a TaskCompletionService.complete.
• src/tasks/TaskCompletionService.ts, símbolo complete: marca la tarea como completada, llama a RewardLedger.grantForTask y después publica task.completed.
• src/rewards/RewardLedger.ts, símbolos grantForTask y restore: grantForTask añade una entrada de recompensa y actualiza el saldo; restore sustituye las entradas del registro por los datos guardados.
• src/ui/RewardToast.ts, símbolo onTaskCompleted: se suscribe a task.completed y lee el saldo actual; no modifica el estado de las tareas ni de las recompensas.
• src/save/SaveCodec.ts, símbolos encode y decode: serializan y restauran tanto el estado de las tareas como las entradas del registro de recompensas.
• Las referencias de símbolos muestran que, en el código de producción, solo TaskCompletionService.complete llama a grantForTask; las entradas del registro de recompensas solo se modifican dentro de RewardLedger.
• tests/TaskCompletionService.test.ts cubre una finalización normal. tests/RewardLedger.test.ts cubre una concesión y una restauración, pero ninguna prueba contempla una finalización repetida ni la repetición de una concesión.
• Nota relevante del historial: un cambio anterior trasladó la modificación de las entradas de recompensa desde TaskCompletionService hasta RewardLedger para centralizar las escrituras. La nota no aborda la prevención de duplicados.

Flujo obligatorio de verificación con IA

1. Proporciona a una herramienta de IA únicamente la solicitud, la lista de archivos y los extractos seleccionados. Pídele que proponga rutas de búsqueda candidatas o que resuma las responsabilidades de los archivos seleccionados.
2. Registra cada afirmación útil de la IA en una tabla con cuatro campos: afirmación, fuente propuesta, resultado de la verificación y cita.
3. Verifica o rechaza cada afirmación mediante los extractos de código, las referencias de símbolos, las pruebas, la configuración o la nota del historial. Cita rutas y símbolos concretos, como src/rewards/RewardLedger.ts::grantForTask; el resumen de la IA no cuenta como evidencia.
4. Marca como desconocida cualquier afirmación no respaldada, en vez de completar los vacíos con suposiciones.

Entrega

Entrega un único archivo de texto llamado repository-map.md que contenga:

1. un mapa S-E-D-B con rutas de evidencia y etiquetas confirmado, inferido o desconocido;
2. el registro de afirmaciones de la IA;
3. una ubicación aceptada para un cambio futuro y otra descartada, ambas justificadas con evidencia del repositorio;
4. al menos tres riesgos, cada uno acompañado de una comprobación de validación específica; y
5. la evidencia que te haría reconsiderar la ubicación aceptada.

La decisión obligatoria es: ¿Qué ubicación autorizarías para un cambio futuro y qué evidencia te haría cambiar de decisión?

2149. Validación / evidencia

2150. Puntos clave

• Determina la propiedad antes de elegir el archivo que vas a cambiar.
• Separa el sistema, el punto de entrada, el dueño de los datos y el límite.
• Da prioridad a la evidencia del repositorio sobre los nombres de archivo o las suposiciones generadas por IA.
• Elige la ubicación más acotada que tenga autoridad sobre el estado, no simplemente el archivo más fácil de editar.
• Registra la incertidumbre y los riesgos para que la inspección posterior pueda comprobar la decisión.

2151. Siguiente lección

Continúa con 5.6 L2 — Planificar un cambio escalonado entre varios sistemas. Lleva a esa lección la ubicación aprobada, los límites de propiedad, los riesgos, las incertidumbres pendientes y las comprobaciones de validación de tu mapa del repositorio para usarlos como restricciones del plan escalonado.

2152. Comprobación