In Lesson 1, you experienced why vibe coding fails: context loss, assumption drift, and pattern violations compound until your AI produces unusable output. Specifications solve this by giving Claude the complete picture upfront.
But not all specifications are created equal. Some are planning artifacts you throw away after implementation. Others become living documentation that evolves with your codebase. And at the experimental frontier, some teams treat specifications as the only artifact worth maintaining, regenerating code on demand.
Understanding where you operate on this spectrum helps you calibrate your effort. You don't need enterprise-grade living documentation for a weekend project. But you also shouldn't throwaway specs for a system your team will maintain for years.
Let's examine each level.
You write the spec. Claude implements it. You move on.
This is where most practitioners operate, and for good reason. For 80% of tasks, the specification served its purpose the moment Claude finished implementing it. The spec prevented vibe coding, ensured Claude had complete context, and resulted in working code.
After that? The spec becomes historical record at best, garbage at worst.
Benefit: Zero maintenance overhead. Write once, implement once, done.
Cost: Six months later, when you need to modify the feature, you have no specification. You're reading code to understand intent, which is exactly the problem specifications solve.
Claude writes it. You publish it. The spec gets filed somewhere you'll never look again. This is perfectly appropriate for a one-time deliverable.
Both specification and code are maintained artifacts.
When you work with a team, specifications become documentation. A new analyst joining in month six shouldn't need to reverse-engineer your report methodology from the final document. They should read the spec and understand how to update it.
Benefit: Specifications serve as onboarding documentation, architectural decision records, and implementation guides. When requirements change, you update the spec first, then the code, maintaining alignment.
Cost: Double maintenance burden. Every code change potentially requires a spec change. Specs and code can drift out of sync if discipline lapses.
Spec-Anchored only works if you enforce the discipline:
When teams adopt Spec-Anchored without this discipline, they get the worst outcome: outdated specs that actively mislead readers, combined with maintenance overhead that provides no value.
The spec from Level 1 becomes a living document—updated quarterly as the AI landscape evolves:
When you later need to add a new tool to the comparison, you:
An analyst joining the team reads spec.md and understands the report methodology without reverse-engineering the final document.
The specification is the primary artifact. Code is regenerated on demand.
This is the frontier. Companies like Tessl are exploring a world where you never edit code directly. You edit specifications, and AI regenerates the implementation. Code becomes a build artifact, like compiled binaries.
Think about it: if Claude can generate code reliably from specifications, why maintain code at all? Code has bugs, requires refactoring, accumulates technical debt. Specifications express intent directly.
In this model:
Here's where Spec-as-Source breaks down in practice:
Identical specifications do not produce identical code.
Ask Claude to implement the same spec twice. You'll get functionally equivalent but syntactically different implementations. Variable names differ. Control flow varies. Comments appear or disappear.
For production systems, this creates problems:
This isn't a new challenge. Model-Driven Development (MDD) promised the same transformation in the 2000s: write models, generate code, never touch implementation.
MDD failed to achieve mainstream adoption for the same reasons Spec-as-Source struggles:
AI-powered generation is more flexible than MDD code generators, but the determinism problem remains unsolved.
Despite challenges, Spec-as-Source makes sense for:
For a production web application with years of expected maintenance? Spec-Anchored remains the safer choice.
Most practitioners should default to Spec-First and graduate to Spec-Anchored when:
Reserve Spec-as-Source experimentation for:
Think of these levels as a maturity spectrum you can adopt gradually:
Week 1: Start with Spec-First. Write specs before asking Claude to implement. Experience the improvement over vibe coding.
Month 1: For projects you'll maintain, try Spec-Anchored. Keep specs alongside code. Update specs when requirements change.
Later: When you have strong test coverage and understand the trade-offs, experiment with Spec-as-Source for appropriate use cases.
You don't need to commit to one level for all projects. A solo weekend project is Spec-First. Your team's core product is Spec-Anchored. That AI-generated API client you regenerate weekly might be Spec-as-Source.
Prompt 1: Level Classification for Real Projects
What you're learning: This prompt uses a concrete project with clear characteristics. Claude's analysis reveals how team size, maintenance horizon, and documentation needs map to SDD levels. Notice how "8 developers" and "onboarding" push toward Spec-Anchored.
Prompt 2: Trade-off Analysis
What you're learning: The same methodology applies differently based on context. Scenario A's "learning exercise" suggests Spec-First (or skip specs entirely). Scenario B's "onboard contractors" changes everything—even under time pressure, Spec-Anchored provides future value.
Prompt 3: Spec-as-Source Reality Check
What you're learning: Spec-as-Source sounds appealing in theory. This prompt surfaces practical issues: determinism problems breaking git workflows, debugging challenges when generated code varies, and edge cases requiring manual patches that get overwritten on regeneration.