← mobang.fr

· Vibecoding

The One-Page Spec That Keeps Your AI-Built App Coherent

Before you type your first prompt, write a one-page spec. Not a forty-page requirements document — a single page that says what your app does, for whom, what the data model is, which screens exist, which business rules are non-negotiable, who can see what, and what the app deliberately does not do. Then paste that page at the top of the context in every new AI session.

Why? Because AI optimizes locally. Every prompt, taken in isolation, gets handled well: code comes out, it runs. But the global architecture gets improvised session after session. The classic result after three weeks: duplicated features, contradictory data models, screens that don't talk to each other. It's not that the AI writes bad code — it's that it has zero memory of your past decisions unless you hand them back every time.

The one-page spec is that memory. It's the cheapest, highest-leverage document in your entire project. Here's how to write one, with a complete example.

The problem: AI optimizes locally, your app lives globally

Every session with an AI assistant starts from scratch, or close to it. You ask it to "add cancellation handling," and it delivers clean cancellation handling — built on whatever assumptions it invents in the moment.

In practice, that looks like:

  • Session 1 creates a users table; session 4 creates accounts for the same thing.
  • One screen shows prices with tax included, another without — nobody decided that.
  • The rule "one slot = one booking" exists in a form validation, but not in the API.

None of this is "bad code." Each piece, taken alone, is correct. The assembly is what's incoherent, because nobody — not you, not the AI — was holding the big picture.

What goes in the spec (and nothing else)

One page. Seven blocks. If it overflows, cut.

  • What the app does: two sentences, max.
  • Who it's for: your user types.
  • The data model: 3 to 10 entities and their relations, as a plain list.
  • The main screens or flows: the backbone of the experience.
  • Non-negotiable business rules: what must be true everywhere, all the time.
  • Security: who sees what, who can do what.
  • Out of scope: what the app does NOT do in v1. This block matters as much as the others.

No mockups, no detailed tech stack, no numbered user stories. All of that comes later — it doesn't determine coherence. The spec does.

Example: a one-page spec for a booking app

# Spec — CoachSlots (v1)

## What
A booking app for independent personal trainers.
A coach publishes time slots; a client books one and pays online.

## Who
Solo coaches (one calendar each) and their clients. No gyms, no teams.

## Data model
- Coach: name, email, timezone
- Slot: coach, date/time, duration, price, status (open/booked/cancelled)
- Client: name, email
- Booking: slot, client, payment status, created_at
Relations: a Coach has many Slots;
a Booking links exactly 1 Slot to 1 Client.

## Screens
1. Coach's public calendar (list of open slots)
2. Booking flow (pick slot → client info → payment)
3. Coach dashboard (slots, bookings, cancellations)

## Non-negotiable business rules
- A slot can only be booked once.
- Free cancellation up to 24h before; after that, no refund.
- All times stored in UTC, displayed in the client's timezone.

## Security
- A coach sees only THEIR slots and bookings.
- A client sees only THEIR bookings.
- We store no payment data (delegated to the payment provider).

## Out of scope for v1
- No multi-coach studios, no subscriptions, no mobile app, no reviews.

Read it again: it fits on one page, and yet almost every structural decision is already made. The AI no longer has to guess whether a slot can be booked twice, or how timezones are handled.

Why it works: the AI fills a frame instead of inventing one

A language model always completes what's missing. If the context doesn't say what the central entity is called, it picks a plausible name — not necessarily the same one as yesterday. With the spec at the top of the context, there's nothing left to invent about the foundations: the names, relations, and rules are already there. The AI goes from improvising architect to disciplined executor — exactly the role it's best at.

This isn't purist nostalgia. Andrej Karpathy, who coined the term "vibe coding" in early 2025, was already describing at the AI Ascent 2026 conference the industry's shift from casual coding toward "agentic engineering": methodical rigor is moving back to the center of the game. The upfront spec is its first building block — and the easiest one to lay.

Bonus: this page serves humans too. Six months from now, it's the document that will re-explain your own project to you in two minutes.

How to use it day to day

Three usage rules, no more:

  • Paste it at the top of every session. First message of the chat, or better: in your tool's persistent context file (CLAUDE.md, Cursor rules, project instructions…).
  • The spec wins. If the AI proposes something that contradicts it, you refuse — or you consciously update the spec, then continue. Never the other way around.
  • Update it as you go. A decision made mid-conversation ("actually, cancellations get a 50% refund") goes into the spec the same day. A stale spec is worse than no spec.

The key point: the spec lives in your repo, versioned like code. A SPEC.md at the root, committed. That's it.

Where to start today

Thirty minutes is enough for a first version. In order:

  1. Create a SPEC.md file at the root of your project — even if code already exists.
  2. Write the two "what it does" sentences and "who it's for." If you can't do it in two sentences, that alone is valuable information.
  3. List your entities (3 to 10). If you already have code, open your database and write down what actually exists — including the duplicates you'll discover along the way.
  4. Write down 3 to 5 non-negotiable business rules, and who sees what.
  5. Write the v1 out-of-scope list. Be brutal: everything that's "later" goes there.
  6. Paste the spec at the top of your next AI session, and watch the difference.

It doesn't need to be perfect. An imperfect spec that exists beats a perfect architecture that only lives in your head.