Claude Code AGENTS.md Support Request

The Feature Request: Support AGENTS.md discussion is important because it exposes a real interoperability problem in AI-assisted development workflows. AGENTS.md has become a shared convention for repo-level instructions across coding agents, while Claude Code currently anchors behavior around CLAUDE.md. That difference may look small, but it creates operational friction for teams that want one canonical instruction file for all assistants. The core pain point is not merely file naming; it is instruction governance. Every duplicate file increases drift, maintenance overhead, and the risk that one assistant receives outdated rules.

The technical insight is that current Claude Code behavior can be approximated without native support. The commonly cited workaround is to place a single import line in CLAUDE.md that points to AGENTS.md, letting teams preserve AGENTS.md as the source of truth while still satisfying Claude Code’s expected entrypoint. A symlink is another option, but it is less portable and can be awkward on systems with restrictions or differing filesystem semantics. This makes the request particularly relevant for cross-platform teams and monorepos, where instruction files need to scale across many contributors.

A second insight is that the issue is as much about ecosystem standardization as product support. If AGENTS.md remains the shared format for multi-agent tooling, then native reads by more assistants would reduce context fragmentation. Until that happens, teams should treat instruction files like configuration artifacts: versioned, reviewed, and intentionally minimized. The most robust setup is usually a thin CLAUDE.md wrapper that imports the canonical AGENTS.md content and adds only Claude-specific deltas.

The available evidence indicates that Claude Code does not read AGENTS.md directly and instead relies on CLAUDE.md as its native project instruction file. That means a repository that only contains AGENTS.md will not automatically transfer its guidance into Claude Code sessions. In practice, the support request is asking for a first-class parser or fallback path so the tool can ingest AGENTS.md without the extra indirection.

The most reliable workaround is to create CLAUDE.md and import AGENTS.md from it. This keeps AGENTS.md as the single source of truth while satisfying Claude Code’s expected entrypoint. Teams that do not need Claude-specific additions can also use a symbolic link from CLAUDE.md to AGENTS.md, but that approach is more fragile in mixed environments and less suitable when repositories must work cleanly on Windows or constrained developer machines. The import pattern is typically preferred because it preserves portability and allows project maintainers to append Claude-only instructions beneath the shared base rules.

Operationally, this request sits in the same category as other AI-devtools integration issues: low-level parsing behavior, repo discovery rules, and instruction precedence all matter. If native AGENTS.md support were added, the main product benefit would be reduced setup friction and fewer repository-specific exceptions. The main tradeoff would be deciding how AGENTS.md should interact with CLAUDE.md when both files exist. A clear precedence model, deterministic merge behavior, and explicit documentation would be essential to prevent ambiguous instruction loading.

From a technical architecture standpoint, this feature request is best understood as a compatibility layer problem. The user expectation is simple: open a repo, let the assistant read the same instruction file other coding agents use, and avoid duplicate maintenance. The implementation challenge is more subtle: the product must define file precedence, merge semantics, session reload behavior, and platform portability. These are the hidden details that determine whether support feels native or merely cosmetic.

The issue also highlights a broader software engineering pattern: shared standards only become valuable when tools converge on the same entrypoint. When one assistant requires a separate filename, teams often end up maintaining parallel instruction stacks, which weakens consistency and increases review burden. For engineering organizations, that cost compounds across dozens of repositories. The strongest long-term design is usually the one that minimizes special cases, documents explicit fallback order, and makes cross-tool reuse straightforward.

For SEO and technical reference purposes, the most useful content to surface is not just whether support exists, but how to operationalize it safely today. That includes the exact workaround structure, when to prefer imports over symlinks, and what to watch for if native support eventually lands. Readers searching this topic want a decision framework: whether to standardize on AGENTS.md, keep CLAUDE.md as a wrapper, or maintain separate files for assistant-specific behavior. That is the practical center of gravity of the entire discussion.