Repository Exploration and Task Framing
Repository Exploration and Task Framing es la práctica de convertir un pedido de desarrollo inicialmente incompleto en una tarea situada en el repositorio: con intención, alcance, restricciones, evidencia, incertidumbres y condiciones de éxito suficientemente claras para actuar. Un Coding Agent puede participar buscando, relacionando y comprobando información, mientras las personas aportan conocimiento del producto y resuelven decisiones que el código no puede determinar.
El resultado no es conocer todo el sistema. Es poder justificar el siguiente cambio o experimento sin confundir una suposición del agente con una decisión del equipo. La exploración puede terminar en una implementación pequeña, una propuesta de alternativas, una pregunta concreta o la conclusión de que todavía falta evidencia para modificar algo.
Exploración, búsqueda y contexto
La búsqueda es un mecanismo: localizar un símbolo, una cadena, una dependencia o un documento. La exploración es una actividad más amplia que combina esas respuestas, evalúa su pertinencia y decide qué comprobar después. Encontrar un controlador que contiene una palabra del pedido no establece que sea el punto correcto de modificación. Todavía pueden faltar una regla de negocio, un consumidor o un límite arquitectónico.
Context Engineering for Software Development abarca cómo seleccionar, mantener y transferir información durante el trabajo. La exploración produce contexto candidato y evidencia sobre el repositorio; context engineering decide cómo conservarlos y utilizarlos junto con instrucciones, resultados de herramientas y decisiones. Hay solapamiento operativo, pero sus responsabilidades difieren. Un buen índice no garantiza que la sesión reciba el contexto adecuado, y una sesión bien organizada puede contener información incorrecta.
Tampoco toda exploración requiere un grafo. Una búsqueda literal puede resolver una modificación localizada. Las relaciones estructurales ayudan cuando importa seguir llamadas, dependencias o límites entre módulos. La elección del mecanismo depende de la pregunta y de la calidad de sus resultados, no del prestigio de la herramienta.
Qué significa encuadrar una tarea
Task framing establece qué quiere decir el pedido en este sistema. Distingue el comportamiento deseado, el problema observado, las restricciones de cambio y lo que queda fuera. También explicita quién puede decidir una ambigüedad y qué evidencia permitiría considerar satisfecho el encargo. Es un proceso de interpretación y delimitación, revisable cuando aparecen datos nuevos.
Un Task Prompt es el artefacto de comunicación que solicita trabajo. Puede iniciar el encuadre o transmitir uno ya acordado, pero su extensión no demuestra que la tarea esté comprendida. Un prompt detallado puede mezclar requisitos incompatibles; uno breve puede ser suficiente para una corrección cuyo contrato ya está documentado. Reescribir el pedido con más palabras no reemplaza investigar esas diferencias.
El encuadre consume requisitos, incidentes y decisiones de producto; no sustituye Requirements Engineering. Si falta decidir si un descuento puede acumularse con otro, el agente no debe deducir la política comercial de un ejemplo aislado. Sí puede elegir una búsqueda o una forma rutinaria de organizar una corrección dentro del alcance autorizado. Separar ambas clases de decisión permite autonomía útil sin inventar requisitos.
Orientación inicial con propósito
Antes de editar interesa conocer la identidad del repositorio, la revisión de partida y el estado del trabajo existente. Cambios locales ajenos, archivos generados y configuraciones de desarrollo pueden alterar lo observado. Registrar ese punto de partida evita atribuir al agente una modificación anterior o verificar una versión distinta de la que se entregará. No implica limpiar ni descartar el trabajo de otra persona.
Después se identifica el subsistema probable y sus entradas y salidas: quién recibe el pedido, dónde se aplica la política relevante y qué consumidores dependen del resultado. Documentación arquitectónica, contratos y pruebas ofrecen pistas distintas del nombre de las carpetas. La ubicación física ayuda a orientarse, pero un archivo próximo no necesariamente pertenece a la misma responsabilidad.
Las Persistent Instructions pueden aportar convenciones y restricciones aplicables. Deben leerse en su alcance y contrastarse con el encargo vigente. Un comentario dentro de un ejemplo o un texto recuperado desde una dependencia no adquiere autoridad para cambiar el objetivo. La exploración reúne información; no convierte cualquier texto encontrado en una instrucción de ejecución.
Formular preguntas antes de ampliar lecturas
Una pregunta concreta limita la búsqueda: qué componente decide el resultado, qué contrato consumen sus clientes o dónde se observa la regresión. Si la pregunta es localizar una implementación conocida, conviene recuperar ese símbolo y sus relaciones inmediatas. Si es entender una discrepancia, interesa comparar el comportamiento esperado con la ruta ejecutada. Leer muchos archivos sin pregunta puede aumentar el contexto y reducir la claridad.
Las respuestas deben distinguir observación e inferencia. “Este método llama al repositorio” puede comprobarse en el código. “Este método explica el incidente” necesita además conectar entradas, estado y ejecución con el síntoma. Una hipótesis plausible orienta el siguiente experimento; todavía no es una causa confirmada. Esta separación evita que el relato del agente se vuelva más seguro que su evidencia.
La expansión debe ser gradual. Un consumidor inesperado justifica abrir otro módulo; una prueba que falla por infraestructura justifica revisar el entorno. Ninguno obliga a inspeccionar todo el proyecto. El criterio práctico es si la siguiente lectura podría cambiar la decisión actual o descubrir un riesgo relevante para el alcance.
Índices y grafos como mecanismos de exploración
Un índice permite recuperar candidatos sin releer el repositorio completo. Un grafo puede mostrar relaciones entre símbolos, archivos o documentos y sugerir el alcance de una modificación. Esas relaciones tienen una semántica concreta: una arista de llamada no equivale a dependencia de negocio, y la ausencia de una arista no demuestra ausencia de interacción mediante configuración, reflexión o mensajería.
Antes de apoyarse en un resultado interesa conocer su raíz, revisión, cobertura y frescura. Un índice del mismo nombre sobre otro checkout, o anterior a cambios locales, puede devolver información coherente pero equivocada para la tarea. Cuando hay cobertura parcial se consultan las líneas o rutas omitidas directamente. Un estado sin errores registrados tampoco prueba que todas las relaciones posibles hayan sido capturadas.
La secuencia útil es descubrimiento mediante el índice y comprobación en la fuente cuando importan comportamiento, metadata o texto exacto. Un resultado negativo exige especial cuidado: quizá el término es distinto, el formato no está indexado o el vínculo es dinámico. La alternativa es una búsqueda focalizada o evidencia de ejecución, no concluir automáticamente que la funcionalidad no existe.
Límites arquitectónicos y alcance del cambio
El encuadre debe identificar qué responsabilidad puede cambiar y qué contratos necesitan conservarse. Modificar una validación en la interfaz puede ocultar que la política se comparte con importaciones y procesos internos. A la inversa, llevar una excepción específica del cliente al dominio puede ampliar indebidamente el comportamiento. El agente necesita entender esa frontera antes de proponer el lugar del cambio.
Design Process aporta el marco general para razonar sobre restricciones y alternativas. La exploración asistida aporta evidencia localizada al proceso: rutas afectadas, dependencias, contratos y pruebas disponibles. No concede al agente autoridad para reemplazar una decisión arquitectónica existente solo porque otra organización de archivos parece más sencilla.
El alcance puede ajustarse si aparece una dependencia imprescindible. Debe explicarse por qué es necesaria para satisfacer la tarea y qué riesgo añade. Una mejora adyacente sin relación causal se registra como posible trabajo futuro. Así se evita convertir una corrección pequeña en una limpieza general cuyos efectos resultan difíciles de revisar.
Ejemplo: un resultado distinto según el canal
Supongamos un servicio de pedidos donde la API rechaza un cupón vencido, pero una importación permite aplicarlo. El pedido inicial dice “arreglar validación de cupones”. El agente puede localizar la política temporal, ambos puntos de entrada y los tests existentes. Encontrar dos validadores con nombres parecidos es una pista; todavía no demuestra cuál debería ser la autoridad compartida.
La exploración descubre que la importación acepta operaciones históricas con fecha efectiva, mientras la API usa la fecha actual. La diferencia podría ser una regla intencional o un defecto. El encuadre pasa a preguntar qué fecha debe gobernar cada operación y si los pedidos históricos deben conservar su comportamiento. Esa decisión pertenece al dominio, no a una preferencia del agente por eliminar duplicación.
Si el contrato confirma que ambos canales deben usar la fecha efectiva, el alcance puede limitarse a transmitirla a la política y comprobar los dos recorridos. Si el contrato es ambiguo, el siguiente resultado útil es presentar la discrepancia y sus consecuencias. En ninguno de los casos hace falta inventariar toda la plataforma antes de avanzar.
Condiciones de éxito y evidencia disponible
La evidencia puede entrar en conflicto. Un comentario describe una regla, un test protege otra y la ejecución observada sigue una tercera. El agente debería conservar la discrepancia y comprobar fechas, alcance y autoridad de esas referencias. Elegir la fuente más fácil de satisfacer puede producir una corrección aparente que mantenga el problema original. La pregunta no es solo qué archivo dice algo, sino qué papel cumple esa afirmación en el sistema y si continúa vigente.
También importa distinguir ausencia de evidencia y evidencia de ausencia. No localizar un consumidor en una búsqueda no prueba que el contrato sea interno; puede existir fuera del repositorio. Cuando el cambio depende de esa conclusión, conviene consultar documentación de integración o al equipo responsable. Si no hay una respuesta disponible, se puede proponer una opción conservadora y declarar el supuesto, sin presentarlo como un hecho comprobado.
Una condición de éxito describe un resultado observable, no una actividad del agente. “Leer el módulo y actualizarlo” cuenta trabajo, mientras “los dos canales aplican la regla acordada para la misma fecha efectiva” permite evaluar el cambio. Las condiciones deben ser proporcionales a la tarea e incluir restricciones importantes, como preservar un contrato público o no modificar datos históricos.
Conviene distinguir evidencia ya obtenida, comprobaciones previstas y limitaciones del entorno. Un test existente puede cubrir la API pero no la importación; una reproducción local puede carecer del proveedor real. El agente no debería presentar ninguna de esas piezas como una garantía más amplia. El encuadre facilita elegir controles pertinentes sin desarrollar aquí un sistema completo de verificación.
La incertidumbre también puede ser un resultado explícito: comportamiento externo no reproducible, configuración desconocida o criterio de negocio pendiente. Identificarla permite decidir si se continúa con una parte independiente o se solicita información. Ocultarla detrás de un plan detallado solo traslada el problema a la implementación.
Colaboración y transferencia
Las personas participan aportando intención, conocimiento tácito y restricciones que pueden no estar codificadas. El agente contribuye relacionando evidencias, proponiendo hipótesis y ejecutando acciones dentro de sus límites. Colaborar incluye explicar alternativas y aprender de correcciones; no se reduce a pedir aprobación para cada paso reversible ni a delegar todas las decisiones al modelo.
Los Development Context and Execution Records pueden conservar el encuadre, las fuentes relevantes y las preguntas pendientes. Es más útil transferir el contrato seleccionado y el motivo de una exclusión que copiar íntegramente una conversación. El receptor necesita poder distinguir una conclusión confirmada de una hipótesis pendiente y volver a la fuente cuando cambia la revisión.
Si interviene otro agente, se transfiere esa misma información situada, incluyendo la revisión de partida y el alcance autorizado. Agregar participantes no corrige un encuadre incorrecto por sí solo. Un único agente con evidencia suficiente puede realizar el trabajo, y un equipo de agentes puede amplificar la misma interpretación equivocada.
Cuándo detener la exploración
Se puede avanzar cuando la intención está suficientemente estable, las zonas afectadas están identificadas y existe un próximo cambio o experimento justificable. No hace falta resolver todas las preguntas del sistema. Sí deben quedar visibles las incertidumbres capaces de invalidar esa acción, especialmente cuando afectan efectos irreversibles o contratos compartidos.
Son señales de exploración insuficiente una modificación elegida solo por coincidencia de nombres, una afirmación de ausencia basada en un único resultado vacío o una solución que inventa una regla no acordada. Son señales de exceso las lecturas que no cambian ninguna decisión y los inventarios completos para tareas localizadas. Ambas situaciones consumen atención que debería dirigirse al riesgo real.
El encuadre puede revisarse durante AI-Assisted Implementation and Change Maintenance. Si una prueba contradice una suposición, volver a explorar es razonable. El workflow organiza una actividad profesional; no impone un patrón universal de control de agentes ni una secuencia rígida de herramientas.
Relaciones
Specification-Assisted Development utiliza el encuadre para decidir qué expectativas merecen un artefacto durable. AI-Assisted Code Review vuelve sobre intención y alcance al evaluar el cambio. Workspace Isolation for Coding Agents ayuda a preservar el estado de trabajo cuando la exploración desemboca en experimentos o tareas independientes. Ninguno reemplaza comprender qué problema se intenta resolver.