File Organization

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 before recommending a structure. Read references/migration-checklist.md before moving files or renaming directories. Read 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

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: Classify the structural pressure before drawing folders

Normalize the request into this intake first:

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

If the user is vague, prefer the smallest obvious interpretation and state the assumption.

Step 2: Choose one primary organization mode

Pick exactly one primary mode for the current run:

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 3: Choose the smallest boundary unit that solves the problem

Use these rules:

• 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.

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

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

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

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

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

Step 5: Keep structural boundaries honest

A good structure recommendation says what it does not own.

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

Mixed requests are normal. Split them explicitly instead of forcing one folder strategy to solve everything.

Step 6: Set reusable naming and import guardrails

Any recommended structure should name these rules explicitly:

• 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

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

Step 7: Plan the migration before changing files

Before moving anything, produce a change plan that covers:

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

Prefer incremental refactors over one huge rename when the repo is active.

Step 8: Produce the file-organization brief

Return a concise artifact someone can act on immediately.

Preferred format:

# File Organization Brief

## Mode
- Primary mode:
- Why this mode fits:

## Boundary choice
- Primary organizing unit:
- What belongs in feature/shared/route/package boundaries:
- What stays out of scope:

## Recommended structure
- Top-level folders/packages:
- One example feature/package layout:
- Naming/import rules:

## Migration plan
1. First step
2. Second step
3. Verification step

## Handoffs
- Adjacent skills:
- Risks / follow-up work:

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

Output format

Always return a file organization brief, repo structure recommendation, or migration audit.

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

Examples

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?

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

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.

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

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.

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

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.

References

• Feature-Sliced Design folder-structure article
• Bulletproof React README
• Bulletproof React project structure
• Next.js project structure docs
• Turborepo repository structure docs
• MIT Comm Lab file structure guidance

Boundary Decision Matrix

Use this when choosing the main organizing unit.

Fast heuristics

• If one user-facing change touches five technical folders, start with feature modularization.
• If the framework already reserves file names/locations, respect those constraints first.
• If shared/ keeps growing faster than features, your shared criteria are too weak.
• If a package would only contain one folder moved for tidiness, you probably do not need a package yet.
• If the team cannot explain what belongs in a folder in one sentence, that folder is not a reliable boundary.

Adjacent-skill handoffs

• Component API and reusable primitive design → ui-component-patterns
• Design-token and library governance → design-system
• State/caching ownership → state-management
• Toolchain/services/runtime setup → system-environment-setup
• Task runners / hooks / bootstrap automation → workflow-automation

Migration Checklist

Use this before moving files or renaming folders in a live repo.

1. Audit current hotspots

• List the folders that cause the most cross-cutting edits.
• Note any framework-reserved files or directories.
• Find barrel files, import aliases, and deep imports that will break.

2. Define the target boundary model

• One sentence per top-level directory/package explaining what belongs there.
• Shared-vs-feature promotion rule.
• Naming convention and public-API/import rule.

3. Pick a migration shape

• Incremental feature-by-feature move for active repos.
• Compatibility shim phase if aliases/barrels must keep old imports alive temporarily.
• Big-bang move only when the repo is small or frozen.

4. Stage the change

1. Create target folders/packages and docs. 2. Move one feature or one boundary class at a time. 3. Update imports/aliases and remove dead compatibility helpers. 4. Run tests/build/lint after each stage. 5. Update onboarding docs and examples.

5. Verify

• Build/test/lint pass.
• Search for stale imports or dead path aliases.
• Confirm no new junk-drawer folders were created during the move.
• Make sure route files, scripts, docs, and generated files still live where tools expect them.

6. Rollback / pause plan

• Keep move batches small enough to revert.
• Avoid half-moving one feature across two architectures for long.
• If the team cannot finish the migration now, choose a stable intermediate structure and document it.

Migration Playbook

Use this when the repo is already messy.

Goal

Improve structure without forcing a heroic rewrite.

Sequence

1. Name the target vocabulary

• top-level folders
• what counts as a feature/domain
• when code becomes shared
• naming conventions for files and folders

2. Pick one migration slice

• one feature
• one backend module
• one docs section
• one game system/content area

3. Move the hottest path first Prefer the area people edit every week, not the oldest dead zone.

4. Preserve stability while moving

• aliases or compatibility exports if needed
• small README notes for changed paths
• package/public-API guards if using workspaces

5. Freeze junk-drawer growth New code should stop entering misc/, common/, helpers/, utils/, or equivalent buckets unless they have an explicit owner and rule.

6. Backfill deliberately Clean old areas only after the new placement rules are already being followed.

Migration do/don't

Do

• move one boundary at a time
• publish simple placement rules
• track exceptions explicitly
• let old and new coexist temporarily when necessary

Don't

• rename everything in one PR unless the repo is tiny
• invent new shared folders just to avoid choosing an owner
• turn migration into a tooling rewrite unless that is the actual bottleneck
• confuse file movement with environment or deployment work

Signs the migration is working

• contributors know where the next file goes
• fewer files land in generic shared buckets
• route/domain changes stay locally scoped
• package extraction becomes rarer and more intentional
• repo docs describe the shape in a few lines, not a wall of exceptions

Naming and Import Rules

A folder strategy fails if naming and imports ignore the boundary model.

Folder naming

• Prefer one consistent convention (kebab-case or framework-standard folder names).
• Name folders by responsibility, not by vague implementation detail.
• Avoid junk-drawer names like misc, common2, helpers-final, or stuff.

File naming

• Follow framework/language conventions when they are meaningful.
• Keep special/reserved files exactly where the framework expects them.
• Use suffixes only when they communicate stable meaning (.test, .spec, .stories, .types).

Public API rules

• If features or packages expose a boundary file, make it explicit and small.
• Do not use wildcard barrels to hide ownership and accidentally widen imports.
• Prefer imports through the intended public boundary rather than deep sibling-folder reach-ins.

Shared promotion rule

Code should move from feature-local to shared only when: 1. it is reused across multiple features/apps, 2. ownership stays clear, 3. the abstraction is stable enough not to churn weekly.

Bad smells

• Deep relative imports crossing sibling features
• Shared folders that contain mostly one-off code
• Route-level files importing random app internals with no public boundary
• Package boundaries that still rely on lots of deep private imports

Repo Shape Decision Guide

Use this quick ladder before proposing a folder tree.

1. Start with the narrowest valid default

• Meta-framework frontend / fullstack app → keep framework routing/layout conventions first.
• Backend service → keep framework/module defaults first.
• Docs repo → organize by reader task and document type.
• Game repo → start from engine-required roots and special folders.

2. Escalate only when a clear pressure appears

3. Delay extraction of shared code

A folder/package becomes shared only when:

• reuse is proven across more than one area,
• its owner is identifiable,
• its public API is small enough to describe,
• moving it will not create a permanent junk drawer.

4. Prefer these top-level buckets

Use only the buckets the repo can explain clearly.

Common valid buckets

• app/ or src/app/ — route/layout entrypoints
• features/ — product or domain slices
• shared/ or ui/ — only truly shared primitives
• apps/ — deployable applications
• packages/ or libs/ — stable shared packages
• docs/ — documentation
• scripts/ — repo utilities and entrypoints
• tools/ — project tooling with clear ownership
• Assets/, Content/, Scenes/, Prefabs/ — game/content structures when engine conventions support them

5. Avoid these anti-patterns

• misc/, common/, helpers/, temp/ with no owner
• top-level folders whose names explain file type but not responsibility
• extracting packages before a stable boundary exists
• barrels at every folder level
• generated or cache folders treated like source architecture

6. Choose the migration scope

• Greenfield: define the target shape up front.
• Incremental: put new work in the new structure first.
• Targeted reorg: move one hot path or feature area; clean old buckets later.

Repo Type Patterns

Frontend / meta-framework app

Default first:

• framework routing/layout conventions
• route colocation
• small intentional shared UI layer

Escalate when:

• components/ and hooks/ stop communicating ownership
• feature work touches UI, state, tests, and data together

Backend service

Default first:

• framework/module/package conventions
• explicit homes for migrations, scripts, jobs, and operational docs

Escalate when:

• one module keeps crossing controllers/services/schemas/jobs unnecessarily
• a global common/ bucket starts owning domain logic

Fullstack monorepo

Default first:

• apps/ + packages/ / libs/
• shared code extracted only after repeated reuse
• docs/scripts/tooling placed as first-class peers when important

Escalate when:

• package boundaries no longer match ownership
• shared packages are mostly wrappers around one app's needs

Docs / ops repo

Default first:

• content organized by user task and document type
• runbooks, architecture notes, onboarding, and reference separated when audiences differ

Escalate when:

• readers cannot predict where a document belongs
• publishing history dominates the folder tree

Game-development repo

Default first:

• engine-required roots and special folders
• clear separation of scenes/levels, prefabs/assets, scripts/tools, and generated outputs
• naming and ownership rules for cross-discipline collaboration

Escalate when:

• asset sprawl makes ownership unclear
• feature/system grouping is needed on top of engine-required buckets

Boundary reminders

• codebase-search finds current files; it does not design structure.
• workflow-automation enforces or scaffolds a chosen structure; it does not choose the structure.
• system-environment-setup makes the repo runnable; it does not decide folder ownership.
• state-management and design-system own subsystem-specific structure inside a broader repo shape.