ATLAS + GOTCHA vs Spec-Driven Development: What's the Same, What's Different

The Problem

A developer comparing structure and chaos on two screens

You’ve been following this series. You know ATLAS (5 phases of structured thinking) and GOTCHA (6 layers of AI instructions). You’ve used them to build APIs, pipelines, and infrastructure. They work.

Then you open Twitter and see: “Spec-Driven Development is the future.” Thoughtworks puts it on the radar. GitHub launches spec-kit. Amazon ships Kiro. Martin Fowler writes about it. Every AI coding blog is talking about specs.

And you wonder: is this the same thing I’ve been doing? Is ATLAS + GOTCHA already SDD? Should I switch? Are they complementary? What’s actually new here?

This article answers those questions honestly. No “our framework is better.” No “SDD is just hype.” A real comparison: what’s shared DNA, what’s genuinely different, and when to use each approach.

What SDD Actually Is

Spec-Driven Development inverts the traditional workflow. Instead of writing code and documenting it later, you write the specification first and use AI to generate the code from it. The spec is the asset. The code is the output.

The Thoughtworks definition: “A development paradigm that uses well-crafted software requirement specifications as prompts, aided by AI coding agents, to generate executable code.”

Most SDD implementations follow three stages:

Specify — Write what the system should do. User stories, acceptance criteria, non-functional requirements. Focus on WHAT, not HOW.
Plan — Generate a technical implementation plan from the spec. Architecture, data models, API contracts, task breakdown.
Execute — AI generates code from the plan. Tests first, then implementation.

Tools like GitHub spec-kit add structure: a spec.md file with user stories, a plan.md with architecture, a tasks.md with ordered work items. Amazon Kiro builds this into the IDE: requirements → design → tasks, each as a markdown document.

The Shared DNA

ATLAS + GOTCHA and SDD agree on the fundamentals. This is not a coincidence — both frameworks exist because the same problem was obvious to everyone working with AI in production.

1. Think before you prompt

Both frameworks say: don’t open the AI tool and type “build me a user service.” Think first. Structure your thinking. Write it down.

In ATLAS, this is the 5-phase checklist: Architect → Trace → Link → Assemble → Stress-test.

In SDD, this is the Specify stage: user stories, acceptance criteria, non-functional requirements.

Same principle. Different vocabulary. Both exist because vague prompts produce vague code.

2. The spec is the asset, not the code

ATLAS + GOTCHA says: keep your GOTCHA prompts in the repository. Update them when requirements change. The prompt is the documentation (article 7, anti-gotcha #7).

SDD says: the specification is the primary artifact. Code is generated from it and can be regenerated.

Same insight. If you lose the code, you can regenerate it from the spec. If you lose the spec, you’re starting over.

3. Structured format over freeform prose

GOTCHA uses 6 explicit layers: Goals, Orchestration, Tools, Context, Heuristics, Args. Each layer answers a different question. You don’t mix them.

GitHub spec-kit uses structured files: spec.md (what and why), plan.md (how), tasks.md (in what order). Each file has a template with sections.

Both reject the idea of a single paragraph prompt. Both separate concerns into distinct sections with clear purposes.

4. Human decides, AI executes

Both frameworks keep the human in the loop. In ATLAS + GOTCHA, the human fills in the ATLAS checklist and writes the GOTCHA prompt. The AI generates code from it. The human reviews and adjusts (article 5, “What the AI Got Right and What We Adjusted”).

In SDD, the human writes the spec, reviews the plan, and validates the generated code. The AI proposes, the human decides.

Neither framework is “autonomous AI coding.” Both are structured collaboration.

The Mapping

Mapping diagram between ATLAS + GOTCHA and SDD

Here’s how the pieces correspond:

ATLAS + GOTCHA	SDD (spec-kit)	What it does
Architect (ATLAS)	spec.md — overview, user stories	Define what to build and the boundaries
Trace (ATLAS)	plan.md — data flow, architecture	Map how data moves through the system
Link (ATLAS)	plan.md — contracts, data models	Define integrations and interfaces
Assemble (ATLAS)	tasks.md — ordered task list	Decide the build order
Stress-test (ATLAS)	spec.md — acceptance criteria	Define how to validate
Goals (GOTCHA)	spec.md — user stories	What the AI must achieve
Orchestration (GOTCHA)	tasks.md — task order	Sequence of work
Tools (GOTCHA)	plan.md — tech stack	Frameworks and libraries
Context (GOTCHA)	Constitution / steering	Project-wide rules and environment
Heuristics (GOTCHA)	Constitution — articles	DO/DON’T rules for the AI
Args (GOTCHA)	plan.md — config, env vars	Concrete values and parameters

The mapping is not 1:1 — the boundaries don’t line up perfectly. But every piece of information that ATLAS + GOTCHA captures has a home in SDD, and vice versa.

The Real Differences

1. Scope: architecture vs. features

ATLAS + GOTCHA starts from architecture. The first question is “what are the boundaries of this system?” The framework is designed for architects who think in terms of services, integrations, data flows, and failure modes.

SDD starts from features. The first question is “what does the user need?” The framework is designed for product teams who think in terms of user stories, acceptance criteria, and business value.

This is the biggest difference. ATLAS asks “how does the system work?” SDD asks “what should the system do?”

Both are valid starting points. But they lead to different prompts. An ATLAS + GOTCHA prompt for a notification service starts with the architecture: “Event-driven .NET worker, Service Bus, 3 channels, circuit breaker on provider failure.” An SDD spec starts with the user: “As a customer, I want to receive an email when my order is confirmed.”

In practice, you need both. The user story tells you what to build. The architecture tells you how to build it so it survives production.

2. Tooling: framework vs. ecosystem

ATLAS + GOTCHA is a framework — a way of thinking. It works with any AI tool. You can use it with Claude, GPT-5, Mistral, Copilot, Cursor, or a plain text file. There’s no CLI, no VS Code extension, no specific file format. The template is a markdown document you fill in.

SDD has become an ecosystem. GitHub ships spec-kit with slash commands (/speckit.specify, /speckit.plan, /speckit.tasks). Amazon built Kiro as a dedicated IDE. OpenSpec is an open-source framework with support for 20+ coding assistants. Each tool has its own workflow, its own file format, its own conventions.

The advantage of tooling: automation. Spec-kit generates the file structure, enforces templates, and connects stages automatically. You don’t need to remember the format — the tool handles it.

The advantage of no tooling: portability. ATLAS + GOTCHA works everywhere, with everything. No vendor lock-in. No tool to install. The knowledge is in your head, not in a CLI.

3. The Constitution concept

SDD (specifically spec-kit) introduces the idea of a constitution — a set of immutable principles that the AI must always follow. Things like “always prefer libraries over custom code” or “all functionality must be exposed through CLI” or “no implementation without tests.”

ATLAS + GOTCHA has Heuristics — the DO/DON’T rules. But Heuristics are per-prompt, not project-wide. You write them for each task.

The constitution is a good idea. It’s project-level Heuristics that apply to every prompt, every task, every generated file. In ATLAS + GOTCHA terms, you could create a “project GOTCHA” with the Heuristics and Context that never change, and include it in every task-level GOTCHA.

If you’re already using ATLAS + GOTCHA, adding a project-level constitution is easy. Create a GOTCHA-PROJECT.md with your permanent Context and Heuristics. Include it by reference in every task prompt. That’s essentially what a constitution does.

4. Regeneration philosophy

SDD, especially at the “spec-as-source” level, treats code as fully regenerable. Change the spec, regenerate the code. The spec is the source of truth, the code is the build output — like a compiled binary.

ATLAS + GOTCHA doesn’t go that far. The GOTCHA prompt generates a first draft that the human reviews and adjusts. Those adjustments live in the code, not in the prompt. Over time, the code diverges from the prompt as the human improves it.

SDD’s regeneration philosophy works well for greenfield projects where the spec is complete. It works less well for brownfield systems where the code has accumulated years of edge-case handling that no spec captures.

5. Three levels of rigor

SDD defines three levels:

Spec-first — Write the spec, then code to it (like TDD but for requirements)
Spec-anchored — Spec and code co-evolve, but the spec stays the reference
Spec-as-source — The spec IS the source code. Regenerate everything from it.

ATLAS + GOTCHA doesn’t define levels. It’s always the same process: think (ATLAS), prompt (GOTCHA), review, adjust. The rigor depends on the task — a small feature gets a light GOTCHA, a new service gets the full ATLAS checklist.

The SDD levels are useful for organizational adoption. “We’re spec-first for new features, spec-anchored for existing services.” It gives teams a vocabulary for their process maturity.

When to Use Each

Situation	ATLAS + GOTCHA	SDD
Designing a new system from scratch	Best — architecture-first thinking	Good — feature-first, add architecture in plan stage
Adding a feature to an existing system	Good — fill in Context from current system	Best — spec fits naturally into product workflow
Infrastructure / DevOps tasks	Best — the series covers Terraform, pipelines, K8s	Untested — SDD is mostly for application code
Team with mixed AI tools	Best — works with anything, no tooling required	Limited — spec-kit is GitHub-specific, Kiro is Amazon-specific
Team adopting AI for the first time	Good — simple mental model, print and use	Best — tooling guides the process step by step
Regulated environment (audit trail)	Good — GOTCHA prompts in the repo	Best — specs are formal documents, easy to audit
Solo developer	Best — lightweight, no overhead	Overkill — spec-kit workflow designed for teams

The honest answer: they’re not competing. They solve the same problem from different angles. ATLAS + GOTCHA is a thinking framework that produces prompts. SDD is a development workflow that produces specifications. Both turn vague intentions into structured AI instructions.

Using Them Together

Two puzzle pieces fitting together

Here’s the combination that works:

Use SDD’s Specify stage with ATLAS — Write user stories (SDD), then run them through the ATLAS checklist to add architecture, data flows, integrations, and failure modes. The spec gets the “what” right. ATLAS adds the “how” and the “what if.”
Use GOTCHA as the plan format — Instead of a freeform plan.md, structure the plan as a GOTCHA prompt. Goals from the spec. Orchestration from ATLAS Assemble. Tools from ATLAS Link. Context from the project constitution. Heuristics from the constitution + task-specific rules. Args from ATLAS Stress-test.
Use SDD’s task breakdown for execution — After the GOTCHA prompt, split it into ordered tasks (SDD’s tasks.md). Each task references the relevant GOTCHA section. The AI executes one task at a time, in order.
Use the constitution for project-level GOTCHA — Create a GOTCHA-PROJECT.md with your permanent Heuristics and Context. Every task-level GOTCHA includes it by reference.

The result: SDD’s product-oriented workflow + ATLAS’s architecture rigor + GOTCHA’s structured prompt format. Each framework contributes what it does best.

User story (SDD Specify)
    ↓
ATLAS checklist (Architect → Trace → Link → Assemble → Stress-test)
    ↓
GOTCHA prompt (Goals → Orchestration → Tools → Context → Heuristics → Args)
    + Project Constitution (permanent Context + Heuristics)
    ↓
Task breakdown (SDD Tasks)
    ↓
AI generates code per task
    ↓
Human reviews and adjusts

Template: The Combined Workflow

=== STEP 1: SPECIFY (SDD) ===
User story: As a [role], I want [capability] so that [benefit].
Acceptance criteria:
  - GIVEN [context] WHEN [action] THEN [result]
  - ...
Non-functional: [performance, security, compliance]
Out of scope: [what we're NOT building]

=== STEP 2: ATLAS (Architecture) ===
[A] ARCHITECT: boundaries, constraints, tech decisions
[T] TRACE: data flow from trigger to response
[L] LINK: integrations, protocols, failure modes
[A] ASSEMBLE: build order, patterns, quality rules
[S] STRESS-TEST: load, failure, security scenarios

=== STEP 3: GOTCHA (AI Prompt) ===
GOALS: (from user story + Architect)
ORCHESTRATION: (from Trace + Assemble)
TOOLS: (from Link)
CONTEXT: (from Link + project constitution)
HEURISTICS: (from Assemble + project constitution)
ARGS: (from Stress-test)

=== STEP 4: TASKS (SDD) ===
1. [task derived from GOTCHA Orchestration]
2. [task]
3. [task]
...

What I Learned

Writing this comparison taught me something I didn’t expect: ATLAS + GOTCHA was already doing spec-driven development before the term existed. The GOTCHA prompt IS a specification. The ATLAS checklist IS the design phase. The “What We Adjusted” section in articles 5 and 6 IS the review step.

The difference is that SDD gave these practices a name, built tooling around them, and got the industry to converge on a shared vocabulary. That matters. A practice without a name is harder to adopt, harder to teach, and harder to evolve.

ATLAS + GOTCHA brings something SDD doesn’t have yet: architecture-first thinking. Most SDD tools start from features and let architecture emerge from the plan stage. ATLAS forces you to think about data flows, integrations, and failure modes before you write a single user story. For enterprise systems — the kind I build every day — that architectural thinking is the difference between a system that works in a demo and one that works in production.

The best approach? Use both. Start with a user story (SDD). Run it through ATLAS (architecture). Format the result as GOTCHA (prompt). Break it into tasks (SDD). Let the AI generate. Review and adjust.

Structured thinking + structured prompts + structured execution. That’s what works.

A Word of Caution

AI multiplies your coding speed. That’s real. What used to take a day takes an hour. But speed without direction is just faster chaos.

The planning phase — ATLAS, SDD Specify, whatever you call it — is not optional overhead. It’s the thing that makes the speed useful. Skip it, and you’ll spend the time you saved fixing hallucinated architectures, reverting wrong assumptions, and debugging code that solves a problem you didn’t actually have.

I’ve seen it happen. A developer generates 2,000 lines of code in 30 minutes. Then spends three days fixing it because the AI guessed the database schema, invented an auth flow nobody asked for, and used a library that doesn’t exist in the project. Net productivity: negative.

The frameworks in this article — ATLAS, GOTCHA, SDD — exist because the planning phase is more important now than it was before AI. Not less. When you could write 50 lines per hour, a wrong decision cost you an afternoon. When AI writes 500 lines per hour, a wrong decision costs you a week of cleanup.

Use AI as the powerful tool it is. But know exactly what you want before you ask it to build. The 15 minutes you spend thinking will save you days of correcting.

This Is Not Waterfall

Too much documentation vs just enough

Before someone reads this and thinks “so we’re back to Big Design Up Front” — no. This is not waterfall. Nobody is writing 200-page requirements documents or spending three months in an analysis phase before writing a line of code.

ATLAS takes 15 minutes. A GOTCHA prompt takes 10. An SDD spec for a feature takes 30. That’s an hour of structured thinking — inside a sprint, not before it. You still iterate. You still ship every two weeks. You still change direction when the business needs it.

The difference from classic agile is the artifact. Agile said “working software over comprehensive documentation.” And for years that became an excuse to document nothing. But that interpretation was always wrong — and now it’s a fatal mistake. AI needs clear instructions to generate useful code. Without documentation, without specs, without structured prompts, the AI guesses. And it guesses badly.

Documentation is more important now than before AI. Not less. A GOTCHA prompt is not a 50-page spec. It’s a one-page contract between you and the AI — just enough structure to get useful output, no more. But it is documentation. And without it, AI speed works against you.

Want to be agile? Great. Lean works: eliminate waste, deliver value, continuous improvement. That fits with everything this series proposes. But if you use Scrum, you need to adapt the philosophy. The agile manifesto was written in 2001, when humans wrote every line of code. In 2026, AI writes most of the code — and AI doesn’t work with post-its and hallway conversations. It needs written specs, explicit context, and clear rules. This isn’t going back to waterfall. It’s updating what “agile” means when your pair programming partner is a machine.

Think of it this way: you wouldn’t tell a new developer “just build the feature, figure it out” without a brief conversation about the approach. ATLAS + GOTCHA is that conversation — but written down, so the AI (and your future self) can refer to it.

This doesn’t replace iteration, sprints, or continuous delivery. It replaces the moment where you open the AI tool and type a vague prompt. That moment — between “I know what I want” and “the AI generates code” — is where these frameworks live.

If this series helps you, consider buying me a coffee.

This is article 9 of the ATLAS + GOTCHA series. Previous: Your 90-Day Roadmap.

Sources: