For the past few months I’ve been bringing spec-driven development (SDD) with AI agents to software development teams. The idea is easy to explain: before writing any code, you write a clear specification, and the agents derive the plan, the tasks and the implementation from it. Making that work with real people is a different story.
These are the lessons that have stuck with me the most. There are no internal details about any company here, only what I think is useful for any team considering this step.
Before: lots of chat, little system
Before SDD, the way people used agents looked a lot like vibecoding. Everyone opened a session, sent messages, corrected things along the way and, with some luck, ended up with something that worked. There was no fixed direction, no usage standard, and no shared guidance on how to ask an agent for things.
The real problem wasn’t the quality of each answer, but where the knowledge ended up. Context, decisions and lessons learned stayed trapped in chat sessions. When a session ended, all of that was gone. The next developer, or the same one the next day, started again from scratch.
What worked: standardize the process, not the prompts
The change with the biggest impact was to stop thinking about “good prompts” and start thinking about a process. We built a multi-step agentic workflow in which every step produces an artifact with a fixed structure: the specification, the technical plan, the tasks. Those artifacts are what ultimately let the agent write good code, because it reaches implementation with the problem well understood.
That workflow lives alongside a quick one for small changes, where walking through every step would be overkill. Having both paths kept the process from feeling like bureaucracy.
The second piece was skills: specialized instructions for each language and type of workflow. A generic agent knows how to code; an agent with a skill that knows the team’s conventions codes like the team.
What didn’t: more context isn’t always better
Our first design produced many artifacts, all of them very thorough. It seemed like a good idea: the more information the agent has, the fewer mistakes it should make.
The opposite happened. The process became slow and tedious, and the extra documents, full of redundant content, confused the agent instead of helping it. We had to cut down both the number and the complexity of the artifacts.
This is probably the most important lesson in this post: supporting documents are useful, but you have to know where to stop. The goal isn’t to give the agent all the context, but the right context. Finding that balance is part of designing the workflow, and you tune it as you use it.
The people: enthusiasm, but also friction
The good news is that developers were proactive. The idea of working with agents in a more structured way was well received.
What was hard was everything around the workflow: the number of things to review at each step, the setup everyone had to do in their own environment, and constantly keeping an eye on the tool’s credit usage. None of that is a big technical problem, but it all adds up, and early on it creates friction.
Teams are still adapting and learning. My takeaway is that adoption has to be designed just like the workflow: cut down manual steps, document the setup and support people during their first weeks, instead of just handing them the tool.
Human review: non-negotiable
If there’s one rule nobody questions, it’s that a person reviews what the agent proposes before moving on. It’s not about distrusting AI; it’s about making sure the agent is heading in the right direction.
We’ve seen it several times: the agent reaches the step right before implementation with a wrong idea about the problem. If nobody notices, that mistake turns into code, and the code turns into rework. When the developer catches it in time and explains the issue, the agent fixes it and the rest of the workflow builds on solid ground. Reviewing at that point takes minutes; skipping it costs days.
What we’re looking at next are living specifications: keeping the spec up to date alongside the code instead of letting it become a document of the past. It’s still at an early stage, but I believe that’s where any workflow like this needs to go.
If you started tomorrow
If your team wants to adopt SDD with agents, these are my two pieces of advice:
- Bring your teams’ knowledge into a format AI can use. Conventions, architecture decisions, how things get done: put it in Markdown files. It takes an upfront effort, but it saves a huge amount of work later and lets you steer the creation and use of agents and skills much better.
- Let developers build the skills themselves. They are the ones with deep technical knowledge. Set up a way to train them in creating skills (with AI’s help, even) and a way to share them, for example through a plugin system. That way, the people who know are the ones who write, review and publish.
The tool matters less than it seems. What makes the difference is a clear process, well-sized context and people who make it their own.