Wiki de proyecto

Wiki

Un wiki de proyecto es una carpeta de páginas Markdown que explica el proyecto: qué hacen sus partes, por qué funciona como lo hace y dónde está la evidencia. Lo leen las personas. Lo mantienen los agentes. Cada nueva fuente, pregunta o cambio de código debería dejarlo un poco más completo y preciso.

Esto sigue el patrón "LLM wiki": conserva las fuentes originales, escribe páginas que las resuman y las conecten, y mantiene un índice y un registro para que todo siga siendo navegable.

Primero, las reglas del repositorio

Si el repositorio ya tiene un wiki, lee su archivo de esquema o instrucciones (normalmente wiki/README.md, wiki/AGENTS.md o wiki/schema.md) antes de cambiar nada. Su estructura, metadatos, estilo de enlaces y comandos tienen prioridad sobre los valores predeterminados aquí. Usa los scripts del wiki del repositorio cuando existan, y no edites manualmente los archivos que ellos generan.

Las partes

Parte	Qué es	Quién la edita
Fuentes	Copias del material original: issues, PRs, artículos, notas, transcripciones	Se añaden una vez, nunca se cambian
Páginas	Explicaciones escritas de temas, citando fuentes y código	Se actualizan cuando los hechos cambian
Esquema	Un archivo con las reglas del wiki: estructura, metadatos, convenciones	Se cambia deliberadamente
Índice	Una lista de cada página con un resumen de una línea	Se regenera o se mantiene completo
Registro	Una lista fechada y de solo añadido de cambios en el wiki	Una entrada por operación

Una estructura predeterminada para un wiki nuevo:

wiki/
├── README.md     # qué es el wiki y cómo usarlo
├── schema.md     # las reglas (el único lugar donde están escritas)
├── index.md      # cada página, una línea cada una
├── log.md        # qué cambió, lo más nuevo al final
├── pages/        # páginas de temas
└── sources/      # material original, sin cambios después de añadirse

Un proyecto pequeño puede quedarse así. Añade subcarpetas solo cuando haya suficientes páginas para que la gente no encuentre las cosas.

Quién tiene razón cuando las fuentes discrepan

Escribe, en el esquema, qué fuente prevalece para cada tipo de afirmación. Para la mayoría de los proyectos de software:

• Cómo se comporta el código hoy: el código y sus pruebas.
• Qué se decidió y por qué: el registro de decisión, issue o PR donde se decidió.
• Qué está planificado o en progreso: el rastreador de issues o la hoja de ruta.

Cuando una página y su autoridad discrepan, corrige la página y deja una nota breve de lo que cambió si la creencia anterior merece recordarse. Nunca edites una fuente para que coincida.

Páginas

• Un tema por página, con un título claro. Actualiza la página existente en lugar de añadir una casi duplicada.

• Cita lo que afirmes. Enlaza a la fuente o nombra el archivo. Un lector debería poder verificar cualquier afirmación importante.

• Usa enlaces Markdown relativos ([Parser](parser.md)) a menos que el wiki ya use otro estilo.

• Mantén el frontmatter pequeño. Un mínimo útil:

  ---
  title: Parser
  summary: Cómo se leen y validan los archivos de entrada.
  sources: [sources/issue-42.md]
  code: [src/parser.ts]
  updated: 2026-01-31
  ---
  

  Añade campos solo cuando una persona o un script vayan a usarlos.

• Cada página es accesible desde el índice y desde al menos una página relacionada.

Operaciones

Configurar un wiki nuevo

1. Observa qué documentación ya existe y quién la lee. No dupliques un sitio de documentación funcional.
2. Propón la estructura y el esquema al usuario, y acuérdalo antes de escribir páginas.
3. Crea README.md, schema.md, index.md y log.md.
4. Escribe algunas páginas para las partes más importantes del proyecto, luego detente y verifica con el usuario antes de completar el resto.
5. Apunta las instrucciones del agente del repositorio (AGENTS.md, CLAUDE.md) al esquema, en lugar de copiar las reglas dentro de ellos.

Añadir una fuente

1. Guarda el material original en sources/, con su procedencia y fecha.
2. Léelo completo.
3. Encuentra cada página existente que afecta y actualízalas. Crea una página nueva solo para un tema que no tenga ninguna.
4. Nota cualquier cosa en ella que contradiga las páginas actuales y resuélvelo usando las reglas de autoridad.
5. Actualiza el índice y añade una entrada en el registro.

Guardar una fuente sin actualizar ninguna página no está terminado. Las páginas son lo que la gente lee.

Responder una pregunta

1. Empieza por el índice, luego busca títulos y texto de páginas.
2. Lee las páginas relevantes y verifica las afirmaciones importantes contra sus fuentes o el código.
3. Responde con enlaces a las páginas y la evidencia que usaste. Indica dónde discrepan o dónde el wiki no tiene respuesta.
4. Si la respuesta es nueva y es probable que se pregunte de nuevo, ofrece añadirla al wiki.

Actualizar tras un cambio de código

Cuando un cambio altera cómo funciona algo:

1. Busca en el wiki los archivos, funciones y términos que tocó el cambio.
2. Actualiza cada página afectada en el mismo PR que el cambio de código.
3. Actualiza el índice si cambiaron los títulos o resúmenes, y añade una entrada en el registro.

Verificar la salud del wiki

Busca:

• enlaces rotos y rutas de código que ya no existen;
• páginas sin enlaces entrantes;
• páginas duplicadas sobre el mismo tema;
• fuentes que ninguna página cita;
• páginas que discrepan entre sí o con el código;
• un índice al que le falten páginas o que liste páginas eliminadas.

Corrige los problemas mecánicos, como enlaces y el índice, directamente. Reporta las decisiones que requieran criterio, como fusionar páginas o decidir qué afirmación es correcta, al usuario.

Entradas del registro

Añade una entrada por operación, al final de log.md:

## 2026-01-31 14:05 UTC: ingest | Issue 42, líneas de entrada vacías

Se añadió el issue como fuente y se actualizó la sección de validación de la página del parser.

Incluye siempre la hora y la zona horaria para que las entradas del mismo día se mantengan en orden.

No hagas

• Editar una fuente después de añadirla.
• Reestructurar o renombrar partes grandes del wiki sin preguntar.
• Eliminar páginas porque están desactualizadas. Márcalas como desactualizadas y enlaza a lo que las reemplazó.
• Escribir las mismas reglas en varios lugares. El esquema es la única copia.
• Tratar el wiki como más autoritativo que el código que describe.
• Escribir en un sistema externo (Confluence, Notion, un rastreador de issues) sin la aprobación del usuario.