Compare
Milestone vs CLAUDE.md
CLAUDE.md is the file Claude Code reads at the start of every session - your repo’s standing instructions, written by hand. It works, and you should keep it. Milestone is a different thing: a shared context layerthat fills itself from your team’s work and serves the relevant slice to any agent over MCP. This page is about where the file stops being enough.
Updated August 3, 2026
The short version
A rules file is the right tool for stable, repo-scoped instructions a human owns - build commands, style rules, “never touch this directory.” It breaks down on four things: knowledge that belongs to the team rather than the repo, context that has to hold across repos, machines, and agents, the reasoning behind a rule, and anything nobody remembers to update. If none of those bite you, you don’t need Milestone yet.
At a glance
| Milestone | CLAUDE.md & rules files | |
|---|---|---|
| What it is | A shared team knowledge graph, served to agents over MCP | A markdown file in your repo, read at the start of each session |
| Scope | Team, workspace, board, or person | One repo, plus a personal global file on your machine |
| Who maintains it | Captured from real work, then reviewed by a human | A human, by hand, remembering to |
| Holds the reasoning | Yes - decisions link to the conventions they set | Only the rule, unless someone also wrote down why |
| Across agents | Agent-neutral over MCP - Claude Code, Codex, and others | One file per agent: CLAUDE.md, AGENTS.md, .cursor/rules |
| Across people & machines | Shared and synced by default | Committed per repo; personal and learned memory stays local |
| How it reaches the model | The relevant subset is retrieved for the task at hand | The whole file is loaded into context, every session |
| How it goes stale | Review surface surfaces new and superseded knowledge | Silently - a wrong rule reads exactly like a right one |
| Setup cost | Install the app, connect the agent | Create a file |
| Pricing | Free forever + Pro $12/seat/mo (free during early access) | Free |
Milestone pricing shown in full - see the pricing page. Rules files cost nothing, which is a genuine advantage and worth weighing honestly.
Keep your CLAUDE.md
Start here, because most comparisons on this topic won’t. A rules file is the correct tool for a specific class of thing: instructions a human owns, that apply to one repo, that rarely change, and that the model should follow every single time. Build and test commands. Style rules. “Use pnpm, not npm.” “Never edit files under generated/.” Nothing about a memory layer improves on a file for that job, and Milestone doesn’t ask you to delete it. The interesting question is what a file is bad at.
A file is per-repo. A team’s knowledge isn’t.
The convention that agents keep violating usually isn’t a property of one repository - it’s a property of how your team works, and it applies across the services, the front end, and the infrastructure repo nobody touches often. With rules files, that means the same paragraph copied into several files, drifting apart as each gets edited. Worse, the most valuable knowledge is often the most local: a gotcha in one module that has bitten three people. That belongs to a code area, not a repo, and a flat file can’t express the difference.
The decay is silent, and that’s the real problem
Rules files rot in a way that’s uniquely hard to notice. A stale rule looks identical to a live one, so nobody catches it in review, and the model follows it with total confidence. Six months in, the file is part instructions and part archaeology, and no one is sure which lines still hold. Milestone attacks this from the capture side: when an agent learns something during a session, it lands on a review surface (/context) where a human approves it before it becomes team knowledge, and superseded conventions get replaced rather than accumulating.
Loading everything vs retrieving what matters
A rules file is loaded in full at the start of every session, so it spends context budget in proportion to its length whether or not any of it is relevant to today’s task. That creates a quiet ceiling: the more you write down, the more each session costs, so teams keep the file short and leave the most useful specifics out. Retrieval changes the shape of that trade. Milestone serves the conventions, prior decisions, and gotchas for the area being touched, which means the knowledge base can grow without every session paying for all of it.
The rule survives. The reason doesn’t.
A rules file records conclusions: “always use the repository pattern for data access.” It very rarely records why, what was tried first, or what broke. So when someone - human or agent - hits a case where the rule is a bad fit, they have no way to tell whether they’ve found an exception or are about to repeat a mistake from last year. Milestone models the decision and the convention as separate, linked things, so the “why” is still there and still queryable when it’s needed.
One file per agent doesn’t scale either
Most teams no longer use one agent. Claude Code reads CLAUDE.md, Codex reads AGENTS.md, Cursor reads its own rules directory, and each new tool adds another copy of the same conventions to keep in sync. Milestone is deliberately agent-neutral: the knowledge is served over MCP, so it’s the same context regardless of which assistant is asking. Your team’s knowledge belongs to your team, not to a vendor’s file format.
Where a rules file is genuinely enough
If you are one person on one repo with conventions that fit on a page and rarely change, a rules file plus Claude Code’s own memory is the right answer and Milestone is overkill. It’s free, it’s in version control, it’s reviewable in a pull request, and it has no dependencies. The honest threshold for adding a memory layer is roughly: more than two or three people, more than one repo, more than one agent, and a recurring feeling that you’ve explained this before.
Who each is for
Choose Milestone if…
- Several people run agent sessions on the same codebase
- The same conventions live in several repos and drift apart
- You want the reasoning behind a rule, not just the rule
- You use more than one agent and keep syncing rules files by hand
Stick with CLAUDE.md & rules files if…
- You're solo, on one repo, with conventions that fit on a page
- You want everything in version control and reviewable in a PR
- Your rules are stable and you're happy maintaining them by hand
- You'd rather add nothing new to your stack
Moving from CLAUDE.md & rules files
This isn’t a migration, because nothing has to leave. Keep CLAUDE.md for what it’s good at - build commands, hard constraints, repo mechanics. What tends to move out is the part that was never comfortable in a file: team conventions that span repos, the reasoning behind past decisions, and the gotchas someone added at 2am and nobody has verified since. In practice teams find their file gets shorter and more accurate, because the things that were rotting in it now live somewhere that reviews them.
Questions
- Does Milestone replace CLAUDE.md?
- No, and it isn't meant to. A rules file is the right tool for repo-scoped instructions a human owns and that rarely change - build commands, style rules, hard constraints. Milestone handles what a file is bad at: knowledge that spans repos, the reasoning behind a convention, gotchas tied to a specific code area, and anything that needs to stay current without someone remembering to edit it. Most teams end up with a shorter, more accurate CLAUDE.md, not none.
- Why does Claude Code forget things between sessions?
- Because each session starts a fresh context window. Claude Code carries two things forward on its own: the CLAUDE.md files it reads at startup, and its own memory of learned patterns. Everything else - what you explained mid-session, why you rejected an approach, the gotcha you hit an hour in - lives only in that conversation and is gone when it ends. Persisting that requires somewhere outside the session to write it, which is what a rules file, a memory MCP server, or a shared context layer each do differently.
- What should go in CLAUDE.md, and what shouldn't?
- A useful rule of thumb: if a human owns the fact, it applies to this repo, and it rarely changes, it belongs in CLAUDE.md - build and test commands, style conventions, directories to leave alone, hard constraints. If the fact is accumulated rather than authored, spans repos or people, needs the reasoning attached, or should be reviewed before every future session inherits it, a file is the wrong container. Also worth watching: the file is loaded whole into every session, so length has an ongoing cost.
- Isn't a rules file better because it's in version control?
- For some things, yes - and that's a real advantage worth keeping. Review in a pull request is a genuine quality gate, and diffs tell you what changed. The catch is that it only reviews what someone chose to write. Most of what a team learns during agent sessions never reaches a file at all, because writing it down is a separate act of discipline nobody has time for. Milestone captures those learnings as they happen, then puts them through a review step before they become durable.
- Does Milestone work with Codex and other agents, or just Claude Code?
- It's agent-neutral by design. The knowledge graph is served over MCP (the Model Context Protocol), so any MCP-capable assistant can read context and write learnings back - Claude Code and Codex among them. That's the point of not storing your team's knowledge in a vendor-specific file: CLAUDE.md, AGENTS.md, and .cursor/rules each cover one tool, and keeping them in sync by hand is work that grows with every agent you add.
- Is CLAUDE.md enough for a team?
- It can be, up to a point. The threshold is roughly: more than two or three people running agent sessions, more than one repo, more than one agent, and a recurring sense that you've explained this before. Below that, a file plus the agent's built-in memory is cheap and works. Above it, the failure modes compound - copies drift between repos, stale rules read exactly like current ones, and the reasoning behind conventions is nowhere.
Related comparisons
See it on your own project.
Join the design-partner program - free during early access. Keep your rules file; we’ll connect the memory layer alongside it.
Free during the design partner program · no card required · we only email you about early access.