Cómo iniciar un proyecto con Claude Code

Guía rápida para desarrolladores que quieren arrancar un proyecto de forma ordenada y sacarle el máximo provecho a Claude Code.

Este artículo no pretende ser una guía exhaustiva — es mi guía de bolsillo personal. La escribí para consultarla cada vez que inicio un proyecto nuevo y no querer recordar de memoria qué pasos seguir. Si te sirve a ti también, genial.

Fuente: Claude Code Advanced de Javier Rayon.

Paso 1 — Pre-Setup: prepara el terreno

Antes de escribir una sola línea de código, pídele a Claude que configure la estructura del proyecto.

Prompt:

Estoy comenzando un proyecto de [descripción]. Antes de programar, ayúdame a crear:
- Estructura de directorios
- CLAUDE.md con convenciones
- Scripts de desarrollo (dev, test, build)
- Configuración de linting y formateo

Claude generará algo así:

my-project/
- src/
    - routes/
    - services/
    - models/
    - utils/
- tests/
- scripts/
- .claude/
    - settings.json
    - CLAUDE.md
    - rules/
        - testing.md
        - api-patterns.md
        - security.md
    - skills/
        - deploy/skill.md
        - db-migrate/skill.md
    - agents/
        - reviewer.md
        - qa.md
    - commands/
        - COMMANDS.md

Cada carpeta tiene un propósito claro:

• rules/ — lo que Claude siempre debe respetar (frameworks, patrones, seguridad)
• skills/ — procedimientos reutilizables (deploy, migraciones)
• agents/ — roles especializados (revisor de código, QA)
• commands/ — comandos slash personalizados (/deploy, /migrate)

Ejemplo de regla (.claude/rules/testing.md):

# Reglas de Testing
- Framework: vitest (NUNCA jest)
- Convención de nombres: *.test.ts
- Toda función pública debe tener al menos una prueba

Ejemplo de skill (.claude/skills/deploy/skill.md):

# Desplegar a Producción
1. Ejecutar pruebas: `npm test`
2. Compilar: `npm run build`
3. Verificar que no haya cambios sin commit
4. Ejecutar: `./scripts/deploy.sh production`

Agrega .claude/worktrees/ a tu .gitignore desde el inicio.

Paso 2 — Plan: define qué vas a construir

Con el proyecto configurado, entra en modo planificación antes de tocar código.

/plan

Claude analizará el problema y presentará un plan detallado sin modificar nada todavía. Tú revisas, ajustas y le das luz verde.

Prompt vago (evitar):

Build a login system

Prompt específico (usar):

Plan an OAuth2 login implementation (Google and GitHub).
Requirements:
- JWT with refresh tokens
- 24h expiration
- Rate limiting of 5 attempts per minute
- E2E tests with Playwright

Técnica avanzada — revisión cruzada:

Usa dos sesiones de Claude en paralelo:

• Sesión A genera el plan completo.
• Sesión B lo revisa con este prompt:

Revisa este plan como si fueras un Staff Engineer.
Busca puntos débiles, casos límite no considerados
y dependencias faltantes.

Ajusta el plan con el feedback de la Sesión B antes de ejecutar.

Paso 3 — Worktrees: ejecuta en paralelo

Con el plan listo, identifica 3 a 5 tareas que puedan avanzar simultáneamente y crea un worktree para cada una.

Opción A — Worktrees manuales (control total):

git worktree add -b feature/auth ../wt-auth main
git worktree add -b feature/api ../wt-api main
git worktree add -b test/e2e ../wt-tests main

Luego lanza Claude en cada uno:

# Terminal 1
cd ../wt-auth && claude

# Terminal 2
cd ../wt-api && claude

# Terminal 3
cd ../wt-tests && claude

Opción B — Worktrees nativos de Claude (más rápido):

claude --worktree auth-feature

Claude crea la rama, el directorio y la sesión en un solo paso. Al terminar, limpia automáticamente si no hubo cambios.

Flujo de cierre:

# Cada worktree hace commit y crea su PR
git add . && git commit -m "feat: auth OAuth2"
gh pr create --title "Auth OAuth2" --body "Descripción"

# Al terminar todos, limpia
git worktree remove ../wt-auth
git worktree prune

Tip: Si en lugar de tareas puntuales necesitas cambios masivos en todo el proyecto (por ejemplo, migrar 50 archivos), usa /batch en lugar de worktrees manuales — Claude los gestiona automáticamente.

Resumen