Skip to main content
Coding agents are only as good as the context you hand them. After a year of shipping Next.js apps with Cursor and Claude Code, the structure that keeps producing clean diffs looks nothing like the default create-next-app layout. Six rules. Each one earns its place.

​
1. Organize by feature, not by file type

A feature is the unit of work an agent reasons about. “Add avatar upload to profile” touches a component, a router, a schema, a hook, a store. If those five files live under five different top-level folders, you spend the first three minutes of every task assembling a context package by hand. Put them together. Stop paying the tax.

​
2. The folder is the prompt

Project structure
With the left layout, your prompt starts with “find all files related to profile.” With the right layout, your prompt starts with @src/features/profile. That’s the whole argument.

​
3. components/ is for primitives and chrome only

src/components/ui/ holds shadcn. src/components/global/ holds the Navbar and Footer. Nothing else goes here. If a component is used by exactly one feature, it lives inside that feature. This rule is the one people break first. Hold the line — the moment you let ProfileHeader.tsx slip into components/, the pattern starts rotting.

​
4. Shared code has to earn its spot

src/lib/, src/hooks/, the top-level trpc/ wiring — these are for things used by two or more features. Everything starts inside a feature folder and graduates out only when a second consumer appears. YAGNI, applied to directories.

​
5. Route handlers stay thin

src/app/ stays as lean as Next.js will let it — route files, layouts, maybe a loading.tsx. The actual work is imported from features/*. Routes become a table of contents; the chapters live elsewhere.

​
6. Deletion should be a one-liner

The real test of a good structure: can you kill a feature with rm -rf src/features/profile and one search-and-replace for imports? If yes, your boundaries are real. If no, you have leaks to fix.

​
Try it on one feature

Don’t refactor the whole app on a Tuesday afternoon. Pick the feature you touched most this week, carve out src/features/<it>/, and move its files in. Run the app. Open your agent. Point it at the folder. You’ll know within one prompt whether to keep going.