Defame1297
537c681bb9
- docs/prd/chunk-3-skills-library.md: PRD for 42-skill library rebuild; AGENTS.md refactor as prerequisite; factory bootstrap order (write-eval first); source field schema; upstream review cadence; design phase sequence; IaC/Gitea scope decisions - docs/adr/0011-provider-agnostic-issue-tracker.md: file-based default, Gitea as provider adapter, "issue" as canonical cross-provider term - docs/adr/0012-agents-md-provider-agnostic-entry-point.md: AGENTS.md as content source, CLAUDE.md as thin adapter; partially supersedes ADR-0005 - CONTEXT.md: 8 new glossary terms (AGENTS.md, skill composition, source field, provider-agnostic issue tracker, design phase sequence, PRD scope, issue scope, bidirectional reference principle); CLAUDE.md index model updated; stale workflow example fixed - docs/ROADMAP.md: changelog tooling and IaC/Gitea scope resolved; when: field question updated; Chunk 3 grill housekeeping note added - docs/spec/overview.md: Chunk 3 target updated with PRD link, skill count, and AGENTS.md prerequisite Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2.2 KiB
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/) is unchanged in this chunk; migration to ~/.agents/ is deferred to Chunk 7 when a second provider (Copilot) provides evidence of what that provider needs.
This partially supersedes ADR-0005 (two-tier CLAUDE.md model). ADR-0005 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-0005 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 ADR-0003 (provider-agnostic core). Content that applies to all agents regardless of provider has no business living in a provider-specific file. When Copilot arrives in Chunk 7, duplicating that content into a Copilot adapter or maintaining two sources of the same rules is exactly the drift ADR-0003 was written to prevent.