Based on Augment Code's thread @augmentcode
There's one piece of documentation you can trust 100%.
The code itself.
Not the design doc. Not the changelog. Not the README, the architecture diagram, or the onboarding wiki. Every one of those becomes stale almost the moment it's written — and stale documentation isn't just useless. In the age of coding agents, it's actively dangerous.
The Documentation Problem Nobody Has Solved
We've been trying to solve documentation drift for decades. We've tried process. We've tried tooling. We've tried making it a team value and a cultural norm. None of it has stuck. And the reason is simple: we keep asking humans to do something humans reliably won't do.
Engineers are built for bursts. Write the doc, ship the feature, move on. Keeping a written artifact in sync with a changing system is continuous, invisible work that competes with everything else on a given day — and it loses that competition almost every time. The updating isn't rewarded, isn't visible, and isn't the interesting part. So it doesn't happen.
Why Spec-Driven Development Has the Same Problem
The promise of spec-driven development (SDD) is compelling: instead of just pasting prompts into a chat window and hoping for the best, you write down what you want before you unleash coding agents. You give them a plan. Obviously better.
But a spec is a document. And we just established what happens to documents.
The difference with SDD is what's at stake. A stale design doc misleads the next engineer who reads it. A stale spec misleads agents that don't know any better. They'll execute a plan that no longer matches reality — confidently, without flagging that anything is wrong. The agent doesn't have enough context to know the ground has shifted. It just builds.
Every documentation-first initiative in software history has failed for the same reason: it asked developers to do continuous maintenance work that nobody sees and nobody rewards. SDD will fail for the exact same reason — unless the agents do their share of the maintenance.
The Question That Changed the Design
When the team at Augment Code started building Intent, the question they kept circling was: what if the spec wasn't something you maintained? What if it maintained itself?
The answer they landed on is deceptively simple.
The spec isn't a human artifact or an agent artifact. Both sides read from it and write to it.
That single design decision changes everything about how the workflow operates.
How Intent Actually Works
You describe what you want to build. A coordinator agent reads your codebase, drafts a spec, and breaks it into tasks. You look at it, edit it, approve before anything runs. Then agents go to work — and as they work, they write back to the spec: what they found, what changed, what constraints they hit that weren't in the plan.
You can pause at any point, rewrite part of the spec, and agents pick up from the new state.
Think about what happens when you hand a task to a good junior engineer. You give them the ticket, they go off and work on it, and when they discover the API doesn't support pagination the way the ticket assumed, they update the ticket themselves. They don't wait for you to notice something is off. They don't just build the wrong thing. They come back and say: "this assumption was wrong, here's what I did instead, here's why." You review their update and either approve or push back.
That's the relationship Intent is designed to create between the developer and the spec. The ticket stays honest because both sides are maintaining it.
Getting the Granularity Right
The junior engineer analogy goes further than you'd expect. A good junior doesn't narrate every line of code — they surface the decisions that change direction: "I found an existing auth context, so I wired into that instead of creating a new one." That's the signal. That's what you want from agents too.
Getting this granularity right turns out to be one of the genuinely hard design problems in the system. Too much and the spec becomes noise you learn to ignore. Too little and you're back to guessing what happened. The goal is a signal-to-noise ratio that mirrors a good engineering teammate: surfacing the things that matter, not everything.
A Concrete Example
You write: "Add a dark mode toggle to the settings page that respects system preferences."
The coordinator reads your codebase, drafts a spec with three subtasks: add the toggle component, wire it to a preference store, update the CSS variables.
You scan it, notice it missed the bit about persisting the choice across sessions, and add a line.
You approve.
Agents pick up the work.
Fifteen minutes later, one of them has updated the spec: "Found an existing theme context provider in the codebase. Wired into that instead of creating a new store."
You review the code change — clearly grouped by agent and task.
The spec now reflects what was actually built, not what was originally planned. And nobody had to remember to update it.
The Principle
If agents can write code, they can update the plan.
The problem with every previous attempt at spec-first or documentation-first development was the maintenance burden. It fell entirely on humans, it was invisible, and it didn't scale. The insight behind Intent is that the maintenance burden can be shared — and that agents are actually better positioned to handle the mechanical part of it, because they're the ones closest to what actually changed.
This doesn't mean specs become self-sufficient. Human judgment is still in the loop at every meaningful decision point: approving the initial plan, reviewing agent updates, catching when an agent's "found an existing thing, used that" actually deserves more scrutiny. The human doesn't disappear. They just stop being responsible for remembering to update a document.
That's the small shift that might finally make spec-driven development work.
Augment Code builds AI coding tools for professional software engineers working with large codebases. Intent is their approach to multi-agent spec-driven development.
Leave a comment ✎