project-documentation

プロジェクト機能ドキュメント

プロジェクトの機能について、何をするのか、なぜ存在するのか、どのように動作するのかを、コードの詳細に踏み込まずにわかりやすく説明する、技術的でないドキュメントを作成します。ドキュメントは docs/ フォルダーに Markdown ファイルとして保存します。

目的

このドキュメントは、次の 2 つの対象者に向けたものです。

1. 開発者以外の人 - 機能を概念的に理解する必要があるプロダクトマネージャー、デザイナー、関係者
2. 問題をトラブルシューティングする AI エージェント - AI がコードにアクセスできても、本来の動作を理解する必要がある場合に、意図された動作、ビジネスルール、機能間の関係についての情報を提供します

対象読者

開発者以外の人にも理解できる平易な言葉で書きつつ、コードベースで作業する AI エージェントが、期待される動作やビジネスロジックをすばやく把握するのに役立つ詳細も含めてください。

機能インデックス（推奨）

機能の一覧とナビゲーション用インデックスを兼ねた docs/README.md を作成します。機能はドキュメント化してから一覧に追加してください。

書式の良い例

# Project Documentation

## Core Features

### [User Authentication](user-authentication.md)
**Related**: User Profile, Session Management
**Summary**: Account creation, login, password reset

### [Payment Processing](payment-processing.md)
**Related**: Order Management, Email Notifications
**Summary**: Stripe integration for payments, refunds, and disputes

### [Dashboard Analytics](dashboard-analytics.md)
**Related**: User Authentication (requires login)
**Summary**: Real-time metrics and reporting

## Secondary Features

### [Email Notifications](email-notifications.md)
**Related**: Most core features
**Summary**: SendGrid integration with queued processing

## Integrations

### [Stripe API](stripe-integration.md)
**Related**: Payment Processing
**Summary**: Payment gateway for transactions and webhooks

インデックス作成のベストプラクティス

機能をインデックスに追加するのは、ドキュメント化してからにしてください。これにより、インデックスが整理され、掲載されているすべての機能にドキュメントがある状態を保てます。

次の項目を含めてください：

• 機能名 - ドキュメントファイルへのリンク
• 関連機能 - 依存関係と関連性
• 概要 - 1 行の説明

ドキュメント構成

各機能について、docs/ に個別の Markdown ファイルを作成します。ファイル名は、内容がわかる小文字とハイフンを使ったものにしてください。

docs/
├── user-authentication.md
├── payment-processing.md
├── email-notifications.md
└── dashboard-analytics.md

「機能」に該当するもの

機能とは、ユーザー向けの重要な動作やシステム機能を指し、次のようなものが含まれます。

• ユーザー向け機能 - ユーザーが実行できる操作（ログイン、フォームの送信、レポートの表示）
• 管理ワークフロー - システムを管理するためのバックエンド処理（ユーザー管理、コンテンツのモデレーション）
• ビジネスルールと条件ロジック - 動作を定めるルール（承認ワークフロー、利用資格の確認）
• 権限とロールに基づく動作 - ユーザーの種類ごとに許可される操作、許可されない操作
• サードパーティーサービスとの連携 - 外部 API、決済ゲートウェイ、メールサービス
• バックグラウンド処理 - cron ジョブ、スケジュールされたタスク、キューに入れられた処理
• 自動化 - イベントによって開始される自動処理（自動通知、データ同期）
• カスタムデータフロー - システム内で情報がどのように流れるか
• ライフサイクルの動作 - 状態の遷移と、その遷移を引き起こすもの

ユーザー体験やシステムの動作に影響するものは、ドキュメント化する価値があります。

機能ドキュメントのテンプレート

各機能について、次の構成を使用してください。

# [Feature Name]

## What It Does

[1-2 paragraph overview of what this feature accomplishes from the user's perspective]

## Why We Built It

[Explain the problem this solves or the need it fulfills]

## How It Works

[Step-by-step explanation of the feature's behavior and logic, without code details]

### Key Components

- **[Component 1]**: What it does
- **[Component 2]**: What it does
- **[Component 3]**: What it does

### Data Flow

[What information enters the feature, how it's transformed, and what comes out]

## User Experience

[Describe what users see and how they interact with this feature]

## Expected Behavior

### Success Scenarios
- **Scenario 1**: [Input] → [Expected Result]
- **Scenario 2**: [Input] → [Expected Result]

### Error Scenarios
- **When [condition]**: [Expected behavior/message]
- **When [condition]**: [Expected behavior/message]

## Business Rules

[Critical validation rules, constraints, and logic that must always be enforced]

**Examples:**
- Passwords must be 8+ characters with 1 number and 1 special character
- Users cannot delete items that are currently in use
- Refunds are only allowed within 30 days of purchase

## Dependencies

### Required Features/Systems
- [Feature/System]: Why it's needed

### Affected Features
- [Feature]: How this feature impacts it

### External Services
- [Service]: What it's used for

## Common Issues & Edge Cases

[Document known edge cases, gotchas, or areas that commonly cause confusion]

**Examples:**
- When the external API times out, the system should queue and retry
- If a user has multiple sessions, changes in one should reflect in all
- Empty state: what happens when there's no data to display

## Future Considerations

[Optional: Known limitations or planned enhancements]

執筆ガイドライン

推奨事項：

• 平易な言葉を使う - 専門用語や技術用語は避けます
• 動作に焦点を当てる - どのようにコード化されているかではなく、何が起こるかを説明します
• 「なぜ」を説明する - ビジネスロジックと判断の根拠を説明します
• 具体例を使う - 想定される結果を含む具体的なシナリオを示します
• ユーザーの操作フローを説明する - 「ユーザーが X をすると、システムは Y を行う」
• エッジケースを記録する - 通常と異なる状況やエラー状況で何が起こるかを説明します
• ルールを具体的にする - 検証ロジック、ビジネス上の制約、必須条件を記載します
• 連携について触れる - 関係する外部サービスやシステムを記載します
• 依存関係を列挙する - この機能が依存するものと、この機能に依存するものを記載します
• 想定されるエラーを記録する - エラーが発生したときに表示されるべきメッセージを記載します

避けること：

• コードに言及する - 関数名、クラス名、ファイルパスは記載しません
• 実装の詳細を含める - データベーススキーマ、API エンドポイント、技術アーキテクチャは記載しません
• 開発者向けの専門用語を使う - 「ミドルウェア」、「ORM」、「シリアライゼーション」などは使いません
• 前提を置く - 略語やドメイン用語は説明します
• 曖昧に書く - 説明せずに「さまざまなケースを処理します」といった表現は避けます

AI のトラブルシューティングで重要なこと：

• 「正常系」を記録する - すべてが正常に動作しているときに何が起こるべきか
• エラー時の動作を記録する - 問題が発生したときに何が起こるべきか
• ビジネスルールを明確にする - 必ず適用しなければならない制約
• 機能の境界を明記する - ある機能がどこで終わり、別の機能がどこから始まるか
• 自明でないロジックを説明する - バグのように見えても、意図的な動作
• 暗黙の動作を説明する - 自動割り当て、デフォルト値、隠れたトリガー
• 設定に依存する動作を記録する - 設定やユーザー属性に応じて何が変わるか

コードだけでは不十分な場合

コードを読むだけでは動作が明らかでない機能もあります。

• 歴史的背景 - 特定の決定がなされた理由
• ビジネスルール - ステークホルダーの要件に基づくロジック
• 暗黙の前提 - コードに明示されていないデフォルトの動作
• エッジケースへの対応 - まれな状況に関する判断
• 設定駆動の動作 - コンテキストによって異なる動作

ドキュメント作成中に動作が不明確な場合：

1. 不明な点を記録する - 回答が必要な質問を記録します
2. ユーザー／SME に尋ねる - ビジネスの背景を知る人に説明を求めます
3. 回答を記録する - 明確になった動作をドキュメントに追加します
4. 明示的に記述する - 暗黙の動作をドキュメントで明確にします

SME に尋ねる質問の例：

• 「ユーザーが複数のロールを持つ場合、どの権限が優先されますか？」
• 「チェックアウト中に外部 API がダウンした場合、どうなるべきですか？」
• 「ユーザーをチーム B ではなくチーム A に自動割り当てするのはなぜですか？」
• 「返金に 30 日の上限を設けているビジネス上の理由は何ですか？」

ドキュメントの例

良い例：

# User Authentication

## What It Does

Allows users to create accounts and securely log in to access their personalized dashboard. Users can also reset their password if they forget it.

## Why We Built It

We needed a secure way to identify users and protect their personal data. Each user has unique settings and history that should only be accessible to them.

## How It Works

### Registration
When someone signs up, they provide an email address and create a password. The system checks that the email isn't already in use and that the password meets security requirements (at least 8 characters, one number, one special character). We send a verification email to confirm they own the email address.

### Login Process
Users enter their email and password. The system verifies these credentials match what's stored. If correct, they get access to their account. After 3 failed attempts, the account is temporarily locked for 15 minutes to prevent unauthorized access attempts.

### Password Reset
If a user forgets their password, they can request a reset link via email. The link is valid for 1 hour. Clicking it allows them to set a new password.

### Data Flow
Email + Password → Validation → Password Security Check → Store Account → Send Verification Email → User Clicks Link → Account Activated

## User Experience

- Registration form with email and password fields
- Validation messages appear in real-time (e.g., "Password too short")
- Verification email arrives within 1-2 minutes
- Login page with "Forgot Password?" link
- Error messages are helpful but don't reveal whether an email exists in the system

## Expected Behavior

### Success Scenarios
- **Valid registration**: User receives verification email within 2 minutes, can click link and access account
- **Valid login**: User enters correct credentials, immediately redirected to dashboard
- **Password reset request**: User receives reset link within 2 minutes, link works for 1 hour

### Error Scenarios
- **Duplicate email**: Show "An account with this email already exists" message
- **Weak password**: Show specific requirements not met (e.g., "Password must include a number")
- **Failed login (1-2 attempts)**: Show "Invalid email or password" message
- **Failed login (3 attempts)**: Show "Account locked for 15 minutes due to too many failed attempts"
- **Expired reset link**: Show "This reset link has expired. Please request a new one."
- **Unverified account login**: Show "Please verify your email before logging in" with option to resend

## Business Rules

- Email addresses must be unique across all accounts (case-insensitive: [email protected] = [email protected])
- Passwords must be at least 8 characters with 1 number and 1 special character (!@#$%^&*)
- Passwords expire after 90 days and users must create a new one
- New password cannot match previous 3 passwords
- Verification emails expire after 24 hours
- Users can't register with disposable email services (list maintained separately)
- Account lockout after 3 failed attempts lasts exactly 15 minutes
- Password reset links expire after 1 hour
- Only one active reset link per account - requesting new one invalidates previous

## Dependencies

### Required Features/Systems
- **Email delivery service**: For verification and password reset emails. If service is down, registration/reset will fail gracefully with "Unable to send email, please try again later"
- **Session management**: Required to maintain logged-in state

### Affected Features
- **User profile**: Cannot be accessed without authentication
- **Dashboard**: Requires active session
- **Settings**: Changes require password re-confirmation

### External Services
- **Email service**: SendGrid for transactional emails
- **Disposable email checker**: API to validate email domains

## Common Issues & Edge Cases

**Multiple tabs/sessions**: If user logs out in one tab, all other tabs should immediately reflect logged-out state. Currently handled via session token validation on each request.

**Email service downtime**: System will retry sending 3 times over 10 minutes. If all fail, user sees error message but account is created - they can request verification resend from login page.

**Case sensitivity**: Email addresses are stored lowercase and compared case-insensitively. "[email protected]" and "[email protected]" are treated as same user.

**Timing attacks**: Login error messages deliberately don't distinguish between "email not found" and "wrong password" to prevent account enumeration.

**Clock skew**: Reset links use server time, not user device time, to prevent timezone issues.

## Future Considerations

- Add two-factor authentication option
- Support social login (Google, GitHub)
- Add "Remember me" option for extended sessions

悪い例：

# Authentication

Uses JWT tokens with bcrypt hashing. The AuthController handles login() and register() methods. Password validation uses regex pattern /^(?=.*[0-9])(?=.*[!@#$%^&*])/.

Database schema includes users table with email, password_hash, and created_at columns.

技術的すぎます。ユーザーの視点での「何を／なぜ／どのように」ではなく、実装に焦点を当てています。

ワークフロー：新機能のドキュメントを作成する

機能が完成したら、次の手順で進めます。

1. 機能の範囲を特定する - ユーザーの視点で、何をこの「機能」とみなすかを決めます
2. ドキュメントファイルを作成する - docs/ に、明確で説明的な名前のファイルを作成します
3. 「何を」から始める - 機能が何をするのか、簡潔に説明します
4. 「なぜ」を説明する - どのような問題を解決するのかを説明します
5. 「どのように」を詳述する - 動作とロジックを順を追って説明します
6. 期待される動作を記録する - 成功時とエラー時のシナリオを、具体例とともに記載します
7. ビジネスルールを列挙する - 適用しなければならないすべての検証と制約を記載します
8. 依存関係を整理する - この機能に必要なものと、この機能を必要とするものを記載します
9. エッジケースを記録する - まれな状況と、その対処方法を記載します
10. インデックスに追加する - 概要と関連情報を添えて、docs/README.md に項目を追加します
11. わかりやすさを確認する - 開発者でない人にも理解できますか？ AI エージェントは期待される動作を把握できますか？

ワークフロー：既存プロジェクトのドキュメントを作成する

既存のドキュメントがないプロジェクト全体を記録する場合は、次の手順で進めます。

1. すべての機能を特定する - プロジェクトを調査するか、把握している機能を洗い出します
2. 機能に優先順位を付ける - 中核となる機能から始め、その後に支援機能を扱います
3. 各機能のドキュメントを作成する - 上記のテンプレートに従います
4. インデックスに追加する - 各機能のドキュメントを作成したら、docs/README.md に追加します（テンプレートについては上記の「機能インデックス」セクションを参照してください）
5. 関連機能をリンクする - 機能同士が連携する箇所を、各ドキュメントで相互参照します

質の高いドキュメントを作成するためのヒント

具体的に書く

• ❌ 「システムはさまざまなエラーケースに対応します」
• ✅ 「メールサービスがダウンしている場合、システムはメッセージをキューに入れ、最長 2 時間、5 分ごとに再試行します」

シナリオを使う

• ❌ 「一括操作に対応しています」
• ✅ 「ユーザーは複数の項目を選択して、一度に削除できます。項目がロック中または使用中の場合、削除できなかった項目とその理由をシステムが表示します」

判断の理由を説明する

• ❌ 「パスワードは 8 文字以上でなければなりません」
• ✅ 「セキュリティと使いやすさのバランスを取るため、パスワードは 8 文字以上でなければなりません。覚えやすい長さを保ちながら、一般的な攻撃に耐えられる長さにしています」

エッジケースを説明する

• ❌ 「決済処理を行います」
• ✅ 「決済処理中に決済ゲートウェイがタイムアウトした場合、システムは30秒待ってから決済ステータスを直接確認します。これにより、二重請求を防止します」

ドキュメントのメンテナンス

• 動作が変わったときに更新する - コードが変更されたときではなく、ユーザー向けの動作やビジネスロジックが変わったときに更新します
• 最新の状態に保つ - 非推奨の機能は削除するか、非推奨であることを明確に示します
• 重要な変更のバージョンを記録する - 主な機能が追加または変更された時期を記載します
• 定期的にレビューする - ドキュメントが製品を正確に反映していることを確認します

要約チェックリスト

機能ドキュメントを仕上げる前に、次の項目を確認してください。

基本コンテンツ

• ユーザーの視点から機能の動作を説明している
• この機能が存在する理由（問題やニーズ）を明確にしている
• コードに言及せずに、動作の仕組みを説明している
• データフローの概要を含めている

期待される動作（AI によるトラブルシューティングに不可欠）

• 具体的な入力と出力を示した成功シナリオを記載している
• 想定されるエラーメッセージを示したエラーシナリオを記載している
• エッジケースや通常とは異なる状況を網羅している
• 依存関係に障害が発生した場合の動作を明確にしている

ビジネスルール（AI によるトラブルシューティングに不可欠）

• 具体例を添えて、すべての検証ルールを列挙している
• 必ず適用しなければならない制約を記載している
• バグのように見える可能性がある、分かりにくいロジックを説明している

統合と依存関係

• 必須の機能やシステムを説明とともに列挙している
• この機能の影響を受ける機能を列挙している
• 外部サービスとその目的を記載している
• 依存関係を利用できない場合の動作を記載している

よくある問題

• 既知のエッジケースを記載している
• 注意点や分かりにくい動作を説明している
• よくある障害のパターンを網羅している

品質

• 開発者以外にも分かる平易な言葉を使っている
• 抽象的な説明ではなく、具体例を示している
• AI エージェントが期待される動作をすばやく理解するのに役立つ
• ファイルが分かりやすい名前で docs/ に保存されている