Guía completa de Claude Code 2026: de la instalación a los agentes de código autónomos

Claude Code no es autocompletado: es un agente de programación que vive en tu terminal. Lee tu repositorio completo, planifica cambios entre archivos, ejecuta comandos, corre pruebas, corrige sus propios fallos e itera hasta terminar el trabajo. Bien usado, se siente como delegar a un ingeniero junior veloz que nunca duerme. Usado sin cuidado, produce disparates seguros de sí mismos a una velocidad impresionante. Esta guía te lleva de la instalación a flujos genuinamente autónomos: CLAUDE.md como memoria del proyecto, servidores MCP que le dan herramientas a Claude, hooks que aplican tus reglas automáticamente y subagentes que paralelizan trabajo real, terminando con un proyecto completo trabajado.

Instalación y primera ejecución

Claude Code requiere Node.js 18 o más reciente. Instálalo globalmente, verifica y lánzalo dentro de un proyecto:

# Install (macOS, Linux, WSL)
npm install -g @anthropic-ai/claude-code

# Verify
claude --version

# Start it inside your project
cd my-project
claude

En el primer inicio, Claude Code te guía por la autenticación: inicia sesión con una suscripción de Claude (Pro o Max) o conecta una clave de API de Anthropic para facturación por uso. Los equipos suelen preferir la API o un plan Teams para llevar el control del uso. Dos comandos para aprender de inmediato:

• /init — escanea tu repo y genera un CLAUDE.md inicial.
• /clear — reinicia el contexto de la conversación. Úsalo cada vez que cambies de tarea; un contexto contaminado es la causa número uno de comportamientos extraños.

CLAUDE.md: la memoria del proyecto

CLAUDE.md es un archivo Markdown que Claude lee al inicio de cada sesión. Es donde codificas todo lo que le dirías a un recién contratado en su primer día: stack, comandos, convenciones y los campos minados. Mantenlo corto, factual y específico: los consejos vagos se ignoran, los datos precisos se usan. Un buen punto de partida:

# Project: Acme Storefront

## Stack
- Next.js 15 (App Router), TypeScript strict mode
- PostgreSQL via Prisma. Redis for sessions.
- Tests: Vitest + Playwright

## Commands
- Dev server: npm run dev
- Tests: npm run test (ALWAYS run before finishing a task)
- Lint: npm run lint
- Typecheck: npm run typecheck

## Conventions
- All money values are integer cents. Never floats.
- API routes live in src/app/api, services in src/server
- No default exports. Named exports only.

## Do not touch
- /prisma/migrations (append only, never edit old ones)
- .env files. If a task needs a new variable, tell me.

Puedes anidar archivos CLAUDE.md en subdirectorios para monorepos: Claude lee los que son relevantes para los archivos en los que trabaja. Tus preferencias personales (estilo de editor, qué tan detalladas deben ser las respuestas) van en ~/.claude/CLAUDE.md, que se aplica en todas partes.

El flujo de trabajo que sí funciona

1. Planifica antes de codificar. Pide a Claude que explore y proponga un plan primero: "Lee el módulo de autenticación y dame un plan paso a paso para agregar restablecimiento de contraseña. Todavía no escribas código". Revisa el plan como un líder técnico.
2. Ejecuta en pasos pequeños. Una tarea del tamaño de un commit por sesión: implementa, prueba, revisa el diff.
3. Haz que las pruebas sean el contrato. "Terminado" significa que la suite de pruebas pasa. Si no hay pruebas para lo que cambiaste, pide a Claude que las escriba primero.
4. Revisa cada diff. La autonomía se gana repositorio a repositorio. Hasta confiar en la configuración, lee los cambios línea por línea: así también aprendes qué agregar a CLAUDE.md.

Comandos slash que usarás a diario

• /init — genera CLAUDE.md desde el repo.
• /clear — borra el contexto y empieza de cero.
• /compact — resume una sesión larga para liberar contexto conservando lo esencial.
• /model — cambia de modelo (usa el más grande para planificación difícil, más rápidos para ediciones rutinarias).
• /cost — muestra el uso de tokens y el costo estimado de la sesión (facturación por API).
• /review — revisa un pull request.
• /agents — gestiona subagentes (tratado más abajo).
• /mcp — inspecciona los servidores MCP conectados y su estado.

También puedes crear tus propios comandos: deja un archivo Markdown en .claude/commands/ y se convierte en un comando slash cuyo contenido es el prompt. Ejemplo: .claude/commands/fix-issue.md:

Analyze and fix GitHub issue $ARGUMENTS.

1. Read the issue and reproduce the problem.
2. Find the root cause. Explain it in two sentences.
3. Implement the smallest fix that resolves it.
4. Add a regression test and run the full suite.
5. Summarize the change and the files touched.

Ahora /fix-issue 123 ejecuta ese procedimiento cada vez, de forma idéntica, para todo el equipo.

Servidores MCP: dale herramientas reales a Claude

De fábrica, Claude Code puede leer archivos, editarlos y ejecutar comandos de shell. Los servidores MCP (Model Context Protocol) extienden eso: acceso a bases de datos, operaciones de GitHub, control del navegador, tus propias API internas. Configura servidores con alcance de proyecto en .mcp.json en la raíz del repo (confírmalo en el control de versiones para que el equipo lo comparta) o agrégalos desde la terminal:

# Filesystem + GitHub + Postgres, added from the CLI
claude mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem ./src
claude mcp add github -- npx -y @modelcontextprotocol/server-github
claude mcp add postgres -- npx -y @modelcontextprotocol/server-postgres \
  "postgresql://readonly:secret@localhost:5432/acme"

El archivo .mcp.json equivalente:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "./src"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}" }
    },
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres",
               "postgresql://readonly:secret@localhost:5432/acme"]
    }
  }
}

Fíjate en los detalles que importan: la conexión de Postgres anterior usa un usuario de base de datos de solo lectura, y los secretos vienen de variables de entorno, nunca escritos directamente en un archivo confirmado. Después de agregar un servidor, pide a Claude algo que lo requiera ("lista los pedidos de los últimos 7 días y compáralos con el código que calcula los totales") y míralo encadenar llamadas a herramientas. Ejecuta /mcp para depurar un servidor que no conecta.

Hooks: reglas que Claude no puede olvidar

Los prompts son peticiones; los hooks son cumplimiento obligatorio. Los hooks son comandos de shell que Claude Code ejecuta automáticamente en puntos del ciclo de vida: antes de que una herramienta se ejecute, después de editar un archivo, cuando una sesión se detiene. Configúralos en .claude/settings.json:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command",
            "command": "npx prettier --write \"$CLAUDE_FILE_PATH\" 2>/dev/null || true" }
        ]
      }
    ],
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          { "type": "command",
            "command": "python3 .claude/hooks/block_dangerous.py" }
        ]
      }
    ]
  }
}

El primer hook formatea automáticamente cada archivo que Claude edita, para que el estilo se mantenga consistente sin regaños. El segundo llama a un script guardián antes de cualquier comando de shell; si el script sale con código 2, el comando se bloquea y se le dice a Claude por qué. Un guardián sencillo:

import json, sys

data = json.load(sys.stdin)
cmd = data.get("tool_input", {}).get("command", "")

BLOCKED = ["rm -rf /", "DROP TABLE", "git push --force", "--prod"]
if any(b in cmd for b in BLOCKED):
    print("Blocked by project policy. Propose a safer alternative.",
          file=sys.stderr)
    sys.exit(2)  # exit 2 = block the tool call
sys.exit(0)

Subagentes: especialistas en paralelo

Los subagentes son instancias separadas de Claude con su propio contexto e instrucciones, definidos como archivos Markdown en .claude/agents/. El agente principal les delega: un revisor que solo revisa, un investigador que solo lee, un escritor de pruebas que solo escribe pruebas. Como cada uno tiene un contexto limpio, se mantienen enfocados, y varios pueden correr en paralelo.

---
name: code-reviewer
description: Reviews code changes for bugs, security issues
  and convention violations. Use after any significant change.
tools: Read, Grep, Bash
model: sonnet
---

You are a strict code reviewer for this repository.

For every change set you are given:
1. Run `git diff` and read the full diff.
2. Flag: security issues, money-handling bugs,
   missing tests, and CLAUDE.md convention violations.
3. Report findings as a numbered list, most severe first.
   If you find nothing, say so plainly. Do not edit files.

Subagentes típicos de alto valor: un escritor de pruebas que convierte la descripción de una funcionalidad en pruebas que fallan, primero; un investigador de documentación que lee documentación y devuelve resúmenes (manteniendo los documentos crudos fuera de tu contexto principal); y un revisor de seguridad como el anterior. El patrón que lo cambia todo: implementador en la sesión principal, subagente revisor tras cada hito, correcciones y luego pruebas.

Ejemplo trabajado: una construcción autónoma, de principio a fin

Objetivo: agregar un flujo de "olvidé mi contraseña" a una pequeña API de Node. Observa el ciclo: planificar, construir con herramientas, verificar con hooks, revisar con un subagente.

# 1. Fresh session, plan first
claude
> Read the auth module and the users table schema.
> Give me a step-by-step plan for password reset with
> expiring tokens. No code yet.

# (review and adjust the plan)

> Implement the plan. Write tests first, then the code.
> Run the suite after each step.

# Claude edits files; the Prettier hook formats each one;
# the Bash guard would block anything destructive.

# 2. Verify independently
> Run the full test suite and the typecheck.
> Show me the git diff summary.

# 3. Subagent review
> Use the code-reviewer subagent on this diff.

# 4. Ship it yourself, informed
git add -A && git commit -m "feat: password reset flow"

Esfuerzo humano total: una revisión del plan, una revisión del diff. Todo lo mecánico —escribir, formatear, probar, primera revisión— fue delegado y verificado, no aceptado a ciegas.

Costos, límites y expectativas honestas

• Costo: los planes de suscripción limitan el uso por ventanas de tiempo; la facturación por API escala con los tokens. Las refactorizaciones grandes en repos grandes cuestan dinero real: /cost te mantiene honesto.
• El contexto es finito. Los monorepos lo desbordan. Trabaja paquete por paquete, mantén CLAUDE.md ajustado y apóyate en subagentes para la investigación, de modo que el material crudo nunca inunde la sesión principal.
• Todavía comete errores. Seguros, plausibles y equivocados. Las pruebas, los hooks y la revisión de diffs no son ceremonias opcionales: son el producto.
• Empieza supervisado. Gana autonomía repo por repo: primero exploración de solo lectura, luego ediciones pequeñas, luego funcionalidades delegadas con revisión.

Domina estas piezas —CLAUDE.md como memoria, MCP como manos, hooks como ley, subagentes como equipo— y Claude Code deja de ser un autocompletado elegante. Se convierte en un flujo de desarrollo que tú diriges, donde tu trabajo pasa de escribir código a revisar resultados. Esa es la habilidad que de verdad vale la pena aprender en 2026.

Modo headless: Claude Code en scripts y CI

Todo lo anterior también corre de forma no interactiva. La bandera -p envía un prompt, transmite el resultado y sale, lo que convierte a Claude Code en un bloque de construcción para automatización: generadores de notas de cambios, resúmenes de PR, verificaciones de migración, trabajos de refactorización nocturnos.

# One-shot question about the codebase
claude -p "List every API route that lacks auth middleware"

# Pipe-friendly JSON output for scripts
claude -p "Review this diff for security issues" \
  --output-format json < diff.patch > review.json

# Restrict autonomy for unattended runs
claude -p "Run the test suite and fix flaky tests" \
  --allowedTools "Read,Bash(npm run test:*),Edit"

La bandera --allowedTools es lo que más importa en automatización: concede exactamente las herramientas que el trabajo necesita (leer archivos, correr pruebas, editar código) y nada más: sin shell sin restricciones, sin escrituras a sistemas de producción. Combina el modo headless con tus hooks guardianes y obtienes agentes que pueden trabajar de noche en una rama y entregarte en la mañana un pull request revisado y probado. Inicia esos trabajos en ramas desechables, mide con qué frecuencia su resultado sobrevive a tu revisión, y amplía sus permisos solo cuando la evidencia lo justifique. La autonomía en producción es una perilla que se gira despacio, no un interruptor que se activa una vez.