No tienes que saberte los nombres de los comandos
El toolkit instala diecisiete comandos, y la forma normal de llegar a uno no es escribirlo. Describes lo que quieres con tus propias palabras y arranca solo el comando cuyo disparador corresponde a lo que pediste. Escribir /develop es cómo anulas esa elección, no cómo la haces.
Así que la respuesta corta a "cómo pido un cambio" es: di qué quieres, di dónde lo quieres y di si algo está roto. Todo lo de abajo es lo que pasa después, en el orden en que pasa. Si todavía no tienes nada instalado, empieza por Instala el toolkit.
1. Describes el cambio con tus propias palabras
Nombra lo que nombraría una persona: la pantalla, el botón, el flujo, el registro. No tienes que nombrar un archivo, una clase ni un componente, y no se espera que sepas dónde vive el código.
Hay dos detalles que vale la pena agregar por tu cuenta, porque los dos cambian lo que sigue. Di si algo que antes funcionaba ahora está fallando, y di qué ves cuando falla. Y si el resultado depende de algo — un rol, una lista vacía, un cupón vencido — dilo, porque los estados que nombras son los estados en los que el cambio se va a construir y a revisar.
2. Tu asistente elige el comando que corresponde a lo que pediste
Describir una funcionalidad arranca el comando de implementación. Preguntar cómo se haría algo arranca el de planeación. Decir que una pantalla debería funcionar y no lo hace también arranca implementación, que empieza por reproducir lo que describiste.
Siempre puedes nombrar tú el comando cuando quieres uno en particular. Qué hace cada comando es la lista, con la razón para echar mano de otro.
3. ¿Tu petición decide algo?
Esta es la bifurcación de la que depende el resto del camino. Una petición que decide algo — dos rutas reales y ninguna respuesta obvia, una regla que sale de una forma para un registro y de otra para el siguiente — se planea antes de construirse.
Planear es un paso aparte, y nada lo arranca a tus espaldas. Si pediste que el cambio se construyera y resulta que tiene una decisión real adentro, la corrida se detiene antes de tocar un solo archivo y te dice que lo planees; nunca abre la sesión de planeación por ti. Qué hace la planeación con tus respuestas, y cómo distinguir una decisión de un dato faltante, está en Planear antes de construir.
Una petición que no decide nada se salta esto por completo y pasa directo a construirse.
4. Construye el cambio y toca solo lo que el alcance necesita
Las ediciones se quedan dentro de lo acordado. El código que la tarea no tuvo que tocar no se reordena, ni se renombra, ni se ordena de pasada, y no se corre ningún formateador. Algo que se ve mal fuera del alcance se te reporta en lugar de cambiarse.
Si el trabajo alcanza más lejos de lo que cubría tu petición — resulta que toca un flujo que nadie nombró —, eso es una parada, no una ampliación silenciosa.
5. El analizador revisa cada archivo que escribió
Cada archivo que la tarea escribió se le envía al analizador con su contenido completo, se corrige cada error que regresa y se vuelve a enviar hasta que sale limpio. Los hallazgos en código heredado que no se tocó, en ese mismo archivo, se te reportan en lugar de convertirse en trabajo que nadie pidió.
Si la conexión con el servidor está caída se te dice con todas sus letras, y un revisor interno toma su lugar — reportado como otra cosa, nunca como una pasada del analizador. Mira Leer un hallazgo y Lo que el analizador no puede revisar.
6. ¿El cambio se ve en una pantalla?
Si se ve, lo abre alguien más. El comando que construyó el cambio no recorre su propio trabajo en el navegador: lo hace el comando de verificación, contra lo que se prometió, punto por punto, y regresa un resultado por punto y un solo veredicto.
Una pasada que falla no es el final del camino. Regresa como una corrección escrita en el mismo plan, lista para construirse, y se construye y se verifica otra vez — tres construcciones en total, después de las cuales lo que hay que revisar es el plan y no el código.
Un cambio que nadie ve en una pantalla — un comando, un job, un servicio, una migración — se prueba corriéndolo. Un cambio que es las dos cosas se prueba en los dos lados.
7. Un commit, y nunca hace push
Lo probado se vuelve un solo commit enfocado, agregando únicamente los archivos que la tarea posee, con el mensaje en inglés aunque tú hayas trabajado en otro idioma. No se hace push, no se crea rama y no se reescribe ningún commit anterior. El hash va en el reporte.
Las dos preguntas que de verdad te van a hacer
Casi todo lo que falta se busca en lugar de preguntarse. Dos cosas sí te llegan.
Lo que solo tú puedes contestar. Los datos que nadie escribió llegan juntos, en un solo mensaje, antes de tocar ningún archivo — nunca de uno en uno. Una decisión real no llega como pregunta: detiene la corrida y te manda a planearla.
Si se puede hacer una escritura riesgosa. Se pregunta una vez, antes de escribir código, y solo por lo que podría perder o cambiar de forma irreversible datos que no son tuyos para perderlos: un entorno que no se confirma como local, una base que parece tener datos de producción, una migración que reescribe una columna en una tabla que ya tiene registros, un servicio externo apuntando a una cuenta de producción. Llega con los tres datos — qué se encontró, qué hay que correr para probar el cambio y qué podría causar — y no se vuelve a preguntar después.
El trabajo local de todos los días no es ninguno de estos. Crear un usuario de prueba, correr un seeder y entrar con una cuenta sembrada pasan sin preguntar.
Qué regresa al final
Un reporte, y vale la pena leerlo hasta la última línea. Nombra qué se construyó y qué archivos cambiaron, recorre la lista punto por punto con la evidencia contra la que se marcó cada uno, dice qué se corrió para probar el cambio, cómo salió la pasada por el navegador y el commit que se creó — o por qué no se creó ninguno.
Un punto sin evidencia no se reporta como hecho. Un punto bloqueado se nombra con su razón, y los puntos que sí se probaron junto a él viajan igual.
La ayuda ya está escrita: cuando el cambio es de los que un usuario nota, la misma corrida que lo construye escribe el ítem de la función y su guía. Lo que la última línea nombra como pendiente es el changelog, y /finish desde la rama principal es quien lo escribe.
Sigue por aquí
- Qué ruta toma tu cambio — el mismo camino recorrido cuatro veces, una por cada tipo de cambio.
- Planear antes de construir — cuándo el paso de planeación vale lo que cuesta.
- Cómo viaja una tarea — el mismo recorrido por dentro, compuerta por compuerta.
- Los agentes detrás de un comando — a quién se le entrega cada paso, y por qué quien escribe el código no es quien lo aprueba.