Documentación para agentes de IA

Cómo conectar Claude, Cursor, VS Code o Codex a esta documentación por MCP, llms.txt o Markdown, y qué reglas siguen los agentes en el código de VANTS.

Esta documentación está preparada para que un agente de IA la consulte igual que una persona. Puedes conectarla a tu editor por MCP, darle a un modelo el índice llms.txt o leer cualquier página en Markdown. Esta página explica cada opción y resume las reglas que siguen los agentes cuando trabajan en el código de VANTS.

Por dónde empezar

1. Mapa del código

   Mapa del código indica qué repositorio y qué archivo tocar para cada cambio.

2. Glosario

   Glosario explica prefijos como pt_ y mm_ y nombres como RR, VANTS-BUS o VANTCALL.

3. Arquitectura

   Arquitectura general muestra cómo se conectan el Worker, Neon, Auth0, Stripe, el bot y los workflows.

4. Referencia

   API pública, Esquema de la base de datos, Bot de Discord y Seguridad tienen el detalle de cada área.

Formas de leer esta documentación

Recurso	Dirección	Para qué sirve
Servidor MCP	https://vantsgg.mintlify.app/mcp	Buscar y leer páginas desde Claude, Cursor, VS Code, Codex u otro cliente MCP
Índice	llms.txt	Lista de todas las páginas con su descripción, en el orden del menú
Documentación completa	llms-full.txt	Todo el contenido en un solo archivo de texto
Página en Markdown	Añade .md a la dirección de la página, por ejemplo glosario.md	Una página concreta, sin HTML

El menú de la parte superior de cada página permite copiarla o verla en Markdown, abrirla en ChatGPT, Claude o Perplexity, copiar la dirección del servidor MCP e instalarlo en Cursor o VS Code.

Conectar el servidor MCP

El servidor no pide autenticación. Permite buscar en esta documentación y leer sus páginas como si fueran archivos.

Claude Code

claude mcp add --transport http vants-docs https://vantsgg.mintlify.app/mcp

Cursor

Añade el servidor a .cursor/mcp.json en el proyecto, o a ~/.cursor/mcp.json para todos tus proyectos:

{
  "mcpServers": {
    "vants-docs": {
      "url": "https://vantsgg.mintlify.app/mcp"
    }
  }
}

VS Code

Añade el servidor a .vscode/mcp.json:

{
  "servers": {
    "vants-docs": {
      "type": "http",
      "url": "https://vantsgg.mintlify.app/mcp"
    }
  }
}

Codex

Añade el servidor a ~/.codex/config.toml:

[mcp_servers.vants-docs]
url = "https://vantsgg.mintlify.app/mcp"

Cómo usar esta documentación

• Si una página no coincide con el código, manda el código. Para el esquema de la base de datos, mandan las migraciones de VantsBasededatos.
• Las páginas de Referencia describen la versión de Vantsgames, salvo que indiquen otro repositorio.
• No des por hecho rutas, tablas, comandos ni variables que no aparezcan aquí: búscalos en el repositorio antes de usarlos.
• Para editar esta documentación, sigue las reglas de AGENTS.md en la raíz del repositorio de la documentación.

Reglas para agentes en el código

Vantsgames y vants-dev-launcher tienen en la raíz un CLAUDE.md con el acuerdo de trabajo del equipo con los agentes. Léelo antes de cambiar código. Sus reglas principales:

• Contexto antes que prompt: cada encargo indica qué archivos tocar y cuáles no, qué está hecho y cuál es el criterio de aceptación.
• Nada de migraciones sin revisión: el esquema se diseña antes de escribir la migración y el propietario la revisa. Ningún agente ejecuta SQL destructivo (DROP, TRUNCATE o DELETE masivo) contra Neon.
• Verificado, o no está terminado: ejecuta node --check en cada archivo JavaScript que toques y prueba en el navegador el flujo afectado. Si algo no se pudo verificar, dilo.
• Imita el repositorio: busca antes de crear, usa IIFE con 'use strict' y escHtml para todo texto dinámico, y no añadas frameworks nuevos a la web estática. Un mismo commit no mezcla refactor y funcionalidad.
• A producción no se llega sin una persona: ningún agente hace push a main. Trabaja en una rama y abre un PR; el propietario lo fusiona, y fusionar despliega.
• Lo prohibido va en hooks: .claude/settings.json bloquea las acciones peligrosas antes de ejecutarlas, como tocar archivos .env o de claves, git push --force o editar .github/workflows/ sin que lo pida el propietario.
• Un agente, un rol: quien escribe un cambio no lo aprueba. Otra pasada, de un agente o de una persona, revisa el diff antes del PR.
• Autenticado no es autorizado: toda consulta que devuelva datos de alguien comprueba que le pertenecen (RLS de Neon y auth0_sub). Los errores indican el código y el campo que falla, nunca trazas ni SQL.
• Todo se ejecuta dos veces: los webhooks y las integraciones son idempotentes, y ninguna consulta a Neon va dentro de un bucle del frontend.
• Decisiones con fecha de caducidad: toda decisión difícil de deshacer se registra en DECISIONS.md con su contexto, motivo, consecuencias, fecha y qué la invalidaría.

Además, en vants-dev-launcher

• La web estática está en tres carpetas idénticas: la raíz, public/ y vants-server/public/. Aplica cada cambio en las tres y comprueba que node scripts/build-webapp.mjs --check termina sin diferencias.
• Si cambias un JavaScript o un CSS que cargan las páginas, sube su versión (archivo.js?v=N pasa a N+1) en todos los HTML que lo cargan, en las tres carpetas, y en webapp/src/layouts/Base.astro.