12 características de Claude Code: explicación detallada con ejemplos

1. Descripción general

Claude Code es un agente de código que se ejecuta en la terminal, capaz de leer, editar, ejecutar comandos y verificar automáticamente el código en tu proyecto. El problema es: el agente es potente, pero si lo usas con configuración predeterminada, fácilmente se “pierde” – edita archivos incorrectos, agota la ventana de contexto, o ejecuta comandos peligrosos. Este artículo explica 12 características que te ayudan a controlar este agente de manera intencionada. Después de leerlo, sabrás cómo configurar CLAUDE.md, permissions, hooks, MCP… para que Claude Code funcione según las convenciones de tu equipo, en un proyecto Spring Boot de ejemplo que incluye Order, Customer, PaymentService.

2. CLAUDE.md

CLAUDE.md es un archivo de memoria que Claude Code lee automáticamente al inicio de cada sesión. Es el lugar donde declaras convenciones de código, estructura de directorios, comandos de build, guías de estilo – para que el agente no tenga que preguntar cada vez.

# CLAUDE.md

## Arquitectura
- Package `com.nonladev.order`: dominio Order, Customer
- Package `com.nonladev.payment`: PaymentService, PaymentGateway (interface)

## Convenciones
- Siempre escribe tests JUnit 5 + AssertJ para métodos públicos nuevos
- No uses `@Autowired` field injection, solo constructor injection
- Ejecuta `mvn verify` antes de reportar "completado"

## Comandos de uso frecuente
- Build: `mvn -q clean verify`
- Ejecutar localmente: `mvn spring-boot:run`

Claude lee este archivo antes de ejecutar cualquier tarea en la sesión. Si solicitas “añadir un método de reembolso para PaymentService”, el agente sabrá automáticamente usar constructor injection y escribir tests – sin necesidad de recordarle.

Nota: No abarroques CLAUDE.md con demasiados detalles. Un archivo largo consume la ventana de contexto desde el inicio de la sesión, cuando la mayoría del contenido no es relevante para la tarea actual.

3. Permissions

Permissions controla qué herramientas puede usar Claude y cuáles quedan bloqueadas – es importante porque el agente tiene permiso para ejecutar comandos reales en shell.

{
  "permissions": {
    "allow": [
      "Bash(mvn *)",
      "Edit(src/main/java/**)"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Edit(src/main/resources/application-prod.properties)"
    ]
  }
}

Este archivo settings.json se coloca en el directorio .claude/. La línea allow permite al agente ejecutar mvn y editar archivos en src/main/java, pero la línea deny bloquea absolutamente comandos recursivos de eliminación y bloquea la edición del archivo de configuración de producción. Cuando Claude quiere exceder los permisos, te pedirá confirmación antes de ejecutar.

Error común: dejar permisos demasiado amplios (allow: ["*"]) permite al agente ejecutar cualquier comando sin preguntar – es peligroso con archivos de configuración sensibles o secretos.

4. Plan Mode

Plan Mode obliga a Claude a presentar un plan antes de tocar el código. Tú revisas el plan, lo editas si es necesario, y luego lo ejecutas.

> Añadir funcionalidad de reembolso parcial para PaymentService

[PLAN MODE]
1. Añadir método refundPartial(Order order, BigDecimal amount) a PaymentService
2. Validar amount <= order.getTotalPaid()
3. Llamar a PaymentGateway.refund(...)
4. Escribir PaymentServiceTest para 2 casos: válido, amount excede

¿Quieres que ejecute este plan? [y/n/edit]

Cuando respondes edit, Claude modificará el plan según tus sugerencias (por ejemplo, añadiendo un paso de log de auditoría) antes de tocar el código fuente real. Este enfoque es especialmente útil para tareas que modifican múltiples archivos, porque detectas errores de dirección desde la etapa de plan – en lugar de después de que el código haya sido modificado de forma desordenada.

5. Checkpoints

Checkpoints son instantáneas automáticas del proyecto en momentos importantes durante la sesión, que te permiten “rebobinar” si el agente comete un error.

# Ver historial de checkpoints en la sesión
/rewind

# Output
Checkpoint 1 - 10:02 - antes de modificar PaymentService
Checkpoint 2 - 10:05 - después de añadir refundPartial
Checkpoint 3 - 10:09 - después de modificar test (actualmente con error)

# Volver al checkpoint 2
/rewind 2

A diferencia de git commit, no necesitas crear checkpoints manualmente – Claude Code los guarda automáticamente antes de cada cambio significativo. Si el agente modifica el test de forma incorrecta (por ejemplo, comentando aserciones para que pasen), puedes rebobinar al estado anterior sin necesidad de un git reset manual.

Nota: los checkpoints solo existen dentro de la sesión actual, no reemplazan git. Deberías hacer commits reales cuando alcances un hito.

6. Skills

Skills son archivos de guía reutilizable que Claude aplica automáticamente cuando detecta una tarea apropiada – sin que necesites mencionar el nombre cada vez.

---
name: spring-boot-test-writer
description: Usar cuando necesites escribir tests para la capa service en un proyecto Spring Boot
---

Cuando escribes tests para una clase Service:
1. Usa JUnit 5 + AssertJ, no uses Hamcrest
2. Mockea dependencias con Mockito, nombra variables como `mock<Dependency>`
3. Nombra métodos de test como `should_<expected>_when_<condition>`

Este archivo se coloca en .claude/skills/spring-boot-test-writer.md. Cuando solicitas “escribir tests para PaymentService”, Claude reconoce automáticamente el skill apropiado y aplica las convenciones en él – el resultado es:

class PaymentServiceTest {

    private final PaymentGateway mockGateway = mock(PaymentGateway.class);
    private final PaymentService paymentService = new PaymentService(mockGateway);

    @Test
    void should_refundAmount_when_amountIsWithinPaidTotal() {
        Order order = new Order("ORD-1", BigDecimal.valueOf(200));

        paymentService.refundPartial(order, BigDecimal.valueOf(50));

        verify(mockGateway).refund(order.getId(), BigDecimal.valueOf(50));
    }

    @Test
    void should_throwException_when_amountExceedsPaidTotal() {
        Order order = new Order("ORD-2", BigDecimal.valueOf(100));

        assertThatThrownBy(() -> paymentService.refundPartial(order, BigDecimal.valueOf(150)))
            .isInstanceOf(IllegalArgumentException.class);
    }
}

Skills difieren de CLAUDE.md en que: CLAUDE.md siempre se carga, mientras que skills solo se cargan cuando el contexto lo requiere – ahorrando ventana de contexto para proyectos con muchas convenciones especializadas.

7. Hooks

Hooks ejecutan scripts de shell en puntos específicos del ciclo de vida del agente – por ejemplo PreToolUse (antes de llamar a una herramienta) o PostToolUse (después de llamar a una herramienta).

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit",
        "command": "mvn -q -pl . checkstyle:check"
      }
    ]
  }
}

Cada vez que Claude termina de editar un archivo (herramienta Edit), el hook ejecuta automáticamente checkstyle:check. Si el comando falla, la salida se devuelve a Claude, el agente corrige automáticamente el código según los errores de estilo – antes de reportar que la tarea está completa, sin que necesites ejecutar la comprobación manualmente.

[PostToolUse] mvn checkstyle:check
ERROR: PaymentService.java:42: Line is longer than 120 characters
→ Claude acorta automáticamente la línea 42 y ejecuta la comprobación nuevamente

Cuándo no debes usarlos: los hooks se ejecutan cada vez que se llama a una herramienta – así que si el script es pesado (compilación completa del proyecto), la sesión será notablemente más lenta. Solo conecta hooks a eventos del ciclo de vida que requieren comprobaciones rápidas.

8. MCP

MCP (Model Context Protocol) conecta Claude con sistemas externos – base de datos, APIs internas, rastreadores de incidencias – como herramientas estandarizadas.

{
  "mcpServers": {
    "postgres-orders": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres",
               "postgresql://localhost:5432/orders_db"]
    }
  }
}

Después de registrar este servidor en .claude/settings.json, puedes preguntar directamente:

> ¿Cuántas Order están en estado PENDING en la tabla orders?

[MCP: postgres-orders] SELECT COUNT(*) FROM orders WHERE status = 'PENDING';
→ 37 órdenes actualmente PENDING

Claude genera automáticamente SQL, lo ejecuta a través del servidor MCP, y devuelve el resultado real de la base de datos – sin que necesites copiar la consulta manualmente a otra terminal.

9. Plugins

Plugin es un paquete que incluye skills, servidor MCP y hooks relacionados – para que puedas instalar una vez en lugar de configurar cada parte por separado.

/plugin install spring-boot-toolkit

Este comando instala un plugin que contiene: skill para escribir tests de Spring Boot, hook que ejecuta mvn verify después de cada edición, y servidor MCP que se conecta al endpoint Spring Boot Actuator para que el agente compruebe automáticamente el estado. En lugar de que tengas que escribir 3 archivos de configuración separados (skill, hook, mcp) como en las secciones 6–8, el plugin empaqueta todo en un paquete único que puedes compartir con todo el equipo con un solo comando.

10. Context

Context es la ventana de contexto actual de la sesión – todos los archivos que se han leído, historial de conversación, salida de comandos. El comando /context te muestra cuánto está usando.

/context

Context usage: 48,200 / 200,000 tokens (24%)
- CLAUDE.md: 1,200 tokens
- Archivos leídos: PaymentService.java, Order.java, PaymentServiceTest.java (6,400 tokens)
- Conversation history: 38,000 tokens
- Tool outputs: 2,600 tokens

Cuando ves que el historial de conversación ocupa la mayor parte, sabes que deberías hacer compactación o iniciar una nueva sesión – para evitar que Claude “olvide” detalles importantes mencionados al inicio de la sesión porque se cortó cuando el contexto se llenó.

11. Slash Commands

Slash command es un atajo para tareas que ejecutas repetidamente – escribe / luego el nombre, sin necesidad de escribir el prompt completo cada vez.

---
name: review-pr
description: Revisar diff actual según checklist estándar
---

Revisar diff de código actual con checklist:
1. ¿Hay tests para la lógica nueva?
2. ¿Hay logs con información sensible (números de tarjeta, contraseñas)?
3. ¿Hay violaciones de convención de inyección de constructor?

Responde en formato: PASS/FAIL para cada elemento, con razones.

Guarda este archivo en .claude/commands/review-pr.md, luego ejecuta:

/review-pr

1. PASS - hay PaymentServiceTest para refundPartial
2. FAIL - log.info contiene order.getCardNumber() en línea 58
3. PASS - usa constructor injection

Slash command difiere de skill en que: skill se activa automáticamente según el contexto – mientras que slash command requiere que lo invoques explícitamente. Es adecuado para listas de verificación fijas como revisión de PR o notas de lanzamiento.

12. Compaction

Compaction comprime el historial de conversación largo en un resumen – liberando tokens sin perder información importante.

/compact

Antes de compactar: 182,000 / 200,000 tokens
Después de compactar:    24,000 / 200,000 tokens

Resumen conservado:
- Tarea actual: añadir refundPartial a PaymentService
- Completado: PaymentServiceTest (2 casos de test pasados)
- Pendiente: actualizar especificación OpenAPI para endpoint /refund

En lugar de que el agente olvide todo el historial cuando se llena el contexto, compaction retiene los puntos importantes (tarea actual, completada, pendiente) como un resumen breve – luego continúa la sesión con el contexto principalmente vacío. Deberías llamar a /compact activamente después de completar una subtarea grande – antes de pasar a la siguiente tarea.

13. Subagents

Subagents permite que Claude Code genere múltiples agentes secundarios que se ejecutan en paralelo – cada agente maneja una parte del trabajo independiente en un flujo de trabajo grande.

---
name: test-writer
description: Especializado en escribir tests unitarios para la clase especificada
tools: Read, Edit, Bash
---

Solo escribes tests, no modificas la lógica de negocio. Usa JUnit 5 + AssertJ.

Con este archivo de subagente en .claude/agents/test-writer.md, puedes asignar una tarea grande al agente principal – y el agente principal se la distribuye automáticamente:

> Completar módulo de reembolso: añadir lógica, escribir tests, actualizar docs

[Main agent] Distribuir trabajo entre 3 subagentes en paralelo:
  → subagent "code-writer": añadir refundPartial a PaymentService
  → subagent "test-writer": escribir PaymentServiceTest
  → subagent "doc-writer": actualizar README.md

[3 subagents se ejecutan en paralelo] ... completado en 42s

En lugar de que el agente principal procese secuencialmente cada paso (código → tests → docs, que podría tomar 3 veces el tiempo) – los subagentes procesan simultáneamente las partes de trabajo independientes, útil para flujos de trabajo de múltiples pasos que no son interdependientes.

Cuándo no debes usarlos: si los pasos son secuencialmente dependientes (por ejemplo, escribir tests requiere que el código esté listo para conocer la interfaz), ejecutar en paralelo causará errores porque el subagente de tests se ejecutaría antes de que el código exista. Solo usa subagents para tareas que realmente se pueden separar de forma independiente.

14. Conclusión

Las 12 características anteriores se dividen en tres grupos claros: grupo de orientación del agente (CLAUDE.md, Skills, Plan Mode), grupo de control de seguridad (Permissions, Checkpoints, Hooks), y grupo de extensión de capacidades (MCP, Plugins, Subagents). Context, Slash Commands y Compaction son la capa de infraestructura que ayuda al agente a funcionar eficientemente en una sesión larga. No necesitas usar las 12 características al mismo tiempo – comienza con CLAUDE.md y Permissions para tu proyecto actual, luego añade Hooks o MCP cuando tu flujo de trabajo realmente los necesite.