Claude Code empresarial con configuración gestionada

Preludio

Imagina un equipo de ingeniería de plataforma con cuarenta desarrolladores que han adoptado Claude Code. La productividad se ha disparado. El responsable de ingeniería está encantado. Entonces entra el CISO, hace una pregunta, y la sala se queda en silencio.

"¿Cómo sabéis lo que está haciendo?"

Nadie tiene una respuesta. Cada desarrollador ha configurado Claude Code de forma independiente. Algunos le han concedido acceso completo a Bash. Otros han instalado servidores MCP de fuentes desconocidas. Unos pocos han escrito hooks personalizados que envían datos de sesión a endpoints personales. No hay política central, no hay registro de auditoría, y no hay forma de imponer una retroactivamente.

Este escenario se repite en organizaciones de todo el mundo ahora mismo. Claude Code es lo suficientemente potente como para que los desarrolladores lo adopten por su cuenta. Pero la adopción individual sin gobernanza central crea exactamente el tipo de brechas de seguridad que mantienen a los CISO despiertos por la noche.

Esta guía es la respuesta a esa pregunta. No es un documento de políticas. Es un recorrido técnico sobre cómo desplegar Claude Code en una organización con configuración gestionada centralmente que los desarrolladores no pueden anular, permisos que siguen el principio de mínimo privilegio, y hooks que te dan un registro de auditoría completo de cada sesión.

El problema

La tensión fundamental es simple. Los desarrolladores quieren autonomía. Los equipos de seguridad quieren control. Claude Code está justo en medio de esa tensión porque es un agente de IA que puede leer archivos, ejecutar comandos, hacer peticiones de red y modificar código.

Sin gestión centralizada, cada instalación de Claude Code de cada desarrollador es una isla independiente. Cada persona decide por sí misma a qué puede acceder Claude, qué comandos puede ejecutar, qué datos puede tocar. No hay forma de que la organización diga "estos son nuestros estándares" y que eso se aplique a nivel de herramienta.

El sistema de permisos por defecto de Claude Code está diseñado para desarrolladores individuales. Tiene un modelo de permisos por niveles donde las herramientas de solo lectura como lecturas de archivos y Grep no necesitan aprobación, los comandos de Bash necesitan aprobación en el primer uso, y las modificaciones de archivos necesitan aprobación en cada sesión. Eso es razonable para un desarrollador individual. Es insuficiente para una organización con cincuenta o quinientos desarrolladores que todos necesitan seguir las mismas políticas de manejo de datos.

La brecha entre la configuración individual y la política empresarial es donde vive la configuración gestionada.

El camino

Entendiendo la jerarquía de configuración

Lo primero que hay que entender es que Claude Code tiene una jerarquía de precedencia clara para la configuración. De mayor a menor prioridad, los niveles son: configuración gestionada, argumentos de línea de comandos, configuración local del proyecto en .claude/settings.local.json, configuración compartida del proyecto en .claude/settings.json, y configuración de usuario en ~/.claude/settings.json.

La configuración gestionada está en la cima. No puede ser anulada por ningún nivel por debajo de ella, incluyendo argumentos de línea de comandos. Un desarrollador no puede eludirla con un flag, un archivo de configuración local o una anulación a nivel de proyecto. Es el techo.

Esta es la base sobre la que se construye todo lo demás. Si configuras una regla de denegación en la configuración gestionada, ningún desarrollador puede deshacerla. Si estableces allowManagedHooksOnly a true, ningún desarrollador puede añadir sus propios hooks. La jerarquía no es una sugerencia. Es aplicada por el runtime.

Desplegando la configuración gestionada en tu flota

El archivo managed-settings.json reside en un directorio del sistema que requiere privilegios de administrador para modificar. Las rutas difieren según el sistema operativo.

En macOS, el archivo va a /Library/Application Support/ClaudeCode/managed-settings.json. En Linux y WSL, va a /etc/claude-code/managed-settings.json. En Windows, va a C:\Program Files\ClaudeCode\managed-settings.json.

Estos no están en el directorio home del usuario. No están en la carpeta del proyecto. Están en rutas a nivel de sistema que los desarrolladores normales no pueden escribir sin privilegios elevados.

Tienes tres mecanismos de entrega para elegir.

Despliegue basado en archivos es el más simple. Automatiza la copia del archivo usando Ansible, Chef, Puppet o un script de shell plano. Copia managed-settings.json a la ruta de sistema apropiada. Esto funciona para cualquier organización que ya gestione la configuración del sistema mediante automatización.

Despliegue MDM utiliza gestión nativa de la plataforma. En macOS, despliega a través de Jamf, Kandji o cualquier MDM que soporte preferencias gestionadas, usando el dominio com.anthropic.claudecode. En Windows, envía la configuración a través de Group Policy o Intune mediante la clave de registro HKLM\SOFTWARE\Policies\ClaudeCode con un valor Settings que contiene la configuración JSON.

Configuración gestionada por servidor envía la configuración remotamente desde la consola de administración de Claude.ai sin ningún archivo en disco. Esta es la opción más limpia para organizaciones que ya gestionan su suscripción de Anthropic centralmente.

Solo gana una fuente gestionada. La precedencia dentro del nivel gestionado es primero gestionado por servidor, luego MDM y políticas a nivel de sistema operativo, luego el archivo managed-settings.json. Las fuentes no se combinan. La fuente de mayor prioridad que exista es la que toma efecto.

El modelo de permisos que realmente funciona

La mayoría de equipos se equivocan con el modelo de permisos el primer día. El instinto es empezar abierto y bloquear cosas específicas. "Dejar que los desarrolladores hagan todo excepto estos comandos peligrosos." Eso es una batalla perdida.

Cada nueva herramienta, cada nuevo script, cada nuevo patrón necesita que alguien recuerde añadirlo a la lista de bloqueo. Siempre se escapa algo. La lista de bloqueo crece eternamente y sigue teniendo huecos.

El mejor enfoque es la lista de permitidos. Empieza sin nada permitido. Añade solo lo que tu equipo realmente necesita. La documentación de permisos soporta esto a través de un orden claro de evaluación de reglas donde las reglas de denegación se comprueban primero, luego las reglas de consulta, luego las reglas de permiso. La primera regla que coincida gana.

Una configuración inicial práctica para un managed-settings.json tiene este aspecto.

{
  "permissions": {
    "allow": [
      "Bash(npm run lint)",
      "Bash(npm run test *)",
      "Bash(npm run build)",
      "Bash(git status)",
      "Bash(git diff *)",
      "Bash(git log *)",
      "Bash(git commit *)"
    ],
    "deny": [
      "Bash(git push *)",
      "Bash(curl *)",
      "Bash(wget *)",
      "Read(./.env)",
      "Read(//**/credentials*)"
    ]
  },
  "allowManagedPermissionRulesOnly": true
}

La línea crítica es allowManagedPermissionRulesOnly. Cuando es true, la configuración de usuario y de proyecto no puede definir sus propias reglas de permiso, consulta o denegación. Solo se aplican las reglas de la configuración gestionada. Un desarrollador no puede anular tus permisos a ningún nivel.

Sin ese flag, un desarrollador podría añadir "allow": ["Bash"] a su configuración de usuario y concederse acceso irrestricto a Bash. Con el flag habilitado, sus reglas de permisos a nivel de usuario simplemente se ignoran.

Un detalle importante sobre los patrones de comodín de Bash. El espacio antes del asterisco importa. Bash(ls *) coincide con ls -la pero no con lsof, porque el espacio impone un límite de palabra. Bash(ls*) sin el espacio coincide con ambos. Claude Code también es consciente de los operadores de shell, por lo que una regla como Bash(npm run *) no permitirá accidentalmente npm run test && rm -rf /.

Bloqueando hooks

Los hooks son una de las funcionalidades más potentes de Claude Code. También son una de las mayores superficies de ataque de seguridad. Un hook es un comando de shell definido por el usuario, un endpoint HTTP o un prompt de LLM que se ejecuta automáticamente en puntos específicos de una sesión de Claude Code.

Hay múltiples eventos de hook. PreToolUse se dispara antes de que Claude use cualquier herramienta y puede aprobar, denegar o modificar la llamada a la herramienta. PostToolUse se dispara después de que una herramienta termina. Notification se dispara cuando Claude produce una notificación de estado. Stop se dispara cuando Claude termina su respuesta. SubagentStop se dispara cuando un subagente completa. Y varios más.

En un entorno no gestionado, cualquier desarrollador puede definir hooks en su configuración de usuario, configuración de proyecto o a través de plugins. Un hook malicioso o mal configurado podría exfiltrar datos a través de un endpoint HTTP, modificar las entradas de herramientas para eludir las políticas de seguridad, o alterar silenciosamente las salidas de Claude.

La solución es una configuración en tu managed-settings.json.

{
  "allowManagedHooksOnly": true
}

Cuando allowManagedHooksOnly está habilitado, cada hook definido por el usuario, cada hook de proyecto y cada hook de plugin se bloquea. Solo se ejecutan los hooks gestionados. El desarrollador los ve ejecutándose en su sesión pero no puede modificarlos, deshabilitarlos ni añadir los suyos propios.

Los hooks se capturan al inicio de la sesión. Incluso si alguien modifica un archivo de configuración a mitad de sesión, los cambios no surten efecto hasta la siguiente sesión. Claude Code avisa al desarrollador y requiere revisión antes de que algo se aplique. Esto previene que pull requests maliciosas que introducen cambios de hooks en .claude/settings.json tomen efecto inmediatamente.

Construyendo tu registro de auditoría con hooks HTTP

Ahora que solo los hooks gestionados pueden ejecutarse, puedes usarlos para construir un registro de auditoría completo. Los hooks HTTP envían la entrada JSON del evento como una petición POST a tu endpoint, con la respuesta usando el mismo formato de salida JSON que los hooks de comando.

Aquí hay una configuración de hook gestionado que envía cada uso de herramienta a tu endpoint de registro.

{
  "hooks": {
    "PostToolUse": [
      {
        "type": "http",
        "url": "https://audit.yourcompany.com/claude-code/tool-use",
        "matcher": "",
        "timeout": 5000,
        "headers": {
          "Authorization": "Bearer $AUDIT_API_KEY",
          "X-Developer-Email": "$DEVELOPER_EMAIL"
        },
        "allowedEnvVars": ["AUDIT_API_KEY", "DEVELOPER_EMAIL"]
      }
    ],
    "Stop": [
      {
        "type": "http",
        "url": "https://audit.yourcompany.com/claude-code/session-end",
        "timeout": 5000,
        "headers": {
          "Authorization": "Bearer $AUDIT_API_KEY"
        },
        "allowedEnvVars": ["AUDIT_API_KEY"]
      }
    ]
  }
}

El campo headers soporta interpolación de variables de entorno, pero solo para variables explícitamente listadas en allowedEnvVars. Esto previene la filtración accidental de secretos. Incluso si una configuración de hook hace referencia a $AWS_SECRET_KEY, se resuelve a vacío a menos que esté explícitamente aprobada en la lista allowedEnvVars.

Puedes restringir esto aún más globalmente con httpHookAllowedEnvVars en la configuración gestionada. La lista allowedEnvVars de cada hook se intersecta con la lista global. Si la lista global no incluye una variable, ningún hook puede acceder a ella independientemente de su propia configuración.

Para restricciones de URL, allowedHttpHookUrls establece una lista blanca de qué URLs pueden alcanzar los hooks. Un array vacío bloquea todos los hooks HTTP. Esto previene que cualquier hook alcance un endpoint que no hayas aprobado explícitamente.

Controlando servidores MCP y acceso a red

Los servidores MCP son otra superficie que necesita control central. Un servidor MCP es un proveedor de herramientas externo al que Claude Code puede conectarse, dándole capacidades como acceso a bases de datos, integraciones de API u operaciones del sistema de archivos más allá del directorio de trabajo.

En la configuración gestionada, allowManagedMcpServersOnly restringe qué servidores MCP están disponibles. Cuando está habilitado, solo los servidores listados en tu configuración MCP gestionada pueden ser usados. Los servidores denegados se combinan de todas las fuentes, por lo que puedes bloquear a cualquier nivel.

Para el acceso a red, la configuración del sandbox proporciona aplicación a nivel de sistema operativo. La configuración sandbox.network.allowManagedDomainsOnly asegura que solo los dominios listados en la configuración gestionada sean accesibles. Los dominios no permitidos se bloquean automáticamente sin siquiera preguntar al desarrollador.

{
  "allowManagedMcpServersOnly": true,
  "sandbox": {
    "network": {
      "allowManagedDomainsOnly": true,
      "allowedDomains": [
        "api.github.com",
        "registry.npmjs.org",
        "audit.yourcompany.com"
      ]
    }
  }
}

Esto crea una defensa por capas. Los permisos controlan lo que Claude decide hacer. El sandbox controla lo que realmente sucede a nivel de sistema operativo, incluso si una inyección de prompt elude la toma de decisiones de Claude.

Gestión de plugins con allowManagedPluginsOnly

Los plugins de Claude Code son un mecanismo de extensión potente, pero en entornos empresariales representan una superficie no controlada. Cada plugin puede inyectar system prompts, añadir servidores MCP, registrar hooks y modificar el comportamiento de Claude. Sin control central, cualquier desarrollador puede instalar cualquier plugin de cualquier marketplace.

La configuración allowManagedPluginsOnly restringe la instalación de plugins a una lista definida centralmente. Cuando está habilitada, los desarrolladores no pueden instalar plugins a través de /plugin install ni añadiendo entradas del marketplace a su configuración de usuario o proyecto. Solo están disponibles los plugins listados en la configuración gestionada.

{
  "allowManagedPluginsOnly": true,
  "enabledPlugins": [
    "typescript-lsp@claude-plugins-official",
    "commit-commands@claude-plugins-official",
    "pr-review-toolkit@claude-plugins-official",
    "security-guidance@claude-plugins-official"
  ]
}

Este es el equivalente para plugins de allowManagedPermissionRulesOnly. La lista gestionada se convierte en el conjunto completo de plugins disponibles. Los desarrolladores pueden ver qué plugins están habilitados a través de /status, pero no pueden modificar la lista.

Combina esto con allowManagedMcpServersOnly para cerrar ambas superficies de extensión simultáneamente. Los plugins que empaquetan sus propios servidores MCP están sujetos a ambas restricciones: el plugin debe estar en la lista gestionada de plugins, y cualquier servidor MCP que proporcione debe estar en la lista gestionada de servidores MCP.

Para organizaciones que evalúan nuevos plugins, el flujo de trabajo recomendado es: un miembro del equipo de seguridad instala el plugin en un entorno aislado, revisa sus permisos, comprueba su código fuente, y si se aprueba, lo añade a la configuración gestionada. El plugin queda entonces disponible para todos los desarrolladores a través del siguiente despliegue de configuración.

Plan de despliegue por fases

Desplegar la configuración gestionada en todo un equipo de ingeniería en un solo paso es tentador pero arriesgado. Si la configuración inicial es demasiado restrictiva, los desarrolladores pierden productividad y se resisten con fuerza. Si es demasiado permisiva, no has resuelto el problema de gobernanza. Un despliegue por fases te da los datos para encontrar el equilibrio adecuado.

Semana 1-2: Modo auditoría. Despliega la configuración gestionada con reglas de permiso amplias y un hook HTTP de auditoría que registra cada uso de herramienta. No restrinjas nada todavía. El objetivo es recopilar datos sobre lo que los desarrolladores realmente hacen con Claude Code. ¿Qué comandos ejecutan? ¿Qué archivos editan? ¿Qué servidores MCP usan? ¿Qué plugins tienen instalados?

{
  "hooks": {
    "PostToolUse": [
      {
        "type": "http",
        "url": "https://audit.yourcompany.com/claude-code/baseline",
        "matcher": "",
        "timeout": 5000,
        "headers": { "Authorization": "Bearer $AUDIT_API_KEY" },
        "allowedEnvVars": ["AUDIT_API_KEY"]
      }
    ]
  }
}

Semana 3: Analizar y redactar. Revisa los datos de auditoría. Identifica los comandos y patrones que aparecen en más del 80% de las sesiones de desarrolladores. Estos se convierten en tus reglas de permiso. Identifica patrones que nunca deberían ocurrir (acceder a credenciales, hacer push a main, ejecutar comandos destructivos). Estos se convierten en tus reglas de denegación. Redacta tu configuración de permisos basándote en el uso real, no en suposiciones.

Semana 4: Grupo piloto. Despliega la configuración gestionada completa a un grupo piloto de 5-10 desarrolladores. Estos deben ser desarrolladores que sean usuarios intensivos de Claude Code y que proporcionen feedback honesto. Habilita allowManagedPermissionRulesOnly y allowManagedHooksOnly para este grupo. Monitoriza los registros de auditoría buscando operaciones bloqueadas. Cada operación bloqueada es o una regla que necesita ajuste o un comportamiento que genuinamente debería bloquearse. Habla con los desarrolladores para averiguar cuál es.

Semana 5-6: Iterar y expandir. Ajusta la configuración basándote en el feedback del piloto. Expande a equipos adicionales. Cada expansión debería ser un equipo nuevo, no toda la empresa. Si un equipo tiene requisitos inusuales (equipos de ciencia de datos que necesitan diferentes comandos de Bash, equipos de infraestructura que necesitan acceso a kubectl), crea reglas de permiso específicas por equipo y documenta por qué difieren del estándar.

Semana 7+: Despliegue completo. Una vez que tres o más equipos estén funcionando con configuración gestionada sin bloqueos significativos, despliega para todos. A estas alturas tienes datos reales mostrando que la configuración funciona, feedback del piloto demostrando que no paraliza la productividad, y un proceso para manejar excepciones.

El error más común es saltarse la fase de auditoría y adivinar lo que necesitan los desarrolladores. El segundo error más común es no tener un camino de escalado para operaciones bloqueadas. Define un proceso (un canal de Slack, un formulario de Jira, un correo rápido al equipo de plataforma) donde los desarrolladores puedan solicitar excepciones. Revisa y responde dentro del mismo día laborable. Un despliegue de configuración gestionada que bloquea a un desarrollador durante un día entero porque nadie puede aprobar una excepción es un despliegue que se revierte.

Monitorización y alertas para la salud de los hooks

Los hooks gestionados son infraestructura. Como cualquier infraestructura, necesitan monitorización. Un hook de auditoría roto significa huecos en tu registro de cumplimiento. Un hook PreToolUse lento significa que la sesión de cada desarrollador se siente lenta. Un endpoint HTTP que falla significa que los eventos se están perdiendo silenciosamente.

Monitoriza la disponibilidad de tu endpoint de auditoría. Si tus hooks HTTP envían eventos a un endpoint de auditoría, monitoriza ese endpoint independientemente con tu monitorización de disponibilidad existente (Datadog, PagerDuty, Pingdom o equivalente). Un error 500 del endpoint no rompe la sesión del desarrollador, pero sí crea un hueco en tu registro de auditoría. Configura alertas para tasas de error superiores al 1% y para latencia superior a 3 segundos.

Rastrea las tasas de fallo de hooks. Si tu endpoint de auditoría recibe eventos, sabe lo que debería estar recibiendo. Compara el número de eventos recibidos por desarrollador por día contra la línea base esperada de tu fase de auditoría. Una caída repentina en los eventos de un desarrollador específico puede indicar que su configuración gestionada no se está cargando correctamente (JSON inválido, ruta de archivo incorrecta o una configuración MDM en conflicto).

Alerta sobre deriva de configuración. Usa el evento de hook ConfigChange para detectar cuándo los archivos de configuración cambian durante las sesiones activas. Esto detecta tanto modificaciones accidentales como intentos deliberados de eludir la configuración gestionada. La alerta debería llegar al equipo de plataforma, no solo a un archivo de registro.

{
  "hooks": {
    "ConfigChange": [
      {
        "hooks": [
          {
            "type": "http",
            "url": "https://alerts.yourcompany.com/claude-code/config-change",
            "timeout": 3000,
            "headers": { "Authorization": "Bearer $ALERT_TOKEN" },
            "allowedEnvVars": ["ALERT_TOKEN"]
          }
        ]
      }
    ]
  }
}

Gestión de costes y tokens mediante configuración gestionada

Para organizaciones con grandes despliegues de Claude Code, el uso de tokens y los costes de IA son una preocupación presupuestaria real. La configuración gestionada proporciona controles indirectos que limitan la exposición a costes sin limitar la productividad individual de los desarrolladores.

Restringir el acceso a modelos. Si tu plan de Anthropic incluye múltiples modelos, puedes usar la configuración gestionada para restringir qué modelos pueden usar los desarrolladores. Los modelos de mayor capacidad cuestan más por token. Restringir el trabajo de desarrollo diario a un modelo rentable mientras se permite el modelo más capaz solo para flujos de trabajo específicos mantiene los costes predecibles.

Limitar el alcance de las operaciones. Las sesiones de Claude Code más caras son aquellas donde Claude lee cientos de archivos, ejecuta docenas de comandos y genera diffs masivos. Las reglas de permisos que restringen las lecturas de archivos al directorio de código fuente del proyecto y deniegan acceso a directorios binarios grandes (node_modules, objetos .git, artefactos de compilación) reducen el uso de la ventana de contexto que impulsa los costes de tokens.

Auditar patrones intensivos en tokens. Tus hooks de auditoría PostToolUse capturan cada invocación de herramienta. Analiza estos datos buscando patrones intensivos en tokens: desarrolladores que rutinariamente piden a Claude leer directorios enteros, sesiones que generan y descartan grandes cantidades de código, y flujos de trabajo que podrían hacerse más eficientes. Estos datos informan tanto la formación como los cambios de configuración.

Denegar patrones derrochadores. Algunos comandos de Bash desencadenan operaciones costosas que generan salidas masivas. Comandos como cat en archivos grandes, find / sin restricciones de ruta, o git log sin límites pueden llenar la ventana de contexto de Claude con datos irrelevantes. Las reglas de denegación para estos patrones reducen el desperdicio de tokens:

{
  "permissions": {
    "deny": [
      "Bash(cat //**/node_modules/**)",
      "Bash(find / *)",
      "Bash(git log --all --oneline)"
    ]
  }
}

El objetivo no es microgestionar el uso sino prevenir el pequeño número de patrones que representan un coste desproporcionado. La mayoría de desarrolladores nunca activan estos patrones intencionalmente. Las reglas de denegación capturan casos accidentales y comandos iniciados por la IA que de otro modo consumirían tokens sin aportar valor.

Requisitos de cumplimiento y auditoría

La configuración gestionada no es solo una conveniencia de seguridad. Para muchas organizaciones, es un requisito de cumplimiento. Si tu empresa tiene certificación SOC 2, está pasando auditorías ISO 27001, o está sujeta a obligaciones del RGPD sobre el tratamiento automatizado de datos, necesitas controles demostrables sobre el comportamiento del agente de IA.

Los criterios de servicios de confianza de SOC 2 requieren que las organizaciones definan y apliquen controles de acceso para los sistemas que procesan datos de clientes. Una instalación no gestionada de Claude Code donde cada desarrollador establece sus propios permisos no cumple ese estándar. La configuración gestionada te da una única configuración auditable que demuestra que la sesión de Claude Code de cada desarrollador opera bajo la misma política. Tu auditor puede inspeccionar un archivo y entender lo que el agente puede y no puede hacer.

Para el cumplimiento del RGPD, la preocupación clave es el tratamiento automatizado de datos personales. Si Claude Code lee archivos que contienen información de clientes, necesitas demostrar que el tratamiento está controlado y limitado. Las reglas de denegación que bloquean el acceso a directorios de datos de producción, combinadas con hooks de auditoría que registran cada lectura de archivo, te dan la pista de evidencia que requiere el registro del Artículo 30.

Los controles del Anexo A de ISO 27001 sobre gestión de accesos (A.9) y seguridad en las operaciones (A.12) se mapean directamente a las capacidades de la configuración gestionada. La lista de permisos permitidos satisface los requisitos de control de acceso. El registro de auditoría basado en hooks satisface los requisitos de registro y monitorización. La configuración disableBypassPermissionsMode satisface el requisito de que los controles de seguridad no puedan ser eludidos por los usuarios finales.

Más allá del cumplimiento formal, muchas organizaciones tienen políticas de seguridad internas que requieren que todas las herramientas de desarrollo estén gestionadas centralmente. La configuración gestionada convierte Claude Code de una herramienta de desarrollo no gestionada en una gobernada centralmente, lo que a menudo es la diferencia entre "aprobada para uso" y "bloqueada por seguridad" en las revisiones de adquisición empresarial.

Patrones de despliegue en la práctica

La elección del mecanismo de despliegue depende de lo que tu organización ya utilice para la gestión de configuración del sistema.

Gestión de configuración basada en Git funciona bien para equipos que tratan la infraestructura como código. Almacena tu managed-settings.json en un repositorio dedicado junto con otras configuraciones del sistema. Usa un pipeline de CI/CD para validar el JSON en cada pull request, ejecutar una comprobación de esquema contra el esquema de configuración de Claude Code, y desplegar el archivo a las máquinas objetivo a través de tu herramienta de aprovisionamiento existente. Esto te da historial de versiones, revisión por pares en los cambios de política, y capacidad de reversión.

Distribución MDM para macOS a través de Jamf o Kandji es la opción más limpia para organizaciones con flotas Apple. Crea un perfil de configuración dirigido al dominio de preferencias com.anthropic.claudecode. La configuración JSON se mapea directamente al payload del perfil. Envía actualizaciones a través de tu consola MDM y toman efecto en cada máquina de desarrollador en el siguiente check-in. Este enfoque también te da informes a nivel de MDM sobre qué máquinas han recibido la configuración.

Distribución por Group Policy de Windows sigue el flujo de trabajo estándar de GPO. Crea una nueva GPO, navega a Computer Configuration > Administrative Templates, y establece el valor de registro en HKLM\SOFTWARE\Policies\ClaudeCode\Settings con tu configuración JSON como valor de cadena. Vincula la GPO a la unidad organizativa apropiada. Para dispositivos gestionados con Intune, despliega la misma clave de registro a través de un perfil de configuración.

Validación CI/CD merece añadirse independientemente de tu mecanismo de despliegue. Un paso simple del pipeline que ejecuta python -m json.tool managed-settings.json detecta errores de sintaxis antes de que lleguen a las máquinas de los desarrolladores. Una comprobación más exhaustiva valida que cada regla de permiso siga la sintaxis correcta Tool(pattern) y que todas las URLs de hooks sean alcanzables. Desplegar JSON inválido a la ruta de configuración gestionada rompe silenciosamente la configuración, lo que significa que los desarrolladores vuelven a su propia configuración sin ningún control central. Detectar errores en el pipeline previene eso.

El bloqueo empresarial completo

Uniendo todo esto, aquí hay un managed-settings.json completo que representa un despliegue empresarial de producción.

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "allow": [
      "Bash(npm run *)",
      "Bash(git status)",
      "Bash(git diff *)",
      "Bash(git log *)",
      "Bash(git commit *)",
      "Bash(* --version)",
      "Bash(* --help *)"
    ],
    "deny": [
      "Bash(git push --force *)",
      "Bash(curl *)",
      "Bash(wget *)",
      "Bash(rm -rf *)",
      "Read(./.env)",
      "Read(//**/credentials*)",
      "Read(///**/.ssh/**)"
    ]
  },
  "allowManagedPermissionRulesOnly": true,
  "allowManagedHooksOnly": true,
  "allowManagedMcpServersOnly": true,
  "disableBypassPermissionsMode": "disable",
  "sandbox": {
    "network": {
      "allowManagedDomainsOnly": true,
      "allowedDomains": [
        "api.github.com",
        "registry.npmjs.org",
        "audit.yourcompany.com"
      ]
    }
  },
  "hooks": {
    "PostToolUse": [
      {
        "type": "http",
        "url": "https://audit.yourcompany.com/claude-code/tool-use",
        "matcher": "",
        "timeout": 5000,
        "headers": {
          "Authorization": "Bearer $AUDIT_API_KEY"
        },
        "allowedEnvVars": ["AUDIT_API_KEY"]
      }
    ]
  }
}

Cada capa se aplica centralmente. Los permisos son solo gestionados. Los hooks son solo gestionados. Los servidores MCP son solo gestionados. El modo de bypass está deshabilitado. El acceso a red está restringido a dominios aprobados. Un hook de auditoría captura cada uso de herramienta. Nada se deja a la configuración individual del desarrollador.

Los desarrolladores verifican su fuente de configuración gestionada ejecutando /status en Claude Code. Pueden ver qué políticas se aplican a su sesión. Simplemente no pueden cambiarlas.

Resolución de problemas comunes de despliegue

Incluso un despliegue bien planificado encuentra problemas. Aquí están los problemas que surgen con más frecuencia y cómo resolverlos.

JSON malformado en managed-settings.json. Si el archivo contiene JSON inválido, Claude Code no puede analizarlo. El resultado es que la configuración gestionada se ignora silenciosamente y los desarrolladores vuelven a su propia configuración de usuario y proyecto. Este es el peor modo de fallo porque parece que todo funciona mientras ninguna política central se está aplicando realmente. Valida siempre tu JSON antes del despliegue. Ejecuta python -m json.tool managed-settings.json o usa jq . managed-settings.json como comprobación previa al despliegue. Si los desarrolladores reportan que /status no muestra ninguna fuente de configuración gestionada, el JSON inválido es lo primero que investigar.

Configuración MDM y basada en archivos ambas presentes. Si tienes tanto una configuración entregada por MDM como un archivo managed-settings.json en la misma máquina, solo una gana. La precedencia dentro del nivel gestionado es primero gestionada por servidor, luego MDM, luego el archivo. Las fuentes no se combinan. Si tu configuración MDM tiene permisos pero no hooks, y tu archivo tiene hooks pero no permisos, la configuración MDM gana completamente y los hooks del archivo se ignoran. Elige un mecanismo de entrega por máquina y mantente con él.

Las reglas de permisos no coinciden como se esperaba. La causa más común es confusión con comodines. Recuerda que Bash(git *) coincide con git status y git diff --staged pero no con gitk, porque el espacio antes del asterisco crea un límite de palabra. Si un desarrollador reporta que un comando que espera que esté permitido está siendo bloqueado, comprueba si el patrón en tu regla de permiso realmente coincide con la cadena completa del comando. Pide al desarrollador que comparta el comando exacto que fue bloqueado. Luego prueba el patrón contra él. También recuerda que la evaluación de reglas es denegación primero, luego consulta, luego permiso. Si tienes una regla de denegación que coincide más ampliamente de lo que pretendías, tiene precedencia sobre cualquier regla de permiso.

Los desarrolladores no pueden ver la configuración gestionada en /status. Esto normalmente significa que el archivo está en la ruta incorrecta o tiene permisos de archivo incorrectos. En macOS, verifica que el archivo está en /Library/Application Support/ClaudeCode/managed-settings.json y es legible por todos. En Linux, comprueba /etc/claude-code/managed-settings.json. En Windows, comprueba C:\Program Files\ClaudeCode\managed-settings.json. El archivo necesita ser legible por la cuenta de usuario del desarrollador, aunque no debería ser escribible por ellos. Un archivo propiedad de root con permisos 644 es la configuración correcta en macOS y Linux.

Los hooks de auditoría devuelven errores. Si tu endpoint del hook HTTP de auditoría es inalcanzable o devuelve un error, el hook falla pero Claude Code continúa operando. Los hooks no bloquean la sesión en caso de fallo por defecto. Esto significa que una interrupción de red en tu endpoint de auditoría no rompe la productividad del desarrollador, pero sí crea un hueco en tu registro de auditoría. Monitoriza la disponibilidad de tu endpoint de auditoría de forma independiente. Si necesitas que los hooks sean bloqueantes, donde un hook fallido previene que el uso de herramienta proceda, usa un hook PreToolUse en lugar de PostToolUse. Un hook PreToolUse que devuelve un error bloqueará la llamada a la herramienta por completo.

Los cambios de configuración no surten efecto a mitad de sesión. Esto es por diseño. Claude Code captura la configuración de hooks y ajustes al inicio de la sesión. Si envías un managed-settings.json actualizado mientras un desarrollador tiene una sesión activa, no verá los cambios hasta que inicie una nueva sesión. Para cambios de política urgentes, puede que necesites comunicar a los desarrolladores que deben reiniciar sus sesiones de Claude Code. No hay un interruptor remoto para sesiones activas a través de la configuración gestionada sola.

La lección

La gestión empresarial de agentes de IA no es un documento de políticas. Es una configuración desplegada centralmente que intercepta cada acción crítica del agente, aplica tus reglas de manejo de datos, y te da un registro de auditoría completo.

Las organizaciones que están desplegando Claude Code con éxito no son las que tienen las políticas más restrictivas. Son las que encontraron el equilibrio adecuado. Los desarrolladores siguen teniendo autonomía dentro de su directorio de trabajo. Todavía pueden usar Claude Code para todo lo que es bueno. Pero las barreras de seguridad son innegociables y se aplican centralmente.

El sistema de configuración gestionada es lo que hace esto posible. No la confianza. No la formación. No la documentación que la gente podría leer. Una jerarquía de configuración donde las políticas de la organización se sientan en la cima y no puedan ser anuladas en ningún nivel inferior.

Si tu equipo está usando Claude Code sin configuración gestionada, cada desarrollador está tomando decisiones de seguridad independientes sobre un agente de IA que puede ejecutar comandos arbitrarios. Para un desarrollador individual, eso está bien. Para un equipo de diez o más, es un riesgo que crece con cada persona que incorporas.

La buena noticia es que la infraestructura existe hoy. La documentación de configuración gestionada cubre cada opción. El modelo de permisos soporta control granular. El sistema de hooks te da el registro de auditoría. Todo lo que queda es desplegarlo.

Conclusión

El CISO que pregunta "¿cómo sabéis lo que está haciendo?" está haciendo la pregunta correcta en el momento equivocado. La respuesta ya debería existir antes de que surja la pregunta.

Un archivo managed-settings.json desplegado en cada máquina de desarrollador a través de tu MDM o gestión de configuración existente te da esa respuesta. Cada regla de permiso, cada hook, cada servidor MCP, cada dominio de red se define centralmente y se aplica por el runtime. El registro de auditoría captura lo que sucedió. Los permisos aseguran que solo las acciones aprobadas sean posibles.

Empieza con una lista de permitidos mínima. Despliega el archivo de configuración gestionada a un grupo de prueba. Habilita los hooks de auditoría y revisa lo que Claude Code realmente hace durante una sesión de desarrollo típica. Expande la lista de permitidos basándote en el uso real, no en suposiciones. Luego despliégalo para todos. Para un plan de despliegue semanal detallado que cubra la incorporación de equipos, formación y escalado más allá del piloto inicial, consulta nuestra guía de despliegue organizativo.

La adopción empresarial de agentes de IA para codificación no es una cuestión de si. Es una cuestión de cómo. Y el cómo es la configuración gestionada.