file-organizer（文件整理）

File Organizer

Overview

Design and maintain well-organized project structures that scale with team and codebase growth. This skill covers monorepo patterns, feature-based vs layer-based architecture, naming conventions, index/barrel files, configuration file placement, and documentation structure.

Apply this skill whenever a project's file organization needs to be established, audited, or restructured for clarity and scalability.

Multi-Phase Process

Phase 1: Assessment

1. Audit current project structure and identify pain points
2. Measure project size (file count, team size, feature count)
3. Identify existing naming conventions and import patterns
4. Catalog configuration file locations
5. Check for circular dependencies or deep nesting

STOP — Do NOT propose a new structure without understanding the current state and its pain points.

Phase 2: Strategy Selection

1. Choose organization strategy using decision table below
2. Define naming conventions and file placement rules
3. Plan barrel export boundaries
4. Establish configuration file placement rules
5. Document import ordering convention

STOP — Do NOT begin migration without documenting the target structure and getting team alignment.

Phase 3: Migration Planning

1. Plan migration path for existing projects (incremental, not big-bang)
2. Identify files that move and their new locations
3. Map import changes required
4. Create automated codemods where possible
5. Define rollback plan if migration causes issues

STOP — Do NOT execute migration without verifying tests pass at each incremental step.

Phase 4: Execution and Validation

1. Move one feature or module at a time
2. Update imports using automated tools
3. Verify tests pass after each move
4. Remove old structure after complete migration
5. Document conventions for team reference

Architecture Strategy Decision Table

Architecture Patterns

Feature-Based (Domain-Driven)

Organize by business domain. Each feature is self-contained.

src/
  features/
    auth/
      components/
        LoginForm.tsx
        SignupForm.tsx
      hooks/
        useAuth.ts
      api/
        auth.api.ts
      types/
        auth.types.ts
      utils/
        auth.utils.ts
      __tests__/
        auth.test.ts
      index.ts          # Public API (barrel export)
    dashboard/
      components/
      hooks/
      api/
      types/
      index.ts
    billing/
      ...
  shared/               # Cross-feature shared code
    components/
      Button.tsx
      Modal.tsx
    hooks/
      useDebounce.ts
    utils/
      format.ts
    types/
      common.types.ts

Best for: Teams > 5 developers, medium-large applications, clear domain boundaries.

Layer-Based (Technical)

Organize by technical concern.

src/
  components/
    Button.tsx
    Modal.tsx
    LoginForm.tsx
    DashboardCard.tsx
  hooks/
    useAuth.ts
    useDebounce.ts
  services/
    auth.service.ts
    billing.service.ts
  utils/
    format.ts
    validation.ts
  types/
    auth.types.ts
    billing.types.ts
  pages/
    Home.tsx
    Dashboard.tsx

Best for: Small teams (1-3), simple applications, rapid prototyping.

Hybrid (Recommended Default)

Combine both: shared layer + feature modules.

src/
  app/                  # App-level concerns
    layout.tsx
    providers.tsx
    routes.tsx
  features/             # Feature modules
    auth/
    dashboard/
    billing/
  components/           # Shared UI components
    ui/                 # Design system atoms
    layout/             # Layout components
  hooks/                # Shared hooks
  lib/                  # Shared utilities
  types/                # Shared types
  config/               # App configuration
  styles/               # Global styles

Monorepo Patterns

Turborepo / pnpm Workspaces

root/
  apps/
    web/                # Next.js web app
      package.json
    api/                # API server
      package.json
    mobile/             # React Native app
      package.json
  packages/
    ui/                 # Shared component library
      package.json
    config/             # Shared configs (ESLint, TypeScript)
      eslint/
      typescript/
      package.json
    utils/              # Shared utilities
      package.json
    types/              # Shared type definitions
      package.json
  package.json          # Root workspace config
  turbo.json            # Turborepo pipeline config
  pnpm-workspace.yaml

Package Boundaries

• Apps depend on packages, never on other apps
• Packages can depend on other packages
• No circular dependencies
• Each package has a clear, single responsibility
• Shared packages export via index.ts barrel

Configuration Sharing

// packages/config/typescript/base.json
{
  "compilerOptions": {
    "strict": true,
    "moduleResolution": "bundler",
    "target": "ES2022"
  }
}

// apps/web/tsconfig.json
{
  "extends": "@repo/config/typescript/nextjs",
  "include": ["src"]
}

Naming Conventions

Files and Directories

Component File Naming

# Single-file component
Button.tsx

# Component with co-located files
Button/
  Button.tsx
  Button.test.tsx
  Button.stories.tsx
  Button.module.css
  index.ts            # Re-exports Button

Import Ordering Convention

// 1. External packages
import React from 'react';
import { useQuery } from '@tanstack/react-query';

// 2. Internal packages (monorepo)
import { Button } from '@repo/ui';

// 3. Feature-level imports
import { useAuth } from '@/features/auth';

// 4. Relative imports (same feature)
import { LoginForm } from './LoginForm';
import { authSchema } from './auth.types';

// 5. Styles
import styles from './Auth.module.css';

Index Files and Barrel Exports

Barrel Export Pattern

// features/auth/index.ts — Public API
export { LoginForm } from './components/LoginForm';
export { useAuth } from './hooks/useAuth';
export type { User, AuthState } from './types/auth.types';

// Do NOT export internal implementation details
// Do NOT export utility functions used only within the feature

Barrel Export Decision Table

Configuration File Placement

Root-Level Configuration

root/
  .editorconfig         # Editor settings
  .eslintrc.js          # ESLint config (or eslint.config.js)
  .gitignore            # Git ignore rules
  .prettierrc           # Prettier config
  .env.example          # Environment variable template
  docker-compose.yml    # Docker composition
  Dockerfile            # Container build
  package.json          # Dependencies and scripts
  tsconfig.json         # TypeScript config
  next.config.js        # Framework config
  tailwind.config.ts    # Tailwind config
  vitest.config.ts      # Test config

Environment Files

.env                    # Local defaults (gitignored)
.env.example            # Template with dummy values (committed)
.env.local              # Local overrides (gitignored)
.env.development        # Development-specific (committed or not)
.env.production         # Production-specific (committed or not)
.env.test               # Test-specific (committed or not)

Documentation Structure

docs/
  architecture/
    adr/                # Architecture Decision Records
      001-framework.md
      002-database.md
    diagrams/
  api/                  # API documentation
  guides/
    getting-started.md
    deployment.md
  contributing.md

Migration Strategy

Incremental Migration (Recommended)

1. Create the target structure alongside existing code
2. Move one feature/module at a time
3. Update imports using automated codemods
4. Verify with tests after each move
5. Remove old structure after complete migration

Automated Tools

• ts-morph: programmatic TypeScript refactoring
• jscodeshift: JavaScript codemods
• IDE refactoring: rename/move with automatic import updates
• ESLint import/order: enforce import ordering

Anti-Patterns / Common Mistakes

Anti-Rationalization Guards

• Do NOT restructure without understanding current pain points -- assess first.
• Do NOT skip the team alignment step -- structure changes affect everyone.
• Do NOT migrate everything at once -- move one module at a time with test verification.
• Do NOT create deeply nested structures "for future scalability" -- flatten until complexity demands it.
• Do NOT ignore barrel export impact on bundle size -- verify with bundle analyzer.

Integration Points

Skill Type

FLEXIBLE — Choose the organization strategy that fits the project's size, team structure, and complexity. The naming conventions and barrel export patterns are recommendations that should be adapted to existing project conventions.