Turning software specs into a map that AI coding agents can follow

What is it about?

AI coding agents build software from specifications: documents that describe what to build. Today, most specs are long text files or pieces of prompts. Agents struggle to find the right one, to see how specs connect, or to know what to build first. We propose a different approach: store specs as a typed graph. Each spec becomes a node, either something to build (like a Feature) or context you need while building (like an Actor or a Test). Nodes connect in three ways: contains, generates, and relates to. Agents read, walk and update this graph while they work. We ran it at a software company for five months, across four production systems, and surveyed 19 practitioners about it.

Featured Image

Photo by GuerrillaBuzz on Unsplash

Photo by GuerrillaBuzz on Unsplash

Why is it important?

When specs are only documents, an AI has to read and guess. The answer is often good, but it can change from one run to the next. A typed spec graph lets simple, deterministic algorithms answer practical questions instead, every time in the same way: what should be built next, what context a step needs, and what breaks if a spec changes. The framework doesn't impose one structure. Each organization defines its own spec types, and the same algorithms still work. In our deployment, practitioners rated the graph's legibility at 4.07 out of 5. They also showed its limits: understanding what agents do (3.89) is not the same as trusting what they produce (3.53). And 13 of 19 said the graph loses its value without regular maintenance.

Perspectives