[Feature] Deduplicate AGENTS.md fallback when identical instructions arrive via another channel
Problem
Since v2.1.277, when a directory has no CLAUDE.md, Claude Code falls back to reading AGENTS.md (toggle in /config). In setups where the same instruction text is also provided through a second channel (in our case an agent harness injects <workspace>/.claude/agend.md into the session as instructions / system reminder), a new session ends up with two near-identical ~17 KB instruction blocks: one from the AGENTS.md fallback, one from the injected file. This doubles context cost and makes one logical instruction set appear as two authorities.
Evidence
- Local file comparison proves the duplication source:
<workspace>/AGENTS.md(~17.4 KB) vs<workspace>/.claude/agend.md(~17.3 KB);diffshows only wrapper markers, team-list ordering, and a build hash differ — the instruction body is effectively identical. - Session-start system reminder in the live session contains the full
AGENTS.mdproject-instructions block. - The second copy (
.claude/agend.mdinjected as instructions into system reminder) is harness-reported in our environment; an isolatedclaude -pminimal repro of the double-load is still pending verification outside the harness. Filing as enhancement/request, not a confirmed loader bug. - Environment: Claude Code 2.1.278, macOS arm64.
Scope
Memory / session-start loading: AGENTS.md fallback path vs any other instruction channel carrying byte-identical (or near-identical) content. No per-line implementation plan proposed.
Expected Outcome
One of (observable, either acceptable):
- Content-hash dedup across instruction sources: identical content loaded once, with a note of which source won; or
- A per-directory opt-out for the
AGENTS.mdfallback (in addition to the global/configtoggle), so harness-managed workspaces can keep a single source; or - Diagnostics listing which instruction sources were loaded + bytes, so duplication is visible (complements #85477).
If the answer is "working as intended — keep both", this issue can be closed as such with the recommended single-source layout documented.
Related
- Related: #94463 — same-file double load via nested_traversal (different path, same waste class)
- Related: #85477 — duplication and conflict detection for instruction sources
- Related: #34235 —
AGENTS.mdnative support origin (fallback shipped in v2.1.277 for #6235)
🤖 opened by: Secondary developer (at-team-impl2)
This issue has 1 comment on GitHub. Read the full discussion on GitHub ↗