Spec-driven development: The Good Parts - and what we learned after three months

After three months, we had a clearer picture of when the added structure helped and when it got in the way.

One of our engineers was preparing a data migration and decided to use spec-driven development (SDD) to plan the work. SDD was meant to help them catch gaps early, make the approach easier to review, and give the agent clear direction. The resulting plan was detailed and, on paper, looked pretty reasonable. It structured the work like this:

Problem → Research → Spec → Review → Implementation → Verification

As implementation progressed, the engineer realized that two jobs could race and create duplicate custom fields. The approach was also making the code increasingly complex and difficult to follow. Fortunately, they caught the problem, stopped implementation, wrote a one-page design document, and tagged a couple of coworkers for input. Together, they worked through the design and found a safer approach.

The original spec did what we asked: it kept the project moving in the original direction. The problem was that the direction was wrong. A detailed spec made the project easy to continue, even when the starting idea was shaky. The agent could build out that idea faster than people could stop and question it.

That project showed one risk of added structure: one agent could carry the same mistaken assumption from the spec into the code and tests. The spec, code, and tests agreed with one another, but that didn’t mean the underlying assumption was right. For riskier decisions, someone else still needed to return to the original goal and look for ways the implementation could violate it.

Still, agents were taking on work that lasted longer than one session, and a prompt often wasn’t enough to preserve what the project was trying to do or why. That led us to build /spec-driven, a workflow harness with a spec at its center. The spec kept the project’s direction available to the next session. Scripts brought in context and ran checks. When a run exposed a missing rule, check, or piece of context, we could add it to the workflow so later agents didn’t have to discover the same gap again.

There is still a fair amount of disagreement about whether SDD’s added structure is worth it. Microsoft and AWS promote SDD, while Thoughtworks describes it as emerging and contested and practitioners report mixed experiences. Critics warn that SDD can produce more Markdown than engineers can maintain, turn a detailed spec into code written in prose, or leave behind another description of the system that drifts from the code.[1][2][3]

After three months of real use, we learned that the important question wasn’t whether to use SDD. It was what the agent was missing on that project. Sometimes the answer was a spec. Sometimes it was a better example, an automated check, or an engineer who knew the area.

Why we built /spec-driven

Some engineers at Asana had already tried GitHub Spec Kit and OpenSpec, but neither became part of their regular workflow. We wanted a version we could adapt as we learned and connect to Asana’s development process.

Built-in plan mode could already research the codebase and produce a useful implementation plan before making changes. SDD added more structure around that plan: it kept the problem, key decisions, and acceptance criteria visible through implementation and verification.

Before implementation, /spec-driven played back its understanding of the problem and raised the questions that could change the plan. That gave the engineer a chance to correct the direction before there was code to rewrite.

We stored that state in the repository so later sessions didn’t have to guess what had happened. We wanted the workflow’s rules to be deterministic, so scripts handled the bookkeeping and checks. The model handled the parts that benefited from judgment: asking questions, weighing tradeoffs, and explaining decisions.

The workflow included several commands. Engineers used /spec-driven spec to work through open questions and produce a spec and implementation plan. After reviewing the plan, they used /spec-driven ship to implement it, verify the result, and prepare the work for review. A state machine tracked the project as it moved through these commands, so later sessions knew what had happened and what came next.

From the start, we wanted /spec-driven to be more than just a way to write and carry out specs. We also wanted it to orchestrate agentic workflows. It orders tasks by dependency and keeps overlapping file changes in separate execution rounds. It sends independent work to multiple agents in parallel, then uses the results to decide what can run next.

Feels like a GPS for the work: at any point it’s clear what the next step is and where the real decisions are, so it’s hard to get stuck.”

Asana engineers used /spec-driven in both spec-first and spec-anchored ways. With spec-first, they used a spec to choose a direction, then stopped updating it. With spec-anchored, they kept it current as the work changed. Engineers also wrote independent specs for parts of a larger effort, so one person could use the workflow without asking the whole team to adopt it.

When /spec-driven is worth the extra work

The added structure paid off most when important context needed to survive across sessions, handoffs, or many related tasks. Engineers could review how the plan changed, and the project’s direction remained available when work moved to another agent session or person. Two product efforts kept living specs for roughly two to three months: one building a major new feature, the other rolling subtask dates up to parent tasks.

I just finished a big-ish initiative with spec-driven and I think it really helped me! I worked on the plan for about two days and then got all the engineering work done and merged in three days.”

Specs made handoffs easier. Someone picking up a paused project could see what the team was trying to do, why it had taken that shape, and what remained. They didn’t have to reconstruct the project from commits and conversations.

Engineers also used /spec-driven to coordinate large batches of agent-run work. In Asana’s Admin Console, where IT teams at customer companies manage organization-wide security, access, integrations, and sharing settings, engineers used it to move 66 settings onto shared frameworks. Moving those settings required roughly 150 migrations across several Admin Console frameworks. Each migration became an Asana ticket for a cloud agent, and engineers ran them in parallel batches, updating the remaining tickets based on earlier results.

The team running that effort reported that 91% of the migrations needed no revision after review and that the overall effort shipped more than a month earlier than the original plan.

Another large migration needed only a short prompt. The difference was how much the codebase already made clear. It had examples agents could follow and checks that could verify the result. The Admin Console agents couldn’t figure out every requirement from the code, so the work needed more structure.

/spec-driven also helped with rapid prototyping. Engineers could quickly answer just enough of the open product questions to build a working end-to-end experience. PMs and designers could try a prototype before engineers invested in production hardening. If engineers decided to keep the code, it usually needed substantial cleanup before it could merge. By then, the prototype had already shown whether the idea was worth pursuing.

What the early numbers showed

We encouraged everyone to try /spec-driven once but didn’t require continued use. About half of the engineers tried it. In the final month, weekly use ranged from 30 to 50 engineers. Among the built-in and Asana-developed agent skills that engineers invoked directly, /spec-driven ranked third. Continued use was encouraging, but it didn’t tell us how /spec-driven affected delivery.

Engineering velocity is notoriously hard to measure. Pull requests and implementation-code additions are imperfect proxies for productivity, but we believe they are often directionally useful measures. For the velocity comparison, we looked at seven engineers and 524 merged pull requests over four months. We compared work before and after each engineer’s first clear use of /spec-driven and excluded specs, plans, and other workflow artifacts. For the revert comparison, we classified a pull request as /spec-driven when it changed the workflow’s project files.

Pull requests per week rose 38%, and implementation-code additions rose 2.66×. One short, unusually high-volume window influenced the additions result. Even without it, additions were still 66% higher. The explicit-revert rate was also slightly lower: 1.2% for /spec-driven work, compared with 1.66% for other pull requests.

More code isn’t necessarily a good result. An agent can produce a large implementation when a smaller one would do, so the increase in code additions could have reflected unnecessarily large solutions rather than more completed work. Normal review gave us one check against that failure mode. We relied on reviewers to flag implementations that were larger or more complex than the problem required, and these changes still passed. That gave us some confidence that oversized implementations weren’t driving the whole increase.

These comparisons weren’t controlled, and we couldn’t separate the effect of /spec-driven from project mix or broader improvements in agent tooling. Even with those limitations, we came away encouraged by the results.

What still needs work

Reviewing the documents can become a bottleneck

Creating a spec took anywhere from 30 minutes to several days, depending on the engineer’s familiarity with the area and the project’s complexity and risk. Engineers could use /spec-driven to have an agent draft a spec quickly, but reviewing it still took time.

In one effort, an engineer spent hours reviewing a pull request with research.md, a working file where the agent recorded what it learned from the codebase, documentation, and earlier decisions before drafting the spec. Some of those findings were vague, imprecise, or slightly wrong.

That review showed that we hadn’t agreed on whether these files were temporary working notes or documentation that future engineers should trust. Some engineers valued the record of how a decision was made. Others worried that checking in imperfect research would make it look authoritative.

On one infrastructure team, spec review became a new blocker before implementation.

I thought the commands and workflow felt far more complicated and time-consuming than just generating a plan and then implementing it.”

Most reviewers didn’t want to read a long spec and then review the code too. By the time the work reached a pull request, the handoff needed to summarize the decision, why we made it, what looked risky, and how we checked the result. If the direction itself needed review, we needed to ask for that earlier, while it was still easy to change.

A useful spec changes as the project does

Engineers kept learning as they implemented the plan. Updating the spec with what they learned took effort. Its detail helped during implementation by showing what the agent thought it was building. Afterward, much of that detail repeated the code.

We now think a working spec should grow while the project is uncertain and shrink once the code can explain the implementation. What remains should help the next reader understand the design, important decisions, constraints, and unresolved risks.

Completed specs raise a related question: what should happen to them? We waited too long to answer it. Leaving them in the monorepo makes them easy to find, but also leaves behind documents no one owns. We’re moving them to a separate archive. We still need a shorter handoff that preserves what matters later. If a document created more work than it saved, it wasn’t helping.

Building feedback loops into the harness

Sometimes the answer wasn’t another document but a change to the system around the agent. One example was a bug in how /spec-driven read Markdown: headings and checkboxes inside examples could be mistaken for actual milestones or unfinished tasks. After recording the bug, we searched the rest of /spec-driven and found several commands with their own small Markdown parser and the same blind spot. We replaced them with one shared parser, added regression tests and an architecture check, and put the fix into the environment. OpenAI describes a related approach as harness engineering: put important knowledge where agents can find it, make rules enforceable, and use failures to improve the environment around the agent.

Other lessons couldn’t become a test or architecture rule. We distilled recurring mistakes into guidance. Since /spec-driven guided users through a predictable workflow, we could show each lesson when the agent reached the relevant step. Engineers still decided which lessons applied beyond the original project.

We tested the guidance on eight historical pull requests, along with synthetic cases designed to catch irrelevant advice. In a follow-up, we tested three of those historical tasks with short, medium, and detailed prompts, for nine comparisons in all. Guidance surfaced a useful extra question or planning boundary in eight of the nine comparisons. A separate test covered three more historical tasks. It clearly improved two plans; in the third, the unguided agent had already spotted the issue.

The most useful guidance asked about behavior changes, affected consumers and variants, and contracts between APIs, schemas, or parsers. The evals only covered questions and plans. We didn’t measure whether the guidance sped up implementation. Narrow guidance also became stale faster and sometimes surfaced in unrelated work.

Maintaining the guidance and evals took more work than building the first version. We could map the landmine with guidance, clear it by fixing the underlying system, or accept the risk that an agent or reviewer would have to find it again. We usually mapped it first because that was cheaper. Fixing the underlying API, test, documentation, or example took more work, but benefited everyone and removed the need for the guidance.

How we would approach /spec-driven now

We wanted to stop engineers from repeating the same prompts and re-explaining the project without removing the useful friction. The agent still needed to stop when it had an important question, evidence was missing, or the next step required human judgment. We came away with a few practical guidelines:

• For most small, local changes, a conversation or short plan is enough.

• Use spec-first to agree on a direction. Keep the spec anchored when decisions must survive later sessions or handoffs.

• Don’t put every missing piece in the spec. The harness should supply context and run checks; architectural judgment still needs human review.

When a spec is worth maintaining, write it for the next reader. Keep decisions and risks easy to find, link to evidence instead of copying it, and decide what should happen to the spec when the project ends.

Where we go from here

After three months, engineers still use /spec-driven when work lasts across sessions, passes between people, or breaks into many related tasks. They have used it to keep multi-month projects moving and organize large batches of agent-run work. That is a good result for an internal experiment.

As we expanded /spec-driven to support more kinds of work, some new features solved real problems for particular teams but made the workflow more complex for everyone. In the next version, we want to move toward a smaller, more focused core.

People have strong opinions about SDD and harness engineering. We learned more by trying them on real work than by debating either one. Before adding more processes, we now ask what the agent is missing on that project. Start small, see where the workflow helps or gets in the way, then adjust based on what you learn.

[1] Birgitta Böckeler, “Understanding Spec-Driven-Development: Kiro, spec-kit, and Tessl,” October 2025.

[2] François Zaninotto, “Spec-Driven Development: The Waterfall Strikes Back,” November 2025.

[3] Gabriella Gonzalez, “A sufficiently detailed spec is code,” March 2026.

About the Author

Walter Li is a Software Engineer on Asana’s Core Storage Infrastructure team, and Rohan Batra is a Software Engineer on the Backend Frameworks team. Both spent a few months embedded with the Agent Success Tiger Team, where they led the development and evaluation of the /spec-driven workflow described in this post.

Team Shout Outs

Special thanks to Leo Zhang, Karol Krupa, Gordie Levitsky, and Mitch Conquer for helping us shape and develop /spec-driven and for being early adopters.