Folder Structure Patterns for AI Rules
Feature-based structure: AI rule: 'Organize by feature, not by type. Each feature has its own directory containing all related files: src/features/notifications/ contains notifications.route.ts, notifications.service.ts, notifications.repository.ts, notifications.types.ts, and __tests__/notifications.test.ts. Never organize by type (all routes in src/routes/, all services in src/services/) — this scatters related code across the project.' The AI: creates new features as self-contained directories. The developer: finds all notification code in one place, not spread across 5 directories.
Layer-based structure (when appropriate): AI rule: 'For projects using layered architecture: src/api/ (routes and controllers), src/domain/ (business logic and types), src/infrastructure/ (database, external services, caching). Each layer: only imports from the layer below (api → domain → infrastructure, never infrastructure → api). Tests: mirror the source structure in __tests__/.' The AI: creates files in the correct layer and respects import direction. The architecture: enforced by convention, not just by the architect's memory.
Hybrid structure: AI rule: 'Use feature-based within layers. src/api/notifications/ (route, controller, validation), src/domain/notifications/ (service, types, events), src/infrastructure/notifications/ (repository, cache). Shared code: src/shared/ (utilities, types, middleware used across features). The shared/ directory: must not import from any feature directory (shared cannot depend on specific features).' The AI: creates files at the intersection of feature and layer. AI rule: 'Folder structure rules are the most undervalued rules in CLAUDE.md. Without them: the AI creates files wherever seems logical (often the project root or a generic utils/ directory). With them: every generated file lands in the architecturally correct location. One rule saves hundreds of file-move operations.'
File and Directory Naming Conventions
File naming rules: AI rule: 'File naming follows the pattern: feature.purpose.extension. Examples: notifications.route.ts, notifications.service.ts, notifications.repository.ts, notifications.types.ts, notifications.test.ts. The purpose suffix: identifies the file's role without opening it. Never use generic names (utils.ts, helpers.ts, index.ts with actual logic). Index files: only for re-exports (barrel files), never for implementation.' The AI: generates files with self-documenting names. The project: navigable by filename alone.
Directory naming rules: AI rule: 'Directory names: lowercase, kebab-case for multi-word names. Feature directories: singular noun (notification, not notifications; user, not users). Layer directories: plural noun (routes, services, repositories). Special directories: __tests__ (tests), __mocks__ (mock files), __fixtures__ (test data). Never nest deeper than 4 levels from src/ (src/features/notification/handlers/ is the maximum depth).' The AI: creates directories that are consistent and navigable. The depth limit: prevents the deeply nested structures that AI tools sometimes create.
Co-location rules: AI rule: 'Tests co-located with source: src/features/notification/__tests__/notification.service.test.ts. Types co-located with feature: src/features/notification/notification.types.ts (not in a global types/ directory). Styles co-located with component: src/components/Button/Button.module.css (not in a global styles/ directory). Co-location principle: if a file is only used by one feature, it lives in that feature's directory.' The AI: generates files near their dependencies, not in global directories. AI rule: 'Naming patterns make the codebase self-documenting. When every file follows feature.purpose.extension: a developer can find any file by typing the feature name and the purpose. When every directory follows a consistent naming pattern: navigation is instant. The AI: follows these patterns because the rules specify them.'
Developer needs the notification service logic. Project without naming rules: is it in utils.ts? helpers.ts? index.ts? notification.ts? service.ts? Developer: searches the codebase. Time: 1-2 minutes. Project with naming rules: notifications.service.ts. Developer: types the filename directly. Time: 3 seconds. Multiply by 50 file lookups per day: 50-100 minutes saved daily. The naming pattern feature.purpose.extension: turns the file system into a queryable database. Type the feature name + the purpose: find the file instantly.
AI-Specific Folder Structure Issues
Issue 1: AI creates files in the project root. Without folder structure rules: the AI sometimes creates new files in the project root (alongside package.json). AI rule: 'Never create source files in the project root. All source code in src/. All scripts in scripts/. All configuration in config/ or the project root (package.json, tsconfig.json only).' The explicit prohibition: prevents the most common AI file placement error.
Issue 2: AI creates unnecessary utility files. The AI: generates a utility function, puts it in src/utils/formatDate.ts. Then generates another: src/utils/formatCurrency.ts. Then another: src/utils/formatName.ts. Soon: a utils/ directory with 50 single-function files. AI rule: 'Utility functions: grouped by domain in the shared/ directory. src/shared/formatting.ts (contains formatDate, formatCurrency, formatName). Maximum file size before splitting: 200 lines. Never create a file for a single utility function.' The rule: prevents utility file sprawl.
Issue 3: AI ignores existing structure. The project has a consistent feature-based structure. The AI: creates a new feature in a different pattern (maybe layer-based because it seems logical for this particular feature). AI rule: 'New features MUST follow the existing structure pattern. Check src/features/ for examples. Every new feature directory: matches the structure of existing feature directories. Never introduce a new organizational pattern without explicit approval.' The rule: forces the AI to observe and follow the existing structure. AI rule: 'AI-specific folder structure issues arise because the AI optimizes for the immediate task, not for project consistency. It creates a file where it seems logical for THIS feature, not where it should go based on the project's established patterns. Rules: override the AI's local optimization with the project's global convention.'
AI generates a date formatting utility. Where does it put it? Without rules: src/utils/formatDate.ts (the AI's default). But the project uses: src/shared/formatting.ts (grouping related utilities). Another AI request: generates a currency formatter. Without rules: src/utils/formatCurrency.ts (another single-function file). With rules: the AI adds formatCurrency to the existing src/shared/formatting.ts. The difference: 1 grouped file vs 50 scattered utility files after 6 months. The rule: 'Utility functions grouped by domain in shared/' — prevents the sprawl before it starts.
Folder Structure Rule Examples
Next.js App Router project: AI rule: 'Next.js structure: app/ (routes and pages), src/components/ (reusable UI components), src/lib/ (utilities and helpers), src/db/ (database schema and queries), src/config/ (configuration), src/types/ (shared types). App Router pages: app/[route]/page.tsx. API routes: app/api/[route]/route.ts. Server actions: app/[route]/actions.ts (co-located with the page that uses them). Components: src/components/[ComponentName]/[ComponentName].tsx with co-located styles and tests.' The AI: generates Next.js code in the correct App Router locations.
Express/Fastify API project: AI rule: 'API structure: src/routes/ (route definitions), src/controllers/ (request handling), src/services/ (business logic), src/repositories/ (data access), src/middleware/ (cross-cutting concerns), src/types/ (shared types), src/config/ (configuration). Each route: one file per resource (users.route.ts, orders.route.ts). Each controller: one file per resource. Registration: routes registered in src/routes/index.ts.' The AI: generates API endpoints following the established pattern.
Monorepo project: AI rule: 'Monorepo structure: packages/ (shared libraries), apps/ (deployable applications). Package naming: @org/package-name. Each package: has its own package.json, tsconfig.json, and src/ directory. Shared types: packages/types/. Shared utilities: packages/utils/. Application-specific code: never in packages/ (only shared code belongs in packages).' The AI: generates code in the correct monorepo location based on whether it is shared or application-specific. AI rule: 'Folder structure examples in CLAUDE.md are worth more than abstract rules. A tree diagram showing the expected structure: more effective than paragraphs of description. The AI reads the tree and replicates it. Include a tree for your specific project layout.'
Text rule: 'Organize features in the features directory with sub-directories for each feature containing route, service, repository, types, and test files.' The AI: interprets this in 5 different ways. Tree diagram in CLAUDE.md: src/features/notifications/ ├── notifications.route.ts ├── notifications.service.ts ├── notifications.repository.ts ├── notifications.types.ts └── __tests__/notifications.test.ts. The AI: replicates the exact structure. Zero interpretation needed. One tree diagram: more effective than a paragraph of description. Always include the tree.
Folder Structure Rules Quick Reference
Quick reference for AI coding folder structure rules.
- Organization: feature-based (group by feature) or layer-based (group by responsibility) — be explicit
- File naming: feature.purpose.extension (notifications.service.ts) — self-documenting names
- Directory naming: lowercase, kebab-case, singular for features, plural for layers, max 4 levels deep
- Co-location: tests, types, and styles next to the code they relate to — not in global directories
- Root prohibition: never create source files in project root — all source in src/
- Utility sprawl: group utilities by domain in shared/ — no single-function utility files
- Consistency: new features MUST follow existing structure pattern — check examples before creating
- Include a tree: a tree diagram of your project structure in CLAUDE.md is more effective than text rules