Mapa de codebase existente con Claude Code: flujo seguro de 45 minutos

Cuando llevas Claude Code a un codebase existente, el primer entregable no debería ser un diff. Debería ser un mapa. Un repo map explica por dónde arranca la aplicación, qué carpetas importan, qué zonas no se deben tocar hoy, cómo verificar un cambio y qué debe saber la siguiente persona. Sin ese mapa, una sesión útil puede convertirse en limpieza amplia, refactors secundarios o cambios difíciles de revisar.

Esta guía propone un flujo de 45 minutos para leer un repositorio antes de editarlo. La documentación oficial de Claude Code overview explica que Claude Code puede leer el codebase, editar archivos y ejecutar comandos. Justamente por eso conviene fijar límites antes de que el agente cambie nada.

Para complementar, revisa primeros prompts para codebases existentes, la guía de permisos de Claude Code y el starter template de CLAUDE.md.

El repo map de 45 minutos

Usa 25 minutos para exploración de solo lectura, 10 para escribir el mapa, 5 para elegir una primera tarea segura y 5 para revisar el plan. No busques un documento de arquitectura perfecto. Buscas un mapa operativo para hacer un cambio pequeño, reversible y verificable.

flowchart TD
  A["Inventario de solo lectura"] --> B["Encontrar entradas"]
  B --> C["Separar zonas seguras y riesgosas"]
  C --> D["Elegir un primer patch"]
  D --> E["Fijar comandos de prueba"]
  E --> F["Escribir repo-map.md"]

Una entrada es el punto donde comienza la app: ruta, handler de API, arranque de servidor, comando CLI, job programado o cargador de contenido. Una zona riesgosa es cualquier lugar donde un error pequeño afecta confianza o ingresos: autenticación, pagos, borrado, configuración de producción, secretos, deploy, analítica o etiquetas de anuncios.

Paso 1: inventario de solo lectura

Empieza con comandos que describen el repositorio sin modificarlo. En Windows PowerShell puedes usar esto tal cual.

git status --short
Get-ChildItem -Force | Select-Object Name, Mode, Length
Get-ChildItem -Recurse -File -Include package.json,astro.config.*,next.config.*,vite.config.*,README*,CLAUDE.md,AGENTS.md | Select-Object -ExpandProperty FullName
rg --files | Select-Object -First 120

Busca stack técnico, documentación, carpetas generadas, cachés y cambios sin commit. Si el árbol está sucio, identifica si esos cambios son tuyos o de otra persona antes de pedir a Claude Code que edite. Es la forma más simple de evitar sobrescrituras.

El primer prompt debe dejar clara la frontera de solo lectura.

Read this repository as an existing codebase. Do not edit files yet.

Goal:
- Create a first repo map in 45 minutes
- Pick exactly one safe starter task
- Identify areas that should not be touched today

Return:
1. Up to 8 important directories
2. Up to 5 runtime or content entry points
3. Risky areas with reasons
4. Three safe starter task candidates
5. Candidate proof commands

If something is uncertain, write "unverified" instead of guessing.

La frase Do not edit files yet mantiene la sesión en modo exploración hasta que exista un plan revisable.

Paso 2: escribir repo-map.md

No dejes el descubrimiento solo en el chat. Escribe un repo-map.md corto para que otra sesión lo reutilice. La documentación oficial de memory explica cómo CLAUDE.md puede guardar instrucciones persistentes, pero el primer mapa suele ser mejor como documento separado. Cuando las reglas se repitan, muévelas a CLAUDE.md.

# repo-map.md

## Purpose
- First working map for using Claude Code safely in this repository

## Entry points
| Type | File | Role | Proof |
| --- | --- | --- | --- |
| Web | site/src/pages/index.astro | Home page | npm run build |
| Content | site/src/content/blog | Article source | Open article URL |

## Safe candidates
- docs/
- site/src/content/blog/
- Small display copy

## Do not touch today
- .env and secrets
- Auth, billing, deletion flows
- Deploy scripts
- Generated dist and cache folders

## First safe task
- Improve one article CTA
- Change one file only
- Verify with build and preview

## Remaining risks
- Production data flow is unverified
- External service integrations need a separate pass

No es una arquitectura completa. Es una barrera para el primer cambio útil.

Paso 3: reforzar el mapa con permisos

Las instrucciones ayudan, pero no son enforcement. La documentación de permissions describe reglas allow, ask y deny. En una primera sesión sobre un repo existente, permite lectura y checks seguros, pregunta antes de build o edición, y bloquea push, comandos destructivos y secretos.

{
  "permissions": {
    "allow": [
      "Bash(git status *)",
      "Bash(git diff *)",
      "Bash(rg *)",
      "Bash(npm run test *)",
      "Read"
    ],
    "ask": [
      "Bash(npm run build *)",
      "Edit(site/src/content/blog/**)"
    ],
    "deny": [
      "Bash(git push *)",
      "Bash(rm -rf *)",
      "Read(.env)",
      "Read(**/.env)",
      "Edit(scripts/deploy*)"
    ]
  }
}

Este JSON es un punto de partida. Tu proyecto quizá no tenga npm run test o necesite otro directorio editable. Lo importante es decidir qué se niega antes de ampliar lo permitido.

Paso 4: elegir el primer patch seguro

Con el mapa listo, elige una tarea pequeña, reversible y fácil de verificar. Hay tres casos muy prácticos.

El primero es corregir un CTA de contenido. Por ejemplo, asegurar que un artículo popular conecte de forma natural con productos y training. Suele tocar un solo archivo y se valida con build y preview.

El segundo es documentar comandos de verificación en README o CLAUDE.md. Añadir build, test, lint y preview reduce el coste de futuras sesiones sin cambiar el comportamiento de la aplicación.

El tercero es ajustar copy o formato de fecha en una sola pantalla. Limita el patch a uno o dos archivos y valida con test, captura o preview local. Deja autenticación, pagos, permisos y borrado fuera del primer cambio.

Using repo-map.md, implement only the first safe task.

Target:
- site/src/content/blog/example.mdx

Requirements:
- Make the final CTA more natural
- Keep internal links to /products/ and /training/
- Do not change pubDate, category, tags, author, or heroImage
- Change this one file only

After finishing, report:
1. Changed files
2. Why they changed
3. Proof commands run
4. Remaining risks

Así una petición amplia se convierte en un patch revisable.

Paso 5: comprobar el mapa

Un repo map es texto, pero puedes verificar que tenga las secciones mínimas. Guarda esto como check-repo-map.js.

const fs = require("node:fs");

const file = process.argv[2] || "repo-map.md";
const text = fs.readFileSync(file, "utf8");
const required = ["Entry points", "Safe candidates", "Do not touch today", "First safe task", "Remaining risks"];
const missing = required.filter((heading) => !text.includes(heading));

if (missing.length > 0) {
  console.error(`Missing repo-map sections: ${missing.join(", ")}`);
  process.exit(1);
}

console.log(`OK: ${file} has the minimum repo-map sections.`);

node check-repo-map.js repo-map.md

El script es simple, pero obliga a dejar un handoff consistente.

Fallos comunes

El primer fallo es comenzar con una petición demasiado amplia, como “refactoriza la app” o “mejora la calidad”. La solución es fijar exploración de solo lectura, número máximo de archivos, zonas prohibidas y comandos de prueba.

El segundo es mezclar artefactos generados en el mapa. dist, .astro, .next, coverage y node_modules hacen que el repo parezca enorme sin ayudar a entenderlo. Exclúyelos salvo que sean el objetivo real de despliegue que debes inspeccionar.

El tercero es subestimar servicios externos. Email, webhooks de pago, anuncios, analítica y CRM pueden tener poco código pero mucho impacto de negocio. Léelos primero y edítalos en otra tarea.

El cuarto es terminar después del build. Un build puede pasar aunque el layout móvil, los code blocks, los CTA o los enlaces internos estén rotos. En un sitio de contenido, abre la preview y revisa cuerpo, código, /products/ y /training/.

Checklist de revisión

Lente	Revisión	Mala señal
Diff	Solo cambiaron archivos pedidos	Formateo incidental masivo
Entrada	Sabes cómo se carga el cambio	El archivo editado no se usa
Riesgo	Auth, pagos, borrado y prod intactos	Cambios en secrets o deploy
Prueba	Hay comando o check manual	Solo “probablemente bien”
Funnel	CTA y enlaces encajan	Links de producto forzados
Handoff	Riesgos restantes escritos	La próxima sesión repite investigación

La checklist no es para desconfiar de Claude Code. Es para que el trabajo sea repetible.

Incluir rutas de ingresos

En un sitio como ClaudeCodeLab, el mapa también debe incluir monetización. ¿Qué artículos traen tráfico? ¿Dónde ve el lector una descarga, un producto o una consulta? Para plantillas listas, mira la biblioteca de productos. Para adopción de equipo, permisos y operaciones de contenido, mira Claude Code training.

Cuando las rutas de ingresos están en el mapa, un CTA pequeño deja de ser solo copy. También revisas enlaces internos, páginas de producto, formularios, analítica y anuncios. El código correcto no genera ingresos si el lector no ve el siguiente paso.

Resumen

Usa los primeros 45 minutos con Claude Code para mapear el codebase, no para reescribirlo. Inventaría el repo, identifica entradas, marca riesgos, elige una tarea segura, fija pruebas y deja repo-map.md. Después haz un cambio pequeño en uno o dos archivos y verifica.