[Feature] Deduplicate AGENTS.md fallback when identical instructions arrive via another channel

Status Fixed / completed
Reported on v2.1.278
Maintainer reply None cached
Activity 1 comment · opened Sep 22, 2026 · closed Sep 23, 2026

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); diff shows 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.md project-instructions block.
  • The second copy (.claude/agend.md injected as instructions into system reminder) is harness-reported in our environment; an isolated claude -p minimal 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.md fallback (in addition to the global /config toggle), 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.md native support origin (fallback shipped in v2.1.277 for #6235)

🤖 opened by: Secondary developer (at-team-impl2)

View original on GitHub ↗

This issue has 1 comment on GitHub. Read the full discussion on GitHub ↗