⏱️ Lectura: 10 min
Claude Code 2.1.277, released on September 18, 2026, changes how the CLI discovers a project’s instructions: if it can’t find a CLAUDE.md, it now reads AGENTS.md instead. It’s the first time the tool accepts an instructions format other than its own.
📑 En este artículo
- TL;DR
- What Changed in Claude Code 2.1.277
- AGENTS.md: What It Is and When It Activates
- AGENTS.md vs CLAUDE.md: When to Use Each
- How to Try It Today
- Other Important Changes in 2.1.277
- Why It Matters for Teams Using Multiple Code Agents
- What’s Next
- Frequently Asked Questions
- What happens if my project has both CLAUDE.md and AGENTS.md?
- Do I need to do anything to activate AGENTS.md?
- Does it work on Amazon Bedrock, Google Vertex AI, or Foundry?
- How do I update to version 2.1.277?
- What is CLAUDE_GATEWAY_PROXY_IS_EGRESS_BOUNDARY?
- Where can I check the full Claude Code changelog?
- References
The same release adds an environment variable for corporate gateways with forced proxy egress and fixes more than twenty-five bugs, including sessions that hung without returning a result and startup errors on Windows.
TL;DR
- Claude Code 2.1.277 was released on September 18, 2026, and is already available via claude update.
- If the project has no CLAUDE.md, Claude Code now reads AGENTS.md automatically.
- The option is configured in /config, under “Project instructions”.
- It still doesn’t work on Amazon Bedrock, Google Vertex AI, or Foundry.
- New CLAUDE_GATEWAY_PROXY_IS_EGRESS_BOUNDARY=1 variable for gateways behind a forward proxy.
- Fixed the hang in claude -p and Agent SDK sessions after an internal error: they now report the error and exit with code 1.
- Fixed an unexpected logout when running an old Claude Code build on the same machine.
What Changed in Claude Code 2.1.277
The update arrived on September 18, 2026, and can be confirmed with a single command: claude --version should show 2.1.277. According to the official changelog, the most visible change is support for AGENTS.md, but the list of fixes is the longest in recent weeks: it touches the Agent SDK, the file editor, the installer, and even interface rendering on slow terminals.
None of these changes require touching existing configuration. A project that already uses CLAUDE.md keeps working exactly the same: the new file only comes into play when that file doesn’t exist.
AGENTS.md: What It Is and When It Activates
AGENTS.md didn’t originate at Anthropic. It’s a convention already adopted by several code agent tools and documented at agents.md: a simple Markdown file, with no required fields, containing project instructions that any agent can read. Claude Code 2.1.277 is the first version that understands it natively.
The priority rule is simple: if the project has a CLAUDE.md, Claude Code uses it and AGENTS.md is ignored entirely, even if it exists. Only when there’s no CLAUDE.md does the CLI look for AGENTS.md and treat it as the project’s instructions file. This avoids conflicts in repositories that already had their own finely tuned CLAUDE.md.
Support can be activated or checked from /config, in the “Project instructions” section. There, teams can also force which file to read if a project has both and want to decide manually instead of leaving the default priority.
📌 Note: AGENTS.md still doesn’t work on Claude Code deployments over Amazon Bedrock, Google Vertex AI, or Foundry. For now it’s exclusive to the direct API and Claude subscriptions.
AGENTS.md vs CLAUDE.md: When to Use Each
For a team starting a new project, the practical question is which file to create. The table below summarizes the differences as they stand in 2.1.277.
| File | When to Use | Advantage | Limitation |
|---|---|---|---|
| CLAUDE.md | Already exists in the repository, or the team wants full control | Supported on all platforms, including Bedrock, Vertex AI, and Foundry | Claude Code’s own format, not read by other agents |
| AGENTS.md | The project has no CLAUDE.md and already uses other code agents | A single instructions file for multiple AI tools | Not yet available on Bedrock, Vertex AI, or Foundry |
How Claude Code Decides Which File to Read
flowchart TD
A["Claude Code opens the project"] --> B{"Does CLAUDE.md exist?"}
B -->|"Yes"| C["Reads CLAUDE.md"]
B -->|"No"| D{"Does AGENTS.md exist?"}
D -->|"Yes"| E["Reads AGENTS.md"]
D -->|"No"| F["No project instructions"]
C --> G["Applies instructions in the session"]
E --> G
How to Try It Today
Updating and verifying the version takes less than a minute on any operating system. The installation command is the same on Windows, macOS, and Linux because Claude Code is distributed as an npm package.
# Windows, macOS, and Linux (requires Node.js 18 or higher)
npm install -g @anthropic-ai/claude-code
# Verify it's on 2.1.277 or higher
claude --version
# 2.1.277With the updated version, creating an AGENTS.md in a project without a CLAUDE.md is enough to activate it. No additional flag is needed.
# In the project root, with no existing CLAUDE.md
cat > AGENTS.md << 'EOF'
# Project instructions
- Runtime: Node.js 20 with TypeScript
- Run npm test before every commit
- Do not modify files in /generated
- Use conventional commits for messages
EOF
claude
> /config
# Look for "Project instructions" and confirm it points to AGENTS.md💡 Tip: if the team already had a CLAUDE.md and wants to migrate to AGENTS.md, they need to delete or rename the CLAUDE.md first: as long as it exists, Claude Code will keep prioritizing it.
Verification doesn’t rely on guesswork: /config explicitly shows which file Claude Code is reading at that moment, so any doubt about whether the change is active gets resolved without leaving the session.
Other Important Changes in 2.1.277
The full changelog has more than forty entries. Besides AGENTS.md, there are two additions aimed at enterprise infrastructure and a long list of stability fixes.
For Claude apps gateways whose only internet egress is a forward proxy, the new CLAUDE_GATEWAY_PROXY_IS_EGRESS_BOUNDARY=1 variable makes every outgoing request pass the hostname to the proxy instead of resolving it locally. An optional headers map was also added to gateway upstreams, to send static headers to a custom proxy sitting in front of a provider.
On the stability side, the fix with the most impact is for claude -p and Agent SDK sessions: before, they could hang with no result after an internal error, and now they report the error and exit with code 1. Also resolved was a “text content blocks must be non-empty” error that made every request in a conversation fail when a prior assistant turn had saved an empty text block alongside other content, even after using --resume.
Other notable fixes: an unexpected logout was fixed when running an old Claude Code build (for example, the one bundled with an IDE extension) on the same machine as the current version; startup hangs were fixed when ~/.claude.json has a malformed theme or customApiKeyResponses value; and claude plugin install no longer breaks the installed copy of a plugin when reinstallation fails while another session is using it.
The list of interface stability fixes is longer than in previous versions. Fixed: unexpected crashes when opening /mcp or /plugin manage with a malformed claudeAiMcpEverConnected value in ~/.claude.json, a crash when pasting text with terminal color codes into the prompt (for example, text recovered from history or loaded from the external editor), and a rare case on Windows where a turn could end with an “Out of memory” error right after Claude responded, leaving that response’s tools unexecuted.
Two cases of tools failing silently were also fixed: Grep and Glob now return an explicit error when a search can’t start because the system ran out of processes, memory, or file descriptors (previously they reported “no results”, which is misleading), and the Write tool no longer ends the turn as if the user had denied permission when the destination path is already an existing directory: it now shows a clear error.
There’s a real limit here: none of these fixes are retroactive. If a team is still on a version older than 2.1.277, the hanging session and unexpected logout bugs remain present until they run claude update.
Why It Matters for Teams Using Multiple Code Agents
The underlying trend is that more teams are combining Claude Code with other agent tools in the same repository. Without a common format, that meant maintaining one instructions file per tool, or forcing every agent to read the same CLAUDE.md even if it didn’t recognize it. With AGENTS.md, a repository can have a single instructions file that multiple tools understand, without depending on each one imposing its own format.
Specifically for Claude Code, this changes nothing if the project already has a mature CLAUDE.md: sticking with it is the option with the most features, since it’s the only one that currently covers Bedrock, Vertex AI, and Foundry in addition to the direct API. AGENTS.md makes the most sense in new projects, or ones just starting to standardize instructions across multiple AI tools.
What’s Next
The changelog doesn’t mention a date for bringing AGENTS.md to Bedrock, Vertex AI, or Foundry, so for now it remains a feature of the direct API and Claude subscriptions. There’s also no sign that CLAUDE.md will lose priority over AGENTS.md: the current order (CLAUDE.md first, AGENTS.md as a fallback) appears designed to avoid breaking existing projects, not to replace its own format.
What is predictable, though not confirmed in the changelog, is that future Claude Code updates will keep adding compatibility with open conventions like this one: the 2.1.277 fix list shows a weekly maintenance pace on the Agent SDK, the installer, and file tools.
📖 Summary on Telegram: View summary
Try it yourself: run npm install -g @anthropic-ai/claude-code, confirm the version with claude –version, and create an AGENTS.md in your next project without a CLAUDE.md.
Frequently Asked Questions
What happens if my project has both CLAUDE.md and AGENTS.md?
Claude Code uses CLAUDE.md and AGENTS.md is ignored entirely. The priority can be confirmed in /config, in the “Project instructions” section.
Do I need to do anything to activate AGENTS.md?
No. With Claude Code 2.1.277 or higher, if the project has no CLAUDE.md, the CLI reads AGENTS.md automatically when the session starts.
Does it work on Amazon Bedrock, Google Vertex AI, or Foundry?
Not yet. The changelog explicitly states that AGENTS.md isn’t available on those platforms for now.
How do I update to version 2.1.277?
With claude update if you already have Claude Code installed, or with npm install -g @anthropic-ai/claude-code for a fresh install on Windows, macOS, or Linux.
What is CLAUDE_GATEWAY_PROXY_IS_EGRESS_BOUNDARY?
It’s a new environment variable for Claude apps gateways whose only internet egress is a forward proxy: it makes every request pass the hostname to the proxy instead of resolving it locally.
Where can I check the full Claude Code changelog?
In the official Claude Code documentation, which is generated directly from the project’s CHANGELOG.md.
References
- Claude Code Changelog: official record of changes for each release, including 2.1.277.
- agents.md: site documenting the open convention for AGENTS.md files used by code agents.
- anthropics/claude-code on GitHub: public repository with issues and discussions about the CLI.
- Claude Documentation: Anthropic’s official reference for Claude and Claude Code.
📱 Enjoying this content? Follow @programacion on Telegram for daily tech content in Spanish: quick summaries, fresh content every day.
Imagen destacada: Foto de Jakub Żerdzicki en Unsplash
0 Comments