The two files serve different scopes. AGENTS.md is the shared, tool-agnostic instruction file that any coding agent can read. CLAUDE.md is read by Claude Code specifically.
The mistake that causes most trouble is duplicating content between them. Two files describing the same stack, the same commands and the same conventions will drift apart, because someone will eventually update one and not the other. At that point you have two sources of truth and no way to tell which is current.
A structure that avoids this: put every project fact in AGENTS.md, and make CLAUDE.md short. Have it import AGENTS.md, state explicitly that AGENTS.md is canonical, and add only workflow guidance that is specific to how you want Claude to work — read the documentation before implementing, carry through from diagnosis to verification, never weaken a test to make a build pass. None of that is a project fact, so none of it can contradict AGENTS.md.
The same principle extends to other agent instruction files. Whatever set you maintain, one of them should hold the facts and the rest should hold tool-specific behaviour. Generating them together from a single source is the reliable way to keep that true, because it removes the opportunity for drift entirely.
A useful test: if you changed your package manager, how many files would need editing? If the answer is more than one, you have duplication that will eventually become a contradiction.
Keep the canonical file in version control alongside the code it describes, and review it when the project changes in ways an agent would notice. An instruction file is documentation, and it decays like documentation.