2. Git en el proyecto

Objetivo del tema: que nadie vuelva a escribir a mano un comando de git del día a día. Al acabar, todo lo de git pasa por la skill /git-flow.

Lo que ya sabéis y aquí no se repite:

Git básico, .gitignore y el formato de los mensajes de commit type(#issue):título: Despliegue 1.
Ramas, los tipos de merge, conflictos y, sobre todo, worktrees y por qué uno por rama cuando se trabaja con agentes: Despliegue 2.
Scrum y los tableros de GitHub: Proyecto 4.

Issues y tablero

Todo trabajo empieza por un issue. El issue es la unidad: de él sale la rama, su número va en los commits y al fusionar se cierra solo.

El tablero es un GitHub Project del repositorio con tres columnas: Todo, In progress y Done. De sus automatizaciones (Workflows del proyecto) solo hace falta una, que viene activada de serie: issue cerrado → Done. El resto se hace a mano: al crear el issue se añade al tablero, y al empezar a trabajarlo se arrastra a In progress. Automatizar eso por línea de comandos no compensa.

Etiquetas: feature y bug. No hacen falta más.

Los issues se crean desde la web o con gh:

gh issue create --title "Alta de clientes" --label feature --body "Formulario de alta con nombre, NIF y email."
gh issue list
gh issue view 12

Las ramas de este proyecto

El modelo de ramas de Despliegue 2 tiene develop, release y master. Aquí, al ser un proyecto individual con un solo entorno, se recorta a dos:

develop: la integración. Solo existe de verdad en local, en la carpeta principal del repositorio; en GitHub está porque es la rama por defecto y es donde se cierran los issues. Nunca se despliega.
main: producción. Cada push a main despliega en el servidor (tema 6). Nunca se trabaja en ella.

Y por cada issue, una rama de trabajo en su propio worktree:

Cosa	Nombre	Ejemplo
Rama	`<alumno>-<N>-<slug>`	`lorenzo-12-alta-clientes`
Worktree	`../<repo>-wt-<N>-<slug>`	`../mi-proyecto-wt-12-alta-clientes`

El número del issue en el nombre de la rama hace que la skill sepa siempre a qué issue pertenece, sin preguntarlo.

Sin pull requests. En un proyecto individual nadie va a revisar el PR, así que es un trámite que no aporta nada: la rama se fusiona en develop en local y se hace push. La revisión del código la hará la IA antes de fusionar (tema 5).

El ciclo de una rama

Iniciar: desde la carpeta principal (siempre en develop, actualizada), crear la rama y su worktree.
Trabajar en el worktree. Commits pequeños con type(#N):título.
Actualizar: si develop ha avanzado (otro issue que se ha terminado antes), traer develop a la rama con git merge develop. Los conflictos se resuelven en la rama, nunca en develop.
Finalizar: fusionar en develop con –squash: todos los commits de la rama se funden en uno con el mensaje feat(#N): título. Push de develop. Borrar el worktree y la rama.
Publicar: cuando hay algo que sacar, develop → main con –ff-only y push.

Por qué –squash hacia develop y –ff-only hacia main está en Usos de merge.

El commit que cierra el issue

GitHub cierra un issue automáticamente cuando llega a la rama por defecto un commit cuyo mensaje contiene Closes #N. Por eso develop es la rama por defecto, y por eso el commit de la fusión lleva el Closes en el cuerpo:

feat(#12): Alta de clientes

Closes #12

Al hacer push de develop, el issue 12 se cierra y el tablero lo pasa a Done. No hay que tocar nada en la web.

Reglas para que la IA toque git

Una skill que ejecuta git puede hacer daño si improvisa. Estas reglas van en la skill y no se negocian:

Nunca git pull. Siempre git fetch –prune y git merge –ff-only origin/<rama>. Así, si las historias han divergido, falla en vez de hacer un merge sorpresa.
Nunca –force, ni –no-verify, ni stash, ni borrar worktrees con –force.
Nunca resolver un conflicto. Si un merge da conflicto, la skill se para, enseña git status y dice qué comandos tiene que ejecutar el alumno. Resolver conflictos es trabajo humano.
La carpeta principal siempre en develop y limpia. Si no lo está, la skill se para antes de hacer nada.
Una operación por invocación: /git-flow iniciar 12, no «inicia y luego finaliza».
allowed-tools como lista blanca: solo git y gh. Nada de rm, nada de escribir ficheros del proyecto.

La skill /git-flow

Se parte de la skill que ya enlaza Despliegue 2, git-flow-skill.md, que es casi lo que hace falta. Se adapta con estos cambios:

Quitar release, bajar y subir. Quedan cinco operaciones:

Operación	Qué hace
`iniciar N`	Lee el issue `N` con `gh issue view`, deriva el slug del título, crea la rama `<alumno>-<N>-<slug>` desde `develop` actualizada y su worktree hermano, y hace push de la rama
`commit`	Mira `git status` y `git diff` del worktree actual y agrupa los cambios por intención, no por fichero: un commit por cosa hecha, cada uno con `type(#N):título`. El `N` lo saca del nombre de la rama. Enseña los commits que va a hacer antes de hacerlos
`actualizar`	Trae `develop` a la rama del worktree actual
`finalizar`	`actualizar`, `–squash` en `develop` con el mensaje `feat(#N): <título del issue>` y `Closes #N` en el cuerpo, push de `develop`, borrar rama remota, worktree y rama local
`publicar`	`develop` → `main` con `–ff-only` y push de `main`

El nombre del alumno para las ramas se lee de AGENTS.md (una línea: «las ramas empiezan por lorenzo-»).
Añadir Bash(gh issue view:*) a allowed-tools.
finalizar y actualizar deducen la rama del worktree en el que se ejecutan, como ya hace la skill original.

En el tema 3 iniciar y finalizar crecen para levantar y parar los contenedores, y en el tema 5 finalizar lanza antes la revisión por IA.

AGENTS.md tiene que decir desde ahora: «git se maneja solo con /git-flow; no ejecutes comandos de git que cambien el repositorio fuera de esa skill». Si no, el agente hará git commit por su cuenta a mitad de una tarea.

Ejercicios

Todos los ejercicios se hacen en el repositorio del tema 1. Desde el ejercicio 2, ningún comando de git se escribe a mano.

Ejercicio 1

Crea el tablero del repositorio (GitHub Project) con las columnas Todo, In progress y Done.
Comprueba en los Workflows del proyecto que está activo «Item closed → Done».
Crea las etiquetas feature y bug.
Crea con gh issue create dos issues: «Página de inicio con el nombre del proyecto» y «README con cómo arrancar». Añádelos al tablero.

Ejercicio 2

Descarga git-flow-skill.md y guárdala como .claude/skills/git-flow/SKILL.md.
Pide al agente que la adapte a este proyecto: quitar release, bajar y subir; que iniciar reciba el número del issue, lo lea con gh issue view y nombre la rama <alumno>-<N>-<slug>; que finalizar ponga Closes #N en el cuerpo del commit; y que publicar lleve develop a main con –ff-only.
Pide que añada la operación commit: agrupar los cambios por intención y proponer los commits antes de hacerlos.
Añade a AGENTS.md el nombre con el que empiezan tus ramas y la regla «git solo con /git-flow».
Lee la skill entera y comprueba que allowed-tools solo tiene git y gh.

Ejercicio 3

/git-flow iniciar con el primer issue y, sin cerrarlo, /git-flow iniciar con el segundo. Comprueba con git worktree list que hay dos worktrees hermanos.
Pasa los dos issues a In progress en el tablero.
En el primer worktree pide al agente la página de inicio; en el segundo, el README.
En cada worktree, /git-flow commit. Mira los mensajes: tienen que llevar type(#N):título.
/git-flow finalizar en el primero. Comprueba en GitHub que el issue está cerrado y en Done y que el worktree y la rama han desaparecido.
/git-flow actualizar en el segundo y después /git-flow finalizar.

Ejercicio 4

/git-flow publicar. Comprueba que main tiene los mismos commits que develop.
Con la carpeta principal en develop, modifica un fichero sin hacer commit y lanza /git-flow iniciar con un issue nuevo. La skill tiene que pararse y decirte por qué. Deshaz el cambio.