プロジェクト構造

プロジェクトのフォルダー構造を業界標準に合わせて整理するスキルです。

コア原則

「デスクトップにコードを置かない」 「分類基準を混ぜない」

安全ルール

整理方法

# ❌ NEVER: 削除
rm -rf old-folder

# ✅ ALWAYS: レガシーフォルダーへ移動
mkdir -p _legacy
mv old-folder _legacy/old-folder_$(date +%Y%m%d)

Part 1: 開発ルートディレクトリ

推奨ルート位置

~/dev        # 最も推奨
~/code
~/workspace
~/git

コンテキスト（目的）中心構造 (推奨)

~/dev/
├── work/              # 会社業務
│   ├── company-a/
│   │   ├── backend-api/
│   │   └── frontend-ui/
│   └── company-b/
├── personal/          # 個人/サイドプロジェクト
│   ├── my-blog/
│   └── todo-app/
├── study/             # 講義/書籍の実習
│   ├── algorithm-101/
│   └── react-course/
├── open-source/       # Fork/貢献プロジェクト
│   └── some-lib/
├── playground/        # 一時的なテスト (サンドボックス)
│   └── test-script.py
└── dotfiles/          # 個人設定ファイルのバージョン管理

ホスト(Source)中心構造 (Goスタイル)

~/dev/
├── github.com/
│   ├── my-username/
│   │   └── project-a/
│   └── other-user/
│       └── awesome-lib/
├── gitlab.com/
│   └── company-group/
│       └── company-project/
└── bitbucket.org/

Part 2: プロジェクト内部構造

基本プロジェクトスキャフォールディング

project-name/
├── src/              # 実際のソースコード
├── assets/           # 画像、フォント、静的ファイル
├── config/           # 設定ファイル
├── docs/             # ドキュメント資料
├── scripts/          # ビルド/デプロイスクリプト
├── tests/            # テストコード
├── dist/             # ビルド成果物 (Git除外)
├── _legacy/          # 整理されたレガシーコード
├── .gitignore
├── .env.example      # 環境変数例 (.envはGit除外)
├── README.md
└── LICENSE

Part 3: フロントエンドアーキテクチャパターン

Pattern A: Next.js App Router + Colocation

ルート（ページ）を基準にフォルダーを作成し、必要なファイルを同じフォルダーに配置します。

app/
├── (marketing)/           # Route Group (URLには反映されません)
│   ├── page.tsx
│   ├── components/        # このルート専用コンポーネント
│   │   └── Hero.tsx
│   └── styles.css
├── dashboard/
│   ├── layout.tsx
│   ├── page.tsx
│   ├── loading.tsx
│   ├── error.tsx
│   └── components/
│       ├── DashboardHeader.tsx
│       └── DashboardStats.tsx
├── api/
│   └── users/
│       └── route.ts
└── globals.css
lib/                       # 共通ユーティリティ
components/                # グローバル共通コンポーネント

適切な場合: Next.jsベースのプロジェクト

Pattern B: Bulletproof React (Feature-based)

機能（Feature）単位でまとめて保守しやすい構造です。

src/
├── app/                   # アプリ初期化 (ルーター、エントリー、グローバル設定)
│   ├── routes/
│   ├── App.tsx
│   └── main.tsx
├── assets/
├── components/            # 完全共通UI
│   ├── Button/
│   ├── Modal/
│   └── Form/
├── config/
├── features/              # 🔑 核心: 機能単位
│   ├── auth/
│   │   ├── api/
│   │   ├── components/
│   │   ├── hooks/
│   │   ├── types/
│   │   └── index.ts
│   ├── users/
│   │   ├── api/
│   │   ├── components/
│   │   ├── hooks/
│   │   └── index.ts
│   └── dashboard/
├── hooks/                 # グローバルフック
├── lib/                   # 外部ライブラリラッパー
├── providers/
├── stores/
├── testing/
├── types/                 # グローバル型
└── utils/                 # グローバルユーティリティ

適切な場合: チーム規模が大きい、または機能が多いReactプロジェクト

Pattern C: Feature-Sliced Design (FSD)

階層（Layer）で分類するアーキテクチャ手法です。

src/
├── app/                   # Layer 1: アプリ初期化
│   ├── providers/
│   ├── styles/
│   └── index.tsx
├── pages/                 # Layer 2: ページ (ルート)
│   ├── home/
│   ├── profile/
│   └── settings/
├── widgets/               # Layer 3: 独立したUIブロック
│   ├── header/
│   ├── sidebar/
│   └── footer/
├── features/              # Layer 4: ユーザーシナリオ
│   ├── auth/
│   ├── comments/
│   └── likes/
├── entities/              # Layer 5: ビジネスエンティティ
│   ├── user/
│   ├── post/
│   └── comment/
└── shared/                # Layer 6: 共有リソース
    ├── ui/
    ├── lib/
    ├── api/
    └── config/

適切な場合: チームがルールを一緒に守れる中規模から大規模プロジェクト

Part 4: ハイブリッドパターン (Next.js + Feature)

Next.js App Routerを骨格とし、features方式を組み合わせた実用的な構造です。

app/                       # Next.js App Router
├── (marketing)/
├── dashboard/
└── api/
src/
├── components/            # グローバル共通コンポーネント
├── features/              # Bulletproofスタイルの機能単位
│   ├── auth/
│   ├── users/
│   └── analytics/
├── hooks/
├── lib/
├── types/
└── utils/

Workflow: フォルダー整理

1. 現在の構造分析

# 最上位フォルダーの確認
ls -la

# ツリー構造の確認 (2段階)
find . -maxdepth 2 -type d | head -30

2. レガシーフォルダーの作成

mkdir -p _legacy

3. 整理対象の移動

# 日付タグを付けて移動
mv messy-folder _legacy/messy-folder_$(date +%Y%m%d)

4. 新しい構造の作成

# Bulletproof構造の例
mkdir -p src/{app,assets,components,config,features,hooks,lib,types,utils}
mkdir -p src/features/{auth,users}/{api,components,hooks,types}

5. ファイルの移動

# 機能別にファイルを移動
mv src/components/LoginForm.tsx src/features/auth/components/
mv src/hooks/useAuth.ts src/features/auth/hooks/

Naming Conventions

Anti-patterns

❌ 言語別分類
~/dev/python/
~/dev/javascript/
→ React + Djangoプロジェクトはどこに？

❌ デスクトップの使用
~/Desktop/新しいフォルダー/test1/asdf/
→ ~/dev/playground/ を使用

❌ スペースを含むフォルダー名
My Project/
→ my-project/

❌ タイプ別のみの分類 (規模が大きい場合)
src/
├── components/  # 100個のコンポーネント
├── hooks/       # 50個のフック
└── utils/       # 30個のユーティリティ
→ features/ 単位でグループ化

Quick Setup Scripts

macOS/Linux: 開発ルートの作成

mkdir -p ~/dev/{work,personal,study,open-source,playground,dotfiles}

プロジェクトスキャフォールディング

# プロジェクトの基本構造
mkdir -p {src,assets,config,docs,scripts,tests,_legacy}
touch README.md .gitignore .env.example

Bulletproof React構造

mkdir -p src/{app/routes,assets,components,config,features,hooks,lib,providers,stores,testing,types,utils}

References

• Next.js Project Structure
• [Bulletproof React](https://github.com/alan2207/bulletpro