# AGENTS.md as provider-agnostic governance entry point; CLAUDE.md as thin adapter

`AGENTS.md` is the single source of truth for always-on agent instructions. It lives at the repo root (project-level) and at `core/AGENTS.md` deployed to `~/.agents/AGENTS.md` (global). It contains all universal rules in plain markdown with no provider-specific syntax. Provider-specific files (`CLAUDE.md`) become thin adapters that import it — the repo-level `CLAUDE.md` contains `@AGENTS.md` plus any Claude Code-specific additions; the global `~/.claude/CLAUDE.md` imports `~/.agents/AGENTS.md` similarly.

Claude Code reads `CLAUDE.md` natively, not `AGENTS.md`. The Anthropic documentation explicitly recommends the import pattern for repos that use `AGENTS.md` for other tools: `CLAUDE.md` contains `@AGENTS.md` and appends Claude Code-specific content below. This means `CLAUDE.md` continues to exist as the Claude Code entry point but carries no original content — it is purely an adapter.

`AGENTS.md` must be self-contained: no `@import` syntax (which is Claude Code-specific and would make the file provider-specific). On-demand instruction loading via `@import` stays in the Claude Code adapter (`CLAUDE.md`), pointing to `core/instructions/` as today. The `core/` deployment path (`~/.claude/core/`) reflects the current provider deployment model.

This partially supersedes ADR-0002 (two-tier CLAUDE.md model). ADR-0002 established the always-on / on-demand split and remains correct as a structural pattern. What changes is where the always-on content lives: previously in `providers/claude-code/CLAUDE.md`, now in `AGENTS.md`. The adapter layer ADR-0002 described still exists; `CLAUDE.md` is now the adapter rather than the source.

The alternative — keeping always-on content in `providers/claude-code/CLAUDE.md` — was rejected because it violates the provider-agnostic principle: content that applies to all agents regardless of provider has no business living in a provider-specific file. When multiple providers exist, duplicating that content into a separate adapter or maintaining two sources of the same rules creates drift and inconsistency.