bingshuo/guanghu
1
0
Fork 0
Code Issues Pull Requests Actions 4 Packages Projects Releases Wiki Activity
guanghu/docs/adr/0065-root-managed-ai-guidance-files.md
Guanghu Domestic Migration 9b41d51231
Some checks are pending
Auto-update PR branches / Update open PR branches (push) Waiting to run
Details
CI / Frontend Static Quality Checks (push) Waiting to run
Details
CI / Frontend Tests & Coverage (push) Waiting to run
Details
CI / Rust Tests & Quality Checks (push) Waiting to run
Details
CI / Linux build verification (push) Waiting to run
Details
Deploy docs / Build VitePress site (push) Waiting to run
Details
Deploy docs / Deploy to GitHub Pages (push) Blocked by required conditions
Details
Release (Alpha) / Compute alpha version (push) Waiting to run
Details
Release (Alpha) / Build release artifacts (push) Blocked by required conditions
Details
Release (Alpha) / GitHub Release (alpha) (push) Blocked by required conditions
Details
Release (Alpha) / Update docs and release pages (push) Blocked by required conditions
Details
chore: import sanitized domestic snapshot for REPO-004 
Source snapshot: 514ab1975951d94342ea38e64101d5a0f1c51c77
2026-07-17 15:55:28 +08:00

2.2 KiB
Raw Permalink Blame History

type, id, title, status, date
type id title status date
ADR 0065 Root-managed AI guidance files with Claude shim active 2026-04-14

Context

Tolaria now supports multiple local CLI agents, but vault-level guidance still carried legacy assumptions. Existing vault bootstrap and repair flows centered on config/agents.md, while modern coding agents expect instructions at the vault root. That mismatch made managed guidance harder to reason about, left Claude Code compatibility implicit, and gave the UI no reliable way to distinguish between Tolaria-managed files that can be repaired and user-authored custom guidance that must be preserved.

Decision

Tolaria manages vault AI guidance at the vault root. AGENTS.md is the canonical shared guidance file, CLAUDE.md is a compatibility shim that points Claude Code back to AGENTS.md, and Tolaria classifies both files as managed, missing, broken, or custom so repair flows restore only Tolaria-managed guidance without overwriting custom user files.

Options considered

  • Root AGENTS.md as canonical plus a root CLAUDE.md shim (chosen): matches current agent expectations, keeps one source of truth for shared instructions, and makes repair status explicit.
  • Keep managed guidance under config/agents.md: preserves the older structure, but hides a user-facing integration contract behind legacy config paths and keeps Claude compatibility indirect.
  • Maintain separate full instruction files for each agent: simple per tool, but duplicates instructions and increases drift risk whenever guidance changes.

Consequences

  • New and repaired vaults now seed AGENTS.md and CLAUDE.md at the vault root.
  • Legacy config/agents.md content is migrated forward when safe, then the obsolete file is removed.
  • The status bar and command palette can expose a first-class restore action because backend guidance state is normalized.
  • Custom root guidance files are preserved instead of being silently overwritten by repair flows.
  • Tolaria keeps a single shared guidance document even while supporting multiple CLI agents.
  • Re-evaluate if supported agents stop relying on root-level files or if future agent integrations require materially different vault instructions instead of a shared source of truth.