Specification-Driven Development with Amazon Q Developer

Introduction

I used to be that developer. You know the one—throwing half-baked prompts at AI assistants like "revactor this!1!" with spelling errors and hoping for magic. The output often looked impressive, felt like magic, but it wasn't engineering. I was just riding the wave of AI-generated coding without structure, context, or intention.

How can we get better?

The Problem with Vibe Coding

Watching AI generate code feels incredible. But after the initial euphoria wears off, you're left with a fundamental problem: you've outsourced thinking to a machine that doesn't understand your business context, architectural decisions, or long-term goals. You get code, but you don't get engineering.

AI assistants like Amazon Q Developer aren't just code generators—they're software engineering partners. But like any partnership, the quality of collaboration depends on how well you communicate, share context, and structure your work together.

Goodbye vibe-coding. Hello, specification-driven development: a systematic approach that treats AI collaboration as serious software engineering. Instead of random prompts, we have structured conversations. Instead of disconnected code snippets, we build comprehensive solutions. Instead of starting with implementation, we start with understanding.

The Foundation

Before diving into my three-phase workflow, let me introduce the foundation that makes everything possible: Project Intelligence. Think of it as giving Amazon Q Developer a persistent memory about your project.

AI assistants have a fundamental limitation—their memory resets between sessions. Imagine if your human colleagues forgot everything about your project every time they left for coffee. You'd spend more time re-explaining context than actually building software.

Project Intelligence solves this through a structured documentation system living in .amazonq/project-intelligence/. It consists of interconnected markdown files:

• projectbrief.md - The foundation defines core requirements and goals

• productContext.md - Why the project exists and problems it solves

• systemPatterns.md - Architecture and design patterns in use

• techContext.md - Technologies, setup, and constraints

• activeContext.md - Current work focus and recent changes

• progress.md - What works, what's left, current status

These files create context for both humans and AI. When I start a session with Amazon Q Developer, I can reference this documentation using context modifiers, like @folder in the IDE chat or /context in the CLI chat. Suddenly, Q Developer understands what I'm asking for and why I'm asking for it within the broader project context.

Project Intelligence is highly inspired by what Cline calls “memory bank”. It isn’t just an AI assistant-specific feature - it’s a methodology for managing AI context through structured documentation.

My current workflow (June 2025)

Let me walk you through exactly how this works by showing you on an active developed feature to improve tag management and discovery in promptz.dev—the community platform I built for sharing Amazon Q Developer prompts.

Phase 1: Specification

I start every feature with a conversation. But this isn't just any conversation—it's a structured engineering discussion using proven prompt frameworks to write a technical specification.

Writing technical specifications isn't just good practice—it's fundamental software engineering. As engineers, our primary role is to solve technical problems. Technical specifications help you think through problems systematically. They increase the chances of building something that matters, building “the thing” right. They force you to consider edge cases, define success criteria, and understand dependencies before you write your first line of code.

The challenge? You might find writing specifications frustrating, especially if you don't consider yourself a strong technical writer. This is where AI assistants shine—they can help reduce this productivity friction and make you more likely to write specifications at all.

Here's the exact prompt I use to kick off the specification phase, available also on promptz.dev for a full preview:

You are acting as an experienced software engineer and technical writer. Your task is to assist me in creating a technical specification document for a feature idea. To complete the task, you must
- Read ALL files in the .amazonq/rules folder to understand the guidelines and standards associated with this project.
- Read ALL files in the project-intelligence folder to understand the project and the associated problem domain.
- Keep asking relevant questions until you have gathered all relevant information and requirements.
- Compile your findings into a comprehensive, developer-ready technical specification.

Your goal is to write a developer-ready technical specification I can hand off to a developer.

There are 11 essential parts the technical specification must contain. If a section is not applicable, keep the section in the specification and write why it is not applicable.

1. Summary: Brief overview of the feature, the user problem it solves, and the proposed solution...
2. Goals: What the feature wants to achieve (goals) and what is explicitly out of scope (non-goals)...
[continues with all 11 sections]

The key insight is treating Amazon Q Developer like an engineering partner. I don't just say "add better tag support"—I have the same type of technical discussion I'd have with a human peers:

• What problem are we solving?

• Who are the users, and what do they need?

• What are the technical constraints?

• How does this fit into our existing architecture?

• What are the success criteria?

Amazon Q Developer, armed with the Project Intelligence context, asks probing questions:

• "How should the tag filtering interact with the existing search functionality?"

• "Do we need to maintain backward compatibility with current tags stored in the prompts table?"

• "What's the expected scale—hundreds or thousands of tags?"

This back-and-forth creates the specification document. Not just requirements, but technical architecture, data models, error handling strategies, and testing approaches. Whatever you need as a developer to implement the feature correctly.

Key highlights from the specification you can read on github:

• Clear problem definition: "Currently, Promptz uses a static list of tags with limited query capabilities, hampering user experience."

• Specific goals and non-goals: What we're building and explicitly what we're not

• Detailed data model with entity relationship diagrams using Mermaid syntax

• Migration strategy that maintains backward compatibility

• Risk assessment with mitigation strategies

• Acceptance criteria that define exactly what "done" looks like

The specification covers aspects from user stories to performance requirements to open questions that need stakeholder input. This isn't just a feature request—it's a complete engineering blueprint that guides every subsequent decision, waiting for you to be fine-tuned.

Phase 2: Implementation Plan

With a solid specification, I move to the second phase: creating a step-by-step implementation blueprint. This is where I break down the complex feature into manageable, testable chunks.

Again, this isn't revolutionary—it's classical software engineering. Breaking complex tasks into smaller, iterative pieces that build on each other is how we've always approached large problems. It's the foundation of agile methodologies, sprint planning, and virtually every successful software project. The principle of "divide and conquer" has been core to engineering for decades.

What's different isn't the approach—it's the tool. Instead of manually decomposing features in planning meetings or writing user stories by hand, I'm collaborating with Amazon Q Developer to create a structured implementation plan. Steered correctly, the AI can bring the same systematic thinking we've always valued, but with the speed and consistency that human planning sometimes lacks.

Here's my prompt for the implementation planning phase:

You are acting as an experienced software engineer. Your task is to create a detailed, step-by-step implementation plan. To complete the task you must

- read ALL files in the .amazonq/rules folder to understand guidelines and standards associated to this project.
- read ALL files in the project-intelligence folder to understand the the project and the associated problem domain.
- read the feature specification.
- define a solid implementation plan.
- break it down into small, iterative chunks that build on each other.
- review the results and make sure that the steps are small enough to be implemented safely with strong testing, but big enough to move the project forward.
- iterate until you think that the steps are right-sized for this project.

Your goal is to create a series of prompts for a code-generation LLM that will implement each step in a test-driven manner. The prompts should be structured using the RISEN framework. Use the following prompt template for each prompt:

You are acting as [insert the role you want AI to take]. 
Your task is to [insert the main task you want AI to complete]. 
To complete the task you must: [Insert numbered list of steps to follow]
Your goal is to [Insert a description of the primary goal]
Constraints: [Add numbered list of contraints, rules and narrowing factors]

Save the implementation plan as `prompt_plan.md` next to the feature specification file.

For each prompt ensure, that it contains a step to read all files in the .amazonq/rules folder to understand the guidelines and standards.
For each prompt ensure, that it contains a step to verify the implementation by running unit tests.
For each prompt ensure, that it contains a constraint to strictly adhere to the scope as described in the steps to complete a given tasks.
Make sure that each prompt builds on the previous prompts.
Format each prompt as plaintext codeblock.
Use markdown.

Amazon Q Developer reads the specification and creates a detailed prompt plan—essentially a series of prompts using the structured RISEN framework. Each prompt builds on the previous one:

1. Project Setup: Initialize tests and basic data structures

2. Core Tag Model: Implement tag entity with validation

3. Tag Service Layer: Add business logic for tag operations

4. UI Components: Build reusable tag display and filter components

5. Integration: Wire everything together with proper error handling

6. Testing: Comprehensive test coverage for each layer

If you manage your context correctly, each step includes specific context references to our Project Intelligence and previous implementation steps. This can be achieved either manually by adding instructions to your prompt to read the project intelligence or by adding the aforementioned context management features of Q Developer.

Phase 3: Implementation Execution

Finally, we are heading to the execution phase, where I work through each prompt in the implementation plan. But here's the crucial difference from vibe coding: every interaction is contextual and purposeful.

Instead of asking Amazon Q Developer to "build a tag system," I'm having focused conversations:

Each response builds on the established context. Amazon Q Developer understands:

• The existing codebase patterns

• The specific requirements from our specification

• How the step fits into the larger feature

• The testing and quality standards we maintain

The result? Collaboration with AI assistants that feels like software engineering.

The Mental Shift

You're no longer just writing code (who said that software engineering was all about just writing code?)—you're orchestrating a sophisticated engineering process where AI handles the heavy lifting while you focus on the high-level thinking.

My time allocation shifted dramatically:

• More time writing specifications, documenting architecture decisions, and maintaining project context

• More time verifying outputs, ensuring consistency, and making strategic technical decisions

• Less time on repetitive coding tasks, debugging syntax errors, and researching implementation details

But here's the paradox: by spending more time on documentation and planning, I want to ship features faster. Better context leads to better AI output, which leads to fewer iterations and less debugging while still being in the lead, being part of the solution, being the solution, not the problem.

The Bigger Picture

Perhaps the most surprising discovery was how this approach brutally enforces good engineering practices. Documentation isn't optional when your AI partner needs context to function effectively. Architecture decisions can't be tribal knowledge when you need to communicate them clearly to an AI system. Who does not celebrate well-crafted and accessible documentation and decisions?

Is AI-assisted software engineering maybe the best thing to happen to our industry in decades? Not because it writes code for us, but because it forces us to practice actual engineering instead of just hacking together solutions.

The benefits I see over time:

• New team members onboard faster because documentation exists and is accessible.

• AI tools become not just tools but partners because they understand the project context.

• An entire workflow evolves with clarity because decisions are documented and software engineering practices are established independently of the toolset.

• Technical debt decreases because specifications catch design issues before implementation, either by yourself, your peers, or your AI assistant.

Getting Started: Your First Specification-Driven Feature with Amazon Q Developer

Ready to try this approach? Start small:

1. Set up Project Intelligence for an existing project—even just the core files will make a difference

2. Pick a simple feature you've been meaning to build

3. Resist the urge to code immediately—spend 30 minutes having a specification conversation with Amazon Q Developer first. I prefer to use the CLI, but you can try it out with other modalities that provide agentic behaviour.

4. Document everything—treat each conversation as valuable project knowledge

5. Build iteratively—follow your implementation plan step by step

You might feel like you're moving slower at first. That's normal. You're trading the illusion of speed (vibe coding) for actual engineering velocity.

The Future of Software Engineering

Specification-driven development isn't just about working better with AI—it's about returning to the fundamentals of software engineering while leveraging AI as a force multiplier.

We're not replacing human judgment with artificial intelligence. We're augmenting human engineering with AI assistance.

The future belongs to developers who can bridge the gap between human creativity and AI capability. The question isn't whether AI will change software engineering—it's whether you'll lead that change or just ride along.

---

Want to experience this approach firsthand? Check out promptz.dev for a collection of Amazon Q Developer prompts, including the specification and implementation prompts I use in my workflow. The platform itself was built using the exact approach described in this post.

Have questions about specification-driven development? I'd love to continue the conversation—reach out and share your experiences with AI-assisted software engineering.