Many people who start building products with AI take the same path, asking for a screen, looking at the result and asking for tweaks until it looks right. I did a lot of that too, and over time I understood that the screen is the part AI does best, and that what went wrong came before it, in the decisions nobody had made. Today my work starts with those decisions, written in a document I call Atlas, and in this note I explain what it is for anyone who has never heard of it.
The problem Atlas solves
Every digital product is made of many small decisions, like what happens when someone gets their password wrong, who can delete an account or what the system does when two people change the same thing at the same time. In a typical project, those decisions end up scattered, one in a meeting, another in a message and another only in the head of whoever talked to the client, and everyone on the team pictures the product a little differently.
The result shows up late, when whoever designed it expected one thing, whoever built it delivered another and the gap only appears in testing, which is when fixing it is already expensive. AI makes this worse, because it quietly fills in every decision that was missing and delivers something that looks finished and breaks on first use.
What Atlas is
Atlas is a single document that describes the whole product, in plain language, before any screen exists. The best comparison I know is a house floor plan, because nobody calls a builder and asks for “a nice house” without first having on paper how many rooms it has, what goes in each one, how people move through it and which wall can’t be moved.
It’s always written in the same order. First comes the Constitution, with what the product is, the words it uses and the rules nothing can break. Then come the objects, the things that exist inside the system, each with the states it goes through and what each person can do with it. Last come the flows, the paths people take through the product, which don’t repeat the rules but only point to them, because a rule copied in two places ends up different in both.
Nothing goes into Atlas as a guess, so every unanswered question is marked as pending, with the name of whoever will decide. Once the document is closed, whoever designs starts from it to make the screens, whoever develops starts from it to build, and any change that comes up along the way goes back to the same place instead of becoming a conversation nobody recorded.
Why it works so well with AI
AI builds whatever you ask for, fast, including the wrong thing, so what it needs from you are the decisions. When I show up with the product written down, there’s nothing for it to make up, because the answer to every situation is already there, and that’s how on Subasta I spent 45 minutes writing Atlas and the AI built the rest in a few hours.
Atlas also keeps contradictions in plain sight. The specification and the prototype sit side by side, and when they disagree the difference is written down until someone decides, instead of each person, or each AI, resolving it their own way without telling anyone.
When the whole company becomes context
Atlas on its own already helps a lot, but it pays off much more since it became part of a bigger environment. At my two companies, Oroz and Sincera, each with its own, we’ve been building what we call the company OS, which is the business’s entire context written down as documents and skills. Skills are instructions that tell the AI what to do, how to do it and which steps to follow to reach a result I’ve already tested and know works.
In practice, that changes the kind of request I make. Instead of explaining the product again in every conversation, I ask the AI to follow the process, and it already knows it has to read Atlas before touching anything, how to document a new flow, how to turn that flow into screens and how to record what changed, because each of those steps became a skill after it worked at least once. That’s how I turned a deliverable into a process, and Atlas is the part of that process that takes care of the product.
From paper to testing
The most recent step to come in was testing, and that’s when Atlas stopped being just a planning document. Technical testing starts from Atlas itself and tries to break the system rule by rule, and each problem it finds becomes a record with a screenshot, organized in batches for whoever develops. Then comes usability testing, with missions taken from the flows, to see whether a real person understands the product without help, and when the problem is the copy, the skill itself already suggests better wording.
Since both tests read the same Atlas that guided design and development, the question stops being whether the product works and becomes whether it does what we decided it would do, which you can answer with yes or no.
Where I have less control
At Oroz and Sincera, I help design the whole environment, so it’s natural for Atlas to fit into it. The harder test is at CodingIT, where I’m Head of Product and UX and have much less control over what’s around me, and that’s where I’m implementing Atlas now, to find out how much of it holds up when I’m not the one who built the rest.
I don’t know the answer yet, which is why this note is part of a series. What I already know is that Atlas stopped being a document I write before building and became the concrete form of a process that keeps growing at both companies, and that each new project leaves that process a little better than the last one.
Written by Matheus Sá. Disagree or want to add something? Write to me.