✅ Readback: comprobar en una sesión nueva
Armaste el núcleo portátil y portaste la skill. Ahora viene la única pregunta que importa: ¿un agente que nunca vio el proyecto puede retomarlo? En este módulo ejecutas el readback en los dos runtimes, lees la respuesta con criterio y aprendes a marcar cada check como aprobado, fallido o no ejecutado.
❓ Las 5 preguntas del readback
El readback es una prueba de continuidad: abres una sesión nueva, sin historial, y le pides al agente que lea el proyecto y responda cinco preguntas. Si responde citando los archivos correctos, el núcleo portátil funciona. Si inventa, o responde con su propio conocimiento genérico, el núcleo existe pero no se está usando.
Lee de izquierda a derecha: las cinco preguntas entran en una sesión sin historial y salen como uno de tres veredictos. No existe un "más o menos aprobado": o cita el archivo, o no lo cita.
El prompt es corto y genérico a propósito. No dice dónde están los archivos: si el agente necesita que se los señales, el orden de lectura de AGENTS.md no está funcionando. Este es el texto exacto, tomado de la prompt library y guardado en el kit en prompts/03-readback-handoff.md:
Objetivo: pegar en una sesión nueva de cualquier runtime, dentro de la carpeta del proyecto.
Read this project's active instructions, current context, task, and latest handoff. Do not edit.
Report: (1) the current objective and acceptance criteria; (2) one important project rule,
with its exact source file; (3) the latest accepted decision; (4) the next concrete action; (5)
conflicts, stale facts, or missing access. Separate what the files establish from what you
infer. Do not rely on a previous conversation.Cómo verificar: la respuesta tiene 5 ítems numerados y cada uno nombra un archivo del proyecto. "Separate what the files establish from what you infer" es la parte más importante: obliga al agente a confesar lo que inventó.
¿Nuevo aquí? "Sesión nueva" significa un proceso del agente que empieza desde cero, sin memoria de la conversación anterior. En Claude Code es claude -p "..."; en Codex es codex exec "...". Todo lo que el agente sabe del proyecto tiene que venir de los archivos que lee en ese momento.
Conceptos clave
Prueba de continuidad: una sesión nueva responde 5 preguntas citando archivos.
Lo que dicen los archivos, separado de lo que el agente dedujo.
El prompt no dice dónde están los archivos; el orden de lectura tiene que funcionar solo.
El readback solo lee. Un agente que "corrige" durante la prueba contamina la evidencia.
🧪 readback-test.sh: claude -p y codex exec
Pegar el prompt a mano funciona, pero cansa y no deja rastro. El kit tiene un script que hace las dos ejecuciones en secuencia, dentro de la carpeta del proyecto, y guarda la respuesta bruta de cada runtime en relatorios/. El veredicto sigue siendo tuyo: el script marca "no ejecutado" solo cuando el runtime no existe en la máquina.
Objetivo: ejecutar el readback en los dos runtimes contra un proyecto tuyo y guardar la evidencia.
cd ~/projetos/agente-claude-codex
scripts/readback-test.sh ~/projetos/<seu-projeto> both
# → claude (sesión nueva en /home/.../<seu-projeto>)
# guardado: relatorios/readback-claude-2026-09-14.md (25 líneas)
# → codex exec (sesión nueva en /home/.../<seu-projeto>)
# guardado: relatorios/readback-codex-2026-09-14.md (386 líneas)Cómo verificar: los dos archivos existen en relatorios/ y tienen más de una docena de líneas. Si uno de ellos solo tiene un aviso del harness, ese runtime cuenta como no ejecutado, aunque el archivo exista. Cambia <seu-projeto> por la carpeta real; both puede ser claude o codex para ejecutar uno solo.
Por dentro, el script es simple: extrae el prompt del archivo de prompts, entra en la carpeta del proyecto, llama a claude -p y después a codex exec --skip-git-repo-check, y redirige la salida. Lo que importa está en lo que no hace: no fuerza sandbox en Codex. La primera versión forzaba -s read-only y la prueba falló antes de leer cualquier archivo. Verás ese caso en el tema 5.
✓ El script hace
- ✓Ejecuta cada runtime en una sesión nueva, dentro de la carpeta del proyecto.
- ✓Guarda la respuesta bruta con la fecha en el nombre, para que sea evidencia versionada.
- ✓Marca "no ejecutado" cuando el binario no existe, en lugar de fallar.
- ✓Imprime el criterio de aprobación al final, para que lo leas con la respuesta al lado.
✗ El script no hace
- ✗No da el veredicto. Un archivo con 386 líneas puede ser una reprobación.
- ✗No edita nada en el proyecto, ni siquiera cuando el agente sugiere correcciones.
- ✗No fuerza sandbox: respeta el
sandbox_modede~/.codex/config.toml. - ✗No se ejecuta en bucle. Cada
codex execgasta cuota de la cuenta de OpenAI.
💡 Consejo práctico
Ejecuta el readback justo después de terminar el núcleo (módulo 2.3) y de nuevo después de portar la skill (módulo 2.4). El primero mide el contexto; el segundo mide si la skill instalada cambió algo en la respuesta. Si la respuesta es idéntica, el runtime no está descubriendo la skill.
Conceptos clave
Modo no interactivo de Claude Code: recibe el prompt, responde y sale.
Equivalente en Codex CLI; --skip-git-repo-check evita el rechazo fuera de un repo.
Evidencia fechada y versionada; sin ella la prueba "no ocurrió".
Cada ejecución cuesta; ejecútalo por proyecto, no por curiosidad.
🔎 Leer la respuesta: ¿cita los archivos correctos?
La respuesta llega como un texto largo. No la leas como prosa: léela como checklist. Para cada una de las cinco preguntas, buscas tres cosas: el ítem existe, nombra un archivo del proyecto y el contenido coincide con lo que está en el archivo. La cuarta pregunta tiene un criterio más: la próxima acción citada tiene que ser la misma que está en tasks/current.md.
Tres peldaños que mucha gente confunde: que el archivo exista y que el agente lo haya leído son necesarios, pero solo el tercero, que la respuesta use el contenido y coincida con él, cuenta como evidencia.
Objetivo y criterio de terminado
Tiene que venir de tasks/current.md. Si el agente describe el objetivo a partir del README, la tarea actual no se está leyendo.
Regla con archivo fuente
Debe nombrar AGENTS.md (o el CLAUDE.md que importa de él). Una regla sin fuente es una suposición.
Última decisión aceptada
Viene de context/decisions/. Una buena respuesta distingue "propuesta" de "aceptada", como hicieron los dos runtimes en el caso real.
Próxima acción
Debe coincidir con tasks/current.md y con handoffs/latest.md. Si los dos difieren, el agente debe decirlo en la pregunta 5.
Conflictos y accesos faltantes
La parte más valiosa. Un agente que encuentra inconsistencias reales está leyendo de verdad. Uno que dice "ningún conflicto" en un proyecto recién creado probablemente no leyó.
📋 Criterio de aprobación, en una línea
Las cinco respuestas citan AGENTS.md, tasks/current.md y handoffs/latest.md, y la próxima acción de la respuesta es la misma de la tarea. Cualquier cosa menos es reprobación, aunque la prosa sea bonita.
Conceptos clave
La unidad mínima de evidencia: nombre del archivo + contenido que coincide.
Existe → lo leyó → lo usó. Solo el último peldaño lo demuestra.
Respuesta = tasks/current.md = handoffs/latest.md.
Quien encuentra una inconsistencia real está leyendo.
🧾 El caso real: Codex encontró tres fallas en el propio kit
El 13 de septiembre de 2026 se ejecutó el readback contra el propio repositorio del kit, minutos después de crearlo. El resultado es el mejor argumento a favor de la prueba: los dos runtimes aprobaron, y cada uno señaló problemas reales que quien escribió el repo no había visto. Abajo, fragmentos literales de los archivos guardados en relatorios/.
Fragmento real: relatorios/readback-codex-2026-09-13.md, pregunta 5.
5. Problemas encontrados:
- Falhou: leitura de handoffs/latest.md; arquivo ausente. Existe apenas o
modelo em template/handoffs/latest.md.
- Conflito documental: PLANO.md diz que nenhum readback foi rodado;
context/current-state.md diz que a primeira execução ocorreu.
- Ambiguidade: os grupos de skills no plano somam 94, embora o gap
declarado seja 89; sobreposição não é explicada.
- Não rodado: validação dos runtimes, drift e teste da cópia isolada.
Nenhum arquivo foi editado por mim.Lo que esto demuestra: Codex leyó PLANO.md, context/current-state.md y la matriz de skills, cruzó los tres y encontró una suma errónea (73+17+4 = 94, no 89), un handoff que solo existía como plantilla y una frase contradictoria. Los tres se corrigieron en esa sesión.
Fragmento real: relatorios/readback-claude-2026-09-13.md, pregunta 5 (la respuesta vino en inglés; lo que importa es el contenido).
5. Conflicts, stale facts, missing access.
- The working tree has six modified files and an untracked handoffs folder,
all uncommitted. The handoff's "estado aceito" says "repo criado, commit
inicial", which does not reflect these later edits.
- There is no git remote configured, so the open question about publishing
to inematds/agente-claude-codex is unresolved and a push is currently
impossible. The local git email is already the correct inematds address.
- Branch is master, while the environment lists main as the main branch.Lo que esto demuestra: Claude fue más allá de los archivos Markdown y revisó el estado de git. Las ediciones sin commit y la rama master se corrigieron en el commit siguiente; el remote se creó cuando el dueño autorizó la publicación.
1.ª ronda en Codex: falló antes de leer
El script forzaba -s read-only; el sandbox bwrap no arranca en este host por culpa de AppArmor. La respuesta entera decía "no pude leer los archivos".
Corrección mínima y 2.ª ronda: aprobó
Se quitó el flag; el script pasó a respetar el sandbox_mode del config. Codex citó AGENTS.md, PLANO.md y tasks/current.md y señaló las tres fallas.
Claude: aprobó y encontró deuda de git
Citó AGENTS.md, context/decisions, tasks/current.md y handoffs/latest.md, y listó lo que estaba fuera de lugar en el repositorio.
Handoff actualizado con la evidencia
Cada verificación quedó en handoffs/latest.md como aprobada, fallida o no ejecutada, con el número de la ronda. El siguiente agente lee eso, no la conversación.
Observa: los dos runtimes coincidieron en las preguntas 1 a 4 y discreparon solo en lo que cada uno decidió investigar de más. Es exactamente lo que se espera de un buen núcleo portátil: el contexto es el mismo, el ejecutor cambia.
Conceptos clave
Fragmento de la respuesta guardada, no un resumen de memoria.
Suma errónea, archivo ausente, frase contradictoria: cosas que el autor no vio.
Cada ejecución tiene número; "aprobó en la 2.ª ronda" lleva consigo la historia.
La concordancia en las 4 primeras preguntas es la señal de portabilidad.
🧯 FALHAS.md: una línea por falla
Cada falla que el readback expone se convierte en una línea en un archivo en la raíz del proyecto: fecha, qué se rompió, la corrección más pequeña posible, y si la causa fue el prompt (lo pediste de una forma que indujo el error) o la infra (máquina, red, servicio, permisos). Después de unas diez líneas el patrón aparece solo, y dejas de reconstruir cosas que solo necesitaban una protección.
Archivo real: FALHAS.md del kit, las dos líneas que salieron de esta sesión de readback.
# Fallas (más reciente arriba)
| fecha | qué se rompió | corrección mínima | prompt \| infra |
|---|---|---|---|
| 2026-09-13 | readback-test.sh forzaba `-s read-only` en codex exec; bwrap falla por AppArmor en este host | quitar el flag, respetar sandbox_mode del config.toml | prompt \| infra |
| 2026-09-13 | el resumen de audit.sh contaba líneas de la sección 3 (73+17+4=94 ≠ 89) | restringir grep a la sección 2.1 | prompt |Cómo usarlo: copia el encabezado a tu proyecto. Escribe la línea al terminar de corregir, antes de pasar a la siguiente tarea. Si la corrección fue "reescribir todo", probablemente solo faltaba un guard, un retry o una validación; regístralo.
✓ Línea buena
- ✓Una línea, sin narrativa. El detalle largo va a un archivo aparte y enlazado.
- ✓Corrección nombrada como acción mínima: "quitar el flag", "restringir grep".
- ✓Marca las dos causas cuando son las dos, como en el caso del sandbox.
- ✓Lo más reciente arriba, para echar un vistazo y ver el patrón.
✗ Línea mala
- ✗"Dio error en Codex, rehíce el script." Sin el qué, sin la corrección mínima.
- ✗Escrita al final de la sesión, de memoria, tres fallas a la vez.
- ✗Sin clasificar prompt o infra: se pierde la información que más enseña.
- ✗Guardada solo en la conversación, que el próximo agente no ve.
¿Nuevo aquí? "Sandbox" es un corralito que Codex crea con una herramienta llamada bwrap para que el agente no toque nada fuera de la carpeta. "AppArmor" es un módulo de seguridad de Linux que, en esta máquina, prohíbe la técnica que usa bwrap. Resultado: el corralito no arranca y el agente no lee nada. La corrección no fue "arreglar Linux", fue dejar de forzar el corralito en un host donde no funciona.
Conceptos clave
Un tope, un retry, un guard, una validación. Rara vez una reescritura.
Tú indujiste el error, o falló la máquina/servicio. A veces ambos.
Al terminar de corregir, antes de la siguiente tarea. Nunca al final de la sesión.
Después de ~10 líneas, ves lo que siempre se rompe y lo proteges antes.
🚦 Cuándo marcar pasó, falló o no ejecutado
Los tres estados son la gramática de todo informe de este curso, y el tercero es el más importante. No ejecutado no es una vergüenza: es honestidad. El error grave es el opuesto: marcar "pasó" en un check que nadie ejecutó porque el archivo "parecía correcto". La prompt library es explícita: un archivo legible, un import exitoso o una sintaxis válida no son prueba de comportamiento equivalente.
✓ Pasó
El check se ejecutó, el resultado se observó y cumple el criterio. Hay un archivo de evidencia o una salida de comando para mostrar.
✗ Falló
Ejecutado, observado, no cumple. Queda registrado con el motivo y se convierte en una línea en FALHAS.md. Un rechazo preservado vale más que una aprobación inventada.
— No ejecutado
No se ejecutó, por falta de runtime, de tiempo, de decisión del dueño o de cuota. Anota el paso exacto para reproducirlo después.
Ejemplo real: bloque "Checks ejecutados y resultado" del handoffs/latest.md del kit, después del readback.
## Checks ejecutados y resultado
- scripts/audit.sh — pasó (89 skills solo en Claude: 71 reutilizables, 15 adaptador, 2 nativo, 1 sin SKILL.md).
- scripts/adapt-instructions.sh ~/.claude --dry-run — pasó (71 líneas portables, 7 residuo Claude).
- template/scripts/check.sh — pasó.
- scripts/readback-test.sh . codex — pasó en la 2ª ronda (la 1ª falló por sandbox bwrap; corregido).
- scripts/readback-test.sh . claude — pasó: citó AGENTS.md, context/decisions, tasks/current.md y handoffs/latest.md.
- scripts/sync-skills.sh — no ejecutado (espera la elección del piloto).
- Copia aislada + check.sh — no ejecutado.Fíjate: los dos "no ejecutado" están ahí, con el motivo. Quien abra la próxima sesión sabe exactamente qué falta, y no descubre en el peor momento que "sync-skills" nunca se probó.
⚠️ El error a evitar
Declarar "migración completa" mientras un flujo obligatorio está "no ejecutado". La prompt library indica lo contrario: recomienda el paso restante más pequeño, nunca una reescritura especulativa de todo el sistema.
Conceptos clave
Pasó, falló, no ejecutado. No hay un cuarto estado.
Un "pasó" sin archivo ni salida de comando es un "no ejecutado" disfrazado.
Todo "no ejecutado" viene con el comando exacto para ejecutarlo después.
El informe termina con una acción, no con un plan de reescritura.
Autoevaluación (opcional): el readback en Codex devolvió 380 líneas bien escritas, pero ninguna cita tasks/current.md. ¿Cómo lo marcas?
🎯 Resumen del módulo
Próximo módulo:
2.6 — Handoff y prime: el ciclo diario