I run a home server with somewhere around 100 small projects on it, and I do the work with AI agents, mostly through Claude Code. For a long time the agents kept guessing: What port is this service on, what's the path to that config, is this the name of the real thing or the name of the thing from three rewrites ago. They would guess, act on the guess, and sometimes the guess was wrong and something broke.
The instinct is to write it all down which I tried. Documentation is outdated the moment reality moves and reality moves constantly on a box like this, because I'm the one moving it, on a whim, at whatever hour I feel like it. A doc that says a service runs a certain way is only true until I change it and forget to update the doc, which is most of the time. Well it is until I remember to update documentation, but I never remember all of it. So the agents would read a doc, trust it, and be wrong anyway.
The registry instead of the doc
The fix I landed on, with a lot of help from the agents themselves, was to stop writing documentation as the source of truth and make a registry the source of truth instead, and that is Atlas. It is an entity store, projects, services, servers, rules, and a set of shared vocabularies, and every one of those things is a record with a defined shape, not a paragraph of prose someone has to keep current by hand.
Atlas is exposed to the agents as a set of tools rather than a folder of files, and when an agent needs to know what a service is called, what it does, or where it lives, it asks Atlas instead of scanning the filesystem or inferring from a stale doc. There is a rule that sits ahead of everything else, discovery before change, meaning an agent is supposed to look a thing up before it touches it, not act on a guess.
Writes work the same way, an agent does not just update the registry because it decided something should change. It proposes the change, shows what it would do, and only applies it once that is confirmed. That way the registry cannot drift just because an agent got a little too confident about what it should be doing.
Checking itself against reality
Atlas does not just trust its own records either, there are drift checks that go and look at what is actually running on the box, and compare that against what the registry claims. If the registry says a service exists and the box disagrees, that is a finding instead of something that is just wrong in a doc nobody is going to reread.
Every session starts by loading Atlas, so an agent never opens cold, it gets oriented before it does anything, and it does not have to reconstruct the shape of a hundred-project stack from scratch every single time, which is roughly what was happening before.
What changed
The registry currently tracks around 100 projects and something like 150 to 160 services, spread across a handful of servers, with more than 40 rules recorded as actual policy instead of just stuff I remembered and never wrote down, and I do not think I could hold all of that in my head reliably, and I do not think the agents could either without somewhere to ask.
What changed in practice is that fewer sessions start with an agent breaking something because it guessed a path or a port and got it wrong, and recall got cheaper too. A question like "what do we have for X" used to mean digging through files by hand, now it is usually a lookup.
What it still gets wrong
It does not fix everything. The registry is only as good as what is been entered into it, and there is still plenty that has not caught up, meaning an agent can ask Atlas a correct question and get an answer that is technically present but out of date if nobody's gone back and reconciled it recently. Well, the drift checks catch a lot of that, but only for the things a drift check has been written for, and anything nobody thought to probe can still sit wrong for a while.
It also does not replace judgment, Atlas can tell an agent what exists and what is supposed to be true, but it cannot tell it what is a good idea, and it was never meant to. Some of the writing about it still lives as design intent rather than something that is actually built yet, and I try not to talk about the parts that are still just an idea as if they are already running.
As far as I can tell, Atlas did not solve the underlying problem so much as move it somewhere I can watch it, drift still happens but now I can see it.