テクニカルライター、平易な言葉によるプロジェクト文書担当

# FORME.md ## 1. 全体像（プロジェクト概要） **プロジェクト名:** ${name} **エグゼクティブサマリー:** このプロジェクトは、[プロジェクトの目的を一文で]を実現するためのシステムです。ユーザーは[主要なユーザーアクション]を通じてサービスを利用し、その背後では複数のコンポーネントが連携して動作しています。このドキュメントを読めば、コードを読めなくても、システム全体がどのように動いているか、なぜそのように設計されたのかを理解できます。 ### 解決する課題と対象ユーザー このプロジェクトが解決するのは、[課題の具体的な説明]です。対象となるユーザーは[ユーザー像]で、彼らは[現在の課題]に直面しています。 ### ユーザージャーニー ユーザーがこのサービスを利用する流れは次のとおりです： 1. **入口:** ユーザーが[ランディングページ/アプリ]にアクセスする 2. **認証:** アカウントを作成/ログインする 3. **主要アクション:** [サービスの中核となる操作]を行う 4. **結果:** [ユーザーが得る価値]を受け取る 5. **継続利用:** [リピート利用のきっかけ]によって再訪する ### レストランに例えると このシステム全体をレストランに例えるなら： - **フロント（ユーザーインターフェース）** は、お客様が注文を伝えるテーブルとウェイターです - **キッチン（API/バックエンド）** は、実際に料理を作る調理場です - **食材庫（データベース）** は、材料を保管する冷蔵庫とパントリーです - **レジ（決済システム）** は、お会計を処理する場所です - **シェフ（サーバー/インフラ）** は、全体の流れを統括する責任者です --- ## 2. 技術アーキテクチャ - 設計図 ### システム構成図 ``` ┌─────────────────────────────────────────────────────────┐ │ ユーザー（ブラウザ/アプリ） │ └────────────────────────┬────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────┐ │ フロントエンド（UI層） │ │ [ユーザーが見る画面・操作する部分] │ └────────────────────────┬────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────┐ │ API層（バックエンド） │ │ [ビジネスロジック・処理の中心] │ └─────────┬──────────────────────────────┬────────────────┘ │ │ ▼ ▼ ┌──────────────────┐ ┌──────────────────────────┐ │ データベース層 │ │ 外部サービス連携層 │ │ [データの保存] │ │ [決済・メール・認証など] │ └──────────────────┘ └──────────────────────────┘ ``` ### 各層の説明（建物ツアー風） #### フロントエンド層 - 「お客様が座るダイニングルーム」 ここはユーザーが直接目にし、触れる部分です。ボタンをクリックしたり、フォームに入力したり、情報を閲覧したりするすべての操作はこの層で行われます。 **なぜこの設計なのか:** フロントエンドを独立した層として分離することで、デザイン変更や機能追加がバックエンドに影響を与えずに行えます。レストランで言えば、内装を変えてもキッチンの設備を変える必要がないのと同じです。 #### API層 - 「料理を作るキッチン」 ここがシステムの心臓部です。フロントエンドからリクエスト（注文）を受け取り、必要な処理（調理）を行い、結果を返します。ビジネスルール（「会員は送料無料」など）はすべてここで適用されます。 **なぜこの設計なのか:** ビジネスロジックを一箇所に集中させることで、ルール変更が一箇所の修正で済みます。また、将来モバイルアプリを追加する場合も、同じキッチン（API）を使い回せます。 #### データベース層 - 「食材を保管する冷蔵庫」 すべてのデータ（ユーザー情報、注文履歴、設定など）がここに保存されます。データは構造化されており、必要なときに素早く取り出せるようになっています。 **なぜこの設計なのか:** データを一元管理することで、バックアップ、セキュリティ、整合性の確保が容易になります。各テーブルがファイルキャビネットの引き出しのようなもので、関連する情報が整理されています。 #### 外部サービス連携層 - 「仕入れ先との取引窓口」 決済処理、メール配信、SMS認証など、自社で構築するより専門業者に任せた方が良い機能を外部サービスに委託しています。 **なぜこの設計なのか:** 決済処理を自前で実装すると、セキュリティ基準の準拠（PCI DSSなど）や金融機関との連携に膨大なコストがかかります。専門サービスを使うことで、信頼性を確保しながら開発コストを抑えられます。 ### 開発者が選んだ賢い設計判断 - **[具体的な設計判断1]:** [理由と利点] - **[具体的な設計判断2]:** [理由と利点] --- ## 3. コードベース構造 - ファイリングシステム ### フォルダ構成（上位2〜3階層） ``` ${name}/ ├── src/ # ソースコード本体 │ ├── app/ # アプリケーションのメインエントリポイント │ ├── components/ # 再利用可能なUI部品 │ ├── lib/ # 共通ユーティリティ関数 │ ├── hooks/ # カスタムフック（状態管理の再利用） │ └── styles/ # グローバルスタイル定義 ├── public/ # 静的ファイル（画像、アイコンなど） ├── tests/ # テストコード ├── docs/ # ドキュメント ├── config/ # 設定ファイル └── package.json # プロジェクトの依存関係とスクリプト定義 ``` ### 各フォルダの説明 #### `src/app/` - 「レストランの入口」 アプリケーションの起動点です。ルーティング（どのURLでどの画面を表示するか）の定義がここにあります。新しいページを追加するときは、このフォルダにファイルを追加します。 #### `src/components/` - 「使い回しのできる食器棚」 ボタン、フォーム、カードなど、複数の画面で使い回すUI部品がここにあります。一度作れば、どこでも使えるように設計されています。 #### `src/lib/` - 「便利な調理器具」 日付のフォーマット、データの検証、API呼び出しのヘルパーなど、特定の画面に依存しない共通機能がここにあります。 #### `src/hooks/` - 「状態管理のレシピ集」 Reactのカスタムフック（状態とロジックを再利用する仕組み）がここに集められています。複数のコンポーネントで同じ状態管理ロジックを使いたい場合に活用します。 ### 命名規則の注意点 - **[非自明な命名規則1]:** [説明] - **[非自明な命名規則2]:** [説明] ### エントリポイント - **`src/app/page.tsx`** - トップページのエントリポイント - **`src/app/layout.tsx`** - 全ページ共通のレイアウト定義 - **`src/server/index.ts`** - バックエンドサーバーの起動点 --- ## 4. 接続とデータフロー - システム間の通信 ### ユーザーアクション1: [例：ユーザーがサインアップする] ユーザーが「登録」ボタンをクリックしたとき、舞台裏では次のことが起こります： 1. **フロントエンドが入力データを検証** - メールアドレスの形式が正しいか、パスワードが十分に強いかをチェックします。これはレストランで注文を受ける前に、メニューに載っている料理かどうかを確認するようなものです。 2. **APIリクエストを送信** - 検証済みのデータが`/api/auth/signup`エンドポイントに送信されます。これはウェイターが注文をキッチンに伝えるようなものです。 3. **バックエンドがユーザーを作成** - サーバーは受け取ったデータを検証し、パスワードをハッシュ化（暗号化のようなもの）して、データベースにユーザーを保存します。 4. **認証トークンを発行** - ユーザーのセッションを識別するためのトークン（入場許可証のようなもの）が生成され、フロントエンドに返されます。 5. **確認メールを送信** - 外部メールサービスを通じて、登録確認メールが送信されます。 **失敗時の挙動:** - メールサービスがダウンしている場合：ユーザー登録自体は成功しますが、確認メールが届きません。システムはエラーをログに記録し、再送信の仕組みを提供します。 - データベースがダウンしている場合：ユーザー登録は失敗し、ユーザーには「しばらくしてからお試しください」というメッセージが表示されます。 ### ユーザーアクション2: [例：ユーザーが注文を確定する] 1. **カートの内容を確認** - フロントエンドが現在のカート内容を表示し、合計金額を計算します。 2. **注文APIを呼び出し** - `/api/orders`に注文データが送信されます。 3. **在庫をチェック** - バックエンドがデータベースの在庫テーブルを確認します。これはキッチンが食材の残りを確認するようなものです。 4. **在庫を減らす** - 在庫がある場合、数量を更新します。 5. **決済処理を実行** - 外部決済サービス（Stripeなど）に請求処理を依頼します。 6. **注文確認を返す** - 成功した場合、注文IDと確認メッセージがフロントエンドに返されます。 **失敗時の挙動:** - 決済サービスがダウンしている場合：注文は保留状態になり、ユーザーには「決済処理に失敗しました。もう一度お試しください」と表示されます。在庫は確保されたままなので、再試行時に問題ありません。 - 在庫が不足している場合：注文は拒否され、ユーザーには「申し訳ございません。この商品は在庫切れです」と表示されます。 ### 認証フロー - 「アプリはあなたが誰かをどう知るか」 このシステムでは、JWT（JSON Web Token）ベースの認証を使用しています。仕組みは次のとおりです： 1. **ログイン時:** ユーザーがメールアドレスとパスワードを送信すると、サーバーが検証し、署名付きトークン（改ざん防止の印が付いた身分証明書）を発行します。 2. **以降のリクエスト:** ブラウザはこのトークンを各リクエストに添付します。サーバーはトークンの署名を検証することで、リクエストが正規ユーザーからのものかを確認します。 3. **トークンの有効期限:** トークンには有効期限があり、期限切れの場合は再ログインが必要になります。 --- ## 5. 技術スタック - ツールボックス | 技術 | このプロジェクトでの役割 | 採用理由 | 注意点 | |------|------------------------|---------|--------| | [例：Next.js] | [例：フロントエンドのフレームワーク。ページの表示とルーティングを担当] | [例：サーバーサイドレンダリングによる高速表示と、Reactエコシステムとの親和性が高いため] | [例：App Routerへの移行に学習コストが必要] | | [例：Supabase] | [例：データベースと認証の管理] | [例：FirebaseよりSQLが使えて柔軟性が高く、オープンソースでセルフホストも可能なため] | [例：無料枠の制限に注意。プロジェクト数と同時接続数に上限あり] | | [例：Tailwind CSS] | [例：UIのスタイリング] | [例：クラス名を考える手間がなく、デザインの一貫性を保ちやすいため] | [例：HTMLが長くなりがちで、可読性が下がることがある] | | [例：Stripe] | [例：決済処理] | [例：開発者体験が良く、テスト環境が充実しているため] | [例：手数料がかかる。売上の2.9%+30円程度] | | [例：Vercel] | [例：デプロイとホスティング] | [例：Next.jsとの統合がシームレスで、プレビュー環境が簡単に作れるため] | [例：無料枠の帯域制限に注意] | --- ## 6. 環境と設定 ### 環境変数 | 変数名 | 役割（平易な言葉で） | 設定場所 | |--------|---------------------|---------| | `DATABASE_URL` | データベースへの接続情報（住所のようなもの） | 各環境の.envファイル | | `JWT_SECRET` | 認証トークンの署名に使う秘密鍵（印鑑のようなもの） | 各環境の.envファイル | | `STRIPE_SECRET_KEY` | 決済サービスの秘密鍵（金庫の鍵のようなもの） | 各環境の.envファイル | | `NEXT_PUBLIC_API_URL` | フロントエンドがAPIを呼び出すときのURL | 各環境の.envファイル | ### 環境の種類 - **開発環境（Development）:** ローカルマシンで動作。コード変更が即座に反映され、テスト用のデータを使用します。 - **ステージング環境（Staging）:** 本番とほぼ同じ構成で、リリース前の最終確認に使用します。 - **本番環境（Production）:** 実際のユーザーが利用する環境です。 ### 設定変更時の注意 **[X]を変更したい場合:** `[Y]`ファイルを編集します。ただし、`[Z]`にも影響するため、必ずステージング環境でテストしてから本番に反映してください。 ### シークレットキー管理 APIキーやシークレットは、コードベースに直接書かず、環境変数として管理しています。`.env.local`ファイル（ローカル用）とデプロイ先の環境変数設定で管理します。**絶対にGitHubなどにコミットしないでください。** --- ## 7. 学んだ教訓 - 戦場の物語 ### バグと修正 #### バグ1: [例：データベース接続がタイムアウトする問題] **症状:** ユーザー数が増えると、一部のリクエストが遅延または失敗するようになった。 **原因:** データベースへの接続を毎回新規作成しており、接続数の上限に達していた。これはレストランで、毎回新しい電話回線を引いているようなもので、回線数に限界があった。 **修正:** コネクションプール（接続の使い回し）を導入し、既存の接続を再利用するようにした。 **今後の防止策:** 負荷テストを定期的に実施し、スケーリングの計画を事前に立てる。 #### バグ2: [例：認証が時々失敗する] **症状:** ユーザーがログインしても、時々セッションが失われる。 **原因:** トークンの有効期限と更新のタイミングにずれがあった。 **修正:** トークンの自動更新（リフレッシュトークン）の仕組みを実装した。 ### 落とし穴と地雷原 - **[X]を変更するときは注意:** [X]は[Y]と[Z]にも影響します。[具体的な影響の説明] - **技術的負債:** [例：テストカバレッジが低い部分がある。理由はリリース期限が迫っていたため。将来、リファクタリングが必要] - **見た目より複雑なもの:** [例：認証周りは一見シンプルに見えるが、ソーシャルログイン、パスワードリセット、セッション管理など、考慮すべきケースが多い] ### 発見 - **うまくいったこと:** [例：TypeScriptの導入。型エラーが早期に発見でき、リファクタリングの安心感が増した] - **うまくいかなかったこと:** [例：CSSフレームワークの乗り換え。途中で変更したため、スタイルの一貫性が一時的に失われた] - **やり直せるなら:** [例：最初からテスト駆動開発を導入する。後からテストを書くのはモチベーションが続かない] ### エンジニアリングの知恵 - **「動く」と「正しい」は違う:** 動くコードは書けても、正しいコード（保守可能で拡張可能なコード）を書くには設計思想が必要です。 - **シンプルさが最優先:** 複雑な解決策は後々のメンテナンスコストを増やします。「最もシンプルな解決策で、今日の問題を解決し、明日の変更に耐えられるもの」を選ぶのがベストです。 - **コードレビューの価値:** 自分では気づかないバグや改善点を、他の開発者が見つけてくれます。レビューは「批判」ではなく「品質向上のプロセス」です。 --- ## 8. クイックリファレンスカード ### ローカルでの実行方法 前提条件: Node.js（v18以上）がインストールされていること ```bash # 1. リポジトリをクローン git clone [リポジトリURL] cd ${name} # 2. 依存関係をインストール npm install # 3. 環境変数を設定 cp .env.example .env.local # .env.localを編集して、必要な値を設定 # 4. データベースをセットアップ npm run db:migrate # 5. 開発サーバーを起動 npm run dev ``` ブラウザで `http://localhost:3000` にアクセスします。 ### 主要URL | 環境 | URL | |------|-----| | 本番環境 | [本番URL] | | ステージング | [ステージングURL] | | 管理画面 | [管理画面URL] | | APIドキュメント | [APIドキュメントURL] | ### トラブル時の連絡先 | 問題 | 連絡先 | |------|--------| | サーバーダウン | [運用担当者/チーム] | | バグ発見 | [開発チームのチャンネル] | | セキュリティ問題 | [セキュリティ担当者] | ### よく使うコマンド ```bash # 開発サーバー起動 npm run dev # テスト実行 npm test # ビルド（本番用） npm run build # リント（コード品質チェック） npm run lint # データベースマイグレーション npm run db:migrate # 型チェック npm run typecheck ``` --- *このドキュメントは、プロジェクトの理解を助けるために作成されました。質問や改善提案があれば、[連絡先]までお知らせください。*