I call them project brains

I call them project brains. The real filename is AGENTS.md, it is an open standard, and you do not have to buy anything.

Every project folder in my workspace has one: a file telling any AI tool what the project is, its rules, and where the current truth is written.

What the file actually is

OpenAI published AGENTS.md in August 2025 as a convention rather than a product. It is now stewarded by the Agentic AI Foundation under the Linux Foundation, alongside the Model Context Protocol and goose as the three anchor projects, with Anthropic and Block as co-founders and Google, Microsoft, AWS, Bloomberg and Cloudflare behind it. Over 60,000 open source projects use it. Codex, Cursor, Copilot, Gemini CLI, Devin, Jules and VS Code read it natively.

So the thing I am describing is a plain markdown file, in your repository, in version control, that the major agents already look for without being told. That is the whole mechanism. Everything below is what happens once you have one.

What you get

Portability, which is the one that costs real money later. The file belongs to your repository, not to a vendor’s memory feature. I have driven three different agent tools over the same tree and the context stayed where it was.

Not perfectly, and the detail matters more than the claim. When I moved five of my own instruction and skill files to a third tool, the things that broke were assumptions rather than content: hardcoded mount paths, a dependency on one vendor’s interactive prompting, and gates that named a specific model family. All of it was fixable in an afternoon. None of it required teaching the tool what the projects were.

Onboarding, from the same file. What briefs an agent briefs a new engineer. That matters because it changes the incentive: documentation nobody reads rots quietly, and a file an agent reads on every session breaks loudly when it is wrong. You find out in days rather than at the next handover.

Boundaries, and this is the one I would care about most in an enterprise seat. An agent with access to a whole workspace does not know what must not be mixed. Client material. Regulated data. One business unit’s numbers surfacing in another’s output. A model has no intuition about your org chart or your contracts. If a boundary is not written where the agent reads, it is not a rule. It is a hope.

Where it goes wrong

Two copies drift, and the stale one wins whichever tool happens to load it. Different tools look for different filenames, so the temptation is to keep one of each. Do not. Keep one real file per folder and make any second one a pointer to it.

Watch the pointer too. Mine are a mix: nine folders carry the canonical-plus-pointer arrangement, but only one of those pointers is a true filesystem symlink and the other eight are small text stubs saying which file to read. That is not tidiness for its own sake. The one real symlink cannot be read at all by one of my own sandboxed environments, which returns an I/O error and moves on. A convention that works in one tool and silently fails in another is worse than a convention you know is manual.

It becomes a dumping ground. Mine total about 80 KB across 22 files. At least one popular tool applies a default size cap and truncates past it without saying so, which means the second half of a long file can be quietly ignored while you believe it is being read. Long is not thorough. Long is ignored.

It goes stale and nobody notices. This is the failure I would bet on in any organisation. While writing this piece I found one of my own status files three days out of date on a decision I had already recorded properly somewhere else. The system knew where the truth lived. It did not stop me leaving a stale copy next to it. So the habit that matters is not writing the file, it is saying so out loud when two files disagree instead of quietly picking one.

What it costs to skip it

The context does not disappear if you never write it down. It moves into individual people’s prompts and chat histories, which your vendor holds and you do not. You cannot diff it, you cannot review it, and you cannot quote a line of it in a meeting.

Every session then pays the explaining cost again. Because that cost is spread thinly across everybody who works with an agent, it never appears as a line item and nobody proposes fixing it. It shows up instead as a vague sense that the pilots are not adding up to anything.

And then somebody asks the question that ends the discussion: what exactly was the AI told before it produced this? Without a file in version control, there is no answer. With one, the answer is a commit.

The method, and where it is weak

The numbers above come from counting my own tree on 7 August 2026: 16 top-level project folders, 12 of which carry their own instruction file, 22 real instruction files totalling 80,846 bytes, 9 folders using the canonical-plus-pointer arrangement, exactly 1 of those pointers a true symlink. The three-tool portability claim covers roughly four weeks of work across those projects.

Three honest limits. This is one operator’s workspace, not a 200-engineer estate, and I have not tested whether the convention survives a large team’s rate of change. The file-size cap I mention is documented in secondary guides rather than in a primary source I could verify, so treat the specific threshold as directional and check your own tooling. And the boundary point is the one I am least able to prove: I can show you that the rules are written where the agents read them, but a written boundary is still a convention, not a control. Nothing in my setup physically prevents a boundary from being crossed. That gap is real and I have not closed it.

Where to start

One project. Half a page. What this is, who owns it, what must never leave it, and where the current truth is written. Then add the next project when the first one has survived a week of actual use.

It is not a platform decision. It is a file.

Written with AI as a tool: research, structure and drafting with Claude; the judgment and every claim are mine.

Source post: Post | LinkedIn