Wikipoke: la wiki de tu código que escribe tu agente de IA

Le preguntas a tu agente cómo se redondean las facturas en tu proyecto.

Abre doce ficheros, lanza seis búsquedas, se lee medio módulo de pagos y te da una respuesta. Correcta, con suerte. Al día siguiente un compañero le hace la misma pregunta con otras palabras y el agente vuelve a empezar de cero: los mismos doce ficheros, los mismos tokens, y a veces una respuesta distinta.

Eso es lo que me llevó a construir wikipoke. Es un proyecto mío, open source, y en este post te lo cuento entero: qué hace, cómo se usa en su versión más sencilla y qué casos cubre. También intento responder a las dudas que tendría yo si alguien me lo propusiera para el repositorio de mi equipo.

Esto es lo que vas a encontrar:

• Qué es wikipoke y la regla que lo sostiene: las skills escriben, el CLI solo mide
• Cómo se instala y cómo se usa en tres comandos
• Cómo es una página de la wiki y cómo sabe cuándo se ha quedado desactualizada
• Los seis casos de uso, de principio a fin
• Los números reales de tokens, incluidos los que salen mal
• Lo que necesita saber un CTO antes de meterlo en un repositorio de equipo

Qué es wikipoke ¶

Wikipoke es una wiki de tu repositorio que escribe tu agente de código, que cita cada afirmación con una línea de código y que te avisa cuando el código cambia y la wiki se queda atrás.

La wiki vive en una carpeta wiki/ dentro del propio repositorio. Son ficheros Markdown normales: el mapa de la arquitectura, los flujos que cruzan varios ficheros, una página por subsistema y las decisiones con su porqué. Nada de base de datos, ni servidor, ni índice vectorial.

Lo escriben tres skills (wikipoke-ingest, wikipoke-query y wikipoke-lint) que funcionan en Claude Code, OpenCode, Codex, Cursor y cualquier agente que lea AGENTS.md. Al lado hay un CLI pequeño que prepara el repositorio, comprueba la wiki y la enseña en el navegador.

El objetivo cabe en una frase del README: una memoria de tu código que sigue siendo cierta y que responde lo que ya se preguntó antes, barato y siempre igual.

La idea de fondo no es mía. Viene del patrón de wiki mantenida por un LLM que propuso Andrej Karpathy: un modelo que va construyendo y corrigiendo una base de conocimiento en Markdown en vez de reconstruirla en cada conversación. Lo que añade wikipoke es la parte aburrida que hace que funcione en un repositorio vivo: citas verificables, detección de páginas desactualizadas y un contrato de página que se puede comprobar en la CI.

Las skills escriben, el CLI solo mide ¶

Esta es la decisión de diseño que más condiciona todo lo demás, y me costó una versión entera llegar a ella.

La versión 0.1 tomó otro camino. El CLI era el que escribía: planificaba lotes de páginas, las publicaba por fases, tenía un bloqueo de escritura y un sello de “wiki completa”. Sobre el papel, muy robusto.

En la práctica, los agentes acabaron manejando el CLI en vez de seguir las skills. Gastaban su atención en operar la herramienta en lugar de leer el código. Y cada ejecución real sacaba una regla nueva que había que programar en TypeScript, publicar e instalar, cuando la misma regla escrita como una frase en una skill funcionaba en la siguiente ejecución.

Así que la 0.2 le dio la vuelta:

• Las skills mandan. Una persona lanza /wikipoke-ingest, /wikipoke-query o /wikipoke-lint. El agente sigue la skill y escribe las páginas en wiki/, sin pasar por el CLI.
• El CLI solo mide y muestra. wikipoke check es determinista: lee git y las páginas, e informa. wikipoke atlas pone esas páginas en un navegador. No hay paso de publicación, ni bloqueo, ni zona de preparación.
• La cobertura es deuda, no un fallo. El código que ninguna página cubre se lista para que la siguiente pasada sepa adónde ir. Un check normal solo falla cuando la wiki está rota: un campo que falta, una fuente que ya no existe, un enlace roto.

🔑 Para un equipo esto tiene una consecuencia práctica: el CLI no llama nunca a un modelo. Puedes ejecutarlo en la CI, en un hook de git o en el portátil de cualquiera sin claves de API ni coste. Los tokens solo se gastan cuando una persona lanza una skill desde su agente.

Las reglas de escritura viven en wiki/CONVENTIONS.md, un fichero que es del proyecto y que el proyecto edita. Las skills lo leen antes de escribir nada y, cuando la skill y ese fichero no están de acuerdo, gana el fichero. Si en tu equipo queréis páginas de tipo runbook o incident, se añade una fila a la tabla de tipos y listo.

Curso gratis por email

Wikipoke es skills de principio a fin: aprende a instalarlas y a crear la tuya

Un minicurso gratis por email, a tu ritmo, para dejar de repetirle lo mismo a tu agente: instalas skills y acabas escribiendo la tuya.

Apúntate al minicurso →

Instalación en un par de minutos ¶

Necesitas Node 22.18 o posterior y git. Nada más. Wikipoke no tiene dependencias en tiempo de ejecución, y eso incluye a tu proyecto: funciona igual en un repositorio de Laravel, de Go o de Python.

# En un proyecto JavaScript, como dependencia de desarrollo
npm install -D wikipoke        # luego: npx wikipoke

# Lo mismo con pnpm
pnpm add -D wikipoke           # luego: pnpm wikipoke

# En cualquier otro repositorio, en cualquier lenguaje
npm install -g wikipoke        # luego: wikipoke

Después, dentro del repositorio:

wikipoke init

init te pregunta tres cosas, una cada vez:

1. Dónde vive la wiki. wiki/ salvo que digas otra cosa (--dir docs/wiki también vale).
2. Si te parece bien la lista de ficheros que va a escribir. No escribe nada antes de tu sí, y si cancelas sale con código 1.
3. Qué hooks quieres. Te dice qué toca cada uno, si se commitea y cuáles ya están instalados. Los que encajan con los ficheros de tu agente aparecen marcados.

Lo que escribe es poco y está todo a la vista:

init nunca escribe páginas, ni index.md, ni log.md. Eso lo hace la primera pasada del agente.

Un detalle que me gusta para equipos: si es el propio agente el que ejecuta wikipoke init (sin nadie en la terminal, o con --yes), no instala ningún hook por su cuenta. Imprime lo que falta y lo que haría cada hook, y el agente te pregunta a ti. Nada instala un hook sin que una persona lo decida.

El uso más sencillo: sembrar, preguntar y mantener ¶

Si te quedas solo con esta sección, ya le sacas partido. Son tres gestos.

1. Siembra la wiki. En tu agente:

/wikipoke-ingest

El agente lee el código y escribe las avenidas: la arquitectura, los flujos principales y una página por subsistema. Luego se para. En el vídeo de demostración del repositorio, con OpenCode, la siembra tarda seis minutos, escribe 20 páginas y los ficheros de código sin cubrir bajan de 43 a 1.

2. Pregunta a través de la wiki.

/wikipoke-query ¿cómo se redondean las facturas?

El agente busca en la wiki, lee las páginas que coinciden y responde citándolas. Si la wiki no lo cubre, lee el código, responde con citas ruta:línea, te dice que había un hueco y se ofrece a guardar la respuesta. Dile que sí. A partir de ahí, esa pregunta y la misma pregunta dicha de otra forma salen de la wiki.

3. Mantenla al día. Cuando un hook te avise de que la wiki va por detrás del código:

/wikipoke-ingest

El mismo comando. Si ya hay un checkpoint, no siembra: reconcilia, que quiere decir que solo reescribe las páginas cuyo código ha cambiado desde la última pasada.

💡 Nombra la skill cuando quieras el ahorro. Si le preguntas al agente “¿cómo funciona X?” sin más, no siempre va a la wiki por su cuenta. Con /wikipoke-query delante no hay duda.

Haz commit de wiki/, de las skills y de los ficheros de hooks. Así lo tiene todo el que clone el repositorio.

Cómo es una página de la wiki ¶

Una página es un Markdown con un frontmatter pequeño. Este es el ejemplo del README:

---title: Billingtype: entityresponsibility: How invoices are computed, rounded and taxed.sources:  - src/billing/synced: a1b2c3d---Invoices round per line, not per total, because… See [the checkout flow](../flows/checkout.md).

Tres campos hacen el trabajo:

• sources: ata la página al código que documenta.
• synced: es el commit contra el que se comprobó por última vez.
• responsibility: dice en una línea de qué se encarga la página.

Los tipos de página por defecto son cinco: architecture (el mapa), flow (una secuencia que cruza ficheros), entity (un módulo o componente), concept (un patrón transversal) y decision (una elección con sus alternativas).

La regla que decide si algo merece una página está escrita así en CONVENTIONS.md: la wiki guarda lo que el código no puede decir. El porqué, los invariantes, los flujos que cruzan ficheros, las alternativas descartadas, los sitios donde tres cosas tienen que cambiar a la vez. Lo que no entra: firmas, listas de parámetros, tablas de opciones. El código y sus tipos ya lo dicen, y una copia se pudre.

Para apuntar al código se cita con línea: src/billing/invoice.ts:42, o un enlace con ancla #L42. Y la skill exige sacar ese número del fichero abierto en ese momento, nunca de memoria ni de otra página.

Se lee sin wikipoke ¶

Una wiki de wikipoke es también un bundle válido de Open Knowledge Format v0.2, el formato de Google para dar contexto curado a los agentes. Frontmatter que lee un parser YAML estricto, un type en cada fichero, okf_version en el índice y un log.md ordenado del día más nuevo al más antiguo.

Esto importa para adoptarlo: si mañana dejas wikipoke, la wiki sigue siendo tuya y sigue siendo legible. Por cualquier persona, por cualquier agente y por cualquier herramienta que entienda OKF.

Drift: la wiki que avisa cuando se equivoca ¶

La documentación escrita a mano se queda desactualizada en silencio. La que generó una IA una vez, también. Wikipoke está construido para que eso haga ruido.

wikipoke check drift

Lista tres cosas:

1. Los commits que la wiki no ha visto desde el último checkpoint.
2. Las páginas desactualizadas: aquellas cuyos ficheros de sources: han cambiado desde su synced:.
3. Las citas que el código ha movido: cada ruta:línea se lleva a través del diff y te dice a qué línea apunta ahora.

Hay un caso que rompe a casi cualquier sistema basado en commits: el merge con squash o rebase, que tira el commit que la página tenía apuntado. Wikipoke lo aguanta porque cada página guarda también un hash de sus fuentes (sources_key:), así que la respuesta no depende de cómo haga merge tu equipo.

Junto a drift hay otras dos comprobaciones:

wikipoke check              # las tres a la vez
wikipoke check coverage     # ficheros que ninguna página reclama, agrupados por carpeta
wikipoke check lint         # campos, tipos, enlaces, citas, fuentes muertas, páginas huérfanas

lint vuelve a leer cada cita y avisa de las que caen más allá del final del fichero, en una línea en blanco o en un corchete de cierre suelto. Son los síntomas típicos de una cita escrita sin abrir el fichero.

El diagrama de cómo encaja todo con los hooks lo resume bien: tú haces commit, el hook ejecuta drift, te dice “la wiki va 3 commits por detrás, 2 páginas desactualizadas”, lanzas /wikipoke-ingest, el agente lee el diff de cada página afectada, reescribe lo que cambió, pasa check y avanza el checkpoint.

Los hooks: avisos que no escriben ¶

Un hook te avisa a ti o a tu agente, en el momento justo, de que la wiki se ha quedado atrás. Ninguno la escribe, ninguno llama a un modelo y ninguno hace fallar nada.

Todos menos decisions ejecutan el mismo notificador, wiki/.wikipoke-hook.sh, que se queda en silencio cuando la wiki está al día. La cobertura se deja fuera del aviso a propósito: un notificador que repite el backlog en cada commit nunca está callado, y un notificador que nunca calla acaba silenciado.

⚠️ Instala al menos uno. Sin hooks nada te dice que la wiki se ha quedado vieja, y una wiki de la que nadie se entera deja de ser cierta sin hacer ruido.

Solo el hook git hay que reinstalarlo en cada clon, porque .git/hooks no se versiona. Con husky 9 viaja con el repositorio. Los demás son ficheros normales: un commit y los tiene todo el equipo.

wikipoke hooks                    # cuáles están instalados y cuáles desactualizados
wikipoke hooks add git claude     # instala o actualiza
wikipoke hooks remove claude      # quita uno

Los seis casos de uso ¶

El README los recorre de principio a fin. Te los resumo con lo que resuelve cada uno.

1. El sistema completo, desde cero ¶

Para el repositorio donde quieres la wiki siempre viva.

1. npm install -D wikipoke y npx wikipoke init.
2. En los hooks, elige git más el de tu agente (claude, opencode, cursor o agents).
3. /wikipoke-ingest siembra la wiki.
4. Commit de wiki/, las skills y los hooks.
5. A partir de ahí, cada commit o sesión nueva te avisa cuando el código adelanta a la wiki, y /wikipoke-ingest reescribe solo lo que cambió.

2. Preguntas que se quedan respondidas ¶

Es el caso que más uso. Triaje de bugs, onboarding, soporte: las preguntas que se repiten.

Preguntas con /wikipoke-query. Si la wiki tiene la respuesta, sale en tres o cuatro pasos. Si no, el agente lee el código, responde con citas y ofrece guardarlo como sección de una página existente o como página nueva. Al guardar, lo enlaza desde sus vecinas, lo añade a index.md y log.md, y ejecuta wikipoke check lint.

Aquí hay un paso que no es opcional: lee lo que ha guardado. Una sección que se deja un caso es peor que no tenerla.

3. Las skills sin los avisos ¶

Para quien quiere la wiki pero no quiere que nada le hable tras cada commit.

wikipoke hooks remove git claude quita los avisos. Las skills siguen funcionando cuando las nombras. Comprueba tú cuando importe, por ejemplo al cerrar una feature, con wikipoke check drift y después /wikipoke-ingest.

4. Documentación para leer y publicar ¶

Cuando lo que quieres es una web de documentación interna o pública.

wikipoke check coverage te dice qué falta. /wikipoke-ingest src/billing documenta una parte concreta y /wikipoke-ingest all da una pasada a todo. Después, wikipoke atlas --out site exporta una web estática con las citas apuntando a tu remoto de GitHub o GitLab.

Ojo con el coste: all es la forma cara de empezar (unos 39M de tokens en una app de 1.480 ficheros). Tiene sentido para documentación que quieres publicar, no para ahorrar tokens.

5. Las decisiones detrás del código ¶

El código guarda cada decisión y ninguno de sus motivos. Aquí el agente apunta el motivo mientras todavía sabe qué descartó.

Hay dos formas de activarlo, y son alternativas:

• Siempre: wikipoke hooks add decisions pide a cada agente que lee AGENTS.md que tome notas cuando escriba código.
• Cuando lo pidas: /wikipoke-implement <plan> toma notas solo para ese trabajo.

Las notas van a wiki/.inbox/, una carpeta que git nunca ve. El siguiente /wikipoke-ingest las contrasta con el código, las convierte en páginas de decisions/ y las borra. El listón lo fija tu equipo en CONVENTIONS.md y empieza estricto: una dependencia nueva en tiempo de ejecución, un patrón de arquitectura o una decisión difícil de revertir. La mayoría de las tareas no dejan nota.

⚠️ Es la única parte de wikipoke que cambia cómo trabajan los agentes en tu proyecto, no solo lo que leen. El bloque va en AGENTS.md, del que haces commit, así que llega al agente de cada compañero. Actívalo cuando el equipo lo haya acordado, y díselo a quien trabaje en el repositorio.

6. Una decisión que tomó una persona ¶

Muchas decisiones salen de una reunión o de una revisión de código, y no quedan en ningún sitio.

/wikipoke-decision mantenemos el CLI en solo lectura: un CLI que escribe necesitaría un bloqueo y una zona de preparación, y las skills ya escriben

El agente te pregunta lo que falta (casi siempre, la alternativa descartada), busca el código que la decisión limita, avisa si el código dice otra cosa y te enseña el borrador. Solo escribe tras tu sí. Si la decisión aún no está en el código, la guarda como planned: true hasta que el código la alcance. Si una decisión nueva revierte otra, la antigua se queda como historia con status: deprecated.

El atlas: la wiki en el navegador ¶

La wiki son ficheros Markdown y se leen bien en GitHub o en tu editor. Pero para una persona que llega nueva al proyecto, el atlas es mucho más cómodo.

wikipoke atlas              # http://127.0.0.1:4747, se redibuja cuando cambian las páginas
wikipoke atlas --port 8080
wikipoke atlas --out site   # la misma página como web estática

Las páginas se agrupan por tipo. Cada una empieza con su responsibility, el commit contra el que se comprobó y sus fuentes, y acaba con las páginas con las que se relaciona. Si una página está desactualizada o parte de ella es una reconstrucción (confidence: inferred), lo dice con una nota.

El grafo dibuja las páginas como nodos y los enlaces como aristas, al estilo de Obsidian con un vault. Los nodos se colorean por tipo, crecen con los enlaces y llevan un anillo cuando están desactualizados.

Si dejas el atlas abierto durante una pasada de /wikipoke-ingest, ves llegar las páginas en directo mientras el agente las escribe. Tiene su punto hipnótico, lo reconozco.

Los números de tokens, también los que salen mal ¶

¿Ahorra tokens? A veces. Ahorra en las preguntas que ya responde una página y cuesta más en las que no. Lo medí en tres repositorios, con un modelo (glm-5.3-flash a través de OpenCode) y una sesión nueva por pregunta, contando todo lo que procesó el modelo: entrada, entrada cacheada y salida.

En dos repositorios pequeños de TypeScript, con tres preguntas que ya cubría una página:

En una aplicación Laravel de 1.480 ficheros, con preguntas de triaje reales:

El ahorro sale de los pasos, no de lecturas más cortas. Cada paso del agente vuelve a enviar toda la conversación (entre 20k y 30k tokens de system prompt y herramientas antes de leer nada), así que una respuesta cuesta más o menos su número de pasos. Si quieres ver ese mecanismo en tu propia sesión, lo desmonto en en qué se gastan tus tokens de Claude Code.

De esas mismas ejecuciones saqué tres lecciones que me importan más que los porcentajes:

• Una página es tan buena como sus frases. Una página explicaba dos casos en el mismo párrafo y cuatro de seis respuestas los mezclaron. Reescrita con una frase por caso, acertaron seis de seis.
• Lee lo que se guarda. Dos de las cuatro primeras respuestas guardadas se dejaron fuera parte de la pregunta. Ahora la skill relee la sección guardada contra la pregunta antes de darla por buena.
• Construirla cuesta. En la app Laravel, sembrar costó unos 5M de tokens, guardar cada hueco entre 0,2M y 0,8M, y cubrirlo todo 39M. En la librería pequeña, cubrir todo el backlog se amortizó tras unas 70 a 100 preguntas.

🛡️ Son mis repositorios, con un modelo, de 1 a 5 ejecuciones por celda y bastante dispersión (una respuesta sin wiki se llevó 1,6M de tokens). Miden estos repositorios, no el tuyo. Haz tu propia prueba con las preguntas que tu equipo repite.

Que no se te acaben los tokens

Que no se te acaben los tokens a mitad de sesión

La wiki ataca los pasos repetidos; el curso mide las otras palancas una a una en Claude Code, Codex y OpenCode: carga inicial, AGENTS.md, skills, MCP, subagentes y caché.

Mira qué baja tu barra →

Cuándo compensa y cuándo no ¶

Mejor decirlo claro antes de que lo instales y te decepcione.

La forma barata de empezar es sembrar poco y crecer con las preguntas. La siembra dibuja el mapa y los flujos principales; cada hueco que encuentra una pregunta se guarda una vez. Y júzgalo por la segunda pregunta, no por la primera.

Queda algo sin medir y prefiero decirlo: si la wiki gana a un AGENTS.md bien cuidado más grep. Son herramientas distintas (en AGENTS.md: dónde vive cada regla de tu agente cuento qué va en ese fichero), pero la comparación directa está pendiente.

Lo que necesita saber un CTO antes de adoptarlo ¶

Esta es la sección que habría querido leer yo antes de meter cualquier herramienta nueva en el repositorio de un equipo. Voy punto por punto.

Dependencias y cadena de suministro ¶

Cero dependencias en tiempo de ejecución. El CLI es TypeScript compilado a ESM plano y todo lo que necesita al ejecutarse está en la librería estándar de Node. Las dos librerías que usa (marked para renderizar el Markdown del atlas y @clack/prompts para las preguntas de init) son devDependencies que el build empaqueta dentro, con sus licencias. Tu node_modules no crece con un árbol de dependencias transitivas.

Las versiones se publican desde GitHub Actions con npm trusted publishing y provenance: no hay token de npm guardado en ningún sitio, npm confía en el propio workflow de release. Un tag que no coincide con package.json no publica nada.

Seguridad del atlas ¶

wikipoke atlas escucha solo en 127.0.0.1, no en todas las interfaces. Cuando una cita abre un fichero de código, solo lo sirve si git lo sigue: nada de .env sin versionar ni ficheros fuera del repositorio. El propio código del servidor está pensado para que una web que reapunte su dominio a 127.0.0.1 no pueda leer tu wiki. La exportación con --out solo escribe en un directorio nuevo, vacío o de una exportación anterior, y nunca dentro de la wiki.

Qué toca en tu repositorio ¶

Wikipoke distingue entre ficheros suyos y ficheros tuyos:

• Los del proyecto (CONVENTIONS.md, .wikipokeignore) se escriben una vez y no se sobrescriben nunca. Cuando una versión nueva trae una plantilla distinta, te lo dice y tú decides qué te llevas.
• Los de wikipoke llevan una línea managed by wikipoke. Si encuentra un fichero sin esa línea donde iba uno suyo, lo deja como está y te dice qué añadir a mano.
• En los ficheros compartidos (.claude/settings.json, AGENTS.md), solo añade y quita su propio bloque delimitado.

Y hay dos fronteras que las skills no cruzan: una pasada de wiki nunca modifica código (si encuentra un bug, lo apunta y te lo cuenta) y synced: nunca se vuelve a sellar sin releer la página contra el código.

Agentes, lenguajes y estructura del repositorio ¶

Funciona con Claude Code, OpenCode, Codex, Cursor y cualquier agente que lea AGENTS.md. Las skills se escriben siempre en las dos carpetas (.claude/skills/ y .agents/skills/), así que un equipo con agentes mezclados no tiene que elegir. El lenguaje del proyecto da igual: lo que lee es git y ficheros de texto.

Si la carpeta wiki/ no te encaja, wikipoke init --dir docs/wiki la pone donde quieras y escribe un .wikipoke.json de una línea para que todos los comandos estén de acuerdo.

Coste y control del gasto ¶

El CLI no consume tokens. Las skills sí, y solo cuando alguien las lanza. Los órdenes de magnitud de la sección anterior te sirven para presupuestar: una siembra en una app grande ronda los 5M de tokens, cada hueco guardado de 0,2M a 0,8M. Lo que no deberías hacer es lanzar /wikipoke-ingest all “por si acaso”.

Calidad y revisión ¶

Una wiki escrita por agentes necesita que alguien la lea. La propia CONVENTIONS.md lo dice: cien páginas escritas de una sentada son cien páginas que nadie revisó. Por eso la wiki crece parte a parte, con una persona revisando cada pasada, y cada pasada queda en log.md.

Para esa revisión tienes dos apoyos. Las páginas llevan las claves de confianza de OKF, generated: cuando una pasada escribe o reescribe y verified: cuando solo vuelve a comprobar, cada una con quién lo hizo (claude-code/<modelo>, human:<id>) y cuándo. Y /wikipoke-lint --deep lee las páginas buscando contradicciones, afirmaciones caducadas y huecos; check te recuerda cuántos días hace de la última pasada profunda.

Salida ¶

wikipoke uninstall

Quita las skills y todos los hooks, incluidas sus entradas en ficheros compartidos. wiki/ se queda: es el conocimiento del proyecto, en Markdown y en formato OKF. No hay lock-in.

Licencia y madurez ¶

Licencia MIT. La versión actual es la 0.4.1. Es un proyecto joven, mantenido por mí, y la release no se etiqueta sin una validación de principio a fin con un agente real que queda registrada en la carpeta validation/ del repositorio, incluido lo que sale mal. La skill wikipoke-agents (que revisa o redacta tu AGENTS.md) está marcada como experimental y solo se ha probado en el propio repositorio.

Integración en la CI ¶

check tiene dos flags pensados para la CI: --json para que lo lean otras herramientas y --strict para salir con código 1 ante cualquier hallazgo.

wikipoke check --against origin/main --strict

--against mide el drift en ese ref en lugar de en tu árbol de trabajo, así que la respuesta es la misma desde cualquier rama. Un requisito: la CI necesita el historial completo (fetch-depth: 0 en actions/checkout), porque un clon superficial da el checkpoint por roto.

Por defecto, un check sin --strict solo falla ante errores de lint, es decir, ante una wiki rota. Las páginas desactualizadas y la cobertura son deuda y no ponen la build en rojo. Es una decisión deliberada: si el pipeline se rompe cada vez que alguien toca código sin actualizar la wiki, el equipo acaba desactivando el check. Empieza así y endurece con --strict cuando la wiki esté asentada.

Las notas de decisión pendientes nunca hacen fallar la CI. Tampoco la ve: la bandeja de entrada no se commitea.

Para actualizar wikipoke en el proyecto:

npm install -D wikipoke@latest && npx wikipoke update

update refresca las skills, actualiza los hooks que ya estaban, no instala ninguno nuevo y respeta tu CONVENTIONS.md.

Para quien quiera contribuir ¶

El repositorio se documenta a sí mismo con wikipoke: la carpeta wiki/ tiene 21 páginas sobre su propia arquitectura, sus flujos y sus decisiones, y la CI ejecuta wikipoke check sobre ella en cada pull request.

npm test           # node --test, ejecuta las fuentes sin compilar
npm run typecheck
npm run build      # tsc a dist/, más la página del atlas
npm run link       # tu copia de trabajo pasa a ser tu wikipoke global

Node ejecuta los .ts quitándoles los tipos, así que en desarrollo no hay nada que compilar. Lo que se publica sí va compilado, porque Node no hace eso dentro de node_modules. De ahí dos reglas para quien edite src/: los imports nombran el fichero .ts y solo se permite sintaxis que se borra sin dejar rastro (nada de enum, namespace ni parameter properties). La CI lo comprueba en Node 22.18 y 24.

La regla para añadir código al CLI está escrita en su AGENTS.md: solo entra una comprobación determinista y de solo lectura, o algo del atlas. El comportamiento nuevo va primero a una skill o a CONVENTIONS.md.

TL;DR ¶

• 📚 Wikipoke hace que tu agente escriba una wiki del repositorio en Markdown, con cada afirmación citando ruta:línea, dentro de wiki/.
• 🔧 Tres gestos: wikipoke init, /wikipoke-ingest para sembrar y mantener, /wikipoke-query para preguntar y guardar lo que falte.
• 🕰️ wikipoke check drift detecta páginas desactualizadas y citas movidas, también tras un squash o un rebase.
• ⚡ En una app de 1.480 ficheros, las preguntas con respuesta guardada costaron entre un 21% y un 75% menos tokens en cinco de seis casos; la primera vez con hueco cuesta más.
• 🛡️ Para un equipo: cero dependencias en tiempo de ejecución, CLI que nunca llama a un modelo, atlas solo en 127.0.0.1, MIT y uninstall que deja la wiki intacta.

Preguntas frecuentes ¶

¿Qué es wikipoke? ¶

Es una herramienta open source que hace que tu agente de código escriba y mantenga una wiki de tu repositorio en Markdown. Cada afirmación cita una línea de código, y un CLI de solo lectura detecta cuándo las páginas se han quedado desactualizadas respecto al código.

¿Con qué agentes de IA funciona wikipoke? ¶

Con Claude Code, OpenCode, Codex, Cursor y cualquier agente que lea AGENTS.md. Las skills se instalan en .claude/skills/ y en .agents/skills/, y hay un hook de inicio de sesión para cada uno.

¿Wikipoke necesita una clave de API o un servidor? ¶

No. El CLI no llama a ningún modelo y se ejecuta en local con Node 22.18 y git. Los tokens los gasta tu agente cuando lanzas una de las skills, con la cuenta que ya uses.

¿Sirve para proyectos que no son de JavaScript? ¶

Sí. Se instala de forma global con npm install -g wikipoke y funciona en cualquier repositorio git, sea Laravel, Go, Python o lo que sea. Solo lee git y ficheros de texto.

¿De verdad ahorra tokens? ¶

En las preguntas que ya cubre una página, sí: entre un 37% y un 49% en dos repositorios pequeños y hasta un 75% en uno grande. La primera vez que una pregunta da con un hueco cuesta más que sin wiki, porque el agente lee la wiki y luego el código.

¿Cómo sabe wikipoke que una página está desactualizada? ¶

Cada página guarda en sources: los ficheros que documenta y en synced: el commit contra el que se comprobó. wikipoke check drift compara eso con git y lleva cada cita a través del diff. Un hash de las fuentes (sources_key:) lo hace resistente a merges con squash o rebase.

¿Puedo meter wikipoke en la CI? ¶

Sí. wikipoke check --against origin/main --strict mide el drift contra main y sale con 1 ante cualquier hallazgo. La CI necesita el historial completo (fetch-depth: 0).

¿Qué pasa si dejo de usar wikipoke? ¶

wikipoke uninstall quita las skills y los hooks, y deja la carpeta wiki/. Las páginas son Markdown y un bundle válido de Open Knowledge Format, así que se siguen leyendo sin wikipoke.

¿Wikipoke modifica mi código? ¶

No. Una pasada de wiki solo toca la carpeta de la wiki. En los ficheros compartidos como AGENTS.md o .claude/settings.json solo añade y quita su propio bloque delimitado.

¿Qué diferencia hay entre wikipoke y un AGENTS.md? ¶

AGENTS.md guarda las reglas que el agente debe seguir. La wiki guarda lo que el código no dice: el porqué, los flujos que cruzan ficheros y las decisiones con sus alternativas. La wiki complementa al AGENTS.md y nunca repite sus reglas.

Fuentes ¶

• webreactiva/wikipoke — repositorio, README, CONVENTIONS.md y la wiki del propio proyecto
• Mediciones de tokens — sección del README con la metodología completa
• Validación de releases — registro de pruebas de principio a fin con agentes
• Open Knowledge Format — especificación del formato de bundle
• wikipoke en npm

🧨 Última oprtunidad para recibir la dinamita que mereces sobre programación con IA el próximo domingo: Suscríbete gratis a Web Reactiva en https://webreactiva.com/newsletter