I have been using AI coding tools quite a lot recently.

At the beginning, the workflow was very simple.

I would open the project, give AI a prompt like:

Add user permissions to this module.

Then AI would read some files, create code, modify migrations, change controllers, update frontend code and sometimes even add tests.

It looks very fast.

But when the project becomes large, this approach creates another problem.

The AI has to guess many things.

Which files should change?

Which existing code should remain untouched?

What should happen for admin users?

What about company-level permissions?

What happens when the user does not have permission?

Should the API return an error or an empty response?

Should the database structure change?

Should old APIs continue to work?

What should happen on mobile?

This is where I think spec-driven development becomes much more useful.

Spec-driven development is getting a lot of attention in AI-assisted software development because the idea is simple: define the requirement and expected behaviour first, then let AI implement it. Microsoft has also described this approach as making the specification the shared source of truth between humans and AI.

What is spec-driven development?

For me, it means:

Idea
  ↓
Requirement
  ↓
Specification
  ↓
Implementation
  ↓
Testing
  ↓
Review

Instead of:

Idea
  ↓
Prompt AI
  ↓
Generate Code
  ↓
Fix Problems
  ↓
Prompt Again
  ↓
Fix More Problems

The second approach can work for small tasks.

For production applications, I prefer the first one.

The main difference is that the AI does not have to invent missing requirements.

A normal AI coding request

Suppose I tell an AI:

Add a customer import feature.

This sounds clear to a human developer.

But actually it is not clear enough.

There can be many questions.

Which file format?

CSV only or Excel also?

How many records?

What columns are required?

What happens with duplicate emails?

Should existing customers be updated?

Should invalid rows be skipped?

Should the import happen synchronously?

What about 100,000 customers?

Who can import?

Should an activity log be created?

Should an email be sent after import?

Should failed rows be downloadable?

The AI will make assumptions.

And those assumptions can become code.

That is where a simple prompt becomes dangerous in a real project.

A better specification

Before asking AI to write code, I can define something like:

Feature: Customer Import

Goal:
Allow company admins to import customers from CSV.

Access:
Only users with customer.import permission.

Input:
CSV file.
Maximum file size: 20 MB.

Required columns:
name
email
phone

Validation:
email must be valid.
name is required.
Duplicate email inside the file must be rejected.

Existing customer:
If email already exists for the company, update the customer.

Invalid records:
Do not stop the complete import.
Store failed rows with validation errors.

Large files:
Process imports through the queue.

Logging:
Create an activity log after import completion.

API:
POST /customers/import

Success:
Return import ID and processing status.

Out of scope:
Do not change the customer table structure.
Do not change existing customer APIs.

Now the task is completely different.

The AI has boundaries.

It knows what is required.

It also knows what not to change.

That last part is very important.

The "out of scope" part is underrated

One thing I have noticed while using AI coding tools is that AI can sometimes solve a problem by changing something else.

For example, I ask:

Fix customer import validation.

The AI may decide to modify:

Controller
Service
Model
Migration
Frontend
API response
Database structure

Some of those changes may not actually be required.

So I like keeping an explicit section:

Do not change:
- Existing customer APIs
- Existing database columns
- Authentication flow
- Existing UI components
- Existing response format

This reduces unnecessary changes.

It also makes the final diff easier to review.

The specification becomes the contract

This is the part I find most useful.

The specification is not just documentation.

It becomes a contract.

For example:

Requirement:
Only company admins can import customers.

Acceptance test:
Normal employee receives 403.
Company admin can start import.

Now the AI can implement the feature and create tests against the requirement.

So instead of checking only:

Does the code look correct?

we can also check:

Does the implementation satisfy the specification?

That is a much better way to work with AI.

Recent research is also exploring this direction. A 2026 study on spec-driven test generation reported improved bug detection and branch coverage when the agent first reasoned from explicit specifications and contracts instead of generating tests directly from code.

AI is very good at implementation

This is where I think AI coding tools are already very useful.

I do not want AI to decide every product requirement for me.

I want to decide:

What?
Why?
Rules?
Constraints?
Expected result?

Then AI can help with:

How?
Which files?
Implementation?
Tests?
Refactoring?
Documentation?

This is a much better separation.

It also works well with existing projects

This is especially useful for old or large projects.

For a new project, AI can sometimes generate a complete structure.

For an existing project, it has to understand what is already there.

For example:

Laravel API
    ↓
Existing authentication
    ↓
Existing tenant system
    ↓
Existing RBAC
    ↓
Existing services
    ↓
Existing frontend

I do not want an AI tool to create another authentication system because it thinks that is easier.

The specification should clearly say:

Use existing authentication.

Do not create a new authentication system.

Use the existing tenant resolution logic.

Use existing permission middleware.

Follow existing API response format.

Now the AI has to work with the architecture instead of replacing it.

Spec-driven development is not only for AI

This is not actually a completely new software development idea.

Developers have used requirements documents, design documents, contracts, RFCs and acceptance criteria for many years.

What changed is AI.

Before AI, a developer could keep many project decisions in their head while writing code.

Now one AI request can produce changes across many files very quickly.

That makes missing requirements much more expensive.

Microsoft, IBM and other developer-focused sources now describe specification-first workflows specifically in the context of AI-assisted development.

I like breaking a feature into small specs

I would not create one huge specification for the entire application.

I prefer small feature-level specifications.

For example:

customer-import.md
customer-export.md
customer-bulk-delete.md
customer-permissions.md
customer-activity-log.md

Each one explains one feature.

This makes the AI task smaller.

It also makes review easier.

I would include these sections

My basic specification structure would be:

1. Goal
2. User / Business Requirement
3. Scope
4. Out of Scope
5. Existing Code to Reuse
6. Database Changes
7. API Changes
8. UI Changes
9. Validation Rules
10. Permission Rules
11. Error Handling
12. Acceptance Criteria
13. Testing Requirements
14. Performance Requirements
15. Security Requirements

It does not always need all 15 sections.

For a small change, the spec can be very short.

For a large feature, I would make it more detailed.

Acceptance criteria are very important

This is probably the most useful section for AI development.

For example:

Given a company admin uploads a valid CSV,
the import should start successfully.

Given a normal employee uploads a CSV,
the API must return 403.

Given the CSV contains a duplicate email,
the duplicate row should be marked as failed.

Given the CSV contains 50,000 records,
the import must use the queue.

Given the import is completed,
an activity log must be created.

Now "done" has a clear meaning.

Without acceptance criteria, the AI can generate something that looks correct but does not actually match the business requirement.

Specs should also include performance requirements

This becomes important for SaaS applications.

For example:

Do not process 100,000 records in one HTTP request.

Use queued jobs.

Do not load all rows into memory.

Process records in chunks.

Avoid N+1 queries.

Do not run one SELECT query for every imported customer.

These are implementation constraints that an AI may not automatically infer from a simple feature description.

Security should be part of the specification

For every feature that touches data, I would explicitly mention:

Authentication required.

Tenant isolation required.

Permission check required.

Do not expose internal database IDs unnecessarily.

Validate uploaded files.

Do not trust user-provided company IDs.

Prevent access to another company's records.

This is especially important in multi-tenant SaaS applications.

An AI can generate working code that still has a tenant-isolation problem.

The specification should make that requirement explicit.

The biggest change is actually how I write prompts

My prompt to AI is becoming smaller.

Earlier:

Build complete customer import system.

Now:

Read docs/features/customer-import.md.

First inspect the existing customer,
tenant, permission and queue implementation.

Do not change existing architecture.

Create an implementation plan.

Wait for plan approval.

Then implement the specification.

Run relevant tests.

Do not modify files outside the scope unless required.

The important information is already inside the specification.

The chat prompt just tells the AI what to execute.

This also makes AI output easier to review

Suppose AI creates 30 files.

Without a specification, I have to inspect everything and ask:

Why did it change this?

With a specification, I can compare:

Requirement
      ↓
Implementation
      ↓
Tests

The review becomes much easier.

I can check whether each requirement has an implementation and a test.

It can work with Git

Another advantage is that specifications can be committed to Git.

For example:

docs/
  specs/
    customer-import.md
    customer-export.md
    inventory-sync.md

Now the specification has a history.

We can see when the requirement changed.

We can also review the specification in a pull request before reviewing hundreds of lines of generated code.

This creates a useful workflow:

Spec PR
   ↓
Review Requirement
   ↓
AI Implementation
   ↓
Code PR
   ↓
Tests
   ↓
Human Review

Tools are also moving in this direction

This approach is no longer only a developer idea.

Tools such as GitHub Spec Kit and Amazon Kiro are built around specification-driven AI development workflows. AWS describes Kiro as taking prompts into detailed specs and then generating code, documentation and tests from them.

That is an interesting signal for me.

AI coding is slowly moving from:

AI writes code

towards:

Developer defines intent
        ↓
Specification
        ↓
AI implements
        ↓
AI tests
        ↓
Developer reviews

I still would not use specs for every tiny change

There is also a practical side.

I don't want to create a 20-page specification for:

Change button text.

That is unnecessary.

For a small change:

Change "Submit" to "Save Customer"

a normal prompt is enough.

For something like:

Billing
RBAC
Tenant changes
Payment gateway
Database migration
Large API
Background jobs
Mobile + web changes

I would absolutely prefer a specification.

My current workflow

For a medium or large feature, my workflow would be:

1. Understand the requirement.

2. Ask AI to inspect the existing project.

3. Create a specification.

4. Review the specification myself.

5. Ask AI to create an implementation plan.

6. Review the plan.

7. Let AI implement.

8. Run tests.

9. Review the Git diff.

10. Compare implementation against the specification.

11. Fix only the remaining gaps.

This gives me much more control.

My takeaway

AI coding is becoming very fast.

That is actually why I think specifications are becoming more important.

When coding was slow, a missing requirement usually meant a developer would discover it while implementing the feature.

When AI can generate hundreds of lines in a few minutes, a wrong requirement can also produce hundreds of wrong lines in a few minutes.

So I don't think the solution is simply better prompts.

For serious development, I think the better approach is:

Think first. Write the specification. Then let AI write the code.

For my kind of development, especially SaaS, ERP, APIs and multi-user systems, this feels much more practical than giving AI random prompts and fixing whatever it generates.

The AI should be fast at implementation.

The developer should still be responsible for deciding what actually needs to be built.