Lesson #1467

agents-md-is-single-source-of-truth-per-project Medium authority: 75

ID: 1467
Author: ai
Agent: agent-claude
Reviewed: ✓ Yes
Source authority: 75 / 100
Source: AGENTS.md = canonical agent instruction file; CLAUDE.md + GEMINI.md are symlinks. No drift between CLI tools.
Source issue: —
Created at: 2026-05-12T10:02:03.357131+00:00
Valid until: —
Deprecated at: —
Supersedes: —
Obsidian path: /root/.claude/projects/-nvmetank1-projects/memory/feedback_agents_md_canonical.md
Obsidian hash: 8e3a9d292fd4ae24668f674b1ee54fb3
Tags: claude-memory,feedback

Content

**Rule:** In every `/nvmetank1/projects/<p>/` repo, `AGENTS.md` is the single source. `CLAUDE.md` and `GEMINI.md` are git-tracked symlinks pointing at it.

**Why:** Before 2026-05-12 each project had separate CLAUDE.md (≤2k) and AGENTS.md (≤15k); content drift between codex (reads AGENTS), claude-code (reads CLAUDE), and gemini-cli (reads GEMINI) was guaranteed. User chose consolidation 2026-05-12.

**How to apply:**

1. When editing project conventions, edit `AGENTS.md`. The symlinks propagate automatically.
2. When bootstrapping a new project, create `AGENTS.md` and:
   ```bash
   ln -s AGENTS.md CLAUDE.md
   ln -s AGENTS.md GEMINI.md
   ```
3. Don't introduce a real `CLAUDE.md` or `GEMINI.md` file — break the symlink only with explicit user approval.
4. Existing projects converted on 2026-05-12: glug, rag-stack, astrologie-dev, scandi, scandi-v2, yoga.
5. The user's GLOBAL files `/root/.claude/CLAUDE.md` + `RTK.md` + `SCANDI.md` are unaffected — those are user-level, not project-scoped.

**Verify:**
```bash
ls -la /nvmetank1/projects/<p>/AGENTS.md /nvmetank1/projects/<p>/CLAUDE.md /nvmetank1/projects/<p>/GEMINI.md
# AGENTS.md must be a regular file; CLAUDE.md + GEMINI.md must be symlinks → AGENTS.md
```

Related: [[reference_memory_context_pack]] (auto-injection of memory + rag-bus).