https://docs.gitlab.com/ee/api

los agentes (y las personas que llegan por primera vez a un sitio) necesitan un índice único y predecible de dónde está la documentación. /llms.txt es la convención propuesta por Anthropic y la comunidad de llmstxt.org: un único archivo Markdown en la raíz del host con el mapa de la documentación.

Puntuación. 2 = H1 + ≥1 H2 + ≥3 enlaces + todos responden · 1 = cualquier archivo con un H1 (degradado desde 2 si los enlaces no responden) · 0 = ausente o shell HTML.

Corrección. Publica /llms.txt en la raíz del host con un título `# H1`, encabezados de sección `## H2` y al menos tres enlaces Markdown en viñetas que apunten a páginas de documentación concretas. Consulta la especificación en https://llmstxt.org.

Evidencia. https://docs.gitlab.com/llms.txt

/rubric#a1 · artículo

/llms-full.txt es el volcado de texto completo de tu documentación en un solo lugar: los agentes basados en grandes modelos de lenguaje lo prefieren antes que rastrear 200 páginas HTML. Las variantes por sección (/llms-api.txt, etc.) también sirven.

Puntuación. 3 = /llms-full.txt en la raíz del host, >1 KB · 2 = agregado por sección hallado a través de llms.txt · 0 = ninguno, o shell SPA en /llms-full.txt.

Corrección. Genera /llms-full.txt en tiempo de compilación (existen complementos para mkdocs/docusaurus) y sírvelo como text/plain. Mantenlo por debajo de 100 MB para que los agentes puedan descargarlo sin streaming.

Evidencia. https://docs.gitlab.com/llms-full.txt

/rubric#a2 · artículo

todo rastreador de IA (GPTBot, ClaudeBot, Google-Extended, PerplexityBot, CCBot) lee /robots.txt antes de rastrear. Un Allow/Disallow explícito por UA más una directiva `Sitemap:` absoluta elimina la ambigüedad tanto sobre la indexación como sobre qué indexar.

Puntuación. 3 = directiva de UA de bot de IA explícita Y línea Sitemap: absoluta · 2 = solo directiva de bot de IA · 1 = solo Sitemap absoluto · 0 = ninguno, o 404.

Corrección. Añade `User-agent: GPTBot\nAllow: /` (o Disallow según dicte tu política) para cada bot de LLM importante, además de una línea `Sitemap: https://example.com/sitemap.xml`. La directiva `Content-Signal:` de Cloudflare también cuenta.

Evidencia. https://docs.gitlab.com/robots.txt

/rubric#a3 · artículo

los sitemaps indican a los rastreadores qué indexar y con qué frecuencia cambia. Un `<urlset>` bien formado con URLs `<loc>` absolutas a lo largo de muchas páginas distintas señala una cobertura real; un sitemap mínimo con una sola URL (o una con un 70 % o más de ruido /tag/ /category/) no aporta ninguna señal.

Puntuación. 3 = bien formado + ≥3 rutas distintas + <30 % de basura de taxonomía · 2 = escaso (<3 rutas) o entre 30-70 % de basura · 1 = solo bien formado · 0 = 404 o error de análisis.

Corrección. Genera /sitemap.xml en tiempo de compilación, incluye cada página de documentación con `<loc>` como URLs absolutas y excluye las variantes /tag/, /category/, /author/, /page=. Referéncialo desde robots.txt con una línea `Sitemap:` absoluta.

Evidencia. https://docs.gitlab.com/sitemap.xml

/rubric#a4 · artículo

las etiquetas de descubrimiento permiten a los agentes encontrar la versión markdown de una página sin una solicitud aparte, y OpenGraph convierte los enlaces de documentación compartidos en vistas previas enriquecidas en Slack/Discord/Twitter. Ambas señalan conciencia de los consumidores automáticos.

Puntuación. 2 = `<link rel=alternate type=text/markdown>` + ≥3 propiedades `og:` distintas · 1 = solo alternativa markdown O solo OpenGraph · 0 = ninguna.

Corrección. Añade `<link rel="alternate" type="text/markdown" href="/page.md">` junto a tu enlace canonical, y asegúrate de que `og:title`, `og:description`, `og:image` (mínimo 3 propiedades) estén definidas en la página de inicio.

Evidencia. https://docs.gitlab.com/ee/api

/rubric#a5 · artículo

navegar 200 páginas HTML para leer tu documentación está bien para las personas; para los agentes supone un coste de tokenización un orden de magnitud mayor. Un gemelo markdown por página permite a los agentes extraer solo la prosa.

Puntuación. 7 = 3/3 páginas muestreadas tienen un gemelo .md funcional · 4 = 2/3 · 2 = 1/3 · 0 = 0/3.

Corrección. Sirve `{page}.md` (o `{page}/index.md`) junto a cada página HTML, O bien admite la negociación de contenido `Accept: text/markdown` que devuelva `Content-Type: text/markdown`. Tanto mkdocs-material como docusaurus tienen complementos para ello.

Evidencia. https://docs.gitlab.com/index.md

/rubric#b1 · artículo

JSON-LD es la forma compatible con schema.org de declarar «esta página es un Article» / «este producto es una SoftwareApplication». Los motores de búsqueda, los agentes y los extractores de datos estructurados se basan en él.

Puntuación. 4 = JSON-LD analizable con `@type` en AMBAS, la página de inicio y una página de documentación de muestra · 3 = una de las dos · 0 = ninguna.

Corrección. Incrusta `<script type="application/ld+json">{"@context":"https://schema.org","@type":"TechArticle",...}</script>` en cada página de documentación. El tipo `WebApplication` encaja bien para la página de inicio.

Evidencia. https://docs.gitlab.com/ee/api

/rubric#b2 · artículo

los enlaces canonical resuelven de forma determinista la cuestión de «¿es esta la versión http o https, con o sin barra final, con o sin parámetros?». Sin ellos, los agentes pueden indexar el mismo contenido bajo varias URLs.

Puntuación. 3 = canonical absoluto en AMBAS, la página de inicio Y una página de muestra · 2 = solo la página de inicio · 1 = presente pero relativo · 0 = ausente.

Corrección. Añade `<link rel="canonical" href="https://example.com/page">` al `<head>` de cada página. La URL debe incluir el esquema + el host (los canonical relativos son HTML válido pero anulan el propósito para los agentes entre hosts).

Evidencia. https://docs.gitlab.com/ee/api

/rubric#b3 · artículo

los agentes (y los motores de búsqueda) reducen su confianza en una documentación que no declara cuándo se actualizó por última vez. Una página de documentación de 2019 sin señal de actualidad es indistinguible de una actualizada ayer.

Puntuación. 2 = `dateModified` en JSON-LD O cabecera HTTP `Last-Modified` presente · 0 = ninguna.

Corrección. Incluye `"dateModified": "2026-05-28"` en tu bloque JSON-LD, o haz que tu CDN/servidor emita una cabecera HTTP `Last-Modified`. El uso de plantillas en tiempo de compilación lo hace gratis en la mayoría de los generadores de sitios estáticos.

Evidencia. https://docs.gitlab.com/ee/api

/rubric#b4 · artículo

una documentación etiquetada ayuda a los agentes a filtrar («muéstrame las páginas relacionadas con auth») sin analizar toda la prosa. `<meta name="keywords">`, `keywords` en JSON-LD o URLs al estilo `/tags/` cuentan todas.

Puntuación. 2 = al menos una señal de taxonomía presente (meta keywords, keywords en JSON-LD o patrones de enlace /tags|/categories|/topics/) · 0 = ninguna.

Corrección. Añade `<meta name="keywords" content="api,auth,oauth">` a cada página, O incluye un array `keywords` en tu JSON-LD, O organiza el contenido bajo prefijos de URL `/topics/` o `/tags/`.

Evidencia. https://docs.gitlab.com/ee/api

/rubric#b5 · artículo

los contenedores semánticos de HTML5 permiten a los agentes (y a los lectores de pantalla) descartar la navegación/el pie/las barras laterales y leer solo la prosa de la documentación. Una página cuyo cuerpo es todo `<div>` exige adivinar.

Puntuación. 2 = texto de `<main>` >200 caracteres Y texto de `<article>` >100 caracteres · 1 = solo `<main>` O solo `<article>` · 0 = ninguno.

Corrección. Envuelve la prosa principal de tu página en `<main>` (o `<article>` para páginas de documentación individuales). Evita usarlos para barras laterales o navegación: están pensados para el contenido real.

Evidencia. https://docs.gitlab.com/ee/api

/rubric#b6 · artículo

una especificación OpenAPI es EL contrato principal legible por máquina de una API REST. Los agentes que la encuentran pueden generar clientes, casos de prueba y documentación precisa sin leer nada de HTML.

Puntuación. 8 = hallada en una ruta de sondeo estándar (/openapi.json, /swagger.yaml, /v1/openapi.json, etc.) · 5 = hallada solo mediante el descubrimiento de enlaces HTML · 0 = nada hallado.

Corrección. Publica tu especificación en `/openapi.json` o `/openapi.yaml` en la raíz del host (o bajo la ruta de tu documentación: la Fase 53 sondea ambas). En los proyectos OpenAPI-first, tu herramienta de compilación ya la produce: solo tienes que exponerla.

Evidencia. https://docs.gitlab.com/ee/api

/rubric#c1a · artículo

encontrar una especificación (C1a) es solo el primer paso; la especificación también debe ser un 3.x válido Y describir esquemas de respuesta para que los agentes sepan qué obtendrán. Una especificación que enumera paths pero ninguna forma de respuesta es medio contrato.

Puntuación. 7 = OpenAPI 3.x + info válida + paths + ≥30 % de las operaciones tienen esquemas de contenido de respuesta · 6 = +paths pero pocos esquemas · 3 = alternativa Swagger 2.0 · 0 = error de análisis.

Corrección. Sube tu especificación a OpenAPI 3.0 o 3.1 si todavía estás en Swagger 2.0. Añade `responses: { '200': { content: { 'application/json': { schema: ... } } } }` a cada operación: los esquemas son lo que hace útil una especificación para los clientes.

Evidencia. https://docs.gitlab.com/ee/api — C1a did not find a spec body

/rubric#c1b · artículo

una especificación OpenAPI permite a los agentes generar un cliente; una colección de Postman curada o un SDK preconstruido permiten a las PERSONAS probar la API en 30 segundos. Ambos señalan inversión en la experiencia de quien desarrolla.

Puntuación. 4 = enlace a colección de Postman Y ≥1 enlace a registro de SDK · 3 = Postman O ≥2 enlaces a SDK · 2 = 1 enlace a SDK · 0 = nada.

Corrección. Publica un botón «Run in Postman» que enlace a god.gw.postman.com/run-collection, y enlaza al menos un SDK oficial de npm/PyPI/RubyGems/etc. directamente desde la página de inicio de tu documentación.

Evidencia. https://docs.gitlab.com/ee/api

/rubric#c2 · artículo

una página de documentación que solo dice «llama a /users» es inútil sin el método, los tipos de parámetro, los campos obligatorios y una solicitud/respuesta de ejemplo. Los agentes (y las personas) necesitan los cinco para hacer una llamada funcional.

Puntuación. 5 = la mayoría de las páginas muestreadas se clasifican como `complete` por el modelo de ML · 3 = la mayoría `partial` (o 2 complete + 1 absent) · 1 = la mayoría `absent` · 0 = no se hallaron páginas candidatas.

Corrección. En cada página de endpoint incluye: método HTTP + path, una tabla de parámetros con tipos e indicadores de obligatoriedad, un ejemplo con curl y un ejemplo de respuesta JSON con código de estado. Las tablas de parámetros estilo Markdown y los bloques JSON en `<pre>` se clasifican con claridad.

Evidencia. https://docs.gitlab.com/api/rest/ — ml: majority=partial

/rubric#c3 · artículo

los ejemplos con curl son comprobables universalmente; los ejemplos con SDK muestran el uso idiomático. Juntos cubren tanto la necesidad de «¿puedo probar esto rápido?» como la de «¿cómo lo integro?».

Puntuación. 4 = curl Y un bloque de SDK de un lenguaje en ≥1 página · 2 = solo curl · 1 = solo SDK · 0 = ninguno.

Corrección. Añade un bloque de código con pestañas por endpoint con al menos curl + el lenguaje de SDK que más usas (Python o JavaScript). Usa `<code class="language-python">` o `language-bash` para que tanto los resaltadores de sintaxis como nuestro clasificador lo detecten.

Evidencia. https://docs.gitlab.com/api/graphql/reference/

/rubric#d1 · artículo

`/users/{id}` con `id = 1` y `email = [email protected]` obliga a quien lee a imaginar cómo son los datos reales. Los placeholders realistas (`[email protected]`, `org_2N5x...`) reducen la fricción y evitan accidentes al pegar desde la documentación.

Puntuación. 4 = el modelo de ML dice que <20 % de los bloques de código están cargados de placeholders · 3 = 20-40 % · 2 = 40-60 % · 1 = 60-80 % · 0 = >80 % o sin bloques de código.

Corrección. Reemplaza `foo`/`bar`/`example.com`/`your_api_key`/`<string>` por valores de aspecto realista (el `pk_test_51N5...` de Stripe, el `+14155552671` de Twilio). No uses datos reales de clientes, pero imita su forma.

Evidencia. https://docs.gitlab.com/api/graphql/reference/ — ml: P(placeholder)>0.6 per block

/rubric#d2 · artículo

cuando una integración se rompe a las 3 de la madrugada, quien desarrolla necesita saber qué significa realmente `403 - resource_not_owned` sin abrir un ticket. Una página de referencia de errores dedicada marca la diferencia entre un arreglo de 5 minutos y media hora de depuración.

Puntuación. 3 = página de errores dedicada (≥3 códigos con explicaciones) · 1 = códigos de error documentados de forma intercalada entre páginas · 0 = ninguno.

Corrección. Publica `/errors` (o `/reference/errors`) enumerando cada estado HTTP que devuelves + los códigos de error a nivel de aplicación + una causa de una frase para cada uno. Las tablas funcionan bien; también las listas de definición `<dl>`.

Evidencia. https://docs.gitlab.com/ee/api

/rubric#d3 · artículo

la autenticación es lo mínimo; los límites de tasa son lo que permite a quien desarrolla saber si su integración sobrevivirá a la carga de producción. Ambos pertenecen a una página de documentación de primer nivel descubrible desde la página de inicio.

Puntuación. 3 = autenticación y límites de tasa documentados · 2 = solo autenticación · 1 = solo límites de tasa · 0 = ninguno.

Corrección. Añade páginas `/authentication` (flujos bearer / API-key / OAuth) y `/rate-limits` (req/min, cabeceras como `X-RateLimit-Remaining`, semántica de reintento del 429). Cada una necesita al menos 200 caracteres de contexto, no solo un fragmento de código.

Evidencia. https://docs.gitlab.com/ee/api

/rubric#d4 · artículo

¿es un «workspace», un «team» o una «organisation»? Elegir un término y mantenerlo en toda la documentación previene toda una clase de tickets de soporte del tipo «¿qué significa X aquí?». Lo mejor es un glosario dedicado; un uso coherente es aceptable.

Puntuación. 3 = /glossary dedicado con ≥3 pares estructurados de término/definición · 2 = sin glosario pero la terminología se mantiene coherente entre páginas (≥80 % de la variante dominante) · 1 = existe un enlace al glosario pero el contenido es escaso · 0 = ninguno.

Corrección. Publica `/glossary` como un `<dl>` con pares `<dt>término</dt><dd>definición</dd>` (o una tabla de 2 columnas con definiciones de ≥50 caracteres). Usa la misma capitalización/ortografía para cada término en todas las páginas.

Evidencia. https://docs.gitlab.com/ee/api — no glossary; 2/2 groups consistent, 0% inconsistent, 15 occ

/rubric#d5 · artículo

quien pegue tu ejemplo de código de 2022 en un proyecto de 2026 no debería descubrir en tiempo de ejecución que el endpoint está obsoleto. Marcadores explícitos de `deprecated` / `beta` / `sunset` en la documentación ahorran dolores de cabeza en la migración.

Puntuación. 2 = `deprecated` en la especificación OpenAPI O en ≥2 páginas de muestra cerca de los encabezados de endpoint · 1 = se hallan palabras clave beta/experimental pero ninguna obsolescencia · 0 = ninguno.

Corrección. Marca cada endpoint obsoleto con `deprecated: true` en OpenAPI Y una insignia o advertencia visible en la documentación HTML (el `<Warning>` de Mintlify, la sintaxis de advertencias de Docusaurus, etc.). Lo mismo para los endpoints en beta: visibles en la prosa, no solo en la especificación.

Evidencia. https://docs.gitlab.com/api/graphql/reference/

/rubric#d6 · artículo

este es el criterio DE BLOQUEO. Si tu documentación solo se renderiza después de que se ejecute JavaScript (shell de single-page-app), los agentes que descargan el HTML en bruto no ven nada. Los rastreadores web + scrapers + curl + la mayoría de los recolectores de IA no ejecutan JS.

Puntuación. 6 = texto del cuerpo >500 caracteres en al menos una página (la de inicio o 2 subpáginas) en los modos de UA · 3 = la página de inicio pasa pero las subpáginas son SPA · 0 = shell SPA en todas partes, o trampa VK (3+ URLs devuelven un cuerpo idéntico).

Corrección. Sirve HTML prerenderizado en URLs estáticas. Si usas Next.js/Nuxt/SvelteKit, habilita SSG o SSR para la sección de documentación. Los shells de single-page-app (React SPA, Vue SPA sin SSR) suspenden este criterio y arrastran a cero en cascada muchos otros.

Evidencia. https://docs.gitlab.com/ee/api

/rubric#e1 · artículo

cuando reorganizas la documentación, los enlaces antiguos no deberían dar 404, sino redirigir con 301 a la nueva URL. Las URLs estables son lo que permite que los enlaces internos de blogs, Stack Overflow y marcadores sobrevivan a tu refactorización.

Puntuación. 2 = redirección 301/308 estable en ≥1 de 2 variantes de URL muestreadas · 1 = patrón de alias canonical (200 con `<link rel=canonical>`) · 0 = 302 (no permanente), 404 o sin redirección.

Corrección. Cuando cambies la URL de un documento, añade una redirección 301 de la ruta antigua a la nueva. Los generadores de sitios estáticos lo gestionan mediante configuraciones `_redirects` (Netlify) o `redirects:` en `vercel.json` (Vercel).

Evidencia. https://docs.gitlab.com/

/rubric#e2 · artículo

`/v1/users` frente a `/v2/users` es la forma barata de versionar una API Y de hacerlo evidente para los agentes. Los metadatos de versión que solo están en una cabecera (y no en la ruta ni en el encabezado de la documentación) son invisibles para los rastreadores.

Puntuación. 2 = versión en la estructura de URL propia de la documentación (URL del sitemap o de la spec OpenAPI: `/v1/`, `/2024-01-15/`) · 1 = versión en la URL de un endpoint documentado (ejemplos curl/código), en `info.version` de OpenAPI, o en un encabezado `<h1>`/`<h2>`/pie de página · 0 = ninguna.

Corrección. Prefija las rutas de tu API con `/v1/`, `/v2/` y muéstralas en tus ejemplos curl/código; O establece un `info.version` no vacío en tu especificación OpenAPI. Las APIs versionadas por fecha (`/2024-01-15/users`) también cuentan.

Evidencia. https://docs.gitlab.com/ee/api

/rubric#e3 · artículo

los enlaces internos podridos son el modo de fallo de documentación más común tras años de cambios. Una comprobación puntual de 5 enlaces atrapa los peores casos (4xx/5xx en enlaces que están en tu propia página de inicio) sin intentar rastrear cada enlace.

Puntuación. 2 = 5/5 de los enlaces del mismo host muestreados devuelven 200 · 1 = 4/5 · 0 = ≤3/5, O se hallaron menos de 5 enlaces distintos del mismo host en la página de inicio.

Corrección. Ejecuta un verificador de enlaces como parte de tu CI (lychee, htmltest, linkinator). Para los enlaces más transitados de la página de inicio, corrige cualquier 404 antes de publicar. Cinco enlaces funcionales desde la página de aterrizaje es el mínimo imprescindible.

Evidencia. https://docs.gitlab.com/

/rubric#e4 · artículo

sin un TOS o una política de uso de IA explícita, todo scraper de LLM tiene que adivinar tu postura. Añadir una página `/terms` o `/license` sustancial, especialmente con palabras clave de IA/ML, hace que la política sea legible por máquina.

Puntuación. 2 = página de TOS hallada Y contiene palabras clave de política de IA/ML en el contenido principal · 1 = TOS hallado (sustancial pero sin palabras clave de IA, o enlace presente pero página 404/escasa) · 0 = sin enlace a TOS.

Corrección. Publica `/terms` (o `/legal`, `/license`) con al menos 1000 caracteres de texto de política. Incluye lenguaje explícito sobre el scraping de IA, el entrenamiento de modelos y el acceso automatizado: aunque lo permitas todo, decirlo es la señal.

Evidencia. https://docs.gitlab.com/ee/api/license

/rubric#e5 · artículo