Skip to main content
Your Next.js folder structure is actively sabotaging your attempts to use AI.

​
Bottleneck

A modern, AI-assisted dev process often splits into two iterative phases:
  1. Research & Planning: Using a large-context AI (like Gemini 2.5 Pro) to analyze an existing feature, brainstorm solutions, or draft a technical specification. This requires providing the AI with all the relevant code for that feature.
  2. Implementation: Using a specialized coding agent or CLI tool to translate the plan from the research phase into clean, functional code.
In a traditional Next.js project, the files for a single feature are spread across multiple top-level directories. Consider a standard project structure:
Types Driven
src/
├── app/
│   ├── profile/
│   │   └── page.tsx
│   └── ...
├── components/
│   ├── profile-avatar.tsx
│   ├── profile-form.tsx
│   └── ui/
├── hooks/
│   └── use-profile-data.ts
├── lib/
│   └── utils.ts
├── prisma/
├── trpc/
│   └── routers/
│       └── profile.ts
└── zustand/
    └── profile-store.ts
To build a complete picture of the user profile feature for an AI, you must manually hunt down and assemble files from app/, components/, hooks/, trpc/, and zustand/. This manual process of curating a “context package” is a bottleneck. It breaks your development flow and makes it harder to get accurate, contextual responses from your AI.

​
Solution

A feature-first (or feature-based) architecture solves this problem by reorganizing the project around functionality rather than file types. The core idea is to create a new top-level features/ directory, where each subdirectory is a self-contained module representing a distinct part of your application. Here is the same project, refactored for a feature-first approach:
Feature Driven
src/
├── app/
│   ├── profile/
│   │   └── page.tsx
│   └── ...
├── components/
│   ├── ui/ (shadcn/ui, etc.)
│   └── global/ (Navbar.tsx, Footer.tsx)
├── features/
│   ├── profile/
│   │   ├── api/ (trpc router for profile)
│   │   ├── components/ (Avatar.tsx, ProfileForm.tsx)
│   │   ├── hooks/ (useProfileData.ts)
│   │   ├── lib/ (profile-specific utils)
│   │   ├── validation/ (zod schemas)
│   │   └── zustand/ (profile state store)
│   └── another-feature/
│       └── ...
├── lib/ (global, shared utils)
├── providers/
├── prisma/
├── trpc/
└── styles/
In this new structure:
  • src/features/: This is the new home for all feature-specific logic. Each feature, like profile, is a self-contained module with its own components, hooks, API endpoints, and state management.
  • src/components/: This directory is now reserved for truly global components. This includes your UI primitive library (like shadcn/ui) and application-wide components like the main navigation or footer.
  • src/lib/, src/hooks/, etc.: Top-level directories like these are now used only for genuinely global, cross-cutting concerns that are shared across multiple features.
It builds on established patterns—modular design and monorepo-style boundaries—and applies them consistently in Next.js to give AI tools a single, coherent context per feature.

​
Speed, Scalability, and Sanity

Adopting a feature-first structure yields immediate and long-term advantages that extend beyond just AI collaboration.

​
AI Workflow Efficiency

This is the most significant and immediate payoff. Instead of spending time manually gathering scattered files, you can now easily create comprehensive context for an AI using tools like Repomix by simply pointing to the feature directory: src/features/profile.
This simple shift can save you 1 to 3 minutes every time you build context for a task, leading to faster analysis, more accurate suggestions, and a more fluid dev cycle.

​
Fluid Developer Experience

By grouping related code, features become modular and decoupled. This makes the entire codebase easier to navigate.
  • Onboarding: New developers can quickly understand a feature by exploring a single directory.
  • Debugging: When a bug appears in the user profile, you know exactly where to look.
  • Refactoring & Deletion: Modifying or removing a feature becomes a trivial task. You can confidently change or delete a feature’s directory without worrying about leaving orphaned files scattered across the repository.