# Guarda el contexto de ingeniería en GitHub: relevos de programación con IA entre herramientas y ramas
> Canonical: https://vxi.me/es/posts/github-first-ai-coding-context-handoff-workflow/
> Locale: es-es
> Published: 2026-10-21
> Updated: 2026-10-21
> Markdown: https://vxi.me/es/posts/github-first-ai-coding-context-handoff-workflow.md
Diagrama ilustrativo de recuperación entre herramientas, ramas, revisión independiente y órdenes obsoletas. Permisos de ejemplo.
Al cambiar de herramienta de programación con IA, lo que más cansa no siempre es la calidad del código generado. Es tener que explicar otra vez el proyecto: por qué elegimos esta arquitectura, qué rama sigue activa, cuáles pruebas realmente pasaron, qué PR falta por revisar y hasta dónde llegaban los permisos del agente anterior.
Empecé a sacar ese estado frágil de las conversaciones y a dejarlo en GitHub. Codex, Claude Code, Cursor o ChatGPT en el navegador pueden ser distintos puntos de entrada: primero consultan Issues, ramas y PR. Si la integración tiene permiso de escritura, trabaja en su propia rama; si solo puede leer, deja observaciones de revisión.
A esto lo llamo GitHub-first: **las herramientas de IA pueden cambiar, pero el estado de ingeniería no debería desaparecer con la ventana del chat**. No hace falta mantener un bot coordinador encendido solo para recordar el progreso. Incluso desde el móvil puedo pasar el siguiente paso.
## La memoria del chat no es el contexto de ingeniería
En un proyecto de varios días, B quizá no sepa por qué A descartó un diseño. Una sesión nueva ve la CI en verde de un commit antiguo y asume que el HEAD actual también pasó. Dos personas editan el mismo archivo creyendo ambas que son responsables de la tarea. Pegar diez páginas de conversaciones anteriores puede resolverlo por un rato, pero aumenta la dependencia del historial de un producto.
**Hay que separar recuerdos de conversación y hechos verificables del proyecto.** GitHub no transfiere el razonamiento interno de un modelo ni su chat privado. Sí puede conservar cuatro capas de información que el siguiente agente podrá leer y contrastar:
- **Reglas del proyecto:** `AGENTS.md`, README y notas de arquitectura. No todos los clientes cargan `AGENTS.md` automáticamente.
- **Identidad de la tarea:** Issue, ID, plan, responsable, checkpoint opcional, trabajo terminado y comprobaciones pendientes.
- **Versión del código:** `main`, ramas de funcionalidad, SHA de commit y Git Blob; importa la rama en la que se trabaja de verdad.
- **Revisión y aceptación:** diferencias del PR, comentarios, ACK, ejecuciones de CI del **HEAD exacto**, merges y despliegues.
No hay que inventar una gran base JSON. Git ya gestiona las versiones, Issues y PR registran decisiones, y un checkpoint puede guardar el siguiente paso cuando haga falta. No conviene almacenar secretos, cachés temporales del modelo ni bloqueos de alta frecuencia en el repositorio.
En vez de copiar todo el chat, comienzo una sesión nueva con esta instrucción corta. Mantengo los ejemplos de código en inglés para que sirvan al cambiar de herramienta:
~~~text
You are the developer for this task. Recover project state read-only first.
Repository: OWNER/REPO
Task: Issue #N, linked PR #M, task ID TASK_ID
Read repository rules, the plan, checkpoint, current feature-branch HEAD,
PR diff, the latest applicable review comments, and checks for that HEAD.
Explain the authorized actions, verified work, and remaining gates.
Stop and report if the branch moved, permissions differ, or orders conflict.
Do not merge, deploy, or change production settings without separate approval.
~~~
**Si desarrollas por tu cuenta, empieza por la versión ligera:** README o `AGENTS.md`, un Issue o PR y los últimos commits. Solo añade checkpoint y validación Order/ACK cuando las tareas duren varios días, haya más de un autor o necesites una revisión independiente.
## GitHub como capa de estado para varias herramientas y ramas
La relación entre las piezas puede resumirse así. El SVG animado al inicio del artículo representa la misma idea:
~~~text
Phone / browser / local IDE / cloud coding agent
|
Read GitHub task facts
|
AGENTS.md · Issue · plan · checkpoint
branch · PR
|
Check permission scope
|
Feature branch A Fix branch B
| |
commit commit
| |
PR A PR B
\ /
review + CI per HEAD
|
Human approval to merge
|
main
~~~
Los distintos accesos no tienen automáticamente los mismos permisos en GitHub. Algunas integraciones solo buscan y leen; ciertos Coding Agents pueden modificar archivos y abrir ramas o PR desde su entorno. **Esta explicación corresponde a octubre de 2026; no implica que haya probado una por una las capacidades actuales de todos los productos mencionados.** Antes de operar, reviso los permisos reales de `read`, `write`, `comment`, `merge` y `deploy` según cuenta e integración.
Por ejemplo, un agente en la nube puede trabajar en la funcionalidad A, una sesión desde el navegador puede proponer cambios de documentación y Codex local puede corregir una API. Todos leen las mismas reglas pero escriben en `feature/A`, `docs/B` o `fix/C`. Sus cambios se encuentran en los PR.
**Separar ramas no evita los conflictos lógicos.** Dos ramas pueden modificar la misma interfaz o dependencia. Prefiero un único escritor real por rama de tarea y, antes del merge, reviso la base común, los archivos afectados, la CI más reciente y las pruebas de integración necesarias. La [documentación de Pull Requests](https://docs.github.com/en/pull-requests/get-started/about-pull-requests) y las [ramas protegidas](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches) ya ofrecen las herramientas para hacerlo.
Mantener varios directorios locales aislados es otra cuestión: ahí ayuda Git Worktree, que explico en mi [artículo sobre Worktree](/posts/git-worktree-parallel-development/). Aquí me interesa **cómo distintas herramientas de IA retoman la misma tarea de GitHub y vuelven a reunir sus resultados**.
## Retomar una tarea entre herramientas: verificar Issue, rama y PR
La instrucción inicial solo señala dónde empezar. El nuevo agente debe poder contestar con evidencia: **¿cuál es el HEAD actual, qué entregó el anterior y quién tiene permiso para escribir?**
Para empezar basta con un `AGENTS.md` corto en la raíz. Su función es dirigir al lector hacia las reglas, arquitectura y comandos de prueba que ya existen:
~~~markdown
# AGENTS.md
- Stack and architecture: see README.md and docs/architecture.md
- Install and test: follow the current commands in README.md
- Task entry points: GitHub Issue and linked PR
- Optional state: tasks//checkpoint.json
- Before editing: verify task ID, branch, and live HEAD
- Prefer one writer for each feature branch
- Merges and deployments need separate approval
~~~
En tareas largas añado opcionalmente un `checkpoint.json`. Los nombres de las claves vienen de un checkpoint que uso de verdad, pero los identificadores y SHA de este ejemplo son marcadores reemplazables:
~~~json
{
"task_id": "TASK_ID",
"phase": "P2",
"status": "IN_PROGRESS",
"branch": "feat/TASK_ID",
"commit_sha": "REPLACE_WITH_LAST_VERIFIED_40_HEX_SHA",
"pr": "https://github.com/OWNER/REPO/pull/N",
"verification": { "merge": { "status": "NOT_AUTHORIZED" } },
"next_action": "Read current HEAD and review comments before resuming"
}
~~~
No es una copia de mi archivo privado ni un esquema completo para cualquier proyecto. **Tampoco es necesario actualizar el checkpoint con cada commit.** En un cambio pequeño bastan comentarios en Issue o PR; actualizo el archivo en hitos de revisión, bloqueos o relevos importantes.
Hay una trampa con las SHA que merece explicarse: **`checkpoint.commit_sha` apunta al último commit de código verificado, no necesariamente al commit que contiene el checkpoint ni al HEAD vivo.** Si se verificó el código en A y después se guardó el checkpoint en B, el archivo puede referirse a A. No puede conocer el hash de B antes de crear B. Tampoco existe un desfase fijo de exactamente un commit.
Al retomar, consulta de nuevo el HEAD vivo en GitHub y compáralo con la versión de referencia y los cambios posteriores. Que las SHA difieran no significa automáticamente que haya un error. En el ACK, `observed_head_sha` y `new_head_sha` señalan la versión antigua revisada y la nueva versión entregada. Rechazar una Order antigua es otra validación distinta.
`AGENTS.md` contiene las reglas; Issues/PR guardan el debate y el control de cambios; checkpoint resume el estado si se necesita. Si el cliente no lee `AGENTS.md` por sí solo, se lo pido expresamente.
Publiqué como código abierto el **núcleo de mi protocolo de entrega más estricto**. No hace falta instalarlo para la opción sencilla. Quien quiera inspeccionar cómo Order/ACK fijan un HEAD, detectan instrucciones antiguas o comprueban los relevos con pruebas offline puede leerlo aquí:
vxime/conversation-memory-hub
Este repositorio ofrece protocolo, validadores y ejemplos. No es un servicio alojado que despierte chats de IA automáticamente ni copia el estado de tus proyectos. Las tareas reales, las ramas y los PR siguen en tu GitHub.
## Un PR real: FIX_REQUIRED, ACK y una segunda revisión independiente
Los diagramas pueden dar una falsa tranquilidad: dos IA contestan «entendido» y creemos que ya colaboran. Volví a revisar un PR real de documentación en un proyecto privado. El revisor B señaló dos defectos, el desarrollador A corrigió el documento y devolvió un nuevo HEAD, y B comprobó **esa nueva versión**. La decisión posterior de hacer merge fue independiente y humana.
`FIX_REQUIRED`, `ACK` y `ADVANCE` son **convenciones de comentarios de mi proyecto, no estados nativos de GitHub**. Representan una petición de reparación, la respuesta de A con la nueva versión y la autorización de B para avanzar tras revisarla. `STALE_ORDER` indica que la instrucción pertenece a una versión obsoleta.
El PR solo revisaba un plan de auditoría de Runner en modo lectura; no instaló ningún Runner. El defecto F-001 era revelador: el plan pretendía detectar riesgos de disparadores por comentarios, como `issue_comment`, pero el comando apenas devolvía **nombres de archivos** de workflows.
~~~sh
# Original plan: names only; the YAML triggers remain invisible.
gh api "repos/OWNER/REPO/contents/.github/workflows" --jq '.[].name'
~~~
Con esos nombres no puedes saber si el YAML incluye `issue_comment` dentro del `on:` de nivel superior. F-002 era una referencia equivocada a una sección del documento. La corrección fijó una SHA de auditoría, leyó los disparadores reales de los YAML y comprobó al final que HEAD no se hubiera movido. Contrasté ambas versiones del documento; la [referencia oficial de eventos de Actions](https://docs.github.com/en/actions/reference/workflows-and-actions/events-that-trigger-workflows) explica la importancia de esos disparadores.
A dejó ACK y el nuevo HEAD como comentario en el PR original. B volvió a leer ese HEAD, confirmó las dos reparaciones y solo entonces emitió `ADVANCE`. **Fue un proceso guiado por una persona entre dos sesiones de IA**, no una función que despierte otro chat, ni un `decideResume()` instalado en Actions o como hook local. Para tareas sencillas basta con comentarios normales y el HEAD correspondiente.
Estos son los campos útiles del ACK real; los ID y hashes privados están reemplazados:
~~~json
{
"protocol": "ai-supervisor/ack/v1",
"task_id": "TASK_ID",
"order_id": "REPLACE_WITH_ORDER_ID",
"decision_received": "FIX_REQUIRED",
"observed_head_sha": "REPLACE_WITH_OLD_HEAD",
"new_head_sha": "REPLACE_WITH_NEW_HEAD",
"executed": [
"F-001: Inspect workflow triggers at a pinned SHA",
"F-002: Correct the audit plan's section reference"
]
}
~~~
El protocolo completo también incluye campos adicionales y comprobaciones de integridad. Lo importante es que A señala a qué HEAD antiguo se referían los hallazgos de B y cuál es el HEAD nuevo que entrega. Así B revisa el código real en vez de confiar en «ya está arreglado».
Ese PR modificó documentación únicamente; **no hubo CI exitosa para el HEAD revisado ni una auditoría real de producción en VPS**. Lo que demuestra es un relevo de revisión rastreable, no un sistema autónomo funcionando de extremo a extremo.
## STALE_ORDER: hay que detener órdenes vinculadas a un HEAD antiguo
Una **Order** es una instrucción estructurada que B escribe en comentarios de Issue/PR. Vincula ID de tarea, rama objetivo, `observed_head_sha`, hallazgos y operaciones permitidas o prohibidas. El `order_id` del ACK se refiere a ella.
En una prueba negativa aparte, una Order estaba fijada a un antiguo HEAD de `main` y después la rama avanzó. Al recuperarla, A debía detenerse con `STALE_ORDER` en vez de aplicar la orden vieja sobre código nuevo.
Verifiqué la Order guardada, el HEAD posterior y la comprobación de obsolescencia dentro de `decideResume()`. A informó entonces de que se había detenido, pero **el resultado fue transmitido por una persona: A no escribió en GitHub un ACK independiente**. Es un ensayo negativo útil, no una validación integral en todos los clientes de IA.
La regla práctica es sencilla: B vincula tarea, rama, HEAD y permisos; A vuelve a consultar el HEAD antes de actuar. Si ha cambiado, se detiene y B revisa la nueva versión. Una instrucción correcta ayer puede ser errónea para el código de hoy.
Por eso mantengo una revisión independiente. Que un agente genere un diff convincente no es lo mismo que **otra sesión verifique la corrección sobre el HEAD nuevo real**. El diseño más general de responsables y estado multiagente está en mi [artículo sobre orquestación de agentes](/posts/ai-agent-orchestration-after-assistants/).
## Colaborar desde el móvil no convierte GitHub en un ordenador gratis
La comodidad para mí es no tener que dejar un Mac encendido ni administrar un bot residente solo para seguir el progreso. Desde un teléfono con los permisos adecuados puedo consultar PRs y comentarios y pasar la siguiente instrucción. La edición de código, compilación y pruebas siguen necesitando un agente en la nube, Runner o equipo local con permisos y entorno de ejecución.
Los costes también son dos asuntos distintos: repetir explicaciones y mantener un servicio puede consumir tiempo de operación, mientras que la inferencia del modelo, las cuotas de Chat/Codex/API y la CI tienen sus propias cuentas. **No he medido un ahorro de tokens bajo condiciones comparables**, así que no presentaré un porcentaje inventado.
Mi blog dispone además de una ruta de despliegue GitHub Actions → Self-hosted Runner. El [artículo sobre desarrollo y despliegue entre dispositivos](/posts/chatgpt-web-github-self-hosted-runner/) trata esa fase posterior. Este aborda la anterior: **cómo saber que otra herramienta, dispositivo o persona está continuando exactamente la misma tarea**.
Para un cambio sencillo y de bajo riesgo, un agente con una rama suele bastar. Cuando el trabajo pasa entre días, herramientas y personas, los checkpoints, responsables de rama, revisiones independientes y límites de autorización valen más. Para mí GitHub-first no es la fantasía de memorias compartidas entre IA: es que **los hechos de ingeniería permanecen donde el siguiente participante puede encontrarlos**.
