Cuatro GIF en el README: el argumento, el artefacto y la prueba - #8
Merged
Merged
Conversation
Un repositorio plantilla tiene la particularidad de que su página de inicio es
el producto: alguien abre el README y decide en quince segundos si esto le
sirve. Diez puntos numerados no ganan esa decisión.
Cuatro GIF, en tres registros deliberadamente distintos:
- comparativa.gif (cabecera) — dos carriles de tarjetas: sin plantilla la flecha
vuelve al principio, con plantilla la línea llega recta a un check verde. Es
un argumento
- flujo.gif ("¿Cómo funciona el protocolo?") — el árbol de archivos creciendo
fase a fase: los docs marcados "vacío" que se llenan, .template/ tachándose, y
la pastilla de la ficha pasando de Acordada a En construcción y a Verificada.
Es un artefacto: no explica el producto, es el producto
- cobertura.gif (nueva sección "La regla que lo sostiene") — el script pasando
con la ficha en construcción, fallando al marcarla Verificada sin el test, y
volviendo a pasar cuando existe. Es una prueba
- excepcion.gif (docs/features/README.md) — la excepción sin justificar,
rechazada
Se elimina el diagrama Mermaid del ciclo: contaba lo mismo que flujo.gif con
menos detalle, y tener los dos era repetirse.
Los GIF de terminal se componen de la salida literal del script ejecutado sobre
un proyecto de prueba. Ni una línea de ese texto está escrita a mano; si el
script cambia sus mensajes, hay que regenerarlos en vez de editarlos, y así está
escrito en .template/assets/README.md.
Todo vive en .template/assets/ con sus tres generadores, de modo que al
inicializar un proyecto las imágenes y el README que las referencia desaparecen
juntos. Las referencias que sobreviven a ese borrado quedan anotadas en el
checklist de inicialización.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
¿Qué se hizo?
Cuatro GIF en el README, y fuera el diagrama Mermaid del ciclo.
Los tres primeros hablan idiomas distintos a propósito:
comparativa.gifes un argumento (dos carriles: el bucle contra la línea recta),flujo.gifes un artefacto (el árbol de archivos montándose fase a fase) ycobertura.gifes una prueba (el script bloqueando de verdad). El cuarto,excepcion.gif, va adocs/features/README.mdjunto a la regla que ilustra.Motivación
Un repositorio plantilla tiene la particularidad de que su página de inicio es el producto: alguien abre el README y decide en quince segundos si esto le sirve. Diez puntos numerados no ganan esa decisión.
Que los tres registros sean distintos no es capricho estético. El diagrama de carriles es una afirmación que nadie puede verificar — como toda comparativa de antes y después, una caricatura amable del problema. El árbol que crece es concreto, pero sigue siendo un dibujo. Los GIF de terminal son lo único del README que un escéptico puede reproducir en su máquina, y por eso se quedan aunque sean los más feos: son la parte que demuestra en vez de prometer.
Requisitos que cierra
Ninguno. Este repositorio es el andamiaje: no tiene PRD con requisitos propios.
Tipo de cambio
Evidencia
1. El texto de los GIF de terminal es salida literal del script, capturada sobre un proyecto de prueba (un catálogo de vinilos, el ejemplo del propio
CLAUDE.md). Los tres estados que se ven encobertura.gif:Ni una línea de ese texto está escrita a mano.
2. Peso de los cuatro:
3. La verificación de cobertura sigue limpia:
Verificación de los requisitos:
No aplica: este PR no cierra ningún requisito de PRD.
Checklist
docs/están actualizados —docs/features/README.mdrecibeexcepcion.gifdocs/features/está en estado Verificada — no aplica: este repositorio es el andamiaje y no tiene fichas propiaschangelog/con este cambio — en.template/changelog//security-reviewsi hay cambios sensibles — no se ha ejecutado y no lo veo justificado: son imágenes y documentación. Los tres generadores de.template/assets/no se ejecutan en CI ni forman parte de ningún flujo; son herramientas de autorSobre dónde viven las imágenes. En
.template/assets/, no enassets/. Así, al inicializar un proyecto, la carpeta se borra y el README se reescribe: imágenes y referencias desaparecen a la vez, sin dejar a nadie con GIF de una plantilla que ya no usa.Eso deja un cabo:
docs/features/README.mdsobrevive a ese borrado y referencia una imagen que no. Está anotado en el paso 9 del checklist de inicialización y en/init-proyecto, y además la verificación porgrepdel paso 10 lo caza sola.Sobre mantenerlos.
.template/assets/README.mdexplica cómo regenerarlos y fija la regla que importa: si el script cambia sus mensajes, se vuelve a ejecutar y se regenera el GIF — no se edita el texto a mano. Un GIF que enseña una salida que el programa ya no produce miente igual que una casilla marcada sin comprobar.