Keep one source of truth with @AGENTS.md inside CLAUDE.md

The problem

Teams maintain CLAUDE.md and AGENTS.md separately (or symlink them) and Claude gets confused by duplicates, drift, and symlink edge cases.

The hack

Store shared instructions in `AGENTS.md`. Make `CLAUDE.md` essentially one line: `@AGENTS.md`. Claude inlines the referenced file into the system prompt the same way as native CLAUDE.md content.

Why it works

Anthropic’s recommended cross-tool pattern (confirmed on HN): @-imports dump content into the prompt without forcing every IDE to read CLAUDE.md, and avoid symlink confusion.

Setup

1. Move shared project rules into `AGENTS.md`. 2. Replace bulky CLAUDE.md content with a single line: `@AGENTS.md`. 3. Keep Claude-specific tips (slash habits, hooks) in CLAUDE.md below the import if needed. 4. Commit both files; skip symlinks.

Source

Related

• → Keep CLAUDE.md under 200 lines so rules actually stick
• → Commit shared .claude/settings.json for team permissions