Spec-Driven Development in the Real World — Transcript

Full transcript

1. 0:00There's a major shift happening in AI
2. 0:01first development right now. And if
3. 0:03you've been watching my channel, you
4. 0:04know I've been talking about this for
5. 0:05months. Spec driven development. This is
6. 0:08how professional builders move away from
7. 0:10the unpredictability of vibe coding into
8. 0:13a workflow that actually ships. It's a
9. 0:15methodical approach that takes your
10. 0:17product from idea to customer
11. 0:19consistently. And for me as a business
12. 0:21owner and a product designer, it's what
13. 0:23has me fired up about this moment. We're
14. 0:25not just changing how we code, we're
15. 0:27changing how we build. So a few months
16. 0:29ago on this channel, I introduced spec
17. 0:31driven development along with agent OS.
18. 0:34That's my free open-source system for
19. 0:36powering a specdriven process. And now
20. 0:39we're seeing the big toolmakers are
21. 0:41converging on the same realization that
22. 0:44a specdriven approach is the way. And I
23. 0:46love this direction that we're going in
24. 0:48as an industry. Just this week, GitHub
25. 0:50launched their spec kit project. Amazon
26. 0:53recently released Kirao, which is built
27. 0:55around planning with specs. Cursor added
28. 0:57some task tracking stuff to their UI.
29. 0:59Cloud code has had planning mode. So,
30. 1:01we're seeing this spec driven approach
31. 1:03make its way into the mainstream tools.
32. 1:06And again, the industry is broadly
33. 1:08getting on the page that specs are
34. 1:10essential, but the tooling and process
35. 1:13behind specri development is still
36. 1:14pretty unsettled. And honestly, that's
37. 1:17good. We're all still figuring out what
38. 1:19it means to build in the AI first era.
39. 1:22Today I want to examine specri
40. 1:24development in the real world because
41. 1:26there are three critical aspects that I
42. 1:29think the mass market tooling is still
43. 1:31missing and if we don't address these AI
44. 1:34adoption with our teams will continue to
45. 1:36be an uphill battle. I'm Brian Castle. I
46. 1:38help professionals stay ahead with
47. 1:40practical AI strategies and every week I
48. 1:43send out my builder briefing. That's a
49. 1:44fiveminute read to help keep you sharp.
50. 1:47You can get yours by going to
51. 1:48buildermethods.com
52. 1:50and subscribers are always the first to
53. 1:52hear about my next live workshop where
54. 1:54we talk about what's working with AI. So
55. 1:56for the last few months as I've been
56. 1:58applying specdriven development in my
57. 2:00own products and watching the tooling
58. 2:02evolve, I've noticed three fundamental
59. 2:05problems that most tools aren't
60. 2:06addressing. These are things that I try
61. 2:08to solve as I iterate on agent OS. And
62. 2:11I'll show you how I use that to make my
63. 2:13specs actually useful. So the first
64. 2:15issue is a lack of process for
65. 2:17establishing alignment. So most tools
66. 2:20just expect you to show up with a prompt
67. 2:23and generate a spec as if they
68. 2:25inherently know what you want and how
69. 2:27that's supposed to fit in the bigger
70. 2:29picture of your product. But we don't
71. 2:31just wake up knowing what to build. Even
72. 2:33when we know what the next feature on
73. 2:34our road map is, there's still a crucial
74. 2:37phase before creating the spec. And that
75. 2:40involves deciding on the right approach,
76. 2:42hashing out the trade-offs, the design
77. 2:44decisions, the edge cases, your product
78. 2:47strategy. Because we know there are
79. 2:48always multiple ways to build the same
80. 2:50feature. The question is which way is
81. 2:53best for your product and your
82. 2:55customers. So the newest version of
83. 2:56Agent OS doesn't rush into writing your
84. 2:59specs. Instead, first it has your agent
85. 3:01work with you on ideiation and strategic
86. 3:04planning. This foundational context is
87. 3:08critical if you want agents to build an
88. 3:10alignment with your vision. Let me show
89. 3:12you what this looks like. So, I'm
90. 3:13working on a simple app called
91. 3:14flashcards so that I can quiz my kids on
92. 3:17their homework assignments. And in here
93. 3:19in the agent OS folder, I have my specs
94. 3:21folder. Now, I've already built out the
95. 3:23first uh feature and that's the finished
96. 3:26spec right there. So, let's go ahead and
97. 3:28start the next spec. I've got Cloud Code
98. 3:30open here and I'm going to start with
99. 3:33new spec. Just going to run the new spec
100. 3:35command. Now, if you're familiar with
101. 3:37agent OS, you know that I already have
102. 3:39my uh product plan with the road map and
103. 3:42mission built in. So, uh agent OS did
104. 3:45reference that and it's asking me if I
105. 3:47want to uh just build the next item in
106. 3:49my road map and I can check my road map
107. 3:52here.
108. 3:54So, we've already built out uh these two
109. 3:56parts and now we need to build out the
110. 3:57question builder interface for multiple
111. 3:59choice questions. Let's go with that. So
112. 4:02now it's using sub aents for every step
113. 4:05in the process if you're using cloud
114. 4:07code which supports sub aents and you
115. 4:10can see that we've now built out the
116. 4:11folder for the next spec. That's the
117. 4:13question builder interface and we're
118. 4:15initializing here. Okay. So now it has
119. 4:18passed the baton onto the spec
120. 4:20researcher sub aent and that one is here
121. 4:22to help me research and plan and hash
122. 4:24out the details for this new feature
123. 4:26before we even get into writing the
124. 4:28spec. So, as you can see, it came up
125. 4:30with a list of clarifying questions. Uh,
126. 4:33looks like we have nine of them. I just
127. 4:35want to point out that built into agent
128. 4:38OS, I've instructed the agent to analyze
129. 4:42my mission, my product road map, my
130. 4:44standards, and the initial idea for what
131. 4:47this feature is going to be, and then to
132. 4:49come up with clarifying questions.
133. 4:52Specifically, I told it to number them,
134. 4:54which is going to make it easy for me to
135. 4:56just answer, you know, number one
136. 4:57answer, number two, answer, number
137. 4:59three. The other thing that I said was I
138. 5:01wanted to ask the questions and then
139. 5:03provide a sensible assumption as the
140. 5:06probable answer to the questions. And
141. 5:09that makes it really easy for me to just
142. 5:11do things like number one, yes, number
143. 5:13two, yes, number three, let me course
144. 5:15correct a little bit, number four, yes.
145. 5:17So, you know, just making the process of
146. 5:19planning and ideulating and hashing out
147. 5:22a little bit easier than for me to have
148. 5:24to come up with these questions on my
149. 5:26own. And one more tip, I also emphasized
150. 5:29the importance of referencing
151. 5:31pre-existing design elements and
152. 5:33architectural elements in the codebase
153. 5:35itself um when it's coming up with these
154. 5:37questions. And uh as you can see down
155. 5:39here we have a section where it asks me
156. 5:41literally are we going to be reusing any
157. 5:43existing code or you know components in
158. 5:47the uh codebase. So this is all really
159. 5:49important planning material that should
160. 5:51go into the process. So let me go
161. 5:53through and answer these questions.
162. 5:55Okay. So I've added my answers to
163. 5:57questions 1 through nine. As you can see
164. 5:59it's really easy for me to just confirm
165. 6:01the uh assumption that the agent made
166. 6:03and make some very minor uh course
167. 6:05corrections. I forgot to add the note
168. 6:08about uh existing reuse. Um
169. 6:11so I'm saying like reuse our existing
170. 6:13styling around the the existing
171. 6:15questions UI that we have. And then
172. 6:16there's one final thing that agent OS
173. 6:18asks for. Now we have a visuals folder.
174. 6:20And this is optional, but if you have
175. 6:22any sort of mockups or wireframes, now
176. 6:25is a great time to put them into the
177. 6:27planning. Agents work so much better
178. 6:29when they get to follow an actual visual
179. 6:31reference. And uh I do have a very
180. 6:34simple um rough wireframe. I'm going to
181. 6:37just drop that into the visuals folder.
182. 6:39So we have that in the planning for this
183. 6:41spec. And we also have it built in to
184. 6:43recognize whether this is a detailed
185. 6:45mockup versus just a rough wireframe. In
186. 6:48this case, it's going to know that it's
187. 6:49a wireframe. Okay. So I think we're good
188. 6:51on my initial questions and I'm going to
189. 6:54send those along. All right. So we're
190. 6:56not done yet. Uh, the agent just
191. 6:58analyzed both my answers to the first
192. 7:00set of questions and it took a look at
193. 7:02the wireframe that I provided it and it
194. 7:05came up with a couple additional
195. 7:06clarifying questions just to really make
196. 7:08sure that we're on the same page. It
197. 7:10noticed something that I put into my
198. 7:12visual wireframe and it wants to confirm
199. 7:14the direction here. It even pointed out
200. 7:16that I forgot to mock up a detail to,
201. 7:19you know, select which is the default
202. 7:20answer.
203. 7:22And again, it worded them in ways that
204. 7:24make it really easy for me to quickly
205. 7:26respond. It says like, would you like to
206. 7:28do it this way or that way? And I can
207. 7:29just say option A, you know. Okay, so
208. 7:32the spec researchers work is done. And
209. 7:34let's see what we have so far. So again,
210. 7:36we're we're inside the spec folder. We
211. 7:38have not created the actual spec yet,
212. 7:40but so far we have this planning folder.
213. 7:43Inside that we've got our visual, that's
214. 7:45our wireframe, and we have this
215. 7:47initialization. This is just very
216. 7:49simple. was, you know, just to record my
217. 7:51very first direction. And then we have
218. 7:54this requirements document. It it just
219. 7:56serves as a reference and a record of
220. 7:59the discussion that we had each question
221. 8:01that the agent asked me uh what my
222. 8:03answers were and um it has the follow-up
223. 8:06questions. it, you know, references some
224. 8:09existing code and it has some notes on
225. 8:12the visual assets and it analyzed them
226. 8:14and and gave itself some notes on what
227. 8:16it found some visual insights,
228. 8:18functional requirements. So again, I can
229. 8:20like even go through here and just
230. 8:23double check that all these details are
231. 8:25in fact correct. You know, I might check
232. 8:27things like, did I actually answer the
233. 8:29right thing? Or do I want to rethink
234. 8:31certain details about how this feature
235. 8:33should be designed? Or I might want to
236. 8:35check to see the agent actually
237. 8:36interpreted what I had to say correctly
238. 8:38because a lot of this stuff is, you
239. 8:40know, notes in the agent's words, not
240. 8:43mine. I'll go through and double check
241. 8:45these, but again, like this is sort of
242. 8:46like the raw material, the strategic and
243. 8:49design decisionm that together we've
244. 8:52come up with. And now it's sort of in
245. 8:55the context, but we also have it
246. 8:56documented here in the folder. So now I
247. 8:59can proceed with the actual creation of
248. 9:01the spec with much higher confidence
249. 9:04that the content of the spec is going to
250. 9:06be exactly what I want. Look, this is
251. 9:09where our craft happens. Now, of course,
252. 9:11we know how our code is going to fit
253. 9:12together, but our agents can build most
254. 9:14of that. Where we bring value is through
255. 9:17design and our taste and experience and
256. 9:21understanding what our customers need.
257. 9:23That happens here in the planning phase.
258. 9:26All right. Now, while the spec writer
259. 9:28sub agent is writing up our spec, I want
260. 9:30to talk about the second big issue that
261. 9:32I'm seeing and that's missing context
262. 9:34about your standards. So, in order to
263. 9:37write specs that ensure agents will
264. 9:39build correctly the first time, we need
265. 9:42granularity about how the code should be
266. 9:44written. So just telling our agent to
267. 9:46build a React app or build a Rails app,
268. 9:48that's not enough. There are countless
269. 9:50variables, your text stack, your code
270. 9:52style, your existing libraries,
271. 9:54established patterns, components,
272. 9:56layouts that you've already developed.
273. 9:58We need our specs to instruct our agents
274. 10:00to adhere to all of these directions.
275. 10:02And we can't just assume that their
276. 10:04quick codebase scan is going to pick up
277. 10:06everything. We also can't just retrain
278. 10:08our agents on every new feature that
279. 10:10they develop because then we're just
280. 10:12back to prompting in circles. So, as
281. 10:14I've shown in my previous videos
282. 10:15covering agent OS, it lets you define
283. 10:18your coding standards and your design
284. 10:20choices and your common patterns once.
285. 10:23So, when your specs get written and your
286. 10:25code gets implemented, your agents
287. 10:27already have that knowledge baked in.
288. 10:29So, it looks like our spec is almost
289. 10:31ready. The spec writer finished its work
290. 10:32and now it passed the baton onto our
291. 10:35spec verifier which is checking the spec
292. 10:37writer's work, making sure that it's all
293. 10:39accurate, that we uh crossed our tees
294. 10:41and dotted our eyes, if you will, and
295. 10:44that's all set. So, here is everything
296. 10:46that it did. So, let's go ahead and take
297. 10:48a look. So, now we have our official
298. 10:50spec.md. Now, I used to have a much more
299. 10:52complex version of this, but I purposely
300. 10:55had the agent simplify it down to just a
301. 10:57one-pager. We've got the goal. We've got
302. 10:59a couple of user stories, some
303. 11:01functional requirements, some
304. 11:03nonfunctional requirements. Uh then we
305. 11:05have some notes on the visual design
306. 11:07referencing the uh the visual that I had
307. 11:10provided. We're also calling out to some
308. 11:12reusable components that already exist
309. 11:14in the codebase so that you know the
310. 11:15agent can leverage those and not rebuild
311. 11:18the same thing twice. We've got some
312. 11:19notes on the technical approach. This is
313. 11:22intentionally not going into great
314. 11:24detail because, you know, we still want
315. 11:25to let the actual coding agent and the
316. 11:28specialist sub agents that are going to
317. 11:30be uh responsible for these items sort
318. 11:32of do their thing rather than leading
319. 11:34them down potentially the wrong path up
320. 11:36front. So, you know, this is just the
321. 11:38highle specification, but it is highly
322. 11:40accurate. As you can see, there are now
323. 11:42multiple layers at play here. We did the
324. 11:44initial Q&A and clarifying and and
325. 11:47hashing out of the details. Then it went
326. 11:50through and and created the uh the
327. 11:52specification which also took into
328. 11:54account my standards that are built into
329. 11:55agent OS and we had the verifier agent
330. 11:58come in and and look at it all and now
331. 12:00I'm putting my human eyes on it as well.
332. 12:02So we've got our spec and then we have
333. 12:04our tasks. So this is the actual task
334. 12:06list that would be implemented once we
335. 12:08get to the implementation phase. It is
336. 12:10broken out into task groups each with a
337. 12:14main parent task and some subtasks. The
338. 12:17other thing that you'll notice is that
339. 12:19agent OS is suggesting which sub aent
340. 12:22like in this case doing the database
341. 12:24updates that's going to go to the
342. 12:25database engineer sub aent and getting
343. 12:28down into the API layer that'll go to
344. 12:30the API engineer. Um so we're grouping
345. 12:33these into groups of tasks that
346. 12:36individual sub aents can tackle sort of
347. 12:39like separately and that'll be really
348. 12:41useful when it comes to implementation.
349. 12:43You know, here we're going to work on
350. 12:45the UI. So, we're going to delegate to
351. 12:46the UI designer sub agent. So, you know,
352. 12:49agent OS 2.0 when you're using it with
353. 12:51cloud code is going to be heavily built
354. 12:54around this idea of orchestrating
355. 12:56multiple sub aents to pick off each
356. 12:58individual uh task group when it comes
357. 13:00to implementation. Now, of course, I I
358. 13:03can still review these tasks. I can even
359. 13:05review which agent it's planning on
360. 13:07delegating to. Um, and these are things
361. 13:09that I can tweak and change on the fly.
362. 13:11like this particular feature might be
363. 13:14built a little bit differently than the
364. 13:15last feature that I built or I might be
365. 13:17doing things a little bit different in
366. 13:19this project versus a different project.
367. 13:21And so agent OS gives me that
368. 13:22flexibility to spin up different types
369. 13:25of sub aents and incorporate them into
370. 13:27my process in different ways depending
371. 13:29on the project. And in fact, that brings
372. 13:31me to the third and I think the most
373. 13:33important factor when it comes to real
374. 13:35world adoption of these AI tools and
375. 13:38spec driven development and that is the
376. 13:40tooling can't be too rigid about
377. 13:42defining our development process.
378. 13:45Because look, we all build differently.
379. 13:47Your team might take an API first
380. 13:49approach. Mine might emphasize UI first.
381. 13:52You might have 30 engineers in a
382. 13:54department or she might be working at a
383. 13:57startup with three co-founders. His team
384. 13:59over there might have multiple testing
385. 14:01phases. Hers prioritizes getting a
386. 14:03product out to customers quickly. And
387. 14:05each feature in your product might be
388. 14:07built a little bit differently. One
389. 14:08might involve a lot of API and database
390. 14:10changes and the next feature might focus
391. 14:12more on UI and the one after that might
392. 14:15just concern the mobile app. Each spec
393. 14:17involves different sub aents and a
394. 14:19different mix of phases in your
395. 14:22development process. You know, if your
396. 14:24tooling adds friction as you or your
397. 14:26team is moving between different
398. 14:28features, different products, that can
399. 14:30prevent full adoption of specd- driven
400. 14:32development, and then you'll miss out on
401. 14:34the benefits and the leverage that AI
402. 14:37first development has to offer. So, in
403. 14:39designing the newest version of Agent
404. 14:41OS, one of my goals is to make it as
405. 14:43adaptable as your development process
406. 14:45requires. It leverages sub agents and
407. 14:48orchestration that you can control as
408. 14:51you move between specs. So, I'll be
409. 14:53sharing my latest patterns in spectriven
410. 14:55development and in agent OS in my next
411. 14:57live workshop and in my builder briefing
412. 15:00newsletter. So, you can get on that by
413. 15:01going to buildermethods.com.
414. 15:03And speaking of patterns, now that we're
415. 15:05rethinking what it means to build and
416. 15:07ship products, it's easy to lose that
417. 15:10sense of flow that we used to have when
418. 15:12we were deep in our code bases before
419. 15:14all these AI agents came along. But I
420. 15:16think it's still possible to achieve
421. 15:17that flow state, which can lead to
422. 15:19breakthroughs in your product. You can
423. 15:22see my recent video on finding flow with
424. 15:24spec driven development. And so after
425. 15:25you hit that subscribe button, head over
426. 15:27there, check that one out next, and
427. 15:29let's keep building.