Claude Code: guía completa del agente de IA para programar desde la terminal

Qué es Claude Code

Claude Code es el agente de programación con IA de Anthropic que funciona directamente en tu terminal. No es un autocomplete ni un chatbot: es un agente autónomo que lee tu codebase completo, edita archivos, ejecuta comandos, corre tests, hace commits y trabaja en tareas complejas de principio a fin con tu supervisión.

Lidera el benchmark SWE-bench Verified con 80.8% de resolución de problemas reales de ingeniería de software, y se ha convertido en la herramienta de referencia para desarrolladores senior que trabajan en codebases complejas.

Está disponible en múltiples superficies: terminal CLI, extensión para VS Code y JetBrains, app de escritorio, web, Slack, y CI/CD con GitHub Actions y GitLab.

Instalación

macOS, Linux o WSL

curl -fsSL https://claude.ai/install.sh | bash

Windows PowerShell

irm https://claude.ai/install.ps1 | iex

Homebrew (macOS)

# Stable channel (~1 semana atrás, salta releases con regresiones)
brew install --cask claude-code

# Latest channel
brew install --cask claude-code@latest

Verificar instalación

claude --version

Requisitos

• Suscripción de Claude (Pro $20/mes, Max $100/mes, Team o Enterprise) o cuenta de Anthropic Console
• Node.js 18+ (para instalación via npm)
• Git instalado (recomendado en Windows para Bash tool)

Primer uso

cd tu-proyecto
claude

Se abrirá el navegador para autenticarte. Una vez autenticado, cada ejecución de claude en un directorio de proyecto inicia una sesión informada —Claude conoce tu filesystem, tu build system y tu CLAUDE.md desde el primer mensaje.

Comandos esenciales

Comando	Qué hace
claude "tarea"	Ejecuta una tarea y permanece en la sesión
claude -p "query"	Consulta headless one-off, sale al terminar
claude -c	Continúa la conversación más reciente del directorio
claude -r	Resume cualquier conversación previa interactivamente
claude agents	Abre Agent View (panel de sesiones en background)

Comandos slash dentro de la sesión

Comando	Qué hace	Cuándo usarlo
/init	Inicializa proyecto con CLAUDE.md	Primera vez en un proyecto
/compact	Compacta conversación con instrucciones opcionales	Contexto >80%
/clear	Borra contexto, empieza fresh	Cambiar de tarea
/diff	Diff interactivo de cambios sin commitear	Antes de commitear
/model	Cambiar entre Opus / Sonnet / Haiku	Matchear modelo a complejidad
/effort	Setear effort: high/xhigh/max	Tarea compleja
/mcp	Ver y gestionar conexiones MCP	Agregar o troubleshooting MCP
/config	Abrir settings (tema, modelo, preferencias)	Personalizar Claude Code

CLAUDE.md: la memoria del proyecto

CLAUDE.md es el archivo más importante de tu setup. Se carga al inicio de cada sesión y define:

• Stack técnico y dependencias clave
• Estructura del proyecto
• Convenciones de código y patrones a seguir
• Comandos comunes (test, build, lint)
• Decisiones de arquitectura

Template de CLAUDE.md

# Proyecto: [nombre]

## Stack
- Next.js 16, TypeScript, Supabase, Tailwind

## Estructura
- app/ — App Router pages
- lib/ — utilidades y tipos
- components/ — componentes React

## Convenciones
- Usar TypeScript estricto
- Validar inputs con Zod
- Server Components por defecto
- getUser() en servidor, nunca getSession()

## Comandos
- pnpm dev — desarrollo
- pnpm build — build
- pnpm test — tests
- pnpm lint — linter

CLAUDE.local.md

Versión personal que se gitignora. Usalo para preferencias individuales, paths locales, shortcuts personales.

Los 8 primitivos de Claude Code

Primitivo	Ubicación	Función
CLAUDE.md	Raíz del proyecto	Memoria compartida del proyecto
.mcp.json	Raíz del proyecto	Configuración de servidores MCP
settings.json	.claude/	Permisos, modelo, hooks
rules/	.claude/rules/	Reglas modulares por tema (estilo, testing, API)
commands/	.claude/commands/	Slash commands custom (/project:review)
skills/	.claude/skills/	Auto-triggered según contexto de la tarea
agents/	.claude/agents/	Sub-agentes especializados con contexto aislado
hooks/	.claude/hooks/	Scripts event-driven (pre/post tool use)

Hooks: automatización event-driven

Los hooks son comandos shell que se ejecutan automáticamente en puntos específicos del ciclo de vida. Se configuran en .claude/settings.json:

Ejemplo: auto-format después de editar

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write|MultiEdit",
        "hooks": [
          {
            "type": "command",
            "command": "prettier --write ${CLAUDE_FILE_PATHS}"
          }
        ]
      }
    ]
  }
}

Eventos de hook disponibles (29 eventos)

Los más usados: SessionStart, PreToolUse, PostToolUse, Stop, Notification, SubagentStart, SubagentStop, PreCompact, SessionEnd.

Sub-agentes: especialistas aislados

Los sub-agentes son especialistas que invocás desde la sesión principal. Tienen su propio system prompt, su propio allowlist de tools y no pueden ver tu contexto principal. Usalos para:

• Paralelizar tareas
• Aislar tareas riesgosas
• Enforzar un rol específico (code reviewer, test writer)

Ejemplo: .claude/agents/code-reviewer.md

---
name: code-reviewer
description: Reviews code changes for quality, security and best practices
tools: [Read, Grep, Glob]
model: claude-sonnet-4-6
---

You are a senior code reviewer. Review changes for:
- Security vulnerabilities
- Performance issues
- Code style violations
- Missing tests
Return a structured report with severity levels.

Agent Teams (experimental)

Agent Teams permite que múltiples teammates compartan una task list y se comuniquen directamente —sin dispatcher central. Requiere Claude Code v2.1.32+ y habilitar:

CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

Un lead session puede delegar a múltiples sub-agentes trabajando en paralelo, cada uno con su propia context window.

MCP: Model Context Protocol

MCP es el estándar abierto que conecta Claude con sistemas externos. Configurás servidores MCP en .mcp.json y Claude gana acceso live a GitHub, databases, Figma, Slack, Notion y cualquier servicio con un MCP server.

Agregar un servidor MCP

# Filesystem server
claude mcp add filesystem npx -- -y @modelcontextprotocol/server-filesystem /Users/you/projects

# GitHub server
claude mcp add github npx -- -y @modelcontextprotocol/server-github

# Ver conexiones
/mcp

Scopes de MCP

• User scope (--scope user): disponible en todos los proyectos
• Project scope (--scope project): commiteado a .mcp.json, compartido con el team
• Local scope (default): solo esta máquina, este proyecto

Modelos

Modelo	Uso	Context window
Claude Opus 4.8	Decisiones arquitectónicas, sesiones autónomas extendidas, multi-agente	1M tokens (beta)
Claude Sonnet 4.6	Desarrollo general, la mayoría de tareas	1M tokens (beta)
Claude Haiku	Lookups simples, queries triviales	Standard

Precios

Plan	Precio	Incluye
Pro	$20/mes	Uso limitado de Claude Code
Max 5x	$100/mes	5x el uso de Pro
Max 20x	$200/mes	20x el uso de Pro
Teams Premium	$150/user/mes	Para equipos
API	Pay-as-you-go	Por token consumido

Workflows recomendados

1. Exploración

"Lee el codebase y explicá el flujo de autenticación.
¿Qué archivos están involucrados y cómo se conectan?"

2. Implementación

"Agregá reset de password. Creá el API route, el email template,
la migración de DB y el componente React. Seguí los patrones existentes."

3. Debugging

"Los tests en auth.test.ts están fallando. Corrélos, leé los errores
y fixeá los issues."

4. Refactoring

"Refactorizá el user service para usar el repository pattern.
Actualizá todos los consumers y los tests."

5. Headless (CI/CD)

claude -p "Fix all TypeScript errors and run tests" --allowedTools Edit,Bash

Permisos y seguridad

El modo Auto usa un clasificador de IA para decidir qué es seguro. Para mayor control:

• Configurá permisos explícitos en settings.json
• Usá allow y deny lists para tools específicas
• Los hooks pueden bloquear operaciones inseguras antes de que ejecuten
• Revisá los git diffs antes de aceptar cambios

Conclusión

Claude Code representa un cambio fundamental: dejás de aceptar sugerencias línea por línea para empezar a delegar tareas end-to-end. Su fortaleza no es solo la calidad del modelo (Opus 4.8 lidera SWE-bench), sino el sistema completo: CLAUDE.md para memoria persistente, hooks para automatización, sub-agentes para aislamiento, MCP para integraciones externas y Agent Teams para paralelismo.

Para desarrolladores que trabajan en codebases reales con tests, migraciones y CI, Claude Code es la herramienta que más se acerca a tener un teammate senior disponible 24/7. La curva de aprendizaje es más pronunciada que Cursor o Copilot, pero el techo de productividad es significativamente más alto.