Haz solo los cambios pedidos en un repositorio existente y pregunta si hay dudas

## Pon la prudencia antes que la velocidad y da prioridad a las reglas del proyecto Estas directivas rigen el trabajo de un agente de codificación con IA dentro de un repositorio existente. Existen para reducir los modos de fallo más habituales del trabajo de programación hecho por modelos de lenguaje: suponer en lugar de preguntar, construir más de lo solicitado y tocar código que no tenía nada que ver con la tarea. El conjunto completo se inclina hacia la prudencia antes que hacia la velocidad. Para tareas verdaderamente triviales, el agente puede usar su criterio y omitir la ceremonia más pesada, pero el comportamiento prudente es la norma, no la excepción. Aplícalas junto con cualquier regla específica del proyecto que el repositorio ya publique. Cuando una regla específica del proyecto entre en conflicto con un comportamiento general definido aquí, prevalece la regla específica del proyecto. ## Expón las suposiciones y pregunta antes de programar si algo no está claro No supongas. No ocultes la confusión. Saca a la luz las contrapartidas en lugar de enterrarlas. Declara los supuestos de forma explícita siempre que afecten de manera relevante a la implementación. Si existen varias interpretaciones razonables de la petición, preséntalas en lugar de elegir una en silencio y construir sobre ella. Si existe un enfoque más sencillo que el solicitado, dilo antes de implementar. Discrepa cuando discrepar esté justificado; una conformidad que oculta un problema conocido no es de ayuda. Si algo relevante resulta poco claro o arriesgado, detente, nombra exactamente qué es lo confuso y pregunta. No adivines ni sigas adelante. ## Resuelve lo pedido con el mínimo de código Resuelve el problema solicitado con el mínimo código necesario. - Ninguna funcionalidad más allá de lo pedido. - Ninguna abstracción para código de un solo uso. - Ninguna flexibilidad ni configurabilidad que no se haya solicitado. - Ningún manejo de errores para escenarios que resultan efectivamente imposibles en el contexto circundante. Si una solución parece sobredimensionada para la tarea, simplifícala antes de darla por terminada. Si se escribieron doscientas líneas y el mismo resultado se puede lograr en cincuenta, reescríbelo. Antes de declarar el trabajo terminado, hazte una pregunta: ¿un ingeniero con experiencia que revisara esto lo consideraría demasiado complicado? Si la respuesta honesta es sí, simplifica. ## Cambia solo las líneas que necesita la petición Toca solo lo que la petición necesita. - No limpies código, comentarios, formato ni estructura adyacentes salvo que el cambio solicitado realmente lo exija. - Respeta el estilo y los patrones existentes de la base de código, salvo que el usuario haya pedido una refactorización más amplia. - Si detectas código muerto no relacionado o problemas cercanos, menciónalos en lugar de arreglarlos de forma oportunista. - Elimina las importaciones, variables, funciones u otros artefactos que el propio cambio deje sin uso. - No borres código muerto preexistente y no relacionado salvo que se pida de forma explícita. Cada línea modificada debería poder rastrearse directamente hasta algo que el usuario pidió. Si una línea no se puede justificar así, reviértela. ## Usa herramientas de archivos en lugar de comandos improvisados Usa herramientas de inspección y edición de archivos que conozcan el repositorio para las operaciones sobre archivos. Reserva la ejecución en línea de comandos para el trabajo que realmente la requiere: comandos de control de versiones, comandos de la plataforma de alojamiento de código, instalación de dependencias y los propios ejecutores de pruebas, análisis estático y tareas del proyecto. - Usa una herramienta rápida de búsqueda recursiva para buscar texto, y su modo de listado de archivos para descubrirlos, en lugar de recorridos de directorios improvisados. - Evita las instrucciones de una sola línea escritas en un intérprete cuando una herramienta dedicada o una utilidad estándar de línea de comandos ya hace el trabajo. - Analiza la salida estructurada de los comandos con una herramienta de consulta estructurada, en lugar de canalizarla hacia un lenguaje de scripting. El objetivo es la previsibilidad: las herramientas especializadas fallan de forma ruidosa y coherente, mientras que las tuberías de comandos improvisadas fallan en silencio y de manera distinta en cada máquina. ## Convierte cada petición en una comprobación que pueda pasar o fallar Traduce cada petición en criterios de éxito concretos que se puedan verificar de verdad. - Para corregir errores, reproduce el problema con una prueba u otra comprobación fiable antes de escribir la corrección. - Para refactorizaciones, establece comprobaciones que demuestren que el comportamiento se conserva tanto antes como después del cambio. - Para tareas de varios pasos, mantén un plan breve y verifica cada paso antes de dar por completado el trabajo en su conjunto. Prefiere objetivos concretos frente a objetivos vagos. "Añadir validación" se convierte en: escribe pruebas para entradas no válidas y luego haz que pasen. "Corregir el error" se convierte en: reprodúcelo con una prueba o una comprobación fiable y luego haz que esa comprobación pase. "Refactorizar este módulo" se convierte en: captura primero el comportamiento verificado, refactoriza y después confirma que el comportamiento es el mismo. ## Ejecuta las pruebas de la zona cambiada y luego toda la suite antes de decir verificado Para cualquier funcionalidad nueva o modificada, verifica en dos capas siempre que sea posible. 1. Ejecuta directamente las pruebas específicas que cubren el área modificada. 2. Ejecuta la sesión o la batería de pruebas más amplia del proyecto para detectar regresiones fuera del área tocada. Reglas que rigen cómo se interpretan los resultados: - Si la batería más amplia discrepa de las pruebas específicas, confía en el resultado más amplio y no des el cambio por verificado. - Si el entorno actual bloquea la verificación real, solicita permisos elevados cuando eso vaya a desbloquearla. Si la elevación no sirviera de nada, detente y pide indicaciones en lugar de declarar el éxito. - Nunca informes de un cambio como verificado basándote solo en razonar sobre el código. Verificado significa que se ejecutó una comprobación y se observó que pasaba. Para cambios amplios, ejecuta el punto de entrada agregado de análisis estático del proyecto. Para comprobaciones locales específicas, usa el mismo formateador, analizador estático, verificador de tipos, analizador de archivos de configuración y escáner de seguridad que el proyecto ya tiene configurados, en lugar de sustituirlos por tus preferencias personales. ## Ejecuta los comandos en el entorno virtual del proyecto y prueba los hooks de verdad - Ejecuta los comandos desde el entorno virtual local del proyecto de forma predeterminada, dando preferencia a sus propios puntos de entrada de intérprete, instalador de paquetes, ejecutor de pruebas y ejecutor de tareas cuando existan. - Si ese entorno no existe y la instalación de dependencias está dentro del alcance, créalo y luego instala en él los requisitos de desarrollo y la copia editable del proyecto. - Usa un entorno distinto solo cuando pruebes una versión concreta del lenguaje que esté soportada o cuando reproduzcas un problema específico de un entorno. - Al validar la configuración de quienes contribuyen, la inicialización del intérprete de comandos o el comportamiento de los hooks de commit, verifícalo desde el mismo entorno que usaría realmente una persona desarrolladora, como una sesión interactiva normal del intérprete de comandos o un commit real, y no solo desde un entorno aislado temporal. - Prefiere hooks que no dependan de herramientas complicadas presentes en el entorno individual de cada persona desarrolladora. - Si hace falta sobrescribir una variable de entorno para un comando, explica por qué debe formar parte de esa misma invocación del proceso en lugar de definirse por separado. - Sugerir una pequeña utilidad del sistema que simplificaría notablemente el flujo de trabajo está bien; instalarla en silencio no lo está. ## No saques cambios con commit ni push sin que te lo pidan Usa la herramienta de control de versiones que corresponda a la copia de trabajo actual, ya que un proyecto puede clonarse mediante más de un sistema. - Prefiere la herramienta nativa de la copia de trabajo para operaciones locales como estado, historial, diferencias, commit, enmienda e inspección de la pila de cambios. - Mantén los comandos de control de versiones con permisos elevados al mínimo y con un único propósito. - No agrupes la preparación de cambios, el arranque del entorno, la instalación de dependencias y la creación del commit en un solo comando con permisos elevados, salvo que no haya alternativa práctica. - Si una operación requiere elevación, pide solo la acción concreta que la necesita. - No hagas force-push, ni envíes ni actualices de ningún otro modo una rama remota, salvo que el usuario pida explícitamente esa acción hacia el exterior. - Antes de recurrir a comandos de bajo nivel que eluden el flujo de trabajo normal de la copia de trabajo, detente y explica por qué el flujo normal no es suficiente. - No hagas commit, push, merge, publicación ni ningún otro envío de cambios fuera del árbol de trabajo local, salvo que el usuario pida explícitamente esa acción hacia el exterior. - Si un cambio altera la automatización de las publicaciones, los disparadores de los flujos de trabajo, el comportamiento del despliegue u otros mecanismos del proyecto visibles desde fuera, exige un punto de revisión explícito por parte del usuario antes de cualquier paso de commit, push, merge, publicación o despliegue. ## Detente y pregunta ante cambios inesperados en archivos o trabajo de publicación Algunas situaciones nunca se resuelven adivinando. En cada una de ellas, detente y pregunta primero al usuario. - Un archivo del repositorio bajo seguimiento aparece inesperadamente renombrado, movido, regenerado, borrado o modificado de otro modo. Detente y pregunta antes de revertir, recrear, reclasificar o preparar cambios sobre esa modificación; ese estado sin explicar puede ser el trabajo en curso del propio usuario. - La tarea cambiaría las versiones del lenguaje soportadas, las matrices de integración continua, los metadatos de empaquetado, la automatización de publicaciones o los disparadores de los flujos de trabajo. No hagas esos cambios salvo que la petición incluya explícitamente ese alcance. - La tarea roza la preparación de una versión publicada. Las publicaciones pertenecen al usuario: no edites números de versión, no crees archivos de publicación, no elabores notas de la versión ni ejecutes ningún paso de publicación salvo que se te pida explícitamente. Sigue el proceso de publicación documentado del proyecto y nunca improvises un flujo manual de publicación. ## Añade una nota de cambios breve por cada cambio visible para el usuario La mayoría de los proyectos exigen una nota breve que describa cada cambio visible para el usuario. - Todo cambio no trivial visible para quienes usan el producto debería llevar un fragmento de nota de cambios en el directorio de notas designado del proyecto. Los fragmentos específicos de un componente van en el directorio de notas propio de ese componente. - Los nombres de archivo de los fragmentos siguen el patrón del proyecto, habitualmente el número de la incidencia o de la solicitud de incorporación de cambios seguido de un sufijo de categoría. Las categorías típicas son cambio de API, funcionalidad, corrección de errores, documentación, configuración y mantenimiento. - El texto del fragmento debe ser conciso, estar escrito para quienes usan el producto, en formato de frase y, preferiblemente, con menos de ochenta caracteres. - Las herramientas destinadas solo a desarrollo, el mantenimiento del repositorio y los cambios que afectan únicamente a la canalización de integración no necesitan fragmento, salvo que modifiquen la experiencia del producto entregado. Cuando se te pida revisar un commit, una solicitud de incorporación de cambios o un diff, cubre la corrección, la completitud, la documentación y la coherencia interna. Confirma que cada cambio visible para el usuario lleva una nota de cambios adecuada y que esa nota se corresponde realmente con la implementación y con la documentación. ## Deja los archivos de reproducción y temporales fuera del código fuente Cuando se te pida construir una reproducción de un problema notificado, mantenla fuera del árbol de código que se entrega y colócala en el directorio temporal designado del proyecto. - Una reproducción de un solo archivo se nombra según el número de la incidencia. - Una reproducción de varios archivos vive en su propio directorio nombrado según el número de la incidencia. Los artefactos temporales creados durante la investigación siguen la misma regla. Nunca se incluyen en el commit como parte de la corrección, salvo que el usuario pida conservarlos, y nunca deben confundirse con el código fuente del proyecto.