Permisos de Claude Code: protege .env, Git y los comandos peligrosos

Al configurar Claude Code, los desarrolladores suelen encontrarse ante una elección equivocada: confirmar constantemente comandos de lectura triviales o activar el bypass completo (--dangerously-skip-permissions) y arriesgar una filtración de .env, un git push --force accidental o un entorno de proyecto dañado.

Ninguno de los dos extremos funciona bien. La operación segura sigue el principio de mínimo privilegio: hay que separar con claridad los accesos de lectura, los permisos de escritura, la ejecución de shell y el control de versiones.

---

1. Mapa de permisos: de la lectura al impacto externo

Organiza los archivos y comandos en cuatro niveles de acceso:

Nivel	Operaciones	Política predeterminada	Ejemplos
1. Inspección de código	Leer archivos del proyecto	Permitido (sin confirmación)	cat, grep, ver código fuente en src/
2. Secretos y configuración	Acceder a .env, claves y tokens	Estrictamente prohibido	.env*, id_rsa, *.pem, credentials.json
3. Edición de archivos	Crear y modificar código	Permitido dentro del workspace	write_to_file, replace_file_content
4. Shell y Git peligrosos	Gestores de paquetes y operaciones destructivas	Requiere aprobación manual	rm -rf, git push --force, npm publish, DROP TABLE

---

2. Aislar los archivos .env y los secretos del proyecto

Transport Layer Security (TLS) cifra el tráfico de API mientras viaja por la red. No impide, sin embargo, que credenciales confidenciales lleguen a la ventana de contexto del modelo, a los registros de errores o a los resúmenes de handoff.

Para evitar que Claude Code ingiera credenciales privadas:

1. Añade a .gitignore todos los archivos de entorno que contengan secretos.
2. Proporciona una plantilla .env.example limpia con valores ficticios; así el agente conoce los nombres de variables sin ver valores de ejecución.
3. Añade una regla de límite estricta en CLAUDE.md o AGENTS.md:

## Regla de protección de secretos

- Nunca inspecciones, muestres ni transmitas contenido de `.env`, `.env.local` o archivos de claves privadas.
- Para comprobar las claves de configuración requeridas, revisa `.env.example`.

[!IMPORTANT] Gestión de claves API: tu clave API de Claude Code se configura en tu entorno local y nunca debe incluirse en archivos del repositorio. Sigue el flujo de integración de la documentación de BetterToken para Claude Code.

.gitignore evita un commit accidental, pero no impide que el agente lea un archivo. Las instrucciones de CLAUDE.md o AGENTS.md expresan intención y no son una frontera técnica. Combínalas con reglas de permisos actuales y con el sandbox del sistema operativo:

{
  "permissions": {
    "deny": [
      "Read(.env)",
      "Read(.env.*)",
      "Read(secrets/**)"
    ]
  },
  "sandbox": {
    "enabled": true,
    "failIfUnavailable": true,
    "allowUnsandboxedCommands": false,
    "filesystem": {
      "denyRead": [
        "./**/.env",
        "./**/.env.*",
        "./secrets"
      ]
    }
  }
}

El deny Read cubre las herramientas de archivos integradas y los comandos reconocidos. Un subprocess arbitrario de Python o Node puede leer de otra forma, por lo que el sandbox es necesario para el aislamiento del sistema. failIfUnavailable y allowUnsandboxedCommands cierran el acceso en vez de continuar sin aislamiento. El sandbox no funciona en Windows nativo; usa WSL2 o un contenedor. En entornos administrados, el administrador debe impedir que la configuración del proyecto debilite la policy.

---

3. Lista de comprobación priorizada para Git y comandos

Al ejecutar tareas con Claude Code, aplica primero esta jerarquía:

El agente propone un comando
  │
  ├─> ¿Contiene patrones destructivos (rm -rf, drop, force push)?
  │     └─> SÍ: Rechazarlo o ejecutarlo manualmente bajo supervisión
  │
  └─> ¿Afecta a internos de .git, archivos .env o redes externas?
        │
        ├─> SÍ: Exigir una justificación explícita y limitar el alcance
        │
        └─> NO: Aprobar su ejecución en la rama objetivo

Barreras paso a paso

1. Paso 1: bloquear mutaciones de Git. No permitas pushes automatizados directos a main sin ejecutar manualmente git diff --check y las pruebas.
2. Paso 2: aislar la instalación de paquetes. Comandos como npm install <package> o scripts curl remotos deben verificarse manualmente para evitar dependencias no confiables y riesgos de cadena de suministro.
3. Paso 3: limitar el alcance de directorios. Restringe el workspace del agente a una carpeta concreta de la funcionalidad o a un Git worktree dedicado.

---

4. El acceso a producción es una frontera independiente

Los permisos locales no sustituyen IAM, las reglas de red ni la aprobación del sistema de producción. Es preferible no dar acceso. Si el diagnóstico lo exige, emite un rol read-only de corta duración y limitado al recurso. Una escritura necesita otra aprobación con comando, destino, ventana, validación, observador y rollback. Si se desconoce el resultado, primero lee el estado real. El audit log registra identidad, recurso, acción y resultado sin secretos ni payloads sensibles; después se revocan las credenciales temporales. Nunca copies una credencial en HANDOFF.md.

5. Validar permisos en un workspace de prueba

Antes de dar a Claude Code acceso a repositorios críticos, realiza una validación en sandbox:

1. Crea una rama temporal de prueba: git checkout -b test/permission-check.
2. Añade un archivo .env ficticio con un secreto de prueba falso.
3. Pide al agente que refactorice el módulo de autenticación.
4. Comprueba que:
   • el agente no leyó el .env ficticio durante la exploración;
   • no aparecen tokens secretos en registros de errores, comentarios o git diff;
   • las pruebas unitarias se ejecutan sin acceder a archivos no autorizados.
5. Elimina la rama de prueba cuando hayas confirmado los límites.

Este límite de permisos protege las credenciales y mantiene una ejecución autónoma rápida.