Q
AGENTS.md or CLAUDE.md?
Both if you use Claude Code heavily; converge on AGENTS.md as the cross-tool base with CLAUDE.md for Claude-specific extras.
Docs · Instruction Files (AGENTS.md, CLAUDE.md)
Instruction Files (AGENTS.md, CLAUDE.md).
Standing orders, kept short.
Direct answer
Keep one cross-tool AGENTS.md plus tool natives (CLAUDE.md, .cursor/rules, copilot-instructions) thin: stack + versions, test/lint/build commands, non-obvious conventions, hard constraints. Everything the agent can infer from code stays out. Measured payoff for well-scoped files: ~29% faster PR tasks, ~17% fewer output tokens.
Instruction Files (AGENTS.md, CLAUDE.md)
Rules
01Only the non-inferableIf the agent can read it from the tree, don't write it. Files carry what code can't say: why, never-dos, environment quirks.
02Scope by locationRoot holds universal truths; packages hold specifics (nested AGENTS.md merge, specific-wins). Cursor rules scope by glob so agents load only their package.
03Version like codePR-reviewed, diff-visible, pruned when behavior drifts. Test changes by watching the agent, not by hoping.
04History goes to memoryDecisions, bug trails, and patterns belong in the Mind graph (weighted, decaying, drift-checked) — not in a markdown file growing toward rot.
Questions
Asked About Instruction Files (AGENTS.md, CLAUDE.md).
Q
How long is too long?
Past a page, split: workflows move to on-demand skills, history moves to memory. Bloated files get ignored and re-bill every turn.
Q
Who owns the file?
The team, in PRs. Convention changes are diffs, not chat messages — ContextOps, not folklore.
Stop Starting From Zero.
One binary. 11+9 Rust crates. 545 tests. Hand-written HNSW index. Three transport modes. Four providers, Ollama, Anthropic, OpenAI, Siemens. Zero API keys required to start. Mind remembers everything after the first session.