Primer mapa de repositorio con Claude Code: leer código existente sin gastar contexto

En un repositorio desconocido, el error no es que Claude Code escriba mal. El error es pedir implementación antes de entender entradas, comandos, riesgos y prueba mínima.

Por qué importa este patrón

Un mapa del repositorio no solo ahorra contexto. También permite que tú, un revisor y otro compañero hablen con la misma base. Mucho tráfico principiante llega después de instalar Claude Code y no sabe qué tarea darle primero. Este artículo convierte esa duda en una ruta hacia PDF gratis, guía de setup y consultoría.

Leer también: Leer también 1, Leer también 2, Leer también 3.

Flujo práctico

En el primer prompt prohíbe editar. Pide leer README, metadatos de package, rutas, tests y despliegue. Antes de ejecutar comandos, separa comandos seguros de zonas riesgosas. Luego elige una tarea con pocos archivos, prueba rápida y sin tocar autenticación ni pagos.

Kit mínimo para copiar

Read this repository for orientation only.
Do not edit files yet.
Return:
1. the main app entry points
2. the commands that appear safe to run
3. the files that define content, routes, and tests
4. three small first tasks ranked by verification cost
5. one risk that should block a larger change

repo_map:
  entry_points:
    - package.json
    - src/main.ts
  safe_commands:
    - npm run build
    - npm test
  first_task_rule:
    max_files: 3
    proof_required: true
    avoid_auth_and_billing: true

export function rankFirstTask(task) {
  const risk = task.touchesAuth || task.touchesBilling ? 10 : 0;
  const scope = task.filesChanged * 2;
  const proof = task.hasFastProof ? -3 : 4;
  return risk + scope + proof;
}

Ejemplos reales

En un sitio Astro, mapea src/content, src/pages, BlogPostLayout y el build antes de cambiar textos.
En un SaaS, marca autenticación, billing y migraciones como riesgo, y empieza por README o tests.
En equipo, resume el mapa dentro de CLAUDE.md para que la siguiente persona no repita la exploración.

Checklist operativo

Este patrón está pensado para repetirse durante trabajo real con Claude Code. Si cambias un artículo, una página de producto o una ruta de consulta, usa esta lista como control compacto.

Escribe el objetivo en una frase y nombra archivos o funciones fuera de alcance.
Separa los archivos que Claude Code debe leer de los que debe evitar.
Deja al menos un comando de prueba. En contenido, revisa URL pública además del build.
Comprueba que PDF gratis, Gumroad y consultoría coinciden en cuerpo y CTA final.
En posts localizados, confirma title, h1, inicio del cuerpo y CTA en el idioma correcto.
No stagees archivos sucios ajenos. Divide el diff otra vez antes del commit si hace falta.
Registra riesgo restante y próxima métrica para que la siguiente sesión empiece clara.

A qué oferta debe conducir

Si el lector aún no domina comandos, la primera salida es el cheatsheet gratuito. Si el flujo se repite cada semana, Prompt Templates ayuda a estandarizar revisión, debugging y edición de artículos. Si el bloqueo está en permisos, CLAUDE.md, hooks, MCP o CI/CD, la mejor ruta self-service es Setup Guide. Si el equipo necesita diseñar ownership, verificación pública y ruta de ingresos, la salida debe ser consultoría.

Qué dejar en el handoff

El trabajo con Claude Code no termina cuando el patch parece listo. Termina cuando la siguiente persona entiende la decisión sin repetir toda la sesión. El handoff debe incluir alcance cambiado, motivo del alcance, comandos de prueba, URL pública, destino de CTA y riesgo restante. En contenido, añade heroImage, enlaces internos, enlaces externos, revisión de idioma y si PDF gratis, Gumroad y consultoría siguen en el cuerpo. En páginas cercanas a producto, separa qué lector solo necesita el recurso gratis, qué lector debe comprar una guía y qué lector necesita ayuda.

Números a mirar después

PV no es la única métrica. Tras publicar, mira indexación, países, clics cerca de la CTA final, clics a Gumroad y visitas al formulario. En un artículo popular ya existente, compara rebote y movimiento a siguiente página antes y después. Si la siguiente sesión de Claude Code recibe esos números primero, decidirá por ruta de ingresos, no solo por volumen de texto.

Casos de fallo

Empezar por una feature permite que el cambio se extienda antes de conocer límites.
No definir comandos seguros vuelve confusa la prueba final.
No guardar el mapa obliga a gastar tokens redescubriendo la estructura.

Ruta hacia PDF gratis, Gumroad y consultoría

Empieza con el PDF gratuito para dominar comandos. Pasa a Gumroad cuando el flujo se repita, y usa consultoría cuando permisos, equipo o ingresos requieran diseño.

Nota de verificación

El artículo enlaza a mapas de codebase, gestión de contexto y runbook de primera tarea, además de incluir CTAs a PDF gratis, Gumroad y consultoría.