Mapa de onboarding de repositorio para Claude Code: elegir la primera tarea segura

El primer día dentro de un repositorio existente decide si Claude Code ayuda o crea ruido. Pedir “mira todo y mejora lo que veas” parece eficiente, pero oculta alcance, riesgo y criterio de finalización.

Esta guía convierte los primeros 30 minutos en un mapa de onboarding. No es un documento de arquitectura enorme; es el mapa mínimo para elegir una primera tarea segura y útil.

Lecturas relacionadas: claude-code-getting-started-complete, claude-code-existing-codebase-map, claude-code-first-30-minutes-checklist. La base oficial de instalación está en Anthropic Claude Code getting started.

Por qué va antes del primer comando

El centro de este tema es orden de lectura, zonas protegidas, primera edición y pruebas. Claude Code puede avanzar rápido, pero si la primera entrada es demasiado amplia, diffs de poco valor, hipótesis viejas y formato sin impacto en ingresos reciben el mismo peso que el trabajo importante.

Para desarrolladores principiantes e intermedios que entran en un código existente, la meta no es hacer que la tarea parezca grande. La meta es definir qué leer, qué no tocar, qué probar primero y a dónde volver si falla. Esto aplica tanto a operaciones de contenido como a producto.

Flujo práctico

1. Leer primero solo README, package.json y una ruta principal
2. Escribir zonas protegidas antes de sugerir cambios
3. Elegir una tarea reversible como copy, CTA o nombre de test
4. Definir pruebas con build, diff y URL pública

Este orden cambia la petición de “piensa libremente” a “trabaja dentro de este límite y deja prueba”. Claude Code conserva espacio para razonar, pero las zonas peligrosas se cierran antes de la primera edición.

Situación	Movimiento seguro	Prueba a guardar
Sitio de contenido	Mejorar solo el CTA final de un artículo popular y verificar enlaces Gumroad	build, diff, URL
SaaS	Aclarar texto de settings sin tocar billing	build, diff, URL
Herramienta interna	Renombrar una columna CSV y probar con datos de muestra	build, diff, URL

Con esa prueba, Claude Code se evalúa por trabajo observable y no por una frase segura.

Prompt y código para copiar

Haz onboarding de este repositorio para una primera tarea con Claude Code. Lee solo README, package.json y rutas principales. Devuelve una tabla con zonas protegidas, primera tarea pequeña y comandos de prueba. No edites todavía.

const repoMap = {
  goal: "find one safe first task",
  readFirst: ["README.md", "package.json", "src/routes/"],
  protectedAreas: [".env", "billing/", "migrations/", "wrangler.toml"],
  firstTask: "improve one article CTA without touching payment code",
  proofCommands: ["npm.cmd run build", "git diff --stat"],
};

function readyForClaudeCode(map) {
  return map.readFirst.length >= 2 &&
    map.protectedAreas.length > 0 &&
    map.proofCommands.some((command) => command.includes("build"));
}

console.log({ ready: readyForClaudeCode(repoMap), firstTask: repoMap.firstTask });

El código es una comprobación pequeña. En un proyecto real, pega la salida en CLAUDE.md, un issue o una nota de handoff para reutilizar el mismo juicio en la siguiente sesión.

Ejemplos reales y fallos

Situación	Movimiento seguro	Prueba a guardar
Sitio de contenido	Mejorar solo el CTA final de un artículo popular y verificar enlaces Gumroad	build, diff, URL
SaaS	Aclarar texto de settings sin tocar billing	build, diff, URL
Herramienta interna	Renombrar una columna CSV y probar con datos de muestra	build, diff, URL

• Leer todo al principio consume tiempo en formato de baja señal.
• Sin zonas protegidas, billing, auth y deploy parecen editables.
• Sin comandos de prueba, la persona tiene que adivinar si el cierre es cierto.

El fallo común no es falta de capacidad de Claude Code. El límite de entrada era demasiado fino. Cuando el límite es fino, el asistente amplía la tarea para ayudar. En artículos monetizados, elegir entre PDF gratuito, Gumroad y consulta también forma parte del límite.

Llevar al lector al PDF, Gumroad y consulta

Si los comandos básicos aún cuestan, empieza con el cheatsheet gratuito. Si el bloqueo está en setup, permisos, CLAUDE.md, MCP o CI, el siguiente paso de pago es la Setup Guide. Si repites prompts de review, debugging o refactor, usa 50 Prompt Templates. Si hay adopción de equipo o ruta de ingresos, pasa a consulta. La comparación de productos empieza en products.

Un CTA no debe vivir solo al final. Cerca de la introducción, el PDF gratuito reduce fricción. Tras ejemplos de implementación, encaja Gumroad. Cuando aparece riesgo de equipo o producción, la consulta es el siguiente paso natural.

Métricas para mirar después de publicar

Después mira clics al PDF gratuito, clics a Setup Guide y visitas a /en/training/ desde este slug.

Después de publicar, separa PV, lectura del inicio, clics internos, registros al PDF gratuito, clics a Gumroad y visitas a consulta. HTTP 200 no basta. h1, canonical, heroImage, CTA y cuerpo localizado deben apuntar a la misma acción.