Q WoW, Upgraded: A Reflection on Spec-First Development

Spec-first development is not about development suddenly having to change because AI tools have appeared.

That would be too simple a conclusion.

What we have done at Q is much more important than that: we took our own way of working, which we have been developing for years through real projects, real clients, real deadlines and real problems, and upgraded it for a new phase of software development.

Q has never built quality by accident. We have always aimed to do our work better and with higher quality, and we have had the freedom to explore ways to improve how we work. We looked for processes and mechanisms that help us preserve knowledge, share it with colleagues and make it available across the organization.

Whenever we recognized through practice that an approach could improve quality in the long term and make the way teams work more consistent, we tried to turn it into a standard. We have done this before with tools and practices such as Docker in local development, and I see spec-first as a similar step. Not as a one-time experiment, but as an attempt to make a good way of working more repeatable, clearer and available to all teams.

Our way of working has always relied on structure, clear communication, technical responsibility, the review process, collaboration between different roles and the ability to turn complex requirements into deliverable solutions. This is part of why we are recognized as a development partner at a high level, not only locally but globally.

Spec-first is not a replacement for that.

Spec-first is the logical continuation of it.

If we already had a good process, we are now making it more explicit. If we previously had knowledge in the heads of seniors, leads, PMs, BAs and designers, we are now trying to document it better, structure it and make it available to the whole team, as well as to the AI tools we use in development.

Because AI can speed up delivery, but it cannot know our way of working on its own.

It does not know our project context. It does not know the agreement with the client. It does not know why we made a certain architectural decision six months ago. It does not know where the scope boundaries are. It does not know what Q considers acceptable quality unless we define it clearly.

That is where spec-first becomes important.

Not as a new layer of bureaucracy, but as a way to turn what we already do well into a more stable, repeatable and clear framework.

From agile work to a clearer decision trail

In our agile way of working, change is part of everyday life. Clients often come with new requests, priorities shift, and sometimes developers themselves propose or introduce changes to improve the solution.

That is normal. Good development is not blindly following a plan someone wrote three months ago. Good development includes learning, adapting and making better decisions along the way.

But every change has its cost and impact on the project.

That is why it is important to have a clear decision trail: what changed, why it changed, who requested the change and who delivered it.

This is exactly why structured artifacts and specifications are not only tools for planning and development, but also mechanisms that provide greater visibility, easier change management and clearer ownership throughout the entire project lifecycle.

In practice, this means that spec-first is not only a technical approach. It is also a way for the team to better understand its own decisions.

And that is often the difference between a project that simply moves forward and a project that progresses in a truly controlled way.

Artifacts as a shared source of truth

In this process, artifacts created or updated by individual skills during development play an important role. We are not talking about documentation as a formality, but about records that carry decisions, context and knowledge needed for quality delivery.

The Constitution document defines architectural principles, technical constraints and the basic rules of the system.

The specification describes business requirements, rules, user flows and the expected behavior of the system.

The UIX document connects user experience and design decisions with the rest of the development process. It helps ensure that information from Figma, such as screen structure, components, states, flows and interactions, does not remain isolated in the design tool, but becomes part of the context that can be used in the specification, technical design and implementation.

The Design document serves as a technical blueprint for the solution; it describes the system structure, key components, integrations, data flows, and decisions that guide implementation.

The Tasks document then breaks complex requirements into smaller, clearly defined tasks ordered in the sequence in which it makes sense to implement them. The Implementation skill goes through those tasks one by one, which breaks implementation into smaller units that are easier to review, validate and correct if needed. After that, it writes an implementation summary, a summary of what has been implemented.

The Review skill checks whether the implementation is aligned with the previously defined artifacts. Its value is not only in checking whether the code works, but also in checking whether the implementation stayed true to the agreed scope, architectural rules, design decisions and expected system behavior.

Together, these artifacts carry the decision trail made during the project and form a shared source of truth that enables consistent execution of those decisions throughout the entire development process.

This is not documentation that stands aside and gathers dust.

It is a working context that helps the team understand faster what is being built, why it is being built, how it is being built and by which criteria we check whether it has been done correctly.

Role knowledge, written into the process

Today, we no longer look at project knowledge only through people and their roles, but also through the artifacts created during the project.

Just as the solution architect defines the fundamental rules and guidelines of the system through the constitution, other disciplines also get their structured sources of truth.

The specification becomes the place where the business analyst shapes business requirements and rules.

The product or project manager uses it to guide priorities, expectations and delivery boundaries.

The designer communicates user experience and interaction principles through UX guidelines.

Design documents reflect the technical decisions of architects and leads.

Tasks are created from the way the development team thinks about delivery, breaks down work and organizes implementation.

Each of these artifacts represents concentrated knowledge from a specific role and makes that knowledge clear, available and applicable throughout the entire project lifecycle.

When we built our spec-first framework, we started from something that was already natural to us: every key role on a project has its own responsibility, its own knowledge and its own way of making decisions.

That is why we gave each of those roles a corresponding AI agent skill that reflects the way that person contributes to the project.

For example, when forming a new project team, the solution architect and tech lead are often involved early on. The solution architect brings a broader architectural perspective and helps establish the foundations of the system, while the tech lead participates from the beginning in shaping the technical direction so that decisions are applicable in everyday development, the review process and further delivery on the project.

Spec-first now makes that way of thinking more explicit through the Constitution document. The Constitution is not just a generated document at the beginning of the project, but a place where the initial architectural vision connects with the practical rules the team uses during development. It defines principles, constraints and architectural guidelines that serve as a reference point for the whole team, as well as for the AI agents involved in the process. In this way, important technical decisions become clearer, more accessible to the team and concrete enough to truly guide implementation.

We look at other roles in the same way.

The business analyst brings understanding of the business context and requirements.

The product or project manager brings priorities, expectations and the broader project framework.

The designer brings user experience, interface structure and interaction principles.

Developers and leads bring technical feasibility, implementation quality and responsibility for the maintainability of the solution.

Spec-first allows knowledge that was previously often implicit to become clearly written, structured and available to everyone.

At a high level, that is exactly the core of the spec-first approach: knowledge, decisions and responsibilities that used to be scattered across people, meetings and communication channels are turned into structured artifacts that become a shared source of truth for the entire team and for AI tools.

Value from a developer’s perspective

From a developer’s perspective, the value becomes even more concrete for me at the operational level.

A large part of development time is not spent on writing code itself, but on understanding context: what exactly needs to be done, why something was decided in a certain way, what the boundaries of the solution are and how my part fits into the broader picture of the system.

When that information is written in specifications, design documents and tasks, I spend less time searching for answers across messages, meetings or colleagues’ heads, and more time on actual implementation.

Even more importantly, this way of working reduces the number of assumptions I have to make as a developer.

Instead of guessing what the author of a requirement had in mind or why a certain architectural decision was made, I can rely on artifacts that carry that context.

This makes development easier, improves the quality of the review process and makes onboarding new team members significantly faster.

With the emergence of AI tools, this effect becomes even stronger.

When an AI agent has access to the same sources of truth that I use, I get an assistant that understands the project context much better than it would from a single prompt.

The result is not only faster implementation, but also fewer wrong assumptions, less revisiting of decisions that have already been made and greater consistency across the entire codebase.

Cost, models and the feeling of control

One of the practical questions that naturally comes up when using AI tools in development is the question of cost. How much does it actually cost, how much does it depend on the model, and can we get a quality result without constantly manually choosing the most expensive options?

My experience is that the spec-first approach brings a lot of value here. In everyday work, I mostly use auto mode in Cursor, where the tool itself orchestrates model selection in the background, so I do not worry about which model is used for each individual step. When the AI agent works from well-prepared context built through the spec-first artifacts, such as the constitution, specification, UIX, design, and tasks documents, the output is good enough that I do not feel the need to constantly select models manually or force stronger ones.

In other words, the focus shifts from the question “Which model should I choose now?” to the question “Have we given the model clear enough context to do a good job?” That is a much more useful way of thinking for me, because as a developer and lead I can actually influence it.

In practice, working with auto mode in Cursor has shown that in most cases the monthly cost can stay within a reasonable range, especially when AI is not used for endlessly regenerating the same problem, but for guided implementation through clearly defined tasks. Exact numbers can depend on the project, intensity of use and internal rules, but the important point is not only how much the tool costs, but how much time and how many wrong attempts it helps us avoid.

Spec-first gives me one more important thing here: a sense of control. When the context is well prepared, AI does not lead the process instead of me. I still guide, check, make decisions and use my own technical knowledge. Sometimes I need to guide the model more, direct it further or correct it, but that is actually healthy. It means the developer does not step out of the process, but remains responsible for the direction and quality of the solution.

In other words, spec-first is not about developers thinking less. It is about developers spending less time on wrong assumptions and more time on decisions that truly require their experience.

Ownership of artifacts

A further important step is clearly defining ownership over these artifacts.

Decision owners existed before as well, but information was often scattered across tickets, documents and communication channels.

Today, the decision trail remains written inside the project codebase through artifacts that have their owners and an approval process.

The team lead takes responsibility for the constitution and design documents and approves them as the owner of the project’s technical direction.

The business analyst, product owner or project manager is responsible for specifications and their approval because they represent the business source of truth.

The development team, through review and approval of tasks, takes responsibility for how the requirements will be implemented.

In this way, it is not only clear what was decided, but also who made the decision, who approved it and where it is permanently recorded.

That is an important shift.

Because in complex projects it is not enough to know that something was done.

We also need to know why it was done exactly that way.

UX/UI, Figma and MCP as part of the same context

A good example of this is the UX/UI discipline.

For years, designers have not used Figma only to create static screens, but to define interface structure, user flows, components, variants, states, visual language and interactions.

In the spec-first approach, we further connect this way of working with the rest of the development process through the UX/UI skill, which knows how to read design artifacts and turn them into context relevant for the specification, design documents and implementation.

When MCP, or Model Context Protocol, is added to this, that context no longer needs to travel manually through screenshots, copy-pasted descriptions or isolated comments.

AI agents can retrieve relevant information from Figma, specifications, the constitution and other sources of truth in a standardized and controlled way exactly when they need it.

In this way, Figma does not remain only a space for design, but becomes one of the active sources of project context that connects designers, developers and AI agents throughout the entire development process.

That is an important difference.

It is not only about having a design that someone later “translates” into code.

It is about design decisions becoming part of a broader, structured development context.

What spec-first actually means in practice

In recent months, there has been a lot of talk about the spec-first approach, but it often remains unclear what it actually means in practice.

At its core, it means defining key decisions, requirements and expectations before implementation, and making the specification the central place around which business and technical stakeholders align.

This approach is not new, but today it gains additional importance because it enables better collaboration between teams and more effective use of AI tools during development.

Spec-first forces us to answer earlier the questions that appear later anyway:

What exactly does the feature do?

What does it not do?

What are the edge cases?

What are the business rules?

Which parts are UX decisions, and which are technical decisions?

What data is needed?

What needs to be approved before implementation?

What is tested?

What are the risks?

In classic development, these questions are often split across several channels: part of the context is in the task, part in Slack, part in a meeting, part in the design, part in the developer’s head, part with the PM or BA.

Spec-first reduces that room for interpretation.

That does not mean everything will be perfect. But it means decisions are made earlier, more visibly and in a more structured way.

And when decisions are made earlier, implementation has much less room to wander.

SPEC gate: where the feature is truly defined

The SPEC phase is one of the most important phases, especially for PM, BA and delivery.

This is where it becomes clearest what the feature is and what it is not.

A developer can implement quickly later, but only if the scope has been defined clearly enough.

If the SPEC is not clear, development becomes expensive guessing. Maybe faster guessing than before, but still guessing.

A good SPEC should capture the business goal, user flow, rules, constraints, edge cases and expected behavior.

It does not need to be a novel.

But it does need to be concrete enough that multiple people on the team can read the same document and reach the same conclusion.

That is what is often missing when we work in a fragmented way.

Not because people do not know their job, but because context easily gets scattered.

One part of the context is in the task, another in the design, a third in a conversation and a fourth in someone’s experience.

Spec-first says: before we start, let us put it in one place.

DESIGN phase: fewer assumptions, more alignment

After SPEC comes the part where we elaborate how the feature will work at the level of design, architecture and user experience.

It is important to emphasize one thing here: spec-first does not replace designers, PMs, BAs or developers. It gives them a better framework.

The UX/UI part is not only a matter of appearance.

It is a matter of interface behavior, states, validations, empty results, errors, permissions, loading, responsiveness and all those “small” details that determine whether a feature works in practice or not.

And we know how it goes.

If those details are not defined before implementation, someone will define them later.

Most often the developer.

Or AI.

Or a bug report.

That is the most expensive designer: a bug report after implementation.

Spec-first helps decisions be made earlier.

Not all of them, not perfectly, but enough so that implementation does not start in the fog.

TASKS phase: AI must not receive chaos as input

Only when we have SPEC and DESIGN does it make sense to break the work down into tasks.

This is the part where spec-first connects very well with AI tools.

AI can help elaborate tasks, dependencies, implementation order, checks and tests.

But again, the quality of the output depends on the quality of the input.

If AI gets an unclear feature, it will generate unclear tasks.

If it gets a good SPEC and a good DESIGN, it can generate a much more useful breakdown.

This brings us to an important change in the way we work: AI is not only a tool for writing code. AI becomes a tool that helps us structure development before code.

That is a big difference.

Because then we do not use AI only as a “faster junior” who types.

We use it as an assistant in preparation, elaboration, review and implementation.

But we still have to lead the process.

AI can speed up execution.

It must not take over ownership.

PM/BA and spec-first

Spec-first is often perceived as something developer-focused because it ultimately lives in the repository and is used before implementation.

But in reality, it brings the most value when it is involved even before development.

PMs and BAs do not necessarily need to work in the repository in the same way as developers. But their input is essential in the SPEC phase.

They help define what the real problem is, what the user expects, what the business rule is, what the priority is and what is out of scope.

There can still be a working version of communication, comments and discussion in tasks.

But the repository should contain the final version that goes into development.

That is the difference between a conversation and a decision.

A task can be the place where the discussion evolves.

The spec should be the place where the decision is locked.

Spec-first does not remove the review

This needs to be said very clearly: spec-first does not mean we can blindly accept AI output.

AI and people still make mistakes. Especially when they are in a hurry.

Having SPEC, DESIGN and TASKS does not mean we can skip senior review.

Quite the opposite.

Review becomes even more important because now we are not only checking whether the code works, but also whether the implementation is aligned with the agreement.

We need to be especially careful when AI works in a stack or area that is not our strongest technical skill.

The output can look convincing.

The structure can look professional.

Names can be good.

Even tests can exist.

But that does not automatically mean the solution is correct.

Senior review is still mandatory.

It simply has better material to check against now.

Instead of the reviewer having to guess what the developer intended to do, they can compare the implementation with the SPEC, DESIGN and TASKS document.

That makes the review more concrete.

What changes for leads

From a lead perspective, spec-first is especially interesting because it changes where control happens.

Without a spec-first approach, the lead often reacts late.

The feature is already implemented, the PR is large, the deadline is close, and then it turns out that some assumptions were wrong.

At that point, corrections become more expensive, and changes require more time and coordination.

Spec-first moves control earlier.

The lead can review the Constitution, SPEC, DESIGN and TASKS before a large PR is created.

They can stop the wrong direction before hours of implementation are spent.

They can see where there are gaps in thinking.

They can help the team avoid going in the wrong direction.

That is not micromanagement.

That is technical leadership.

A good lead does not need to write every line of code.

But they need to help the team know what is being built, why it is being built and according to which rules it is being built.

Spec-first provides that structure.

The biggest challenge: discipline

Of course, spec-first is not magic.

The biggest challenge will not be the tool.

It will not even be the document format.

The biggest challenge will be discipline.

It is easy to skip SPEC when we are in a hurry.

It is easy to say: “It is clear, just let AI do it.”

It is easy to accept a generated document because it looks professional.

It is easy to start implementation before open questions are closed.

But that is exactly when spec-first has the most value.

The process is not there for the days when everything goes smoothly.

The process is there for the days when there is pressure, when deadlines are tight, when there are many assumptions and when everyone thinks “there is no time.”

That is when the difference between speed and maturity becomes visible.

Speed without control is just a faster path to rollback.

Conclusion

I do not see spec-first development as a break from our existing way of working, but as its natural evolution.

At Q, we have spent years building a way of working based on quality, responsibility, collaboration and technical clarity.

Spec-first does not fundamentally change that way of working.

It makes it more visible, more structured and better prepared for development in which AI tools become part of the everyday process.

That is the most important difference for me.

We do not start from the question of what AI will do instead of us.

We start from the question of how we will carry our existing quality standard into a new way of working.

Constitution defines the project rules.

SPEC locks what the feature is and what it is not.

DESIGN elaborates behavior, experience and technical direction.

TASKS turn the agreement into an executable plan.

Implementation then no longer starts from an empty prompt, but from context that reflects our way of working.

That is why I do not see spec-first as a trend, but as an upgrade of the existing engineering process.

AI can give us speed.

But structure, responsibility and quality still have to come from us.

And that is exactly why spec-first matters: not because it changes who we are, but because it helps preserve what we already do well while adapting it to the way we build software today.

______________________________________________

A sneak peek at what comes next

For this workflow, everything lives in the IDE today. The next blog we will be getting it out of the editor, one piece at a time. Each step’s already a skill running against the artifacts, so you can hand a step to an agent that owns it end to end, asking in Slack, waiting on a gate in a dashboard, dropping the approved artifact back in the repo for the next agent. The workflow doesn’t move. Where the work happens does.
Three things sit on top, and each one’s its own write-up. Legacy projects get an on-ramp, a swarm of subagents reads the old code and reverse-engineers a constitution from it, so a brownfield repo runs the same workflow as a greenfield one. What’s solid right now is the workflow you run in the IDE. Artifacts first. Gates first. Discipline first. The agents come after, once that foundation is boring and dependable.