AGENTS.md vs Pathrule: When Each One Makes Sense
AGENTS.md became a real cross-tool standard in under a year.
It also inherits the same scaling pattern that broke CLAUDE.md.
Here is how Pathrule sits next to it, not against it.
What this covers
- AGENTS.md is a single Markdown file at the repo root that AI coding agents read for project guidance.
- It is supported by GitHub Copilot, OpenAI Codex, Cursor, Amp, Warp, Aider, Devin, Gemini CLI, Amazon Q, and Windsurf.
- AGENTS.md is great for small repos and small teams. It carries the same scaling pattern as CLAUDE.md once the instruction list grows.
- Pathrule is a path-indexed knowledge graph that delivers a focused slice of team memories, rules, and skills at hook time, before the first tool call.
- For most teams the right answer is both: keep a short AGENTS.md for tool-level conventions and let Pathrule route the long-tail team knowledge per path.
Comparison
| Area | AGENTS.md | Pathrule |
|---|---|---|
| Where it lives | A single file at the repo root | A path-indexed knowledge graph in the cloud, mirrored to a local cache |
| What it carries | Free-form Markdown instructions | Typed memories, rules, and skills with scope and priority |
| When the assistant reads it | On session start, every session, in full | At hook time, scoped to the working directory, focused per intent |
| Scaling pattern | Grows into a long instruction list teams stop reading | Adds nodes near the work, signal stays high as the team grows |
| Review trail | Git history of one file | Change log per node with actor, version chain, and conflict resolution |
| Tools that read it | GitHub Copilot, Codex, Cursor, Amp, Warp, Aider, Devin, Gemini CLI, Amazon Q, Windsurf | Claude Code, Cursor, Codex, Windsurf via one MCP surface |
What AGENTS.md got right
In under a year AGENTS.md went from a proposal to a de facto standard. Public reporting puts adoption past sixty thousand open-source repositories and the file is read natively by GitHub Copilot, OpenAI Codex, Cursor, Amp, Warp, Aider, Devin, Gemini CLI, Amazon Q, and Windsurf.
The reason is simple. Teams were already writing CLAUDE.md, .cursorrules, .windsurfrules, .clinerules, and copilot-instructions.md as separate files for separate tools. Each was different enough to drift, similar enough to maintain twice. AGENTS.md offered one predictable file at the repo root that every agent agreed to read.
That is a real win. The agent context space had a coordination problem and AGENTS.md solved the surface area of it.
What AGENTS.md inherits from CLAUDE.md
The remaining problem is the shape of a flat file. Anyone who used CLAUDE.md at team scale knows the shape.
A small repo writes ten useful instructions and the agent follows them. The team grows. Each new path adds a few exceptions: this folder uses a different test runner, that package is legacy, this surface needs a security note, that data model has a subtle invariant. The instruction list lengthens.
At some point the file crosses the threshold where the model starts treating later instructions as background noise. Practitioners discussing this in 2025 and early 2026 land on a similar number: frontier models follow somewhere around one hundred fifty to two hundred instructions consistently. Smaller models follow fewer. Past that, signal drops and the team cannot tell which rule the assistant respected last and which one it skipped.
AGENTS.md does not solve that. It is a different file in the same shape.
Where Pathrule is different
Pathrule treats agent context as a retrieval problem with a typed knowledge model behind it. Team-written content lives at a path in a workspace tree that mirrors the repo. A memory carries a fact. A rule carries a constraint with an enforcement level. A skill carries a named procedure.
Retrieval walks from the active path up the ancestors. A UI tweak in `apps/web/dashboard` does not need to see the rules about database migrations. A billing change does not need to see the marketing voice guidelines.
The slice is injected at hook time, before the first tool call, from a precomputed local cache. The assistant reads it as system context. There is no extra MCP round trip in the agent loop and no global file that grows forever.
Pathrule is a path-indexed knowledge graph for AI coding assistants. It routes team memories, rules, and skills into Claude Code, Cursor, Codex, Windsurf, and GitHub Copilot at hook time. Source code never leaves the machine.
They are complementary, not competing
The healthy pattern is to keep AGENTS.md short and keep Pathrule for everything that grew the file in the first place.
AGENTS.md is the right home for tool-level conventions that really do apply across the whole repo. The commands the agent should run for tests, the structure of the project, the high-level expectations about commits and PRs. Things that change rarely and matter everywhere.
Pathrule is the right home for the long tail. The schema gotcha for one table. The postmortem from one incident. The convention for one folder. The release checklist for one service. None of that needs to be in every session of every teammate. All of it needs to show up when the assistant works near it.
A concrete shape for the two together
A version of AGENTS.md that pairs well with Pathrule is intentionally small. Five to ten sections. One screen of content. Section headers cover the project overview, the test and build commands, the conventions that really do apply everywhere, the security posture, and a one-line reference that more specific knowledge lives in Pathrule and reaches the assistant through hooks.
Pathrule then carries the rest. Memories at the paths where they are useful. Rules with scope and priority. Skills attached to the surfaces where they are invoked.
This is the structure that scales because each layer is doing the job it is good at. AGENTS.md does the job of a predictable cross-tool entry point. Pathrule does the job of a knowledge graph that grows with the team without bloating the agent context.
Migration is light, not heavy
Teams already running AGENTS.md or CLAUDE.md do not need to throw the file away to try this. The first pass is mechanical. Read the file. Decide which sections truly apply everywhere. Keep those in AGENTS.md. Move the rest into Pathrule under the path where it actually applies.
Most files split in the same direction. A few global conventions stay. A long tail of folder-specific notes moves to nodes. Once the split is done the AGENTS.md gets shorter, the team stops treating it as background noise, and the path-specific knowledge becomes visible at the moment it matters.
If you want to try this on a real repository with us, [email protected] is open. Every signup gets three months of Pathrule PRO on the house. We help teams shape their first migration in the first week.