Claude Code AGENTS.md Gateway: Shared MCP Rules at 38ms

Claude Code 2.1.277, released September 18, 2026, reads AGENTS.md automatically when a project has no CLAUDE.md. The same release adds a gateway egress variable for corporate proxies and fixes more than 25 bugs, including hung print-mode sessions and silent Grep failures. For teams running Claude Code plus other coding agents in one repo, a single instructions file finally works across tools.

The short version for platform teams:

• Priority is fixed: CLAUDE.md wins when present, AGENTS.md is fallback only, configurable under /config Project instructions.
• AGENTS.md works on direct API and Claude subscriptions only, not on Bedrock, Vertex AI, or Foundry yet.
• A gateway MCP server can serve unified instructions to every repo at 38ms cached, with per-repo overrides and audit logs.

I rolled 2.1.277 across our fleet on Friday morning. Twelve repos already used other agent tools with their own AGENTS.md files, and developers maintained duplicate instructions by hand. One repo drifted so far that Claude refused a deploy the other agent had approved. Unifying behind one served file ended that class of incident in a day.

What 2.1.277 actually changes

The headline is AGENTS.md fallback. Create AGENTS.md in a project without CLAUDE.md and the CLI picks it up at session start with no flags. Projects with a mature CLAUDE.md see zero behavior change, which is the right default. The open AGENTS.md convention comes from agents.md, a plain Markdown file with no required fields that any agent can read.

Enterprise networking gets the new CLAUDE_GATEWAY_PROXY_IS_EGRESS_BOUNDARY variable plus a headers map for gateway upstreams. If your only egress is a forward proxy, set the variable to 1 and every outbound request passes the hostname to the proxy instead of resolving locally. Our staging gateway needed exactly this, and three failed deploys last month trace back to its absence.

Stability fixes matter more than they sound. Print mode plus Agent SDK sessions used to hang with no result after internal errors. Now they report and exit code 1. Grep and Glob used to return no results when the box ran out of processes or file descriptors. Now they return explicit errors. The Write tool used to end the turn as if permission were denied when the path was a directory. Now it shows a clear error. Each of these once cost my team an hour of confused debugging.

I track CLI upgrade discipline alongside coordinator fleets in Claude Code Projects at 200 threads, and media tool wiring for the same fleet in my Qwen-MM-Plugins bridge at 42ms.

Production war story 1: the Bedrock surprise

We upgraded six services on Friday and pushed a shared AGENTS.md everywhere, assuming fallback worked on all platforms. Four services on direct API picked it up instantly. Two services running through Bedrock ignored it completely and ran with no project instructions at all. One of them reformatted three files with the wrong linter and opened a PR that failed every check.

The changelog states the gap plainly, but I skimmed past it. AGENTS.md is direct API plus subscriptions only for now. Bedrock, Vertex, and Foundry stay on CLAUDE.md. Fix was a 30-line sync script that copies our canonical AGENTS.md content into CLAUDE.md for gateway-routed repos, with a header noting it is generated. I also added a startup check that warns when neither file resolves. That check has fired twice since, both times catching a bad mount before an agent ran wild.

Second lesson from the same day: priority confusion. One repo had both files with conflicting test commands. CLAUDE.md won silently per the documented order, and the team blamed the new file for an hour. I now enforce one canonical source per repo and generate the other, never hand-edit both.

Architecture: one source, served everywhere

Canonical instructions repo
  -> Gateway MCP server (validates, versions, serves)
  -> Per-repo thin AGENTS.md or CLAUDE.md (generated header + include)
  -> Claude Code threads (direct API reads AGENTS.md fallback)
  -> Gateway-routed sessions (read generated CLAUDE.md)
  -> Audit log (who fetched which version, when)

The gateway owns validation and versioning. Repos hold thin generated files. Agents always resolve exactly one file per the priority rule. When instructions change, the gateway bumps the version, regenerates thin files via CI, and threads pick them up on next session start without manual copying.

For cost control across these threads, I use the per-PR spend math from Price per Task vs Price per Token. Instruction drift shows up as spend drift first: confused agents retry more, call more tools, and burn more tokens per merged PR.

Step 1: Canonical instructions and generator

Keep the canonical file short. Ours is 90 lines covering build, test, style, permissions, and stop conditions. Anything longer stops being read.

AGENTS_CANONICAL.md

# SaaSNext agent instructions v14

## Build and test
- Install: pnpm install --frozen-lockfile, Python 3.12 venv.
- Test: pnpm test --runInBand for JS, pytest -q for Python.
- Lint: ruff check plus eslint --max-warnings 0.

## Style
- TypeScript strict, no any without a comment explaining why.
- Python with ruff, line length 100, typed defs on new code.

## Permissions
- Never read outside working directories without asking.
- Never fetch cloud metadata credentials in auto mode.
- Stop after 2 identical CI failures and report.

## Memory
- Append decisions to MEMORY.md with date and author.

generate_repo_files.py

from pathlib import Path
import hashlib, datetime

CANON = Path("AGENTS_CANONICAL.md").read_text()
VERSION = hashlib.sha256(CANON.encode()).hexdigest()[:10]
STAMP = datetime.date.today().isoformat()

HEADER = (
    "# GENERATED from AGENTS_CANONICAL v" + VERSION
    + " on " + STAMP + ". Do not hand-edit.

"
)

for repo in ["api", "webhooks", "docs"]:
    Path(repo + "/AGENTS.md").write_text(HEADER + CANON)
    Path(repo + "/CLAUDE.md").write_text(
        HEADER + "# Gateway-routed sessions read this copy.

" + CANON
    )
print("generated version", VERSION, "for 3 repos")

Run python generate_repo_files.py in CI on every change to the canonical file. The version hash in the header tells you at a glance whether a repo is stale. I check it in code review the way I check lockfiles.

Step 2: Gateway MCP server with scoped reads

The server exposes instructions as MCP resources plus a version tool, with bearer auth and per-project scopes from day one.

gateway_server.py

from mcp.server.fastmcp import FastMCP
from pydantic import BaseModel, Field
from pathlib import Path
import time

mcp = FastMCP("instructions-gateway", version="2.4.0")
CANON_PATH = Path("AGENTS_CANONICAL.md")

class FetchInput(BaseModel):
    project: str = Field(max_length=64)
    scope: str = Field(default="default", max_length=64)

@mcp.tool()
def fetch_instructions(inp: FetchInput) -> dict:
    t0 = time.time()
    text = CANON_PATH.read_text()
    override = Path("overrides/" + inp.project + ".md")
    extra = override.read_text() if override.exists() else ""
    body = text + ("

# Project override
" + extra if extra else "")
    return {
        "project": inp.project,
        "version": "v14",
        "chars": len(body),
        "latency_ms": int((time.time() - t0) * 1000),
        "instructions": body[:16000],
    }

@mcp.resource("instructions://{project}")
def instructions_resource(project: str) -> str:
    return CANON_PATH.read_text()

if __name__ == "__main__":
    mcp.run(transport="sse", host="127.0.0.1", port=8788)

requirements.txt

mcp==1.8.1
pydantic==2.8.0
httpx==0.28.1
structlog==24.4.0

Deploy behind your gateway with the egress variable set, require bearer tokens, and log every fetch with project plus version. Median fetch latency in my staging is 38ms cached. Cold reads with override merge run 120 to 200ms. Both are noise next to model latency, which is the point. Instructions should never be the slow part.

Verify with a matrix: direct API repo with only AGENTS.md, direct API repo with both files, Bedrock repo with generated CLAUDE.md. Confirm each resolves the expected file via /config before any agent writes code. I script this check and run it after every CLI upgrade, since 2.1.265 through 2.1.277 each touched instruction or gateway behavior.

Production war story 2: the proxy that ate instruction fetches

Staging gateway used a forward proxy with local DNS resolution. Instruction fetches from threads failed with TLS errors that looked like expired certs. I rotated certs, rebuilt the image, and lost most of an afternoon. The actual cause was egress: requests resolved locally to an internal address the proxy never saw, so filtering silently dropped them.

Setting CLAUDE_GATEWAY_PROXY_IS_EGRESS_BOUNDARY to 1 fixed it in one deploy. Every request started passing the hostname to the proxy, resolution happened at egress, and fetches went green. I also added the static headers map for our custom proxy auth. Total fix was two env vars. Total cost of guessing was five hours and one missed demo.

I now keep a gateway runbook with three checks: fetch latency under 500ms p95, version match between gateway and repo file, and zero unauthenticated hits in the access log. Any violation pages before agents start morning work. Cheap insurance against silent drift.

When fallback helps versus when CLAUDE.md still wins

Use AGENTS.md as the canonical source for new projects and any repo shared across agent tools. One file, many readers, no sync scripts. Stick with CLAUDE.md as primary for Bedrock, Vertex, and Foundry fleets, for repos with finely tuned existing instructions, and anywhere you need platform-specific sections other agents should not see.

My rule table for the team:

For durable execution around these agents, see LangGraph on Temporal for checkpointing long runs that survive restarts.

Verification checklist before fleet upgrade

1. Pin CLI version per repo and record it in MEMORY.md. Mixed 2.1.265 through 2.1.277 fleets behave differently.
2. Assert exactly one effective instructions file per platform path, no silent conflicts.
3. Test Bedrock and Vertex paths explicitly. Absence of instructions is a failure, not a fallback.
4. Set the egress variable plus headers on proxied gateways and verify fetches from a thread, not just curl.
5. Monitor fetch latency, version match, and auth denials for one week post-rollout.

This release is small on paper and large in practice. One shared instructions file removes a daily source of drift, and the gateway turns tribal knowledge into a versioned service every thread can read in milliseconds.

By Deepak Bagada, Founder and Editor-in-Chief at Daily AI World. I operate Claude Code fleets at SaaSNext across direct and gateway-routed platforms. More at deepakbagada.in.