Cómo navegar codebases grandes con Claude Code y Codex

Cuando entras a una base de código grande, el objetivo inicial no es entender cada archivo. Lo primero es construir un mapa: por dónde arranca el sistema, qué carpetas son generadas, qué archivos tienen riesgo de negocio y qué límites de propiedad no debes cruzar sin revisión.

Claude Code y Codex ayudan mucho en esa lectura, pero solo si la investigación está controlada. Si pegas archivos completos, logs largos y cientos de resultados de búsqueda en la conversación principal, tendrás más texto, no más claridad. A eso le llamo hinchazón de contexto: la conversación crece, pero la densidad de información útil baja.

Esta guía convierte el flujo que uso en handoffs, auditorías y mantenimiento de artículos de ClaudeCodeLab en comandos y paquetes de prompts copiables. Para el comportamiento de las herramientas uso documentación oficial: Claude Code common workflows, CLI reference, memory, Codex non-interactive mode y Codex AGENTS.md.

Empieza Con Un Mapa Del Repo

Antes de pedirle a un agente que explique el repositorio, reduce tú mismo la forma exterior. rg es ripgrep: rápido, práctico y fácil de combinar con exclusiones para que dist, build o coverage no contaminen la lectura.

git status --short
git rev-parse --show-toplevel
git branch --show-current

rg --files \
  -g '!*node_modules*' \
  -g '!dist' \
  -g '!build' \
  -g '!coverage' \
  -g '!*.lock' \
  | sed 's#^[^/]*/##' \
  | sort \
  | uniq -c \
  | sort -nr \
  | head -40

find . -maxdepth 3 \( \
  -name package.json -o \
  -name pnpm-workspace.yaml -o \
  -name pyproject.toml -o \
  -name go.mod -o \
  -name Cargo.toml -o \
  -name Dockerfile -o \
  -name docker-compose.yml -o \
  -name AGENTS.md -o \
  -name CLAUDE.md \
\) -print

Después pide un mapa en modo solo lectura. Los workflows oficiales de Claude Code recomiendan empezar con preguntas amplias y luego bajar a componentes concretos. La documentación de Codex indica que codex exec corre por defecto en un sandbox de solo lectura, así que encaja bien para el primer resumen.

codex exec "Read only. Summarize the repository map: apps, packages, entrypoints, test commands, generated folders, and files that define project rules. Do not edit files."

Con Claude Code, -p sirve para obtener una respuesta no interactiva. La referencia CLI lo documenta como print mode.

claude -p "
Solo lectura. Construye un mapa de este repositorio.
Devuelve la respuesta en este orden:
1. Apps, packages y services
2. Entrypoints de ejecución, test y build
3. Carpetas generadas y carpetas que conviene ignorar
4. Puntos clave de AGENTS.md, CLAUDE.md, README y notas de diseño
5. Los siguientes 10 archivos que leerías, con una razón por archivo
Solo sugiere ediciones o comandos; no los ejecutes.
"

Busca Por Capas

Un match de texto no es comprensión. La búsqueda solo genera candidatos. Uso cinco capas: estructura, vocabulario de dominio, referencias, configuración e historia.

# 1. Candidatos a entrypoint
rg -n "createServer|listen\(|app\.use|router\.|main\(|bootstrap|hydrateRoot|createRoot" \
  src apps packages server web

# 2. Vocabulario de dominio. Cambia estos términos para tu producto.
rg -n "Auth|Billing|Invoice|Notification|Search|FeatureFlag" \
  src apps packages test tests

# 3. Llamadores y referencias del área que podrías modificar
rg -n "AuthService|useAuth|requireAuth|authMiddleware" \
  src apps packages test tests

# 4. Configuración y variables de entorno
rg -n "process\.env|import\.meta\.env|PUBLIC_|DATABASE_URL|JWT|STRIPE|OPENAI|ANTHROPIC" \
  . -g '!node_modules' -g '!dist' -g '!build'

# 5. Historia: por qué existe este diseño
git log --oneline --decorate --date=short --max-count=30 -- src/auth packages/auth

No pegues cien resultados en el agente. Mira primero la forma del resultado y pásale un conjunto pequeño para clasificar.

Eres revisor de navegación de codebase.
Clasifica estos resultados de rg en: entrypoint de implementación, llamador, configuración, test y ruido.
Limita cada clase a los 5 archivos más importantes para leer después.
Para cada archivo elegido, da una razón concreta.
Si no estás seguro, escribe "necesita otra búsqueda" en lugar de adivinar.

Dibuja Un Grafo De Dependencias Ligero

Antes de instalar un analizador completo, un script pequeño de Node puede dar suficiente señal. No es un compilador de TypeScript; solo sigue imports relativos locales. Aun así, ayuda a ver el radio de impacto directo.

#!/usr/bin/env node
import { execFileSync } from "node:child_process";
import { readFileSync } from "node:fs";
import path from "node:path";

const target = process.argv[2]?.replace(/\\/g, "/");
if (!target) {
  console.error("Usage: node scripts/dependency-map.mjs src/path/to/file.ts");
  process.exit(1);
}

const tracked = execFileSync("git", ["ls-files"], { encoding: "utf8" })
  .split(/\r?\n/)
  .filter(Boolean)
  .map((file) => file.replace(/\\/g, "/"));

const trackedSet = new Set(tracked);
const sourceFiles = tracked.filter((file) => /\.(mjs|cjs|js|jsx|ts|tsx)$/.test(file));
const importPattern =
  /(?:from\s+["']([^"']+)["']|import\s*\(\s*["']([^"']+)["']\s*\)|require\s*\(\s*["']([^"']+)["']\s*\))/g;

function resolveLocalImport(specifier, fromFile) {
  if (!specifier.startsWith(".")) return null;
  const base = path.normalize(path.join(path.dirname(fromFile), specifier)).replace(/\\/g, "/");
  const candidates = [
    base,
    `${base}.ts`,
    `${base}.tsx`,
    `${base}.js`,
    `${base}.jsx`,
    `${base}/index.ts`,
    `${base}/index.tsx`,
    `${base}/index.js`,
  ];
  return candidates.find((candidate) => trackedSet.has(candidate)) ?? base;
}

const incoming = [];
for (const file of sourceFiles) {
  const source = readFileSync(file, "utf8");
  for (const match of source.matchAll(importPattern)) {
    const resolved = resolveLocalImport(match[1] || match[2] || match[3], file);
    if (resolved && (resolved === target || resolved.endsWith(`/${path.basename(target)}`))) {
      incoming.push(file);
    }
  }
}

console.log(`Target: ${target}`);
console.log("Direct importers:");
for (const file of incoming.sort()) console.log(`- ${file}`);

Guárdalo y ejecútalo así.

mkdir -p scripts
$EDITOR scripts/dependency-map.mjs
node scripts/dependency-map.mjs src/services/AuthService.ts

Luego convierte la salida en un mapa de riesgo.

Con estos direct importers, evalúa el radio de impacto de cambiar AuthService.ts.
Usa high / medium / low.
High significa autenticación, billing, autorización, persistencia o API pública.
Para cada clase, lista tests y archivos de configuración que deberían leerse antes de editar.

Traza Desde Los Entrypoints

Una lista de archivos no explica el comportamiento en runtime. En backend, traza request, middleware, route, controller, service, repository y database. En frontend, traza route, loader, state, API client, component y analytics.

rg -n "middleware|loader|action|controller|handler|route|repository|service" \
  src apps packages \
  -g '*.ts' -g '*.tsx' -g '*.js' -g '*.jsx'

rg -n "fetch\(|axios|graphql|trpc|prisma|drizzle|sequelize|typeorm" \
  src apps packages \
  -g '*.ts' -g '*.tsx' -g '*.js' -g '*.jsx'

Pide una tabla de flujo, no un párrafo.

Lente	Buen resultado	Resultado débil
Entrada	POST /login -> auth route -> AuthService.login	”Auth es importante”
Estado	Cookie, session, DB, cache o queue mutado	No lista cambios de estado
Fallo	Respuesta de error, log, auditoría, retry	Solo happy path
Tests	Test existente y casos faltantes	”Añadir tests” genérico

Traza el flujo de login desde el entrypoint hasta la persistencia.
Devuelve una tabla con columnas: orden, archivo, función/clase, cambio de estado, comportamiento de fallo, tests que leer.
No rellenes huecos con suposiciones. Si falta un paso, nombra el siguiente archivo a inspeccionar.

Mapea Propiedad Y Riesgo

En un repositorio grande, la primera pregunta no es “¿corre?”, sino “¿de quién es este límite?”. Los límites pueden ser de equipo, datos, release, compliance o ingresos.

find . -maxdepth 4 \( \
  -name CODEOWNERS -o \
  -name OWNERS -o \
  -name README.md -o \
  -name AGENTS.md -o \
  -name CLAUDE.md \
\) -print

rg -n "owner|maintainer|deprecated|legacy|do not edit|generated|migration|rollback|release" \
  . -g '!node_modules' -g '!dist' -g '!build'

Codex lee oficialmente AGENTS.md, así que vale la pena poner reglas del proyecto allí. Claude Code puede usar CLAUDE.md y memory para acortar sesiones futuras. Para una plantilla más amplia, mira CLAUDE.md Best Practices.

## Codebase map

### Entry points
- Web: apps/web/src/main.tsx
- API: services/api/src/server.ts
- Jobs: services/jobs/src/index.ts

### Ownership boundaries
- services/payments: owned by payments team; never change schema without migration review.
- packages/ui: shared design system; visual regression test required.
- legacy/: read-only unless the issue is production severity.

### High-risk files
- services/api/src/auth/AuthService.ts: login, session rotation, audit log.
- packages/db/schema.ts: migrations affect API and jobs.
- apps/web/src/routes/checkout.tsx: revenue path and analytics.

### Handoff notes
- Always start with rg search, then read top files.
- Prefer small diffs with tests.
- Do not paste large logs into the main conversation; summarize first.

Usa Prompts De Exploración Solo Lectura

En la primera exploración, mantén al agente en modo consultivo. Necesitas mapa, hipótesis e incógnitas antes de que empiece a cambiar archivos.

Investiga en modo solo lectura. No edites archivos, no añadas dependencias, no formatees código y no ejecutes tests.

Objetivo:
Entender el alcance de implementación y el riesgo de cambio para [nombre de la feature].

Devuelve:
1. Archivos entrypoint
2. Modelos de datos centrales
3. Dependencias directas e indirectas
4. Límites de propiedad
5. Mapa de riesgo: high / medium / low
6. Archivos a inspeccionar después
7. Hipótesis aún no confirmadas

Reglas:
Marca las conjeturas como hipótesis.
Incluye nombres de archivo y evidencia.
No cites cuerpos grandes de archivos.

Los subagents de Claude Code sirven cuando la exploración llenaría la conversación principal con lecturas de archivos. La documentación oficial explica que trabajan en su propio contexto y devuelven solo un resumen. Codex también documenta subagents para exploración paralela de código. Úsalos con límites claros porque consumen tokens. Hay más patrones en Subagent Patterns.

Ejecuta tres subagents en modo solo lectura:
1. Entrypoints API y límites de auth
2. DB schema y límites de migration
3. Rutas UI y camino de ingresos

Cada subagent puede leer como máximo 8 archivos y debe devolver solo hallazgos finales.
Al terminar, el agente padre fusiona duplicados, conflictos e incógnitas.

Evita La Hinchazón De Contexto

La regla simple es separar evidencia y decisiones. Archivos completos, logs largos y cien hits de búsqueda son evidencia demasiado pesada. Filtra primero y decide después.

La compaction de OpenAI es una función de API, pero el principio operativo también sirve aquí: conserva el resumen necesario y suelta el detalle viejo.

Comprime la investigación para que otra persona pueda continuar en menos de 300 palabras.
Conserva:
- Entrypoints confirmados
- Archivos high risk
- Límites que no deben cruzarse
- Hipótesis sin confirmar
- Siguiente comando a ejecutar

Descarta:
- Hipótesis ya descartadas
- Logs largos
- Archivos generados que no hay que leer

Las notas de handoff importan tanto en desarrollo como en operaciones de contenido. En artículos multilingües, anota qué locale files poseías. En una app, anota hasta qué entrypoint trazaste. En un bug, anota qué hipótesis fallaron. Combínalo con Claude Code Testing Strategies y la guía de approval y sandbox.

Tres Casos De Uso

Primero, handoff de un SaaS. El primer día mapea login, billing, admin y notificaciones. Encuentra importers de AuthService y BillingService, luego traza checkout desde la ruta hasta la base de datos. No edites todavía. El resultado debe ser un mapa de riesgo y un orden de lectura.

Segundo, migración legacy. Busca legacy, deprecated y migration antes de pedir código de reemplazo. Pregunta por riesgos de compatibilidad. Migraciones de base de datos, APIs públicas, jobs batch y cron merecen cuidado porque revertirlos cuesta.

Tercero, un sitio de contenido y monetización como ClaudeCodeLab. Artículos, componentes CTA, enlaces internos, productos y traducciones viven en carpetas distintas. Trabaja por slug. Pide al agente que posea solo un slug y use otros artículos solo para verificar enlaces. Eso hace más seguro el trabajo paralelo.

Fallos Frecuentes

• Confiar solo en el README. Los entrypoints reales suelen desviarse de documentación vieja.
• Tratar resultados de búsqueda como flujo de ejecución. Un hit es candidato, no prueba.
• Permitir edición antes de aclarar propiedad. El código puede correr y aun así fallar en review.
• Meter carpetas generadas, lockfiles, coverage o dist en la conversación.
• Pedir a subagents una investigación demasiado amplia.
• Decir “arregla de forma segura” sin definir high / medium / low.

CTA Para Equipos

Navegar codebases grandes también afecta ingresos. Checkout, formularios de leads, contenido pago, analytics y anuncios viven detrás de límites de riesgo. Un mapa antes de editar reduce retrabajo.

Si tu equipo adopta Claude Code o Codex, empieza con una plantilla de repo map, reglas en AGENTS.md/CLAUDE.md, criterios de review y prompts de exploración solo lectura. Para empezar individualmente, usa la cheat sheet gratuita. Para entrenamiento con repos reales, revisa Claude Code training and consulting.

Nota De Verificación Práctica

Cuando uso este flujo, los prompts de implementación posteriores son más estables que cuando empiezo pegando archivos grandes. Los artefactos más útiles son el repo map, los resultados de rg clasificados, una tabla pequeña de dependencias y el mapa high / medium / low. Cuando salto esos pasos, carpetas generadas, tests viejos y módulos de otros equipos entran en la conversación. Antes de publicar, revisé los comandos, prompts y script de Node para que fueran copiables y tuvieran estructura JavaScript válida.