Handoff Docs for Vibe Coders

Contents

• The Vibe Coder Amnesia Problem
• Why Traditional Documentation Fails AI Codebases
• The 4-Part Lean Handoff Stack
• Part 1: The One-Command Bootstrap Script
• Part 2: The Architecture and Data Flow Map
• Part 3: Agent Directives and Repo Guardrails
• Part 4: Operational Runbook and Recovery Paths
• Automating Handoff Hygiene in Git
• FAQ

The Vibe Coder Amnesia Problem

You built a working SaaS prototype in four days. You prompted Cursor, iterated with Claude Code, generated database schemas, connected Stripe webhooks, and pushed to production. The app works, customers are signing up, and everything runs smoothly.

Then, you take a three-week break to work on another project.

When you return, you open the editor and hit a wall. You cannot remember which background worker handles webhook retries. You cannot remember why a specific environment flag must be set to false. When you ask an AI assistant to fix a bug, the model hallucinates an alternative database pattern and wipes out working logic because it has zero context on how the system was originally conceived.

If you bring in a freelance developer or co-founder, the situation is even worse. They spend three days trying to run the project locally, wrestling with undocumented dependencies, missing environment variables, and unrecorded secrets.

This is the vibe coder amnesia problem. High-velocity AI development generates high code volume with low conceptual documentation. When architectural intent exists only in ephemeral chat windows, your codebase becomes a legacy burden within a month.

At ZeroShot Studio, we operate autonomous agents and continuous pipelines daily. We solved this problem by codifying an ultra-lean handoff protocol that takes under thirty minutes to write and keeps projects maintainable indefinitely.

Why Traditional Documentation Fails AI Codebases

Software engineering culture has spent decades oscillating between two extremes:

1. The 50-page enterprise specification: Confluence pages and monolithic Word documents that take weeks to write and fall out of date the minute code changes.
2. Zero documentation ("the code is self-documenting"): A mindset that collapses instantly when 80% of the code was generated probabilistically by an LLM that is no longer in the room.

AI-generated codebases rot faster than handwritten code because models introduce subtle quirks: non-standard library choices, idiosyncratic folder patterns, and undocumented glue logic.

To make an AI-assisted project durable, your documentation must satisfy three operational criteria:

• Executable over explanatory: If a command can be scripted in bash or a Makefile, script it. Do not write four paragraphs explaining how to install Redis.
• Dual-audience design: Documentation must be equally legible to a new human contractor and an autonomous coding agent parsing context in Cursor or Claude Code.
• Co-located with code: Docs must live in the Git repository alongside source files, updated in the same PRs that change application logic.

flowchart TD
    A["Vibe Coded Project Scaffold"] --> B["Part 1: Bootstrap Script\nscripts/setup.sh / Makefile"]
    A --> C["Part 2: Architecture Map\nSystem Boundaries + Data Flow"]
    A --> D["Part 3: Agent Directives\nAGENTS.md / CLAUDE.md Rules"]
    A --> E["Part 4: Operational Runbook\nDeployments + Secrets + Rollbacks"]
    B --> F["Frictionless Developer & Agent Onboarding"]
    C --> F
    D --> F
    E --> F
    F --> G["Zero-Downtime Continuity & Fast Iteration"]

The 4-Part Lean Handoff Stack

Instead of an exhaustive technical manual, organize your handoff package into four discrete files inside the root of your repository:

Let us explore how to construct each element with concrete templates you can drop directly into your projects.

Part 1: The One-Command Bootstrap Script

The fastest way to alienate a new engineer or frustrate an AI session is an onboarding process that requires 14 manual steps.

Create an executable setup script at scripts/setup.sh that validates prerequisites, configures environment files, installs dependencies, and boots local services.

#!/usr/bin/env bashset -euo pipefailecho "==> Validating runtime prerequisites..."command -v node >/dev/null 2>&1 || { echo "Error: Node.js is required."; exit 1; }command -v pnpm >/dev/null 2>&1 || { echo "Error: pnpm is required."; exit 1; }command -v docker >/dev/null 2>&1 || { echo "Error: Docker is required."; exit 1; }echo "==> Configuring environment variables..."if [ ! -f .env ]; then  cp .env.example .env  echo "Created .env from .env.example. Please populate secrets."fiecho "==> Installing dependencies..."pnpm install --frozen-lockfileecho "==> Booting local dependencies (Postgres, Redis)..."docker compose up -d postgres redisecho "==> Running database migrations..."pnpm db:migrateecho "==> Running pre-flight verification..."pnpm test:smokeecho "✅ Environment ready! Run 'pnpm dev' to start the application."

Pair this with a strict .env.example that documents every environment variable, its expected format, and where to obtain testing keys:

# Server ConfigurationPORT=3000NODE_ENV=development# Database configurationDB_HOST=localhostDB_PORT=5432DB_USER=postgresDB_NAME=app_dev# Authentication (Generate with: openssl rand -base64 32)AUTH_SECRET=replace_with_local_secret_for_testing# External APIs (Leave blank for mock mode)STRIPE_SECRET_KEY=sk_test_placeholderOPENAI_API_KEY=mock_key_or_actual_test_token

When a developer or agent clones your repository, running ./scripts/setup.sh takes them from zero to a passing test suite in ninety seconds.

Part 2: The Architecture and Data Flow Map

Do not write narrative essays about your code. Create a concise architecture map in docs/ARCHITECTURE.md that highlights three items:

1. Core Domains: What does each top-level directory own?
2. Data Flow: How does an incoming request move from the edge to the database?
3. External Dependencies: What 3rd-party services does this app touch?

Here is a production-ready markdown structure:

# System Architecture## Directory Layout- `src/app/`: Next.js App Router endpoints and page layouts.- `src/components/`: Reusable UI elements (Tailwind + Radix).- `src/lib/db/`: Postgres client, schema definitions, and migrations.- `src/workers/`: BullMQ asynchronous background queue consumers.## Core Data Flow1. Client submits task request to `POST /api/tasks`.2. Route handler authenticates session via JWT cookie.3. Payload is validated against Zod schema (`src/lib/schemas/task.ts`).4. Task record created in Postgres with status `queued`.5. Job dispatched to Redis queue (`task-processor`).6. Worker picks up job, executes LLM generation, writes result to database, and triggers webhook.## External Services & Gateways- **Postgres (Plesk/RDS):** Primary application data and relational models.- **Redis:** Job queue broker and rate-limiting cache.- **Resend:** Transactional email delivery.- **Stripe:** Billing subscriptions and webhooks.

Adding a clean Mermaid diagram to this file gives both humans and AI models an instant topological view of how components interact.

Part 3: Agent Directives and Repo Guardrails

When you hand off a codebase, the next person modifying it will almost certainly use Cursor, Claude Code, or another AI assistant.

If your repository lacks an instruction file (AGENTS.md or CLAUDE.md), their assistant will make wild guesses about your conventions. It might install an incompatible state management library, rewrite working functional components into classes, or introduce unneeded abstraction layers.

Create an AGENTS.md file in the repo root establishing boundaries:

# Repository Agent Contract## Tech Stack Rules- Language: TypeScript (strict mode enabled, zero 'any' allowed).- Framework: Next.js (App Router, Server Components by default).- Styling: Tailwind CSS (no inline CSS or style tags).- Database: Direct SQL or lightweight ORM (never add Prisma).## Modification Constraints1. Edit only the files directly related to the requested task.2. Never delete defensive error handling or null checks.3. Always run 'pnpm typecheck' and 'pnpm test' before reporting done.4. If a task requires modifying more than 3 files or 100 lines, present a proposed plan first.5. All environment variables must be declared in '.env.example' with validation in 'src/lib/env.ts'.

This single file ensures that any future AI tool respects your architectural boundaries and prevents regressions.

Part 4: Operational Runbook and Recovery Paths

What happens when production crashes on a Saturday night?

An operational runbook (docs/RUNBOOK.md) is your insurance policy. It documents how to build, deploy, monitor, and roll back the system when things break.

Include four critical sections:

1. Deployment Pipeline: How does code reach production? (GitHub Actions, Docker container builds, VPS SSH commands).
2. Health Check Endpoints: Which URLs verify system status (/api/health)?
3. Log Access: Where do logs live and how do you tail them?
4. Emergency Rollback: How do you revert a bad deployment in under two minutes?

# Operational Runbook## Production Deploy- Automated: Pushing to branch 'main' triggers GitHub Actions.- Manual VPS Deploy:  ```bash  ssh deploy@vps.internal  cd /opt/apps/production  git pull origin main  docker compose build --no-cache  docker compose up -d

Health Verification

• Web health: curl -f https://app.example.com/api/health
• Database check: docker exec -it app-postgres pg_isready

Log Inspection

• Web container logs: docker logs --tail 100 -f app-web
• Worker logs: docker logs --tail 100 -f app-worker

Emergency Rollback

If a deployment causes critical errors, rollback immediately to the previous image:

1. Identify the last working commit: git log -n 5 --oneline
2. Checkout the tag: git checkout v1.4.2
3. Force rebuild container: docker compose up -d --build
4. Post incident note in team chat.

## Automating Handoff Hygiene in GitDocumentation rots when it lives separately from the codebase. To make handoff maintenance effortless, tie documentation updates into your Git workflow:- **The Docs-with-PR Rule:** If a PR introduces a new environment variable or external service, the PR is incomplete unless `.env.example` and `docs/ARCHITECTURE.md` are updated in the same commit.- **Automated Verification:** Add a GitHub Actions check that verifies `./scripts/setup.sh` runs cleanly in a fresh Ubuntu runner on every pull request.- **Keep it Lean:** If a section of documentation requires more than two pages, it is too complex. Strip out descriptive fluff and replace it with automated scripts or concise tables.Taking thirty minutes to establish this 4-part handoff stack transforms an ephemeral vibe-coded prototype into a professional, maintainable software asset that you, your contractors, and your AI assistants can build on for years.## FAQ### What are the essential sections every AI project handoff doc must include?Every project handoff doc needs four core components: a one-command bootstrap script (`scripts/setup.sh`), an architecture and data flow map (`docs/ARCHITECTURE.md`), an agent instruction file (`AGENTS.md`), and an operational recovery runbook (`docs/RUNBOOK.md`).### How do I keep handoff documentation from falling out of date?Co-locate documentation directly in your Git repository and enforce that any code changes adding environment variables, APIs, or database models must update the corresponding docs in the exact same commit.### How do handoff docs improve future AI coding sessions?AI models like Cursor, Claude Code, and Codex read repository instructions (`AGENTS.md`) and architecture summaries upfront. Providing clear constraints prevents models from hallucinating alternative conventions or wiping out critical error handling.### Where should handoff files live inside a Git repository?Keep executable scripts in `scripts/`, agent directives in the root (`AGENTS.md` and `CLAUDE.md`), and system architecture alongside runbooks in a dedicated `docs/` folder.