The problem
In almost every product project I’ve seen, the truth is scattered, with one rule in meeting notes, another in a design comment and another only in the head of whoever talked to the client. The designer understands one thing, the developer builds another, and the gap only shows up in testing, when fixing it is already expensive.
AI made this worse, because it builds whatever you ask for, fast, including the wrong thing, and with all the confidence in the world. Atlas was born to fix that, as one place where the product is written down and that everyone reads and updates, people or AI, with no parallel documents.
The pillars
Objects before flows. First come the things the product handles, what they are, which states they go through and who can do what with them, and only then come the journeys. The rule lives in the object and the flow just points to it, because every copy of a rule becomes a second truth, and it’s always the copy that goes stale.
Contradiction in plain sight. The specification and the prototype sit side by side, and when they disagree the divergence is recorded, with both sides, until someone decides, so nobody resolves it quietly.
Extract, don’t invent. An unanswered question becomes a pending decision with an owner, and nothing goes in as a guess, not even when the AI is the one writing.
The text describes the now. The page says what the product is today, and what changed, when and why lives in the version history, not in the middle of the text.
How it connects product and development
Everyone has their part and everyone works in the same place, since whoever decides writes the rules, whoever designs starts from them and brings the prototype back to the same page, whoever develops builds from it and testing checks the product against it.
To make that work, each part of Atlas moves through phases, from draft to delivered, and only advances by passing a gate, so you can’t send something to design with an open decision, or to development while the prototype still contradicts the spec.
Before calling a part done, there’s still the gap audit, which means rereading everything as if you had to build it the next day, looking for what was left unanswered, and that’s where questions like “what if two people do this at the same time?” or “how do you ever leave this state?” come up.
AI comes in at every one of these points and helps document, design and build, always starting from Atlas. That’s how it went with Subasta, where I spent 45 minutes writing the product down before any screen and the AI built the rest in a few hours without having to guess anything.
From Notion to GitHub
Atlas was born in Notion, because that’s where the team already worked, and for writing it worked well, but the weak spot showed up when it came to updating.
Notion keeps the past poorly, because it doesn’t show what changed between two dates or who changed each rule, and we ended up writing the history inside the text itself (“it used to be this, now it’s that”) until the page turned into an excavation site. With several people and an AI editing at the same time, it was hard to know which version had been approved.
In October 2026 we moved to GitHub, and each product got its own repository, with version control keeping who changed what, when and why, which freed the page to describe only the now. Each decision becomes a record written for people to read and each approved round bumps the Atlas version, so whoever handles the client compares two versions and whoever develops reads only what changed since the last delivery.
Not everything moved, and the test scripts went into the repository for a while but came back to Notion, because they change with every round of testing and the people who use them work there.
Day to day
Today I use Atlas at three companies, on projects of very different sizes, so a big product gets the full Atlas, while a simple website gets a light version, with just the essentials, and the rest shows up when it’s needed.
What changed most was working with AI, because instead of explaining the product again with every request I point it to Atlas and it reads the rules before touching anything. When a decision changes, it changes in one place, and everyone sees it.
The question I still haven’t answered is how deep to go and how much to simplify, since a method that’s too detailed is one nobody follows and one that’s too simple can’t hold up a real product, and I keep adjusting it with every project.