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 Збільшити

Referencia y navegación de comandos integrados en Claude Code

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

Para dominar rápidamente la herramienta, concéntrate en estos tres comandos:

/plan — utilízalo antes de emprender tareas complejas para evitar modificaciones desordenadas en el código.
/compact — ejecútalo cada 20–30 minutos de trabajo continuo para prevenir la degradación de atención del modelo.
/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 Збільшити

Gestión interactiva de contexto, sesiones y comandos en Claude Code

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

Mantén el contexto despejado: utiliza /compact regularmente y delega auditorías extensas a subagentes.
Formaliza el conocimiento: documenta las reglas en CLAUDE.md en lugar de repetirlas en cada mensaje.
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`