Claude Code 2.1.277 suma soporte para AGENTS.md como alternativa a CLAUDE.md

⏱️ Lectura: 11 min

Claude Code 2.1.277, publicado el 18 de septiembre de 2026, cambia cómo el CLI descubre las instrucciones de un proyecto: si no encuentra un CLAUDE.md, ahora lee AGENTS.md en su lugar. Es la primera vez que la herramienta acepta un formato de instrucciones distinto al propio.

📑 En este artículo

1. TL;DR
2. Qué cambió en Claude Code 2.1.277
3. AGENTS.md: qué es y cuándo se activa
4. AGENTS.md vs CLAUDE.md: cuándo usar cada uno
   1. Cómo decide Claude Code qué archivo leer
5. Cómo probarlo hoy
6. Otros cambios importantes en 2.1.277
7. Por qué importa para equipos con varios agentes de código
8. Qué sigue
9. Preguntas frecuentes
   1. ¿Qué pasa si mi proyecto tiene CLAUDE.md y AGENTS.md al mismo tiempo?
   2. ¿Necesito hacer algo para activar AGENTS.md?
   3. ¿Funciona en Amazon Bedrock, Google Vertex AI o Foundry?
   4. ¿Cómo actualizo a la versión 2.1.277?
   5. ¿Qué es CLAUDE_GATEWAY_PROXY_IS_EGRESS_BOUNDARY?
   6. ¿Dónde reviso el changelog completo de Claude Code?
10. Referencias

La misma versión suma una variable de entorno para gateways corporativos con salida forzada por proxy y corrige más de veinticinco bugs, entre ellos sesiones que se quedaban colgadas sin devolver resultado y errores de arranque en Windows.

TL;DR

• Claude Code 2.1.277 se publicó el 18 de septiembre de 2026 y ya está disponible con claude update.
• Si el proyecto no tiene CLAUDE.md, Claude Code ahora lee AGENTS.md automáticamente.
• La opción se configura en /config, bajo “Project instructions”.
• Todavía no funciona en Amazon Bedrock, Google Vertex AI ni Foundry.
• Nueva variable CLAUDE_GATEWAY_PROXY_IS_EGRESS_BOUNDARY=1 para gateways detrás de un proxy forward.
• Se corrigió el colgado de claude -p y sesiones del Agent SDK tras un error interno: ahora reportan el error y salen con código 1.
• Se arregló un cierre de sesión inesperado al correr una build vieja de Claude Code en la misma máquina.

Qué cambió en Claude Code 2.1.277

La actualización llegó el 18 de septiembre de 2026 y se puede confirmar con un solo comando: claude --version debe mostrar 2.1.277. Según el changelog oficial, el cambio más visible es el soporte para AGENTS.md, pero la lista de correcciones es la más larga de las últimas semanas: toca el Agent SDK, el editor de archivos, el instalador y hasta el renderizado de la interfaz en terminales lentas.

Ninguno de estos cambios requiere tocar la configuración existente. Un proyecto que ya usa CLAUDE.md sigue funcionando exactamente igual: el archivo nuevo solo entra en juego cuando ese archivo no existe.

AGENTS.md: qué es y cuándo se activa

AGENTS.md no nace en Anthropic. Es una convención que ya adoptaron varias herramientas de agentes de código y que documenta el sitio agents.md: un archivo Markdown simple, sin campos obligatorios, con instrucciones de proyecto que cualquier agente puede leer. Claude Code 2.1.277 es la primera versión que lo entiende de forma nativa.

La regla de prioridad es simple: si el proyecto tiene CLAUDE.md, Claude Code lo usa y AGENTS.md se ignora por completo, aunque exista. Solo cuando no hay CLAUDE.md el CLI busca AGENTS.md y lo trata como si fuera el archivo de instrucciones del proyecto. Esto evita conflictos en repositorios que ya tenían su propio CLAUDE.md afinado.

El soporte se puede activar o revisar desde /config, en la sección “Project instructions”. Ahí también se puede forzar qué archivo leer si un proyecto tiene ambos y el equipo quiere decidir manualmente en vez de dejar la prioridad por defecto.

📌 Nota: AGENTS.md todavía no funciona en despliegues de Claude Code sobre Amazon Bedrock, Google Vertex AI ni Foundry. Por ahora es exclusivo de la API directa y las suscripciones de Claude.

AGENTS.md vs CLAUDE.md: cuándo usar cada uno

Para un equipo que arranca un proyecto nuevo, la pregunta práctica es qué archivo crear. La tabla resume las diferencias tal como quedaron en 2.1.277.

Archivo	Cuándo se usa	Ventaja	Limitación
CLAUDE.md	Ya existe en el repositorio, o el equipo quiere control total	Soportado en todas las plataformas, incluidas Bedrock, Vertex AI y Foundry	Formato propio de Claude Code, no lo leen otros agentes
AGENTS.md	El proyecto no tiene CLAUDE.md y ya usa otros agentes de código	Un solo archivo de instrucciones para varias herramientas de IA	Aún no disponible en Bedrock, Vertex AI ni Foundry

Cómo decide Claude Code qué archivo leer

flowchart TD
A["Claude Code abre el proyecto"] --> B{"Existe CLAUDE.md?"}
B -->|"Si"| C["Lee CLAUDE.md"]
B -->|"No"| D{"Existe AGENTS.md?"}
D -->|"Si"| E["Lee AGENTS.md"]
D -->|"No"| F["Sin instrucciones de proyecto"]
C --> G["Aplica las instrucciones en la sesion"]
E --> G

Cómo probarlo hoy

Actualizar y verificar la versión toma menos de un minuto en cualquier sistema operativo. El comando de instalación es el mismo en Windows, macOS y Linux porque Claude Code se distribuye como paquete de npm.

# Windows, macOS y Linux (requiere Node.js 18 o superior)
npm install -g @anthropic-ai/claude-code

# Verificar que quedo en 2.1.277 o superior
claude --version
# 2.1.277

Con la versión actualizada, crear un AGENTS.md en un proyecto que no tenga CLAUDE.md alcanza para activarlo. No hace falta ningún flag adicional.

# En la raiz del proyecto, sin CLAUDE.md existente
cat > AGENTS.md << 'EOF'
# Instrucciones del proyecto

- Runtime: Node.js 20 con TypeScript
- Ejecutar npm test antes de cada commit
- No modificar los archivos en /generated
- Usar conventional commits para los mensajes
EOF

claude
> /config
# Buscar "Project instructions" y confirmar que apunta a AGENTS.md

💡 Tip: si el equipo ya tenía un CLAUDE.md y quiere migrar a AGENTS.md, hay que borrar o renombrar el CLAUDE.md primero: mientras exista, Claude Code lo va a seguir priorizando.

La verificación no depende de adivinar: /config muestra explícitamente qué archivo está leyendo Claude Code en ese momento, así que cualquier duda sobre si el cambio quedó activo se resuelve sin salir de la sesión.

Otros cambios importantes en 2.1.277

El changelog completo tiene más de cuarenta entradas. Además de AGENTS.md, hay dos adiciones pensadas para infraestructura empresarial y una lista larga de correcciones de estabilidad.

Para gateways de Claude apps cuya única salida a internet es un proxy forward, la nueva variable CLAUDE_GATEWAY_PROXY_IS_EGRESS_BOUNDARY=1 hace que cada solicitud saliente le pase el hostname al proxy en vez de resolverlo localmente. También se agregó un mapa opcional de headers en los upstreams del gateway, para enviar cabeceras estáticas a un proxy propio delante de un proveedor.

En el lado de estabilidad, la corrección con más impacto es la de claude -p y las sesiones del Agent SDK: antes podían quedarse colgadas sin resultado después de un error interno, y ahora reportan el error y salen con código 1. También se resolvió un error de “text content blocks must be non-empty” que hacía fallar todas las solicitudes de una conversación cuando un turno anterior del asistente guardaba un bloque de texto vacío junto a otro contenido, incluso después de usar --resume.

Otras correcciones notables: se arregló un cierre de sesión inesperado al correr una build vieja de Claude Code (por ejemplo, la que trae empaquetada una extensión de IDE) en la misma máquina que la versión actual; se corrigieron cuelgues al iniciar cuando ~/.claude.json tiene un valor de theme o customApiKeyResponses mal formado; y claude plugin install dejó de romper la copia instalada de un plugin cuando la reinstalación falla mientras otra sesión lo está usando.

La lista de arreglos de estabilidad de la interfaz es más larga que en versiones anteriores. Se corrigieron cierres inesperados al abrir /mcp o /plugin manage con un valor mal formado de claudeAiMcpEverConnected en ~/.claude.json, un cierre al pegar en el prompt un texto con códigos de color de terminal (por ejemplo, texto recuperado del historial o cargado desde el editor externo), y un caso raro en Windows donde un turno podía terminar con un error de “Out of memory” justo después de que Claude respondiera, dejando sin ejecutar las herramientas de esa respuesta.

También se corrigieron dos casos de herramientas que fallaban en silencio: Grep y Glob ahora devuelven un error explícito cuando una búsqueda no puede arrancar porque el sistema se quedó sin procesos, memoria o descriptores de archivo (antes reportaban “sin resultados”, que es engañoso), y la herramienta Write deja de terminar el turno como si el usuario hubiera rechazado el permiso cuando la ruta de destino ya es un directorio existente: ahora muestra un error claro.

Hay un límite real que conviene marcar: ninguna de estas correcciones es retroactiva. Si un equipo sigue en una versión anterior a 2.1.277, los bugs de sesiones colgadas y de logout inesperado siguen presentes hasta que corra claude update.

Por qué importa para equipos con varios agentes de código

El dato de fondo es que cada vez más equipos combinan Claude Code con otras herramientas de agentes en el mismo repositorio. Sin un formato común, eso significaba mantener un archivo de instrucciones por herramienta, o forzar a todos los agentes a leer el mismo CLAUDE.md aunque no lo reconocieran. Con AGENTS.md, un repositorio puede tener un único archivo de instrucciones que varias herramientas entienden, sin depender de que cada una imponga su propio formato.

Para Claude Code puntualmente, esto no cambia nada si el proyecto ya tiene un CLAUDE.md maduro: seguir usándolo es la opción con más funciones, porque es la única que hoy cubre Bedrock, Vertex AI y Foundry además de la API directa. AGENTS.md tiene sentido sobre todo en proyectos nuevos, o en los que recién empiezan a estandarizar instrucciones entre varias herramientas de IA.

Qué sigue

El changelog no menciona una fecha para llevar AGENTS.md a Bedrock, Vertex AI o Foundry, así que por ahora sigue siendo una función de la API directa y las suscripciones de Claude. Tampoco hay señales de que CLAUDE.md vaya a perder prioridad frente a AGENTS.md: el orden actual (CLAUDE.md primero, AGENTS.md como respaldo) parece pensado para no romper proyectos existentes, no para reemplazar el formato propio.

Lo que sí es previsible, aunque no está confirmado en el changelog, es que actualizaciones futuras de Claude Code sigan sumando compatibilidad con convenciones abiertas como esta: el listado de correcciones de 2.1.277 muestra un ritmo de mantenimiento semanal sobre el Agent SDK, el instalador y las herramientas de archivos.

📖 Resumen en Telegram: Ver resumen

Probalo vos: corré npm install -g @anthropic-ai/claude-code, confirmá la versión con claude –version y creá un AGENTS.md en tu próximo proyecto sin CLAUDE.md.

Preguntas frecuentes

¿Qué pasa si mi proyecto tiene CLAUDE.md y AGENTS.md al mismo tiempo?

Claude Code usa CLAUDE.md y AGENTS.md queda ignorado por completo. La prioridad se puede confirmar en /config, en la sección “Project instructions”.

¿Necesito hacer algo para activar AGENTS.md?

No. Con Claude Code 2.1.277 o superior, si el proyecto no tiene CLAUDE.md, el CLI lee AGENTS.md automáticamente al iniciar la sesión.

¿Funciona en Amazon Bedrock, Google Vertex AI o Foundry?

Todavía no. El changelog aclara explícitamente que AGENTS.md no está disponible en esas plataformas por ahora.

¿Cómo actualizo a la versión 2.1.277?

Con claude update si ya tenés Claude Code instalado, o con npm install -g @anthropic-ai/claude-code para una instalación nueva en Windows, macOS o Linux.

¿Qué es CLAUDE_GATEWAY_PROXY_IS_EGRESS_BOUNDARY?

Es una variable de entorno nueva para gateways de Claude apps cuya única salida a internet es un proxy forward: hace que cada solicitud le pase el hostname al proxy en vez de resolverlo localmente.

¿Dónde reviso el changelog completo de Claude Code?

En la documentación oficial de Claude Code, que se genera directamente desde el CHANGELOG.md del proyecto.

Referencias

• Claude Code Changelog: registro oficial de cambios de cada versión, incluida la 2.1.277.
• agents.md: sitio que documenta la convención abierta de archivos AGENTS.md para agentes de código.
• anthropics/claude-code en GitHub: repositorio público con issues y discusiones sobre el CLI.
• Documentación de Claude: referencia oficial de Anthropic para Claude y Claude Code.

📱 ¿Te gusta este contenido? Únete a nuestro canal de Telegram @programacion donde publicamos a diario lo más relevante de tecnología, IA y desarrollo. Resúmenes rápidos, contenido fresco todos los días.

Imagen destacada: Foto de Jakub Żerdzicki en Unsplash