# Prompt: auditoría de código completa de un sitio Astro + Sanity Plantilla reutilizable para correr un QA técnico sobre cualquier proyecto Astro con CMS headless. Pensado para pegarse en Claude Code (o cualquier agente con acceso al repo y a la terminal) al terminar una migración o antes de un lanzamiento. **Cómo usarlo:** copiar todo lo que está bajo la línea, reemplazar los valores entre `<>` del bloque de contexto, y pegarlo. El resto no hace falta tocarlo. Está escrito a partir de una auditoría real de 216 páginas donde aparecieron 22 problemas que ni TypeScript ni el build detectaban. Cada check de la lista corresponde a algo que efectivamente estaba mal en un sitio que parecía terminado — no es una lista teórica de buenas prácticas. --- ## CONTEXTO DEL PROYECTO - Repo: `` - Framework: Astro ``, output `` - CMS: ``, dataset `` - Idiomas: ``. Estrategia de rutas: `` - Hosting previsto: `` - Servicios de terceros que carga el sitio: `` - Comandos: build ``, typecheck ``, dev `` ## OBJETIVO Audita el código en siete ejes —bugs, accesibilidad, rendimiento, SEO, seguridad, duplicación y deuda técnica— y entrega un reporte concreto: qué encontraste, con qué evidencia, y qué propones. **No apliques nada todavía.** Primero el reporte, después yo decido el alcance. ## REGLAS DE TRABAJO 1. **Mide, no supongas.** Cada hallazgo tiene que venir con el número, el comando que lo produjo o el `file:line`. "Podría haber un problema de rendimiento" no es un hallazgo; "el build tarda 6m36s con el CPU al 2%, porque el shell dispara 1.400 consultas idénticas" sí. 2. **Un build verde no prueba nada.** Los bugs más caros son código válido que produce output equivocado. Audita el HTML generado, no solo el fuente. 3. **Distingue severidad.** Separa lo que está roto ahora, lo que degrada métricas, y lo que es deuda técnica. No los mezcles en una sola lista. 4. **Cero cambios de contenido sin aprobación.** Si un arreglo implica tocar texto visible —copy, títulos, meta descriptions—, proponlo en una tabla "antes → después" y espera el visto bueno. El código sí se puede arreglar directo una vez aprobado el alcance. 5. **Si hay design system, úsalo.** No inventes variables de tipografía, color ni espaciado. Busca el token existente más parecido; si genuinamente no hay, avisa antes de crear uno. 6. **Reporta lo que decidiste NO hacer y por qué.** Un pendiente documentado con su motivo vale más que un arreglo apurado. --- ## FASE 0 — Inventario (antes de opinar) ```bash find src -type f | sort # estructura real wc -l src/**/*.astro | sort -n # dónde está el peso cat astro.config.mjs package.json ``` Anota: cantidad de páginas, rutas dinámicas, componentes, y qué se genera en build contra qué se resuelve en cliente. Corre el typecheck y el build **cronometrando**, y guarda el `dist/` como línea de base para comparar más adelante: ```bash time pnpm build cp -R dist /tmp/baseline ``` --- ## EJE 1 — Bugs que el compilador no ve ### 1.1 Links y assets rotos Los `href` y `src` son strings: nada los valida. Recorre el `dist/` y comprueba cada destino interno contra las páginas y archivos realmente generados. ```python # por cada .html del dist: extraer href="/..." y src="/..." # comprobar contra el set de rutas generadas + el set de archivos # reportar destino + cuántas páginas lo referencian ``` > En la auditoría real esto encontró el favicon apuntando a un archivo > inexistente. Estaba en el layout base: **404 en las 215 páginas**. ### 1.2 Jerarquía de encabezados ```bash # contar

por página en el dist — debería ser exactamente 1 ``` Si el contenido viene de un CMS con rich text migrado, revisa **qué estilos de bloque mapea el renderizador**. Todo estilo no mapeado cae al renderer por defecto: sale sin las clases del design system y, si es un `h1`, compite con el título de la página. > Doce artículos tenían hasta **siete `

`**, uno de ellos duplicando el > título. Además 17 `h4` y 2 tablas salían con la tipografía default del > navegador. ### 1.3 Fuentes de verdad duplicadas Busca diccionarios, mapas de rutas o listas de configuración que existan en más de un archivo. Presta especial atención a los que tienen un comentario del tipo "esto debe reflejar X": **ese comentario es la evidencia de que ya se desincronizaron o de que lo van a hacer.** > Un mapa de rutas EN→ES vivía en `astro.config.mjs` y en `lib/sanity.ts`, con > el comentario puesto. Al sumar el blog se actualizó uno solo: **92 de 214 URLs > del sitemap salieron sin `hreflang`.** ### 1.4 Contenido del CMS inyectado sin escapar Revisa cada `set:html`. Los valores que se interpolan dentro de atributos (`alt`, `href`, `title`) deben escaparse: `&`, `"`, `<`, `>`. Si hay SVG inline procesados por código, verifica que no se rompan las referencias internas (`fill="url(#gradiente)"`, `clip-path`). Un `id` renombrado o borrado deja el elemento negro o invisible, sin ningún error. --- ## EJE 2 — Rendimiento ### 2.1 Amplificación de consultas al CMS **El check de mayor retorno en un sitio estático.** Cuenta cuántas veces se consulta el CMS por página renderizada: ```bash grep -rn "await get\|sanity.fetch" src/components src/layouts ``` Todo lo que esté en layout, navbar, footer o secciones compartidas se ejecuta **una vez por página**. En un sitio de 200 páginas, seis consultas en el shell son 1.200 requests devolviendo lo mismo. La señal inequívoca es el build lento con el CPU bajo: no compila, espera. ```bash time pnpm build # si el %cpu es de un dígito, es red ``` Arreglo, para consultas sin parámetros: ```ts function once(fn: () => Promise): () => Promise { let cached: Promise | undefined; return () => (cached ??= fn()); // la PROMESA, no el resultado } ``` Cachear la promesa y no el valor hace que dos renders en paralelo compartan el request en vuelo. El caché vive en el módulo: cada build arranca limpio, así que no hay riesgo de servir contenido viejo. > Resultado real: **6m36s → 1m38s**. De ~1.850 ms a 4 ms por página. ### 2.2 Imágenes sin dimensiones ```bash # contar en el dist; cuántos tienen width Y height ``` Sin dimensiones hay layout shift en cada imagen. Para las locales, mide el archivo. Para las del CMS, muchas codifican el tamaño en el identificador del asset —Sanity lo hace: `image--1440x833-jpg`—, así que se puede derivar sin consultas extra: ```ts const m = ref?.match(/-(\d+)x(\d+)-[a-z]+$/i); // alto = ancho_pedido * (h / w) ``` ### 2.3 Peso y formato de los assets ```bash du -sh public/* | sort -h # ¿quedan JPG/PNG donde el resto del sitio ya usa AVIF/WebP? ``` Convierte manteniendo la resolución: el ahorro viene del códec, y así no hay riesgo de que algo se vea distinto. ### 2.4 Assets sin referencia Comparar los archivos de `public/` contra los referenciados en `src/`, CSS y JS. Los exports de constructores visuales dejan variantes responsive que nunca se usan si el markup no tiene `srcset`. > 48 archivos huérfanos, **2,55 MB**. `public/images` bajó de 7,9 a 3,2 MB. ### 2.5 Terceros en el `` Por cada script externo: ¿versión fijada? ¿bloquea el render? ¿tiene SRI? Cuidado especial con **pares core + plugin en versiones distintas** y con las URLs sin versión (`unpkg.com/` sirve siempre la última: puede cambiar en producción sin que nadie toque el repo). > Estaban GSAP core 3.15.0 y su plugin ScrollTrigger 3.14.2 —combinación que la > propia librería no soporta— más un paquete sin pinear, los tres bloqueando el > primer render. --- ## EJE 3 — Accesibilidad ### 3.1 Controles que no son controles ```bash grep -rn "addEventListener(\"click\"" public/js src ``` Por cada handler de click: ¿el elemento es un `