file-organization · diff
git:20260306.b04d94a to v2.0
214 added, 280 removed. Audit A to A.
---
name: file-organization
- description: Organize project files and folders for maintainability and scalability. Use when structuring new projects, refactoring folder structure, or establishing conventions. Handles project structure, naming conventions, and file organization best practices.
- allowed-tools: Read Write Glob Bash
+ description: "Design or refactor project structure around the right boundary unit: feature, shared layer, route segment, or workspace package. Use when a repo feels scattered, a team needs naming/import conventions, or the user must choose between type-based, feature-based, framework-colocated, and workspace layouts. Triggers on: file organization, folder structure, project structure, reorganize repo, feature folders, shared vs feature code, where should this file live, apps/packages split, and project layout refactor."
+ allowed-tools: Read Write Bash Grep Glob
+ compatibility: >
+ Best for frontend, backend, fullstack, and developer-workflow repositories
+ where the main problem is maintainable file boundaries and migration planning.
+ Not for component API design, environment provisioning, or workflow/deployment
+ automation.
+ license: MIT
metadata:
- tags: file-organization, project-structure, folder-structure, naming-conventions
- platforms: Claude, ChatGPT, Gemini
+ tags: project-structure, folder-structure, feature-based-architecture, naming-conventions, monorepo, migration
+ platforms: Claude, ChatGPT, Gemini, Codex
+ version: "2.0"
+ source: akillness/oh-my-skills
---
+ # File Organization
- # Project File Organization
+ Use this skill when the main question is **"what structural boundary should this codebase use, and how do we move toward it without turning a reorg into chaos?"**
+ The job is not to dump a giant folder tree and pretend it fits every repo.
+ The job is to:
+ 1. identify the real organizing unit,
+ 2. separate feature/shared/framework/package boundaries,
+ 3. define naming and import rules that prevent drift,
+ 4. plan the migration safely,
+ 5. return a structure brief another engineer or agent can apply immediately.
+ Read [references/boundary-decision-matrix.md](references/boundary-decision-matrix.md) before recommending a structure.
+ Read [references/migration-checklist.md](references/migration-checklist.md) before moving files or renaming directories.
+ Read [references/naming-and-import-rules.md](references/naming-and-import-rules.md) when the problem includes barrel files, alias paths, or team conventions.
+
## When to use this skill
+ - Choose a maintainable folder strategy for a new repo or app
+ - Refactor a repo whose `components/`, `hooks/`, `utils/`, and `store/` folders no longer match business boundaries
+ - Decide whether code belongs in a feature module, shared layer, route segment, or workspace package
+ - Review structure drift before a large reorganization or migration
+ - Standardize naming, import paths, and ownership rules across a growing team
+ - Decide whether a monorepo/workspace split is justified or premature
+ - Produce a migration plan that minimizes broken imports, duplicate files, and half-finished moves
- - **New Projects**: Initial folder structure design
- - **Project Growth**: Refactoring when complexity increases
- - **Team Standardization**: Establish consistent structure
+ ## When not to use this skill
+ - **The main task is designing reusable component APIs, variants, or slot/primitive composition** → use `ui-component-patterns` or `design-system`
+ - **The main task is framework state ownership, cache/store boundaries, or URL/form/server-state placement** → use `state-management`
+ - **The main task is making the repo runnable across machines, services, toolchains, or containers** → use `system-environment-setup`
+ - **The main task is task runners, bootstrap scripts, hooks, or local-CI command design** → use `workflow-automation`
+ - **The main task is deployment topology or hosted CI/CD rollout** → use `deployment-automation` or `vercel-deploy`
+ - **The repo only needs a tiny mechanical file move with no architectural decision**; in that case implement the move directly instead of reopening structure design
## Instructions
- ### Step 1: React/Next.js Project Structure
+ ### Step 1: Classify the structural pressure before drawing folders
+ Normalize the request into this intake first:
- ```
- src/
- ├── app/ # Next.js 13+ App Router
- │ ├── (auth)/ # Route groups
- │ │ ├── login/
- │ │ └── signup/
- │ ├── (dashboard)/
- │ │ ├── layout.tsx
- │ │ ├── page.tsx
- │ │ └── settings/
- │ ├── api/ # API routes
- │ │ ├── auth/
- │ │ └── users/
- │ └── layout.tsx
- │
- ├── components/ # UI Components
- │ ├── ui/ # Reusable UI (Button, Input)
- │ │ ├── Button/
- │ │ │ ├── Button.tsx
- │ │ │ ├── Button.test.tsx
- │ │ │ └── index.ts
- │ │ └── Input/
- │ ├── layout/ # Layout components (Header, Footer)
- │ ├── features/ # Feature-specific components
- │ │ ├── auth/
- │ │ └── dashboard/
- │ └── shared/ # Shared across features
- │
- ├── lib/ # Utilities & helpers
- │ ├── utils.ts
- │ ├── hooks/
- │ │ ├── useAuth.ts
- │ │ └── useLocalStorage.ts
- │ └── api/
- │ └── client.ts
- │
- ├── store/ # State management
- │ ├── slices/
- │ │ ├── authSlice.ts
- │ │ └── userSlice.ts
- │ └── index.ts
- │
- ├── types/ # TypeScript types
- │ ├── api.ts
- │ ├── models.ts
- │ └── index.ts
- │
- ├── config/ # Configuration
- │ ├── env.ts
- │ └── constants.ts
- │
- └── styles/ # Global styles
- ├── globals.css
- └── theme.ts
+ ```yaml
+ structure_intake:
+ repo_shape: single-app | app-plus-api | monorepo | library-cli | content-site | unknown
+ current_pattern: type-based | feature-based | route-colocated | package-workspace | mixed | unknown
+ main_pressure:
+ - scattered-feature-code
+ - unclear-shared-boundaries
+ - framework-routing-collision
+ - premature-monorepo-split
+ - monorepo-needed-now
+ - naming-drift
+ - import-chaos
+ - migration-risk
+ - onboarding-confusion
+ - unknown
+ change_scope: greenfield | incremental-refactor | major-reorg | audit-only
+ primary_boundary_unit: feature | shared-layer | route-segment | package | unknown
+ confidence: high | medium | low
```
- ### Step 2: Node.js/Express Backend Structure
-
- ```
- src/
- ├── api/ # API layer
- │ ├── routes/
- │ │ ├── auth.routes.ts
- │ │ ├── user.routes.ts
- │ │ └── index.ts
- │ ├── controllers/
- │ │ ├── auth.controller.ts
- │ │ └── user.controller.ts
- │ └── middlewares/
- │ ├── auth.middleware.ts
- │ ├── errorHandler.ts
- │ └── validation.ts
- │
- ├── services/ # Business logic
- │ ├── auth.service.ts
- │ ├── user.service.ts
- │ └── email.service.ts
- │
- ├── repositories/ # Data access layer
- │ ├── user.repository.ts
- │ └── session.repository.ts
- │
- ├── models/ # Database models
- │ ├── User.ts
- │ └── Session.ts
- │
- ├── database/ # Database setup
- │ ├── connection.ts
- │ ├── migrations/
- │ └── seeds/
- │
- ├── utils/ # Utilities
- │ ├── logger.ts
- │ ├── crypto.ts
- │ └── validators.ts
- │
- ├── config/ # Configuration
- │ ├── index.ts
- │ ├── database.ts
- │ └── env.ts
- │
- ├── types/ # TypeScript types
- │ ├── express.d.ts
- │ └── models.ts
- │
- ├── __tests__/ # Tests
- │ ├── unit/
- │ ├── integration/
- │ └── e2e/
- │
- └── index.ts # Entry point
- ```
+ If the user is vague, prefer the smallest obvious interpretation and state the assumption.
- ### Step 3: Feature-Based Structure (Large-Scale Apps)
+ ### Step 2: Choose one primary organization mode
+ Pick exactly one primary mode for the current run:
- ```
- src/
- ├── features/
- │ ├── auth/
- │ │ ├── components/
- │ │ │ ├── LoginForm.tsx
- │ │ │ └── SignupForm.tsx
- │ │ ├── hooks/
- │ │ │ └── useAuth.ts
- │ │ ├── api/
- │ │ │ └── authApi.ts
- │ │ ├── store/
- │ │ │ └── authSlice.ts
- │ │ ├── types/
- │ │ │ └── auth.types.ts
- │ │ └── index.ts
- │ │
- │ ├── products/
- │ │ ├── components/
- │ │ ├── hooks/
- │ │ ├── api/
- │ │ └── types/
- │ │
- │ └── orders/
- │
- ├── shared/ # Shared across features
- │ ├── components/
- │ ├── hooks/
- │ ├── utils/
- │ └── types/
- │
- └── core/ # App-wide
- ├── store/
- ├── router/
- └── config/
- ```
+ 1. **starter cleanup**
+ - Use when a type-based starter tree is still small enough to fix before it calcifies.
+ 2. **feature modularization**
+ - Use when business areas are spread across technical folders and need feature ownership.
+ 3. **framework colocation**
+ - Use when Next.js / similar router conventions should guide route-segment placement.
+ 4. **shared layer governance**
+ - Use when the repo already has features, but shared code keeps leaking everywhere.
+ 5. **workspace split**
+ - Use when multiple runnable apps/services/packages justify `apps/` + `packages/` boundaries.
+ 6. **migration audit**
+ - Use when the repo needs a safe move plan more than a brand-new structure proposal.
- ### Step 4: Naming Conventions
+ ### Step 3: Choose the smallest boundary unit that solves the problem
+ Use these rules:
- **File Names**:
- ```
- Components: PascalCase.tsx
- Hooks: camelCase.ts (useAuth.ts)
- Utils: camelCase.ts (formatDate.ts)
- Constants: UPPER_SNAKE_CASE.ts (API_ENDPOINTS.ts)
- Types: camelCase.types.ts (user.types.ts)
- Tests: *.test.ts, *.spec.ts
- ```
+ - Prefer **feature folders** when the same business area touches components, hooks, data access, tests, and state together.
+ - Prefer **shared layers** only for code reused by multiple features with stable ownership.
+ - Prefer **framework colocation** when routing/layout/file-convention semantics are part of the architecture, not just file storage.
+ - Prefer **workspace packages** only when there are multiple deployable apps/services, reusable libraries, or independent dependency/runtime needs.
+ - Do not promote a package split just because the repo feels messy; many repos need better feature/shared rules, not a monorepo.
+ - Keep **generated artifacts, docs, scripts, and tests** explicit instead of burying them in ambiguous utility folders.
- **Folder Names**:
- ```
- kebab-case: user-profile/
- camelCase: userProfile/ (optional: hooks/, utils/)
- PascalCase: UserProfile/ (optional: components/)
+ ### Step 4: Apply the decision ladder
+ #### Use feature modularization when
+ - understanding one user-facing capability currently requires opening files across many technical folders
+ - changes in one domain repeatedly touch `components/`, `hooks/`, `utils/`, `api/`, and `store/`
+ - the team needs clear ownership per feature or business area
- ✅ Consistency is key (entire team uses the same rules)
- ```
+ #### Use framework colocation when
+ - route segments, loaders, layouts, server/client boundaries, or file conventions shape where code must live
+ - the framework docs already define special files or reserved paths
+ - the real goal is to organize around routes/features without fighting the framework
- **Variable/Function Names**:
- ```typescript
- // Components: PascalCase
- const UserProfile = () => {};
+ #### Use shared layer governance when
+ - the repo already has features, but shared folders have become a dumping ground
+ - teams keep asking whether something is truly shared or just reused twice
+ - import paths and barrel files make boundaries hard to see
- // Functions: camelCase
- function getUserById() {}
+ #### Use workspace split when
+ - the repo contains multiple apps/services/packages with distinct dependencies or runtime targets
+ - shared libraries need versioned or explicit package boundaries
+ - build/test/deploy concerns are meaningfully different per package
- // Constants: UPPER_SNAKE_CASE
- const API_BASE_URL = 'https://api.example.com';
+ #### Use migration audit when
+ - the structure idea is mostly known but the move would break imports, docs, tests, or ownership if done casually
+ - the team needs staged moves, aliases, codemods, or compatibility shims
- // Private: _prefix (optional)
- class User {
- private _id: string;
+ ### Step 5: Keep structural boundaries honest
+ A good structure recommendation says what it does **not** own.
- private _hashPassword() {}
- }
+ Examples:
+ - if the real pain is reusable component primitives and API shape, route to `ui-component-patterns`
+ - if the real pain is design-token / library-wide UI governance, route to `design-system`
+ - if the real pain is runtime/services/toolchain setup, route to `system-environment-setup`
+ - if the real pain is recurring scripts and task entrypoints, route to `workflow-automation`
+ - if the real pain is state/caching ownership, route to `state-management`
- // Booleans: is/has/can prefix
- const isAuthenticated = true;
- const hasPermission = false;
- const canEdit = true;
- ```
+ Mixed requests are normal. Split them explicitly instead of forcing one folder strategy to solve everything.
- ### Step 5: index.ts Barrel Files
+ ### Step 6: Set reusable naming and import guardrails
+ Any recommended structure should name these rules explicitly:
- **components/ui/index.ts**:
- ```typescript
- // ✅ Good example: Re-export named exports
- export { Button } from './Button/Button';
- export { Input } from './Input/Input';
- export { Modal } from './Modal/Modal';
+ - **Directory purpose** — what belongs here and what does not
+ - **Naming style** — folder and file case conventions
+ - **Shared vs feature rule** — when code graduates into shared folders/packages
+ - **Public API rule** — whether features/packages export through one boundary file
+ - **Import rule** — whether deep imports across sibling features are forbidden
+ - **Test/doc/story placement rule** — colocated with feature or centralized by policy
- // Usage:
- import { Button, Input } from '@/components/ui';
- ```
+ Bad smells:
+ - `utils/` or `shared/` becoming a junk drawer
+ - feature code spread across five top-level technical folders
+ - barrel files that erase ownership and encourage deep implicit coupling
+ - moving to `apps/` + `packages/` without a real package/runtime boundary
+ - framework special files mixed with unrelated domain logic with no colocation rule
- **❌ Bad example**:
- ```typescript
- // Re-export everything (impairs tree-shaking)
- export * from './Button';
- export * from './Input';
- ```
+ ### Step 7: Plan the migration before changing files
+ Before moving anything, produce a change plan that covers:
- ## Output format
+ 1. current hotspots and why they are painful
+ 2. target boundary model
+ 3. staged move order
+ 4. alias/import or barrel compatibility strategy
+ 5. test/build/docs verification steps
+ 6. rollback or partial-adoption safety
- ### Project Template
+ Prefer incremental refactors over one huge rename when the repo is active.
- ```
- my-app/
- ├── .github/
- │ └── workflows/
- ├── public/
- ├── src/
- │ ├── app/
- │ ├── components/
- │ ├── lib/
- │ ├── types/
- │ └── config/
- ├── tests/
- ├── docs/
- ├── scripts/
- ├── .env.example
- ├── .gitignore
- ├── .eslintrc.json
- ├── .prettierrc
- ├── tsconfig.json
- ├── package.json
- └── README.md
- ```
+ ### Step 8: Produce the file-organization brief
+ Return a concise artifact someone can act on immediately.
- ## Constraints
+ Preferred format:
+ ```markdown
+ # File Organization Brief
- ### Required Rules (MUST)
+ ## Mode
+ - Primary mode:
+ - Why this mode fits:
- 1. **Consistency**: Entire team uses the same rules
- 2. **Clear Folder Names**: Roles must be explicit
- 3. **Max Depth**: Recommend 5 levels or fewer
+ ## Boundary choice
+ - Primary organizing unit:
+ - What belongs in feature/shared/route/package boundaries:
+ - What stays out of scope:
- ### Prohibited (MUST NOT)
+ ## Recommended structure
+ - Top-level folders/packages:
+ - One example feature/package layout:
+ - Naming/import rules:
- 1. **Excessive Nesting**: Avoid 7+ levels of folder depth
- 2. **Vague Names**: Avoid utils2/, helpers/, misc/
- 3. **Circular Dependencies**: Prohibit A → B → A references
+ ## Migration plan
+ 1. First step
+ 2. Second step
+ 3. Verification step
- ## Best practices
+ ## Handoffs
+ - Adjacent skills:
+ - Risks / follow-up work:
+ ```
- 1. **Colocation**: Keep related files close (component + styles + tests)
- 2. **Feature-Based**: Modularize by feature
- 3. **Path Aliases**: Simplify imports with `@/`
+ ### Step 9: Prefer clarity over template worship
+ When modernizing an existing structure:
+ - keep the recommendation tied to current repo pressures, not a fashionable template
+ - use framework conventions where they help, but do not confuse framework files with the whole architecture
+ - move code toward the smallest durable boundary model
+ - treat naming/import rules as part of the architecture, not cleanup trivia
+ - preserve transferable principles that work across frontend, backend, and fullstack repos
- **tsconfig.json**:
- ```json
- {
- "compilerOptions": {
- "baseUrl": ".",
- "paths": {
- "@/*": ["./src/*"],
- "@/components/*": ["./src/components/*"],
- "@/lib/*": ["./src/lib/*"]
- }
- }
- }
- ```
+ ## Output format
+ Always return a **file organization brief**, **repo structure recommendation**, or **migration audit**.
- **Usage**:
- ```typescript
- // ❌ Bad example
- import { Button } from '../../../components/ui/Button';
+ Required qualities:
+ - classify the structure problem before prescribing a tree
+ - choose one primary organization mode
+ - name the boundary unit explicitly
+ - include route-outs to adjacent skills
+ - provide naming/import guardrails
+ - include a migration plan when the repo already exists
- // ✅ Good example
- import { Button } from '@/components/ui';
- ```
+ ## Examples
- ## References
+ ### Example 1: Type-based starter tree is collapsing
+ **Input**
+ > We have `components`, `hooks`, `utils`, and `store`, but every checkout change touches all four folders. How should we reorganize this React app?
- - [React File Structure](https://react.dev/learn/thinking-in-react#step-1-break-the-ui-into-a-component-hierarchy)
- - [Node.js Best Practices](https://github.com/goldbergyoni/nodebestpractices)
- - [Clean Architecture](https://blog.cleancoder.com/uncle-bob/2012/08/13/the-clean-architecture.html)
+ **Good output direction**
+ - mode: `feature modularization`
+ - recommend feature folders for checkout/auth/catalog with a small shared layer
+ - add a rule for when code is allowed to move into shared
+ - keep state-ownership specifics routed to `state-management`
- ## Metadata
+ ### Example 2: Next.js route folders are getting messy
+ **Input**
+ > Our Next.js app router repo mixes route files, data helpers, and business logic all over `app/`. We need a clean structure that still respects framework conventions.
- ### Version
- - **Current Version**: 1.0.0
- - **Last Updated**: 2025-01-01
- - **Compatible Platforms**: Claude, ChatGPT, Gemini
+ **Good output direction**
+ - mode: `framework colocation`
+ - keep special route files where Next.js expects them
+ - colocate route-local code with route segments, move reusable domain logic into feature/shared boundaries outside route-only files
+ - mention route groups/private folders if they help organize without changing the URL
- ### Tags
- `#file-organization` `#project-structure` `#folder-structure` `#naming-conventions` `#utilities`
+ ### Example 3: Team wants to split into packages
+ **Input**
+ > Should this repo become `apps/` and `packages/`? We now have a web app, worker, and shared UI library.
- ## Examples
+ **Good output direction**
+ - mode: `workspace split`
+ - justify package boundaries by runnable targets and shared libraries
+ - recommend `apps/` for deployables and `packages/` for reusable libraries/tooling
+ - include migration and verification steps instead of only drawing the final tree
- ### Example 1: Basic usage
- <!-- Add example content here -->
+ ## Best practices
+ 1. Start from the pressure on the repo, not from a favorite architecture meme.
+ 2. Prefer the smallest boundary model that reduces change amplification.
+ 3. Treat shared code as a governed exception, not the default landing zone.
+ 4. Let framework conventions inform structure, but do not let them become accidental junk drawers.
+ 5. Split into packages only when dependencies, runtimes, or deployables truly require it.
+ 6. Name import and public-API rules early; they are part of the organization system.
+ 7. Use staged migrations and verification steps for live repos.
- ### Example 2: Advanced usage
- <!-- Add advanced example content here -->
+ ## References
+ - [Feature-Sliced Design folder-structure article](https://feature-sliced.design/blog/frontend-folder-structure)
+ - [Bulletproof React README](https://raw.githubusercontent.com/alan2207/bulletproof-react/master/README.md)
+ - [Bulletproof React project structure](https://raw.githubusercontent.com/alan2207/bulletproof-react/master/docs/project-structure.md)
+ - [Next.js project structure docs](https://nextjs.org/docs/app/getting-started/project-structure)
+ - [Turborepo repository structure docs](https://turborepo.dev/docs/crafting-your-repository/structuring-a-repository)
+ - [MIT Comm Lab file structure guidance](https://mitcommlab.mit.edu/broad/commkit/file-structure/)