Checklist de los primeros 30 minutos con Claude Code

Los primeros 30 minutos deben crear confianza, no un parche enorme

La primera sesión con Claude Code suele fallar cuando el pedido es demasiado amplio. Un principiante pide una función completa, una limpieza general del código o un rediseño entero, y después no sabe si el diff generado es seguro. El objetivo correcto para los primeros 30 minutos es más pequeño: entender el repositorio, lograr una mejora verificable, guardar evidencia y dejar preparado el siguiente paso.

La descripción oficial de Claude Code explica que la herramienta puede leer el codebase, editar archivos, ejecutar comandos e integrarse con herramientas de desarrollo. Esa potencia exige límites claros. En la primera sesión no necesitas demostrar que puede hacerlo todo; necesitas demostrar que puede trabajar dentro de una tarea pequeña y revisable.

Esta checklist se complementa con First Task Runbook, Repo Map First Pass, Session Handoff Template y Verification Receipt Workflow. Úsalos cuando quieras convertir esta primera sesión en un proceso repetible.

Conceptos básicos antes de empezar

Un repositorio es la carpeta del proyecto: código, tests, configuración, scripts y documentación. Un agente es la parte que puede investigar, editar, ejecutar comandos y proponer verificaciones. Los permisos son las reglas de seguridad que definen qué puede leer, modificar o ejecutar Claude Code. La documentación oficial de permissions explica reglas allow, ask y deny, además de los modos de aprobación.

CLAUDE.md es una guía de proyecto. Ahí puedes guardar estándares de código, decisiones de arquitectura, comandos de build, comandos de test y criterios de review. La guía oficial de memory ayuda a entender cómo las instrucciones del proyecto y la memoria hacen más estables las sesiones siguientes.

Verificar significa tener una prueba repetible. Puede ser npm run build, un test que pasa, una captura de pantalla, una revisión de logs o una nota que diga qué no se pudo comprobar. Un diff plausible no es suficiente. Antes de editar, define cuál será la prueba.

Qué debería existir después de 30 minutos

Resultado	Contenido	Por qué importa
Mapa del repo	Entradas, directorios importantes, comandos y zonas de riesgo	Evita editar a ciegas
Victoria pequeña	Un diagnóstico, un enlace corregido, un test explicado o una reproducción	Mantiene el cambio revisable
Nota de verificación	Comandos ejecutados, resultado y dudas restantes	Permite repetir la prueba
Siguiente paso	La tarea útil más pequeña	Acelera la segunda sesión

No estás renunciando a cambios grandes. Solo estás evitando que el primer contacto mezcle exploración, edición y verificación sin orden.

Minutos 0 a 5: pedir contexto, no implementación

La primera petición debe ser de solo lectura. Sirve para comprobar si Claude Code entiende el proyecto antes de tocar archivos.

Read this repository and tell me:
1. the main entry points
2. the commands I will probably need
3. the risky directories I should avoid first
4. the safest high-value first task for a 30-minute session

Do not edit files yet. Give me a short plan and the proof command you would run.

Este prompt obliga a identificar entradas, comandos, zonas peligrosas y una primera tarea razonable. Los common workflows oficiales siguen la misma lógica: explorar, planear, implementar y verificar. Los primeros cinco minutos se usan para leer, no para escribir.

Minutos 5 a 20: elegir un caso de onboarding

El primer caso práctico es explicar un test fallido. Pide que identifique el test, el valor esperado, el valor real y el archivo más probable. No pidas la corrección hasta que el fallo esté descrito con evidencia.

El segundo caso es una actualización pequeña de contenido o CTA. En un sitio monetizado, puede ser confirmar que el enlace de producto apunta a /products/, que la consulta apunta a /training/ y que el texto explica por qué el lector debería hacer clic. Es una tarea pequeña con valor de negocio claro.

El tercer caso es convertir un bug vago en una reproducción. “El dashboard falla a veces” no es una tarea. Una buena primera sesión lo convierte en entorno, pasos, resultado esperado, resultado real, logs y archivos candidatos.

El cuarto caso es crear un CLAUDE.md mínimo. No escribas un manual completo de equipo. Empieza con comandos prohibidos, comandos de build, comandos de test, estilo y evidencias de review. Cuando eso deba convertirse en configuración compartida, revisa la documentación oficial de settings.

Scripts listos para copiar y ejecutar

En macOS, Linux o WSL, ejecuta esto desde la raíz del repositorio. Lee estado y no modifica archivos.

#!/usr/bin/env bash
set -euo pipefail

echo "== location =="
pwd

echo "== git status =="
git status --short

echo "== package scripts =="
if [ -f package.json ]; then
  node -e "const p=require('./package.json'); console.log(p.scripts || {})"
else
  echo "package.json not found"
fi

echo "== likely docs =="
find . -maxdepth 2 \( -name 'README*' -o -name 'CLAUDE.md' -o -name 'AGENTS.md' \) -print

echo "== recent changed files =="
git diff --name-only

En Windows PowerShell, usa esta versión.

$ErrorActionPreference = "Stop"

Write-Host "== location =="
Get-Location

Write-Host "== git status =="
git status --short

Write-Host "== package scripts =="
if (Test-Path package.json) {
  node -e "const p=require('./package.json'); console.log(p.scripts || {})"
} else {
  Write-Host "package.json not found"
}

Write-Host "== likely docs =="
Get-ChildItem -Force -File -Include README*,CLAUDE.md,AGENTS.md -Recurse -Depth 2 |
  Select-Object -ExpandProperty FullName

Write-Host "== recent changed files =="
git diff --name-only

Para una nota de handoff repetible, guarda esto como first-30-handoff.mjs, edita los valores y ejecuta node first-30-handoff.mjs.

const handoff = {
  outcome: "Adjusted one CTA sentence and confirmed the product/training links stayed visible.",
  verified: ["git status --short", "npm run build"],
  notVerified: ["Mobile visual check"],
  nextStep: "Open the page locally and inspect the CTA area at 390px width.",
};

for (const [label, value] of Object.entries(handoff)) {
  const body = Array.isArray(value) ? value.map((item) => `- ${item}`).join("\n") : value;
  console.log(`## ${label}\n${body}\n`);
}

Una configuración inicial de permisos debería ser conservadora. Este ejemplo es JSON válido; ajusta los comandos al proyecto real.

{
  "permissions": {
    "allow": [
      "Bash(git status *)",
      "Bash(npm run build)",
      "Bash(npm test *)"
    ],
    "deny": [
      "Bash(git push *)",
      "Read(./.env)",
      "Read(./.env.*)"
    ]
  }
}

Errores concretos que conviene evitar

El primer error es pedir “arregla todo”. Esa frase no tiene alcance ni criterio de éxito. Cámbiala por “explica un test fallido” o “actualiza un bloque CTA y verifica los enlaces”.

El segundo error es usar permisos demasiado amplios en un árbol de trabajo normal. Los modos fuertes pueden servir en contenedores o entornos aislados, pero un principiante debería empezar con lectura, confirmación de ediciones y reglas deny para secretos o acciones destructivas. Si el proyecto contiene credenciales o datos privados, lee la documentación oficial de security.

El tercer error es no ejecutar ninguna prueba. Una explicación convincente no reemplaza un receipt de verificación. Decide si la prueba será npm run build, tests, parseo JSON, revisión visual o captura de pantalla.

El cuarto error es cerrar sin handoff. Si no guardas qué cambió, qué se verificó, qué falta y cuál es el siguiente paso, la próxima sesión repetirá la exploración.

Siguiente paso y ruta de conversión

Para practicar solo, empieza por la cheatsheet gratis y usa los prompts seguros como rutina. Si quieres plantillas reutilizables, ejemplos de CLAUDE.md y checklists de review, revisa ClaudeCodeLab products. Si tu equipo necesita permisos, hooks, recibos de verificación y formación de adopción, usa Claude Code training and consultation.

Al probar este flujo en un repositorio real, lo más valioso no fue el script, sino el hábito de pedir un mapa antes de editar y cerrar con git status --short. Nota japonesa del artículo: 実際に試した結果, una primera tarea pequeña hizo el diff más confiable y dejó una segunda sesión de Claude Code mucho más limpia.