Claude Code Cheat Sheet: Guía Completa para Desarrolladores Principiantes

Si te estás sumergiendo en Claude Code, el potente asistente de codificación con IA de Anthropic, tener una referencia clara es esencial. Esta Hoja de trucos de Claude Code está pensada para desarrolladores que desean una guía práctica y apta para principiantes que cubra la configuración, los flujos de trabajo, la configuración y los consejos avanzados. Al final, te sentirás más seguro utilizando Claude Code en tu entorno local o como parte de tus procesos de CI/CD.

¿Qué es Claude Code?

Claude Code es una herramienta de codificación con IA basada en CLI de Anthropic. Permite a los desarrolladores generar, refactorizar, probar y documentar código utilizando los modelos avanzados de Claude. En lugar de una simple interfaz de chat, Claude Code se comporta como un IDE de IA: comprende la estructura de tu repositorio, aplica las salvaguardas definidas en los archivos de configuración, puede ejecutar comandos bash y se integra con los flujos de trabajo de Git.

Instalar Claude Code:

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

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

# NPM:
npm install -g @anthropic-ai/claude-code

# Homebrew:
brew install --cask claude-code

Empezar a usar Claude Code:

cd your-project
claude

Componentes clave de Claude Code — Tu hoja de trucos

Aquí tienes los bloques de construcción y características esenciales que querrás conocer al empezar con Claude Code:

1. CLAUDE.md — Manifiesto del Agente

• El archivo CLAUDE.md es la "constitución" de tu agente: define cómo se comporta Claude en tu repositorio.
• Úsalo para documentar herramientas aprobadas, flujos de trabajo comunes y restricciones.
• Mejor práctica: Mantenlo corto, enfocado en las salvaguardas clave y evita incrustar documentos muy grandes.

# MyProject CLAUDE.md

## Project Overview  
This is a Node.js + Express REST API for a task management application.  

## Technology Stack  
- Backend: Node.js (ES6), Express  
- Database: PostgreSQL  
- Testing: Jest  
- Linting & Style: ESLint, Prettier

## Development Commands  
- `npm install` — Install dependencies  
- `npm run dev` — Start development server  
- `npm run test` — Run all tests  
- `npm run lint` — Run linter  

## Coding Standards  
- Use 2-space indentation.  
- Always use `async / await` instead of `.then()` chains.  
- Functions must have JSDoc comments.  
- Prefer composition over inheritance.

## Git Workflow  
- Feature branches must follow this pattern: `feature/FOO`  
- Use `git rebase` instead of `merge` for updating branches.  
- When committing: write descriptive commit messages that follow the Conventional Commits format.

## File Structure Guidance  
- `src/` — Your main application code  
- `tests/` — Test files  
- `scripts/` — Utility or setup scripts  
- `migrations/` — Database migrations  

## Known Issues / Workarounds  
- `db.connect()` sometimes times out; in that case, retry twice.  
- For large JSON payloads, use streaming to avoid memory issues.

## Memory / Style Preferences  
- Always ask for clarification if the request is ambiguous.  
- Do not generate new `.md` files unless explicitly instructed.  
- Include a `co-authored-by Claude` line in generated commits.

2. Gestión de Contexto

a. Usa /context para inspeccionar el uso de tokens de tu sesión actual de Claude.

b. Comandos para reiniciar o reducir el contexto:

• /clear + /catchup: Borra toda la conversación y luego recarga los archivos de un commit o rama.
• Un flujo de "Documentar y Borrar": haz que Claude vuelque su plan en un archivo Markdown, borra la memoria y luego recarga desde ese archivo.

3. Comandos de barra diagonal

• Los comandos de barra diagonal son atajos para mensajes predefinidos.
• Ejemplos:

• Mantén los comandos de barra diagonal mínimos y enfocados; no dependas de ellos para cada tarea.

4. Modo Planificación

• Usa el modo de planificación al iniciar tareas complejas. Claude esbozará un plan antes de escribir el código.
• Luego puedes revisar, editar o aprobar ese plan antes de pedirle a Claude que lo ejecute.
• Ideal para grandes trabajos de características, refactorización o cambios arquitectónicos.

5. Subagentes y Delegación de Tareas

• Claude Code soporta subagentes, permitiéndote delegar partes del trabajo a "clones" del agente principal.
• Shrivu prefiere una arquitectura "Maestro-Clon": el agente principal genera clones a través de Task(...), en lugar de usar subagentes especializados rígidos.
• Esto preserva la flexibilidad al tiempo que evita la fragmentación del contexto.
• Accede a los subagentes de Claude Code usando el comando de barra: /agents.

6. Habilidades de Claude vs. MCP — ¿Cuál es la diferencia?

a. Las Habilidades de Claude son "módulos" preconstruidos que enseñan a Claude cómo realizar tareas específicas. Están escritas en Markdown o código, y se cargan solo cuando son necesarias. Puedes usar las Habilidades para definir flujos de trabajo como formatear informes, resumir datos o hacer cumplir el estilo de tu equipo.

b. El Protocolo de Contexto del Modelo (MCP), por otro lado, es un protocolo para conectar Claude a datos y herramientas externas, como bases de datos, tu base de código o sistemas empresariales. Es como un "adaptador universal" que permite a Claude acceder y actuar sobre recursos externos sin integraciones personalizadas por herramienta.

c. Diferencias clave:

1. Propósito:

• Las Habilidades codifican conocimiento procesal.
• El MCP gestiona la conectividad de herramientas y datos.

2. Eficiencia de Tokens:

• Las Habilidades se cargan solo cuando son necesarias, usando relativamente pocos tokens.
• Las definiciones de herramientas de MCP pueden ocupar un espacio significativo de tokens si se habilitan muchas.

d. Caso de uso:

• Usa Habilidades para enseñar a Claude flujos de trabajo específicos de un dominio (por ejemplo, "al escribir informes de estado, incluye siempre X, Y, Z").
• Usa MCP cuando Claude necesite leer/escribir datos, llamar a APIs o acceder a sistemas externos como Git o una base de datos.

En la práctica, los dos funcionan mejor juntos: MCP le da a Claude acceso a tus datos, y Habilidades le enseñan a Claude cómo usar esos datos de una manera estructurada y repetible.

6. Ganchos (Hooks)

a. Los Ganchos son tu forma de aplicar reglas automáticamente.

b. Dos tipos comunes:

• Bloqueo al enviar (Block-at-submit): Por ejemplo, un gancho PreToolUse puede bloquear git commit a menos que las pruebas hayan pasado.
• Ganchos de sugerencia (Hint hooks): No bloqueantes; proporcionan orientación o sugerencias sin detener la ejecución.

c. Evita los ganchos de "bloqueo al escribir" (block-at-write); dejar que Claude complete su plan y luego validarlo es más estable.

# Example Hook in .claude/settings.toml

[[hooks]]
# The event that triggers the hook.
event = "PostToolUse" 

# (Optional) Conditions for the hook to run.
[hooks.matcher]
tool_name = "edit_file"
file_paths = ["*.py", "api/**/*.py"]

# The shell command to execute.
command = "ruff check --fix $CLAUDE_FILE_PATHS && black $CLAUDE_FILE_PATHS"

# (Optional) Whether to run the command in the background.
run_in_background = false 

7. SDK de CLI

• El SDK de Claude Code te permite programar interacciones con Claude: útil para procesamiento por lotes, construir herramientas internas o prototipar agentes.
• Úsalo para ejecutar refactorizaciones paralelas, para generar código a partir de plantillas, o como un agente ligero dentro de flujos de trabajo CI/CD.

Instalación:

# Typescript:
npm install @anthropic-ai/claude-agent-sdk

# Python:
pip install claude-agent-sdk

8. Acciones de GitHub (GHA) de Claude Code

• Puedes integrar Claude Code directamente en las Acciones de GitHub.
• Úsalo para generar automáticamente solicitudes de extracción, hacer cumplir estándares de código o ejecutar comprobaciones basadas en CLAUDE.md como parte de tu pipeline de CI.
• Dado que los registros se almacenan, puedes auditar el comportamiento del agente y mejorar tu archivo CLAUDE.md con el tiempo.

9. Configuración y Ajustes

a. En settings.json, puedes configurar:

• Proxy (HTTPS_PROXY) — útil para depurar el tráfico de la CLI.
• Tiempos de espera (MCP_TOOL_TIMEOUT, BASH_MAX_TIMEOUT_MS) — auméntalos si ejecutas tareas largas.
• Clave API (ANTHROPIC_API_KEY) — usa tu clave de Anthropic o un script auxiliar.
• Permisos — controla qué herramientas del sistema se le permite ejecutar a Claude Code.

{
  "permissions": {
    "allow": [
      "Bash(npm run lint)",
      "Bash(npm run test:*)",
      "Read(~/.zshrc)"
    ],
    "deny": [
      "Bash(curl:*)",
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)"
    ]
  },
  "env": {
    "CLAUDE_CODE_ENABLE_TELEMETRY": "1",
    "OTEL_METRICS_EXPORTER": "otlp"
  },
  "companyAnnouncements": [
    "Welcome to Acme Corp! Review our code guidelines at docs.acme.com",
    "Reminder: Code reviews required for all PRs",
    "New security policy in effect"
  ]
}

Características Avanzadas y Consejos de Productividad

1. Cambio de Modelo: Elige Claude 4 Sonnet u Opus según tu tarea. Sonnet es rápido y eficiente en costes; Opus es más capaz para cambios complejos y multifichero.
2. Modos de Pensamiento (Truco): Algunos usuarios ajustan el modo de razonamiento de Claude a think, think hard, think harder o ultrathink para ajustar la profundidad de su razonamiento.
3. Comandos Personalizados: Define comandos de barra reutilizables en .claude/commands con marcadores de posición dinámicos ($argument). Genial para probar, construir o revisar.
4. Historial de Sesiones: Usa claude --resume o claude --continue para reanudar sesiones antiguas. Claude almacena todo el historial de sesiones localmente.
5. Bucle de Retroalimentación: Revisa el comportamiento del agente a través de los registros de las Acciones de GitHub o los datos históricos de la sesión y actualiza tu CLAUDE.md para corregir malentendidos o aplicar mejores salvaguardas.

Preguntas Frecuentes (FAQ)

P1. ¿Cuál es el propósito de CLAUDE.md?
Resp: CLAUDE.md actúa como el manifiesto del agente. Define reglas, herramientas y convenciones que Claude Code debe seguir. Ayuda a estandarizar el comportamiento en tu repositorio.

P2. ¿Debería usar subagentes o solo tareas simples?
Resp: Usa subagentes si quieres flujos de trabajo modulares estrictos. Pero muchos encuentran que el patrón Maestro-Clon (usando Task(...)) es más flexible: mantienes el contexto mientras delegas subtareas.

P3. ¿Cómo reinicio una sesión de Claude sin perderlo todo?
Resp: Usa /clear para restablecer el chat y luego /catchup para cargar archivos de tu rama de Git para que Claude tenga el contexto completo de nuevo.

P4. ¿Qué son los ganchos (hooks) y por qué los necesito?
Resp: Los ganchos aplican reglas o comprobaciones cuando Claude confirma el trabajo. Por ejemplo, un gancho de bloqueo al enviar puede asegurar que las pruebas pasen antes de permitir un commit de Git.

P5. ¿Cómo puedo integrar Claude Code en CI/CD?
Resp: Utiliza la Acción de GitHub de Claude Code para ejecutar tareas, validar código, generar solicitudes de extracción o aplicar tus salvaguardas de CLAUDE.md en pipelines automatizados.

Conclusión

Esta Hoja de Trucos de Claude Code te ofrece una visión práctica y estructurada de cómo usar Claude Code de forma efectiva. Desde la creación de un archivo CLAUDE.md bien elaborado hasta el aprovechamiento de comandos de barra, subagentes, ganchos e integración con CI, estos patrones forman una base sólida para usar Claude Code como un socio de desarrollo confiable impulsado por IA.

Al dominar estas características, los nuevos desarrolladores pueden incorporarse rápidamente, y los ingenieros más experimentados pueden optimizar sus flujos de trabajo, aplicar salvaguardas y escalar la productividad asistida por Claude. Claude Code es más que una herramienta de generación de código: es un sistema programable y agéntico que se adapta a las necesidades de tu equipo.