Imagine you're a maestro standing before a grand orchestra, baton in hand, ready to weave a symphony from chaos. Now picture a lively jazz jam session where musicians riff off each other's vibes, creating magic on the fly—but sometimes, they hit a sour note. That's the whimsical world of AI-assisted coding.
AI coding assistants are like those talented musicians, helping us build solutions quickly. But relying solely on impromptu interactions ("vibe coding") can lead to brilliant bursts of creativity mixed with brittle code that might crumble under pressure.
Enter spec coding, where you, the human conductor, lay out a clear score (specifications) to guide the AI ensemble toward harmonious, reliable results. This smart, structured collaboration keeps humans firmly in control. If you're wondering how to maximize the efficiency of your AI tools without sacrificing quality, keep reading. This approach isn't about ditching the fun; it's about making the music last.
The vibes and specs of AI coding
Let's start with vibe coding, the free-spirited pioneer of AI-assisted development. Picture this: You're knee-deep in a project, chatting back and forth with your AI buddy, one prompt at a time. "Hey, add this feature," you say, and poof, code appears. It's iterative, interactive, and a blast for quick prototypes or brainstorming. Many of us discovered the power of AI coding this way, and it's still the go-to approach for countless developers.
But while vibe coding shines in its flexibility, those ad-hoc exchanges can result in code that's speedy but not always sturdy. Think of it as a jazz improv that thrills in the moment but might not hold up for a full concert tour.
On the flip side, spec coding (short for specification coding) puts specifications first. It's like drafting a detailed blueprint before building your dream house, ensuring every nail and beam aligns perfectly. Here, humans define the "what" (the functional goals of the code) and the "how" (rules like standards, architecture, and best practices), while the AI handles the heavy lifting (code generation).
You can mix and match specs for different projects, languages, or even teams, turning one-off efforts into reusable symphonies. This approach improves developer productivity without skimping on quality. Stakeholders get involved early through clear functional specs, which cuts down the time-to-value and makes your AI investments sing with better ROI.
The goal: Precision meets playfulness
At its core, spec coding aims for orchestral precision: Think 95% or higher accuracy in implementing specs on the first go, with code that's error-free and unit tested. Humans craft the "what," focusing on user stories or natural-language descriptions of desired outcomes, while setting "how" guardrails for everything from security to deployment. This empowers AI with context so it generates code that adheres to corporate standards, like using specific APIs or testing frameworks.
Multiple "how" specs can play together harmoniously—say, one for architecture, another for documentation, and others for testing or security. Keep the specs scoped tightly to avoid overlap, and voilà: Your AI can generate code in a mix of programming languages, all while learning from past hiccups via a "lessons learned" file. This feedback loop is valuable and reduces AI coding agent errors over time. In a business context, it democratizes AI coding, pulling in diverse stakeholders and accelerating AI-infused applications. More brains (human and silicon) equal faster innovation and smarter resource use.
How to get started with spec coding
Ready to conduct? There's no one-size-fits-all workflow yet, though tools like Kiro and GitHub's spec-kit are tuning up. In the meantime, here's a simple yet practical guide to kick things off with any AI coding assistant.
Crafting your specifications
First, compose your functional spec. This is the "what" melody, pure and without requiring knowledge of a programming language. Use user stories like "As a user, I want to have the CRM system automatically make updates when I state activities such as: “I just had a meeting with Rich Naszcyniec at MegaCorp and we discussed the Red Hat AI Platform." Keep it in natural language for easy reading. After all, specs should invite collaboration.
Pro tip: Enlist AI for "vibe spec-ing," that playful back-and-forth to draft or even reverse-engineer specs from existing code. A general-purpose language model works well here. It's like jamming with a friend to outline your hit song before recording.
Add language-agnostic specifications
Next, layer in the programming language-agnostic "how": Define data structures, component contracts, architecture (for example, "Use REST for all exposed APIs"), security, and so on. This helps keep things flexible, letting you swap and mix programming languages without rewriting the core tune.Fine-tune with language-specific details
Then, fine-tune with language-specific specs. For each language, detail versions, features, and preferences (for example, "Stick to Swift 6.2 toolchain, fallback to 6.1"). Don't forget testing: Specify frameworks, scopes, and how tests self-correct code. AI often resolves bugs on round two thanks to this.
Specify documentation and granular rules
Documentation gets its own spec, too: Outline READMEs, architecture overviews, or language quirks (for example, "Use Apple's DocC for Swift"). Architecture specs can get granular, like mandating packages such as your favorite open source project for OpenAI calls while letting AI choose other implementations for all other REST calls.
Run the code generation prompt
With specs in hand, it's showtime for code generation. Set up a project folder, tuck your specifications into a specs subfolder, and prompt your AI:
Using the Specs folder, generate Swift code that implements the code required to meet all specification requirements. Code generation isn’t complete until the code compiles error-free and passes all unit tests. As coding errors are corrected, log those errors and fixes in a file named LessonsLearned.md in the specs folder. Whenever you encounter an error that needs to be fixed, check the lessons learned file to see if you already know how to fix it.
Then sit back and watch as AI iterates, fixing errors and building a knowledge base. This structured flow cuts development time, boosting utility from your infrastructure and improving ROI.
Review, refine, and remix
No performance is perfect without rehearsal. AI handles initial reviews to ensure compilation and unit tests pass, but humans take the spotlight for validation: Test functionality, assess quality, and ensure maintainability. It's your chance to applaud or tweak.
Need application code corrections? Options abound in this ongoing debate. Purists regenerate all code from updated specs, keeping them as the ultimate truth (great for consistency, but resource-hungry). Others treat AI-generated code as a draft, hand-editing for familiarity (upside: deeper understanding; downside: specs drift if not synced). Or vibe it out with interactive sessions where AI proposes changes, you approve, and lessons get logged, blending human insight with AI speed.
Post-project, tune up those specs. Review your AI lessons learned to tune up your specifications (AI can help here, too), and roll reusable "how" specifications to your next gig. Over time, your spec library becomes a greatest-hits album, refining with each project. This iterative polish means progressively faster cycles, more AI-powered solutions, and stakeholders beaming at the efficiency.
Wrapping the encore: Why spec coding hits the high notes
Spec coding transforms AI from a solo act into a full orchestra under your baton, delivering robust, scalable code with human ingenuity at the helm. By adding specifications to your workflow, you don't just coding faster; you build smarter. This leads to results like better team productivity, wider collaboration, and a higher return on investment from your AI tools.
Ready to grab the baton? Experiment with spec coding on a simple application and witness the difference. Or, for a fun challenge, time a vibe-coded version versus a spec-coded one. You'll likely see the efficiency increase.
- I’ve published two open source spec projects on GitHub that help simplify infusing AI into applications using OpenAI-compatible endpoints like those available using vLLM in Red Hat AI.
- SwiftChatCompletionsDSL for using OpenAI-compatible chat completions endpoints.
- SwiftResponsesDSL for using OpenAI-compatible responses endpoints.
- Learn how Red Hat is leveraging coding agents in our AI projects in Chris Wright's post AI-assisted development: Supercharging the open source way.
- Finally, if you're going to accelerate application development with AI, and produce more AI infused applications, you need a plan. Take a look at the article Building an adaptable enterprise: A guide to AI readiness by Mike Ferris for four strategies to build an adaptable enterprise.
