Vibe coding vs spec: the change still has to land in the contract

On 12 September 2026 we ran a live session: Build an App with AI, From Idea to Running Application. The screen looked like classic “vibe coding” — Cursor dark theme, SurveyDesk open, an agent sidebar waiting for the next sentence. The prompt we typed was not “change the iPad UI.” It was: update spec to allow iPad refresh button where it is available on Android but not iPad.

What people mean by vibe coding

Vibe coding is conversational delivery: describe the feeling of the product, let the agent move files, keep prompting until the UI looks right. It is fast, social, and great for discovery. The failure mode is not that the agent is wrong — it is that the only durable record of “what we decided” lives inside a closed tab.

• Intent stays in chat history the next agent cannot reliably read.
• Platform quirks (“Android has refresh; iPad does not”) become tribal knowledge.
• Green demos hide missing acceptance coverage for the new behaviour.
• Regeneration later rebuilds yesterday’s product, not today’s decision.

What Spec-Driven Development changes

In SurveyDesk the left sidebar is not decoration. specs/acceptance holds Gherkin features. specs/adr holds architecture decisions. package.json scripts run execute:specs, regen:parallel, and test:acceptance. On the live stream the terminal already showed six acceptance files passing — lifecycle, form-builder, adaptive-layout, and friends. That suite is the proof surface for whatever the agent changes next.

The live moment: refresh on Android, not on iPad

Product asks often arrive as vibes: “Why can’t I refresh on iPad the way I can on Android?” Pure vibe coding answers by patching the iPad screen until a button appears. Spec-first answers by opening adaptive-layout.feature (or the relevant SHALL) and writing the platform rule where the next agent — and the next human — can find it.

# Illustrative — the durable form of the live ask
Feature: Adaptive operator layout
  Scenario: Refresh control by platform
    Given an operator session on Android
    Then the refresh control SHALL be available
    Given an operator session on iPad
    Then the refresh control SHALL NOT be available
    # After the product decision changes:
    # Then the refresh control SHALL be available on iPad too

Once the feature file (or requirement ID) carries the new rule, implementation and tests follow the contract. If someone later regenerates apps/, the iPad refresh behaviour survives because it was never only a chat suggestion.

Side by side

• Vibe-only: “Add an iPad refresh button.” → agent edits Swift/UI → demo looks fine → next session forgets why Android differed.
• Vibe → spec: “Update the spec so iPad may refresh like Android.” → agent edits acceptance + SHALL → implements → test:acceptance stays green for the new rule.
• Vibe-only source of truth: the model’s memory of the last prompt.
• Spec source of truth: git-versioned specs/ plus executable acceptance.

A practical loop you can steal

1. 01Feel the change in natural language — keep the vibe.
2. 02Aim the agent at the contract: “update the spec / feature / SHALL for …”
3. 03Let the agent implement against the updated IDs.
4. 04Run acceptance (and regenerations) so the suite proves the new behaviour.
5. 05Review the diff on specs/ first — that is the product decision.

Related reading

• Spec-Driven Development — https://suherman.net/articles/spec-driven-development
• Crafted vs AI-generated in a Spec-Driven repo — https://suherman.net/articles/crafted-vs-ai-generated-code
• SurveyDesk specs with Agent On Rails — https://suherman.net/articles/agent-on-rails-surveydesk-specs
• SurveyDesk on GitHub — https://github.com/iman-suherman/survey-desk

Bottom line from the live stream: keep talking to the agent like a human. Just make sure the sentence ends with the contract — because the product has to go back to the spec again.