project-folder-structure

プロジェクトのフォルダー構成

クイックスタート

複雑なプロジェクトでは、まずローカルルールを読み、次に同梱のヘルパーを使って構成を定量的に把握します。

node scripts/structure-snapshot.mjs --root /path/to/project --max-depth 3

編集前に監査結果を提示します。スキャンした範囲、ローカルの規約、変更できない制約、ファイルが集中している領域、ライフサイクルが混在している箇所、曖昧な名前、提案する整理軸、最小限で安全な変更単位、移行リスク、検証コマンドを含めてください。

基本ルール

パターンを適用する前に、プロジェクトの現状を尊重してください。適切な整理によって、フレームワークのルール、公開契約、生成されるパス、永続化された状態、ローカルの規約を保ちながら、人がプロジェクトを理解、変更、テスト、運用、アーカイブしやすくします。

ワークフロー

1. 対象範囲を定義します。ワークスペース、リポジトリ、パッケージ、アプリ領域、機能、ドキュメントツリー、データ／成果物領域、または混在したモノレポから選びます。
2. ローカルの情報を確認します。AGENTS.md、CLAUDE.md、README.md、CONTRIBUTING.md、CONTEXT.md、ドキュメント、ADR、マニフェスト、CI、デプロイ設定、スクリプト、既存の整理メモを読みます。
3. 構成を提案する前に、変更できないパスやリスクの高いパスを特定します。フレームワークの特別なパス、公開 API、パッケージのエクスポート、ルート、CLI コマンド、マイグレーション、生成されたクライアント、デプロイパス、永続化された成果物、ランタイム状態、シークレット、外部の利用者が依存するパスが該当します。
4. scripts/structure-snapshot.mjs または同等の、名前と件数を調べる読み取り専用スキャンを実行します。シークレットの内容は確認しないでください。
5. 現在のフォルダーを整理軸に沿って分類します。外部制約、概念／機能、変更パターン、対象者／利用者、成果物のライフサイクル、所有権、ステータス、ツールチェーンのレイヤーが軸になります。
6. プロジェクトの理解や変更の方法に最も合う軸を選びます。ローカルまたは外部の制約で必要な場合を除き、まとめて変更されるファイルは近くに配置することを優先します。
7. 有用性を保てる最小限の変更単位を提案します。ファイルが集中したフォルダー、1 つの概念、1 つのライフサイクルの分割、1 つのパッケージ、1 つのワークスペース整理、またはドキュメント／アセットの移動が該当します。
8. 編集前に、移動するもの、安定したまま維持するもの、残すラッパーやリダイレクト、互換性の維持方法を明示します。
9. 編集後に、インポート、CLI パス、ドキュメント、テスト、パッケージ／設定の参照、生成されたマニフェスト、CI、アーキテクチャのガードを更新します。
10. プロジェクト標準のチェック、対象を絞ったテスト、旧パスの検索、利用可能な場合は git diff --check で検証します。

判断基準

• 作業が製品領域、ドメイン用語、ユーザーワークフロー、再利用可能なコンポーネント、安定した責務ごとに変わる場合は、概念／機能別のフォルダーを使います。
• 利用者が小規模で相互に置き換え可能なツール、アダプター、テンプレート、プラグイン、ポリシー、サンプルから選ぶ場合は、ツールボックス用フォルダーを使います。
• ソース、テスト、ドキュメント、アセット、生成ファイル、ランタイム状態、レポート、データセット、実験、アーカイブ、一時作業で保持ルールが異なる場合は、ライフサイクル別のフォルダーを使います。
• 公開サンプル、SDK の公開面、運用スクリプト、内部実装、コントリビューター向けドキュメントを別々に配置する必要がある場合は、対象者別のフォルダーを使います。
• ワークスペース全体の整理には、ステータス別のフォルダーを使います。例として、アクティブ、アーカイブ済み、外部、フォーク、実験、非推奨、クライアント／プロジェクトの所有権があります。
• 言語、フレームワーク、ビルドツール、デプロイ先、コントリビューターのワークフローによって、その構成が最も明確または必須となる場合に限り、レイヤー／ツールチェーン別のフォルダーを使います。
• helpers、services、managers、misc、utils のように、実際の概念を隠したり、無関係なファイルをまとめたりする、種類だけに基づく分類は避けます。
• エントリーポイントは薄く、安定させます。外部の呼び出し元、パッケージスクリプト、URL、cron ジョブ、ユーザーの習慣、永続化されたパスが旧位置に依存している場合は、実装をエントリーポイントの背後に移します。
• プロジェクトに明記された理由がない限り、生成物、ランタイム出力、キャッシュ、一時ファイル、大容量の成果物はソースフォルダーに置きません。
• 原則として削除しません。移動計画、アーカイブ／隔離先、保持ルール、またはユーザーの明示的な承認を優先します。

承認ゲート

以下のいずれかに該当する場合は、適用する前に確認してください。

• 複数のドメイン／パッケージ／ワークスペース領域を同時に移動する場合。
• 公開インポート、ルート、CLI コマンド、パッケージのエクスポート、URL、cron ペイロード、データパス、永続化されたアーティファクトのパスが変更される場合。
• 秘密情報、認証設定、デプロイ設定、マイグレーション、データベースの状態、生成物の保持、バックアップ、または大規模なデータに影響する場合。
• ローカルの規約とツール／フレームワークのドキュメントが矛盾する場合。
• 根拠に基づく保守性ではなく、主に見た目を理由とする場合。

出力形式

次の簡潔な形式を使用してください。

## Structure Audit
- Scope scanned:
- Local rules read:
- Immovable constraints:
- Current organizing axes:
- Crowded or mixed-lifecycle areas:
- Ambiguous/generic folders:

## Proposed Batch
- Organizing axis:
- Move:
- Keep stable:
- Wrappers/redirects:
- Docs/config to update:
- Risks:
- Verification:

詳細な原則については、REFERENCE.md をご覧ください。プロジェクトの種類ごとのガイダンスについては、PROJECT_TYPES.md をご覧ください。移動表の例については、EXAMPLES.md をご覧ください。