Rename CLAUDE.md to AGENTS.md org-wide, with CLAUDE.md as a symlink

[lesnik512]

What

Every repo in the org keeps its agent instructions in CLAUDE.md — this repo included. AGENTS.md
is the cross-agent filename other coding agents look for, so the instructions are invisible to
anything that is not Claude Code.

Proposal: rename the file to AGENTS.md in each repo and leave CLAUDE.md as a symlink to it, so
Claude Code keeps loading it with no change on its side.

Scope

Repos with a CLAUDE.md today include this one, modern-di, faststream-outbox, and the
modern-di-* integrations. Worth doing in one pass rather than per repo — half-migrated is worse
than either end state, because a reader cannot tell which file is authoritative.

Per-repo checklist

• git mv CLAUDE.md AGENTS.md
• ln -s AGENTS.md CLAUDE.md (git stores the symlink as a mode-120000 blob; no config needed)
• Update inbound references. In faststream-outbox that is two: .github/PULL_REQUEST_TEMPLATE.md
  and a prose mention in tests/test_client_contract.py. Other repos will have their own.

Worth checking before doing it

• Windows checkouts. Git creates symlinks on Windows only with core.symlinks=true and
  developer mode or elevation; otherwise the working tree gets a plain text file containing the
  target path. If anyone develops on Windows, a committed duplicate with a one-line pointer may beat
  a symlink.
• Direction. AGENTS.md as the real file and CLAUDE.md as the link is the right way round —
  the generic name should be the content — but it means any tool that writes to CLAUDE.md writes
  through the link, which is fine, and any tool that replaces it breaks the link silently.
• Tools that resolve vs. read links. Worth a quick check that the agents in use follow a symlink
  rather than skipping it.

Context

Raised in review on modern-python/faststream-outbox#159, which deliberately did not do the rename:
that PR's premise is aligning with modern-di, which is still on CLAUDE.md, so renaming in one
repo alone would have introduced the drift this issue exists to avoid.

[lesnik512]

This was generated by AI during triage.

Agent Brief

Category: enhancement
Summary: Rename CLAUDE.md to AGENTS.md in every org repo that has one, as a plain rename with no symlink, updating inbound references in the same pass.

Verified before writing this brief. Claude Code 2.1.261 discovers AGENTS.md natively: a fixture containing only AGENTS.md and no CLAUDE.md loaded correctly. A second fixture with AGENTS.md plus a CLAUDE.md symlink also loaded, once, with no double-read. The CLI bundle states it directly — "Claude Code hardcodes CLAUDE.md / AGENTS.md discovery."

This settles the issue's open question. The symlink was proposed so "Claude Code keeps loading it with no change on its side"; that is already true without one. Doing the plain rename removes the two risks the body flags — Windows checkouts needing core.symlinks and developer mode, and any tool that replaces CLAUDE.md silently breaking the link. Do not create the symlink.

Current behavior:
Agent instructions live in CLAUDE.md. Across the org's non-archived repos, 27 of 28 have one and none has an AGENTS.md, so any coding agent that looks for the cross-agent filename finds nothing. One repo (that-depends) has neither.

Desired behavior:
AGENTS.md is the real, and only, instructions file in every repo that has one today. No CLAUDE.md remains — not as a file, not as a symlink. Every inbound reference points at the new name, and each file's own top-level heading no longer says CLAUDE.md.

Scope — derive it, don't trust a list. The set changes; compute it at run time rather than working from a snapshot:

gh repo list modern-python --limit 60 --json name,isArchived \
  --jq '.[] | select(.isArchived | not) | .name'

For each, act only if CLAUDE.md exists at the repo root. As of triage that was every non-archived repo except that-depends.

Inbound references — find them per repo, don't assume a count. In each repo, after renaming, search the whole worktree for the old name and fix every hit:

• The file's own H1. At least modern-di and faststream-outbox open with # CLAUDE.md, which becomes wrong on rename.
• .github/PULL_REQUEST_TEMPLATE.md in the repos that have a local one — it links to the file for the "Where a fact goes" section.
• Prose mentions in tests. faststream-outbox has one in its client-contract test that names the file as the home of a documented invariant.
• ADR bodies. modern-di has at least one ADR citing the file by name.
• modern-di's integration-authoring guide is the load-bearing one. It instructs new integration authors to mirror modern-di's CLAUDE.md, and appears in both its prose and its checklist. Left stale, it propagates the old name into every future integration repo.

Acceptance criteria:

• Every non-archived org repo that had a root CLAUDE.md now has AGENTS.md and no CLAUDE.md — no file, no symlink.
• git log --follow on the new path shows the pre-rename history, i.e. the change was a rename and not a delete-plus-add.
• In every touched repo, a case-insensitive search for CLAUDE.md across the worktree returns no hits outside .git/.
• Each renamed file's top-level heading names the new file.
• modern-di's integration-authoring guide tells authors to mirror AGENTS.md, in both its prose and its checklist.
• Each repo's own lint/test gate passes unchanged — just lint-ci where present, plus the repo's test recipe.
• Opening a session in a renamed repo loads the instructions (verifiable with claude -p against a fact stated only in that file).

Out of scope:

• Creating a CLAUDE.md symlink or stub. Explicitly rejected above; do not add one "just in case".
• that-depends. It has no agent instructions at all. Whether it should is a separate decision, not part of a rename.
• Editing the content of any instructions file beyond its own heading and stale self-references. This is a rename, not a rewrite.
• The PR-template convention question — that is Host the PR-body-as-spec template org-wide; adopt the convention here #50 and its follow-up. If a repo's PR template mentions the file, update the name only; leave its wording alone.
• Archived repos.

Sequencing note: the body is right that half-migrated is worse than either end state, because a reader cannot tell which file is authoritative. Prefer one pass over all repos. If that is not possible in a single run, finish each repo completely — rename plus all its inbound references — before starting the next, so no repo is ever left in a mixed state.