Specifications
Vibe coding at its simplest consists of telling the tool what you want in a chat session, and then chatting away endlessly to nudge it in the right direction or fix things that aren’t working, or add new things you want. But when you have made several rounds of corrections to what was built, you don’t actually have a definition of what you were trying to build: you have a conversation. You might think the code itself is a specification, but if you do, any bugs in your code are not bugs, they're the way it's supposed to work.
Worse, your AI coding tool has no hesitation to spindle, fold, and mutilate when it wants to. Only a separate specification will hold it back: a specification is your way to tap the sign when your AI coder forgets some feature or doesn't remember why it was done that way. And, trust me, you need to tap the sign a lot.
The key insight here is that vibe coding tools can create and maintain specifications just as well as they can code. So how do we put them to service here?
I try to start a new project with a reasonably well written document in Markdown format. Markdown is the perfect balance of simplicity and expressiveness that allows you to convey your thoughts. I use a Markdown native editor called Typora to do this. I will use this to generate the first version of whatever module or function I'm building. I'll also save the specification in the project itself (usually in a specifications folder) so it’s always there for AI to read when it wants and is tracked and maintained over commits to the repository. This way, I can tell the AI coding tool to read the specification and, before doing anything, ask me any questions it has. And it always has them. I answer the questions the best I can (sometimes after several rounds of back and forth).
As the application evolves, I ask the tool to revise and update the specification from time to time to keep it current. Then, should the LLM start to develop amnesia about what we're building, I can refer it to the specification.
After a while, the situation can grow beyond one specification file; you don't want a novel length spec, it doesn't help if the LLM has forgotten what was at the beginning by the time it gets to the end.
Fortunately, the LLM can help you break up and maintain sub-specifications. I often get these "for free" when I write up a specification for a new feature or big revision. The key is ensuring that the LLM knows where the specifications are for it to look up details it needs.
As time goes by, I'll start to organize your specifications into directories and subdirectories, if the project gets large enough,.
Remember: Start with a spec and keep it reasonably up to date as the application evolves.
To get updates on this Cookbook and other thoughts on AI, subscribe to my substack (it's free):
