CommitCycle Insights, en español

La instrucción que escribes una vez, no en cada sesión

Tue, 18 Aug 2026 00:00:00 GMT

Hay un momento, cada pocos días, en el que escribes la misma corrección otra vez. Usa nuestro componente de botón. No añadas una dependencia para eso. Las fechas de este proyecto van siempre en ISO. Lo dijiste el martes, la sesión terminó y el conocimiento terminó con ella.

Una skill es esa instrucción, escrita una sola vez, en un fichero que el agente recoge por su cuenta cuando pasa a ser relevante.

Ése es el concepto entero, y el resto de esta página son los mecanismos, el criterio sobre qué va dentro de una y la depuración — porque el fallo habitual no es escribir una skill mala, es escribir una skill buena que nunca se carga.

Qué es una skill en el disco

Una carpeta con un fichero markdown dentro:

.claude/skills/
  cc-brand/
    SKILL.md
    references/
      token-reference.md
      motion-and-craft.md
      cc-tokens.css
    assets/
      AppShell.vue

SKILL.md abre con un frontmatter que lleva dos cosas que importan:

---
name: cc-brand
description: Implements UI in the CC design system for Vue. Use this WHENEVER
  building, styling, theming or reviewing any Vue interface, component, page,
  dashboard or form for CommitCycle — and whenever the user mentions CC UI, the
  brand blue (#693DFF), Plus Jakarta Sans, shadcn-vue, or "make this on-brand".
---

# CC Design System Implementor

Everything the agent should know, in ordinary markdown.

No hace falta nada más. Ni build, ni registro, ni fichero de configuración. La carpeta existe, luego la skill existe.

¿Por qué no ponerlo en el prompt?

Porque tienes que acordarte cada vez, y no te vas a acordar. Más exactamente: las veces que se te olvida no son aleatorias. Son las veces en que ibas rápido, que son las veces en que el agente tenía menos contexto, que es justo cuando la convención más importaba.

¿Por qué no ponerlo en AGENTS.md?

Ésta es la pregunta de verdad, y la respuesta es el diseño entero de la función.

AGENTS.md (o CLAUDE.md) se carga siempre. Cada turno, cada sesión, cada task, venga o no a cuento. Eso lo hace perfecto para hechos que son siempre ciertos — el stack, los comandos, la estructura de carpetas, lo que nunca hay que hacer — y significa que cada línea que añades cuesta contexto en trabajos que no tienen nada que ver con ella. Un AGENTS.md de 900 líneas es un impuesto sobre cada petición.

Una skill se carga sólo cuando encaja. Lo que está siempre en contexto es su nombre y su description: un par de líneas. El cuerpo se lee sólo cuando el agente decide que el trabajo lo pide.

Esto se llama progressive disclosure, y funciona en tres niveles:

Nivel	Qué se carga	Cuándo
1	Nombre + description	Siempre. No cuesta casi nada
2	El cuerpo del SKILL.md	Cuando la description encaja con la task
3	Los ficheros que acompañan a la carpeta	Cuando el cuerpo apunta a ellos y la task los necesita

Por eso una skill puede ser enorme — un sistema de diseño completo, una checklist de cumplimiento, la superficie entera de una API — sin pagarla en una petición que va de otra cosa. Llevas una biblioteca, no una nota.

Qué va dónde

El criterio que hace que todo esto funcione:

Ponlo en	Cuándo	Ejemplo
El prompt	Cierto sólo para esta task	“Usa azul para la cabecera de esta página”
AGENTS.md	Siempre cierto, siempre relevante, corto	“El stack es Astro + Tailwind. Nunca edites ficheros de `dist/`”
Una skill	Cierto en una situación concreta, demasiado largo para AGENTS.md	Tu sistema de diseño completo, tus convenciones de API, tu voz al escribir
Un servidor MCP	El agente necesita alcanzar algo	Tu base de datos, tu gestor de incidencias, tu analítica

El error habitual es meter contenido del tamaño de un sistema de diseño en AGENTS.md, donde se carga en cada petición, incluidas las que van de un script de build. El otro error habitual es meter el stack del proyecto en una skill, donde puede no cargarse en el momento en que hace falta.

La description es el disparador entero

Si te llevas una sola cosa de esta página: la description no es documentación, es la regla de coincidencia. Es la única parte de tu skill que el agente ve antes de decidir si lee el resto.

Así que escríbela con las palabras que una persona teclea de verdad. No:

Directrices de implementación de marca y estándares de componentes.

Eso no coincide con nada. Quien pide “haz que esto se parezca a nuestra app” no ha usado ninguna de esas palabras. Mejor:

Úsalo siempre que construyas, estilices, tematices o revises cualquier interfaz, página, dashboard, formulario o componente de [producto] — y siempre que se mencione [el color de marca], [la tipografía], [la biblioteca de componentes] o “que quede on-brand”. Recurre a ello incluso cuando la petición sea sólo “haz una página de ajustes” o “dale estilo a esta tarjeta”.

Concretamente, una description que salta de forma fiable nombra:

Los verbos — construir, estilizar, revisar, migrar, redactar
Los sustantivos — los artefactos a los que se aplica
Las cadenas literales — nombres de producto, códigos hex, nombres de tipografía, nombres de biblioteca
Las formulaciones informales — “que quede on-brand”, “como siempre”, “como el resto de páginas”
Cuándo usarlo aunque no parezca que aplica — esta línea hace un trabajo sorprendente

Pasarse de inclusivo cuesta un poco de contexto cuando salta sin necesidad. Quedarse corto te cuesta la skill entera, en silencio, para siempre. Inclínate por que salte.

Dónde viven las skills

Dos sitios, y la elección importa más de lo que parece.

.claude/skills/ dentro del proyecto. Se commitea con el repositorio, así que está en tu otro ordenador, en cada sesión futura y para cualquiera que lo clone. Todo lo que describe este producto va aquí.

~/.claude/skills/ en tu carpeta personal. Disponible en cada proyecto que toques, invisible para todos los demás. Esto es para tu propia forma de trabajar: cómo te gusta que se escriban los commits, cómo quieres estructurados los documentos.

Por defecto, el proyecto. Una skill que vive sólo en tu portátil está a un ordenador de distancia de no existir, y es la razón por la que un proyecto “sólo funciona bien cuando lo ejecutas tú”.

¿Cómo sé que ha saltado?

Pregunta. ¿Qué skills has usado para eso? es una pregunta razonable y tiene una respuesta directa. ¿Qué skills tienes disponibles? las lista, que es la primera comprobación después de instalar una.

La comprobación fuerte es de comportamiento: abre una sesión nueva, formula una petición como la formularía un usuario real — no como la formula la documentación de la propia skill — y mira si la salida cumple las normas sin que las menciones. Ése es el único test que importa, porque ésa es la condición real de uso.

¿Por qué no salta mi skill?

Síntoma	Casi siempre	Arreglo
No se carga nunca	La description no contiene las palabras que se teclean	Reescribe la description con formulaciones reales y nombres literales
Se carga, y luego la salida la ignora	El SKILL.md es demasiado largo o las normas están enterradas en prosa	Recórtalo. Empieza por las normas. Mueve el detalle a `references/`
Se carga con todo	La description es demasiado amplia	Añade el límite: para qué no es
A ti te funciona, a un compañero no	Está en `~/.claude/skills/`, no en el proyecto	Muévela al repositorio y commitéala
Otras instrucciones la contradicen	AGENTS.md dice otra cosa	Decide cuál gana y dilo explícitamente en las dos

Fíjate en que cuatro de los cinco son problemas de description o de ubicación. El contenido casi nunca es lo que está mal.

Mantener corto el SKILL.md

Una vez cargado, el cuerpo se lee entero — así que la longitud cuesta algo, y la buena estructura es un fichero de instrucciones corto que apunta al detalle.

SKILL.md              las normas, el orden de decisión, qué gana en un conflicto
references/           el material largo: tablas de tokens, superficies de API, ejemplos
assets/                cosas que copiar: componentes, hojas de estilo, plantillas
scripts/               cosas que ejecutar

La skill cc-brand del ejemplo de arriba tiene exactamente esta forma: el SKILL.md declara la prioridad de capas y la regla de conflicto en unos cientos de palabras, y la referencia de tokens, la guía de movimiento y los componentes de shell ya hechos están en ficheros a los que apunta. El agente abre la referencia de la barra lateral cuando está construyendo una barra lateral, y nunca en otro caso.

Dos cosas van en el SKILL.md y no en un fichero de referencia: el orden de precedencia (cuando dos normas chocan, cuál gana) y qué no hacer. Las dos son cortas y las dos son lo que el agente hace mal cuando faltan.

Skills, MCP, subagents, slash commands

Cuatro cosas que se confunden, en ejes genuinamente distintos:

	Qué es	Quién lo dispara
Skill	Instrucciones que se cargan por relevancia	El agente, al encajar la description
Servidor MCP	Tools que alcanzan sistemas externos	El agente, cuando necesita la tool
Subagent	Una ventana de contexto aparte para trabajo delegado	El agente, o tú
Slash command	Un prompt guardado que invocas por su nombre	Tú, explícitamente

Skills y MCP son complementos, no alternativas. El servidor MCP le da al agente una conexión con tu base de datos; la skill le cuenta tus convenciones de esquema y qué tablas no se escriben nunca directamente. Tools sin instrucciones es la configuración que tiene casi todo el mundo, y es la razón por la que el agente puede alcanzarlo todo y aun así hacer lo que no toca con ello.

Instalar una que te han pasado

Pon la carpeta en .claude/skills/ (proyecto) o ~/.claude/skills/ (personal).
Abre una sesión nueva — una ya abierta ha construido ya su lista.
Pregunta qué skills tienes disponibles y comprueba que la tuya aparece por su nombre.
Dale una petición realista y mira si las normas se aplican sin mencionarlas.

Si falla el paso 3, la carpeta está en el sitio equivocado o el SKILL.md está mal nombrado. Si falla el paso 4, es la description.

La que merece la pena instalar el primer día es una skill de diseño. Si tienes una idea pero todavía ni marca ni opinión visual, startpow.com te deja elegir lo que te gusta, exportar y descargar el resultado como skill. La sueltas dentro y, a partir de ahí, cada pantalla que construya el agente llega con tus colores, tu tipografía y tu espaciado sin que los describas otra vez — que es más o menos la diferencia entre un producto y una demo, por unos diez minutos de trabajo.

¿Cuántas skills son demasiadas?

Hay un presupuesto real, y no es el que preocupa a la gente. Los cuerpos son gratis hasta que se cargan, así que una carpeta con cuarenta skills no ralentiza nada. Lo que no es gratis son las descriptions, que están todas en contexto, todo el rato.

Cuarenta descriptions vagas son peores que cinco afiladas por una segunda razón: cuantas más se solapen, menos fiable es que gane la correcta. Dos skills que cubren “estilos” de forma igual de plausible significan un cara o cruz en cada petición de UI.

La forma práctica es un puñado de skills con fronteras limpias, cada una de las cuales podrías describir en una frase sin usar la palabra “y”. Cuando no puedes, eso son dos skills.

Una skill son instrucciones que aceptas ejecutar

Merece la pena decirlo claro, porque las skills se pasan de mano en mano como si fueran plantillas de estilo, y no lo son.

Una skill es un conjunto de instrucciones que un agente va a seguir, con tus permisos, en tu repositorio. Una skill descargada puede decirle a un agente que instale un paquete, que mande un fichero a alguna parte, que trate una norma como más importante que las que escribiste tú. Es la misma decisión de confianza que ejecutar un script que te ha mandado alguien, y el hecho de que sea markdown y no código la hace parecer más pequeña de lo que es.

Así que: lee el SKILL.md antes de instalarla, mira qué más hay en la carpeta y ten más cuidado con las skills que traen scripts que con las que traen documentación. Un sistema de diseño de una herramienta que elegiste tú es algo muy distinto de una skill pegada en un hilo de un foro.

Lo mismo vale al revés cuando publicas una: quien instale la tuya te está extendiendo esa confianza.

Llevarlas a un equipo

Tres vías, de menor a mayor ceremonia:

Commitéalas al repositorio. .claude/skills/ está en el repo, así que clonarlo las trae. Esto cubre la mayoría de los casos y no necesita infraestructura ninguna.
Distribúyelas en un plugin. Un plugin puede llevar skills junto con comandos y servidores MCP, se instala por su nombre y se actualiza de forma centralizada. Lo correcto cuando varios repositorios necesitan las mismas convenciones.
Manda la carpeta. Vale una vez, es inmanejable a la cuarta persona, porque ya no hay respuesta para “¿qué versión tienes tú?”.

El fallo que hay que evitar es aquél en el que la skill existe sólo en la carpeta personal de alguien. El proyecto se comporta entonces de forma distinta según quién esté al mando, y nadie puede ver por qué.

La forma más rápida de escribir tu primera skill

No empieces con una página en blanco. Las páginas en blanco producen normas genéricas, y las normas genéricas son las que el modelo ya sigue.

En su lugar: trabaja normal, y presta atención a lo que corriges. La tercera vez que digas lo mismo — la tercera vez que señales el formato de fecha, o el componente, o que aquí no usamos esa biblioteca — di:

Convierte lo que acabas de aprender en una skill. Escribe la description para que salte siempre que alguien pida algo de esta área, incluidas las formulaciones informales. Mantén corto el SKILL.md y pon el detalle largo en un fichero de referencia.

Tus correcciones ya son exactamente el contenido que una skill necesita. Son específicas, son reales y son las que de verdad se estaban haciendo mal — que es un punto de partida mucho mejor que cualquier cosa que se te ocurriera escribir de antemano.

Trucos que marcan una diferencia real

Enseña, no sólo cuentes. Un ejemplo trabajado de tu convención rinde más que tres párrafos describiéndola. Los modelos son extremadamente buenos reconociendo patrones a partir de un ejemplo, y meramente obedientes al seguir una norma.
Una skill por asunto. Una única skill de “nuestros estándares” que cubra diseño, testing y despliegue salta con todo y no se aplica bien a nada. Divídela.
Di qué gana. Toda skill que contenga más de una fuente de criterio necesita una frase que diga cuál tiene precedencia en un conflicto. Sin ella elige el modelo, y elige distinto cada vez.
Escribe las normas en negativo. No introduzcas una segunda biblioteca de componentes. No añadas dependencias para algo que ya hace la biblioteca estándar. Las restricciones negativas se siguen de forma más fiable que las positivas y casi siempre son lo que de verdad te importaba.
Versiónala con el código que describe. Una skill de diseño en el repositorio cambia en el mismo commit que los tokens que documenta. Una skill de diseño en tu portátil se desvía en quince días y luego enseña con toda confianza los colores del mes pasado.
Prueba con una sesión fría y una formulación perezosa. “haz la página de ajustes” es como llegará la petición de verdad. Si la skill necesita la versión bien formulada para saltar, no funciona.
Deja morir a las skills viejas. Una skill que describe una convención que abandonaste es peor que ninguna skill: es una instrucción segura de sí misma, siempre disponible, para hacer lo que no toca.

Si no estás en Claude Code

Las skills como carpetas son una función de Claude Code. Otras herramientas agénticas leen un único fichero de instrucciones siempre cargado, y la convención casi universal es AGENTS.md en la raíz del repositorio.

El contenido se traslada tal cual. Lo que no se traslada es la carga selectiva — todo lo que hay en ese fichero se paga en cada petición — así que la disciplina es otra: limítalo a lo que siempre es cierto, pon el material largo en documentación normal y apunta a ella desde el fichero en lugar de pegarla dentro.

En cualquier caso, el movimiento de fondo es el mismo, y es el hábito de mayor palanca del desarrollo con agentes: la segunda vez que expliques algo, escríbelo donde el agente lo vaya a encontrar. El resto del montaje que rodea a esto — el repositorio, el modelo, el host, el stack, las salvaguardas — son seis decisiones.

GitHub para quien no escribe el código

Tue, 18 Aug 2026 00:00:00 GMT

Si nunca has usado GitHub, ignora cómo suele describirse. No es una red social para programadores, no estás ahí para leer el código de nadie, y los cuadraditos verdes no son un marcador que tengas que rellenar.

Es un sistema de guardado con historial, alojado en un sitio que no es tu portátil. Eso es todo.

Para un vibe coder se gana el sitio por una razón concreta. En algún momento — no quizá, en algún momento — una sesión reescribirá algo que ya funcionaba. Refactorizará un fichero que te gustaba, borrará una función que decidió que no se usaba, o arreglará un bug introduciendo dos en silencio. Sin commits, ese trabajo se ha ido y tu única recuperación es describirlo otra vez de memoria a un modelo que ha olvidado la conversación. Con commits, la recuperación es una frase.

Esta guía es todo lo que necesitas para eso, y nada que no necesites.

Git y GitHub no son lo mismo

Merece diez segundos, porque confundirlos es lo que hace confuso todo lo demás.

Git es un programa en tu ordenador. Registra versiones de una carpeta. Funciona sin internet, sin cuenta y sin web, y es lo que hace todo el trabajo real.

GitHub es una web que guarda una copia de un repositorio Git y añade lo que una web puede añadir: una página para navegarlo, un sitio para otras personas, automatización que corre cuando subes algo.

Así que cuando tu agente “commitea”, eso es Git, en local, al instante. Cuando hace “push”, eso es la copia viajando a GitHub. Por eso puedes trabajar en un avión y por eso un commit no es una copia de seguridad hasta que se ha subido.

Las alternativas — GitLab, Bitbucket, Codeberg — son el mismo Git por debajo con otra web encima. Nada de esta guía cambia si eliges una de ésas.

Las siete palabras que cubren casi todo

Van en inglés porque así es como las verás en GitHub y en la terminal:

Palabra	Qué es en realidad
Repository (“repo”)	Tu carpeta de proyecto, más cada versión que ha sido
Commit	Un punto de guardado con una nota pegada
Branch (rama)	Una copia del proyecto donde puedes romper cosas sin peligro
Push / pull	Mandar tus commits a GitHub / traerte los de los demás
Clone	Descargar un repositorio entero, historial incluido
Pull request (“PR”)	“Aquí hay un cambio, míralo antes de que entre”
Merge	Plegar los commits de una rama dentro de otra

Dos más que verás y que puedes ignorar casi siempre: origin es el apodo por defecto de “la copia que está en GitHub”, y main es el nombre por defecto de la rama principal.

¿Necesito aprender comandos de Git?

No, y ésta es la parte que nadie le cuenta a quien empieza. Necesitas tres frases que decirle a tu agente, y él ejecuta los comandos.

Commitea esto con un mensaje claro.
¿Qué ha cambiado desde el último commit?
Deshaz todo desde el último commit.

Ésa es la interfaz entera de tu primer mes. Lo que sí necesitas es entender qué significan esas tres cosas, que es para lo que está el resto de esta página — porque el fallo habitual no es teclear el comando equivocado, es pedir el tipo de deshacer equivocado.

Si prefieres botones a frases, GitHub Desktop es gratuito, muestra los ficheros cambiados como un diff visual y convierte commit y push en dos clics. Mucha gente que publica productos reales no usa nunca la terminal para Git.

Dónde vive tu código mientras trabajas

Los mensajes de Git hablan de ficheros “staged”, “tracked” y “untracked”, y nada de eso tiene sentido hasta que sabes que hay tres sitios donde puede estar un cambio:

Sitio	Qué significa	Cómo sale de ahí
Directorio de trabajo	Tú (o el agente) habéis editado el fichero. No hay nada registrado	`git add`
Área de staging	Marcado como parte del próximo commit, pero todavía sin guardar	`git commit`
Ya en un commit	Registrado en el historial de forma permanente	`git push` lo manda a GitHub

El área de staging es la parte que al principio parece inútil. Su propósito es elegir: han cambiado doce ficheros, cuatro pertenecen a este commit, así que pones esos cuatro en staging. Como vibe coder commitearás casi siempre todo de golpe — pero necesitas saber que el staging existe, porque si no “changes not staged for commit” es un mensaje de error sobre nada.

git status es el comando de “dónde estoy”, y es el que merece la pena que sepas leer tú. Te dice en qué rama estás, qué ha cambiado, qué está en staging y si vas por delante o por detrás de GitHub. Cuando algo confunde, esto es lo primero que hay que mirar, y es completamente seguro: no cambia nada.

El primer fichero que importa: .gitignore

Antes de tu primer push, antes que nada: .gitignore es una lista de ficheros que Git no debe registrar nunca.

Como mínimo contiene:

.env
.env.local
node_modules/
.DS_Store
dist/

.env es el que importa. Ahí es donde viven tus API keys, y esa única línea es lo que impide que se publiquen la primera vez que subes algo. Los repositorios públicos los escanea continuamente gente que busca exactamente esto, y una clave filtrada se encuentra en minutos, no en días.

Pídelo explícitamente al montar el proyecto — añade un .gitignore apropiado para este stack, y asegúrate de que .env está dentro — y luego comprueba con tus propios ojos que .env aparece. Es una comprobación de treinta segundos que evita el error caro más habitual de quien empieza.

Haz el repositorio privado por defecto. Público es una decisión deliberada de publicar, y es mucho más fácil hacer público después un repositorio privado que despublicar algo, incluido todo lo que hay en su historial.

¿Cómo leo un diff sin leer código?

Un diff es lo que cambió, mostrado línea a línea. Las líneas verdes con + se añadieron, las rojas con - se quitaron, las grises son contexto sin cambios. No necesitas entender el código para sacarle valor real:

¿Cómo de grande es? Doce líneas cambiadas para una petición pequeña es normal. Cuatrocientas es una señal para parar y preguntar qué más ha hecho.
¿Qué ficheros? Si pediste un cambio de color y en la lista hay un fichero con auth, migration o schema en el nombre, ése es el momento de preguntar por qué.
¿Se ha borrado algo que no pediste borrar? Los bloques largos de rojo merecen una pregunta.

Ésa es toda la habilidad, y es la mayor parte de lo que una revisión de código te da en un proyecto en solitario. Enséñame el diff y explícame en lenguaje llano qué hace el cambio de cada fichero es una buena costumbre antes de cada commit.

¿Qué hace que merezca la pena escribir un mensaje de commit?

Su único trabajo es ayudar al tú del futuro a encontrar un momento en el tiempo. “Update” y “fixes” fracasan en eso; seis seguidos son indistinguibles.

Escribe cuál es el estado, no lo que hiciste: pantalla de login funciona, validación aún sin hacer. Seis semanas después, ese mensaje es lo que te deja decir “vuelve a cuando el login funcionaba” y que signifique algo preciso.

Commitea cuando algo funciona, no al final del día. El final del día es un punto de guardado para ocho horas de decisiones. Cada estado que funciona es un sitio al que puedes volver.

¿Cuándo necesito de verdad una rama?

Como vibe coder en solitario, menos a menudo de lo que dan a entender los tutoriales. Necesitas una cuando estás a punto de probar algo de lo que podrías arrepentirte: una refactorización grande, un cambio arriesgado de dependencia, un experimento del que sólo estás medio convencido.

La razón es que deshacer sale gratis. Estás en experiment, sale mal, te vuelves a main y borras la rama. Nada que desenredar, nada que revertir, ninguna discusión con el agente sobre qué cambió.

En el momento en que alguien más toca el repositorio, esto deja de ser opcional y pasa a ser una rama por cada pieza de trabajo — que es donde el vibe coding se pone genuinamente más difícil, y un problema distinto de éste.

¿Cómo deshago algo?

La sección más importante de esta página. Hay cuatro tipos de deshacer y pedir el que no es, es como la gente pierde trabajo intentando salvarlo.

1. Tienes cambios sin commitear y los quieres fuera.

git restore .

Todo lo posterior al último commit desaparece. Éste es el de cada día: la sesión salió mal, no había nada que valiera la pena, se empieza otra vez desde el último estado bueno.

2. Commiteaste, pero no has subido, y quieres el commit fuera.

git reset --soft HEAD~1   # deshace el commit, conserva los cambios
git reset --hard HEAD~1   # deshace el commit y los cambios

--soft es para “commit correcto, mensaje equivocado, momento equivocado”. --hard es para “esa dirección entera estaba mal”.

3. Ya subiste, y otras personas (o un despliegue) lo tienen.

git revert <commit>

Esto hace un commit nuevo que deshace el viejo. Es el seguro, porque añade al historial en lugar de reescribirlo, y nada de lo que ya tiene otra persona entra en conflicto con lo que tienes tú.

4. Crees que has perdido algo para siempre.

git reflog

Git guarda un registro privado de cada posición en la que ha estado tu rama durante unos noventa días, incluidos commits que “borraste” y ramas que quitaste. Casi nada se pierde de verdad. Éste es al que recurrir después de un --hard del que te arrepientes o de un force-push que se comió tu tarde — y merece la pena saber que existe precisamente porque el momento en que lo necesitas es el momento en que estás en pánico.

¿Qué es un conflicto de merge, y quién lo arregla?

Dos ramas cambiaron las mismas líneas. Git no va a adivinar qué versión gana, así que marca la sección en disputa en el fichero con <<<<<<< y >>>>>>> y se para.

No hay nada roto ni nada perdido. Las dos versiones están ahí mismo; alguien tiene que elegir.

Los agentes son buenos en esto, con una condición: cuéntales para qué era cada cambio. La decisión va de intención, no de sintaxis — este lado es la lógica nueva de precios, ése es el arreglo del bug de ayer, conserva los dos comportamientos obtiene una resolución correcta. “Arregla el conflicto” obtiene un cara o cruz.

¿Qué pasa si commiteo una API key?

Rótala. Ya. Ve al servicio, revoca la clave, emite una nueva.

Borrar el fichero en un commit posterior no hace nada, porque la clave sigue ahí en el historial, donde cualquiera puede leerla. En un repositorio público, da por hecho que se rastreó en minutos: esto está automatizado a escala.

GitHub ayuda en dos puntos, y merece la pena activar los dos. Secret scanning detecta formatos de clave conocidos en tu repositorio y te avisa. Push protection va más allá y bloquea el push antes de que el secreto llegue a aterrizar. Ninguno cubre todos los formatos, así que .gitignore sigue siendo la defensa de verdad.

Limpiar la clave del historial después es posible y engorroso. También es secundario: una vez rotada la clave, la que está en el historial es una cadena muerta.

¿Qué más es GitHub, más allá del almacenamiento?

Cosas con las que te vas a encontrar, en una línea cada una:

Issues — una lista de pendientes pegada al proyecto. Vale para notas en solitario, aunque un board de verdad es mejor en cuanto el trabajo toma forma.
Actions — automatización que corre al hacer push. Así es como corren los tests y como se disparan los despliegues. Te lo encontrarás la primera vez que conectes un host.
Releases y tags — un nombre clavado a un commit concreto. v1-launch es un marcador que dice esta versión era buena, y no cuesta nada.
Pages — alojamiento estático gratuito directamente desde un repositorio. Vale para una landing, no para nada con backend.
Fork — tu propia copia del repositorio de otra persona. Relevante cuando quieres cambiar el proyecto de código abierto de alguien.
Dependabot — abre pull requests cuando una dependencia tiene un arreglo de seguridad. Gratis, merece la pena dejarlo activado.
Codespaces — un entorno de desarrollo completo en el navegador. Útil cuando quieres trabajar desde una máquina que no tiene nada instalado.

Cosas que te confundirán exactamente una vez

Cada una de éstas produce un momento de alarma genuina, y cada una es inofensiva una vez la has visto.

“You are in ‘detached HEAD’ state.” Miraste un commit antiguo y ahora estás parado encima de él en lugar de sobre una rama. Los commits hechos aquí no pertenecen a nada y son fáciles de perder. git switch main te devuelve. No hay nada roto.

Tu repositorio contiene otro repositorio. Un agente ejecutó git init dentro de una carpeta que ya estaba en un repo, normalmente mientras montaba algo. GitHub muestra entonces una carpeta que no puedes abrir y que no contiene nada. El arreglo es borrar la carpeta .git interior — y la pista es un commit que añade un directorio pero ninguno de los ficheros que hay dentro.

Un fichero es demasiado grande para subirlo. GitHub rechaza ficheros individuales de más de 100 MB, y un vídeo, un volcado de base de datos o un node_modules que se escapó del .gitignore van a chocar con eso. La trampa es que quitar el fichero no arregla el push, porque sigue en el historial: hay que deshacer el commit que lo añadió. Mucho más fácil prevenirlo: revisa el .gitignore antes del primer push.

Tus dos máquinas no se ponen de acuerdo. Commiteaste en el portátil, subiste, y luego commiteaste en el sobremesa sin hacer pull. Git rechazará el segundo push. git pull primero, resuelve lo que te pregunte, y luego push. La costumbre que lo evita del todo es hacer pull al empezar una sesión y no al terminarla.

El agente ha commiteado como otra persona. Los commits llevan el nombre y el email de tu configuración local de Git, que en una máquina recién estrenada puede estar vacía o mal. Merece la pena configurarlo una vez, o tu historial estará firmado por “unknown”.

Trucos que se pagan solos

Commitea antes de cada sesión con el agente, no después. El commit no es un registro de lo que hiciste, es el punto de guardado que estás a punto de arriesgar. Diez segundos, y convierte cada desastre en un git restore .
Pide el diff antes de aceptar. Enséñame qué has cambiado y por qué pilla el extra servicial que no querías, que es el fallo más habitual que sobrevive hasta producción.
Una rama por experimento, y borrarla es el deshacer. Más barato que cualquier revert.
git stash cuando el agente se queje de un árbol sucio. Se guarda en el bolsillo tu trabajo sin commitear; git stash pop te lo devuelve. Mejor que commitear basura para desatascarte.
--force-with-lease, nunca --force a secas. Los dos reescriben lo que hay en GitHub. El primero se niega si alguien ha subido algo mientras tanto; el segundo lo sobrescribe sin preguntar.
Protege main en cuanto haya algo real dentro. La protección de ramas de GitHub puede exigir un pull request antes de fusionar, lo que hace que “el agente subió directo a main a las 2 de la mañana” sea estructuralmente imposible en lugar de meramente desaconsejado.
Etiqueta la versión que funcionaba. Antes de un cambio grande, v-works no cuesta nada y se encuentra sin esfuerzo, a diferencia de un hash de commit que no vas a reconocer jamás.
Haz squash al fusionar. Catorce commits de “wip”, “fix”, “esta vez sí” se colapsan en una entrada con sentido, y tu historial sigue siendo legible por un humano — y por el siguiente agente que lo lea.
Acuérdate de que reflog existe antes de necesitarlo. En el momento en que lo necesites no estarás en condiciones de descubrirlo.

Qué hacer el primer día

Crea la cuenta. Haz el primer repositorio privado.
Pon el .gitignore en su sitio con .env dentro, y compruébalo con tus propios ojos.
Pídele al agente que haga el primer commit y lo suba. Mira el repositorio en GitHub y ve tus ficheros ahí.
Y después, cada vez que algo funcione: commitea esto con un mensaje claro.

Ésa es la práctica entera. Todo lo demás de esta página está ahí para el día en que algo salga mal — y la razón para leerlo ahora es que el día en que algo sale mal es un mal día para estar aprendiendo qué tipo de deshacer necesitas.

El resto del montaje en el que esto encaja — el modelo, el host, el stack, las salvaguardas — son seis decisiones, y el control de versiones es la que todas las demás dan por hecha que ya tienes.

Seis decisiones antes de tu primer prompt, y por qué está ahí cada una

Tue, 18 Aug 2026 00:00:00 GMT

Nadie quiere gastar una tarde en setup. La tentación es abrir un chat y empezar a describir la cosa, y para un prototipo ése es el instinto correcto — la primera semana tiene su propio post y casi todos los consejos de allí son ve más rápido.

Éste es el otro post. Es para el momento en que decides que la cosa seguirá existiendo el mes que viene, y son seis decisiones. Cada una cuesta minutos. Cada una cierra una forma concreta de que la segunda semana salga mal, y la razón de tomarlas juntas es que las seis son baratas ahora y caras después.

Ninguna de ellas va sobre qué modelo es el mejor.

1. GitHub, que es un botón de deshacer con el que puedes hablar

Si no lo has usado nunca, ignora cómo se suele describir. GitHub no es una red social para programadores y no estás ahí para leer el código de nadie. Es un sistema de guardado con historial, alojado en un sitio que no es tu portátil.

Cinco palabras cubren casi todo lo que necesitas:

Repositorio — la carpeta de tu proyecto, más todas las versiones que ha tenido.
Commit — un punto de guardado con una nota pegada. «La pantalla de login funciona» es un commit.
Rama (branch) — una copia del proyecto donde puedes romper cosas sin romper el original.
Push / pull — sincronizar entre la copia de tu máquina y la copia en GitHub.
Pull request — «aquí hay un cambio, míralo antes de que entre». Estando solo no lo necesitarás; lo necesitarás el día en que otra persona toque el proyecto.

Y aquí está por qué le importa específicamente a quien hace vibe coding. En algún momento — no «quizá» — una sesión reescribirá algo que ya funcionaba. Refactorizará un fichero que te gustaba, o borrará una función que decidió que no se usaba, o arreglará un bug metiendo dos. Sin commits, ese trabajo desaparece y tu única recuperación es describirlo otra vez de memoria. Con commits, la recuperación es una frase.

Lo que lleva a la parte que nadie le cuenta a los principiantes: no tienes que aprender Git. Tienes que aprender tres frases que decirle a tu agente.

Haz commit de esto con un mensaje claro.
¿Qué ha cambiado desde el último commit?
Deshaz todo desde el último commit.

Ésa es toda la interfaz durante el primer mes. El agente ejecuta los comandos.

Móntalo así y deja de pensar en ello: crea la cuenta, haz el repositorio privado por defecto, y antes que nada asegúrate de que .env está en .gitignore. Esa única línea es lo que impide que tus claves de API se publiquen la primera vez que hagas push. Las claves se filtran constantemente desde repositorios de principiantes, y se rastrean en cuestión de minutos.

Luego un hábito, que es lo de mayor rendimiento de todo este post: cuando algo funcione, haz commit. No al final del día. En el momento en que funciona.

Con eso basta para empezar. El resto — leer un diff sin leer código, los cuatro tipos distintos de deshacer y cuándo aplica cada uno, qué hacer el día que hagas commit de una clave de API — está en la guía completa.

2. Un modelo, y importa menos de lo que crees

Claude Code, Codex, o un modelo de pesos abiertos que ejecutes tú. Dicho con franqueza: ésta es la decisión que puedes revertir gratis. El repositorio es portable, tus prompts son portables, y nada de lo que construyas queda atado a la herramienta que lo escribió.

Lo que de verdad los separa no son las puntuaciones en benchmarks, es si la herramienta vive dentro de tu proyecto:

	Qué es	Dónde encaja
Claude Code	CLI agéntica en tu terminal, lee y escribe tus ficheros, ejecuta comandos	Construir funcionalidades enteras a través de muchos ficheros
Codex	El equivalente agéntico de OpenAI, terminal y nube	El mismo trabajo, otro estilo de la casa
Pesos abiertos (vía Ollama, LM Studio, y un cliente como Aider o Cline)	Modelos corriendo en tu máquina o en tu propio servidor	Privacidad, control de coste, sin factura por token

La recomendación: elige una herramienta agéntica de pago y quédate en ella un mes. No porque las otras sean peores, sino porque la habilidad que estás construyendo es saber qué pedir y cómo detectar que la respuesta está mal, y esa habilidad se transfiere despacio mientras sigues cambiando de herramienta cada semana.

Sobre open source, con franqueza: es real, es más barato, es privado, y es el primer movimiento equivocado. Te gastarás la primera semana en setup en lugar de en la cosa que querías construir, y los trabajos agénticos largos — muchos ficheros, muchos pasos, sostener el plan hasta el final — son exactamente donde la brecha sigue siendo más ancha. Vuelve a ello en el mes dos, cuando sepas qué estás comparando.

Y elijas la que elijas, la palanca no está en el modelo. Está en lo que el modelo puede ver de tu proyecto, que son las decisiones 4, 5 y 6.

3. Un host, y una sola cuenta si puedes

Vas a necesitar dónde ponerlo. Las dos respuestas obvias son Cloudflare y Vercel, y la pregunta que decide no es el rendimiento.

Es cuántas cuentas quieres sostener.

Cloudflare es el todo-en-uno: hosting, una base de datos (D1), almacenamiento de ficheros (R2), clave-valor, el propio dominio, DNS, enrutado de correo — un login, una factura, un sitio donde están mal las cosas cuando están mal. Para alguien que empieza, esa consolidación vale más que cualquier funcionalidad concreta. El precio es un runtime que no es exactamente Node, así que un puñado de paquetes de npm no correrán ahí, y te enteras al desplegar y no al instalar.

Vercel te da el despliegue más suave que existe si estás en Next.js. El intercambio es que las piezas de datos vienen de socios del marketplace, así que la base de datos es el panel de otro, el almacenamiento es otro más, y acabarás reconectando tres servicios un domingo por la noche intentando recordar cuál tiene la credencial que falla.

Elige Cloudflare salvo que tengas un motivo concreto para estar en Next.js.

Y compra el dominio el primer día, del mismo proveedor. Cuesta unos diez euros, lleva cuatro minutos, y cambia cómo tratas el proyecto. Una cosa con dominio es una cosa que existe.

4. Un stack — elegido por ti, y por escrito

La tentación es dejárselo al modelo. No lo hagas, y el motivo no es que su elección fuera a ser mala.

Es que el modelo elige por conversación. La sesión del lunes elige Next.js. La del miércoles, sin memoria del lunes, elige Vite y React Router. La del viernes añade una biblioteca de componentes que duplica la que ya tienes. Nada falla cuando esto pasa — simplemente acabas con un proyecto que son tres proyectos con una gabardina puesta, y cada sesión futura tiene que adivinar en qué convención está.

Así que: React + Tailwind, y dile al modelo que use shadcn/ui.

Por qué esa combinación concreta, cuando hay montones de otras perfectamente buenas:

Es la combinación mejor documentada en los datos de entrenamiento de cualquier modelo. Estás eligiendo la región del mapa donde el modelo es más certero y menos inventivo, y eso vale más que cualquier ventaja técnica el primer día.
Tailwind mantiene el estilo en el marcado, así que cuando dices «haz esta card más compacta», el agente cambia una línea en el fichero que estás mirando en vez de perseguir una hoja de estilos.
Los componentes de shadcn se copian a tu repositorio, no se instalan como dependencia. Ésta es la parte infravalorada. Cuando pides un cambio en un botón, el agente edita tu botón. Con una biblioteca de componentes tradicional, tiene que pelearse con la API de la biblioteca, y normalmente pierde envolviéndola en tres capas de tontería.

Una excepción, y es común. Si lo que construyes es sobre todo contenido — un sitio, una landing, un blog, un conjunto de documentación, con un pequeño panel de administración pegado — usa Astro en su lugar. Envía casi nada de JavaScript por defecto, las páginas van rápidas sin que hagas nada, y escala hasta ser una aplicación de verdad cuando lo necesitas. Este sitio es Astro.

Skills: cómo dejas de repetirte

Una skill es una carpeta con un fichero SKILL.md dentro que tu agente lee sólo cuando es relevante. Esa última parte es todo el sentido: son instrucciones disponibles sin estar estorbando.

La anatomía es pequeña. Un fichero en .claude/skills/<nombre>/SKILL.md, que empieza con:

---
name: my-design-system
description: Úsala al construir o reestilizar cualquier UI de este proyecto —
  colores, tipografía, espaciado, patrones de componentes.
---

Todo lo que el agente debería saber, en markdown normal.

La línea description es la importante, porque es contra lo que el agente compara para decidir si carga la skill siquiera. Descripción vaga, skill que no dispara nunca.

Dos sitios donde ponerlas: .claude/skills/ dentro de tu proyecto, lo que significa que va commiteada a GitHub y sigue ahí mañana y en tu otra máquina, o ~/.claude/skills/, para cosas que quieres en todos los proyectos que toques. Prefiere la del proyecto — una skill que describe este producto pertenece a este producto.

Para instalar una que te hayan dado: suelta la carpeta dentro, arranca una sesión nueva, y pregunta qué skills tienes disponibles. Si no la lista, la descripción es lo primero que hay que revisar.

Ésa es la forma que tiene. Por qué la descripción es la única parte que siempre se carga, qué va en una skill frente a AGENTS.md, y la manera más rápida de escribir la primera — la guía completa.

(Las skills son una funcionalidad de Claude Code. Si te fuiste con Codex, la palanca equivalente es el fichero AGENTS.md descrito en la sección extra — la misma idea, con una carga menos selectiva.)

La de diseño merece la pena el primer día. Si tienes una idea pero ni marca, ni colores, ni opinión visual todavía, ve a startpow.com, elige lo que te guste, exporta, y escoge la descarga de skill. Suéltala en .claude/skills/. Desde ese momento cada pantalla que construya el agente llega con tus colores, tu tipografía y tu espaciado, sin que los describas otra vez — que es la diferencia entre un producto y una demo, y cuesta unos diez minutos.

5. Algo que recuerde, para que mañana no sea reconstruir

Éste es el fallo del que va esta decisión, y merece la pena ser preciso porque la versión popular es falsa.

El modelo no es malicioso. Es complaciente y rápido, en sitios donde equivocarse sale caro. La base de datos no la tira una IA rebelde; la tira porque una migración estaba rota, tirar la tabla era el camino más corto a un test en verde, y no se le preguntó a nadie. El auth no se reescribe en un acto de sabotaje; se reescribe porque un test fallaba y la comprobación de auth era lo que lo hacía fallar.

Dos capas de defensa, y la primera es gratis:

Los hábitos. Una base de datos de desarrollo que no es la de producción. Credenciales de producción que el agente nunca tiene. Un commit antes de empezar nada. Y la instrucción que casi nadie da — qué no debe tocar. Los modelos son complacientes; harán encantados algo útil que tú no querías.

Las herramientas. Esto es lo que es CommitCycle: el trabajo empieza como una task con un alcance declarado, el agente recibe acceso atado a esa única task y a una única rama y caduca por sí solo, los paths que de verdad harían daño llevan un owner que tiene que decir que sí, y cada task cierra con un registro de lo que se declaró frente a lo que se tocó.

Ahora el límite honesto, que es también la frase más importante de aquí: no elimina la posibilidad. La responsabilidad final siempre es de la persona que aprueba lo que el agente pide. El agente ejecuta; tú consientes. Lo que las herramientas eliminan es la clase de accidente en la que nadie pudo decir que no, porque no se preguntó a nadie — y esa clase son la mayoría.

Si lo quieres: /plugin marketplace add pow-paulinho/commitcycle-plugin y después /plugin install commitcycle@commitcycle, en Claude Code, o npm i -g commitcycle para la CLI. El board alojado es sólo por invitación mientras esto es pequeño.

6. ¿Y ahora qué? Empieza por la forma, no por la pantalla

Ya tienes las seis piezas. El instinto es pedir constrúyeme la home, y es el primer movimiento equivocado — no porque la home no importe, sino porque es consecuencia de decisiones que aún no has tomado.

La primera pregunta útil es: ¿esto necesita cuentas? Casi todo se ordena en cuatro superficies a partir de ahí.

Superficie	Qué es	¿La necesitas?
Parte pública	Todo lo visible sin iniciar sesión	Casi siempre
Auth	Registro, login, recuperar contraseña, verificar correo	Sólo si existe un «tu» algo
El producto	Lo que ve la gente después de iniciar sesión	Si hay auth, entonces sí
Admin	Donde tú ves usuarios, pagos, problemas	Sí, y todo el mundo lo olvida hasta la segunda semana

Si la respuesta honesta es «sobre todo parte pública, admin pequeño», constrúyelo en Astro y no añadas un sistema de autenticación que vas a mantener para un solo usuario. Si es «sobre todo producto», el auth y el modelo de datos son lo primero, porque todo lo demás cuelga de ellos.

Los prompts

Primero, el que no escribe código. Éste es el prompt de más valor de todo el proceso y es el que más gente se salta:

Quiero construir: [descríbelo en tres o cuatro frases, incluyendo para
quién es y por qué pagan, si es que pagan algo].

No escribas código todavía. Entrevístame — hazme las preguntas que
necesites que responda para planificar esto bien, por tandas.

Cuando tengas suficiente, devuélveme:
1. Las pantallas, agrupadas en público / auth / producto / admin
2. El modelo de datos, como lista de entidades y cómo se relacionan
3. Cualquier servicio de terceros que esto necesite y por qué
4. Qué construirías primero, y qué dejarías deliberadamente para
   más adelante

Estás haciendo que el modelo produzca una pregunta, y revisar una pregunta es mucho más barato que revisar trescientas líneas de una respuesta construida sobre un supuesto que nunca viste.

Segundo, los cimientos. Despliega la cosa vacía el primer día — «ponerlo en producción» no debería convertirse nunca en un proyecto aparte más adelante:

Monta el esqueleto del proyecto:
- [Astro | React + Vite], TypeScript, Tailwind, shadcn/ui
- Destino de despliegue: Cloudflare
- Un repositorio Git con un primer commit, subido a GitHub

Deja una página vacía desplegada y dame la URL en vivo antes de añadir
ninguna funcionalidad.

Después escribe AGENTS.md en la raíz recogiendo: el stack y las
versiones, la estructura de carpetas, las convenciones de nombres, los
comandos para ejecutar y compilar, y cualquier cosa que nunca debas
hacer en este proyecto.

No añadas todavía autenticación, base de datos ni ninguna dependencia
más allá de lo anterior.

Tercero, las superficies que necesitan un sistema detrás:

Construye registro y login: alta, inicio de sesión, cierre de sesión,
recuperación de contraseña, verificación de correo.

Usa [el proveedor de auth que elegiste] en vez de hacerlo a mano.
Las pantallas usan nuestros componentes existentes — no introduzcas una
segunda biblioteca de componentes.

Dame también la página de admin más pequeña que liste usuarios, porque
necesito poder ver si esto funciona.

NO toques: pagos, las páginas de marketing, nada bajo [path].
Si te encuentras con una decisión que yo no he tomado — precios,
duración de sesión, qué pasa con las cuentas sin verificar después de
una semana — párate y pregunta en vez de elegir.

Fíjate en las dos líneas que casi nadie escribe: qué no debe tocar, y párate y pregunta en vez de elegir. Esas dos líneas evitan más retrabajo que cualquier cantidad de finura en prompt engineering.

Cuarto, una vez funcione, hazlo tuyo: instala la skill de diseño y pide que se reestilice una pantalla con ella. Revisa ésa. Luego déjala correr con el resto.

7. Historias de usuario, que es donde esto se pone real

Si puedes narrar lo que hace una persona, puedes construirlo. Coge la frase del propio usuario:

Alguien ve un anuncio, aterriza en el sitio, se crea una cuenta, se suscribe a un plan, paga con tarjeta, y su suscripción se activa.

Léela otra vez despacio, porque esa única frase es una especificación. Contiene:

Una landing a la que apunta el anuncio, que no es la home
Registro, y por tanto verificación, y por tanto correo que llega de verdad
Probablemente onboarding, porque una cuenta nueva y vacía es donde la gente se va
Un proveedor de pagos — Stripe, en la práctica — y un checkout
Un webhook, porque el pago tiene éxito en los servidores de Stripe y tu aplicación tiene que enterarse
Entitlement: algún estado que diga que esta cuenta ya es suscriptora
Feature gating guiado por ese estado, en todos los sitios donde importe
La ruta de fallo: tarjeta rechazada, pago correcto pero webhook que no llegó, suscripción cancelada a mitad de mes
Una vista de admin, para que cuando alguien te escriba diciendo que pagó y no se activó nada, puedas mirar

Una frase, nueve elementos de trabajo, y los tres últimos son los que se descubren en producción, por un cliente, si nadie los escribió.

Esto también es trabajo que el modelo hace bien — dale la historia y pregúntale qué implica, y producirá una lista muy parecida a la de arriba. Lo que no puede hacer es recordar la lista el martes que viene. Para eso está un board: cada elemento se convierte en una task con un alcance, una task se convierte en una rama, y la rama cierra con un registro de lo que cambió de verdad.

Esto suena aburrido. Lo es, un poco. Y por no vender de más: tres prompts de verdad pueden darte algo que corre y se ve bien, y el subidón de verlo funcionar es real y merece la pena tenerlo. Ve y tenlo.

Pero la cosa que sigue en pie en el mes tres, la que puedes entregarle a otra persona, la que puedes cambiar sin contener la respiración — ésa la construyó alguien que escribió qué se suponía que tenía que hacer. La consistencia es poco glamurosa y es toda la diferencia.

Pista extra

Cosas pequeñas, en orden aproximado de cuánto arrepentimiento evitan:

AGENTS.md en la raíz del repositorio. El fichero de mayor retorno que escribirás. Stack, convenciones, comandos, y la lista de cosas que nunca hay que hacer. Toda herramienta agéntica lo lee. El nuestro guarda ahí el mapa de zones y escribe la task activa en un CLAUDE.local.md ignorado por git, que se limpia al entregar, pero uno escrito a mano ya es la mayor parte del valor.
Dos bases de datos desde el primer minuto. Desarrollo y producción, nunca las mismas credenciales, y el agente sólo tiene la de desarrollo. Ésta es la defensa concreta contra el desastre concreto.
Los secretos nunca en el repositorio. .env en .gitignore, los valores reales en el almacén de secretos de tu host. Rota cualquier cosa que llegara a commitearse — borrar el fichero no lo quita del historial.
Despliegues de preview por rama. Tanto Cloudflare como Vercel te dan una URL por rama gratis. Ver el cambio en una URL real antes de que esté en producción vale más que cualquier cantidad de pruebas locales.
Deja que el agente vea lo que construyó. Capturas, o una herramienta de navegador que pueda manejar. Un agente construyendo UI sin mirarla nunca trabaja a ciegas, y se nota.
Seguimiento de errores, más exactamente un número de analítica que mires de verdad. Más de uno y no mirarás ninguno.
Términos y política de privacidad antes de cobrar una tarjeta. Stripe pedirá un sitio funcionando con ambos antes de activar la cuenta, y enterarse de eso el día del lanzamiento es un mal día.
Conoce tu restauración, no sólo tu copia de seguridad. Una copia sin probar es una creencia, no una copia.
Un fichero de decisiones. Tres líneas por decisión: qué, por qué, qué descartaste. Seis semanas después es lo único que separa que vuelvas a litigarlo todo con un modelo que no estaba allí.
Espera que el modelo cueste más que el hosting. Esa proporción es correcta y no es señal de que lo estés haciendo mal.

Todo el setup de arriba es una tarde. Lo que compra es que la segunda semana sea una continuación en vez de un proyecto de arqueología — y si quieres los hábitos que van encima, ése es el post de la primera semana.

Vibe coding, y la primera semana que no acaba en un desastre

Fri, 14 Aug 2026 00:00:00 GMT

El vibe coding consiste en construir describiendo lo que quieres y aceptando lo que el modelo escribe sin leerlo todo. El término es de Andrej Karpathy, y lo que lo distingue no es que la IA escribiera el código — eso ya es lo normal — sino que nadie lo revisó línea a línea.

Eso es un intercambio, no un error. Que sea un buen intercambio depende por completo de una pregunta: ¿cuánto tiempo tiene que vivir este código?

¿Dónde funciona de verdad el vibe coding?

Prototipos que piensas borrar. El coste de equivocarte es que lo tiras, que es lo que ibas a hacer de todos modos.

Scripts y herramientas de un solo uso. Algo que reordena un CSV, siembra una base de datos, hace scraping de una página una vez. Si produce la salida correcta has terminado; nadie va a mantenerlo.

Aprender la forma de algo que no conoces. Conseguir un ejemplo funcionando de una biblioteca que no has usado nunca es más rápido así que leerte antes la documentación, y puedes leer la documentación después con algo concreto delante.

Cualquier cosa donde el feedback sea inmediato y total. Si funciona, funciona, y te enteras en diez segundos.

El hilo común es que equivocarse es barato y evidente. Ésa es la condición. No el tamaño del proyecto, ni el lenguaje, ni si es «real» — sólo si un error aparece de inmediato y cuesta poco.

¿Cuándo deja de funcionar?

En el momento en que el código sobrevive a la sesión que lo produjo.

Esto no es un juicio moral. Es aritmética: compraste velocidad saltándote la comprensión, y la factura llega cuando alguien tiene que cambiar código que nadie entendió cuando se escribió. Si nadie lo cambia nunca, la factura no llega nunca y la velocidad te salió gratis. Ése es un resultado real y ocurre mucho.

Lo que hace que salga mal es no saber en cuál de los dos casos estás. Casi todas las malas experiencias empiezan como un prototipo que se volvió crítico en silencio, sin que nadie decidiera nada.

¿Cómo sé en qué caso estoy?

Tres preguntas, y van sobre la situación más que sobre el código:

Pregunta	El vibe coding vale cuando	Deja de valer cuando
¿Con qué rapidez me entero de que me equivoqué?	En segundos. Lo ejecutas y lo ves	En semanas, a través de un cliente
¿Qué cuesta equivocarse?	Lo borras y empiezas otra vez	Dinero, datos o la confianza de alguien
¿Quién más depende de esto?	Nadie	Cualquiera que no seas tú

Las tres apuntando en la misma dirección es el caso para el que se hizo esto. Las tres apuntando en la otra y no estás haciendo vibe coding, estás apostando con pasos extra.

Lo útil es que esto se decide por pieza de trabajo, no por proyecto. La misma tarde puede contener un script desechable que no lees nunca y un cambio de permisos que lees dos veces. Tratar un repositorio entero como un único ajuste es lo que produce los dos errores habituales: leerlo todo en un prototipo, y no leer nada en la parte que muerde.

¿Qué no debería hacer nunca con vibe coding?

Una lista corta, y el motivo es el mismo en todos los puntos:

Autenticación y permisos. Equivocarse aquí no lanza un error. Deja entrar en silencio a quien no debe, y te enteras por otra persona.
Dinero. Precios, cargos, devoluciones, divisas. Un off-by-one en un bucle es un bug; un off-by-one en céntimos es un chargeback y un correo que no quieres escribir.
Cualquier cosa que borre. Los borrados en cascada sobre todo. La prueba para esta categoría es si existe un deshacer.
Migraciones de base de datos. Se ejecutan una vez, contra datos reales, y el fallo se descubre cuando los datos ya no están.
Todo lo que maneje datos personales de otros. Equivocarse aquí lleva un regulador incorporado.

Fíjate en lo que no es el criterio: la dificultad. Algunas de éstas son código fácil. La propiedad que comparten es que equivocarse no se anuncia solo — que es exactamente el supuesto sobre el que corre el vibe coding.

Esto no es «escríbelo tú». Es «lee éste». Deja que el modelo lo escriba, después lee de verdad lo que escribió, y pídele que te explique las partes que no puedas seguir. La lectura es todo el coste, y en estas cinco merece la pena pagarlo.

La primera semana

Mantén las sesiones cortas, y termina cada una en algo que funcione. Éste es el hábito de mayor rendimiento y no va sobre la IA en absoluto. Una sesión larga acumula decisiones que nadie escribió, y cuando por fin algo va mal no hay ningún punto al que volver. Sesiones cortas con un commit que funciona al final te dan un sitio al que regresar.

Lee las partes caras. No todo — eso echaría a perder el propósito. Lee todo lo que toque dinero, autenticación, borrado de datos, o código en el que también trabaja otra persona. El resto, ojéalo. La habilidad que se construye aquí es el triage, y es una habilidad real: saber dónde equivocarse sale caro es la mayor parte de lo que sabe un ingeniero senior.

Di lo que no debe hacer. Casi todo el mundo describe lo que quiere y se para ahí. La instrucción que más tiempo ahorra es la que descarta cosas — no toques el módulo de auth, no añadas dependencias, no cambies el schema de la base de datos. Los modelos son complacientes y harán encantados algo útil que tú no querías.

Ejecútalo antes de creértelo. Código generado que parece correcto y no arranca es el fallo suelto más común, y el más barato de detectar.

Date cuenta de cuándo el prototipo dejó de ser un prototipo. Suele haber un momento concreto: alguien más lo abre, o se pone delante de un usuario, o lo despliegas. Ése es el momento en que el intercambio cambia, y la respuesta honesta es volver atrás y leerlo bien.

Cómo es una buena sesión, de principio a fin

En concreto, porque «mantén las sesiones cortas» es un consejo con el que puedes estar de acuerdo y aun así no aplicar:

Empieza desde un commit. No desde un repositorio ordenado: desde uno con commit. Éste es el punto de guardado, y cuesta diez segundos.
Di el objetivo y el límite en el mismo mensaje. Lo que quieres, y lo que está prohibido. La segunda mitad es la que la gente se salta.
Déjalo trabajar sin interrumpir. Corregir el rumbo a mitad de vuelo produce un cambio que es medio de un plan y medio de otro, y eso es más difícil de leer que cualquiera de los dos.
Lee el diff, no el código base. Cuántos ficheros, cuáles, y si se ha borrado algo que no pediste borrar.
Ejecútalo. Antes de creerte nada.
Haz commit, o tira la sesión entera. Los dos son resultados aceptables. El que no lo es: arrastrar un estado a medias hasta la siguiente sesión.

Alrededor de una hora es donde esto suele caer para la mayoría, y el número importa menos que la forma: la sesión es la unidad que puedes tirar. En cuanto una sesión lleva tanto tiempo que descartarla resulta impensable, has perdido la propiedad que hacía segura toda la aproximación — y eso pasa de forma gradual, que es justo por lo que vale la pena vigilarlo.

Las preguntas que la gente hace de verdad

«¿Sigo siendo un desarrollador de verdad si hago esto?»

La pregunta de debajo es si estás construyendo una habilidad o esquivándola. Estás construyendo una — triage, especificación, saber dónde vive el riesgo — y no es la misma habilidad que escribir tú la sintaxis. Las dos son reales. Ninguna se basta sola.

«¿Cómo evito que invente bibliotecas que no existen?»

Ejecuta el código. Los imports alucinados fallan de inmediato, lo que convierte a éste en el tipo de error menos peligroso. Preocúpate más por los que sí arrancan.

«Ha reescrito algo que no le pedí que tocara.»

Muy común, y el arreglo normal es decir qué está prohibido antes de empezar. En un repositorio en el que trabaja más gente, esto deja de ser una molestia y pasa a ser el problema de verdad — que tiene su propio post.

«¿Debería hacer commit de código que no he leído?»

En algo desechable, sí. En algo compartido, le estás entregando a tus compañeros un diff sobre el que no puedes responder preguntas, y eso es un problema social antes que técnico.

«¿Así es como trabajan ahora los equipos profesionales?»

En parte, y honestamente la respuesta todavía se está moviendo. Lo que sí está claro es que la restricción se ha desplazado de con qué rapidez se puede escribir esto a con cuánta confianza se puede cambiar después, y los equipos que van bien son los que tratan eso como el eje del diseño.

Hacia dónde va esto, y qué hacemos nosotros

Todo lo anterior funciona para una persona sola en su máquina. Los fallos interesantes empiezan cuando el repositorio es compartido — cuando el código generado es localmente razonable y globalmente equivocado porque el modelo no podía ver una convención que vive en la cabeza de alguien.

Ése es el problema en el que trabaja CommitCycle: cada agente recibe un grant atado a una task y a una rama que caduca por sí solo, los paths que harían daño llevan un owner, y cada task cierra con un registro de lo que declaró frente a lo que tocó.

Siendo claros sobre dónde está eso: el plugin instala hoy el enforcement, y el paquete commitcycle de npm instala la CLI — el proceso sin el muro. El board alojado es sólo por invitación mientras esto es pequeño. Y nada de eso es lo que necesitas en tu primera semana de vibe coding — en tu primera semana necesitas sesiones cortas y el hábito de leer las partes caras.

La semana siguiente, cuando ya hayas decidido que la cosa va a existir más allá del viernes, la pregunta pasa de hábitos a setup: qué tener montado antes del primer prompt, y por qué está ahí cada pieza.

Qué se rompe cuando el vibe coding llega a un repositorio compartido

Fri, 14 Aug 2026 00:00:00 GMT

Todo lo del vibe coding cambia cuando el repositorio tiene a más gente dentro. No porque el código empeore, sino porque la manera en que falla deja de ser visible.

En tu propia máquina, un error aparece como algo que no funciona. En un repositorio compartido, el fallo característico es código que funciona, se lee razonable, pasa la revisión y aun así está mal — porque rompió una regla que nunca se escribió en ningún sitio que el modelo pudiera leer.

Cómo es la forma

A un agente se le pide añadir un campo a un formulario. Lo hace, con competencia. También añade una migración de base de datos, porque eso es lo que normalmente hace falta para añadir un campo.

La migración está bien. El problema es que este equipo aplica las migraciones a mano, en un orden concreto, después de una revisión de la persona que es owner del schema — una convención que existe por un incidente de hace dieciocho meses, la conocen cuatro personas, y no está escrita en ninguna parte.

Nada en ese diff parece mal. Ése es el fallo. No es código malo; es código localmente razonable y globalmente equivocado, y la distancia entre esas dos cosas es exactamente la distancia entre lo que hay en el repositorio y lo que hay en la cabeza de alguien.

¿Por qué no lo detecta la revisión?

La revisión lee el diff y pregunta si es bueno. Esta clase de problema es invisible para esa pregunta, porque el diff sí es bueno. El defecto vive en la relación entre el cambio y una pieza de contexto que no está en pantalla.

Quien revisa lo detecta sólo si da la casualidad de que lleva la convención encima y de que se acuerda de ella mientras lee. Eso funciona, a veces, cuando quien revisa es una de esas cuatro personas. Deja de funcionar en cuanto sube el volumen — y que suba el volumen es justo el sentido de usar agentes.

Así que el consejo habitual, revisa el código generado por IA con más cuidado, es medio cierto y no escala. Revisar línea a línea y con cuidado todo elimina la razón de generarlo para empezar.

¿Cuál es el fallo que más cuesta?

Dos agentes, a la vez, en el mismo repositorio.

Cada uno es correcto por separado. Cada uno pasa sus propios tests. Uno refactoriza un helper del que el otro depende; o los dos tocan la misma configuración desde direcciones opuestas; o uno mueve un fichero en el que el otro está escribiendo. Nada falla. Las dos ramas están en verde.

La pérdida aparece días después como un cambio que se hizo y luego ya no estaba, y nadie sabe decir cuándo dejó de existir. Es caro precisamente porque no hay un momento de fallo al que señalar — estás reconstruyendo un negativo a partir del historial de git.

Esto no es hipotético y no es raro. Es la consecuencia ordinaria de correr más de un agente en un repositorio, que hoy es un martes cualquiera.

¿Cómo sé si esto ya está pasando?

No llega como un incidente, y ésa es la dificultad. Llega como un conjunto de hechos pequeños que cada uno tiene una explicación individual plausible:

Trabajo que se hizo y luego no estaba. Alguien recuerda haberlo escrito. Git dice que existió. Nadie puede nombrar el commit que lo quitó.
El mismo bug arreglado dos veces, con tres semanas de diferencia, por dos personas que cada una creía ser la primera.
Una convención reexplicada en tres sesiones distintas, porque cada sesión empezó sin memoria de la anterior y nadie la escribió entre medias.
Un pull request que toca ficheros que nadie esperaba, donde los ficheros de más son todos individualmente defendibles.
«¿Quién cambió esto?» respondido por un mensaje de commit que dice refactor y un autor que no estaba leyendo con atención.

Cualquiera de éstas por separado es una mala semana normal. Todas juntas son el fallo, y la razón por la que se queda sin nombre tanto tiempo es que no hay ningún error que buscar. Estás buscando la ausencia de algo, y las ausencias no avisan a nadie.

¿Y si las otras personas son mis propios agentes?

La inversión que pilla a más gente: no necesitas un equipo para tener un problema de repositorio compartido. Con dos terminales basta.

Un repositorio no sabe que dos sesiones pertenecen al mismo humano. Todas las propiedades que hacen esto difícil en un equipo están presentes cuando estás solo — escrituras concurrentes a los mismos ficheros, ninguna memoria compartida entre las sesiones, convenciones que existen sólo en tu cabeza — y una propiedad es estrictamente peor. En un equipo, el trabajo del segundo agente al menos lo lee una persona distinta. Cuando los dos son tuyos, apruebas los dos, rápido, la misma tarde, y no hay un segundo lector en ninguna parte del circuito.

Por eso «soy desarrollador en solitario, esto no va conmigo» suele ser falso ya en el momento en que alguien lo dice. El umbral no es el número de personas. Es el número de cosas escribiendo en el repositorio a la vez.

¿AGENTS.md y CLAUDE.md arreglan esto?

La respuesta estándar es un CLAUDE.md o un AGENTS.md con tus convenciones dentro. Escríbelo. Ayuda de verdad, y es lo más barato de esta lista.

También se degrada, por la misma razón por la que se degrada toda la documentación: es una foto de lo que alguien recordaba el día que lo escribió, y nada obliga a revisarlo cuando cambia aquello que describe. Seis meses después es una mezcla de cierto, caducado y aspiracional, y un agente que lo lee no puede distinguir qué línea es cuál. Una persona recién incorporada tampoco.

Un fichero de contexto es necesario y no es suficiente, y el hueco entre esas dos cosas es donde está el trabajo interesante.

¿Qué ayuda de verdad?

Nombra los paths donde equivocarse sale caro. No todo — la mayor parte de un repositorio es genuinamente segura de cambiar, y tratarlo todo como peligroso significa que nada lo es. Una lista corta de los paths que harían daño vale más que una exhaustiva, porque una lista corta se lee.

Dale a cada uno un owner. No por burocracia: para que «¿esto debería cambiar?» tenga a quién preguntar. Una regla sin owner es una regla que se esquiva al primer inconveniente, tanto por humanos como por agentes.

Acota el trabajo antes de que empiece, no después. Qué debe hacer esto, qué no debe hacer, qué áreas toca. Escrito antes de que el código exista, eso es una especificación. Escrito después, es una excusa.

Haz posible ver qué tocó de verdad una pieza de trabajo, frente a lo que dijo que tocaría. Esa diferencia es donde están las sorpresas, y es una pregunta que git puede responder si alguien se la hace.

Nada de eso necesita un producto. Necesita que la lista exista en algún sitio que puedan leer tanto las personas como los agentes.

¿Qué puedo hacer el lunes, sin comprar nada?

En orden, porque hacer las dos primeras es la mayor parte del valor:

Escribe los cinco paths donde equivocarse sale caro. Cinco, no cincuenta — el sentido es que la lista se lea. Migraciones, auth, el código de pagos, la configuración compartida, los que sean los tuyos.
Pon un nombre junto a cada uno. Para que «¿esto debería cambiar?» tenga a dónde ir. No hace falta que sea un owner formal; hace falta que sea una persona.
Empieza cada pieza de trabajo diciendo qué no debe tocar. Una línea, antes de que el código exista. Ésta es la frase de mayor rendimiento del desarrollo agéntico y no cuesta nada.
Una vez a la semana, mira qué cambió de verdad frente a lo que creías que se estaba trabajando. No una revisión del código: una comparación de dos listas. El hueco es donde viven las sorpresas, y una vez a la semana basta para pillarlas mientras siguen siendo baratas.

Nada de eso es un producto y nada de eso necesita permiso. Si resulta que te importa, la siguiente pregunta es qué lo impone cuando todo el mundo está ocupado — que es donde el resto de esto se pone interesante.

Dónde encaja CommitCycle

Esa lista es la cosa sobre la que construimos. Las zones son los paths que harían daño, cada una con un owner y un risk level. Una task declara lo que toca antes de empezar, y mover un muro requiere una aprobación con un motivo. Cada agente recibe un grant atado a una task y a una rama que caduca por sí solo, así que dos sesiones en sus propios worktrees no pueden autorizarse mutuamente en silencio — si comparten un mismo directorio, todavía pueden, y por eso el worktree es la instrucción y no una preferencia. Cada task cierra con un registro de lo que declaró frente a lo que tocó.

Dónde está de verdad, dicho llanamente: el enforcement se instala hoy como plugin de Claude Code; el paquete commitcycle de npm pone cycle en tu PATH y no lleva hook, así que te da el proceso sin el muro. El board alojado es sólo por invitación mientras esto es pequeño. El modelo de zones es agnóstico del agente, pero el punto de enforcement necesita un pequeño adaptador por harness, y hoy sólo el de Claude Code se ha visto denegar en una instalación real.

Y el límite honesto que merece la pena repetir: denegar una llamada a una herramienta en vuelo no es lo que hace esto distinto. Varios fabricantes lo publican y Claude Code lo incluye gratis. La parte que es nuestra es el grant atado a una única task, atribuido a un owner, y que caduca por sí solo — y el registro posterior que dice qué pasó de verdad.

Si eres una persona sola con un prototipo, nada de esto es tu problema todavía, y el post de los primeros pasos es el más útil — o el del setup, si el prototipo ha empezado a parecer que sobrevivirá al mes.

Qué sacar de Obsidian, y qué dejar dentro

Fri, 14 Aug 2026 00:00:00 GMT

El post anterior sostenía que un vault de Obsidian no puede ser la base de conocimiento de tus agentes de IA: es privado de una máquina, sus afirmaciones no llevan procedencia y nada marca una nota como caducada.

Con ese argumento se está de acuerdo y luego no se actúa, porque «mueve tu conocimiento» no es algo que nadie pueda empezar un martes. Este post es la mitad práctica. Qué se mueve de verdad, qué se queda, y qué aspecto tiene el reemplazo una vez está en marcha.

La línea, aplicada nota a nota

Si equivocarte en esta nota induciría a error a otra persona, se le ha quedado pequeño un vault personal.

Nota a nota, no vault a vault. Esa distinción lo es todo, y es la razón de que sea un trabajo más pequeño de lo que suena. La mayor parte de un vault es pensamiento — conexiones a medio hacer, restos de reuniones, cosas que escribiste para averiguar qué pensabas. Nada de eso se mueve. Lo que se mueve es la minoría sobre la que otras personas, o un agente, actuarían.

En la práctica ha sido menos de una quinta parte de las notas en todos los casos que he visto hacerlo. El resto se queda exactamente donde está.

¿Qué se mueve?

Las convenciones. «Las migraciones las hacemos en dos pasos.» «Los handlers devuelven el error, no lo registran.» Cualquier cosa formulada como hacemos X es una afirmación sobre el equipo, y una afirmación sobre el equipo pertenece a donde el equipo pueda verla y corregirla.

Las decisiones, con sus motivos. No sólo lo que se eligió, sino lo que se descartó y por qué. Es la categoría de mayor valor y la que más se pierde, porque el razonamiento vive en la cabeza de alguien y el vault registra sólo la conclusión. Un agente al que le entregas la conclusión sin el motivo la deshará alegremente la primera vez que la conclusión resulte incómoda.

Cualquier cosa sobre la que un agente actuaría. Si una nota cambiaría lo que se escribe cuando un agente la lee, es operativa, no personal. Es la categoría más nueva y aquella para la que los vaults nunca se diseñaron.

Los límites. «Deliberadamente no hacemos X, y aquí está por qué.» Nadie los escribe y todo el mundo los redescubre por la vía cara.

¿Qué se queda?

Todo lo demás, y no es un premio de consolación.

Las ideas a medio formar. Las notas a las que se les permite estar equivocadas. La conexión que aún no has hecho. Las notas de lectura, los restos de reuniones, lo que escribiste a las 2 de la mañana y a las 2 de la mañana tenía sentido. Obsidian es mejor en todo eso que cualquier cosa por la que lo cambiarías, y es mejor porque no tiene revisión, ni aprobación, ni público — exactamente las propiedades que lo descalifican para la otra categoría.

Un vault que sólo contiene esto es un vault haciendo su trabajo.

¿Y las notas que son mitad pensamiento, mitad convención?

El caso incómodo habitual, y el que atasca a la gente, porque la línea parece limpia hasta que te encuentras con una nota real de dos mil palabras dándole vueltas a algo con una decisión de verdad enterrada al final.

Divídela, y es más fácil de lo que parece. El pensamiento se queda en el vault. La afirmación se mueve, sola, como una frase. Enlaza de vuelta si quieres.

Lo que no debes hacer es mover el conjunto. Una nota que es ochenta por ciento tanteo y veinte por ciento decisión, dentro del repositorio, le enseña a un agente que las convenciones de tu equipo son tentativas — y un agente que cree que una regla es tentativa negociará con ella la primera vez que la regla resulte incómoda. Dejar el conjunto en el vault tiene el fallo opuesto: el veinte por ciento que otras personas necesitan queda invisible, indistinguible de la divagación que lo rodea.

La prueba de si una nota está lista: ¿puedes extraer una frase que empiece por «hacemos» o «no hacemos»? Si no, todavía no hay nada que mover, y la nota sigue haciendo su trabajo donde está.

¿Dónde deben vivir las notas que se mueven?

En el repositorio que describen. No en un wiki, no en una segunda herramienta: el repo, revisado en el mismo pull request que el código del que hablan.

Esa ubicación es la que hace el trabajo. Una nota en el repo se lee en el momento en que alguien cambia lo que describe, porque está en el diff. Una nota en un wiki se lee cuando alguien va a buscarla, que es el modo de fallo que estás dejando atrás.

También significa que la nota se revisa como código. Alguien la aprueba. Alguien responde por ella. Dos ingenieros no pueden sostener dos versiones contradictorias sin que una de ellas aparezca en un diff.

¿Qué aspecto tiene una nota ya movida?

El formato importa menos que cuatro propiedades, y cada una responde a una forma en que fallaba la versión del vault:

Una afirmación por nota. «Las migraciones las hacemos en dos pasos» es una nota. «Notas sobre nuestro backend» es una carpeta disfrazada de nota, y nada de lo que hay dentro se puede confirmar, contradecir ni archivar por separado.
Dice de dónde viene. La decisión, el incidente, el pull request. Una afirmación que no puedes rastrear es una afirmación que no puedes ponderar, y mover una afirmación irrastreable al repositorio reubica el problema en lugar de arreglarlo.
Dice qué se descartó. La conclusión sin el razonamiento se deshace la primera vez que la conclusión resulta incómoda — normalmente por un agente, alegremente, en un diff que parece una simplificación.
En presente, y lo bastante concreta como para poder estar equivocada. «Cuidado con las migraciones» no es una nota, es un estado de ánimo. Nadie puede actuar sobre ella y nadie podrá demostrar nunca que ha caducado.

Y corta. La razón por la que las páginas de wiki no se leen es que tienen dos mil palabras cuando la afirmación es una línea, y una nota que nadie lee es una nota que no existe — que es el mismo desenlace que dejarla en el vault, después de más trabajo.

¿Qué no arregla esto?

Mover las notas al repo arregla el descubrimiento y la revisión. No arregla la degradación, y cualquier post que te dijera lo contrario te estaría vendiendo algo.

Una nota en un repositorio caduca exactamente igual de rápido que una nota en un vault. Lo que cambia la degradación no es la ubicación, es un disparador — algo que obligue a escribir el conocimiento mientras la persona todavía recuerda por qué, y algo que permita retirar una nota equivocada por un mecanismo y no por la memoria de alguien.

Esas son las dos propiedades que hay que buscar en lo que sea que uses, y son las dos sobre las que construye CommitCycle: el conocimiento se alimenta al cerrar una unidad de trabajo, una línea cada vez, cuando el motivo aún está fresco; y archived es un estado real, que es lo que permite que el corpus encoja en lugar de sólo volverse más seguro de sí mismo.

¿Cómo empiezo sin una migración?

No migres. Las migraciones de conocimiento fallan por la misma razón que fallan las migraciones de cualquier cosa: el esfuerzo va por delante y el beneficio queda difuso.

En su lugar: la próxima vez que escribas una nota de la que otras personas dependerían, escríbela en el repo en lugar de en el vault. Y luego la siguiente. El vault deja de crecer en la categoría que duele, y el corpus que importa empieza a acumularse en el sitio donde se revisa. No se mueve nada y no se pierde nada.

Para las notas cuyos lectores son agentes y no personas, el destino tiene una forma: una skill es una carpeta en el repositorio que se carga cuando resulta relevante y se ignora cuando no, que es lo más parecido a una nota de vault que un agente puede usar de verdad.

Al cabo de unas semanas, lo que siga en el vault y siga siendo estructural es una lista corta, y para entonces sabrás exactamente qué notas están en ella.

¿Cómo sé que está funcionando?

Cuatro señales, más o menos en el orden en que aparecen:

Dejas de reexplicar lo mismo en cada sesión nueva. Esta llega primero y es la más satisfactoria de inmediato.
Alguien corrige una nota durante una revisión de código. Eso es la ubicación dando fruto: significa que la nota se leyó en el momento en que se estaba cambiando lo que describe, que es la razón entera por la que fue al repositorio.
Un agente te cita una de vuelta — propone algo y nombra la nota de la que salió, en lugar de proponer algo plausible.
Alguien archiva una. Esta es la señal de verdad, y es la que más tarda. Un corpus que sólo ha crecido se está acumulando, no manteniendo, y acabará exactamente donde estaba el vault: más seguro de sí mismo cada mes y menos exacto.

La contraseñal es el espejo de esa última. Si las notas del repositorio crecen y nunca se ha retirado ninguna, has reconstruido el vault con ceremonia extra, y la caducidad viene de camino.

Dónde está CommitCycle de verdad

Merece decirse claramente, porque el sentido de este post es una línea que puedes aplicar con nosotros o sin nosotros: el enforcement se instala hoy como plugin, y el paquete commitcycle de npm instala la CLI a su lado. El board alojado es sólo por invitación mientras esto sea pequeño.

Así que coge la línea y úsala. No cuesta nada, se aplica a las herramientas que tengas, y el argumento que hay debajo está en el post anterior si quieres comprobar el razonamiento antes de fiarte de la conclusión.

Tu vault de Obsidian no puede ser la base de conocimiento de tus agentes de IA

Mon, 10 Aug 2026 00:00:00 GMT

Un vault de Obsidian falla como base de conocimiento para agentes de IA por tres razones estructurales: es privado de una máquina, sus afirmaciones no llevan citas, y nada te dice cuándo una nota dejó de ser verdad. Los agentes leen lo que se les entrega y no tienen forma de distinguir una nota vigente de otra que caducó hace tres sprints — así que la respuesta segura y equivocada y la correcta llegan con el mismo aspecto.

Esto no es una crítica a Obsidian. Es muy bueno en el trabajo para el que se construyó, que es una persona pensando. El fallo es un error de categoría: una herramienta personal de pensamiento a la que se le pide ser una fuente de verdad compartida.

¿Pueden los agentes leer siquiera un vault de Obsidian?

Sí, y conviene aclararlo primero porque es donde suele empezar la conversación. Un vault es una carpeta de markdown plano. Cualquier agente con acceso a ficheros lo lee sin ceremonia, y hay servidores MCP que te lo conectan en una tarde.

El acceso nunca fue el problema. Leer y confiar son operaciones distintas, y un vault no lleva ninguna señal que las separe. Una nota escrita la semana pasada y una nota que dejó de ser cierta en 2024 son el mismo tipo de objeto, en la misma carpeta, con la misma autoridad. Quien lee su propio vault descuenta automáticamente — ah, esa es vieja — usando conocimiento que no está en ninguna parte del fichero. Un agente no tiene con qué descontar.

Así que la mitad fácil queda resuelta, la difícil pasa desapercibida, y el montaje parece funcionar justo hasta que actúa con total seguridad sobre algo que ya había caducado.

Los tres fallos, por orden de lo que cuestan

1. Es privado, así que el conocimiento es por persona

Un vault vive en un portátil. Sincronízalo y tendrás una carpeta compartida, no conocimiento compartido — porque el vault no tiene noción de revisión. Nadie aprueba una nota. Nadie responde por ella. Dos ingenieros mantienen dos vaults, cada uno acertado en cosas distintas, y el agente se queda con el vault de quien lo esté operando.

El síntoma es fácil de reconocer: la misma pregunta obtiene dos respuestas según quién se la haga a su agente.

2. Las afirmaciones no llevan procedencia

Una nota dice «las migraciones las hacemos en dos pasos». ¿Es una decisión que tomó alguien, la observación de un incidente, o algo que un compañero creía en 2024? La nota no lo dice, y a los pocos meses nadie se acuerda.

Para una persona esto es fricción. Para un agente es fatal, porque no puede ponderar una afirmación que no puede rastrear. Seguirá una nota caducada exactamente con la misma confianza con la que sigue una correcta.

3. Nada marca una nota como caducada

Este es el que hace más daño en silencio. Un vault no tiene estado de muerte. Las notas se acumulan, y el único mecanismo para retirar una equivocada es que alguien recuerde que lo está — lo que falla de forma fiable, porque quien sabe que la nota está caducada no es quien la está leyendo.

El resultado es un corpus que crece monótonamente más seguro de sí mismo y menos exacto.

¿Qué tiene que ser la documentación para agentes?

Cada propiedad de abajo existe por una forma concreta en que fallan los vaults:

Propiedad	El fallo que responde
Vive en el repositorio	Se revisa como código, no se sincroniza como una carpeta
Cita una decisión, una task o un fichero	Una afirmación que no puedes rastrear es una que no puedes ponderar
Se escribe al cerrar el trabajo	No «cuando alguien se acuerde», que es nunca
Tiene un estado de archivada	Una nota equivocada debe poder retirarse por algo que no sea la memoria
Se carga según lo que declara la task	Cincuenta notas no son contexto, son ruido

Esa última fila es la que la mayoría de herramientas se salta. Entregarle a un agente una base de conocimiento entera no es ingeniería de contexto; es un prompt más grande. Lo que una task necesita es el subconjunto relevante para esa task, seleccionado por algo que la propia task declaró.

¿Y por qué no darle al agente el vault entero?

El movimiento obvio, y falla de tres formas concretas:

El volumen no es contexto. Cuatrocientas notas en un prompt significan que las tres relevantes quedan diluidas entre trescientas noventa y siete que no lo son. Eso es un prompt más grande, no un mejor anclaje, y cuesta exactitud en lugar de comprarla.

Nada dice qué notas aplican aquí. Los enlaces de un vault codifican asociación — esto me recordó a aquello — no aplicabilidad a la task que tienes delante. Son relaciones distintas, y sólo una sirve para seleccionar.

Las contradicciones no tienen resolución. Dos notas discrepan sobre cómo se despliega. Nada en el vault registra cuál ganó, porque el ganador se decidió en una conversación. El agente lo resuelve escogiendo la que más se parece al prompt, y reporta el resultado con la misma seguridad en cualquiera de los dos casos.

El desenlace es peor que un fichero corto y curado: una respuesta bien redactada, aparentemente bien fundamentada, y equivocada.

¿Lo arregla RAG sobre el vault?

En parte, y conviene ser preciso sobre qué parte, porque es el arreglo que más se propone.

La recuperación resuelve la selección. Eso es real: convierte «el agente leyó cuatrocientas notas» en «el agente leyó las cuatro más cercanas», que es una mejora de verdad y la molestia que más se nota.

No toca la procedencia ni la caducidad, y en la caducidad se inclina ligeramente hacia el lado malo. La recuperación saca lo que está textualmente más cerca de la pregunta, y una nota caducada escrita con seguridad — «las migraciones las hacemos en dos pasos» — suele ser lo más cercano a una pregunta sobre migraciones. La nota correcta puede ser más nueva, más matizada y estar redactada menos como la pregunta. Los embeddings no opinan sobre fechas ni sobre la verdad; ordenan por similitud.

Así que RAG asciende el problema de el agente lo leyó todo y no sabía qué estaba vigente a el agente leyó las cuatro cosas más relevantes y no sabía qué estaba vigente. Mejor, y no el arreglo.

¿Y Notion, Confluence o un wiki?

Responden limpiamente a uno de los tres fallos y dejan los otros dos más o menos donde estaban.

Compartido: sí. Esta es la ganancia real, y no es poco — un corpus, muchos lectores, se acabó el «la misma pregunta obtiene dos respuestas según de quién fuera el vault que leyó el agente».

Procedencia: no. Una página de wiki rara vez dice de qué decisión salió o qué incidente la produjo, por la misma razón que no lo dice una nota de vault: quien la escribió lo sabía, así que anotarlo parecía redundante.

Caducidad: podría decirse que peor. Las notas malas de un vault al menos están enterradas. Las de un wiki están indexadas, se buscan y las enlazan otras cuatro páginas, así que la escala hace una afirmación caducada más localizable, no menos, y nada en la herramienta la archiva. El mecanismo para retirar una página equivocada sigue siendo que alguien se acuerde.

Y un fallo que el wiki añade: no está donde cambia el código. Una nota en el repositorio la tienes delante, en el diff, en el momento en que alteras lo que describe. Una nota en un wiki se lee cuando alguien va a buscarla — que es justo la conducta que querías arreglar.

Cómo lo hace CommitCycle

CommitCycle llama a esto playbooks — ficheros de conocimiento por topic y por proyecto que viven en tu repositorio. Cuatro propiedades, cada una respondiendo a una fila de arriba:

Citan. Cada afirmación apunta a una decisión, una task o un fichero. Un lint señala la afirmación que no lleva ninguna cita — avisa, no bloquea — y cuando cycle seed redacta playbooks, una afirmación que cita un fichero que no está en el repositorio se descarta, y un playbook que se queda sin nada citado no se crea siquiera.
Se alimentan al cerrar el trabajo, de viñeta en viñeta, cuando la persona todavía recuerda por qué. Ni en una retro, ni cuando alguien se acuerde.
Se cargan según los topics declarados por la task, así que una task sobre la base de datos no carga las convenciones del frontend.
Se pueden archivar. archived es un estado real, y eso es lo que permite que el corpus encoja.

Y una pasada adversarial — cycle challenge — está hecha para proponer las prácticas que al repositorio le faltan a la vista, cada una con una fuente nombrada. Como cycle seed, necesita un modelo configurado en el board, y todavía no se ha ejecutado contra uno real. Puedes rechazarlas, y tu rechazo queda registrado con sus motivos. «Nos desviamos de esto a propósito, y aquí está por qué» también es conocimiento, y es del tipo que los vaults nunca capturan porque nadie escribe lo que decidió no hacer.

La parte honesta

Aquí hay una objeción real y merece una respuesta directa: «si generas un playbook a partir de mi repositorio heredado, ¿no va a codificar mi desastre?»

Sí. Por diseño, describir y nada más codifica el desastre — con recibos. Por eso existe el challenger: está hecho para proponer lo que al repo le falta en lugar de sólo describir lo que tiene, y una persona acepta o rechaza cada propuesta. No hay auto-aceptación, y hay un test que mantiene esa vía cerrada.

Lo que esto no sustituye

Quédate con el vault. Esto no es una migración.

Obsidian sigue siendo mejor que cualquier cosa de aquí para pensar — para ideas a medio formar, para conexiones que aún no has hecho, para notas que son para ti y a las que se les permite estar equivocadas. Lo que sale de ahí es el subconjunto del que otros lectores dependen para que sea cierto. Ese subconjunto siempre fue la parte que dolía cuando caducaba, y nunca fue la parte que Obsidian se diseñó para sostener.

Una línea útil que trazar: si equivocarte en esta nota induciría a error a otra persona, no pertenece a un vault personal.

Adónde va en su lugar, para las notas que un agente debe leer, es a una skill en el repositorio — el mismo markdown, pero versionado con el código que describe y cargado sólo cuando la task lo pide.

Dónde está CommitCycle de verdad

CommitCycle lleva su propio desarrollo — el board, el gate, los audit records y los playbooks descritos arriba están en uso hoy en su propio repositorio. La mitad de enforcement se instala como plugin de Claude Code; el paquete commitcycle en npm pone la CLI cycle en tu PATH, sin el hook. El board alojado es sólo por invitación mientras esto sea pequeño. Phase 0 está medida y publicada con sus límites.

Así que este post no te pide migrar nada hoy. Plantea un argumento que puedes evaluar por sus méritos, y si te convence, la waitlist es el siguiente paso honesto. Si el argumento es erróneo, eso nos vale más que un alta.

El resto del producto está documentado por completo: el bloque de contexto AGENTS.md, las zones y el audit record.