Llevo meses usando Claude Code como herramienta principal de desarrollo. Ocho horas al dia, minimo. Y ayer me di cuenta de que no conocia ni una fraccion de lo que el CLI puede hacer.

Este post es la guia que me hubiera gustado tener el primer dia. No es la documentacion oficial reescrita: es lo que de verdad uso y lo que deberia haber usado antes.

Lo basico que ya sabias (o no)

Invocar Claude

claude                    # Modo interactivo (REPL)
claude "explica este bug" # Prompt directo, responde y sale
claude -p "prompt"        # Print mode: responde a stdout, sin interactividad
claude -r                 # Resume: continua la ultima conversacion
claude -c                 # Continue: continua la ultima conversacion en modo interactivo

La diferencia entre -r y -c es sutil pero importante. -r es "resume" (retoma contexto, modo interactivo). -c es "continue" (retoma la ultima conversacion). En la practica, -c es el que mas uso: "eh, sigue con lo de antes".

El stdin es tu amigo

Esto cambia todo. Puedes pipear cualquier cosa a Claude:

cat error.log | claude "que ha pasado aqui"
git diff | claude "revisa estos cambios"
curl -s https://api.example.com/status | claude "resume esto"
git log --oneline -20 | claude "que hemos hecho esta semana"

Claude recibe el stdin como contexto adicional antes de tu prompt. Esto convierte cualquier comando Unix en un prompt de IA.

Output estructurado

claude -p "genera 3 nombres de proyecto" --output-format json
claude -p "analiza este codigo" --output-format stream-json

stream-json es especialmente util para integraciones: emite objetos JSON parciales mientras piensa, ideal para UIs que quieran mostrar progreso.

Y si necesitas un schema especifico:

claude -p "extrae los campos" --output-format json \
  --json-schema '{"type":"object","properties":{"name":{"type":"string"},"version":{"type":"string"}}}'

Los slash commands que no conocias

Dentro del REPL interactivo, los slash commands son el poder oculto. Todo el mundo conoce /help. Pocos conocen el resto.

Gestion de contexto

/compact es critico para sesiones largas. Claude tiene una ventana de contexto finita. Cuando se llena, comprime automaticamente, pero puedes forzarlo cuando quieras. El truco: dale instrucciones. /compact conserva los nombres de archivo y las decisiones de arquitectura es mucho mejor que /compact a secas.

Modelos y configuracion

/model sin argumentos te muestra las opciones. Puedes cambiar entre Opus (potente, lento), Sonnet (equilibrado) y Haiku (rapido, barato) segun la tarea. Para un refactor complejo: Opus. Para formatear imports: Haiku.

MCP (Model Context Protocol)

MCP es lo que le da superpoderes a Claude Code. Es un protocolo que permite conectar herramientas externas. Nosotros lo usamos para conectar nuestro blog: Claude puede listar posts, publicar, editar y borrar directamente desde el REPL. Pero puedes conectar bases de datos, APIs, sistemas de archivos remotos…

La configuracion va en ~/.claude/settings.json:

{
  "mcpServers": {
    "mi-servidor": {
      "type": "sse",
      "url": "https://mi-api.dev/mcp/sse"
    }
  }
}

O para servidores locales (stdio):

{
  "mcpServers": {
    "sqlite": {
      "command": "npx",
      "args": ["-y", "@anthropic-ai/mcp-server-sqlite", "mi-db.sqlite"]
    }
  }
}

El que te va a volar la cabeza: /remote

Nuevo en 2.1.59. /remote (o /rc) genera un codigo QR en la terminal. Lo escaneas con el movil y controlas tu sesion de Claude Code desde el navegador del telefono.

Caso de uso real: estas en el sofa, el ordenador esta en el escritorio. Claude esta compilando algo. Escaneas el QR, ves el progreso, mandas el siguiente comando desde el movil. Sin levantarte.

Flags de la CLI que cambian el juego

Sesiones con nombre

claude --session-id "refactor-auth"   # Crea/retoma sesion con nombre
claude --no-session-persistence       # Sesion efimera (no se guarda)

Las sesiones con nombre son oro para pipelines. Puedes tener una sesion para cada tarea, volver a ella cuando quieras, y no mezclar contextos. En n8n usamos --session-id para mantener estado entre pasos de un workflow.

Control de herramientas

claude --allowedTools "Read,Write,Edit,Glob,Grep"  # Solo estas herramientas
claude --disallowedTools "Bash"                      # Todo menos Bash

Util para restringir que puede hacer Claude en entornos automatizados. Si solo quieres que lea y analice sin modificar nada: --allowedTools "Read,Glob,Grep".

El flag mas peligroso (y util)

claude --dangerously-skip-permissions

Desactiva TODAS las confirmaciones de permisos. Claude ejecuta todo sin preguntar. Obviamente, solo para entornos controlados (CI/CD, scripts automaticos). En produccion, ni de broma.

El sistema de permisos

Claude Code tiene un sistema de permisos granular que pocos configuran bien.

Niveles de confianza

En settings.json puedes definir que herramientas se auto-aprueban:

{
  "permissions": {
    "allow": [
      "Read",
      "Glob",
      "Grep",
      "WebSearch",
      "WebFetch",
      "mcp__mi-servidor__*"
    ],
    "deny": []
  }
}

Los permisos soportan wildcards. mcp__mi-servidor__* auto-aprueba todas las herramientas de un servidor MCP especifico.

Permisos por proyecto

Puedes tener un .claude/settings.json en cada proyecto con permisos especificos. Los del proyecto se fusionan con los globales. Asi un proyecto puede tener acceso a su base de datos MCP sin dar ese acceso a todos los proyectos.

Skills: plugins de la comunidad

Las skills son como plugins: anaden capacidades especificas a Claude Code. Son directorios con un SKILL.md que Claude lee como instrucciones.

Donde viven

• ~/.claude/skills/ - Skills globales
• .claude/skills/ - Skills del proyecto

Ejemplos de skills utiles

• pdf - Genera PDFs desde la conversacion
• commit - Hace commits con mensajes bien escritos
• review-pr - Revisa pull requests con checklist
• tdd-workflow - Ciclo TDD guiado

Se invocan con slash: /pdf, /commit, /review-pr.

Crear tus propias skills

Una skill es un directorio con al menos un SKILL.md:

~/.claude/skills/mi-skill/
  SKILL.md      # Instrucciones para Claude
  template.txt  # (opcional) plantillas, assets

El SKILL.md contiene instrucciones en lenguaje natural que Claude sigue cuando invocas la skill. Es literalmente un prompt especializado. Nada de codigo, nada de APIs: solo texto que le dice a Claude que hacer.

Nosotros tenemos skills propias para nuestro workflow: /dejavu (protocolo anti-amnesia entre sesiones), /checkup (diagnostico rapido de las maquinas), /preteleport (preparar contexto antes de saltar entre maquinas).

Hooks: automatizacion reactiva

Los hooks ejecutan comandos shell en respuesta a eventos de Claude Code. Se configuran en settings.json:

{
  "hooks": {
    "preToolCall": [
      {
        "matcher": "Write|Edit",
        "command": "echo 'Modificando archivo...'"
      }
    ],
    "postToolCall": [
      {
        "matcher": "Write",
        "command": "prettier --write $FILE_PATH"
      }
    ],
    "afterError": [
      {
        "command": "notify-send 'Claude Code' 'Error detectado'"
      }
    ]
  }
}

Eventos disponibles:

• preToolCall - Antes de ejecutar una herramienta (puedes bloquearlo devolviendo exit code != 0)
• postToolCall - Despues de ejecutar una herramienta
• afterError - Cuando algo falla

Caso de uso real: un hook preToolCall que bloquea escrituras en .env o archivos con secretos. Otro que ejecuta prettier automaticamente despues de cada Write.

Agentes especializados (Task tool)

Claude Code puede lanzar sub-agentes para tareas complejas. No son plugins: son instancias de Claude con herramientas especificas y un rol definido.

Agentes nativos

Agentes personalizados

Se definen en ~/.claude/agents/ o .claude/agents/ con archivos YAML. Un agente tiene: nombre, descripcion, herramientas disponibles, instrucciones, y opcionalmente un modelo preferido.

Nosotros tenemos agentes para cada dominio: chema para redes y seguridad, nixos-guru para configuracion NixOS, cohete-expert para el blog… Cada uno con su personalidad y herramientas.

El fichero CLAUDE.md

El CLAUDE.md es el cerebro persistente de Claude Code en un proyecto. Se carga automaticamente al inicio de cada conversacion. Hay tres niveles:

Es el sitio para poner: convenciones del proyecto, patrones arquitectonicos, cosas que Claude debe saber siempre (ej: "nunca uses jQuery", "los tests van en __tests__/", "el deploy es con Terraform").

Memory: Claude recuerda entre sesiones

La memoria automatica (/memory) permite a Claude guardar notas persistentes entre sesiones. No es magia: son archivos markdown en ~/.claude/projects/*/memory/.

Que guarda:

• Patrones confirmados del proyecto
• Decisiones arquitectonicas
• Preferencias de workflow
• Soluciones a problemas recurrentes

Que NO guarda (o no deberia):

• Estado temporal de la sesion
• Datos sin verificar
• Lo que ya esta en CLAUDE.md

La gracia es que Claude decide solo que merece guardarse. Si algo le parece importante y recurrente, lo apunta. Puedes pedirle explicitamente: "recuerda que siempre usamos bun" y lo guardara.

Atajos de teclado en el REPL

El Escape doble (rapido) es el mas util: para la generacion en seco y puedes redirigir a Claude sin esperar a que termine.

Tips avanzados que ojala hubiera sabido antes

1. Claude lee imagenes

claude "que ves en esta captura" < screenshot.png
# O dentro del REPL, arrastra una imagen a la terminal

Funciona con PNG, JPG, GIF. Util para debugging visual: "por que este CSS se ve roto?" con una captura del bug.

2. Git integration nativa

Claude entiende git de forma nativa. No necesitas explicarle el estado del repo:

> que he cambiado desde el ultimo commit?
> haz commit con un mensaje descriptivo
> crea un PR con todo lo que llevo en esta rama

Lee git diff, git log, git status automaticamente. Los commits los hace con formato convencional y anade co-author.

3. El plan mode

Antes de implementar algo complejo, Claude puede entrar en "plan mode": explora el codebase, disena una estrategia, te la presenta para aprobar, y solo entonces ejecuta. Es la diferencia entre "hazlo" y "piensalo y luego hazlo".

Se activa automaticamente cuando Claude detecta que la tarea es no trivial, pero puedes forzarlo: "planifica primero como harias X".

4. Parallel tool calls

Claude puede ejecutar varias herramientas en paralelo. Si necesita leer 5 archivos, los lee todos a la vez, no uno por uno. Esto aplica tambien a sub-agentes: puede lanzar 3 investigaciones en paralelo y combinar resultados.

No necesitas hacer nada especial: Claude optimiza automaticamente.

5. El context window se comprime solo

Cuando la conversacion se acerca al limite de contexto, Claude comprime automaticamente los mensajes anteriores en un resumen. No pierdes informacion critica: preserva decisiones, archivos modificados y estado actual.

Pero es mejor no depender de esto. Si una sesion se alarga mucho, usa /compact proactivamente con instrucciones de que conservar.

6. Multiples conversaciones en paralelo

Puedes tener varias terminales con Claude Code corriendo simultaneamente en el mismo proyecto. Cada una tiene su propio contexto. Util para: investigar en una terminal mientras implementas en otra.

Para pipelines y automatizacion

# CI: revisar PR automaticamente
git diff main..HEAD | claude -p "revisa estos cambios, busca bugs" --output-format json

# Generar documentacion
claude -p "genera docstrings para todas las funciones publicas" \
  --allowedTools "Read,Glob,Grep,Edit" \
  --dangerously-skip-permissions

# Traducir archivos
cat README.md | claude -p "traduce a espanol, mantiene formato markdown"

# Analisis de logs
tail -1000 /var/log/app.log | claude -p "resume los errores criticos de las ultimas 24h"

El patron -p + pipe + --output-format convierte a Claude Code en un componente mas de tu toolchain Unix.

Lo que falta (o lo que viene)

Claude Code evoluciona rapido. Entre la version 2.1.47 y la 2.1.59 (12 versiones en menos de una semana) anyadieron /remote, mejoraron el MCP, y pulieron decenas de cosas.

Lo que me gustaria ver:

• Mejor soporte para sesiones distribuidas (poder retomar desde otra maquina de forma nativa)
• Plugins con estado (skills que recuerden cosas entre invocaciones)
• Integracion mas profunda con editores (Emacs, Neovim)

Pero honestamente, ya es la herramienta mas potente que he usado para desarrollo. El truco esta en conocerla bien. Espero que esta guia ayude a eso.

—

Esta guia esta viva. La iremos actualizando con cada version nueva que traiga features interesantes. Si hay algo que me he dejado, los comentarios estan abiertos.