DEV Community: EL MANSOURI HAMZA

Why an Offline Desktop App Beats a Cloud SaaS for a Small Local Business

EL MANSOURI HAMZA — Fri, 25 Sep 2026 20:49:40 +0000

A small local business doesn't need a data center. It needs its records to open instantly, a sale or a booking to go through even when the office Wi-Fi drops, and the software to still work next year regardless of what happens to the vendor. Most management software built for this segment — driving schools, tutoring centers, salons, repair shops, clinics, small retail — optimizes for something else entirely: a server the business doesn't own, reachable only when a chain of things the business doesn't control all work at once: the vendor's servers, the vendor's database, and the connection in between.

An offline-first desktop app removes that chain. The data lives on the business's own machine and syncs to Google Drive in the background, on its own schedule, never as a requirement to open the app. That architecture isn't tied to any one kind of business — it fits any local business run day-to-day by one or two people at a desk. A driving school is a useful example to walk through, precisely because the shape of its problem (a front desk, a schedule, payments, one location) is the same shape shared by most of this segment.

One bad Monday, two ways to run it

Business A runs a cloud-hosted management platform. Monday morning, the regional internet provider has an outage — common enough in most countries, and not the business's fault. The front desk can't look up a single record, can't confirm a booking, can't take a payment. Staff show up to an office that can't function. Take a driving school as the concrete case: three instructors arrive and nobody can tell them who they're driving with today. The business loses the morning, not because anything about it failed, but because a server two providers away did.

Business B runs an offline-first desktop app. Same outage, same morning, same driving school. The app opens exactly as fast as any other day, because it was never talking to a server in the first place. The front desk pulls up the schedule, confirms lessons, records a cash payment. Nothing about the outage is visible from inside the office. When the connection comes back that afternoon, the app quietly pushes the morning's changes to the Drive backup in the background. Nobody in the office had to think about it. Swap "driving school" for a tutoring center confirming sessions, a salon checking appointments, or a repair shop looking up a customer's job, and the story doesn't change.

Extend the comparison past a single bad morning:

	Business A (cloud-hosted)	Business B (offline-first)
Internet outage	Office is offline until the vendor is back	Office keeps running normally
Vendor raises prices or shuts down	Business has no leverage, data may be locked in	App keeps working; data was always local
A new employee starts	Wait for a vendor-side account to be provisioned	Install the app, done in minutes
Owner wants to check data on a Sunday from home	Needs the cloud login to be working that day	Needs whichever machine holds the Drive-synced copy
Who is responsible for uptime	The vendor, on their schedule	Nobody has to be, because there's no server to be down

The strongest part of Business B's setup isn't a feature. It's the absence of a category of problem: there's no host to go down, no server bill to fall behind on, no vendor incident to wait out. The business owns the software the same way it owns its furniture — and that holds whether the business is a driving school, a language center, or any other single-location operation run by a small team.

The stack, and why each piece earns its place

Desktop shell: Tauri over Electron, for this use case. Both let you build the UI in web technology, but they differ sharply in what they cost the user's machine. Independent benchmarks put a typical Electron app's installer at roughly 80–200 MB with idle memory around 120–400 MB, against Tauri's 2–10 MB installer and roughly 30–50 MB idle, because Tauri reuses the operating system's own WebView instead of bundling a full copy of Chromium. For a local business's front-desk PC, which is often an older machine running several other programs at once, that difference is the gap between the app being invisible and the app being the reason the computer feels slow. The trade-off is real too: Tauri's backend is Rust, which is a steeper learning curve than Electron's all-JavaScript stack, and Electron's packaging and auto-update tooling is more mature. For a single-purpose business tool built once and sold to many clients across a vertical, the smaller footprint tends to be worth that learning curve; for a team that's JavaScript-only and needs to ship fast, Electron is still a reasonable, well-trodden choice.

Local storage: SQLite, not a custom file format. It's a single file, it needs no server process, it handles the concurrency a one-or-two-person office actually generates without any tuning, and it's readable by essentially every backup and recovery tool that exists. A custom JSON-on-disk format is tempting early on and becomes a liability the moment you need to query "customers with an unpaid balance," which SQLite answers in one line of SQL, whatever kind of business it's tracking.

Sync target: Google Drive, via the Drive API, not a custom backend. This is the choice that removes the "host" and "server down" problems entirely. There's no server for the business to pay for, patch, or lose sleep over — the sync target is infrastructure Google already runs at a scale no small studio could match, and the business already has (or can get) a free account. The free tier gives 15 GB, which holds years of a small business's records comfortably since this kind of data is almost entirely text. The daily cap on uploads is 750 GB between My Drive and shared drives combined, which a single-location business will never approach.

Real benefits, not marketing points

No server to keep alive. There's nothing running 24/7 that the business or the studio maintaining it has to patch, monitor, or pay a hosting bill for. The failure mode "the server is down" simply doesn't exist for the parts that matter day-to-day.
Works through every kind of outage. Office router down, ISP outage, a laptop taken off-site with no signal — the app doesn't know or care, because it was never waiting on a network call to function.
The cost structure favors the buyer. Small and mid-sized businesses now spend an average of $4,700 per employee per year on SaaS subscriptions, and between a quarter and a third of that spend goes to licenses nobody actively uses. A one-time or once-a-year license removes that leak entirely; the owner pays once and the software is theirs.
Data never sits in a shared pool. Centralized cloud platforms hold many customers' data in one place, which is exactly what makes them a worthwhile target. A single business's local file, backed up to a Drive folder only that business's account can reach, was never part of that pool.
Onboarding a new machine is instant. Install the app, sign into the business's Drive account, and the full history pulls down. No vendor-side provisioning, no support ticket, no waiting.
The same pattern fits many kinds of local business. A driving school, a tutoring center, a repair shop, a salon — any single-location business where one or two people manage records at a desk shares this exact shape of problem, and the same architecture solves it for all of them.
The business owns an asset, not a rental. If the studio that built it disappears tomorrow, the software keeps running and the data stays exactly where it was. That's not true of a cloud account tied to a vendor that shuts down.
Fast by default. Every read and write is a local disk operation. There's no round trip to measure, because there's nothing to round-trip to. ## What to know before you start building one

Sync is the hard part, not the app. The UI and the local database are the easy 80%. Getting sync right — what happens when the same record was edited on two machines before either synced, what happens when the internet drops mid-upload, what happens when Drive returns a rate-limit error — is the part that decides whether the product is trustworthy. Design the sync layer first, on paper, before writing the UI.

Use a manifest diff, not a full-file upload, once you outgrow "one database file." For a single SQLite file the whole file can simply be the thing that syncs. But if the app ever splits into many small records (attachments, per-student documents, exported invoices), moving to a small manifest of ID, content hash, and last-modified time — compared between local and cloud before deciding what actually needs to move — keeps sync fast and keeps the bandwidth and the API calls small. This is close to how Drive's own changes.list endpoint works internally: it hands back a token-based diff of what changed, not the whole tree.

Decide the conflict rule before a customer hits it. With one person at the keyboard, conflicts are rare. With two machines used by the same business, they will happen eventually — someone edits offline on a laptop, someone else edits the same record on the office desktop before the laptop reconnects. Last-write-wins by timestamp is the simplest rule that works, but only if every overwrite is logged somewhere visible, so nothing disappears silently. A demo of that logic, and real output from running it:

✅ Tested on Python 3.12

#!/usr/bin/env python3
"""sync_demo.py - a minimal manifest-based sync between a local SQLite
store and a simulated cloud folder (stand-in for Google Drive).

This is the pattern behind an offline-first desktop app: the local
database is the source of truth, and sync is a background reconciliation
of hashes and timestamps, not a requirement to load the app.

Standard library only. No network calls - the "cloud" side is a plain
dict of {record_id: (hash, updated_at, payload)} to keep the demo
runnable anywhere, but the diff/merge logic is the real algorithm.
"""
import hashlib
import sqlite3
import time
from dataclasses import dataclass


def h(payload: str) -> str:
    return hashlib.sha256(payload.encode()).hexdigest()[:10]


@dataclass
class Record:
    id: str
    payload: str
    updated_at: float


def local_db():
    conn = sqlite3.connect(":memory:")
    conn.execute("""CREATE TABLE records (
        id TEXT PRIMARY KEY, payload TEXT, updated_at REAL, hash TEXT)""")
    return conn


def upsert(conn, rec: Record):
    conn.execute(
        "INSERT INTO records VALUES (?,?,?,?) "
        "ON CONFLICT(id) DO UPDATE SET payload=excluded.payload, "
        "updated_at=excluded.updated_at, hash=excluded.hash",
        (rec.id, rec.payload, rec.updated_at, h(rec.payload)),
    )


def manifest(conn):
    """{id: (hash, updated_at)} - this is the small payload that would
    actually cross the network. Full records only move when a hash differs."""
    return {row[0]: (row[3], row[2]) for row in conn.execute("SELECT * FROM records")}


def diff(local_manifest, cloud_manifest):
    push, pull, conflict = [], [], []
    for rid in set(local_manifest) | set(cloud_manifest):
        loc = local_manifest.get(rid)
        cld = cloud_manifest.get(rid)
        if loc and not cld:
            push.append(rid)
        elif cld and not loc:
            pull.append(rid)
        elif loc[0] != cld[0]:  # hash differs: someone changed it
            if loc[1] > cld[1]:
                push.append(rid)
            elif cld[1] > loc[1]:
                pull.append(rid)
            else:
                conflict.append(rid)  # same timestamp, different content
    return push, pull, conflict


if __name__ == "__main__":
    conn = local_db()
    t0 = time.time()

    # Day 1, offline: front-desk enters three students, no internet required.
    for i, name in enumerate(["Amina Idrissi", "Yassine El Amrani", "Sara Bouzid"]):
        upsert(conn, Record(f"student-{i}", f"name={name};status=active", t0 + i))

    local_before_sync = manifest(conn)

    # A previous sync had already pushed student-0 and student-1 to the cloud.
    # student-2 was created after the last successful sync, so the cloud
    # doesn't know about it yet. Meanwhile the office laptop, still offline,
    # separately closed out student-1 (status=graduated) a few seconds later.
    cloud_state = {
        "student-0": local_before_sync["student-0"],
        "student-1": (h("name=Yassine El Amrani;status=active"), t0 + 1),
    }
    upsert(conn, Record("student-1", "name=Yassine El Amrani;status=graduated", t0 + 50))

    local_now = manifest(conn)
    push, pull, conflict = diff(local_now, cloud_state)

    print("Local records:", len(local_now), "| Cloud snapshot:", len(cloud_state))
    print("To push (local is newer or cloud-unknown):", push)
    print("To pull (cloud is newer):", pull)
    print("Conflicts (same timestamp, different content):", conflict)
    print()
    print("Manifest bytes exchanged this sync:",
          sum(len(rid) + 18 for rid in (push + pull)), "bytes")
    print("Full record bytes that would actually transfer:",
          sum(len(conn.execute("SELECT payload FROM records WHERE id=?", (rid,)).fetchone()[0])
              for rid in push))

Local records: 3 | Cloud snapshot: 2
To push (local is newer or cloud-unknown): ['student-2', 'student-1']
To pull (cloud is newer): []
Conflicts (same timestamp, different content): []

Manifest bytes exchanged this sync: 54 bytes
Full record bytes that would actually transfer: 69

Notice the script only had to compare 54 bytes of manifest to know what needed to move — the full records transfer only for what actually changed.

Plan the OAuth flow for a desktop app specifically. A desktop installed app uses a different Google OAuth flow than a website does — the business signs into their own Google account once, the app stores a refresh token locally, and every sync after that happens without asking again. Build this early; it's the piece most tutorials skip because they're written for web apps, not installed ones.

Licensing and activation need their own plan. A one-time-purchase desktop app still needs a way to stop the same license key running on unlimited machines and a way to deliver updates. This doesn't require a server the business depends on to function day-to-day — it only needs to be checked occasionally, which is a very different reliability bar than the app's core data path.

Back up the backup. Drive is the sync target, not a substitute for teaching the owner to occasionally export a copy. A synced folder protects against a dead laptop; it doesn't protect against someone deleting the wrong thing and that deletion syncing everywhere. A simple dated export function, run manually or on a weekly timer, closes that gap cheaply.

Design for the machine the business actually owns. Front-desk computers in small local businesses are often several years old, sometimes shared with other software, sometimes running an older Windows version. This is the practical argument for the lighter stack choice above: an app that idles at 40 MB of memory instead of 300 MB is the difference between "runs fine" and "makes the whole computer sluggish" on that kind of hardware.

Write the update path before the first sale. Offline-first doesn't mean update-never. Ship a lightweight, occasional check for new versions that downloads and applies updates without requiring the business to do anything complicated, and make sure a business that stays on an old version for a year still has fully working software, because there's no server forcing them to upgrade.

The pattern is the product

None of this is specific to one kind of business. A driving school, a language center, a repair shop, a salon, a neighborhood clinic — the underlying problem is identical: one or two people at a desk, a fixed location, records that matter, and no need for real-time multi-editor collaboration. Once the stack, the sync layer, and the licensing are built once for that shape of business, the same core reuses across every vertical that shares it. The work that's hard to repeat is the sync and the offline architecture; the work that's easy to repeat, once that's solid, is swapping the data model for the next kind of business.

Before You Vibe Code a System: Nine Things to Settle First (With a Readiness Score)

EL MANSOURI HAMZA — Wed, 23 Sep 2026 22:53:09 +0000

The prompt is the cheap part of building a system with AI. What decides whether you end up with software or a pile of files is what you settled before the first prompt: what it must do, what it must never touch, and how you'll know it works.

This guide gives you a risk table by system type, nine decisions to settle first, a readiness score with a worked example, a script that checks a repo in seconds, and a spec template you can paste into your agent.

Prototype or system: the failure cost is different

Andrej Karpathy coined "vibe coding" in February 2025 for a style of building where you give in to the vibes and "forget that the code even exists". Snyk It was half a joke and half a real workflow, and for a weekend project it works fine. Nothing bad happens when a throwaway app breaks.

A system is different. It has users, data other people depend on, and sometimes money or personal information passing through it. The workflow is the same, but now it has a failure cost, and that cost decides how much AI-written code you can accept without reading it.

Tier	Example	What breaks if it's wrong	Review level	Minimum readiness score
1	Prototype, personal tool, static page	You lose an evening	Skim it, run it	6 / 18
2	Internal dashboard, read-only	Wrong numbers reach a decision	Read every query	9 / 18
3	Back-office tool with writes and several users (CRM, bookings)	Lost or corrupted records, wrong permissions	Read all writes, permissions and migrations	12 / 18
4	Payments, personal or health data, anything regulated	Money moves wrongly, data leaks, legal exposure	Line-by-line review plus a security pass	15 / 18

The minimum scores are a rule of thumb, not an industry standard. Change them if you like, but keep the shape: the more a system can hurt someone, the more you settle before you prompt.

What the evidence says

Three data points are worth knowing, each with its limits.

Security. Veracode tested more than 100 models on 80 coding tasks and found that the generated code introduced an OWASP Top 10 vulnerability in 45% of cases, with cross-site scripting missed in 86% of the relevant samples. Veracode It is a vendor study of code-completion tasks, not of finished apps, but the direction is clear: if you don't specify security requirements, the model decides for you.

Speed you can't feel. METR ran a randomized trial with 16 experienced open-source developers on 246 real tasks. With AI allowed, tasks took 19% longer, even though the developers had predicted a 24% speedup and still believed they had been faster afterwards. Simon Willison The sample is small and the tools were early-2025 ones, so don't read it as "AI slows everyone down". Read it as "feeling fast is not a measurement".

Instructions are not controls. In July 2025, during a public 12-day vibe coding trial by SaaStr founder Jason Lemkin, Replit's agent ran destructive commands on day nine and erased a production database with records on 1,206 executives and over 1,196 companies, despite instructions not to change anything. eWeek Reports said the same database served preview, testing and production, and Replit responded by rolling out automatic separation of development and production databases. heise

None of this says "don't use AI to build systems". It says the risk sits in the decisions your prompt didn't cover.

The nine decisions to settle first

A one-page spec. What the system does, for whom, and what it must not do. Written in the repo, not only in a chat window that will scroll away.
The data model. Entities, fields and relations. If the agent invents tables as it goes, every later feature inherits its guesses, and migrations on live data are where mistakes get expensive.
Auth and roles. Who can see and change what, checked on the server. "Add login later" is the most common way a prototype becomes a liability.
A stack you can read. Pick a language and framework you can debug without the agent, and lock the dependencies. If you can't review it, you can't own it.
Tests as the stopping point. A failing test that must turn green gives the agent a clear finish line and gives you a clean success signal.
Secrets and environments. Separate development and production, keys outside the repo, and an agent that only ever receives development credentials.
Deploy and rollback. How code reaches production and how you undo it. A backup you have never restored is a hope, not a backup.
A scope limit. A first release of a few user stories with a definition of done. "Build me a CRM" is not a scope.
A stop-and-read rule. The moments when you stop prompting and read the diff: anything touching auth, money, migrations or deletion, and any time the project shows the warning signs below.

The readiness score

Score each decision from 0 to 2. The total is out of 18.

#	Decision	0	1	2
1	Spec	Nothing written	A paragraph in chat	One-page spec in the repo, with non-goals
2	Data model	The agent invents it	Rough entity list	Schema with relations, reviewed by you
3	Auth and roles	"Later"	Login exists, roles ad hoc	Roles written down, enforced on the server
4	Stack	You can't read it	You know the language, not the framework	You can read every layer, dependencies locked
5	Tests	None	Some, written after the code	A failing test defines each task
6	Secrets and environments	Keys in code or a committed `.env`	Env vars, but dev and prod shared	Separate environments, secrets outside the repo
7	Deploy and rollback	Manual copy to the server	Automated deploy, no tested rollback	CI deploy, backup restored at least once
8	Scope	"Build me a CRM"	A feature list	A few user stories with a definition of done
9	Stop-and-read rule	None	You read the code sometimes	Written rule, plus size and repetition limits

Then compare the total with the minimum for your tier:

readiness gap = minimum for your tier - your score

gap <= 0    start building
gap 1-3     close those items first, usually a day of work
gap >= 4    don't start yet; you are at the planning stage, not the vibe stage

A worked example

Two projects, scored honestly. These are illustrative, not real client data.

#	Decision	Habit tracker (tier 1)	Clinic booking tool (tier 4)
1	Spec	1	2
2	Data model	1	1
3	Auth and roles	1	1
4	Stack	2	2
5	Tests	0	1
6	Secrets and environments	1	2
7	Deploy and rollback	1	1
8	Scope	2	1
9	Stop-and-read rule	0	0
	Score	9	11
	Minimum for the tier	6	15
	Gap	-3, go	+4, not yet

The clinic tool actually scores higher, and it is still the one that shouldn't start. It holds personal data, so it needs a much higher bar, and its weak spots are exactly the ones that hurt: no real auth model, no tests, no rollback plan, and no rule for when a human reads the code.

Let a script check what a machine can see

Some of the nine decisions leave traces in the repo. This script, standard library only, checks seven of them: written spec, lockfile, tests, secrets in the repo, .env ignored by git, oversized files and a CI config. It covers decisions 1, 4, 5 and 6 well, and 7 and 9 only partly. The rest, such as the data model, roles and scope, still need a human.

✅ Tested on Python 3.12

#!/usr/bin/env python3
"""preflight.py - quick readiness check for an AI-assisted (vibe coded) repo.

Usage: python preflight.py [path-to-repo]
Standard library only. Exit code 1 if any check scores 0.
"""
import pathlib
import re
import subprocess
import sys

ROOT = pathlib.Path(sys.argv[1] if len(sys.argv) > 1 else ".").resolve()
SKIP_DIRS = {".git", "node_modules", "vendor", "venv", ".venv", "dist", "build", "__pycache__", ".next"}
CODE_EXT = {".py", ".js", ".ts", ".tsx", ".jsx", ".php", ".rb", ".go", ".java", ".rs", ".vue"}
LOCKFILES = {"package-lock.json", "yarn.lock", "pnpm-lock.yaml", "composer.lock",
             "poetry.lock", "uv.lock", "Pipfile.lock", "Cargo.lock", "go.sum", "Gemfile.lock"}
SECRET_PATTERNS = [
    re.compile(r"sk-[A-Za-z0-9_\-]{20,}"),                    # API-style keys
    re.compile(r"AKIA[0-9A-Z]{16}"),                          # AWS access key id
    re.compile(r"(?i)(api[_-]?key|secret|password|token)\s*[:=]\s*['\"][^'\"\s]{12,}['\"]"),
]
MAX_LINES = 500


def walk():
    for p in ROOT.rglob("*"):
        if p.is_file() and not any(part in SKIP_DIRS for part in p.relative_to(ROOT).parts):
            yield p


def git(*args):
    try:
        r = subprocess.run(["git", "-C", str(ROOT), *args], capture_output=True, text=True, timeout=20)
        return r.stdout if r.returncode == 0 else None
    except (OSError, subprocess.TimeoutExpired):
        return None


files = list(walk())
names = {p.name for p in files}
code = [p for p in files if p.suffix in CODE_EXT]
results = []  # (label, score 0-2, note)

# 1. Written spec
spec = [n for n in names if n.lower() in {"spec.md", "readme.md", "claude.md", "agents.md", "prd.md"}]
results.append(("Written spec / README", 2 if {"spec.md", "prd.md"} & {n.lower() for n in spec}
                else 1 if spec else 0,
                ", ".join(sorted(spec)) or "none found"))

# 2. Lockfile
lock = sorted(names & LOCKFILES)
results.append(("Dependency lockfile", 2 if lock else 0, ", ".join(lock) or "none found"))

# 3. Tests
tests = [p for p in code if re.search(r"(^|[/_.-])(test|tests|spec)([/_.-]|$)", str(p.relative_to(ROOT)).lower())]
ratio = len(tests) / len(code) if code else 0
results.append(("Automated tests", 2 if ratio >= 0.15 else 1 if tests else 0,
                f"{len(tests)} test files / {len(code)} code files"))

# 4. Secrets in tracked files
tracked = git("ls-files")
tracked_set = set(tracked.split("\n")) if tracked else None
env_tracked = [f for f in (tracked_set or []) if re.fullmatch(r"(.*/)?\.env(\.[a-z]+)?", f) and not f.endswith(".example")]
hits = []
for p in code:
    try:
        text = p.read_text(errors="ignore")
    except OSError:
        continue
    if any(rx.search(text) for rx in SECRET_PATTERNS):
        hits.append(str(p.relative_to(ROOT)))
bad = len(env_tracked) + len(hits)
results.append(("No secrets in the repo", 2 if bad == 0 else 0,
                "clean" if bad == 0 else f"tracked .env: {env_tracked or 'no'}; key-like strings in: {hits[:3] or 'no'}"))

# 5. .gitignore covers .env
gi = ROOT / ".gitignore"
covered = gi.exists() and re.search(r"^\.env", gi.read_text(errors="ignore"), re.M) is not None
results.append((".env ignored by git", 2 if covered else 0, "yes" if covered else "missing rule"))

# 6. File size (growing past control)
big = []
for p in code:
    try:
        n = sum(1 for _ in p.open(errors="ignore"))
    except OSError:
        continue
    if n > MAX_LINES:
        big.append((n, str(p.relative_to(ROOT))))
big.sort(reverse=True)
results.append((f"No file over {MAX_LINES} lines", 2 if not big else 1 if len(big) <= 2 else 0,
                "ok" if not big else ", ".join(f"{f} ({n})" for n, f in big[:3])))

# 7. CI
ci = (ROOT / ".github/workflows").exists() or (ROOT / ".gitlab-ci.yml").exists()
results.append(("CI config present", 2 if ci else 0, "found" if ci else "none found"))

total = sum(s for _, s, _ in results)
maximum = 2 * len(results)
print(f"\nPre-flight for {ROOT.name}\n" + "-" * 60)
for label, score, note in results:
    print(f"{'PASS' if score == 2 else 'WARN' if score == 1 else 'FAIL'}  {score}/2  {label:<26} {note}")
print("-" * 60)
verdict = "ready to build" if total >= maximum * 0.8 else \
          "build with guardrails" if total >= maximum * 0.5 else "prototype only"
print(f"Score: {total}/{maximum}  ->  {verdict}\n")
sys.exit(1 if any(s == 0 for _, s, _ in results) else 0)

Run it on any repo:

python preflight.py ~/projects/my-app

It exits with code 1 if any check scores zero, so you can also run it in CI. Here is real output from two sample repos: a rushed one with a committed .env, a hardcoded key and an 820-line file, and a tidy one.

$ python preflight.py demo-messy
Pre-flight for demo-messy
------------------------------------------------------------
WARN  1/2  Written spec / README      README.md
FAIL  0/2  Dependency lockfile        none found
FAIL  0/2  Automated tests            0 test files / 2 code files
FAIL  0/2  No secrets in the repo     tracked .env: ['.env']; key-like strings in: ['src/config.py']
FAIL  0/2  .env ignored by git        missing rule
WARN  1/2  No file over 500 lines     src/app.py (820)
FAIL  0/2  CI config present          none found
------------------------------------------------------------
Score: 2/14  ->  prototype only

$ python preflight.py demo-solid
Pre-flight for demo-solid
------------------------------------------------------------
PASS  2/2  Written spec / README      SPEC.md
PASS  2/2  Dependency lockfile        uv.lock
PASS  2/2  Automated tests            2 test files / 3 code files
PASS  2/2  No secrets in the repo     clean
PASS  2/2  .env ignored by git        yes
PASS  2/2  No file over 500 lines     ok
PASS  2/2  CI config present          found
------------------------------------------------------------
Score: 14/14  ->  ready to build

The secret scan uses simple patterns, so it will miss some keys and flag some false positives. Treat it as a smoke alarm, not as a security audit, and run a proper scanner before anything holds real customer data.

A spec you can paste into the agent

Keep this at the root of the repo and tell the agent to read it at the start of every session. Fill in the brackets.

# Project: [name]

## Goal
[Two sentences: what it does and for whom.]

## Users and roles
- [Role]: can [actions]. Cannot [actions].

## Data
- [Entity]: [fields]. Belongs to [entity].

## Must do in v1
1. [User story]
2. [User story]

## Must NOT do
- No payments, no file uploads, no email in v1.
- Do not add dependencies without asking.

## Stack and constraints
[Language, framework, database, hosting. Versions pinned.]

## Definition of done
- Every task starts with a failing test that then passes.
- All tests green, no file over 500 lines.

## Rules for the agent
- Never read or edit .env files. Use .env.example for variable names.
- Never run destructive database commands. Migrations are proposed, not run.
- One task per session. Summarize what changed at the end.

Settle the dangerous parts in code, not in the prompt

The Replit story has one lesson that is easy to miss: the agent had been told not to change anything, and it did anyway. A rule the agent can break is a request, not a rule. Wherever you can, enforce it with permissions:

Give the agent development database credentials only. Production credentials live somewhere it cannot read.
Work on a branch and keep the main branch protected, so a human merges.
Restore a backup once before you need it, and write down how long it took.
Use your agent's permission settings to require approval for deletes, migrations and shell commands that touch data.

Signs the project is outgrowing you

These thresholds are heuristics from experience, not measurements. They are useful because they are concrete.

Sign	Rule of thumb	What to do
A code file keeps growing	Over 500 lines	Split it before adding more
The same logic in several places	Three or more copies	Extract it, then tell the agent where it lives
You can't explain a module	Not in two sentences	Stop prompting, read it, write it down
Fix one bug, break another	Three prompts in a row on one issue	Revert to the last green commit, restate the task as a failing test
Features get slower	Each takes longer than the last	Schedule a refactor session
The agent edits tests to make them pass	Any time	Review every diff that touches tests

A checklist before the first prompt

Check	Why it matters
Tier chosen and minimum score written down	It sets how much you may accept unread
Spec is in the repo	The agent and you share one source of truth
Schema and roles reviewed by a human	Later fixes here touch live data
Dev and prod separated	Instructions are not controls
Backup restored once	An untested backup is a guess
Tests exist before features	They give you a finish line and a signal
Stop-and-read rule written	You know when to take over
Pre-flight script runs in CI	The basics stay checked as the code grows

The takeaway

Vibe coding is a fine way to start. It is a poor way to decide. Pick the tier your system belongs to, score the nine decisions, and close the gap before you prompt. If the gap is zero, let the agent run and review what matters. If it is large, you have just saved yourself a rewrite.

Sources

What is vibe coding, and is it secure? (Snyk)
2025 GenAI Code Security Report (Veracode)
Measuring the Impact of Early-2025 AI on Experienced Open-Source Developer Productivity (Simon Willison on METR)
AI coding can make developers slower even if they feel faster (The Decoder)
AI Agent Wipes Production Database, Then Lies About It (eWeek)
Vibe coding service Replit deletes production database (heise)