Vibe Codingに最適なNext.jsのディレクトリ構成を整理しました。
前回の記事の続きとなります。
（シリーズとしてはweb3領域を念頭に置いていますが、通常のプロダクト開発にも適用可能です）
はじめに
Claude CodeのようなAI開発ツールを実用するためには、 事前準備が寛容です。
- 要件定義
- 技術選定
- プロジェクト構造
本記事では、Claude CodeなどのAgentic CodingによるMVP開発に最適なNext.js（App Router）ディレクトリ構成を提案します。
僕はClaude Codeをメインで使用していますが、他のAgentic Codingツール（CursorやClineなど）にも使用できます。
「AI開発を効率化するための事前準備」のノウハウが変わることはありません。なぜならそれはシステム開発の基本に過ぎないからです。
対象読者
本記事は以下のような方にお勧めです。
- 効率的なAI開発フローを模索したいエンジニア
- 技術選定に悩んでいるPM
- 素早くMVPを開発したいハッカソン参加者
特に、最速で仮説検証用MVPを開発したい方に有用です。あるいはソロプレナーなど。
また、FBやTipsをシェアは大歓迎なので、ぜひお気軽にコメントしてください。「ここはバッドプラクティスでは？」などのツッコミもぜひ。
docs/directory-structure.md
英語と日本語両方で用意していますが、LLMに与えるときには英語を使用してください。
# Directory Structure Guide
## Project Root
```plaintext
my-dapp-project/
├── .claude/ # 🤖 Claude AI settings
│ ├── project-context.md # Project context
│ ├── prompts/ # Custom prompts
│ ├── contexts/ # Feature contexts
│ └── workflows/ # Development workflows
├── .github/ # 🔧 GitHub settings
├── .vscode/ # 📝 VSCode settings
├── docs/ # 📚 Documentation
│ ├── ui-design-system.md # UI design guide
│ ├── state-management.md # State management guide
│ └── directory-structure.md # This file
├── public/ # 🌐 Static files
│ ├── favicon.ico
│ ├── logo.svg
│ └── og-image.png
├── src/ # 💻 Application source
├── .env.example # 📋 Environment template
├── CLAUDE.md # 🤖 Claude Code info
├── README.md # 📖 Project overview
├── components.json # 🎨 shadcn/ui config
├── next.config.ts # ⚡ Next.js config
├── package.json # 📦 Package info
├── tailwind.config.ts # 🎨 Tailwind config
└── tsconfig.json # 📘 TypeScript config
```
## src/ Directory
```plaintext
src/
├── app/ # 🚀 Next.js App Router
│ ├── mint/
│ │ └── [id]/page.tsx # Dynamic routes
│ ├── about/page.tsx
│ ├── profile/page.tsx
│ ├── globals.css # Global styles
│ ├── layout.tsx # Root layout
│ └── page.tsx # Home page
│
├── components/ # 🧩 Reusable components
│ ├── layout/ # Layout components
│ │ ├── Header.tsx
│ │ ├── HeaderNavigation.tsx
│ │ └── Footer.tsx
│ ├── providers/ # Context providers
│ ├── shared/ # Cross-feature shared
│ └── ui/ # shadcn/ui components
│
├── constants/ # 📋 Constants & config
│ ├── chain-info/ # Blockchain info
│ ├── contracts/ # Smart contract info
│ ├── meta/ # SEO & social meta
│ │ ├── brand-copy.ts
│ │ ├── site-metadata.ts
│ │ ├── social-links.ts
│ │ └── external-links.ts
│ ├── common/ # Common constants
│ └── index.ts # Unified exports
│
├── features/ # 🎛️ Feature modules
│ └── mint/ # Mint feature package
│ ├── components/ # Feature components
│ ├── hooks/ # Feature hooks
│ ├── types/ # Feature types
│ └── utils/ # Feature utilities
│
├── hooks/ # 🎣 Global shared hooks
├── lib/ # 📚 Libraries & utilities
├── stores/ # 🏪 Zustand state management
├── types/ # 📝 Global type definitions
└── utils/ # 🔧 Global utilities
```
## Key Principles
### 1. Feature-Based Organization
- Group related functionality in `features/`
- Each feature is self-contained
- Cross-feature sharing goes to `components/shared/`
### 2. Next.js App Router
- `app/` for routing only
- Business logic in `features/` and `components/`
- Server/Client components clearly separated
### 3. State Management
- `stores/` for Zustand global state
- Feature-specific state in `features/[name]/hooks/`
- Component state with `useState`
### 4. Shared Resources
- `components/ui/` for shadcn/ui components
- `components/shared/` for cross-feature components
- `constants/` for application-wide constants
- `types/` for global TypeScript definitions
### 5. Development Tools
- `.claude/` for AI-assisted development
- `.vscode/` for team editor settings
- `docs/` for design guides and specifications
## File Naming Conventions
| Type | Pattern | Example |
| ---------- | ----------------- | ------------------ |
| Components | PascalCase | `WalletButton.tsx` |
| Hooks | camelCase | `useMintForm.ts` |
| Utilities | camelCase | `formatAddress.ts` |
| Constants | UPPER_SNAKE_CASE | `CHAIN_INFO.ts` |
| Types | PascalCase | `MintState.ts` |
| Stores | camelCase + Store | `mintStore.ts` |
## Import Conventions
```typescript
// Absolute imports with path mapping
import { Button } from "@/components/ui/button";
import { useMintStore } from "@/stores/mintStore";
import { CHAIN_INFO } from "@/constants/chain-info";
// Feature imports
import { MintForm } from "@/features/mint/components/MintForm";
import { useMintForm } from "@/features/mint/hooks/useMintForm";
```
## Best Practices
### Do
- Keep features self-contained
- Use TypeScript for all files
- Export from index files for clean imports
- Group related constants together
- Separate business logic from UI components
### Don't
- Mix feature logic across directories
- Create deep nesting (max 3 levels)
- Put business logic in `app/` directory
- Skip TypeScript types
- Create circular dependencies
This structure supports scalable Web3 dApp development with clear separation of concerns and optimal Claude Code integration.
docs/ja/directory-structure.md
# ディレクトリ構成ガイド
## プロジェクトルート
```plaintext
my-dapp-project/
├── .claude/ # 🤖 Claude AI 設定
│ ├── project-context.md # プロジェクトコンテキスト
│ ├── prompts/ # カスタムプロンプト
│ ├── contexts/ # 機能コンテキスト
│ └── workflows/ # 開発ワークフロー
├── .github/ # 🔧 GitHub 設定
├── .vscode/ # 📝 VSCode 設定
├── docs/ # 📚 ドキュメント
│ ├── ui-design-system.md # UI デザインガイド
│ ├── state-management.md # 状態管理ガイド
│ └── directory-structure.md # ディレクトリ構成
├── public/ # 🌐 静的ファイル
│ ├── favicon.ico
│ ├── logo.svg
│ └── og-image.png
├── src/ # 💻 アプリケーションソース
├── .env.example # 📋 環境変数テンプレート
├── CLAUDE.md # 🤖 Claude Code 情報
├── README.md # 📖 プロジェクト概要
├── components.json # 🎨 shadcn/ui 設定
├── next.config.ts # ⚡ Next.js 設定
├── package.json # 📦 パッケージ情報
├── tailwind.config.ts # 🎨 Tailwind 設定
└── tsconfig.json # 📘 TypeScript 設定
```
## src/ ディレクトリ
```plaintext
src/
├── app/ # 🚀 Next.js App Router
│ ├── mint/
│ │ └── [id]/page.tsx # 動的ルート
│ ├── about/page.tsx
│ ├── profile/page.tsx
│ ├── globals.css # グローバルスタイル
│ ├── layout.tsx # ルートレイアウト
│ └── page.tsx # ホームページ
│
├── components/ # 🧩 再利用可能コンポーネント
│ ├── layout/ # レイアウトコンポーネント
│ │ ├── Header.tsx
│ │ ├── HeaderNavigation.tsx
│ │ └── Footer.tsx
│ ├── providers/ # コンテキストプロバイダー
│ ├── shared/ # 機能横断で共有
│ └── ui/ # shadcn/ui コンポーネント
│
├── constants/ # 📋 定数と設定
│ ├── chain-info/ # ブロックチェーン情報
│ ├── contracts/ # スマートコントラクト情報
│ ├── meta/ # SEO とソーシャルメタ
│ │ ├── brand-copy.ts
│ │ ├── site-metadata.ts
│ │ ├── social-links.ts
│ │ └── external-links.ts
│ ├── common/ # 共通定数
│ └── index.ts # 統一エクスポート
│
├── features/ # 🎛️ 機能モジュール
│ └── mint/ # ミント機能パッケージ
│ ├── components/ # 機能コンポーネント
│ ├── hooks/ # 機能フック
│ ├── types/ # 機能型定義
│ └── utils/ # 機能ユーティリティ
│
├── hooks/ # 🎣 グローバル共有フック
├── lib/ # 📚 ライブラリとユーティリティ
├── stores/ # 🏪 Zustand 状態管理
├── types/ # 📝 グローバル型定義
└── utils/ # 🔧 グローバルユーティリティ
```
## 主要原則
### 1. feature ベース構成
- `features/` で関連機能をグループ化
- 各機能は自己完結型
- 機能横断で共有は `components/shared/` や `hooks/`へ
### 2. Next.js App Router
- `app/` はルーティングのみ
- ビジネスロジックは `features/` と `components/` へ
- Server/Client コンポーネントを明確に分離
### 3. 状態管理
- `stores/` で Zustand グローバル状態
- 機能固有の状態は `features/[name]/hooks/` へ
- コンポーネント状態は `useState` で
### 4. 共有リソース
- `components/ui/` で shadcn/ui コンポーネント
- `components/shared/` で機能横断コンポーネント
- `constants/` でアプリケーション全体の定数
- `types/` でグローバル TypeScript 定義
### 5. 開発ツール
- `.claude/` で AI 支援開発
- `.vscode/` でチームエディター設定
- `docs/` でデザインガイドと仕様書
## ファイル命名規約
| 種類 | パターン | 例 |
| -------------- | ----------------- | ------------------ |
| コンポーネント | PascalCase | `WalletButton.tsx` |
| フック | camelCase | `useMintForm.ts` |
| ユーティリティ | camelCase | `formatAddress.ts` |
| 定数 | UPPER_SNAKE_CASE | `CHAIN_INFO.ts` |
| 型定義 | PascalCase | `MintState.ts` |
| ストア | camelCase + Store | `mintStore.ts` |
## インポート規約
```typescript
// パスマッピングでの絶対インポート
import { Button } from "@/components/ui/button";
import { useMintStore } from "@/stores/mintStore";
import { CHAIN_INFO } from "@/constants/chain-info";
// 機能インポート
import { MintForm } from "@/features/mint/components/MintForm";
import { useMintForm } from "@/features/mint/hooks/useMintForm";
```
## ベストプラクティス
### すべきこと
- 機能を自己完結型に保つ
- すべてのファイルで TypeScript を使用
- クリーンなインポートのためにインデックスファイルからエクスポート
- 関連する定数をグループ化
- ビジネスロジックを UI コンポーネントから分離
### すべきでないこと
- ディレクトリをまたいで機能ロジックを混在させる
- 深いネストを作る（最大 3 レベル）
- `app/` ディレクトリにビジネスロジックを配置
- TypeScript 型を省略
- 循環依存を作成
この構成は、関心の分離が明確で Claude Code との統合が最適化された、スケーラブルな Web3 dApp 開発をサポートします。
ディレクトリ構成の方針
本構成は以下の方針に基づいて設計しています。
MVP開発に特化した構成
MVP開発やハッカソン開発に最適化し、必要最小限の機能から始めて段階的に拡張できる構造を採用。
過度に複雑な抽象化は避け、直感的でわかりやすい配置を重視。
機能別パッケージ化
オーソドックスなfeatures/パターンを採用。
機能ごとに独立したモジュールを管理し、コンポーネント・フック・型定義を一箇所に集約。
機能の追加・削除が容易になり、AIへのタスク依頼もしやすい。
（人間時代はbullet-proof-reactなど採用していたが廃した。AI開発には適さないため）
静的ツールやエディタ設定
GitHub、VSCode、ESLint、Prettierなどの設定をきちんと行う。
チーム開発にも有用だが、むしろAIに対して特に有効。コード品質を保つことが開発効率に直結する。
Claude Code連携の最適化
LLMが解釈・理解しやすい命名規則と、機能別のモジュール化を徹底。
また、.claude/や docs/ でコンテキスト管理を行い、開発効率を最大化する
参考
シリーズ記事
Claude Codeを使用した開発フロー（特にdApps）に最適なテンプレートを構築中で、各項目についてメモを残しています。
- Claude Code x MVP開発に最適なdApps要求定義
- Claude Code x MVP開発に最適なNext.jsディレクトリ構成
- Claude Code x MVP開発に最適なUXデザインガイド
- Claude Code x MVP開発に最適なNext.jsの状態管理パターン [Zustand, React Hook Form, TanStack Query]
- Claude Code x MVP開発の作業フロー（のメモ）
- AO dApps × Next.jsのnpmライブラリ選定 [2025年]
- EVM dApps x Next.jsのnpmライブラリ選定 [2025 年]
- Solana dApps × Next.jsのnpmライブラリ選定 [2025年]
参考文献
『LLMのプロンプトエンジニアリング ―GitHub Copilotを生んだ開発者が教える生成AIアプリケーション開発』
『生成AIのプロンプトエンジニアリング ―信頼できる生成AIの出力を得るための普遍的な入力の原則』
『開発者とアーキテクトのためのコミュニケーションガイド ―パターンで学ぶ情報伝達術』