Spec-Driven Development in the Real World

There's a major shift happening in AI first development right now. And if

you've been watching my channel, you know I've been talking about this for months. Spec driven development. This is

months. Spec driven development. This is

how professional builders move away from the unpredictability of vibe coding into a workflow that actually ships. It's a

methodical approach that takes your product from idea to customer consistently. And for me as a business

consistently. And for me as a business owner and a product designer, it's what has me fired up about this moment. We're

not just changing how we code, we're changing how we build. So a few months ago on this channel, I introduced spec driven development along with agent OS.

That's my free open-source system for powering a specdriven process. And now

we're seeing the big toolmakers are converging on the same realization that a specdriven approach is the way. And I

love this direction that we're going in as an industry. Just this week, GitHub launched their spec kit project. Amazon

recently released Kirao, which is built around planning with specs. Cursor added

some task tracking stuff to their UI.

Cloud code has had planning mode. So,

we're seeing this spec driven approach make its way into the mainstream tools.

And again, the industry is broadly getting on the page that specs are essential, but the tooling and process behind specri development is still pretty unsettled. And honestly, that's

pretty unsettled. And honestly, that's good. We're all still figuring out what

good. We're all still figuring out what it means to build in the AI first era.

Today I want to examine specri development in the real world because there are three critical aspects that I think the mass market tooling is still

missing and if we don't address these AI adoption with our teams will continue to be an uphill battle. I'm Brian Castle. I

help professionals stay ahead with practical AI strategies and every week I send out my builder briefing. That's a

fiveminute read to help keep you sharp.

You can get yours by going to buildermethods.com and subscribers are always the first to hear about my next live workshop where we talk about what's working with AI. So

for the last few months as I've been applying specdriven development in my own products and watching the tooling evolve, I've noticed three fundamental problems that most tools aren't

addressing. These are things that I try

addressing. These are things that I try to solve as I iterate on agent OS. And

I'll show you how I use that to make my specs actually useful. So the first issue is a lack of process for establishing alignment. So most tools

establishing alignment. So most tools just expect you to show up with a prompt and generate a spec as if they inherently know what you want and how that's supposed to fit in the bigger

picture of your product. But we don't just wake up knowing what to build. Even

when we know what the next feature on our road map is, there's still a crucial phase before creating the spec. And that

involves deciding on the right approach, hashing out the trade-offs, the design decisions, the edge cases, your product strategy. Because we know there are

strategy. Because we know there are always multiple ways to build the same feature. The question is which way is

feature. The question is which way is best for your product and your customers. So the newest version of

customers. So the newest version of Agent OS doesn't rush into writing your specs. Instead, first it has your agent

specs. Instead, first it has your agent work with you on ideiation and strategic planning. This foundational context is

planning. This foundational context is critical if you want agents to build an alignment with your vision. Let me show you what this looks like. So, I'm

working on a simple app called flashcards so that I can quiz my kids on their homework assignments. And in here in the agent OS folder, I have my specs folder. Now, I've already built out the

folder. Now, I've already built out the first uh feature and that's the finished spec right there. So, let's go ahead and start the next spec. I've got Cloud Code open here and I'm going to start with

new spec. Just going to run the new spec

new spec. Just going to run the new spec command. Now, if you're familiar with

command. Now, if you're familiar with agent OS, you know that I already have my uh product plan with the road map and mission built in. So, uh agent OS did reference that and it's asking me if I

want to uh just build the next item in my road map and I can check my road map here.

So, we've already built out uh these two parts and now we need to build out the question builder interface for multiple choice questions. Let's go with that. So

choice questions. Let's go with that. So

now it's using sub aents for every step in the process if you're using cloud code which supports sub aents and you can see that we've now built out the folder for the next spec. That's the

question builder interface and we're initializing here. Okay. So now it has

initializing here. Okay. So now it has passed the baton onto the spec researcher sub aent and that one is here to help me research and plan and hash out the details for this new feature

before we even get into writing the spec. So, as you can see, it came up

spec. So, as you can see, it came up with a list of clarifying questions. Uh,

looks like we have nine of them. I just

want to point out that built into agent OS, I've instructed the agent to analyze my mission, my product road map, my standards, and the initial idea for what

this feature is going to be, and then to come up with clarifying questions.

Specifically, I told it to number them, which is going to make it easy for me to just answer, you know, number one answer, number two, answer, number three. The other thing that I said was I

three. The other thing that I said was I wanted to ask the questions and then provide a sensible assumption as the probable answer to the questions. And

that makes it really easy for me to just do things like number one, yes, number two, yes, number three, let me course correct a little bit, number four, yes.

So, you know, just making the process of planning and ideulating and hashing out a little bit easier than for me to have to come up with these questions on my own. And one more tip, I also emphasized

own. And one more tip, I also emphasized the importance of referencing pre-existing design elements and architectural elements in the codebase itself um when it's coming up with these

questions. And uh as you can see down

questions. And uh as you can see down here we have a section where it asks me literally are we going to be reusing any existing code or you know components in

the uh codebase. So this is all really important planning material that should go into the process. So let me go through and answer these questions.

Okay. So I've added my answers to questions 1 through nine. As you can see it's really easy for me to just confirm the uh assumption that the agent made and make some very minor uh course

corrections. I forgot to add the note

corrections. I forgot to add the note about uh existing reuse. Um

so I'm saying like reuse our existing styling around the the existing questions UI that we have. And then

there's one final thing that agent OS asks for. Now we have a visuals folder.

asks for. Now we have a visuals folder.

And this is optional, but if you have any sort of mockups or wireframes, now is a great time to put them into the planning. Agents work so much better

planning. Agents work so much better when they get to follow an actual visual reference. And uh I do have a very

reference. And uh I do have a very simple um rough wireframe. I'm going to just drop that into the visuals folder.

So we have that in the planning for this spec. And we also have it built in to

spec. And we also have it built in to recognize whether this is a detailed mockup versus just a rough wireframe. In

this case, it's going to know that it's a wireframe. Okay. So I think we're good

a wireframe. Okay. So I think we're good on my initial questions and I'm going to send those along. All right. So we're

not done yet. Uh, the agent just analyzed both my answers to the first set of questions and it took a look at the wireframe that I provided it and it came up with a couple additional

clarifying questions just to really make sure that we're on the same page. It

noticed something that I put into my visual wireframe and it wants to confirm the direction here. It even pointed out that I forgot to mock up a detail to, you know, select which is the default answer.

And again, it worded them in ways that make it really easy for me to quickly respond. It says like, would you like to

respond. It says like, would you like to do it this way or that way? And I can just say option A, you know. Okay, so

the spec researchers work is done. And

let's see what we have so far. So again,

we're we're inside the spec folder. We

have not created the actual spec yet, but so far we have this planning folder.

Inside that we've got our visual, that's our wireframe, and we have this initialization. This is just very

initialization. This is just very simple. was, you know, just to record my

simple. was, you know, just to record my very first direction. And then we have this requirements document. It it just serves as a reference and a record of

the discussion that we had each question that the agent asked me uh what my answers were and um it has the follow-up questions. it, you know, references some

questions. it, you know, references some existing code and it has some notes on the visual assets and it analyzed them and and gave itself some notes on what it found some visual insights,

functional requirements. So again, I can

functional requirements. So again, I can like even go through here and just double check that all these details are in fact correct. You know, I might check things like, did I actually answer the

right thing? Or do I want to rethink

right thing? Or do I want to rethink certain details about how this feature should be designed? Or I might want to check to see the agent actually interpreted what I had to say correctly because a lot of this stuff is, you

know, notes in the agent's words, not mine. I'll go through and double check

mine. I'll go through and double check these, but again, like this is sort of like the raw material, the strategic and design decisionm that together we've come up with. And now it's sort of in

the context, but we also have it documented here in the folder. So now I can proceed with the actual creation of the spec with much higher confidence that the content of the spec is going to

be exactly what I want. Look, this is where our craft happens. Now, of course, we know how our code is going to fit together, but our agents can build most of that. Where we bring value is through

of that. Where we bring value is through design and our taste and experience and understanding what our customers need.

That happens here in the planning phase.

All right. Now, while the spec writer sub agent is writing up our spec, I want to talk about the second big issue that I'm seeing and that's missing context about your standards. So, in order to

write specs that ensure agents will build correctly the first time, we need granularity about how the code should be written. So just telling our agent to

written. So just telling our agent to build a React app or build a Rails app, that's not enough. There are countless variables, your text stack, your code style, your existing libraries,

established patterns, components, layouts that you've already developed.

We need our specs to instruct our agents to adhere to all of these directions.

And we can't just assume that their quick codebase scan is going to pick up everything. We also can't just retrain

everything. We also can't just retrain our agents on every new feature that they develop because then we're just back to prompting in circles. So, as

I've shown in my previous videos covering agent OS, it lets you define your coding standards and your design choices and your common patterns once.

So, when your specs get written and your code gets implemented, your agents already have that knowledge baked in.

So, it looks like our spec is almost ready. The spec writer finished its work

ready. The spec writer finished its work and now it passed the baton onto our spec verifier which is checking the spec writer's work, making sure that it's all accurate, that we uh crossed our tees

and dotted our eyes, if you will, and that's all set. So, here is everything that it did. So, let's go ahead and take a look. So, now we have our official

a look. So, now we have our official spec.md. Now, I used to have a much more

spec.md. Now, I used to have a much more complex version of this, but I purposely had the agent simplify it down to just a one-pager. We've got the goal. We've got

one-pager. We've got the goal. We've got

a couple of user stories, some functional requirements, some nonfunctional requirements. Uh then we

nonfunctional requirements. Uh then we have some notes on the visual design referencing the uh the visual that I had provided. We're also calling out to some

provided. We're also calling out to some reusable components that already exist in the codebase so that you know the agent can leverage those and not rebuild the same thing twice. We've got some notes on the technical approach. This is

intentionally not going into great detail because, you know, we still want to let the actual coding agent and the specialist sub agents that are going to be uh responsible for these items sort

of do their thing rather than leading them down potentially the wrong path up front. So, you know, this is just the

front. So, you know, this is just the highle specification, but it is highly accurate. As you can see, there are now

accurate. As you can see, there are now multiple layers at play here. We did the initial Q&A and clarifying and and hashing out of the details. Then it went through and and created the uh the

specification which also took into account my standards that are built into agent OS and we had the verifier agent come in and and look at it all and now I'm putting my human eyes on it as well.

So we've got our spec and then we have our tasks. So this is the actual task

our tasks. So this is the actual task list that would be implemented once we get to the implementation phase. It is

broken out into task groups each with a main parent task and some subtasks. The

other thing that you'll notice is that agent OS is suggesting which sub aent like in this case doing the database updates that's going to go to the database engineer sub aent and getting

down into the API layer that'll go to the API engineer. Um so we're grouping these into groups of tasks that individual sub aents can tackle sort of

like separately and that'll be really useful when it comes to implementation.

You know, here we're going to work on the UI. So, we're going to delegate to

the UI. So, we're going to delegate to the UI designer sub agent. So, you know, agent OS 2.0 when you're using it with cloud code is going to be heavily built around this idea of orchestrating

multiple sub aents to pick off each individual uh task group when it comes to implementation. Now, of course, I I

to implementation. Now, of course, I I can still review these tasks. I can even review which agent it's planning on delegating to. Um, and these are things

delegating to. Um, and these are things that I can tweak and change on the fly.

like this particular feature might be built a little bit differently than the last feature that I built or I might be doing things a little bit different in this project versus a different project.

And so agent OS gives me that flexibility to spin up different types of sub aents and incorporate them into my process in different ways depending on the project. And in fact, that brings

me to the third and I think the most important factor when it comes to real world adoption of these AI tools and spec driven development and that is the tooling can't be too rigid about

defining our development process.

Because look, we all build differently.

Your team might take an API first approach. Mine might emphasize UI first.

approach. Mine might emphasize UI first.

You might have 30 engineers in a department or she might be working at a startup with three co-founders. His team

over there might have multiple testing phases. Hers prioritizes getting a

phases. Hers prioritizes getting a product out to customers quickly. And

each feature in your product might be built a little bit differently. One

might involve a lot of API and database changes and the next feature might focus more on UI and the one after that might just concern the mobile app. Each spec

involves different sub aents and a different mix of phases in your development process. You know, if your

development process. You know, if your tooling adds friction as you or your team is moving between different features, different products, that can prevent full adoption of specd- driven

development, and then you'll miss out on the benefits and the leverage that AI first development has to offer. So, in

designing the newest version of Agent OS, one of my goals is to make it as adaptable as your development process requires. It leverages sub agents and

requires. It leverages sub agents and orchestration that you can control as you move between specs. So, I'll be sharing my latest patterns in spectriven development and in agent OS in my next

live workshop and in my builder briefing newsletter. So, you can get on that by

newsletter. So, you can get on that by going to buildermethods.com.

And speaking of patterns, now that we're rethinking what it means to build and ship products, it's easy to lose that sense of flow that we used to have when we were deep in our code bases before

all these AI agents came along. But I

think it's still possible to achieve that flow state, which can lead to breakthroughs in your product. You can

see my recent video on finding flow with spec driven development. And so after you hit that subscribe button, head over there, check that one out next, and let's keep building.