☕ Markdown Is Becoming the Language We Use to Build Software

Thoughts on Spec-Driven Development, AI, and the Future of Engineering

Jul 02, 2026

AI-generated image, spec-driven development

Welcome back to Code & Coffee.

Every so often, a technology comes along that doesn’t just change how we build software. It changes where the real engineering happens.

I think AI is one of those moments.

Not because it writes code.

We’ve had code generators for decades.

What’s different is that modern AI can reason over requirements, architecture, documentation, APIs, business rules, and tests simultaneously.

And that has led me to a simple thought that I haven’t been able to shake:

Maybe code is no longer the primary artifact of software engineering.

Maybe the specification is.

The Thought That Started It All

A few months ago, I noticed something interesting about my own workflow.

I wasn’t spending most of my time writing Java anymore.

Or Python.

Or TypeScript.

Instead, I was writing...

Markdown.

Not documentation.

Specifications.

Requirements.

Architecture decisions.

Domain models.

Acceptance criteria.

Plans.

The actual coding part often came afterwards, with the help of AI.

That felt... backwards.

Or perhaps...

It’s actually the new normal.

What If Markdown Is the New Programming Language?

Obviously, Markdown isn’t replacing Java.

Or Python.

Or Javascript.

Or Go.

That’s not what I mean.

What I’m suggesting is something different.

Programming languages describe how software behaves.

Specifications describe what should exist.

As AI becomes better at translating intent into implementation, that “what” becomes increasingly valuable.

Markdown isn’t executing software.

It’s executing ideas.

Through AI.

We Used to Think Like This

For years, software projects looked something like this:

Idea
  ↓
Architecture
  ↓
Implementation
  ↓
Testing
  ↓
Documentation

Notice what happens?

Documentation is almost always trying to catch up.

Requirements drift.

Architecture diagrams become outdated.

The code becomes the only thing anyone truly trusts.

AI Quietly Changes the Equation

Now imagine something different.

Idea
  ↓
Specification
  ↓
Planning
  ↓
Tasks
  ↓
Tests
  ↓
Implementation
  ↓
Continuous Validation

The specification isn’t an afterthought anymore.

It’s the first artifact.

Everything else is derived from it.

Including the code.

That’s a profound shift.

Why This Feels Different

When I use AI today, I notice two completely different experiences.

One looks like this:

“Build a billing system.”

Then follows fifteen prompts explaining everything I forgot to mention.

The other starts with a carefully written specification.

Business goals.

Actors.

Rules.

Constraints.

Acceptance criteria.

Performance expectations.

Security.

Only then do I ask AI to implement it.

The second experience feels less like prompting.

It feels like engineering.

AI Doesn’t Need Better Prompts

It Needs Better Context.

That’s the biggest lesson I’ve learned.

Developers spend a lot of time talking about prompt engineering.

I think specification engineering is much more interesting.

A good specification answers questions before they’re asked.

It removes ambiguity.

It becomes a contract.

Not between developers.

Between humans and AI.

We’re Becoming Designers Again

One concern I hear often is:

“Will AI replace software engineers?”

I don’t think so.

But I do think it changes what great engineers spend their time doing.

Instead of manually implementing every detail, we increasingly focus on:

designing systems
understanding domains
defining constraints
thinking about trade-offs
reviewing implementations
ensuring quality
making architectural decisions

Ironically...

AI pushes us toward higher-level engineering.

Not lower.

The Most Important Repository Isn’t `/src`

Imagine opening a new project in a few years.

Instead of seeing this:

/src

You see:

/specs

Inside are files like:

constitution.md
product-spec.md
domain-model.md
security.md
api-spec.md
acceptance-tests.md
tasks.md

Every AI agent reads them.

Every engineer reviews them.

Every feature begins there.

Every pull request references them.

That repository becomes institutional knowledge.

Not scattered conversations with AI.

Not forgotten documents.

Living specifications.

This Isn’t About Replacing Code

We’ll always need code.

We’ll always need algorithms.

Performance still matters.

Architecture still matters.

Programming languages still matter.

But perhaps they stop being where software starts.

Maybe they become where software finishes.

A Small Prediction

Five years ago, asking an AI to generate production-ready code sounded unrealistic.

Today, many of us do it daily.

So here’s my prediction.

Within the next few years, the first file created in many software projects won’t be:

main.py

App.java

index.ts

It will be:

product-spec.md

Not because Markdown became executable.

But because intent became executable.

And that may be the biggest shift software engineering has seen since version control.

Coffee Break ☕

I’m curious how your workflow has changed over the past year.

Are you still starting with code?

Or are you already spending more time writing specifications than implementations?

If you’re experimenting with Spec-Driven Development, or even if you disagree with the premise, I’d love to hear your perspective.

The most interesting conversations often start with a simple question.

Maybe this is one of them.

Discussion about this post

Ready for more?