The Essential Files to Create Before You Start Vibe Coding

The Essential Files to Create Before You Start Vibe Coding#

Vibe coding lets you turn an idea into a working prototype just by describing what you want and letting an AI tool write or change the code. The catch is that the tool can only make good decisions when it has enough context about the project.

Without that context, an AI assistant will happily pick an unsuitable library, spin up a second version of a component you already have, invent database fields, rearrange an established folder structure, or build a feature that doesn't match what you actually need. It can look impressive in a demo and turn into a maintenance headache a few iterations later.

A better approach is to write a small set of project files before you ask an AI tool to build anything. These files become the project's shared reference: they explain what you're building, who it's for, how it should work, which technical decisions are already settled, and how to verify changes.

You don't need a full documentation system for every experiment. Start with the core files below and add the detailed ones when the project actually needs them.

The short answer: start with these files#

For a small application or MVP, create these first:

For a full-stack application, also consider ARCHITECTURE.md, DATA_MODEL.md, API_CONTRACT.md, and UI_SPEC.md. They earn their keep once the project has several components, persistent data, an API, or multiple screens. For a one-page prototype, they're optional.

1. README.md — give the project a clear identity#

The README is the entry point for anyone opening the repository for the first time. Keep it short and factual. It should say what the project is for and how to get it running.

Include:

• Project name and purpose: one or two sentences on what the application does.
• Target users: who it's designed for.
• Core features: the main capabilities planned for the first release.
• Technology stack: frontend, backend, database, and important services.
• Setup instructions: prerequisites, installation, environment setup, and run commands.
• Useful links: links to the product specification, architecture notes, and task plan.

A good README doesn't need to explain every feature in detail. Leave detailed requirements in PRODUCT_SPEC.md and technical design in ARCHITECTURE.md.

Example:

# InvoiceFlow

InvoiceFlow is a web application that helps independent freelancers
create invoices and track payment status.

## Initial features
- Create and edit clients
- Create and download invoices
- Track draft, sent, paid, and overdue invoices

## Technology
- Frontend: React
- Backend: Spring Boot
- Database: MySQL

## Local development
1. Copy `.env.example` to `.env` and fill in local values.
2. Install the project dependencies.
3. Start the backend and frontend using the commands below.

## Project documentation
- Product requirements: `PRODUCT_SPEC.md`
- Architecture: `ARCHITECTURE.md`
- Development tasks: `TASKS.md`

Don't list commands you haven't tested. An inaccurate setup guide confuses developers and coding agents alike.

2. PRODUCT_SPEC.md — define what you are actually building#

This is one of the most important files to have ready before you start vibe coding. A product specification turns a broad idea into requirements you can implement and check.

Take "build an expense tracker." That leaves a lot unanswered. Can users edit transactions? Are expenses recurring? Can one account have multiple workspaces? What happens when a user deletes a category? Should the first version support exports?

Write down the decisions that affect the first release:

Problem and users#

Describe the problem, the intended users, and the situation they'll be in when they use the product. Avoid vague statements like "for everyone who wants to be productive."

MVP features#

List the features that must exist in the first usable version. Keep them separate from ideas that can wait.

User flows#

Describe the important journeys in order. For example:

1. A user creates an account.
2. The user adds a client.
3. The user creates an invoice for that client.
4. The user downloads or shares the invoice.
5. The user marks the invoice as paid when payment arrives.

Business rules and acceptance criteria#

Record the rules the AI can't safely infer. For an invoice application, that might mean invoice-number uniqueness, tax calculations, date rules, and who is allowed to edit an invoice.

Write acceptance criteria in observable language:

• A user cannot save an invoice without a client and at least one line item.
• The displayed total equals the sum of line items, taxes, and discounts according to the documented calculation rules.
• A user cannot access another user's invoices by changing an identifier in the URL.

Non-goals#

State what the first version won't include. Non-goals matter because coding assistants will otherwise stretch a task past its intended scope.

A simple specification can follow this structure:

# Product Specification

## Problem
## Target users
## MVP features
## User flows
## Business rules
## Acceptance criteria
## Out of scope
## Open questions

Keep unresolved decisions under Open questions instead of letting the coding assistant quietly invent answers.

3. AGENTS.md — explain how the AI should work in this repository#

A product specification describes the product you want. An agent instruction file describes how a coding assistant should work on the codebase.

Use it to capture project-specific rules such as:

• Which framework, language, and package manager the project uses.
• Where pages, components, API routes, services, and database code belong.
• Which existing libraries or patterns should be reused.
• Which technologies or approaches shouldn't be introduced without approval.
• How errors, validation, authentication, and authorization should be handled.
• Which commands to run for linting, tests, and production builds.
• What the assistant must report when it can't run a check.

Example:

# Project Instructions

## Stack
- Frontend: React with JavaScript.
- Backend: Spring Boot with Java.
- Database: MySQL.

## Project rules
- Follow the existing folder structure and naming conventions.
- Inspect existing components and services before creating new ones.
- Do not add a dependency when the existing stack can solve the problem.
- Keep database access in the backend service/repository layers.
- Never place secrets or real credentials in source code.

## Before finishing a change
- Run the relevant tests.
- Run lint and build checks when available.
- Summarize changed files and any checks that could not be completed.

Important: not every coding tool reads AGENTS.md automatically, and not every configuration does either. Instruction-file names and discovery rules depend on the tool or agent harness you're using. For example, current VS Code documentation lists AGENTS.md for Codex, CLAUDE.md for Claude, and .github/copilot-instructions.md or AGENTS.md for Copilot sessions. Check your tool's documentation, put the file in a supported location, and verify that the assistant actually loaded the instructions. See the official VS Code custom instructions guide.

Keep this file tight. A short list of accurate rules beats a long page of generic advice. Update it whenever the architecture or development commands change.

4. ARCHITECTURE.md — show how the pieces fit together#

The architecture file describes the main parts of the application and how they talk to each other. It's especially useful once you have a frontend, backend, database, background jobs, or external services.

Document:

• The major components and their responsibilities.
• How data moves from the user interface to the backend and database.
• Where authentication and authorization are enforced.
• Which services or third-party integrations the application uses.
• Important boundaries, constraints, and technical decisions.
• A simple diagram, when it makes the design easier to follow.

For example, a basic full-stack application might have this flow:

Browser
   |
   v
React frontend
   |
   | HTTPS / REST API
   v
Spring Boot backend
   |
   +------> Authentication and authorization
   |
   +------> Business services
   |
   v
MySQL database

Also spell out the boundaries that shouldn't be crossed. For instance, the frontend shouldn't connect directly to the production database, and controllers shouldn't hold complex business logic if the project uses a service layer.

Don't document an architecture you merely hope to build. Make the file match the actual first-version design, then update it when the design changes.

5. DATA_MODEL.md — define the important data before generating database code#

Create this file when your application stores meaningful data or has relationships between users, organizations, and records.

List the main entities, their important fields, relationships, and constraints. For example:

Record the details that affect correctness: required and optional fields, uniqueness, deletion behavior, indexes, ownership, and relationships.

For multi-user or multi-tenant applications, document data ownership and tenant isolation explicitly. State how every query is restricted to the authenticated user's account or tenant. Don't leave the AI to guess the right ownership model from table names.

You can add an entity relationship diagram, SQL schema, or ORM model examples as the project matures. Keep the written rules consistent with the actual migrations and database schema.

6. API_CONTRACT.md — agree on how the frontend and backend communicate#

When your application has a separate frontend and backend, define the API contract before generating both sides independently.

For each important endpoint, document:

• HTTP method and route.
• Authentication requirements.
• Request body and query parameters.
• Successful response shape.
• Possible error responses.
• Validation and authorization rules.

Example:

## Create an invoice

POST /api/invoices

Authentication: required

Request:
{
  "clientId": "client_123",
  "items": [
    {
      "description": "Website maintenance",
      "quantity": 2,
      "unitPrice": 1500
    }
  ]
}

Success: 201 Created
Errors: 400 validation error, 401 unauthenticated, 403 forbidden

The example is illustrative, so use the identifier types, naming style, and response format your application has chosen. A consistent contract stops the frontend from expecting fields or status codes the backend never returns.

For a very small project, the API contract can start out inside PRODUCT_SPEC.md or ARCHITECTURE.md. Split it into its own file once it gets hard to maintain in one place.

7. UI_SPEC.md — describe screens and states, not just colors#

If you're building a user-facing application, give the coding assistant a clear description of the experience you expect. A screenshot or design reference helps, but it doesn't explain every interaction or state.

For each important screen, document:

• Its purpose and the main user action.
• The content and components it should display.
• Navigation and responsive behavior.
• Loading, empty, error, and success states.
• Form validation and disabled states.
• Accessibility requirements, including keyboard interaction and labels.

For a dashboard, for example, specify what a first-time user sees before they've added any data. Otherwise an AI tool may hand you a polished dashboard full of fabricated numbers instead of a useful empty state.

Add design tokens or references to an existing design system where relevant. Don't describe every pixel in prose if a maintained Figma file or visual reference already holds that information — link to the source of truth instead.

8. TASKS.md — turn the idea into small, verifiable steps#

Don't ask an AI coding assistant to build an entire product in one enormous request. Break the work into phases you can review and test independently.

A practical task plan might look like this:

# Development Tasks

## Phase 1: Project foundation
- [ ] Create frontend and backend project structure.
- [ ] Configure local environment variables.
- [ ] Confirm both applications start successfully.

## Phase 2: Authentication
- [ ] Implement registration and login.
- [ ] Add server-side authorization checks.
- [ ] Test invalid credentials and unauthorized access.

## Phase 3: Client management
- [ ] Create the client data model and migration.
- [ ] Implement create, list, update, and delete endpoints.
- [ ] Build the client screens and form validation.
- [ ] Test account-level data isolation.

## Phase 4: Verification
- [ ] Run relevant automated tests.
- [ ] Check loading, empty, and error states.
- [ ] Run the production build.

Each task should have a clear result. "Add server-side validation for required invoice fields and test invalid requests" is a good task. "Finish invoices" is not.

Ask the AI to work on one phase, or a small group of related tasks, at a time. Review the changed files and test the result before moving on. Then update the task list so it reflects what's actually done, not what the assistant claims to have done.

9. .env.example and .gitignore — establish safe local configuration#

Applications often rely on database URLs, API keys, authentication secrets, and service configuration. Create an .env.example file that documents the variable names the project expects, using placeholders instead of real credentials.

Example:

DATABASE_URL=
JWT_SECRET=
APP_BASE_URL=http://localhost:3000
PAYMENT_PROVIDER_SECRET=

Add real local environment files to .gitignore, along with dependencies, build outputs, logs, and other generated files appropriate to your stack. Keep .env.example tracked so developers know which variables to configure.

Never paste real secrets into prompts, source files, screenshots, or committed documentation. Use your framework's documented environment-variable mechanism and a secure secret store for production values. An example file documents configuration — it's not a place to keep credentials.

Optional files for projects with additional complexity#

You can add more documentation as the application grows. These files are useful in the right context, but they shouldn't turn into a checklist every small experiment has to satisfy.

The goal isn't to produce the most documentation. It's to keep important decisions visible and easy to verify.

A practical starter folder structure#

A small full-stack project could begin with this structure:

my-project/
├── README.md
├── PRODUCT_SPEC.md
├── AGENTS.md                 # Or the supported file for your AI tool
├── ARCHITECTURE.md           # Add when the app needs it
├── DATA_MODEL.md             # Add when persistent data is involved
├── API_CONTRACT.md           # Add when frontend and backend are separate
├── UI_SPEC.md                # Add for multi-screen user interfaces
├── TASKS.md
├── .env.example
├── .gitignore
├── frontend/
└── backend/

Treat this as an example, not a mandatory structure. If you're building a small frontend-only tool, you may not need a backend folder, data model, or API contract. Keep documentation files at the repository root when they describe the whole project; move detailed material into docs/ once it gets large.

How to use these files with an AI coding assistant#

Creating the files is only the first step. The assistant has to use them as working context, and you have to check that its changes follow them.

A reliable first prompt is:

Before writing or changing code:
1. Read README.md, PRODUCT_SPEC.md, the project instruction file,
   and any relevant architecture, data, API, or UI documents.
2. Inspect the existing repository. Do not assume the documented
   structure already matches the code.
3. Identify missing or conflicting decisions. Do not silently invent
   product requirements, database fields, API behavior, or dependencies.
4. Propose a small implementation plan with files to change and
   acceptance criteria for each step.
5. Wait for my review of the plan before making the first code change.

Once you've reviewed the plan, ask the assistant to implement one small phase. When it finishes, inspect the diff, run the relevant checks, and verify the behavior yourself. Update the documentation if an approved implementation decision changes the original plan.

Remember that instruction files guide an AI assistant; they don't guarantee it will follow every rule. Tests, code review, and security checks are still necessary. Microsoft's guidance also recommends keeping instructions specific to the repository and verifying that the selected agent uses them. Read the VS Code guide to configuring AI for a codebase for examples.

Common mistakes to avoid before vibe coding#

Writing a huge specification for a tiny experiment. Start with a one-page product brief and the rules that matter. Add detail only when complexity calls for it.

Mixing product requirements with coding rules. PRODUCT_SPEC.md says what the product should do. AGENTS.md explains how the assistant should work in the repository. Keeping the purposes separate makes both easier to maintain.

Creating documentation and never updating it. Outdated architecture diagrams, commands, and API examples can mislead the next coding session. Update the source of truth whenever an approved change makes it inaccurate.

Letting the AI decide important business rules. Ask it to surface open questions instead of inventing pricing rules, permission models, tenant ownership, or data-retention behavior.

Trusting generated code because it runs once. A successful local run doesn't prove that validation, authorization, error handling, migrations, or edge cases are correct.

Adding every possible instruction file. Use the filename and location your actual coding tool supports. Avoid maintaining duplicate files with conflicting instructions.

Conclusion#

Vibe coding works best when you give the AI coding assistant a clear project boundary before handing it implementation work. A README, product specification, agent instructions, and task plan are a strong starting point. Architecture, data, API, and UI documents add clarity as the application grows more complex.

You don't need to write every file before building your first screen. You do need to make important decisions explicit, keep the documentation aligned with the code, and verify what the AI produces. A little preparation can prevent a lot of avoidable rework later.

References#

• Use custom instructions in VS Code — supported instruction formats and agent-harness differences.
• Configure AI for your codebase — practical guidance for project-specific instructions and verification.
• Iterating Development Workflows with Codex — an example of using project guidance and phased development workflows with Codex.