Funciones desacertadas de Claude Code: en qué falla su flujo de trabajo con agentes

Los defectos de Claude Code son, sobre todo, problemas de límites

El error más costoso de Claude Code que he visto no fue una modificación incorrecta del código. Fue una modificación correcta realizada en un estado inadecuado del repositorio.

Un desarrollador pidió a Claude Code que «actualizara el middleware de autenticación y ejecutara las pruebas». El árbol de trabajo ya contenía una migración sin confirmar de otra tarea. Claude inspeccionó suficientes archivos para entender el middleware, modificó la implementación correcta, ejecutó un formateador e informó de que había terminado correctamente. El diff resultante era técnicamente plausible, pero mezclaba dos cambios sin relación y hacía casi imposible la revisión posterior.

Esa es la lección incómoda que hay detrás de muchos defectos de Claude Code: el sistema suele hacer exactamente lo que su flujo de trabajo fomenta. El problema es que un agente con acceso al sistema de archivos, acceso al shell, memoria en archivos de instrucciones y un objetivo conversacional no respeta de forma natural los límites que los desarrolladores dan por supuestos.

Algunas críticas describen debilidades reales del producto. Otras describen decisiones deliberadas que se vuelven peligrosas cuando se tratan como valores predeterminados invisibles. La pregunta útil no es si Claude Code debería ser «más autónomo» o «menos autónomo». Es dónde termina la autonomía, cómo se representa ese límite y si el desarrollador puede observar lo que ocurrió.

El valor predeterminado sorprendente: el contexto no implica aislamiento

Claude Code está diseñado para operar en un directorio de trabajo real. Puede inspeccionar el repositorio, editar archivos, invocar herramientas e iterar a partir de la salida de los comandos. Eso resulta mucho más útil que pedir a un modelo que devuelva un parche a partir de una petición abstracta.

También significa que el directorio actual forma parte del estado efectivo del agente.

En la práctica, Claude Code puede encontrarse con:

• Cambios sin confirmar de otra tarea
• Archivos generados que parecen fuentes autorizadas
• Configuración local que difiere de la de CI
• Credenciales o variables de entorno accesibles mediante herramientas
• Árboles de trabajo, repositorios anidados o directorios enlazados simbólicamente
• A CLAUDE.md Un archivo de instrucciones que cambia el comportamiento sin aparecer en la petición
• Scripts de compilación que acceden a la red o realizan operaciones de limpieza destructivas

El agente puede detectar estas condiciones, pero detectarlas no equivale a imponer aislamiento. Un modelo puede decir «he encontrado cambios ajenos a esta tarea» y aun así continuar si la petición del usuario parece clara.

Una sesión disciplinada comienza con una comprobación explícita del estado:

git status --short
git branch --show-current
git diff --stat
pwd

También prefiero indicar el límite en la primera petición:

Work only on the request in this session. Do not modify existing unrelated changes.
Before editing, report the current branch, dirty files, and the files you intend to change.
Do not commit, reset, checkout, or delete files.

Esto parece repetitivo hasta que una sesión sale mal. Las instrucciones del agente no son controles de acceso. Son directrices de comportamiento, y las directrices de comportamiento son probabilísticas.

La decisión de diseño del producto es comprensible: obligar a que cada tarea se ejecute en un entorno aislado desechable haría que los flujos de trabajo habituales fueran más lentos y menos cómodos. Pero el comportamiento predeterminado sigue dejando demasiada responsabilidad al usuario para comprender el estado del repositorio antes de delegar.

CLAUDE.md Es potente y, por tanto, fácil de malinterpretar

Las instrucciones del proyecto son una de las mejores funciones de Claude Code. Permiten definir una sola vez los comandos de prueba, las restricciones arquitectónicas, las convenciones de nomenclatura y las expectativas de revisión, en lugar de repetirlos en cada petición.

También constituyen un acoplamiento oculto.

Un repositorio puede contener instrucciones que indiquen a Claude que debe:

• Ejecutar un gestor de paquetes concreto
• Dar preferencia a un directorio frente a otro
• Actualizar las instantáneas
• Evitar modificar archivos generados
• Usar un comando de despliegue o de base de datos
• Leer archivos de instrucciones adicionales

El usuario ve la tarea, pero el agente ve la tarea junto con una jerarquía de instrucciones. Cuando el comportamiento te sorprenda, inspecciona las instrucciones efectivas en lugar de asumir que el modelo ignoró la petición.

Mantén las instrucciones del proyecto breves y operativas:

# Repository instructions

- Run `npm test` for the unit suite.
- Run `npm run lint` before describing the work as complete.
- Do not edit files under `generated/`; update the source and regenerate only when requested.
- Never run production deployment commands.
- Preserve unrelated working-tree changes.

Evita incluir objetivos vagos como «tomar siempre la mejor decisión arquitectónica» en este archivo. Las instrucciones amplias aumentan el margen de decisión del agente precisamente donde quieres un comportamiento predecible.

Límites de control: la confirmación no es un modelo de seguridad

El sistema de permisos de Claude Code ofrece un mecanismo de control útil, pero es fácil sobreestimar lo que garantiza.

Una solicitud de confirmación suele responder a una pregunta concreta: ¿debe ejecutarse ahora esta acción de la herramienta? No responde necesariamente a lo siguiente:

• ¿Es seguro el comando desde el punto de vista semántico?
• ¿Comprendió el modelo los efectos secundarios del comando?
• ¿Está la ruta de destino dentro del proyecto previsto?
• ¿Invocará un script comandos adicionales?
• ¿Envía el comando código fuente o secretos a través de la red?
• ¿Es reversible el cambio?

Un comando aparentemente inofensivo puede ocultar un comportamiento considerable:

npm run test

El script podría eliminar una caché, iniciar un contenedor, acceder a un servicio remoto o ejecutar un hook de posinstalación. Claude Code puede pedir permiso para ejecutar el comando, pero no puede convertir un comando de shell en un límite de capacidades completamente verificado.

Los permisos a nivel de proyecto pueden reducir las solicitudes de confirmación rutinarias:

{
  "permissions": {
    "allow": [
      "Bash(npm test)",
      "Bash(npm run lint)",
      "Bash(git diff -- *)"
    ],
    "deny": [
      "Bash(rm *)",
      "Bash(git reset *)",
      "Bash(git checkout *)",
      "Read(.env)",
      "Read(.env.*)",
      "Read(secrets/**)"
    ]
  }
}

Trata esto como documentación de políticas y una forma de reducir la fricción, no como un entorno aislado. Los patrones deben ser restrictivos. Permitir Bash(npm *) es práctico, pero autoriza todos los scripts de npm, incluidos los que quizá no hayas inspeccionado.

La distinción práctica es la siguiente:

Para trabajos de gran impacto, utiliza aislamiento a nivel del sistema operativo: un worktree desechable, un contenedor, credenciales restringidas y una política de red adecuada para la tarea. Las solicitudes de permiso de Claude Code complementan esos controles; no los sustituyen.

La observabilidad es menor de lo que sugiere la transcripción

La transcripción de un agente parece ofrecer observabilidad porque contiene mensajes como «Inspeccionaré las rutas», llamadas a herramientas, salidas de comandos y un resumen final. Pero una transcripción no es lo mismo que un registro de auditoría.

Las preguntas importantes que suelen quedar sin respuesta son:

• ¿Qué archivos se leyeron pero no se mencionaron?
• ¿Qué archivos de instrucciones influyeron en la decisión?
• ¿Qué variables de entorno estaban visibles exactamente?
• ¿Invocó un script de shell procesos secundarios?
• ¿Qué comandos modificaron el estado?
• ¿Qué consideraba el modelo que se había verificado y qué se había inferido únicamente?
• ¿Se volvió a intentar un comando fallido con una interpretación diferente?

Claude Code proporciona controles interactivos útiles, como /status, /permissions, /compact, /clear, /rewindy /doctor. Úsalos, pero comprende su alcance. Te ayudan a inspeccionar o gestionar la sesión actual; no crean automáticamente un registro persistente de cambios adecuado para analizar incidentes.

Para trabajar en repositorios, crea tu propio registro sencillo de evidencias:

git status --short
git diff --name-only
git diff --check
npm test
git diff --stat

Un hook puede añadir mecanismos para hacer cumplir las reglas de uso de las herramientas. Por ejemplo, un hook PreToolUse puede inspeccionar un comando Bash propuesto y rechazar operaciones especialmente arriesgadas:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "python3 .claude/hooks/reject-dangerous.py"
          }
        ]
      }
    ]
  }
}

Un hook mínimo podría leer la entrada de la herramienta proporcionada por el protocolo de hooks de Claude Code y rechazar comandos que contengan operaciones destructivas conocidas:

#!/usr/bin/env python3
import json
import sys

event = json.load(sys.stdin)
command = event.get("tool_input", {}).get("command", "")

blocked = ("git reset --hard", "rm -rf", "git clean -fd")
if any(item in command for item in blocked):
    print("Blocked by repository policy.", file=sys.stderr)
    sys.exit(2)

sys.exit(0)

Los campos exactos de los eventos de hooks y la configuración admitida pueden variar según la versión de Claude Code, así que verifica el esquema local antes de estandarizar este patrón. El principio de diseño fundamental se mantiene: incorpora los controles no negociables a políticas ejecutables, no solo a texto.

Modo de fallo: el agente prioriza completar la tarea

La interacción recompensa de forma natural al modelo de lenguaje por producir avances. Si las pruebas fallan, tiende a investigar. Si aparece un error de tipos, tiende a corregirlo. Ese ciclo es valioso, pero puede convertir «realizar el cambio solicitado» en «hacer que el repositorio pase todas las comprobaciones por cualquier medio que parezca razonable en el contexto local».

Entre los síntomas habituales se incluyen:

• Actualizar una instantánea en lugar de corregir el comportamiento
• Ampliar una aserción de prueba para aceptar una regresión
• Añadir una rama de compatibilidad sin confirmar que sea necesaria
• Modificar directamente la salida generada
• Ejecutar un formateador sobre archivos no relacionados
• Considerar que superar una prueba de alcance limitado demuestra que la funcionalidad está completa
• Repetir un comando fallido sin cambiar el supuesto en el que se basa

La solución consiste en definir condiciones de parada, no solo objetivos:

Implement the parser change.
Run only the parser unit tests first.
Do not modify tests unless a test is demonstrably incorrect.
Do not update snapshots without showing the before/after behavior.
Stop after two failed repair attempts and summarize the failure.
Finish with the exact files changed and commands run.

Esto reduce la tendencia del agente a convertir la incertidumbre en más modificaciones.

Un patrón especialmente eficaz es la ejecución en dos fases:

1. Solicita una investigación y una propuesta de plan sin realizar modificaciones.
2. Revisa la lista de archivos, los riesgos y la estrategia de pruebas.
3. Inicia una segunda solicitud que autorice la implementación dentro de esos límites.

La planificación no es una garantía. Es un punto de control en el que una persona puede detectar una interpretación incorrecta antes de que se convierta en un diff.

Modo de fallo: la compresión del contexto pierde detalles operativos

Las sesiones largas son útiles para depurar, pero con el tiempo requieren compactación o resumen. El modelo conserva una representación comprimida en lugar de todas las salidas anteriores de las herramientas. Los objetivos generales suelen mantenerse. Las restricciones específicas no siempre se conservan igual de bien.

Esto genera un problema habitual: al principio de la sesión dices «no toques los archivos de migración» y, más adelante, el agente encuentra una prueba de esquema que falla y propone precisamente eso.

Para trabajos con restricciones relevantes:

• Reitera las condiciones que deben mantenerse después de /compact
• Mantén la lista de archivos activos en un archivo de notas visible o en una incidencia
• Utiliza sesiones separadas para tareas no relacionadas
• Prefiere una sesión nueva a una extremadamente larga y sin un rumbo claro
• Vuelve a ejecutar git diff --name-only antes de aceptar el resultado

El equilibrio es sencillo. El contexto persistente mejora la continuidad, mientras que un contexto nuevo mejora la previsibilidad. Ninguno es superior en todos los casos.

Modo de fallo: «terminado» significa que parece razonable en el entorno local

Claude Code puede ejecutar pruebas, pero ejecutarlas no implica que sean adecuadas. Puede elegir el comando pertinente más rápido, seguir las instrucciones del repositorio o detenerse después de un comando que parezca suficiente. Un resultado satisfactorio puede significar únicamente que una ruta de ejecución funcionó en un entorno local concreto.

Define la verificación de forma explícita y exige evidencias:

Before finishing:
- Run `git diff --check`.
- Run `npm test -- --runInBand`.
- Report the exact commands and whether each passed.
- Distinguish tests run from tests not run.
- Do not claim production behavior was verified.

En sistemas que utilizan una API, pide al agente que inspeccione las estructuras de las solicitudes y las respuestas en lugar de inferirlas a partir de un wrapper. Una llamada mínima a la API de Claude podría tener este aspecto:

import os
from anthropic import Anthropic

client = Anthropic(api_key=os.environ["ANTHROPIC_API_KEY"])

response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=512,
    system="Return JSON only.",
    messages=[
        {"role": "user", "content": "Classify this event: login_failed"}
    ],
)

print(response.model_dump_json(indent=2))

La respuesta contiene bloques de contenido estructurados, no simplemente una cadena. El código que asume que response.content[0].text siempre es el resultado semántico completo se vuelve frágil cuando el uso de herramientas o varios bloques entran en el flujo de trabajo.

Este es otro problema de límites: el resumen en lenguaje natural del modelo no es un contrato de interfaz. Analiza las salidas estructuradas, valídalas y conserva los metadatos originales de las solicitudes cuando la depuración lo requiera.

¿Qué críticas corresponden a defectos del producto?

Algunos comportamientos merecen mejoras a nivel de producto:

• Puede ser difícil comprender de un vistazo las instrucciones y los permisos importantes que están vigentes.
• Es demasiado fácil confundir un resumen final en lenguaje natural con una verificación completa.
• La experiencia de usuario de las confirmaciones no puede comunicar todos los efectos secundarios de comandos de shell arbitrarios.
• El estado de las sesiones largas y la compactación pueden hacer que las restricciones sean menos visibles.
• El estado del repositorio no se aísla automáticamente de otros trabajos no relacionados.

Otros comportamientos son una consecuencia razonable del diseño elegido:

• Un agente que puede editar y ejecutar es más útil que un asistente que solo genera parches.
• Pedir permiso antes de cada lectura o prueba de bajo riesgo haría que el flujo de trabajo fuera demasiado lento.
• El acceso amplio al repositorio permite depurar de forma transversal la compilación, las pruebas y el código fuente.
• La corrección iterativa es necesaria en proyectos reales, donde el primer comando suele fallar.

La respuesta adecuada consiste en operar por capas: permisos limitados, entornos desechables para tareas arriesgadas, instrucciones explícitas, sesiones breves, hooks ejecutables y verificación mecánica.

Conclusiones prácticas

• Inspecciona git status, la rama y el diff antes de conceder a Claude Code permisos de escritura.
• Trata CLAUDE.md como una política de proyecto ejecutable y mantenla concisa.
• Usa patrones de permisos limitados de allow y deny ; nunca los confundas con el aislamiento en un sandbox.
• Implementa los controles de comandos destructivos en hooks o en el entorno de ejecución que los rodea.
• Separa la planificación de la implementación para cambios poco familiares o de gran impacto.
• Repite las restricciones críticas después de la compactación y antes de la verificación final.
• Exige comandos de prueba exactos y distingue entre «no ejecutado» y «superado».
• Revisa git diff --name-only, git diff --check y el diff completo antes de fusionar.
• Usa contenedores, credenciales restringidas o árboles de trabajo desechables cuando los efectos secundarios de la shell sean relevantes.
• Trata la autonomía de Claude Code como una capacidad que debes configurar, no como un ajuste de confianza que se activa o desactiva.

La crítica central es válida: un flujo de trabajo agéntico deja implícitos los límites de control justo cuando deberían ser explícitos. Pero eso no hace que el flujo de trabajo sea inutilizable. Significa que los equipos experimentados deben aportar los límites que faltan mediante configuración, aislamiento, observabilidad y revisión.