# Guía para Claude Code: configuración para programación con agentes (para principiantes)

> Guía práctica completa para configurar Claude Code: instalación de CLI, configuración de CLAUDE.md y settings.json, matriz de permisos, hooks automáticos, comando /truth y subagentes.

## 1. Instalación de Claude Code y preparación del entorno

Claude Code se instala como una interfaz de línea de comandos (CLI) independiente diseñada para una interacción agéntica profunda con tu base de código mediante los modelos de Anthropic. A diferencia de los chatbots convencionales, Claude Code interactúa directamente con el sistema de archivos, ejecuta comandos de terminal, analiza la jerarquía del repositorio y realiza modificaciones atómicas.

### 1.1. Métodos de instalación de CLI: script nativo frente a npm

El método de instalación recomendado por los desarrolladores es el instalador nativo del sistema, que configura automáticamente los binarios y el entorno de ejecución. Como alternativa para entornos que ya cuentan con herramientas de Node.js, se admite la instalación global mediante npm:

```bash
# macOS, Linux o WSL
curl -fsSL https://claude.ai/install.sh | bash

# Windows PowerShell
irm https://claude.ai/install.ps1 | iex

# Instalación alternativa mediante npm
npm install -g @anthropic-ai/claude-code
```

Una vez finalizada la instalación, verifica que la herramienta funcione correctamente ejecutando `claude --version` en tu terminal.

### 1.2. Vinculación al directorio del proyecto y autenticación

Antes de ejecutar la herramienta por primera vez, es fundamental navegar al directorio raíz de tu proyecto de trabajo:

```bash
cd your-project-directory
claude
```

> 💡 **Por qué esto es crucial:** Claude Code vincula la memoria a largo plazo, las reglas locales y los permisos de seguridad directamente al directorio de trabajo activo. Ejecutar la herramienta desde tu carpeta de inicio (`~`) o el escritorio despoja al agente de todo el contexto arquitectónico del repositorio.

Durante la primera ejecución, la herramienta te solicitará autenticación:
- **Inicio de sesión OAuth a través del navegador** con una suscripción activa de Claude (Pro, Max o Team).
- **Clave API de Anthropic Console** para facturación directa por uso de tokens según tarifas de API.

Además de la terminal independiente, Claude Code cuenta con una extensión oficial para VS Code, un plugin para JetBrains, una aplicación de escritorio y una interfaz web en claude.ai. Todas estas interfaces comparten los mismos archivos de configuración `.claude/`, asegurando que tus preferencias se mantengan idénticas sin importar el entorno elegido.

## 2. Los tres archivos de configuración: arquitectura de memoria y ajustes

Claude Code emplea una jerarquía de configuración de dos niveles: el directorio del proyecto local `.claude/` (junto con el archivo `CLAUDE.md` en la raíz) y el directorio global `~/.claude/` en la carpeta de inicio del usuario. Las configuraciones globales se aplican a todas las sesiones de la máquina, mientras que las reglas locales tienen prioridad en el repositorio actual.

### 2.1. CLAUDE.md y las reglas de memoria del repositorio

`CLAUDE.md` funciona como la memoria persistente del proyecto que Claude lee al inicio de cada sesión en el repositorio. Aquí se definen los principios arquitectónicos, comandos de pruebas, convenciones de estilo de código y la pila tecnológica.

| Mecanismo | Ubicación | Propósito |
| --- | --- | --- |
| **Guía raíz** | `CLAUDE.md` | Instrucciones principales y descripción del stack (recomendado hasta 2500 tokens). |
| **Reglas modulares** | `.claude/rules/*.md` | Instrucciones específicas cargadas condicionalmente para archivos coincidentes. |
| **Generador de memoria** | Comando `/init` | Analiza el repositorio automáticamente y genera una plantilla inicial. |
| **Editor de memoria** | Comando `/memory` | Permite la edición interactiva rápida de las reglas almacenadas. |

> ⚠️ **Principio clave de memoria:** Las instrucciones dadas únicamente en el chat se perderán inevitablemente cuando se active la compresión de contexto en sesiones largas. Cualquier regla que deba perdurar debe escribirse explícitamente en `CLAUDE.md`.

### 2.2. settings.json y el mecanismo de memoria automática (Auto memory)

El archivo de configuración `settings.json` (ubicado en `.claude/settings.json` para el proyecto o en `~/.claude/settings.json` para preferencias globales) gestiona permisos de herramientas, hooks del sistema, variables de entorno y la selección del modelo predeterminado.

La función **Auto memory** permite que Claude Code registre automáticamente observaciones de trabajo entre sesiones sin intervención manual. Puedes desactivar este comportamiento con el parámetro `"autoMemoryEnabled": false` o mediante la variable de entorno `CLAUDE_CODE_DISABLE_AUTO_MEMORY=1` si prefieres una gestión de memoria estrictamente manual a través de `CLAUDE.md`.

## 3. Configuración anticipada de permisos y hooks

Para mantener un flujo de trabajo seguro y evitar solicitudes repetitivas de confirmación, Claude Code ofrece modos interactivos de ejecución y reglas declarativas en su configuración.

### 3.1. Modos de permisos interactivos y matriz allow/ask/deny

Puedes alternar entre los modos interactivos de permisos en cualquier momento usando `Shift+Tab`:
- **Default** — solicita confirmación manual antes de cada llamada potencialmente riesgosa o modificación de archivo.
- **Auto-Accept Edits** — aplica ediciones de archivos sin confirmación, solicitando aprobación únicamente para comandos del sistema.
- **Plan Mode** — modo de solo lectura para diseño previo donde no se ejecutan comandos de terminal ni se modifican archivos hasta aprobar el plan.

Para suprimir confirmaciones innecesarias en tareas rutinarias, configura una matriz de permisos en `.claude/settings.json`:

```json
{
  "permissions": {
    "allow": [
      "Bash(npm test:*)",
      "Bash(npm run lint:*)",
      "Read(**)"
    ],
    "ask": [
      "Bash(git push:*)"
    ],
    "deny": [
      "Bash(rm -rf /*)",
      "Bash(sudo:*)",
      "Read(.env)"
    ]
  }
}
```

La regla `deny` siempre tiene prioridad absoluta: incluso si `Read(**)` otorga acceso global de lectura, la restricción `Read(.env)` garantiza que las claves secretas y variables de entorno nunca se filtren al contexto del modelo.

### 3.2. Automatización mediante hooks PostToolUse y PreToolUse

Los hooks permiten ejecutar scripts locales antes o después de que el agente utilice sus herramientas internas.

Por ejemplo, un hook **PostToolUse** formatea automáticamente cada archivo modificado utilizando Prettier:

```json
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "npx prettier --write \"$CLAUDE_TOOL_INPUT_FILE_PATH\""
          }
        ]
      }
    ]
  }
}
```

Por su parte, un hook **PreToolUse** permite interceptar y bloquear programáticamente comandos bash peligrosos a nivel de script en Python antes de que lleguen a la terminal:

```python
#!/usr/bin/env python3
# .claude/hooks/block-dangerous-bash.py
import json
import re
import sys

DANGEROUS_PATTERNS = [
    r'\brm\s+.*-[a-z]*r[a-z]*f',
    r'sudo\s+rm',
    r'chmod\s+777',
    r'git\s+push\s+--force.*main',
]

input_data = json.load(sys.stdin)
if input_data.get('tool_name') == 'Bash':
    command = input_data.get('tool_input', {}).get('command', '')
    for pattern in DANGEROUS_PATTERNS:
        if re.search(pattern, command, re.IGNORECASE):
            print("BLOCKED: command matches dangerous security pattern", file=sys.stderr)
            sys.exit(2)
sys.exit(0)
```

El código de salida `2` le indica a Claude Code que aborte la operación de inmediato por motivos de seguridad.

## 4. Comandos que debes aprender primero

Aunque Claude Code incluye más de sesenta comandos incorporados, dominar el conjunto esencial es suficiente para maximizar tu productividad diaria.

### 4.1. Tabla de comandos integrados y avanzados

La siguiente tabla resume los comandos más relevantes organizados por categoría:

| Comando | Categoría | Propósito y comportamiento |
| --- | --- | --- |
| `/init` | Configuración | Analiza la base de código y crea el archivo inicial `CLAUDE.md`. |
| `/memory` | Configuración | Abre la memoria del proyecto para edición directa. |
| `/clear` | Contexto | Reinicia el historial de la conversación conservando la memoria del proyecto. |
| `/compact [focus]` | Contexto | Comprime el contexto de la sesión manteniendo los aspectos clave indicados. |
| `/context` | Contexto | Muestra el uso actual de tokens y el estado de la ventana de contexto. |
| `/plan` | Planificación | Activa el modo de solo lectura para diseñar planes paso a paso. |
| `/diff` | Verificación | Abre un visor interactivo con todos los cambios de la sesión. |
| `/code-review [--fix]` | Verificación | Examina los cambios preparados en busca de errores o mejoras de calidad. |
| `/security-review` | Verificación | Auditoría de seguridad enfocada en vulnerabilidades en el diff actual. |
| `/resume [session]` | Navegación | Reanuda una sesión anterior mediante su identificador o nombre. |
| `/branch [name]` | Navegación | Divide la conversación actual en una sesión independiente. |
| `/rewind` | Navegación | Revierte el código o la conversación a un punto de control previo. |
| `/model` | Rendimiento | Cambia el modelo activo (Sonnet, Haiku, Opus) en medio de la sesión. |
| `/effort` | Rendimiento | Ajusta la profundidad de razonamiento y el presupuesto de pensamiento. |
| `/cost` | Rendimiento | Informa el consumo de tokens y los costes acumulados de la sesión. |
| `/agents` | Delegación | Administra subagentes especializados y tareas en segundo plano. |
| `/permissions` | Configuración | Menú interactivo para auditar y actualizar las reglas de permisos. |
| `/hooks` | Configuración | Panel de diagnóstico de hooks del sistema registrados. |
| `/doctor` | Diagnóstico | Ejecuta una comprobación exhaustiva del entorno, red y credenciales. |

![Referencia y navegación de comandos integrados en Claude Code](/api/guides-media/automation/claude-code-agentic-programming-setup-guide/images/claude-code-agentic-programming-setup-guide-extra-01.webp)

### 4.2. Tríada de productividad diaria: /compact, /plan y /diff

Para dominar rápidamente la herramienta, concéntrate en estos tres comandos:
1. **`/plan`** — utilízalo antes de emprender tareas complejas para evitar modificaciones desordenadas en el código.
2. **`/compact`** — ejecútalo cada 20–30 minutos de trabajo continuo para prevenir la degradación de atención del modelo.
3. **`/diff`** — revísalo antes de cada commit para verificar minuciosamente los cambios generados.

## 5. Creación de tu propio comando de verificación /truth

El comando `/truth` no viene preinstalado en Claude Code, pero resuelve un desafío fundamental: la tendencia de los modelos a reportar tareas como concluidas sin validar los archivos reales en el disco.

### 5.1. Concepto de verificación de hechos frente a la base de código

Cuando un agente afirma: *«He actualizado la interfaz en el archivo X y corregido las importaciones en el archivo Y»*, a menudo se basa en sus intenciones conversacionales. El propósito de `/truth` es obligar a releer los archivos del disco y contrastar cada afirmación con la salida real de `git diff`.

![Gestión interactiva de contexto, sesiones y comandos en Claude Code](/api/guides-media/automation/claude-code-agentic-programming-setup-guide/images/claude-code-agentic-programming-setup-guide-extra-02.webp)

### 5.2. Implementación de la habilidad .claude/skills/truth/SKILL.md

Los comandos personalizados se estructuran como habilidades (skills). Crea el archivo `.claude/skills/truth/SKILL.md` en tu repositorio:

```markdown
---
description: "Verify Claude's most recent claims and edits against the actual codebase"
allowed-tools: ["Read", "Grep", "Glob", "Bash(git diff:*)"]
---

Re-examine everything you just told me in this conversation against what actually exists in the codebase right now. Specifically:

1. For every file you claim to have edited, read it again and confirm the change is actually present and matches what you described.
2. For every claim about existing code (a function's behavior, a config value, an import, a dependency version), verify it against the real file rather than your memory of reading it earlier in the session.
3. Run `git diff` and compare the actual diff against what you described changing.
4. Report back plainly: which claims checked out, which didn't, and exactly what the discrepancy was for anything that failed. Do not soften or hedge a discrepancy you find, state it directly.
```

Al limitar `allowed-tools` exclusivamente a operaciones de lectura y a `git diff`, el comando no puede modificar archivos, funcionando como un auditor independiente.

## 6. Subagentes y flujos de trabajo paralelos

Al abordar proyectos extensos, la lectura de numerosos archivos y la ejecución de pruebas pueden saturar rápidamente la ventana de contexto principal.

### 6.1. Aislamiento de contexto y subagentes especializados (/agents)

Un subagente es una instancia aislada de Claude Code con su propio contexto, herramientas personalizadas y un prompt de sistema específico. Resuelve subtareas en segundo plano y devuelve únicamente un resumen conciso a la conversación principal.

```bash
# Abrir el menú interactivo de subagentes en la sesión
/agents
```

También puedes definir subagentes permanentes en `.claude/agents/code-reviewer.md`:
- Asignar herramientas en modo de solo lectura (`Read`, `Grep`, `Glob`).
- Utilizar un modelo rápido y de bajo consumo.
- Prohibir la edición directa de archivos para asegurar revisiones imparciales.

### 6.2. Escalado de tareas mediante worktrees y ejecución por lotes (/batch)

Para tareas paralelas en áreas no relacionadas del proyecto, Claude Code admite Git Worktrees y el comando `/batch`:
- **Aislamiento con Git Worktree (`--worktree`):** múltiples agentes trabajan simultáneamente en copias independientes sin conflictos de bloqueo.
- **Procesamiento por lotes (`/batch`):** automatiza tareas sistemáticas de refactorización o generación de pruebas en segundo plano.

## 7. Plantilla lista para usar de CLAUDE.md y settings.json

Las siguientes configuraciones probadas en entornos de producción proporcionan un punto de partida confiable para tu repositorio.

### 7.1. Plantilla inicial de memoria CLAUDE.md

Guarda este contenido en el archivo `CLAUDE.md` en la raíz de tu proyecto:

```markdown
# Project Context

### Stack
- Language/Framework: [Node.js, TypeScript, Next.js / Python, FastAPI]
- Styling: [Tailwind CSS]
- Database: [PostgreSQL / SQLite via Drizzle ORM]

### Commands
- Dev server: `npm run dev`
- Build: `npm run build`
- Test: `npm test`
- Lint: `npm run lint`

### Conventions
- Strict TypeScript typing without `any`
- Functional React components with named exports
- Keep business logic in services or hooks, not inside UI components

### Before finishing any task
- Run test suite and confirm 100% pass rate
- Run `/truth` if the task involved modifying multiple files
```

### 7.2. Configuración de producción .claude/settings.json con hooks

Guarda esta configuración en `.claude/settings.json`:

```json
{
  "permissions": {
    "allow": [
      "Bash(npm test:*)",
      "Bash(npm run lint:*)",
      "Read(**)"
    ],
    "ask": [
      "Bash(git push:*)"
    ],
    "deny": [
      "Bash(rm -rf /*)",
      "Bash(sudo:*)",
      "Read(.env)"
    ]
  },
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "python3 .claude/hooks/block-dangerous-bash.py"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "npx prettier --write \"$CLAUDE_TOOL_INPUT_FILE_PATH\""
          }
        ]
      }
    ]
  }
}
```

Para configuraciones personales específicas de tu entorno local, utiliza `.claude/settings.local.json` y agrégalo a `.gitignore`.

## 8. Conclusión y lista de verificación de preparación

Un entorno agéntico de alto rendimiento se distingue de un chat convencional por sus barreras de protección preventivas, una memoria duradera y protocolos rigurosos de verificación.

### 8.1. Principios fundamentales de la ingeniería agéntica

1. **Mantén el contexto despejado:** utiliza `/compact` regularmente y delega auditorías extensas a subagentes.
2. **Formaliza el conocimiento:** documenta las reglas en `CLAUDE.md` en lugar de repetirlas en cada mensaje.
3. **Verifica cada resultado:** recurre a `/truth` y analiza `/diff` antes de realizar cualquier commit.

### 8.2. Lista de verificación de preparación del entorno

| Fase | Acción | Estado requerido |
| --- | --- | --- |
| **Instalación de CLI** | Instalar CLI nativo de Claude Code e iniciar sesión | `Obligatorio` |
| **Memoria del proyecto** | Crear `CLAUDE.md` con stack, comandos y reglas | `Obligatorio` |
| **Permisos** | Configurar listas `allow`, `ask` y `deny` en `settings.json` | `Obligatorio` |
| **Hook de formato** | Configurar `PostToolUse` para formateo con Prettier | `Recomendado` |
| **Filtro de seguridad** | Activar `block-dangerous-bash.py` vía `PreToolUse` | `Recomendado` |
| **Habilidad personalizada** | Implementar verificador `.claude/skills/truth/SKILL.md` | `Recomendado` |