Explicación detallada de Claude Code /checkup: limpieza de contexto, reparación de configuración y mejora de la seguridad del agente

Introducción

Claude Code ha incorporado una verificación de configuración más potente. En la versión 2.1.205, Anthropic amplió el flujo de trabajo existente de /doctor para que pueda diagnosticar problemas de configuración y ayudar a solucionarlos. /checkup está disponible como un alias para el mismo flujo de trabajo dentro de la sesión.

El cambio puede parecer pequeño porque se activa con un solo comando de barra. En la práctica, aborda un problema común en configuraciones de Claude Code de larga duración: habilidades no utilizadas, servidores de Protocolo de Contexto de Modelo obsoletos, archivos de instrucciones demasiado grandes, hooks lentos, instalaciones desactualizadas y solicitudes de permiso repetidas que gradualmente hacen que el entorno sea más difícil de entender.

El objetivo no es solo informar que algo está mal. La verificación actualizada puede inspeccionar la configuración, explicar los cambios propuestos y solicitar aprobación antes de aplicarlos.

/checkup

También puedes usar el comando canónico:

/doctor

Una Verificación de Configuración en un Solo Comando

Según el registro de cambios de Claude Code 2.1.205, /doctor es ahora una verificación de configuración completa que puede diagnosticar y solucionar problemas, mientras que /checkup es su alias.

Esto es diferente del comando de terminal separado:

claude doctor

El comando de terminal imprime diagnósticos de instalación y configuración de solo lectura sin iniciar una sesión interactiva. El flujo de trabajo en sesión /doctor o /checkup puede ir más allá proponiendo soluciones y permitiendo que Claude coordine la limpieza a través de sus herramientas disponibles.

El creador de Claude Code, Boris Cherny, describió varias tareas que la verificación está diseñada para manejar:

1. Limpiar habilidades no utilizadas, servidores MCP y complementos.
2. Desduplicar instrucciones locales de CLAUDE.md contra las instrucciones del proyecto confirmadas.
3. Dividir un CLAUDE.md raíz demasiado grande en archivos anidados y habilidades reutilizables.
4. Identificar y deshabilitar hooks lentos.
5. Actualizar Claude Code a la versión más reciente disponible.
6. Habilitar el modo automático por defecto cuando sea apropiado.
7. Preaprobar comandos de solo lectura rechazados con frecuencia.
8. Detectar otros problemas de configuración que hacen que el entorno sea más lento o menos confiable.

El comando solicita confirmación antes de realizar cambios.

Lo que Realmente Revisa la Verificación

1. Habilidades, Servidores MCP y Complementos No Utilizados

Claude Code puede ampliarse con habilidades, complementos, hooks y servidores MCP. Estas integraciones son útiles, pero una configuración madura a menudo acumula componentes que ya no son

relevante.

Es posible que se haya añadido un servidor MCP para un sistema de seguimiento de incidencias antiguo. Puede que se haya creado una habilidad para un flujo de trabajo que el equipo ya no utiliza. Un plugin podría seguir habilitado aunque sus comandos hayan sido reemplazados.

La revisión puede detectar esos componentes no utilizados y proponer su eliminación o desactivación.

Esto es importante porque las herramientas y las instrucciones pueden consumir atención y contexto incluso cuando no están ayudando activamente en la tarea actual. Menos integraciones irrelevantes también facilitan la auditoría del modelo de permisos.

2. Instrucciones CLAUDE.md duplicadas o demasiado extensas

Los archivos CLAUDE.md proporcionan instrucciones persistentes para Claude Code. Pueden contener comandos de compilación, convenciones de codificación, notas arquitectónicas, requisitos de prueba y reglas específicas del proyecto.

Estos archivos se cargan en el contexto de la sesión. Anthropic recomienda mantener cada archivo conciso y revisar periódicamente los archivos de instrucciones anidados para detectar reglas obsoletas o conflictivas.

Con el tiempo, un proyecto puede desarrollar varios problemas comunes:

• La misma regla aparece tanto en archivos locales como en los registrados.
• Las instrucciones antiguas permanecen después de que la base de código cambie.
• Un archivo raíz se convierte en una larga colección de procedimientos no relacionados.
• Las reglas de todo el equipo y las reglas específicas de un directorio se mezclan.
• Los flujos de trabajo detallados se almacenan en CLAUDE.md, aunque funcionarían mejor como habilidades bajo demanda.

La revisión puede comparar las instrucciones locales y las del proyecto, identificar duplicaciones y sugerir una estructura más enfocada.

Una disposición práctica podría ser así:

proyecto/
├── CLAUDE.md
├── .claude/
│   ├── rules/
│   │   ├── frontend.md
│   │   ├── backend.md
│   │   └── testing.md
│   └── skills/
│       └── release/
│           └── SKILL.md
└── packages/
    └── api/
        └── CLAUDE.md

El archivo raíz puede contener solo las reglas necesarias en todo el repositorio. Las instrucciones más específicas se pueden cargar cuando Claude trabaja dentro del directorio correspondiente, mientras que los procedimientos reutilizables pueden convertirse en habilidades que se cargan cuando se invocan.

3. Hooks lentos o redundantes

Los hooks son acciones deterministas que se ejecutan en puntos específicos del ciclo de vida de Claude Code. Pueden formatear archivos, validar comandos, aplicar políticas, enviar notificaciones o integrar Claude Code con sistemas internos.

Un hook solo es útil cuando su valor justifica su costo. Un script que añade dos o tres segundos a cada llamada de herramienta puede generar una gran demora en una sesión larga.

La revisión puede ayudar a identificar hooks que sean:

• Consistentemente lentos.
• Que se activen con más frecuencia de la prevista.
• Que dupliquen otro paso de validación.
• Que hagan referencia a scripts que ya no existen.
• Que produzcan errores que el usuario ha aprendido a ignorar.
• Que ya no estén conectados a un flujo de trabajo activo.

Desactivar un hook innecesario no solo mejora la velocidad. También reduce el ruido, facilitando la detección de fallos importantes.

4. Problemas de instalación y actualización

Un lanzador roto, una instalación desactualizada o una actualización parcial pueden generar un comportamiento confuso. La revisión de configuración puede inspeccionar el estado de la instalación y recomendar actualizar Claude Code.

Para verificar la versión instalada manualmente, use:

claude --version

El método exacto de actualización depende de cómo se haya instalado Claude Code.

Las implementaciones empresariales gestionadas pueden fijar intencionalmente una versión, por lo que los usuarios no deben anular la política de la organización simplemente porque exista una versión más reciente.

5. Solicitudes Repetidas de Permiso de Solo Lectura

Claude Code utiliza un sistema de permisos que separa las inspecciones de bajo riesgo de las acciones que modifican el entorno.

La documentación de seguridad de Anthropic establece que un conjunto integrado de comandos de solo lectura, incluidos comandos como ls, cat y git status, puede ejecutarse sin solicitar confirmación. Los comandos que editan archivos, ejecutan operaciones de Bash potencialmente modificadoras o acceden a sistemas adicionales pueden requerir aprobación.

Si un usuario rechaza repetidamente o aprueba manualmente un comando inofensivo de solo lectura, la verificación puede sugerir una regla de permiso más clara. El objetivo es reducir la fatiga de las solicitudes sin otorgar acceso amplio de escritura.

Una buena regla de permiso debe ser específica. Aprobar un patrón concreto de solo lectura es más seguro que permitir una categoría completa de shell o herramienta.

Por Qué es Importante el Mantenimiento del Contexto

Un agente de codificación de IA debe encajar varios tipos de información en un solo contexto de trabajo:

• La conversación actual.
• Archivos fuente relevantes.
• Resultados de herramientas y salida de comandos.
• Instrucciones de CLAUDE.md.
• Descripciones de habilidades.
• Definiciones de herramientas MCP.
• Planes, estado de tareas y hallazgos intermedios.

La ventana de contexto es finita. Una gran cantidad de información de configuración irrelevante puede dejar menos espacio para el problema real.

Esto no significa que cada habilidad instalada o servidor MCP se cargue automáticamente por completo. Claude Code utiliza mecanismos como cuerpos de habilidades bajo demanda y descubrimiento de herramientas para controlar el uso del contexto. Aun así, la configuración innecesaria crea complejidad adicional y aumenta la probabilidad de que instrucciones desactualizadas o integraciones influyan en una sesión.

Por lo tanto, una configuración saludable necesita el mismo tipo de mantenimiento que un proyecto de software:

1. Eliminar lo que ya no se usa.
2. Mantener las instrucciones globales breves.
3. Mover procedimientos especializados a archivos o habilidades con alcance definido.
4. Auditar integraciones y permisos.
5. Medir el costo de los ganchos.
6. Revisar la configuración después de cambios importantes en el proyecto.

Del Diagnóstico a la Limpieza Asistida

Las herramientas de diagnóstico anteriores a menudo se detenían después de enumerar errores. El usuario aún tenía que entender cada advertencia, encontrar el archivo relevante, decidir una solución y aplicarla manualmente.

La verificación en sesión actualizada sigue un patrón más activo:

1. Inspeccionar el entorno actual.
2. Identificar problemas específicos.
3. Estimar el beneficio de una limpieza.
4. Presentar los cambios propuestos.
5. Permitir que el usuario elija una limpieza completa, correcciones seleccionadas o una opción solo de informe.
6. Aplicar solo los cambios aprobados.
7. Dejar las modificaciones de archivos visibles para su revisión.

Esto hace que el flujo de trabajo se asemeje más a un asistente de mantenimiento interactivo que a un informe de errores pasivo.

El paso de aprobación es importante. Una herramienta no debe

eliminar silenciosamente una habilidad del proyecto, reescribir archivos de instrucciones o cambiar el comportamiento de los permisos simplemente porque considera que la configuración es ineficiente.

Mejoras de seguridad en torno a los comandos autónomos

La misma versión también incluyó cambios destinados a reducir el riesgo cuando Claude Code actúa de forma más autónoma.

Protección contra aprobaciones falsificadas en registros de sesión

Las notificaciones de tareas en segundo plano ahora indican explícitamente cuando no hubo intervención humana. Esto busca evitar que el texto dentro de una transcripción se confunda con una aprobación real del usuario.

Para un agente, la diferencia entre "la transcripción contiene texto similar a una aprobación" y "el usuario realmente aprobó esta acción a través de la interfaz" es fundamental. Las decisiones sensibles a la seguridad necesitan un canal de aprobación confiable.

Confirmación adicional para comandos rm -rf riesgosos

El registro de cambios también señala una mejora en el modo automático: Claude Code pregunta antes de ejecutar rm -rf cuando la ruta contiene una variable que no puede resolver a partir del contexto.

Un ejemplo peligroso es:

rm -rf "$TARGET_DIR/"

Si TARGET_DIR está vacío o se expande incorrectamente, el resultado puede ser muy diferente al que pretendía el autor del script.

La lección correcta no es que un mensaje de confirmación haga seguros los comandos destructivos del shell. Los usuarios aún deben inspeccionar la ruta resuelta, usar un entorno aislado o desechable cuando sea posible, mantener copias de seguridad y evitar comandos de eliminación amplia en sistemas de producción.

La autonomía necesita límites

La versión combina dos objetivos que pueden parecer contrapuestos:

• Reducir interrupciones innecesarias para tareas rutinarias y de solo lectura.
• Añadir confirmaciones más sólidas en torno a acciones inciertas o destructivas.

Estos objetivos trabajan juntos. Un agente útil debe moverse rápido dentro de un área segura bien definida y disminuir la velocidad cuando se acerca a un límite con consecuencias irreversibles.

/doctor, /checkup y claude doctor

Los nombres similares pueden resultar confusos.

Para la mayoría de los usuarios que desean que Claude inspeccione y ayude a limpiar la configuración activa, /doctor o /checkup es el comando relevante.

Para scripts, comprobaciones de soporte o diagnósticos rápidos de instalación fuera de una sesión, claude doctor es más adecuado.

Una forma segura de ejecutar /checkup

Paso 1: Verificar el estado actual del repositorio

Antes de permitir que una herramienta modifique archivos de configuración, asegúrese de que el trabajo importante esté confirmado o respaldado.

git status

Revise los archivos no confirmados y evite mezclar cambios de código no relacionados con la limpieza de configuración.

Paso 2: Iniciar Claude Code en el proyecto correspondiente

cd /ruta/al/proyecto
claude

Ejecutar la verificación desde el repositorio correcto es importante porque las instrucciones del proyecto, los hooks, los plugins y la configuración de MCP pueden estar limitados al ámbito.

Paso 3: Ejecutar la verificación

/checkup

Lea el informe antes de aceptar cambios.

Paso 4: Elegir el alcance

Dependiendo de lo que Claude

Basándose en los resultados, la interfaz puede ofrecer opciones como:

• Aplicar la limpieza recomendada.
• Seleccionar categorías individuales.
• Mantener la configuración actual y generar un informe.
• Discutir una recomendación antes de decidir.

Prefiera la limpieza selectiva cuando el repositorio tenga herramientas internas personalizadas o una configuración de equipo compartida.

Paso 5: Revisar el Diff

Después de que los archivos de configuración cambien, inspecciónelos:

git diff

Preste especial atención a:

• CLAUDE.md y CLAUDE.local.md.
• Archivos dentro de .claude/.
• Definiciones de hooks.
• Configuraciones de plugins.
• Configuración de MCP.
• Reglas de permisos.
• Cualquier skill generado.

Paso 6: Probar un Flujo de Trabajo Normal

Ejecute una tarea que represente el uso diario. Confirme que las herramientas necesarias siguen funcionando, las instrucciones relevantes aún se cargan, los hooks siguen aplicando reglas importantes y los avisos de permisos se comportan como se espera.

Paso 7: Confirmar la Limpieza por Separado

Cuando la configuración compartida del proyecto cambie, use un commit específico para que los compañeros puedan revisarlo y revertirlo de forma independiente.

git add CLAUDE.md .claude/
git commit -m "chore: limpiar la configuración de Claude Code"

Ajuste las rutas para que coincidan con los archivos que realmente cambiaron.

Cuándo No Aceptar la Limpieza Automática de Inmediato

No apruebe todas las recomendaciones sin revisar cuando:

• El repositorio utiliza configuraciones gestionadas por la organización.
• Los servidores MCP proporcionan integraciones críticas para el negocio.
• Los hooks aplican políticas de seguridad o cumplimiento normativo.
• CLAUDE.md contiene duplicación intencional para portabilidad.
• El proyecto fija Claude Code a una versión probada.
• Varios equipos dependen del mismo plugin o jerarquía de instrucciones.
• La limpieza propone cambiar el comportamiento de los permisos.
• El árbol de trabajo contiene cambios no confirmados no relacionados.

En esos casos, use la verificación primero como un informe de auditoría. Discuta o aplique los cambios a través del proceso de revisión normal del equipo.

Preguntas Frecuentes

¿Qué es el comando /checkup de Claude Code?

/checkup es un alias del flujo de trabajo /doctor expandido dentro de la sesión, introducido en Claude Code 2.1.205. Audita problemas de configuración y puede proponer correcciones para la configuración, el contexto, las integraciones, los hooks, el estado de la instalación y problemas relacionados.

¿Es /checkup diferente de /doctor?

En las versiones actuales de Claude Code, /checkup es un alias de /doctor. Ambos invocan la misma verificación completa de configuración dentro de una sesión interactiva de Claude Code.

¿claude doctor es lo mismo que /doctor?

No. claude doctor se ejecuta desde la terminal e imprime diagnósticos de solo lectura sobre la instalación y la configuración sin abrir una sesión. El comando de barra diagonal puede coordinar correcciones después de solicitar aprobación.

¿Puede /checkup eliminar skills o servidores MCP automáticamente?

El flujo de trabajo puede identificar componentes no utilizados y proponer una limpieza, pero está diseñado para preguntar antes de realizar cambios. Los usuarios deben revisar cada eliminación propuesta, especialmente en proyectos compartidos o gestionados.

¿Por qué un CLAUDE.md grande afecta a Claude Code?

Las instrucciones de CLAUDE.md entran en el contexto de la sesión, por lo que los archivos largos o duplicados consumen espacio que de otro modo podría usarse para la tarea activa. Anthropic recomienda instrucciones concisas y archivos con alcance definido para proyectos grandes.

¿Debería sacarse todo procedimiento de CLAUDE.md?

No. Las instrucciones estables

Los datos del proyecto, las reglas de codificación y los comandos requeridos deben estar en CLAUDE.md. Los procedimientos largos y reutilizables suelen ser más adecuados para las habilidades, ya que su contenido completo se carga solo cuando es necesario.

¿El comando /checkup hace que el modo automático sea completamente seguro?

No. Puede mejorar los valores predeterminados y agregar protecciones, pero los usuarios siguen siendo responsables de revisar los comandos y permisos. Las operaciones destructivas, las escrituras externas, el acceso a producción y el manejo de credenciales aún requieren controles cuidadosos.

¿Con qué frecuencia debo ejecutar la verificación de configuración?

No hay una frecuencia requerida. Es útil después de cambios importantes en la configuración, cuando Claude Code se siente más lento o menos consistente, después de agregar varias integraciones, o como parte de una revisión periódica de mantenimiento del proyecto.

Herramientas relacionadas

• Claude Code: La herramienta de codificación agente de Anthropic para terminales, IDE, escritorio y web.
• Claude Code Skills: Cree procedimientos reutilizables y bajo demanda que amplíen Claude Code.
• Model Context Protocol en Claude Code: Conecte Claude Code a herramientas externas, APIs, bases de datos y servicios.
• Claude Code Hooks: Ejecute automatización determinista en puntos definidos del ciclo de vida del agente.
• Claude Code Plugins: Empaquete y distribuya habilidades, agentes, hooks e integraciones MCP.
• Claude Agent SDK: Construya agentes programables con las mismas herramientas principales y bucle de agente que utiliza Claude Code.

Enlaces relacionados

• Claude Code Changelog: Historial oficial de versiones, incluyendo los cambios de la verificación de configuración de la versión 2.1.205.
• Claude Code Commands Reference: Referencia para comandos de barra incorporados y habilidades empaquetadas.
• Claude Code CLI Reference: Referencia oficial para comandos de terminal y banderas CLI.
• Cómo Claude Recuerda un Proyecto: Guía para estructurar y mantener archivos CLAUDE.md.
• Seguridad de Claude Code: Comportamiento de permisos, sandboxing, controles de aprobación y guía de seguridad.
• Configuración de Claude Code: Ámbitos de configuración, ajustes gestionados, plugins, políticas MCP y controles del sistema de archivos.
• Solución de problemas de Claude Code: Guía oficial de diagnóstico y recuperación.
• Automatizar acciones con Hooks: Guía práctica para crear y auditar hooks del ciclo de vida.

Resumen

Claude Code 2.1.205 transforma /doctor en un flujo de trabajo más amplio de mantenimiento de configuración y agrega /checkup como un alias. El comando puede inspeccionar extensiones no utilizadas, instrucciones duplicadas, archivos CLAUDE.md sobredimensionados, hooks lentos, problemas de instalación,

y comportamiento de permisos repetitivo.

La parte más útil de la actualización no es que oculta el mantenimiento detrás de un solo comando. Es que el flujo de trabajo puede explicar los cambios propuestos y mantener al usuario involucrado antes de modificar el entorno.

El lanzamiento también refuerza un patrón importante para las herramientas agentivas: el trabajo rutinario de solo lectura debería requerir menos fricción, mientras que las operaciones inciertas o destructivas deberían contar con salvaguardas más sólidas.

Una configuración más saludable de Claude Code no es la que tiene más habilidades, hooks e integraciones, sino aquella donde cada componente cargado tiene un propósito claro y cada acción poderosa tiene un límite apropiado.