Spec-Driven Development in a Startup

Author(s): Andrzej Ryl

Originally published on Towards AI.

This is a typical “tech-guy” in a startup. This is also a typical “media-person” in a startup but you get the point. There is no such thing as one responsibility and if there is anything even remotely tech-related, it will land on your lap no matter what. That’s how I ended up learning Python, Django, AWS, Swift, iOS, React, ML and probably a bunch of other stuff even though I started as an Android developer 😅 I learned it because we needed it.

In Uncover we have 2 native mobile applications supported by Django backend hosted on AWS, and whenever a new feature appears on the roadmap I am faced with building for 3 platforms. Someone would say “Dude… have you heard about multiplatform?”.

I did. But back when we started, multiplatform was still clunky and we have some serious UI work in our apps so having 2 native solutions is actually something that has helped a lot. I’m sure there are many startups like that… RIGHT?

The Problem

So let’s assume you’re in the same situation. You have to deliver a new feature for both mobile platforms and it needs backend changes. Normally it would mean flexing your generalist muscle and writing code in 3 different languages OR flexing your wallet and hiring 3 different contractors 💰💰💰

But there is a better way.

The solution

You have the knowledge, right? You have the understanding how to actually pull this off. You might not have the full understanding how to do it in ALL the technologies but you should have a pretty good idea how to do it in at least one of them. That’s when the AI specs come in handy.

What is an AI spec? TL:DR; version

Some will actually tell you that this is a new code and I have to admit I’m starting to lean into that idea. This is basically a very detailed tech description of what you want to achieve. It has phases, technical details, trade-offs, acceptance criteria etc. It’s like a documentation but written beforehand.

What do I do with it and why should I care?

I’m glad you asked 🤣 you take the specification (usually written with the help of AI btw) and you feed it to AI agent. Agent takes the spec and (this is the most important part) delivers it TO-THE-LETTER. It doesn’t ideate. It doesn’t go on a weird journey like this guy. It doesn’t decide that your project is bad and it’s better to rewrite it. It just does the job. It behaves as a regular dev that shows promise and wants to impress you. But it doesn’t have to be senior or staff. You already did that part — you created a spec based on your experience and your understanding of the project. The only thing left is to do the mundane — code it.

And the best part? You can use this spec to build the same stuff on your other platform 😍

The proof

Let me show you a real-life example from Uncover. Like I said — we have both Android and iOS versions of the app. September was approaching so knowing our users, we knew that something related to Fall is absolutely necessary. That’s how “Fall Vibes challenge” came to life.

The idea is simple — we select books matching fall vibes and our users are to read 9 books to complete the challenge. Easy enough. But in order for this to be entertaining we had to introduce mechanics like time-constrained seasons, custom challenge graphics that are easy to share, a way to find those books in the app (sth like scavenger hunt) and a bunch of fun rewards along the way. This is where it got tricky. Those are some of the designs we came up with.

Looks cozy, right?

But the very cherry on top was when I received a special request: “When a user opens a book that is taking part in the challenge, the leafs have to be falling….”. This is how the end result looks like 😍

All of this is truly magical (especially now that I use it in the app) but before starting I knew it will be a lot of work.

The prompt ✨

So how did I go about those specs? I fired up Claude Code (I show how to protect yourself from agent accessing files you don’t want it to see at the end) in the backend repository and started with this prompt. I use sth similar to every spec I build:

Please look at @CLAUDE.md to understand what type of project we're working on 
and look on all docs in @ai-specs.
Those are specs for previous features we were working on in this project 
and guidelines on how to build such specs.
Today we're going to build a new spec. We are ONLY building the spec. 
NO CODING PLEASE. NO RUNNING COMMANDS. Just simple spec creation. 
Below you will find description of the feature we will be building spec for.
Please remember to include sections for progress tracking and learnings.

Today we're building spec for VibeChallenge. It will be a very similar 
concept to HashtagChallenge but it has to be a separate mechanism as the logic
is a little bit different - instead of unlocking spots based on hasthags 
we will have a highlight with 9 spots and each spot will be unlocked 
by a book that has a selected vibe. We will need to add vibes field to 
the book most probably (right now we will only have FALL_VIBES but 
there will be more in the future). Can you investigate how hashtag 
challenges work in this app to propose a specification that will be similar 
to this mechanism? VibeChallenges will also generate a UserHighlight. 
Remember - NO CODING, we're building spec for now.

The first part of the prompt is my saved Claude command. I always use it for starting new spec. The second part is the actual description of the feature. The ai-specs folder is just a folder where I keep all my specs. I ask agent to look into it to learn how the previous specs looked like but trust me — the first prompt building the first spec was extremely similar. You will notice many reminders about NOT CODING because agents like to go ahead and you have to control them. You don’t want them to code just like you don’t want to start coding right away. You have to first plan what to code.
NOTE: the part about progress tracking is sth I picked up from one of the developers I work with. If you have a section for progress tracking and during the implementation agent runs out of tokens, you can easily go back to where you left of when the progress is updated after each step. Super simple but helps with having to explain what we did, what we planned to do etc. etc.

So I ran this prompt, allowed agent to look around the code and propose the spec. Once the first version is done, you simply go in there, investigate on your own (with your own expertise and knowledge about the project) and request changes. Until you’re happy with the spec. That’s it.

I have one additional step that I also added as a saved Claude command. When I’m done with reviewing and fixing the spec I run this command:

Please act as an experienced django developer and review spec 
#$ARGUMENTS. What clarifying questions do you need in order to start 
building this feature? DO NOT START any coding. Just ask clarifying questions. 
When you get all answers you need DO NOT START coding, just let me know 
that you are done and you can start building.

Agent will typically list out some questions (very good ones TBH) about edge cases etc. Once you answer them, it will update the spec and when you’re ready just type in

Ok. Let’s code it! Just remember about updating progress

And boom! You can grab a coffee and watch the magic happen 😍

The reusage

Once backend was done, I opened Claude Code in Android repo. I pasted the spec from the backend (entire spec. Just copied it over to ai-specs folder in Android app so that agent can read it) and started with this prompt

Please look at @CLAUDE.md to understand what type of project we're working 
on and look on all docs in @ai-specs.
Those are specs for previous features we were working on in this project 
and guidelines on how to build such specs.

Today we're building spec for VibeChallenge functionality. 
It is going to be very similar to HahstagChallenge but with elements 
from BookWrapUp. Please look through 
@ai-specs/backend-05-vibe-challenge-api.md <-- this is a spec from Django 
backend to build support for this feature. 
You will understand how the backend work. Today we're building spec 
(remember, no coding) to support displaying of new type of user highglight 
story, new highlight and new challenge settings and details. 
VibeChallenge is very similar to hashtag challenge but there are no 
topics - we will display a grid of 9 pumpkins and user will read books 
to unlock those pumpkins (just like topics in hashtag challenge but 
there are no topics so you don't have to implement reveal logic or display 
different topics , just a pumpkin icon or a book cover). 
Template has 9 spots (either pumpkin or cover) but it user has more 
than 9 books you have to create additional page just like on 
BookWrapUp (there you have up to 16 books and if user has more you 
chunk them in lists of 16 books and provide more pages). 
I will provide all kinds of images etc but you have to let me know 
which ones you need. 
As for the template, we will have a title (just like on monthly wrap up 
but without the title background), background (loaded from url), 
grid of 9 spots (pumpkin icon by default and book cover when spot is filled) 
and a counter text in the bottom right corner saying 
"PUMPKIN HARVESTED x/9" where x is the current progress. 
When current progress reaches or surpasses 9 it should just show 
"PUMPKIN HARVESTED x". 
We should also implement reward system for VibeChallenge - 
just like the reward system for hashtag challenge. 
One difference here - there will be 9 rewards (1 reward for each book) 
but the ssytem should change because of that. 
Remember, NO CODING for now

As you can see, there are A LOT of steps here. But that’s the beauty of spec writing. Normally agent would just go off and with this kind of intructions it would destroy your project by rewriting everything. But with specs? We just spent an hour or so building a very detailed step-by-step plan on how to implement all of this. Agent even estimated this as 3 weeks of work for a strong team 😅

And then it delivered it in about 45mins…
Did it make mistakes? Hell yeah. Would I make mistakes? For sure.

But I was just reviewing code and testing after each stage and 2 days later I had backend and Android app working….

Then I did exactly the same with iOS but equipped with 2 previous specs. And you know what amazed me? After we’ve built the iOS spec and agent finished actual coding, app just built on the first go 🤯 I still had to make changes after testing and realizing that UI was a total mess and there were edge cases that just worked differently on iOS but overall I was very pleasantly surprised. With that much context and all the learnings from Android side, iOS agent had a way simpler task. It understood the context of iOS app (because it read CLAUDE.md for this project and was aware that it’s working with Swift and not Kotlin) but thanks to all the learnings from the backend and Android it exactly knew what to do.

I was done with entire project after a weekend and 3 evenings. Before agents and specs it would probably take me around 2 weeks. That should start your thinking.

Summary

When agents first came out I was under the impression that they are just too risky. They have too much power and without constant supervision they can just mess your project up. Or do actual harm. But we can still use them VERY efficiently by putting guardrails and simply not trusting it fully. Just like you don’t trust new devs in your team. You always check what they’ve done because they don’t have the project experience you do. And if you tell them to do the entire process iteratively, you can control the output on every step and react.

Someone said that spec is simply a new code. At the beginning we were typing processor instructions in Assembly. Then C came and we started using more structured code but still controlled pointers etc. Then objective programming came and we all forgot what pointers were. Then all the frameworks came and people forgot how to write sorting because now you always had this magical sorted() function at your disposal.
And now here we are. We can write plain English instructions and the sorting happens. It takes getting used to but I must say that I enjoy this coffee moment when I see my screen going off and I can relax and see the magic happen. JARVIS is around the corner.

Apendix: how to make sure AI Agent doesn’t access sensitive data?

This is something that scared me from the very first AI Agents announcement and I actually experienced this first hand. When I was playing with Augment I specifically mentioned my sensitive files as a NO-GO and added it to AI version of gitignore. I was extremely surprised when during one of debugging sessions agent just happily quoted sth from this file. When I confronted it about it, it of course just apologized and promised not to do it again. But the damage was done, right? Data was already flying through Augment servers.

So I decided not to use agents until I figure out how to make it stop. And I did so if you are Mac or Linux user, here is the instruction.

Mac users

For Mac users there is sth called sandbox. It is deprecated but I haven’t yet found a replacement so for now it has to do. It’s a built-in feature so it works straight out of the box ❤️

You create a sandbox-config.sb file in your repo that looks like that

(version 1)
; Start permissive, then carve out hard denies.
; In SBPL the *last applicable rule wins*, so these denies override the default allow.
; (This is a common pattern documented by practitioners.)
(allow default) ; everything allowed unless explicitly denied

; ---- Block your sensitive project paths ----
(deny file-read* file-write* file-map-executable
 (subpath ".../.ebextensions") ; folder restriction (absolute path)
 ...
 (literal ".../django/.ebignore") ; file restriction (absolute path)
 ...
)

and than simply run claude code with that profile

> sandbox-exec -f sandbox_config.sb claude

That’s it. Claude will simply be restricted by the system to access (or even see when it comes to files) the files/directories you specify. I tried multiple different ways to convince it to access the files and every time we were simply rejected by the system.

Linux users

Very similar tool, but on Linux it’s called firejail . It needs installation but once you do, you simply add configuration file (a little bit different but the idea is the same) and start claude in its context. Work the same way. Whenever claude tries to access the files it simply gets rejected by the system.

Remember to use those tools and you should be good 💪

Join thousands of data leaders on the AI newsletter. Join over 80,000 subscribers and keep up to date with the latest developments in AI. From research to projects and ideas. If you are building an AI startup, an AI-related product, or a service, we invite you to consider becoming a sponsor.

Published via Towards AI