How to Scaffold a New Project with AI

Starting a FastAPI and Postgres service for veterinary clinics should take an afternoon. Instead it takes three days of decisions: folder layout, config loading, database session handling, migration tool, test harness, and a health check that everyone forgets until deployment. By the time the first endpoint works, the interesting part of the business problem has gone cold.

This workflow uses the model to lay the boring foundation fast, without letting it design your domain for you. You stay in charge of the spec; the AI produces the throwaway scaffolding, the config wiring, and the test stubs. The output is a service that boots, connects to a database, and passes one honest test before you write a line of business logic.

The Skeleton You Are Building

A running service with a clean folder tree, environment-based configuration, a database connection, one migration, a health endpoint, a test that hits it, and CI stubs for lint and tests. Nothing is clever. The goal is a floor you can stand on, so every later commit adds behaviour rather than plumbing.

Step 1: Write the Spec Before the Code

A scaffold inherits every ambiguity in the spec. Spend the first prompt forcing those decisions into writing.

You are a senior Python engineer. I am starting a FastAPI and Postgres service for veterinary clinics. Before writing any code, produce a one-page spec covering:
1. The 5 core entities and their key fields.
2. The 6 API endpoints for a first release.
3. The non-functional needs: auth, audit logging, and data sensitivity.
4. The 3 decisions I must make now versus later.
Ask me up to 5 clarifying questions and wait for answers. Do not generate code yet.

You get a spec you can paste into the repo and a short list of decisions to make before scaffolding. For a vet service those decisions usually include multi-clinic data isolation and whether clinical notes are encrypted at rest.

Step 2: Choose the Folder Layout

The tree decides how painful the next year is. Make the model justify a layout rather than paste a template.

Propose a folder layout for this FastAPI and Postgres service that keeps API routes, domain logic, database access, and configuration separate.
Give the tree as plain indented text. For each top-level folder, explain in one line what belongs there and what must never go there.
Then state the trade-off between this layout and a simpler flat layout, and tell me which you recommend for a 3-person team.

You get a layout with reasons attached, so you can defend it in review. Separating routes, services, and repositories is what keeps a small service from turning into one 800-line file by month four.

Step 3: Generate the First Runnable Slice

Generate the smallest thing that runs end to end. A service that boots and answers one endpoint is worth more than a perfect module that nothing imports.

Write the minimal runnable slice for this service:
1. A FastAPI app with a GET /health endpoint that returns a status and a version.
2. The main file that starts the app.
3. A requirements list with pinned major versions.
4. A README section with the exact commands to install and run it locally.
No business endpoints yet. The service must boot with: uvicorn app.main:app --reload

You get a service you can start in one command. Booting early proves the toolchain is correct before you add the complexity that hides environment problems.

Step 4: Add Configuration and Environment Handling

Hardcoded connection strings are the first thing to bite you. Centralise configuration now.

Add configuration handling to the service:
1. A settings module that reads values from environment variables, including the Postgres connection URL, log level, and an API key placeholder.
2. A .env.example file listing every variable with a safe placeholder value.
3. Validation that fails fast at startup if a required variable is missing.
4. A rule that no secret ever appears in source control.
Never print the connection string in logs.

You get a configuration layer that fails loudly at boot instead of quietly at runtime. Failing fast on a missing variable saves the debugging session where you discover the database URL was never set.

Step 5: Scaffold Data Models and Migrations

Wire the database before the endpoints, so later work has somewhere real to read and write.

Scaffold the database layer for a veterinary clinic service:
1. SQLAlchemy models for Owner, Pet, Appointment, VisitNote, and Clinic.
2. A database session dependency for FastAPI.
3. An Alembic setup with one initial migration that creates all five tables.
4. A single repository function that returns a list of appointments for a clinic.
Keep relationships explicit. Use UUID primary keys. Add created_at and updated_at to every table.

You get models, a session, and one real migration. Running the initial migration on a fresh database is the moment the scaffold stops being a mock and becomes a service.

Step 6: Set Up Tests, Lint, and CI Stubs

A scaffold without a test gate invites drift. Add the guardrails while the project is still small.

Finish the scaffold with developer guardrails:
1. One pytest test that calls GET /health and asserts a 200 response.
2. A lint and format configuration using widely used defaults.
3. A CI workflow stub that runs lint and tests on every push.
4. A short CONTRIBUTING note describing how to run tests locally.
Keep the test honest: it must actually start the app, not mock it.

You get a passing test suite and a CI stub you can enable when you push. One honest integration test that boots the app catches more wiring mistakes than a dozen mocked unit tests.

Scaffold Completion Checklist

• A one-page spec with entities, endpoints, and explicit decisions.
• A folder layout with a stated reason for each top-level directory.
• A service that boots with a single uvicorn command.
• Configuration read from environment variables with fail-fast validation.
• A .env.example with no real secrets.
• Models, a database session, and one applied migration.
• One honest integration test, plus lint and CI stubs.

Mistakes That Cost You Later

Mistake 1 — letting the model invent your domain. A generated model will happily add fields you never asked for and miss the one you need. Review the entity list against your own spec, field by field.

Mistake 2 — scaffolding ten endpoints at once. Broad scaffolds hide broken wiring. Build one slice that runs, then extend.

Mistake 3 — committing a real connection string. Ask for a .env.example, add .env to gitignore, and scan the diff before the first push.

Mistake 4 — a test that mocks everything. If the health test does not boot the app, it will pass while the app fails to import. Keep at least one end-to-end test.

To decide what belongs in the architecture before you code, read code versus architecture prompts. When you hand the repo to a teammate, our codebase explanation workflow speeds up onboarding, and for model-side settings see ChatGPT coding settings.

The First Runnable Slice

Here is the shape of the slice from Step 3, so you can see how little is needed before the service boots.

app/
  main.py
  core/config.py
  api/routes/health.py
tests/test_health.py
requirements.txt
.env.example
README.md

main.py
  from fastapi import FastAPI
  app = FastAPI(title="Vet Clinic Service", version="0.1.0")

health.py
  @router.get("/health")
  def health():
      return {"status": "ok", "version": "0.1.0"}

run: uvicorn app.main:app --reload

Nine lines and a folder tree. Everything after this is additive, which is exactly the point: a scaffold should make the next commit easier, not more frightening.

Developer Questions

Should I let the model pick my framework versions? Let it set a baseline, then pin versions you have tested. Unpinned scaffolds break silently when a dependency ships a breaking change.

Is FastAPI overkill for a small service? For a service with async database access and typed request models, no. For a single cron job, a plain script is simpler.

How much of the scaffold should be AI-written? The plumbing can be. The domain logic, the data isolation rules, and anything touching patient data should be written and reviewed by you.

When do I stop scaffolding and start building? When the app boots, the test passes, and the migration runs against a real database. That is your signal to switch to features.

Sources & Notes

Folder conventions, fail-fast configuration, and migration-first setup are standard software practice; the prompts and sequencing here are our own, reviewed on 2026-10-09. Never paste production credentials or real patient data into a model, always treat generated code as untrusted until reviewed, and confirm your handling of clinical data against the regulations that apply to veterinary records in your region.