Spec-Driven Development Is Becoming a Core Software Engineering Skill

I still remember the day a code generator built a feature that “worked” on the surface, until a casual security review found a critical SQL injection bug. We had given the AI agent a quick, vague prompt, and it turned out that approach was a blind alley. After 10+ years shipping production software, this quiet failure spurred a realization: “vibe coding” isn’t enough. Teams need structure, not just improvisation, when working with AI. Software engineers are now returning to classic discipline: writing clear requirements and design documents before telling an AI to write code.

This shift is not just philosophy. Veracode’s GenAI Code Security Report (July 2025) put numbers on it: 45% of AI-generated code samples introduced OWASP Top 10 vulnerabilities, with Java code failing security checks 72% of the time. Even the latest large models flunked XSS (86% failed) and log-injection tests (approximately 88% failed). These grim statistics are real reasons why teams stopped prompting AI agents blindly and started writing specs first. In this article I’ll explain what spec-driven development means in practice, why tools like GitHub Spec Kit, Amazon’s new Kiro IDE, and the AGENTS.md standard emerged to support it, and how we can catch issues before code is written. Along the way I’ll share how these practices tie into modern skills and training, including the Refonte Learning Software Engineering Program that teaches the fundamentals (like planning and secure design) that underpin a spec-first workflow.

Why "Vibe Coding" Stopped Being Enough

We used to call it “vibe coding”: iterating by feeling, throwing quick prompts at an AI and hoping for the best. In February 2025, Andrej Karpathy coined the term for exactly this style of ad-hoc AI work. Vibe coding is great for exploration, but it often leads to unpredictable results: agents may choose the wrong libraries, miss hidden requirements, or introduce subtle bugs. GitHub’s announcement of its Spec Kit noted that teams needed to move “beyond quick ‘vibe-coding’ experiments” to something repeatable and verifiable. In other words, ad-hoc prompting was leading to code that compiles but misses the intent or security constraints. Developers began demanding a more reliable approach.

General industry trend pieces (for example, "Software Engineering in 2026: 5 Key Trends Shaping the Future") have emphasized AI coding and cloud, but none zoom into the process change the way a spec-driven workflow does. We’re talking about a narrower but deeper shift: treating specification writing as a first-class skill. Instead of “start coding and fix it later,” we now write out what to build in detail, then guide our AI agents to implement it. This structured approach reduces the guesswork that plagued pure vibe coding.

The Data Behind the Shift: Veracode's 2025 Findings

Security and correctness problems in AI-generated code are not hypothetical. Veracode’s July 2025 report tested 100+ language models on 80 coding tasks across Java, Python, C#, and JavaScript. The results were eye-opening:

•   45% of AI-generated code samples failed basic security tests, introducing OWASP Top 10 issues.

•   Language breakdown of failure rates: Java was by far the riskiest, failing 72% of tasks. Python, C#, and JavaScript all had failure rates around 38% to 45%.

•   Common flaws were not edge cases. For example, Cross-Site Scripting (CWE-80) crept into 86% of relevant AI-generated examples. (Likewise, Log Injection (CWE-117) also flunked in roughly 87% to 88% of cases.)

This alarming data explains the urgency. AI can write code that runs, but it often fails to embed the security and quality guardrails we need. Even more startling: newer, larger models were no more secure than older ones. Veracode found that as models got better at generating functional code, their security performance stayed flat. Today’s biggest LLMs (GPT-5, Gemini, Claude, etc.) still got only about 50% to 55% of tasks right in security terms. In practice, that means nearly half of AI-generated code can quietly slip dangerous bugs in.

The takeaway is clear: We can’t rely on a smarter AI model alone to produce safe code. We needed a process change, not just a bigger model. Spec-driven development is the industry’s answer to these findings. By forcing us to codify requirements, assumptions, and architecture up front, it helps ensure that what gets generated aligns with intent and security standards.

Why Bigger Models Didn't Fix the Problem

Some have wondered if a more powerful LLM might solve this, but Veracode’s data say no. Models spanning years of releases, from small to huge, all hovered around roughly the same 50% security pass rate. In other words, there’s no “giant model” that magically writes secure code by default. The security ceiling has held firm while models get better at syntax. It turns out robust software requires human insight and structured process, not just scale.

What Spec-Driven Development Actually Means

Spec-driven development (SDD) flips our traditional priorities. Instead of treating coding as the first step, it makes the specification itself the central artifact. GitHub’s Spec Kit project puts it bluntly: “specifications become executable, directly generating working implementations rather than just guiding them.” In practice, that means before any code is written (or generated by AI), the team writes down exactly what to build: user requirements, acceptance criteria, performance constraints, data models, etc. Only once that spec is clear do we ask our AI agent to start writing code.

For decades, specs were treated as optional overhead, just paperwork to get through. SDD makes them mandatory living documents. We refine them continuously, use them to generate test cases, and even give them to AI agents as “ground truth.” As one GitHub engineer put it, traditional prompting tends to “miss the intent” because it lacks a shared spec. Spec-driven dev changes that by making the spec itself the source of truth that all code and tests must satisfy. In effect, we’re shifting from code-first to spec-first workflows, which becomes a critical skill for engineers.

GitHub Spec Kit, Explained

GitHub’s open-source Spec Kit is the most visible embodiment of this workflow. It provides a ready-made, tool-agnostic process to use with any AI coding agent (Copilot, ChatGPT, Claude, etc.). At a high level, Spec Kit structures work into four main phases:

(This table is adapted from Spec Kit’s documentation.)

The idea is that you don’t advance to coding until each step is validated. After /speckit.specify, the AI generates a detailed spec (often evolving it with your feedback). After /speckit.plan, it creates diagrams or outlines of how components will fit together. And with /speckit.tasks, it produces a list of granular code tasks. You review the requirement spec, design document, and task list before running the AI to write code. In effect, Spec Kit turns the AI agent into a structured pair programmer, guided by slash commands that ensure you don’t skip the plan.

How the Requirements-Design-Tasks Workflow Works

Putting it another way, think of Spec Kit as enforcing a mini-waterfall within your agile process: you write requirements first, then do a design review, then split into development tasks. For example, imagine adding a “review system” to a web app. With Spec Kit you might first use /speckit.specify to outline user stories (e.g. “As a user I can submit a review so others can rate products”), complete with acceptance criteria (input validation, error messages, UI notes). Next, /speckit.plan might produce a tech plan: a database schema for reviews, an API endpoint contract, and a wireframe of the UI. Then /speckit.tasks could list individual tasks: write the review API handler, build the frontend form, write unit tests for input validation, etc. Each task is traceable back to the spec, so nothing is done arbitrarily. Finally, you hit /speckit.implement and let the agent generate code for each task, reviewing each bit as it comes.

By following these commands, Spec Kit turns what used to be a chaotic prompt-chat loop into a repeatable sequence: specify, plan, break into tasks, and implement. This aligns well with how engineers are trained to work: define requirements clearly, design the solution, break it into chunks, then build. The difference is that AI agents do the heavy lifting, but only after we’ve set up the guardrails.

Amazon Kiro's Approach to Spec-First Coding

AWS also recognizes the spec-first trend. In July 2025 at the AWS Summit NYC, Amazon unveiled Kiro, a new AI-powered IDE (a fork of VS Code) built around spec-driven development. Kiro is designed to take developers from prototype to production with minimal manual coding, but it enforces that you start with a requirements spec. Its workflow has three main steps, very much like Spec Kit’s:

•   Generate Requirements: You type a plain-language prompt (e.g. “Add a user login feature”), and Kiro creates a Markdown requirements.md with user stories and EARS (Easy Approach to Requirements Syntax) acceptance criteria for each. This ensures all edge cases and error conditions are spelled out before any code is written.

•   Create Design Document: Once the spec is approved, Kiro builds a design.md file. It analyzes your codebase and draws architecture diagrams, database models, TypeScript interfaces, and API outlines reflecting the requirements. For example, it might output a component hierarchy diagram or class interfaces needed for the feature. This step makes sure you see how the pieces will fit together before coding begins.

•   Break into Tasks: Finally, Kiro generates a tasks.md list, sequencing all implementation work needed to meet the requirements. Each task item includes details like "Write frontend form with validation and loading state" or "Generate unit tests for the login API." Crucially, every task is linked back to a specific requirement so nothing is overlooked.

After these steps, the AI agent will write the code, tests, and docs automatically. Kiro even offers “hooks” (background automations) to enforce consistency, for example, updating tests whenever you write new code, or scanning for secrets on commit. In short, Kiro’s slogan could be: “Yes, we can vibe-code to prototype, but to ship it safely, we use specs.” As the AWS team puts it, Kiro’s strength is getting prototypes into production by adding structure like specs and hooks.

This tool is built on AWS infrastructure (integrating with Bedrock and AWS IAM), and it reached public preview in mid-2025. Reports initially conflicted on when Kiro reached general availability. Kiro’s own November 2025 announcement stated that the IDE had officially launched with new enterprise features. The key point is that Amazon has put its weight behind a spec-driven workflow for AI-assisted coding, much like GitHub has. The announcement said Kiro had seen strong adoption of Specs since its July preview and positioned the tool as an early mover in spec-driven AI coding. In practice, using Kiro means your code sessions start with writing specs, a clear sign that spec-first has become mainstream, not a fringe idea.

AGENTS.md: A Shared Standard Across Tools

Alongside these IDEs, the AI developer community has standardized how to instruct agents in any codebase. Enter AGENTS.md, an open-source convention that is effectively a “README for AI agents”. The file, named AGENTS.md, lives at the root of a project and contains all the context an AI assistant needs: setup commands, coding style rules, testing instructions, security reminders, etc. Think of it as supplemental documentation specifically for AI tools, so they know the project norms without cluttering the human README.

AGENTS.md was launched in mid-2025 by a collaboration led by OpenAI (and supported by Google, Anthropic, and others), and it has taken off rapidly. As of late 2025, over 60,000 open-source projects and agentic tools have adopted AGENTS.md. Major AI coding assistants like Copilot, Google’s Gemini CLI, Cursor, Devin, Amp, Jules, VS Code itself, and many more all support the format. In December 2025, the standard was donated to the new Agentic AI Foundation under the Linux Foundation to ensure its governance is open and neutral.

What 60,000+ Projects Adopting It Signals

The explosive adoption of AGENTS.md sends a clear signal: the industry recognizes that AI agents need more context to code effectively and safely. When thousands of projects agree on a place to put conventions and setup commands, it means a few things:

•   Interoperability: A developer can onboard a new AI tool (Copilot, Devin, Zed, etc.) and know it will look in AGENTS.md for guidance. This avoids each tool reinventing its own context story.

•   Consistency: Team norms (variable naming, API endpoints, security filters, etc.) get codified once in AGENTS.md, so every AI-generated pull request checks the same rules.

•   Safety and Clarity: Explicit instructions (e.g. “don’t log user passwords”, “use this linter”, “run these tests”) reduce the chance that an AI will unknowingly violate a policy.

Put simply, broad AGENTS.md support reflects the same desire driving spec-first development: lock in human intent up front so AI agents don’t veer off track. With over 20 tools (including VS Code, Copilot, Cursor, Devin, Zed, Aider, Gemini CLI, and others) already “speaking AGENTS.md,” we’re building a shared foundation for safe AI coding.

Writing a Spec an AI Agent Can Actually Follow

Of course, producing a spec that an AI (or any developer) can act on is its own skill. Here are some practitioner tips for writing effective specs:

•   Be explicit and structured. Use clear user stories or requirement statements. For example: “As a logged-in user, I want to update my profile picture so that others see my latest photo.” Follow each with acceptance criteria (often in GIVEN-WHEN-THEN or bullet form). This removes ambiguity. For instance, list valid image formats or size limits under Acceptance Criteria so the AI handles those details.

•   Cover edge cases and constraints. Don’t assume the AI knows everything. Spell out non-functional requirements in the spec (e.g. security checks, performance needs, or compliance constraints). For example, if uploading files, explicitly note that you must check file type, file size, and sanitize filenames. That way the AI won’t skip basic validation.

•   Use domain-specific terms. Put project-specific context in the spec. If your team calls something a “CartService” or “UserProfile API,” use those names. If you follow certain architecture patterns or libraries, mention them. This helps the agent stay within your code ecosystem.

•   Link requirements to data flows. Diagrams or mock JSON/API examples in the spec can be invaluable. They create a shared mental model. For instance, sketch out a sample API request and response in your spec so the AI knows what payloads to send.   Iterate and clarify. Treat the spec like code: review it, test it. GitHub’s Spec Kit even provides commands like /speckit.clarify to let the AI ask questions about ambiguous areas, or /speckit.analyze to check for contradictions after you write it. Use such tools, or simply peer-review the spec with teammates. A good spec is often shorter in the long run, because it prevents writing lots of unneeded code and then discarding it.

In practice, writing specs for AI is not so different from writing requirements for a traditional project: clarity, completeness, and precision are paramount. The difference is you can hand this spec directly to your AI and say “make it real.” That accountability makes spec writing worth the upfront effort.

Where Specs Catch Problems Prompts Don't

A well-formed spec catches many issues that a blind prompt will miss. Here are a few examples of how having a spec first prevents common pitfalls:

• Misunderstood requirements: Without a spec, an AI might implement the first interpretation of a prompt, even if it’s incomplete. With a spec, every requirement (including corner cases) is spelled out. For instance, if you ask “Add login,” an AI might just do the happy path. But a spec-based approach would include scenarios like invalid credentials or expired sessions, because they’re in the requirements. This closes the intent vs. implementation gap noted by GitHub engineers.

•   Architecture drift: In ongoing projects, ad-hoc coding can gradually invent new patterns or ad-hoc fixes, leading to inconsistent code. A design spec locks in the intended architecture and style (e.g. “use our UserService for auth,” “database schema change X”), so the AI’s code fits the existing design. In other words, a spec prevents the agent from “reinventing” parts of the system in incompatible ways.

•   Missing security checks: Without guidance, an AI won’t know about your org’s security rules. A spec can include security requirements (e.g. “encrypt this field,” “sanitize inputs”) so the agent automatically implements them. For example, the OWASP report showed AI often missed XSS safeguards; a spec-first workflow forces you to explicitly say “escape HTML on output,” which the AI will then encode.

•   Test coverage and documentation: Vibe coding often neglects testing or docs. In a spec-driven flow, creating tests can be one of the generated tasks. Because Spec Kit and Kiro tie each generated task back to a requirement, your test suite naturally reflects what’s needed. The agent can even auto-generate unit and integration tests for each spec item (e.g. checking that X happens under condition Y).

In short, specs are proactive: they build quality gates into the process. They elevate questions like “Did we handle this case?” from a late code review concern to a planned requirement. Veracode’s findings make the distinction clear: getting AI code that works is easy; the real goal is AI code that works securely, and specs help bridge that gap.

How This Changes Code Review

Spec-driven development reshapes the role of code review and testing in a team. If the specification is the source of truth, then a pull request becomes a comparison between the code and the spec. Reviewers now check “Does this implementation fulfill the documented requirements?” instead of just eyeballing the code for logic errors. For example, if the spec said “the API must reject SQL injection attempts,” then the reviewer expects to see input sanitization or ORM usage in the code. If the spec said “show a loader during data upload,” then the frontend code should include that behavior.

This also helps QA and automated checks. Testing teams can use the spec to write test cases, and CI pipelines can validate that each acceptance criterion is met. (This complements other QA approaches. For instance, our Visual Regression Testing: What AI Test Agents Miss article discusses how AI-driven UI tests work; spec-driven development ensures backend logic has similar coverage early on.) In practice, code review becomes more straightforward: you have a checklist (the spec) to tick off. Instead of purely manual code inspection, you validate consistency against a design document. This makes code reviews faster and more reliable.

In teams with spec-driven workflows, you might even see a formal “spec review” step, where the spec document itself is reviewed and approved before coding begins. That way, everyone agrees on the plan first, and coding (including AI-generated code) mostly checks boxes rather than inventing new ones. In short, spec-first means fewer “surprises” in pull requests, because any major issues were ironed out in design already.

Common Objections to Spec-First Workflows

Whenever a new process comes along, practitioners raise objections. Here are some frequent ones and how to address them:

Each of these objections stems from habit or misunderstanding. In reality, spec-driven workflows borrow the best of disciplined engineering (clear requirements) and pair it with AI speed. Over time, most teams find that the slight upfront discipline is a worthy trade-off for predictability and fewer urgent fire-fighting fixes later.

"Isn't This Just Slower?"

This specific concern deserves its own answer. Writing a good spec does take effort, and it often means thinking harder upfront. But consider the alternative: dozens of AI cycles generating code that you then have to debug, refactor, or throw away when it doesn’t meet your needs. How much time did that waste? In many cases, teams find spec-driven sessions complete significantly more work per hour of human oversight. One study of AI-assisted PRs (not from Veracode, but industry feedback) showed that un-reviewed AI code often contains hidden bugs. Fixing those bugs after deployment costs far more than preventing them.

In short: yes, the first few features might take a bit longer to spec out, but subsequent work is faster and safer. And with practice, writing specs becomes second nature. After a few runs of this process, developers reported they could draft basic specs in the time it used to take to write just one AI prompt and initial few lines of code. The increased confidence (and code quality) more than offsets the initial discipline.

Integrating Spec-Driven Development Into an Existing Team

Switching workflows is a challenge, but it can be managed incrementally. Here are some practical steps:

•   Pilot a project or feature. Choose a small greenfield task and try the spec-first process. Use a template: write a draft spec, review it, then run the AI on it. Gather the team’s feedback on the process. Early wins (like catching a missing edge case) will sell the value.

•   Adopt the tools. Install Spec Kit’s CLI or try AWS Kiro in preview. These tools scaffold the workflow (they create the /speckit commands or the requirement files) so the team doesn’t have to build everything from scratch. Also, consider adding an AGENTS.md to your repos to standardize the agent’s context (which encourages writing down project-specific rules).

•   Adjust your process. Insert a “spec review” step in your cycle. For example, treat the spec as an artifact: have peers or product owners review the spec before coding starts. Then when turning tasks into pull requests (you can even automate task-to-issue conversion in Spec Kit), require that each PR references the spec item it implements. This keeps spec-first in the team’s workflow.

•   Train and mentor. Organize a workshop or pair programming session where a senior writes a spec with the AI for a trivial feature, explaining each part. Let others ask “Why include this detail?” and discuss. Real examples help. Emphasize that this is similar to writing user stories or design docs; the difference is that the AI will consume them.

•   Iterate on the workflow. No process is perfect on day one. Gather metrics like “time spent debugging AI code” before and after adopting specs. Use those numbers to refine the practice. If specs seem too long, trim irrelevant details; if too terse, add needed clarity. Over time, the team will find the right balance of thoroughness and speed.

By phasing in these changes, a team can evolve from unstructured prompting to a mature spec-driven cycle without losing agility. The goal is to add structure, not bureaucracy: specs are simply the voice of collective team decisions, written down.

What This Means for Junior vs. Senior Engineers

Spec-driven development has an interesting impact on engineers at different career stages. Junior developers often take to it quickly. Why? Many new grads have been trained with formal methods (writing specs, using UML, or writing tests first) as part of their education. They haven’t formed as many habits around unstructured coding, and they tend to be eager to follow rigorous practices. In fact, some junior developers may find spec-first workflows more familiar than senior devs, because they learned in environments (university, bootcamps) that emphasized planning and documentation.

On the other hand, senior engineers may initially resist. Having shipped countless features by intuition, a vet might feel constrained by spending hours on a spec. It requires patience to see the payoff. However, senior devs bring a big advantage: they know what details matter in practice. A senior engineer writing a spec can foresee pitfalls (like threading or caching issues) and include them up front. They become mentors in this process: leading spec reviews, and helping juniors understand why certain spec items are necessary. Over time, many seniors find that the time they save by not having to fix avoidable mistakes frees them to focus on architecture and mentorship.

Why Juniors May Adapt Faster

Several factors explain juniors’ quicker adaptation:

•   Fresh mindset: Newer developers grew up in the era of documentation and tools. They might already use README-driven workflows (a concept similar to AGENTS.md) and may have used TDD or BDD in school. Spec-writing is just an extension of those habits.

•   Less ego about “just code it”: Unlike some veterans who pride themselves on being able to hammer out code quickly, juniors are often more open to following prescribed processes. They may actually feel relieved to have clear instructions.

•   Comfort with AI tools: Younger developers tend to be heavy AI users (Stack Overflow’s 2025 Developer Survey found 51% use AI tools daily). They view AI as just another tool and expect structured inputs. Spec-first fits naturally into how they already work with AI assistants (think of LLM prompts as just elaborate instructions).

In contrast, seasoned engineers may need persuasion, but once they see that spec-driven dev accelerates large-scale projects and reduces unplanned firefighting, many become converts. The best outcome is teams blending strengths: seniors guiding architecture in the spec, and juniors using it to confidently implement features.

Software Engineer Skills and Salaries in 2026

In the landscape of 2026, software engineering remains a high-demand, high-pay field. Refonte’s program page boasts a $97.5K+ starting salary and “200K+ (Jobs Annually)” for software engineers. To put that in context, U.S. labor data and market surveys show similar trends. The Bureau of Labor Statistics projects 15% growth for software developers (2024 to 2034), with roughly 129,200 openings per year. Independent salary data (April 2026) give a more granular picture: Indeed reports an average base of about $132,000 for U.S. software engineers (entry-level around $75K), and Glassdoor an average of $149,000 (range of roughly $119K to $189K). In short, Refonte’s numbers line up with market reality: engineers are well-paid and plentiful jobs are available nationwide.

Beyond raw salary, the skills expected of engineers continue to broaden. 2026 employers prize not just coding ability, but system thinking: version control, CI/CD, cloud architecture, observability, and security practices are table stakes. This matches the Refonte curriculum focus (full-stack, cloud, performance, security). Spec-driven development neatly fits into these demands. It is essentially a cross-cutting skill that touches planning, design, collaboration, and security. Writing and using specs with AI agents hones your abilities in requirement analysis, architecture design, and secure-by-design coding, all vital soft and hard skills.

For more on broader career skillsets, see our related guide How to Become a Successful Software Engineer in 2026: Skills and Career Path. The bottom line: companies will value engineers who can move a feature from idea through production consistently and safely. Spec-driven development is increasingly seen as a core capability in that toolkit, as essential as knowing a popular language or framework.

Building This Skill Set: The Refonte Learning Software Engineering Program

Spec-driven development and AI coding tools are cutting-edge, but they rest on timeless software fundamentals. Refonte Learning’s Software Engineering Program (3 months, approximately 12 to 14 hours per week) is built to teach exactly the kind of solid foundation you’ll need for this new workflow. The curriculum includes modules like Foundations of Software Engineering, Cloud Architecture and Microservices, and Application Security, all of which reinforce structured thinking and secure design. (It doesn’t explicitly say “we teach Spec Kit or Kiro,” because these tools are very new; instead, it covers the underlying skills that those tools leverage.) With mentors like Oskar Eriksson (10+ years of experience) guiding learners, the program emphasizes real-world projects and modern practices.

In practical terms, the program’s focus on requirements, cloud-based systems, and security means you’ll naturally gain experience that complements a spec-first approach. For example, an assignment to design a microservices architecture or to enforce input validation in an app directly teaches you to think in terms of specs and constraints. Graduates from the program step out ready to enter roles like Software Engineer or Cloud Engineer, where they’ll likely be expected to work with AI tools at some point. By learning to write clean specifications, plan robust designs, and prioritize security within a guided environment, you build the habits for success with AI-assisted development.

Refonte Learning’s Software Engineering Program is more than just a list of topics. It’s a career accelerator that aims to boost the very skills we’ve discussed: structured development practices, cloud-native thinking, and solid security habits. If you’re looking to future-proof your career, consider how mastering a spec-driven workflow could set you apart. With the program page advertising starting salaries around $97.5K+ and employers actively seeking engineers who can bridge coding and planning, now is the time to level up. For details on this program, see the Refonte Learning Software Engineering Program page.

Each software team will adopt these methods at its own pace, but as a practitioner I can assure you: investing in spec-driven skills is investing in safer, more maintainable code. The era of winging it with AI prompts is giving way to disciplined agentic engineering. By writing specs, standards (like AGENTS.md), and plans first, we keep the human intent at the center of our AI-powered development. As the community has learned, that’s the best way to keep shipping production-quality software.