Onboarding de desarrolladores con Claude Code: de meses a 2 semanas

El onboarding de un nuevo ingeniero no termina al entregar un portátil. Consiste en llevar a la persona desde “puedo abrir el repositorio” hasta “puedo enviar un cambio pequeño, revisable y alineado con las reglas del equipo”. Lo que suele retrasar el proceso son las preguntas repetidas de setup, un codebase enorme, criterios de revisión poco claros y conocimiento tribal que solo vive en la cabeza de los veteranos.

Claude Code no debe sustituir al mentor. Su mejor uso es crear una base segura: instrucciones en CLAUDE.md, un script de setup repetible, reglas de permisos, checklist para la primera tarea, plantilla de PR y una forma clara de leer CI. En términos sencillos, el codebase es todo el código fuente de la aplicación, un PR es una solicitud de revisión, y CI es el sistema que ejecuta tests y builds antes de fusionar cambios.

Como Claude Code cambia con el tiempo, usa la documentación oficial como fuente principal: Claude Code setup, CLI reference, memory y settings. Para ampliar, revisa navegación de codebase, code review con Claude Code y plantillas CLAUDE.md.

flowchart LR
  A["Day 1: setup"] --> B["Day 2: codebase map"]
  B --> C["Day 3-5: first task"]
  C --> D["Week 2: PR review"]
  D --> E["Retrospective and docs update"]

1. Empezar por CLAUDE.md

CLAUDE.md es la memoria de proyecto que Claude Code lee como instrucciones compartidas. Para onboarding, no lo llenes de frases abstractas. Escribe comandos, límites y reglas de escalado.

cat > CLAUDE.md <<'EOF'
# Project instructions for Claude Code

## Goal
Help new engineers make small, reviewable changes without bypassing tests or team rules.

## Daily commands
- Install: npm ci
- Type check: npm run typecheck
- Unit tests: npm test -- --runInBand
- Lint: npm run lint
- Build: npm run build

## Boundaries
- Do not edit files under migrations/ without human approval.
- Do not read .env, .env.*, secrets/, or production credentials.
- Do not push, commit, deploy, or publish packages.
- Prefer small diffs under 150 lines for first tasks.

## First PR rules
- Explain the intent before editing.
- Reuse existing patterns before adding dependencies.
- Add or update tests for behavior changes.
- Include command output in the PR description.

## When stuck
Ask the engineer to provide:
1. What they tried
2. The exact error
3. The file or command involved
4. What Claude Code inferred and what still needs human judgment
EOF

El objetivo no es convertir a Claude Code en un senior mágico. Es reducir el alcance para que la nueva persona aprenda el estándar del equipo y produzca un diff revisable.

2. Hacer repetible el setup

El primer bloqueo suele ser la versión de Node, dependencias, variables locales, datos de prueba y el comando que demuestra que todo funciona. Un script lo convierte en una ruta clara.

mkdir -p scripts
cat > scripts/onboarding-setup.sh <<'EOF'
#!/usr/bin/env bash
set -euo pipefail

echo "== Checking required tools =="
node --version
npm --version
git --version

if ! command -v claude >/dev/null 2>&1; then
  echo "Claude Code is not installed."
  echo "Install with: npm install -g @anthropic-ai/claude-code"
  exit 1
fi

echo "== Installing dependencies =="
npm ci

if [ ! -f .env ] && [ -f .env.example ]; then
  cp .env.example .env
  echo "Created .env from .env.example. Fill in local-only values before running the app."
fi

echo "== Running baseline checks =="
npm run lint
npm run typecheck
npm test -- --runInBand

echo "== Ask Claude Code for a local map =="
claude -p "Read README.md, package.json, and CLAUDE.md. Explain how to start this project locally, which checks just ran, and what a new engineer should verify before opening the first PR."
EOF
chmod +x scripts/onboarding-setup.sh

En un proyecto npm típico se puede copiar y ejecutar. Si tu equipo usa pnpm, Yarn, Docker Compose o Makefile, cambia los comandos, pero conserva la idea: una ruta de setup, una verificación y una explicación generada por Claude Code.

3. Añadir permisos seguros

Claude Code puede leer archivos, buscar código, ejecutar comandos y editar cuando se le permite. Eso ayuda, pero también puede exponer .env, ejecutar comandos peligrosos o producir cambios demasiado grandes. Declara lo permitido, lo que debe preguntar y lo prohibido.

mkdir -p .claude
cat > .claude/settings.json <<'EOF'
{
  "permissions": {
    "allow": [
      "Read",
      "Grep",
      "Glob",
      "Bash(git status:*)",
      "Bash(git diff:*)",
      "Bash(git log:*)",
      "Bash(npm run lint)",
      "Bash(npm run typecheck)",
      "Bash(npm test:*)"
    ],
    "ask": [
      "Edit",
      "Write",
      "Bash(npm install:*)",
      "Bash(git checkout:*)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)",
      "Bash(git push:*)",
      "Bash(git commit:*)",
      "Bash(rm:*)",
      "Bash(curl:*)",
      "Bash(npm publish:*)"
    ]
  }
}
EOF

Durante la primera semana conviene permitir lectura, búsqueda, diff, log y tests. Las ediciones pueden pedir confirmación. Push, commit, deploy, publish y secretos deben quedar fuera del camino de onboarding.

4. Fijar el checklist del primer PR

El primer PR es una práctica de trabajo en equipo. Buenos candidatos: añadir un test a comportamiento existente, corregir un texto pequeño, mejorar un mensaje de error o limpiar duplicación en una carpeta. Malos candidatos: autenticación, pagos, permisos, migraciones, formateo masivo y upgrades de dependencias.

mkdir -p docs/onboarding
cat > docs/onboarding/first-task-checklist.md <<'EOF'
# First task checklist

## Before editing
- [ ] I can run `npm ci`.
- [ ] I can run `npm run lint`.
- [ ] I can run `npm run typecheck`.
- [ ] I can run the nearest test for the area I will touch.
- [ ] I understand the user-visible behavior being changed.

## Good first task examples
- [ ] Add a missing unit test around existing behavior.
- [ ] Fix a small UI copy typo with screenshot evidence.
- [ ] Replace duplicated helper logic in one folder.
- [ ] Improve one error message without changing API contracts.

## Not good for the first task
- [ ] Authentication, billing, permissions, or migrations.
- [ ] Broad formatting changes.
- [ ] Dependency upgrades.
- [ ] Refactors across multiple packages.

## PR evidence
- [ ] Summary of the change.
- [ ] Test commands and results.
- [ ] Screenshot or log if behavior changed.
- [ ] Open question for reviewer, if any.
EOF

Este flujo cubre casos reales: setup autónomo, lectura del codebase, selección de primera tarea y auto-revisión antes de abrir PR.

5. Estandarizar la solicitud de revisión

Muchos primeros PR vuelven porque el revisor no ve qué se comprobó. La plantilla obliga a escribir intención, seguridad, verificación y foco de revisión.

mkdir -p .github
cat > .github/pull_request_template.md <<'EOF'
## Summary
- TODO

## Why this is safe for a first PR
- Scope:
- Files changed:
- Behavior changed:

## Verification
- [ ] `npm run lint`
- [ ] `npm run typecheck`
- [ ] `npm test -- --runInBand`

## Claude Code self-review prompt used
Ask Claude Code:
"Review git diff origin/main...HEAD for naming, tests, security, and consistency with CLAUDE.md. Return only actionable issues."

## Reviewer focus
- TODO

## Screenshots or logs
- TODO
EOF

También ayuda al mentor: queda claro si debe revisar diseño, tests, comportamiento, capturas o el proceso de trabajo.

6. Enseñar CI desde el primer día

CI significa integración continua. Es el sistema que ejecuta checks antes de fusionar un PR. La persona nueva debe aprender a reproducir un fallo localmente, no solo mirar una marca roja.

name: onboarding-checks

on:
  pull_request:
    branches: [main]

jobs:
  verify:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: "20"
          cache: "npm"
      - run: npm ci
      - run: npm run lint
      - run: npm run typecheck
      - run: npm test -- --runInBand
      - run: npm run build

Aunque uses otro CI, documenta los mismos comandos. Luego pide a Claude Code que lea el log fallido y diga cuál es el primer comando local que conviene ejecutar.

Errores comunes

El primero es delegar juicio de negocio en Claude Code. Puede inferir desde código e historial, pero compromisos con clientes, excepciones y cumplimiento siguen siendo decisión humana.

El segundo es hacer demasiado grande el primer PR. Mantén el cambio por debajo de 150 líneas cuando sea posible, con tests y fácil de revertir.

El tercero es exponer secretos. Bloquea .env, credenciales y archivos de producción en settings, y usa solo valores de ejemplo en docs.

El cuarto es prohibir preguntas humanas. “Pregunta primero a Claude” funciona solo si durante las dos primeras semanas hay contacto frecuente con el mentor.

CTA

Para un equipo, estandariza juntos CLAUDE.md, permisos, evidencia de PR y CI. Si trabajas solo, empieza con la cheatsheet gratuita. Para plantillas reutilizables, revisa ClaudeCodeLab products. Para formación, permisos y adopción en repos reales, usa Claude Code training and consultation.

Resultado al probarlo

En trabajos de contenido de ClaudeCodeLab y cambios pequeños de código, el salto de calidad vino de escribir las reglas antes de pedir implementación. Con CLAUDE.md, permisos limitados, comandos de verificación y plantilla de PR, el diff fue mucho más fácil de revisar. Cuando Claude Code se equivocó, las suposiciones y comandos guardados hicieron sencillo encontrar el malentendido.