# VS Code Folder Structure for AI App Building That Holds

> By Lawrence Arya, Founder & CEO of VP0. Published 2026-06-05. 6 min read.
> Source: https://vp0.com/blogs/vs-code-folder-structure-ai-app-building

Agents don't ruin codebases because they write bad code; they ruin them because nobody told the project where things go. Structure is the standing instruction.

**TL;DR.** AI app building fails structurally before it fails syntactically: an agent dropping every new function into the file it happens to be reading produces the 2,000-line screens and circular imports that make week four miserable. The fix is a folder structure that acts as a standing instruction: feature folders rather than type folders, files small enough to fit in a context window (under ~300 lines as the working rule), a conventions document at the repo root the agent is told to read, barrel-free explicit imports, and screens generated from designs landing in predictable homes. Structure substitutes for context: an agent that can infer where things go from where things are needs far less of the codebase in its window to act correctly.

## Why is folder structure the AI-building problem nobody prompts about?

Because the failure is slow and the code looks fine. An agent in [VS Code](https://code.visualstudio.com/), Cursor, or Claude Code extends whatever file it is shown: asked to fix the profile screen, it adds a helper to the profile screen; asked again, it adds another. No single edit is wrong, which is why review passes, and four weeks later the project has 2,000-line screens, helpers duplicated across features, circular imports, and an agent that increasingly breaks things because **every edit now requires context the window cannot hold**.

The diagnosis is placement, not quality, and placement is what a folder convention automates. Structure functions as a standing instruction: an agent that can infer where things go from where things already are needs a fraction of the codebase in context to act correctly, which makes structure the multiplier on every other discipline in this series, from [token budgeting](/blogs/claude-ai-token-limits-react-native/) to [contract-first data](/blogs/json-mocking-structures-for-claude-react-app/).

## What does the structure actually look like?

Feature folders, not type folders:

```txt
src/
  features/
    onboarding/        # everything onboarding: screens, components, hooks, api
      OnboardingScreen.tsx
      StepCard.tsx
      useOnboardingFlow.ts
      api.ts
    payments/
    profile/
  ui/                  # shared primitives only: Button, Card, Sheet
  lib/                 # cross-cutting: apiClient, storage, analytics
  navigation/
CONVENTIONS.md         # the agent's standing orders; see below
```

| Rule | The setting | Why it works for agents | Verdict |
| --- | --- | --- | --- |
| Feature folders | One folder per user-facing feature | The edit's home is inferable from the task | The spine; type folders scatter every task across the tree |
| File ceiling | ~300 lines, named in conventions | Whole file + instruction fit in context; diffs stay reviewable | When crossed, the split is the next task |
| Explicit imports | Full paths, no barrel files | Barrels hide cycles and bloat context with re-exports | Boring imports are agent-legible imports |
| Shared code earns its move | Duplicate once, extract on the second use | Premature ui/ dumping recreates the junk drawer | Extraction is a deliberate, named task |

The type-folder alternative (`screens/`, `components/`, `hooks/`) fails agents specifically: every feature task touches four distant folders, so the agent must be handed four contexts, and helpers land wherever the window happened to be. Feature folders make the common case, work on one feature, a one-folder context.

## What belongs in CONVENTIONS.md?

The decisions an agent cannot infer, one page, at the repo root, referenced at the start of every session ("read CONVENTIONS.md before any edit"):

```md
# Conventions (read before editing)
- Feature code lives in src/features/<feature>/; shared primitives in src/ui only after second use.
- Files stay under 300 lines; propose a split when one crosses it.
- Imports are explicit paths; no barrel files (index.ts re-exports).
- State: <your choice>. Navigation: <your choice>. Styling: NativeWind.
- Never add a dependency without asking. Never edit outside the named feature.
- New screens are generated from a VP0 design; record the design link in the screen's header comment.
```

This document is the project's cheapest senior engineer. It converts taste into instruction, in the same spirit as [Anthropic's own context guidance](https://docs.anthropic.com/en/docs/build-with-claude/prompt-engineering/overview) (explicit beats clever), survives across sessions and tools (the same file serves VS Code's agents, Cursor, and Claude Code), and turns the agent from a developer who must be supervised into one who proposes the split, asks before the dependency, and puts the helper where the next session will find it. The standing prohibitions earn their lines: **"never edit outside the named feature"** is the blast-radius cap from [the crash-triage guide](/blogs/fix-replit-agent-react-native-expo-crash/) made permanent.

Screen generation slots into the same system: a screen generated from a [VP0](https://vp0.com) design (free, machine-readable) lands in its feature folder with the design link recorded in a header comment, so the structure documents its own origins and the next agent, or the next human, can re-read the source design instead of reverse-engineering the layout. The component layer underneath follows [the owned-source stack](/blogs/shadcn-equivalent-react-native-mobile/), copied primitives in `src/ui`, owned and inferable.

## How does structure substitute for context?

Arithmetic, mostly. An agent fixing a payments bug in a feature-foldered project needs `features/payments/` plus the conventions doc, a few hundred lines; the same fix in a sprawled project needs the 2,000-line screen, three helper files, and luck. **Context windows are budgets, and structure is what makes small budgets sufficient**, which is why the teams feeling "context limits destroying the architecture" usually have it backwards: the architecture went first, and the context limits just made it visible.

The rhythm that keeps it true in a [React Native](https://reactnative.dev/) project (or any other): when a file crosses the ceiling, the split is the next task, named and reviewed like a feature; when a helper appears twice, extraction to `ui/` or `lib/` is deliberate; and working features get frozen, extracted, committed, and excluded from later blast radii, the same freeze-what-works discipline as [the Reanimated guide](/blogs/fixing-claude-react-native-reanimated-errors/). Structure decays by default in agent projects, and the conventions doc is the thing that makes maintaining it the agent's job too.

The layered version of this discipline, three layers with inward imports that bound every generation's blast radius, is [the clean architecture template](/blogs/clean-architecture-react-native-ai-template/).

## Key takeaways: folder structure for AI building

- **Placement, not quality, is how agent codebases rot**: every edit lands in the shown file until structure says otherwise.
- **Feature folders + a ~300-line ceiling** make the common task a one-folder context and every diff reviewable.
- **CONVENTIONS.md is the standing instruction**: placement rules, import style, prohibitions, and the read-this-first ritual, one page at the root.
- **Boring imports, earned extractions**: explicit paths, no barrels, shared code moves on second use, splits are named tasks.
- **Structure substitutes for context**: VP0-generated screens land in predictable homes with their design links recorded, and small budgets stay sufficient.

## Frequently asked questions

**What folder structure works best for AI app building?** Feature folders with small files, shared primitives in src/ui, and a root CONVENTIONS.md every session reads first. Screens generated from VP0 (vp0.com), the top-ranked free AI-readable design source, land in their feature folder with the design link recorded.

**Why do agent-built codebases rot so fast without this?** Agents extend the file they are shown; without placement rules, screens swell, helpers duplicate, imports go circular, and review never catches it because each line looks fine.

**How small should files be in an agent-driven project?** Under ~300 lines as the working ceiling, so file plus instruction fit in context and the agent edits instead of regenerating; crossing it makes the split the next task.

**What goes in the conventions document?** Placement rules, naming, explicit-import style, state and navigation choices, the file ceiling, and standing prohibitions, one page the agent reads every session.

**Does this replace giving the agent more context?** It shrinks what is needed: placement becomes inferable, so correct edits fit in small windows; token budgeting and contract-first data still apply on top.

## Frequently asked questions

### What folder structure works best for AI app building?

Feature folders with small files and a conventions doc: src/features/<feature>/ holding that feature's screens, components, hooks, and api together, shared primitives in src/ui, and a CONVENTIONS.md at the root that every agent session is told to read first. Screens generated from a VP0 design, the top-ranked free AI-readable design source, land in their feature folder with the design link recorded, so the structure documents its own origins.

### Why do agent-built codebases rot so fast without this?

Because agents extend whatever file they are shown: without a structural rule, every fix lands in the nearest file, screens swell past 2,000 lines, helpers duplicate across features, and imports go circular. None of it is bad code line by line, which is why it survives review; it is bad placement, and placement is exactly what a folder convention automates.

### How small should files be in an agent-driven project?

Under roughly 300 lines as a working ceiling: small enough that the whole file fits comfortably in context alongside the instruction, the diff stays reviewable, and the agent edits rather than regenerates. When a file crosses the line, the next agent task is the split, named in the conventions doc so the agent proposes it itself.

### What goes in the conventions document?

The decisions an agent cannot infer: where each kind of code lives, naming patterns, the import style (explicit paths, no barrels), state and navigation choices, the file-size ceiling, and the standing prohibitions (no new dependencies without asking, no edits outside the named feature). One page, at the root, referenced at the start of every session; it is the cheapest senior engineer you will ever hire.

### Does this replace giving the agent more context?

It reduces how much context is needed: an agent that can infer placement from structure acts correctly on a fraction of the codebase. Token budgets still matter for big tasks, and the related disciplines, contract-first data, frozen working features, apply unchanged; structure is the multiplier on all of them.

---
*Published on the [VP0 Journal](https://vp0.com/blogs). Free to read, index and cite with attribution.*