Claude Code — flujo de trabajo

Este archivo es lo primero que cualquier sesión de Claude Code debe leer al empezar a trabajar en esta wiki, sobre todo en una VM donde el repo no está clonado todavía. CLAUDE.md en la raíz del repo resume este orden de lectura y se carga automático al abrir el proyecto en Claude Code — este archivo es la versión completa.

Orden de lectura al iniciar sesión

1. Este archivo (meta/claude-code-workflow.md).
2. meta/convenciones.md — estructura, frontmatter, estilo.
3. meta/tags.md y meta/hosts.md — vocabulario controlado, antes de escribir cualquier tag o host nuevo.

Flujo git

Si el repo ya está clonado en la VM: git pull antes de editar, para partir de la versión más reciente.

Si el repo no está clonado en esta VM (sesión nueva en una máquina donde nunca se ha trabajado esta wiki): clonar primero con la URL del repo. Requiere que la VM tenga acceso SSH o token configurado hacia GitHub — si no lo tiene, avisar a Esteban en vez de intentar workarounds.

git clone <url-del-repo>

Después de editar:

git add .
git commit -m "mensaje descriptivo del cambio"
git pull --rebase origin main
git push

El git pull --rebase va otra vez aquí, justo antes del push — no solo al inicio de la sesión. Esta wiki la mantienen varias sesiones de Claude Code en paralelo, potencialmente en distintos hosts, y una tarea puede tardar bastante entre el pull inicial y el commit final. El pull del inicio de sesión no cubre esa ventana; el segundo pull, inmediato antes de pushear, sí. Reduce la carrera de “toda la duración de la tarea” a “los segundos entre el pull y el push”, que es lo más que se puede achicar sin coordinación explícita entre sesiones.

Si ese segundo pull trae conflicto, es casi siempre en uno de los archivos hub — tags.md, hosts.md, o el index.md del proyecto — porque casi cualquier página nueva los toca (ver reglas de registro más abajo). El patrón de conflicto es predecible: dos ediciones que agregan una línea distinta a la misma lista. Se resuelve fusionando ambos lados, nunca descartando uno — tomar solo “la versión más reciente” pierde contenido real de la otra sesión. Con git rebase, eso implica: editar el archivo para dejar ambas líneas conflictivas, git add <archivo>, git rebase --continue.

El push dispara el build automático en Cloudflare Pages (npx quartz build) — no hay paso manual de publicación. El sitio queda actualizado unos segundos/minutos después del push.

Al crear una página nueva

1. Verificar si ya existe una página relacionada antes de crear una nueva (grep por tema/host/tags) — evitar duplicar contenido que debería ser una sola página ampliada.
2. Frontmatter completo según convenciones.md — project, host (o none), tags (solo del vocabulario controlado), status, updated.
3. Si se usa un tag o host nuevo, registrarlo en tags.md / hosts.md en el mismo commit.
4. Seguir las 5 reglas de estilo de convenciones.md (tercera persona, explicar el porqué, fecha en frontmatter no en prosa, “Véase también” con anotación).
5. Enlazar la página nueva desde el index.md del proyecto correspondiente, para que quede conectada al grafo desde un nodo central.

Al editar una página existente

Actualizar updated en el frontmatter. Si el cambio hace obsoleto el contenido anterior en vez de complementarlo, cambiar status: deprecated en vez de borrar.

Búsqueda antes de responder

Antes de responder una pregunta de Esteban sobre “qué hice / dónde levanté X”, grep por host: o tags: en el frontmatter primero — es más barato en tokens y más confiable que buscar por contenido libre. Solo cargar el contenido completo de las páginas que hacen match.

Ingesta de material sin procesar

Material crudo (exports de Trilium, artículos, notas de sesión) no se escribe directo en content/ — se deja primero en raw/ (ver raw/README.md) y se compila con /wiki-ingest en batch, no una fuente a la vez. Ingesta y compilación son pasos separados a propósito.

Documentos de referencia literal

Distinto de la ingesta de arriba: cuando un documento técnico externo (cierre de query SQL, roadmap de columnas, bitácora de validación) ya sirvió para escribir o ampliar una página de content/, y vale la pena conservarlo tal cual como respaldo de detalle, se copia a sources/ — nunca se transcribe, ni ahora ni después. raw/ es staging pendiente de compilar; sources/ es un anexo permanente que ya cumplió su función de fuente y no se vuelve a tocar. Ver sources/README.md para las reglas completas.

Skills del repo

.claude/commands/ trae tres comandos reutilizables:

• /wiki-ingest — compila lo pendiente en raw/ hacia content/.
• /wiki-lint — audita content/ (tags fuera de vocabulario, wikilinks rotos, contradicciones, páginas huérfanas) sin editar nada.
• /wiki-query — responde una pregunta consultando la wiki, con la misma disciplina de búsqueda barata por frontmatter.