Skip to main content
Your Next.js folder structure is actively sabotaging your attempts to use AI. You’ve embraced powerful assistants like Claude and Gemini to accelerate development. However, standard folder structures scatter related code across components/, hooks/, lib/, etc., forcing tedious manual context assembly for every task.

​
Bottleneck

A modern, AI-assisted development process often splits into two distinct phases:
  1. Research & Planning: Using a powerful, large-context AI (like Gemini 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.
The bottleneck lies in Phase 1. 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 creating a “context package” is a tedious bottleneck. It breaks your development flow and makes it harder to get accurate, contextual responses from your AI.

​
Solution (Feature-First Architecture)

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 development cycle.

​
Improved Maintainability & Scalability

By grouping related code, features become modular and decoupled. This makes the entire codebase easier to reason about.
  • 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.

​
Enhanced Developer Experience

This structure benefits human developers just as much as AI. When you’re working on a task, all the files you need are co-located, minimizing the need to jump between distant directories. This reduces cognitive load and allows you to stay focused on the problem at hand.

​
Final Thoughts

Your project’s architecture should be a facilitator, not a bottleneck. As AI assistants become more integrated into your development workflow, structuring your codebase to support efficient context-sharing will directly impact your productivity and code quality.
⌘I