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.
Run Agents That Fit On Your Laptop.
25.6 MB median RSS. 25 agents ran in parallel on a Core 2 Duo with 4 GB RAM. Hundreds on your machine. Zero cloud required on the Ollama path.
Requires Rust/cargo to build from source. Linux and macOS today, Windows not yet supported. Pre-1.0, public beta. Pricing TBD.