How to actually work with AI when building software

Choose your mode

Most of what follows depends on what you're actually doing. Find the row that fits — not the one that sounds impressive — and read the rest of the page through that lens. These aren't filters; they're orientation.

Recommended starter stacks

Concrete picks for each mode above. Not the only valid answers — but answers that actually work today, and that you can change later without rewriting everything. Skip the ones that don't apply yet.

Move up a row when the current one stops fitting — usually because a hallucinated change made it past you. Don't adopt the heaviest stack on day one. The overhead only pays off when the risk it covers is real.

The stack layers

AI-assisted dev happens in four layers. You don't have to use all of them, but understanding what each layer does helps you choose tools deliberately instead of by hype.

Most teams start with layers 1+2. As work gets bigger, they add layer 3. Once they've been bitten by a hallucinated PR or two, they add layer 4.

Models as a team, not a tool

The 2026 default for serious work isn't "pick the best AI and use it for everything." It's splitting the work across roles, like a small engineering team. The pattern people converge on:

The point isn't to use four different products. It's to think in roles. You can play all four roles with one product if you switch prompts. You can play them with two or three different models. The structure matters more than the brand.

See the glossary on AI team topology and model verification for the underlying concepts.

Three workflow shapes

Most AI-assisted dev work fits one of three shapes. Pick deliberately — using the wrong shape is where most velocity gets lost.

Handoff patterns

The thing that breaks multi-model workflows isn't the models — it's the handoffs. People paste 50k tokens of chat history into the next model and wonder why output drops. The fix is structured handoffs: small, deliberate documents that capture decisions, not conversation.

Each handoff doc is short — under 2k tokens, ideally. The discipline is in summarizing, not in writing more.

Files every repo should have

The single highest-ROI thing you can add to a codebase for AI-assisted work is a repo instruction file at the root. It tells every coding agent how your code actually works — conventions, dependencies, gotchas — so they stop relearning it every session.

A good repo file is short (a few hundred lines max), specific (real examples, not principles), and actively maintained. Bad ones are aspirational and rot. See the glossary on repo instruction files for what good ones look like.

# Acme Dashboard

Stack: Next.js 16 (App Router) + Postgres 16 + Resend.
Deployed to Vercel. Postgres on Neon (preview branches per PR).

## Commands
- npm run dev          # localhost:3000
- npm run typecheck    # must pass before commit
- npm test             # vitest, watch mode by default
- npm run db:migrate   # drizzle, never edit migrations by hand

## Architecture
- App Router only. No /pages directory.
- Server Components by default. Add 'use client' only when needed.
- DB access lives in lib/db/*. Never import drizzle in components.
- All emails go through lib/email/send.ts (wraps Resend).

## Tests
- Co-located: foo.ts -> foo.test.ts.
- New server actions require a test. UI components do not.
- Coverage gate: 70% on lib/, no gate on app/.

## Never
- Don't add a new ORM. We use drizzle.
- Don't introduce client-side data fetching for first paint.
- Don't catch errors silently — log via lib/log.ts and rethrow.

## Style
- Tailwind utility classes, no CSS modules.
- Named exports only. No default exports outside route files.
- Dates as ISO strings at the boundary; Date objects internally.

# Welcome to Acme

Acme is a next-generation platform empowering teams to
unlock productivity through delightful experiences. Our
mission is to build software people love.

## Our values
- We value clean code.
- We believe in excellence.
- We move fast and care deeply about quality.
- Communication is key.

## Getting started
Clone the repo and follow the README. Make sure you have
Node installed. Install dependencies and you should be
good to go!

## Coding guidelines
- Write good, readable code.
- Follow best practices.
- Write tests where appropriate.
- Keep functions small and focused.
- Comment your code where it makes sense.
- Be a good citizen of the codebase.

## Architecture
We use a modern stack with industry-standard tools. The
frontend talks to the backend, which talks to the database.
For more details ask in #engineering.

## Notes
TODO: update this doc — last edited 14 months ago.

Template gallery

Starting points for the files above. Copy, paste at the root of your repo, then strip what doesn't apply and fill in the rest. Templates are intentionally terse — a long file that nobody reads is worse than a short one that everyone does.

# Project: <name>

Stack: <framework> + <db> + <key services>.
Deployed to <host>. Source of truth: this file.

## Commands

# Claude Code instructions

You are working in a real production repo. Read this file fully
before touching code. When in doubt, ask before editing.

## Stack

# .cursorrules

Stack: <framework> + <db> + <key services>.
Read AGENTS.md at repo root before any non-trivial edit.

## Editing

# PLAN: <feature name>

Author: <model + role>
Date: <YYYY-MM-DD>
Status: draft | accepted | implemented

# IMPLEMENTATION: <feature name>

Author: <model + role>
Date: <YYYY-MM-DD>
Plan: link to PLAN-<feature>.md

# REVIEW: <feature name>

Reviewer: <model + role>
Date: <YYYY-MM-DD>
Implementation: link to IMPL-<feature>.md
Verdict: approve | request-changes | block

These are starting scaffolds, not finished docs. The first edit pass — deleting lines that don't apply to your stack — is where the file becomes useful.

Verification loops

The most underrated practice in AI-assisted dev right now. AI lets you build 5x faster — but reviewing a 500-line diff still takes 500 lines of attention. If verification doesn't scale with build velocity, error rates rise silently. The principle is build-more, verify-more.

Three verification layers worth wiring in:

Verification scales with risk, not effort. The right amount is the minimum that catches the failures you care about — and the floor rises fast once real users, real money, or real data are on the line.

Read the rows as floors, not ceilings. A throwaway demo can absolutely get human review if you have time — but production code without an independent verifier is shipping on faith.

Escalation rules

The matrix above is the default. These are the overrides — situations where the normal verification level is not enough, regardless of how confident the builder model sounds. Treat them as hard rules, not suggestions. If a diff trips one, the gate closes until the extra verification is done.

These rules exist because confident-wrong is the AI failure mode that costs the most. The builder will tell you the migration is safe. The builder is not the one paying for the rollback.

Picking your setup

There's no single right answer. The right setup depends on what you build, how often, and how much risk you can absorb. A rough sorting:

For specific tool comparisons see /compare. For tools by category see /tools. For Claude-specific deep-dive see /agents.

Where it ships

Most AI builders include their own one-click deploy — Lovable, Bolt, v0, Replit, Base44, and Emergent will all ship what they generate without any external service. That's the right call for prototypes and demos. The platforms below are where teams land when they outgrow the built-in hosting: to own the deploy, extend the stack, control costs at scale, or wire into infra they already run.

Hosting & deploy

Database & backend

Once you're going external, pick by fit with your existing workflow — not feature lists. Most AI-generated apps will run on any of these; the right answer is whichever one matches how you already deploy, monitor, and pay.

Common mistakes

The mistakes change as you get more practice. What trips up someone in their first week is different from what blows up a team six months in. Sorted by where you are.