VS Code Folder Structure for AI App Building That Holds

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, 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 to contract-first data.

What does the structure actually look like?

Feature folders, not type folders:

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”):

# 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 (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 made permanent.

Screen generation slots into the same system: a screen generated from a VP0 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, 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 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. 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.

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.