Answers
Your CLAUDE.md outgrew a page. What comes out of it?
The advice to keep a CLAUDE.md under a page is good advice, and the reason it is hard to follow is that two different kinds of knowledge end up in the same file. One belongs there permanently: the commands, the conventions, the mistakes an assistant keeps repeating in this codebase. The other is what a person decided — which rule is in force, why an approach was dropped, what may be promised to a customer — and it grows without limit, because decisions never stop being made. The cut is not between important and unimportant. It is between what a repository owns and what a team owns.
What earns its place in the file
Keep what an assistant needs in order to work in this codebase and nowhere else: how to build and test it, the conventions the code actually follows, the shape of the directories, and the specific mistakes an assistant repeats here. That content is stable, it is owned by the repository, and it is short by nature — it stops growing once it is accurate. If it changes, it changes because the code changed, which means the same commit that changes the code changes the file.
What is making it long
Everything with a person behind it. A decision about pricing or scope, a rule about what may be sent to a customer, the approach the team tried and abandoned, the convention agreed in a meeting by someone who does not commit. Each line is worth keeping and none of them belongs to the repository, so the file grows in the one direction it cannot afford — and the moment it passes the page, the parts that matter most compete for attention with the parts that were merely never deleted.
Where the second kind goes
Into curated memory: written by people and by the assistants they use, sanctioned by a person before it governs anything, carrying an explicit condition that kills it, and ranked against the task at hand rather than loaded whole. The size problem stops being a size problem, because a read selects. A file cannot select — it is text placed in front of the model, all of it, every time, and the only way to keep it small is to keep deleting things a person still needs.
What it looks like in practice
A team's context file reaches four pages. Someone trims it back to one, and the trimming is done by length rather than by ownership: the build commands stay because they are short, and the paragraph explaining why the team stopped using a library goes because it is long. Two weeks later an assistant proposes that library. The trim was performed exactly as advised, and it removed the line that was doing the most work.
Questions people ask about this
- So the CLAUDE.md is wrong?
- No. The file is right for what a repository owns, and Arroway's own repository keeps one for exactly that. What the file cannot do is hold what changes without the code changing, say that a line was superseded, or reach a person who never opens the repository. Those three gaps are what the second layer is for — the file stops growing because the growth had somewhere else to go.
- Can I not just split it into several files?
- You can, and it postpones the problem rather than solving it. More files means more text placed in front of the model, or a loading rule someone has to maintain, and neither addresses the part that actually hurts: nothing in a file says which of two contradicting lines is the one in force today. Splitting organises the text; it does not give a decision an expiry, an author, or a person who approved it.
- What does the assistant read, then, and how do I know it arrived?
- It reads the file for what the repository owns and calls the commons for what the team owns, at the start of the work. That read is ranked against the task it declares and comes back stating the budget it used and what did not fit — so the question "did the assistant actually get our rules?" has an answer you can look at, which is something no file can offer about itself.
Where this is verifiable
Product documentation on this site (How it works, Install) and the sanctioned product spec in the repository. The guidance about keeping a context file short is publicly published practice; every property named here about a plain context file is one any versioned text file has — no expiry, no sanction step, no selection, no delivery receipt. This page makes no claim about the built-in memory of any AI product.
https://www.arroway.app/en/answers/context-file-outgrew-a-page