Working with the Garage Door Up, Without a Door
Why every design doc we write goes straight to a public Git branch, and what we've learned by leaving the door off.
There’s a thing many engineering teams do where design docs get written after the code is already merged, if they get written at all. We do it backwards.
Every Helix feature starts with three Markdown files on a public branch before any implementation starts: a requirements doc, a design doc, and a task breakdown. The agents write these. They take a feature request, draft the three docs, and put them up for human review like a teammate would. We push back, ask questions, suggest pivots. Only then do they start coding.
The reason it’s sustainable is that we build Helix with Helix. The agents drafting our design docs run on the same platform we ship to customers, against the same agent-driven workflow. When we improve the process, we improve the product. When we improve the product, the process gets cheaper. Writing up specs stops being the expensive part of building software when an agent does most of the drafting and a human does the steering.
It sounded performative when we proposed it. In practice it changed how we work, not just how the work looks from the outside. Mid-project architectural pivots become visible while there’s still time to reroute. Comments on design docs interrupt our implementation agents in real time, instead of queueing for review weeks later. Six months on, when the same shape of problem comes back round, the reasoning is searchable, instead of buried in a Slack thread no one can find.
And here’s the part we didn’t expect to land hardest: the agents themselves read the corpus back. When a new feature lands on an agent’s desk, it doesn’t start from zero. It starts from the accumulated design decisions of every feature that came before it. The team has memory. The agents inherit it. Spec-first turns out to be agent-first by side effect. And I’ve found that when a duplicate task arrives, the agent knows that when looks up the design docs.
Read the full post on helix.ml/blog