commit 17077288f62e8ee70733cd9c850b62e8646e9436 Author: Zhongwei Li Date: Sun Nov 30 09:06:31 2025 +0800 Initial commit diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json new file mode 100644 index 0000000..1a80aa1 --- /dev/null +++ b/.claude-plugin/plugin.json @@ -0,0 +1,12 @@ +{ + "name": "sdd-docs", + "description": "ソフトウェア設計ドキュメント（SDD）を作成・修正・更新・管理します。3つの主要ファイル - requirements.md（EARS記法によるユーザーストーリー）、design.md（技術アーキテクチャ）、tasks.md（実装計画）の新規作成、既存ドキュメントの編集、EARS記法への変換、要件・設計・タスクの追加や修正が必要な場合に使用してください。", + "version": "0.0.0-2025.11.28", + "author": { + "name": "Winds Chord", + "email": "zhongweili@tubi.tv" + }, + "skills": [ + "./skills/sdd-docs" + ] +} \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..3b4f24b --- /dev/null +++ b/README.md @@ -0,0 +1,3 @@ +# sdd-docs + +ソフトウェア設計ドキュメント（SDD）を作成・修正・更新・管理します。3つの主要ファイル - requirements.md（EARS記法によるユーザーストーリー）、design.md（技術アーキテクチャ）、tasks.md（実装計画）の新規作成、既存ドキュメントの編集、EARS記法への変換、要件・設計・タスクの追加や修正が必要な場合に使用してください。 diff --git a/plugin.lock.json b/plugin.lock.json new file mode 100644 index 0000000..06c057b --- /dev/null +++ b/plugin.lock.json @@ -0,0 +1,68 @@ +{ + "$schema": "internal://schemas/plugin.lock.v1.json", + "pluginId": "gh:windschord/claude_skils:sdd-docs", + "normalized": { + "repo": null, + "ref": "refs/tags/v20251128.0", + "commit": "077b162819a8ea58f2d75e1bac6bacecc41c8270", + "treeHash": "0dcb27eb1c2c093f442491bf2b452bc3af8e8f387be886eb4e3ab874773c1f47", + "generatedAt": "2025-11-28T10:29:02.574191Z", + "toolVersion": "publish_plugins.py@0.2.0" + }, + "origin": { + "remote": "git@github.com:zhongweili/42plugin-data.git", + "branch": "master", + "commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390", + "repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data" + }, + "manifest": { + "name": "sdd-docs", + "description": "ソフトウェア設計ドキュメント（SDD）を作成・修正・更新・管理します。3つの主要ファイル - requirements.md（EARS記法によるユーザーストーリー）、design.md（技術アーキテクチャ）、tasks.md（実装計画）の新規作成、既存ドキュメントの編集、EARS記法への変換、要件・設計・タスクの追加や修正が必要な場合に使用してください。" + }, + "content": { + "files": [ + { + "path": "README.md", + "sha256": "b68fac5d1e0f5826681c162dd6e7c335944279681ddaf4688ea00ed92bb48584" + }, + { + "path": ".claude-plugin/plugin.json", + "sha256": "15c6ecec4d4a4115b9ca2faae86138b90b15329d503eb4cde8a7cedd646da000" + }, + { + "path": "skills/sdd-docs/README.md", + "sha256": "2dac28077e58a4f86a775339cb60a527faba90c7bc0681c24ce8aff1de650993" + }, + { + "path": "skills/sdd-docs/SKILL.md", + "sha256": "6c2e7bd1926f585beeb29598240d37f04ccdaeab25c35dcdac739c0e5de1d95f" + }, + { + "path": "skills/sdd-docs/references/ears_notation_ja.md", + "sha256": "b340fc094299949ef09d4b07f48e03cb2f851dfd9f303ea4ed77fc3eb038993e" + }, + { + "path": "skills/sdd-docs/references/examples_ja.md", + "sha256": "5da78650b7b02093c12acdba0e4339e778b230d1648fb5c08ff47be52ea97bbd" + }, + { + "path": "skills/sdd-docs/assets/templates/requirements_template_ja.md", + "sha256": "ec5ee2568fae4d540ee5d1b26c305f301d91568b8aa52eca54e4030758078980" + }, + { + "path": "skills/sdd-docs/assets/templates/design_template_ja.md", + "sha256": "01f908a5cb0d924b2f14bfd2df869d66c34a784191144157031c5ade1f0f10c0" + }, + { + "path": "skills/sdd-docs/assets/templates/tasks_template_ja.md", + "sha256": "6da6582710d8cfa9aea5474d1bba145e52c28b9aa27a50c5ad44478fb80073cb" + } + ], + "dirSha256": "0dcb27eb1c2c093f442491bf2b452bc3af8e8f387be886eb4e3ab874773c1f47" + }, + "security": { + "scannedAt": null, + "scannerVersion": null, + "flags": [] + } +} \ No newline at end of file diff --git a/skills/sdd-docs/README.md b/skills/sdd-docs/README.md new file mode 100644 index 0000000..8a5005f --- /dev/null +++ b/skills/sdd-docs/README.md @@ -0,0 +1,407 @@ +# SDD-Docs - ソフトウェア設計ドキュメント管理スキル + +Claude Codeのための構造化されたソフトウェア設計ドキュメント（SDD）作成・管理スキルです。EARS記法を用いた要件定義、技術設計、タスク管理の3つのドキュメントを一貫したプロセスで作成・維持します。 + +--- + +## 目次 + +- [特徴](#特徴) +- [クイックスタート](#クイックスタート) +- [EARS記法について](#ears記法について) +- [ドキュメント構成](#ドキュメント構成) +- [使い方](#使い方) +- [ワークフロー](#ワークフロー) +- [ベストプラクティス](#ベストプラクティス) +- [FAQ](#faq) +- [トラブルシューティング](#トラブルシューティング) +- [リファレンス](#リファレンス) + +--- + +## 特徴 + +### 解決する課題 + +- 曖昧で測定不可能な要件定義 +- 技術的決定事項の記録不足 +- タスク分解と進捗管理の困難さ +- ドキュメントの一貫性の欠如 + +### 提供する価値 + +- **明確性**: EARS記法による曖昧さのない要件定義 +- **追跡可能性**: 要件→設計→タスクの明確な紐付け +- **テスト可能性**: すべての要件が検証可能 +- **一貫性**: 統一されたドキュメント構造 + +--- + +## クイックスタート + +### 1. スキルを有効化 + +Claude Codeでこのスキルが自動的に提案されます。 + +### 2. プロジェクトでドキュメントを初期化 + +``` +docsディレクトリを初期化してください +``` + +### 3. 生成されるドキュメント + +``` +your-project/ +└── docs/ + ├── requirements.md # 要件定義書（EARS記法） + ├── design.md # 設計書 + └── tasks.md # タスク管理書 +``` + +### 4. 使用例 + +**要件を追加:** +``` +ユーザー認証機能の要件を追加してください +``` + +**設計を文書化:** +``` +認証システムのアーキテクチャを設計書に追加してください +``` + +**タスクに分解:** +``` +認証機能を実装可能なタスクに分解してください +``` + +--- + +## EARS記法について + +EARS（Easy Approach to Requirements Syntax）は、明確で曖昧さのない要件を記述するための構造化された記法です。 + +### 5つの基本パターン + +| パターン | 形式 | 使用場面 | 例 | +|---------|------|----------|-----| +| **基本** | システムは〜しなければならない | 常時適用される要件 | システムはパスワードをbcryptで暗号化しなければならない | +| **イベント** | 〜の時、システムは〜しなければならない | イベント駆動要件 | ユーザーがログインボタンをクリックした時、システムは認証処理を開始しなければならない | +| **条件** | もし〜ならば、システムは〜しなければならない | 状態依存要件 | もし認証が失敗した場合、システムはエラーメッセージを表示しなければならない | +| **継続** | 〜の間、システムは〜しなければならない | 継続的要件 | ファイルアップロード中、システムは進捗バーを表示しなければならない | +| **場所** | 〜において、システムは〜しなければならない | コンテキスト固有要件 | EU地域において、システムはGDPR同意バナーを表示しなければならない | + +### EARS記法の利点 + +- **一貫性**: すべての要件が同じ構造に従う +- **明確性**: 曖昧な表現を排除 +- **テスト可能性**: 各要件が検証可能 +- **完全性**: トリガー、条件、動作が明確 + +詳細: [EARS記法リファレンス](references/ears_notation_ja.md) + +--- + +## ドキュメント構成 + +### 3つの必須ドキュメント + +```mermaid +graph LR + A[requirements.md
何を作るか] --> B[design.md
どう作るか] + B --> C[tasks.md
どう実装するか] + C --> D[実装] + D --> A +``` + +#### 1. requirements.md - 要件定義書 + +**目的**: 何を作るかを定義 + +**含まれる内容**: +- ユーザーストーリー（私は〜として、〜したい、なぜなら〜） +- EARS記法による受入基準（REQ-001, REQ-002...） +- 非機能要件（NFR-001, NFR-002...） + +**例**: +```markdown +### ストーリー1: ユーザーログイン +**私は** 登録済みユーザーとして +**ログインしたい** +**なぜなら** 個人データにアクセスできるから + +#### 受入基準 +- REQ-001: ユーザーがログインボタンをクリックした時、システムは2秒以内に認証を完了しなければならない +- REQ-002: もしパスワードが誤っている場合、システムはエラーメッセージを表示しなければならない +``` + +#### 2. design.md - 設計書 + +**目的**: どのように作るかを文書化 + +**含まれる内容**: +- アーキテクチャ図（Mermaid形式） +- コンポーネント設計（目的、責務、インターフェース） +- データモデル・スキーマ +- 技術的決定事項と根拠 + +**例**: +```markdown +### コンポーネント: 認証サービス +**目的**: ユーザー認証とセッション管理 +**責務**: +- JWT トークンの生成・検証 +- パスワードのハッシュ化（bcrypt） +- セッションの管理 + +**インターフェース**: +- POST /auth/login - ログイン +- POST /auth/logout - ログアウト +``` + +#### 3. tasks.md - タスク管理書 + +**目的**: どのように実装するかを計画 + +**含まれる内容**: +- フェーズごとのタスク分解 +- 各タスクの受入基準 +- 依存関係と見積もり時間 +- ステータス管理（TODO/IN_PROGRESS/BLOCKED/REVIEW/DONE） + +**例**: +```markdown +#### タスク1.1: ログインエンドポイント実装 +**説明**: POST /auth/loginエンドポイントの実装 +**受入基準**: +- [ ] メール/パスワード検証 +- [ ] JWTトークン生成 +- [ ] エラーハンドリング +**依存関係**: なし +**推定工数**: 4時間 +**ステータス**: `TODO` +``` + +--- + +## 使い方 + +### 基本的な使用フロー + +1. **要件定義から開始** + ``` + ユーザー認証機能の要件を定義してください + ``` + → `docs/requirements.md`にEARS記法で要件が追加される + +2. **設計を文書化** + ``` + 認証機能のアーキテクチャを設計してください + ``` + → `docs/design.md`にコンポーネント設計が追加される + +3. **タスクに分解** + ``` + 認証機能の実装タスクを作成してください + ``` + → `docs/tasks.md`に実装可能なタスクが追加される + +4. **実装とレビュー** + ``` + タスク1.1を実装してください + ``` + → コードが実装され、タスクステータスが更新される + +5. **ドキュメントの検証** + ``` + ドキュメントをレビューしてください + ``` + → チェックリストに基づいてレビューが実行される + +### 高度な使用例 + +**既存プロジェクトのドキュメント化:** +``` +このプロジェクトの既存コードから要件と設計を抽出してください +``` + +**要件の検証:** +``` +requirements.mdの要件がEARS記法に従っているか確認してください +``` + +**タスクの進捗確認:** +``` +完了したタスクと残りのタスクをリストアップしてください +``` + +--- + +## ワークフロー + +### 標準的な開発フロー + +``` +┌─────────────────────────────────────────────────────────┐ +│ 1. 要件定義（requirements.md） │ +│ ↓ ユーザーストーリーとEARS記法で「何を作るか」を定義 │ +├─────────────────────────────────────────────────────────┤ +│ 2. 設計（design.md） │ +│ ↓ アーキテクチャとコンポーネントで「どう作るか」記述 │ +├─────────────────────────────────────────────────────────┤ +│ 3. タスク計画（tasks.md） │ +│ ↓ 実装可能な粒度に分解して「どう実装するか」計画 │ +├─────────────────────────────────────────────────────────┤ +│ 4. 実装 │ +│ ↓ タスクを実行し、ステータスを更新 │ +├─────────────────────────────────────────────────────────┤ +│ 5. レビュー │ +│ ↓ ドキュメントとコードの整合性を確認 │ +├─────────────────────────────────────────────────────────┤ +│ 6. 反復 │ +│ ↓ 新しい要件や変更に応じてドキュメントを更新 │ +└─────────────────────────────────────────────────────────┘ +``` + +### ドキュメント検証チェックリスト + +**requirements.mdの確認項目:** +- [ ] すべての要件がEARS記法に従っている +- [ ] 要件IDが一意である（REQ-XXX、NFR-XXX） +- [ ] 各要件がテスト可能である +- [ ] 非機能要件が含まれている +- [ ] 具体的な数値が使用されている + +**design.mdの確認項目:** +- [ ] アーキテクチャ概要がある +- [ ] 主要コンポーネントが定義されている +- [ ] インターフェースが明確である +- [ ] 技術的決定事項と根拠が記載されている +- [ ] 図表が含まれている（Mermaid推奨） + +**tasks.mdの確認項目:** +- [ ] タスクが適切な粒度に分解されている（半日〜2日程度） +- [ ] 各タスクに受入基準がある +- [ ] 依存関係が明確である +- [ ] 見積もり時間が記載されている +- [ ] ステータスが有効な値である + +--- + +## ベストプラクティス + +### 1. 具体的で測定可能な値を使用 + +**悪い例**: システムは速くなければならない +**良い例**: システムはユーザークエリに200ミリ秒以内に応答しなければならない + +### 2. 1要件1文の原則 + +**悪い例**: システムはデータを検証し、保存し、メールを送信しなければならない +**良い例**: +- REQ-001: システムはデータを検証しなければならない +- REQ-002: データが有効な場合、システムは保存しなければならない +- REQ-003: データ保存後、システムは確認メールを送信しなければならない + +### 3. 曖昧な用語を避ける + +**避けるべき**: すべきである、できる、かもしれない、おそらく、一般的に +**使用する**: しなければならない + +### 4. 依存関係を明確にする + +タスク間の依存関係を明記して、実装順序を明確にします。 + +### 5. 図表を積極的に活用 + +Mermaid記法でアーキテクチャ図、シーケンス図、ER図を作成します。 + +### 6. 継続的な同期を維持 + +プロジェクトの進展に応じて、ドキュメントを常に最新の状態に保ちます。 + +--- + +## FAQ + +**Q: EARS記法は必須ですか？** +A: 推奨されますが、プロジェクトに応じて調整可能です。ただし、EARS記法を使用することで要件の明確性が大幅に向上します。 + +**Q: 既存プロジェクトにも適用できますか？** +A: はい。既存のコードベースから要件と設計を抽出して、ドキュメント化することができます。 + +**Q: 英語版はありますか？** +A: 現在は日本語版のみですが、将来的に英語版テンプレートの追加を検討しています。 + +**Q: タスクのステータス管理はどうすればいいですか？** +A: マークダウンファイル内で直接更新します。Claude Codeを使用すると自動的に更新されます。 + +**Q: 他のツール（Jira、GitHub Issues）との連携は？** +A: 将来的な拡張機能として検討中です。現在はマークダウンベースでの管理のみです。 + +--- + +## トラブルシューティング + +### 問題: スキルが認識されない + +**原因**: スキルファイルのパスが正しくない +**解決策**: +1. `.claude-plugin/marketplace.json`のパスを確認 +2. `sdd-docs/SKILL.md`が存在するか確認 + +### 問題: テンプレートが見つからない + +**原因**: テンプレートファイルのパスが間違っている +**解決策**: +```bash +ls -la assets/templates/ +``` +で3つのテンプレートファイルが存在するか確認 + +### 問題: EARS記法が正しく適用されない + +**原因**: パターンの理解不足 +**解決策**: [EARS記法リファレンス](references/ears_notation_ja.md)を参照し、5つの基本パターンを確認 + +--- + +## リファレンス + +### 詳細ドキュメント + +- **EARS記法の完全ガイド**: [ears_notation_ja.md](references/ears_notation_ja.md) +- **実装例集**: [examples_ja.md](references/examples_ja.md) + - ECショッピングカート（requirements.md例） + - タスク管理API（design.md例） + - ユーザー認証機能（tasks.md例） + +### テンプレート + +- [requirements_template_ja.md](assets/templates/requirements_template_ja.md) +- [design_template_ja.md](assets/templates/design_template_ja.md) +- [tasks_template_ja.md](assets/templates/tasks_template_ja.md) + +### ディレクトリ構造 + +``` +sdd-docs/ +├── SKILL.md # スキル定義ファイル +├── README.md # このファイル +├── assets/ +│ └── templates/ # ドキュメントテンプレート +│ ├── requirements_template_ja.md +│ ├── design_template_ja.md +│ └── tasks_template_ja.md +└── references/ # リファレンス資料 + ├── ears_notation_ja.md # EARS記法詳細ガイド + └── examples_ja.md # 実装例集 +``` + +--- + +## 謝辞 + +- **EARS記法**: Alistair Mavin et al.による"EARS - The Easy Approach to Requirements Syntax" +- **標準規格**: IEEE 830-1998, ISO/IEC/IEEE 29148:2018 diff --git a/skills/sdd-docs/SKILL.md b/skills/sdd-docs/SKILL.md new file mode 100644 index 0000000..cfd7d6a --- /dev/null +++ b/skills/sdd-docs/SKILL.md @@ -0,0 +1,777 @@ +--- +name: sdd-docs +description: ソフトウェア設計ドキュメント（SDD）を作成・修正・更新・管理します。3つの主要ファイル - requirements.md（EARS記法によるユーザーストーリー）、design.md（技術アーキテクチャ）、tasks.md（実装計画）の新規作成、既存ドキュメントの編集、EARS記法への変換、要件・設計・タスクの追加や修正が必要な場合に使用してください。 +--- + +# SDD ドキュメンテーションスキル + +構造化されたソフトウェア設計ドキュメント（SDD）の作成を支援します。明確な要件定義、設計思想、実行可能なタスクを重視したドキュメント作成手法です。 + +## 概要 + +SDD-Docsスキルは、以下の3つの必須ドキュメントファイルの作成と管理を支援します： +- **requirements.md**: EARS記法を用いたユーザーストーリーと受入基準 +- **design.md**: 技術アーキテクチャ、コンポーネント、実装詳細 +- **tasks.md**: 追跡可能な個別タスクへの作業分解 + +すべてのドキュメントは`docs`ディレクトリに保存され、可視性とGit管理が容易になります。 + +## このスキルを使用する場面 + +以下の状況でこのスキルを有効にしてください： + +### 新規作成時 +- 新規ソフトウェアプロジェクトで構造化されたドキュメントが必要な場合 +- 明確でテスト可能な受入基準を持つ要件を作成する場合 +- 技術アーキテクチャと設計決定を文書化する場合 +- 機能を実装可能なタスクに分解する場合 +- プロジェクトのドキュメント構造を設定する場合 + +### 既存ドキュメントの修正・更新時 +- docs/requirements.mdに新しい要件を追加・修正する場合 +- docs/design.mdの設計内容を更新・変更する場合 +- docs/tasks.mdにタスクを追加・修正・更新する場合 +- 既存の要件をEARS記法に変換・修正する場合 +- 要件・設計・タスクの整合性を確認・修正する場合 +- ドキュメントの内容をレビュー・改善する場合 + +## ドキュメント初期化の方法 + +「docsディレクトリを初期化してください」や「SDDドキュメントを作成してください」と依頼されたら、以下の作業を行います： + +1. **docsディレクトリの作成** +2. **requirements.md（要件定義書）の作成** - assets/templates/requirements_template_ja.mdを基に作成 +3. **design.md（設計書）の作成** - assets/templates/design_template_ja.mdを基に作成 +4. **tasks.md（タスク管理書）の作成** - assets/templates/tasks_template_ja.mdを基に作成 + +作成時は、プロジェクトの内容に応じてテンプレートをカスタマイズします。 + +## 既存ドキュメントの編集方法 + +既存のSDDドキュメント（requirements.md、design.md、tasks.md）を修正・更新する場合は、以下の手順で行います： + +### 要件定義（requirements.md）の修正・追加 + +「requirements.mdに〜を追加してください」「要件を修正してください」などと依頼されたら： + +1. **既存ドキュメントの確認** + - docs/requirements.mdの現在の内容を確認 + - 既存の要件ID（REQ-XXX、NFR-XXX）を把握 + +2. **修正・追加の実施** + - 新しい要件を追加する場合は、次の要件IDを採番 + - 既存の要件を修正する場合は、EARS記法に従っているか確認 + - ユーザーストーリーとの整合性を確認 + +3. **ユーザー確認** + - 修正内容をユーザーに確認 + - 承認を得てから次のステップへ + +### 設計（design.md）の修正・更新 + +「design.mdを更新してください」「設計を変更してください」などと依頼されたら： + +1. **既存設計の確認** + - docs/design.mdの現在のアーキテクチャ、コンポーネント構成を確認 + - requirements.mdとの整合性を確認 + +2. **設計変更の実施** + - アーキテクチャ変更の場合は、影響範囲を明確にする + - 新しいコンポーネント追加の場合は、既存との統合方法を明記 + - 技術的決定事項を更新 + +3. **ユーザー確認** + - 変更内容をユーザーに確認 + - 承認を得てから次のステップへ + +### タスク（tasks.md）の修正・追加 + +「tasks.mdにタスクを追加してください」「タスクを更新してください」などと依頼されたら： + +1. **既存タスクの確認** + - docs/tasks.mdの現在のタスク一覧、フェーズ構成を確認 + - 進行中のタスク、依存関係を把握 + +2. **タスクの追加・修正** + - 新しいタスクを追加する場合は、適切なフェーズに配置 + - 既存タスクを修正する場合は、受入基準、依存関係を更新 + - TDDの実装手順を含める + - AIエージェント向けの具体的な指示を記載 + +3. **ユーザー確認** + - 追加・修正内容をユーザーに確認 + - 承認を得て完了 + +### 整合性の確認 + +ドキュメント修正時は、3つのドキュメント間の整合性を確認してください： + +- requirements.mdの要件変更 → design.mdとtasks.mdへの影響を確認 +- design.mdの設計変更 → tasks.mdのタスク内容を更新 +- tasks.mdのタスク追加 → requirements.mdとdesign.mdに対応する内容があるか確認 + +## EARS記法ガイド + +EARS（Easy Approach to Requirements Syntax）により、要件を明確で曖昧さがなく、テスト可能にします。 + +### 基本パターン（日本語版） + +| パターン | 形式 | 使用場面 | +|---------|------|----------| +| 基本 | `システムは〜しなければならない` | 常時適用される要件 | +| イベント | `〜の時、システムは〜しなければならない` | イベント駆動要件 | +| 条件 | `もし〜ならば、システムは〜しなければならない` | 状態依存要件 | +| 継続 | `〜の間、システムは〜しなければならない` | 継続的要件 | +| 場所 | `〜において、システムは〜しなければならない` | コンテキスト固有要件 | + +### 要件の例 + +```markdown +- REQ-001: ユーザーが「カートに追加」をクリックした時、システムは500ms以内に商品を追加しなければならない +- REQ-002: カートが空の場合、システムは「カートは空です」と表示しなければならない +- REQ-003: 決済処理中、システムは進捗インジケーターを表示しなければならない +- REQ-004: ユーザーがEU地域にいる場合、システムはGDPR同意オプションを表示しなければならない +- NFR-001: システムは性能劣化なしに1000人の同時ユーザーを処理できなければならない +``` + +詳細なEARSガイダンスは `references/ears_notation_ja.md` を参照してください。 + +## ドキュメント構造の説明 + +### requirements.md（要件定義書） + +```markdown +# 要件定義 + +## 概要 +[機能/システムの高レベルの目的と目標を記載] + +## ユーザーストーリー +### ストーリー1: [タイトル] +**私は** [ユーザータイプ]として +**〜したい** [目標] +**なぜなら** [価値/利点] + +#### 受入基準（EARS記法） +- REQ-001: [イベント]の時、システムは[振る舞い]しなければならない +- REQ-002: もし[条件]ならば、システムは[振る舞い]しなければならない + +## 非機能要件 +- NFR-001: システムは[性能/セキュリティ/ユーザビリティ要件]を満たさなければならない +``` + +### design.md（設計書） + +```markdown +# 設計 + +## アーキテクチャ概要 +[システムアーキテクチャの説明と図] + +## コンポーネント +### コンポーネント1: [名前] +**目的**: [機能] +**責務**: [リスト] +**インターフェース**: [API/メソッド] + +## データフロー +[シーケンス図とデータフローの説明] + +## 技術的決定事項 +[主要な技術選択と根拠] +``` + +### tasks.md（タスク管理書） + +```markdown +# タスク + +## 実装計画 + +### フェーズ1: [名前] +#### タスク1.1: [タイトル] +**説明**: [実施内容] +**受入基準**: [チェックリスト] +**依存関係**: [他のタスク] +**ステータス**: `TODO` +``` + +## ワークフロー + +1. **初期化**: docsディレクトリとテンプレートファイルを作成 +2. **要件定義**: EARS記法を使って何を作るかを定義 +3. **設計**: どのように作るかを文書化 +4. **タスク計画**: 実装を計画 +5. **レビュー**: ドキュメントの品質をチェック +6. **反復**: プロジェクトの進展に応じて更新 + +## 検証チェックリスト + +ドキュメントをレビューする際は以下を確認： + +### 要件定義書のチェック項目 +- ✅ ユーザーストーリーが明確に定義されている +- ✅ すべての要件がEARS記法に従っている +- ✅ 要件IDが一意である（REQ-XXX、NFR-XXX） +- ✅ 各要件がテスト可能である +- ✅ 非機能要件が含まれている + +### 設計書のチェック項目 +- ✅ アーキテクチャ概要が記載されている +- ✅ 主要コンポーネントが定義されている +- ✅ インターフェースが明確である +- ✅ 技術的決定事項と根拠が記載されている +- ✅ 必要に応じて図表が含まれている + +### タスク管理書のチェック項目 +- ✅ タスクが適切な粒度に分解されている +- ✅ 各タスクに受入基準がある +- ✅ 依存関係が明確である +- ✅ 見積もり時間が記載されている +- ✅ ステータスが有効な値である（TODO、IN_PROGRESS、BLOCKED、REVIEW、DONE） + +## ベストプラクティス + +1. **なぜから始める**: 目的を理解するためユーザーストーリーから開始 +2. **具体的に**: 測定可能な値を使用（「高速」ではなく「2秒以内」） +3. **要件ごとに1つ**: 複合要件を避ける（複数の「しなければならない」を含めない） +4. **すべてをテスト可能に**: 各要件は検証可能でなければならない +5. **依存関係を追跡**: 関連タスクを明確にリンク +6. **最新を保つ**: 作業の進行に応じてステータスを更新 + +## ユーザーとの対話ガイドライン + +**【重要】推測を避け、必ずユーザーに確認する** + +このスキルを使用する際は、以下の原則に従ってユーザーとコミュニケーションを取ってください： + +### 1. 推測禁止の原則 +- プロジェクトの詳細、技術スタック、要件などについて推測しない +- 不明確な点や曖昧な情報がある場合は、必ずユーザーに確認する +- 仮定を立てる必要がある場合は、その仮定を明示してユーザーに確認を求める + +### 2. 選択肢を提示する +ユーザーに確認を求める際は、以下のような形式で選択肢を提示してください： + +**良い例**： +``` +プロジェクトの種類について確認させてください： +A) Webアプリケーション +B) モバイルアプリケーション +C) API/バックエンドサービス +D) その他 + +どれに該当しますか？ +``` + +**良い例（Yes/No形式）**： +``` +このプロジェクトはWebアプリケーションですか？ +- はい +- いいえ +``` + +**悪い例**： +``` +Webアプリケーションとして進めます。 +``` + +### 3. AskUserQuestionツールの活用 + +**【重要】質問が必要な場合は必ずAskUserQuestionツールを使用する** + +複数の選択肢がある場合や、重要な決定が必要な場合は、AskUserQuestionツールを積極的に使用してください。 + +#### 基本方針 +- 不明な点は積極的に質問する +- 質問する時は常にAskUserQuestionツールを使って回答させる +- 選択肢にはそれぞれ、推奨度と理由を提示する + - 推奨度は⭐の5段階評価（⭐⭐⭐⭐⭐：最も推奨、⭐：推奨しない） + +#### 推奨度の評価基準 + +**加点要素**: +- ✅ **ユーザーから明示的な指示がある**: +1〜2⭐ + - 例：「TypeScriptを使いたい」→ TypeScript関連の選択肢を加点 +- ✅ **Web検索により根拠が明確**: +1⭐ + - 例：公式ドキュメントで推奨されている、業界標準として広く採用されている +- ✅ **プロジェクトの既存構成と整合性がある**: +1⭐ + - 例：既にNext.jsを使用している場合、Next.jsエコシステムの選択肢を加点 + +**減点要素**: +- ❌ **根拠が不明確**: -1⭐ + - 例：「一般的には良いと思われる」程度の曖昧な理由 +- ❌ **推論や仮定が含まれる**: -2⭐ + - 例：「おそらく〜だろう」「〜と思われる」などの推測ベース +- ❌ **ユーザーの指示と矛盾する**: -2〜3⭐ + - 例：ユーザーが「JavaScriptで」と言っているのにTypeScriptを推奨 + +**評価の例**: +``` +選択肢A: Next.js + TypeScript +- 基本点: ⭐⭐⭐ +- ユーザーが「Reactベースで」と指示: +1⭐ +- 公式ドキュメントで推奨されている（Web検索確認済み）: +1⭐ +- 最終評価: ⭐⭐⭐⭐⭐ + +選択肢B: 独自フレームワーク +- 基本点: ⭐⭐ +- 根拠が不明確（「良さそう」という推測のみ）: -1⭐ +- 推論が含まれる（「たぶん動く」という仮定）: -2⭐ +- 最終評価: できない（評価不能のため選択肢から除外） +``` + +#### 推奨度付き選択肢の例 + +**良い例**： +``` +技術スタックについて確認させてください： + +A) Next.js + TypeScript ⭐⭐⭐⭐⭐ + 推奨理由：モダンで型安全、SSR/SSG対応、開発者体験が良い + +B) React + JavaScript ⭐⭐⭐ + 推奨理由：シンプルで導入が容易だが、型安全性に欠ける + +C) Vue.js + TypeScript ⭐⭐⭐⭐ + 推奨理由：学習コストが低く、TypeScriptとの組み合わせも良好 + +D) その他 ⭐⭐ + 詳しく教えてください + +どれを選択しますか？ +``` + +**使用場面**： +- プロジェクトタイプの選択 +- 技術スタックの確認 +- アーキテクチャパターンの選択 +- 非機能要件の優先順位付け +- タスクの粒度や見積もりの確認 + +### 4. 確認が必要な場面 + +以下の場合は必ずユーザーに確認してください： + +#### ドキュメント初期化時 +- プロジェクトの種類や目的 +- 対象ユーザー +- 主要な機能 +- 技術的制約 + +#### 要件定義時 +- ユーザーストーリーの優先順位 +- 非機能要件の具体的な値（性能、セキュリティなど） +- 受入基準の妥当性 + +#### 設計時 +- アーキテクチャパターンの選択 +- 技術スタックの選定 +- データモデルの構造 +- 外部サービスとの連携方法 + +#### タスク分解時 +- タスクの粒度 +- 優先順位 +- 見積もり時間 +- 実装の順序 + +### 5. 確認の形式 + +**推奨される確認パターン**： + +1. **二択の確認** + ``` + 〜という理解で正しいですか？ + - はい + - いいえ + ``` + +2. **複数選択** + ``` + 以下のうち、どれに該当しますか？ + A) 選択肢1 + B) 選択肢2 + C) 選択肢3 + D) その他（詳しく教えてください） + ``` + +3. **段階的な確認** + ``` + まず、〜ですか？ + - はい → 次の質問へ + - いいえ → 別の質問へ + ``` + +### 6. 避けるべき表現 + +以下のような推測に基づく表現は避けてください： + +❌ 「おそらく〜でしょう」 +❌ 「一般的には〜です」 +❌ 「〜と仮定して進めます」 +❌ 「〜のようですので」 + +✅ 「〜でしょうか？確認させてください」 +✅ 「以下の選択肢から選んでいただけますか？」 +✅ 「〜という理解で正しいですか？」 + +### 7. 絵文字の使用ルール + +**原則**: 文章では絵文字を使用しない + +- ドキュメント作成時、説明文、コメントなどでは絵文字を使わない + +**良い例**： +```markdown +## 重要な注意事項 +システムのセキュリティを確保するため、以下の要件を必ず満たしてください。 +``` + +**悪い例**： +```markdown +## 重要な注意事項 🚨 +システムのセキュリティを確保するため 🔒、以下の要件を必ず満たしてください ✨ +``` + +### 8. ドキュメント作成の順序と確認プロセス + +**【重要】必ず要求→設計→タスクの順で作成し、各ステップでユーザー確認を取る** + +ドキュメントの作成・修正は以下の順序で進めてください： + +#### 作業の流れ + +1. **requirements.md（要件定義）の作成・修正** + - EARS記法を用いて要件を記述 + - 完成したら必ずユーザーに内容を確認 + - ユーザーの承認を得てから次へ進む + +2. **design.md（設計）の作成・修正** + - requirements.mdの内容を基に設計を記述 + - 完成したら必ずユーザーに内容を確認 + - ユーザーの承認を得てから次へ進む + +3. **tasks.md（タスク）の作成・修正** + - design.mdの内容を基にタスクに分解 + - 完成したら必ずユーザーに内容を確認 + - ユーザーの承認を得て完了 + +#### 確認の取り方 + +各ドキュメント完成時に以下のように確認を求めてください： + +``` +requirements.mdの作成が完了しました。 +内容を確認していただけますか？ + +- 承認して次（design.md）に進む +- 修正が必要 +``` + +#### 注意事項 + +- 各ドキュメントは完全に完成してから次のドキュメントに進む +- ユーザーの承認なしに次のステップに進まない +- 修正が必要な場合は、修正後に再度確認を取る +- 3つのドキュメントを同時に作成・修正しない + +#### ワークフロー例 + +``` +1. requirements.md作成 + ↓ +2. ユーザー確認・承認 + ↓ +3. design.md作成 + ↓ +4. ユーザー確認・承認 + ↓ +5. tasks.md作成 + ↓ +6. ユーザー確認・承認 + ↓ +7. 完了 +``` + +### 9. AIエージェント向けタスク化のガイドライン + +**【重要】タスクはAIエージェントが実行することを前提に作成する** + +tasks.mdを作成・修正する際は、以下の原則に従ってください： + +#### 実装者の前提 + +- すべてのタスクはAIエージェント（Claude Code等）が実装することを前提とする +- 人間の開発者ではなく、AIエージェントが理解しやすい表現を使用する +- 作業時間見積もりはAIエージェントの処理時間として記載する + +#### タスク記述の原則 + +**1. 明確で具体的な指示** + +AIエージェントが迷わないよう、以下の情報を明記してください： + +- 実装すべきファイルパス +- 使用する技術やライブラリ +- 実装の具体的な手順 +- 期待される入出力 + +**良い例**： +```markdown +#### タスク1.1: ユーザー認証APIエンドポイントの実装 + +**説明**: +`src/api/auth.ts`に以下のエンドポイントを実装する： +- POST /api/auth/login - ユーザーログイン処理 +- POST /api/auth/logout - ログアウト処理 +- JWTトークンを使用した認証方式 +- bcryptでパスワードをハッシュ化 + +**受入基準**: +- [ ] login/logoutエンドポイントが実装されている +- [ ] JWTトークンが正しく生成・検証される +- [ ] パスワードがbcryptでハッシュ化されている +- [ ] エラーハンドリングが適切に実装されている +- [ ] ユニットテストが実装され、すべて通過する + +**依存関係**: なし +**推定工数**: 30分（AIエージェント作業時間） +**ステータス**: `TODO` +``` + +**悪い例**： +```markdown +#### タスク1.1: 認証機能を作る + +**説明**: 認証機能を実装してください + +**受入基準**: +- [ ] 認証ができる + +**推定工数**: 2時間 +``` + +**2. AIエージェントが理解しやすい構造化** + +- ファイルパス、関数名、クラス名を明記する +- 技術的な用語を正確に使用する +- 実装の順序を明確にする +- コードの場所を具体的に指定する + +**3. 作業時間見積もりの基準** + +AIエージェントの作業時間として、以下を目安に見積もってください： + +- **シンプルな実装**: 10-20分 + - 単一ファイルの作成 + - 基本的な関数の実装 + - 設定ファイルの追加 + +- **標準的な実装**: 20-40分 + - 複数ファイルの作成・編集 + - APIエンドポイントの実装 + - データモデルの定義 + - 基本的なテストの作成 + +- **複雑な実装**: 40-90分 + - 複数コンポーネントの統合 + - 複雑なロジックの実装 + - 包括的なテストの作成 + - リファクタリング + +- **非常に複雑な実装**: 90分以上 + - さらに小さいタスクへの分解を検討する + +**4. 受入基準の書き方** + +AIエージェントが検証可能な基準を記載してください： + +```markdown +**受入基準**: +- [ ] `src/components/Button.tsx`ファイルが作成されている +- [ ] Buttonコンポーネントがprops（label, onClick, disabled）を受け取る +- [ ] TypeScriptの型定義が含まれている +- [ ] `src/components/Button.test.tsx`にテストが3つ以上ある +- [ ] すべてのテストが`npm test`で通過する +- [ ] ESLintエラーがゼロである +``` + +**5. 技術的な文脈の提供** + +AIエージェントが適切な判断を下せるよう、以下の情報を含めてください： + +- プロジェクトで使用している技術スタック +- コーディング規約やパターン +- 既存のコードベースとの統合方法 +- 参照すべき既存の実装例 + +**例**： +```markdown +**技術的文脈**: +- フレームワーク: Next.js 14 (App Router) +- スタイリング: Tailwind CSS +- 状態管理: Zustand +- 既存のコンポーネントパターンは`src/components/Card.tsx`を参照 +``` + +**6. エラーハンドリングとテストの明記** + +すべてのタスクで以下を明記してください： + +- エラーハンドリングの要件 +- テストの有無と範囲 +- バリデーションの要件 + +#### タスク分解の粒度 + +AIエージェント向けのタスクは、以下の粒度を推奨します： + +- **最小単位**: 1つのファイルまたは1つの機能 +- **推奨時間**: 20-40分程度 +- **最大時間**: 90分を超えないこと（超える場合は分解） + +#### 依存関係の明示 + +AIエージェントが正しい順序で作業できるよう： + +```markdown +**依存関係**: +- タスク1.1（データモデルの定義）が完了していること +- `npm install express`が実行済みであること +- 環境変数`.env`に`DATABASE_URL`が設定されていること +``` + +### 10. テスト駆動開発（TDD）の原則 + +**【重要】実装は原則としてTDD（テスト駆動開発）で進める** + +#### TDDの基本サイクル + +すべての実装タスクは以下のサイクルで進めてください： + +1. **テストを書く** + - 期待される入出力に基づき、まずテストを作成する + - 実装コードは書かず、テストのみを用意する + +2. **テストを実行して失敗を確認する** + - テストが正しく失敗することを確認する + - テストが正しいことを確認できた段階でコミットする + +3. **実装する** + - テストをパスさせる最小限の実装を進める + - 実装中はテストを変更せず、コードを修正し続ける + +4. **すべてのテストが通過するまで繰り返す** + - テストが通過したら、必要に応じてリファクタリングを行う + - リファクタリング後もテストが通過することを確認する + +#### タスク定義におけるTDDの適用 + +tasks.mdでタスクを定義する際は、以下のようにTDDのステップを明記してください： + +**例**： +```markdown +#### タスク1.1: ユーザー認証機能の実装 + +**説明**: +TDDで`src/auth/authenticate.ts`を実装する + +**実装手順（TDD）**: +1. テスト作成: `src/auth/authenticate.test.ts`にテストケースを作成 + - 正常な認証のテスト + - 無効な認証情報のテスト + - 空の入力のテスト +2. テスト実行: すべてのテストが失敗することを確認 +3. テストコミット: テストのみをコミット +4. 実装: `authenticate.ts`を実装してテストを通過させる +5. 実装コミット: すべてのテストが通過したらコミット + +**受入基準**: +- [ ] テストファイル`src/auth/authenticate.test.ts`が存在する +- [ ] テストが3つ以上含まれている +- [ ] 実装前にテストのみのコミットが存在する +- [ ] `src/auth/authenticate.ts`が実装されている +- [ ] すべてのテストが通過する（`npm test`） +- [ ] 実装後のコミットが存在する + +**推定工数**: 40分（AIエージェント作業時間） +- テスト作成・コミット: 15分 +- 実装・テスト通過・コミット: 25分 +``` + +#### TDDのメリット + +- 要件の明確化: テストを書くことで要件が明確になる +- 品質保証: テストが常に存在するため、リグレッションを防げる +- リファクタリングの安全性: テストがあるため、安心してリファクタリングできる +- ドキュメント: テストが実装の使用例となる + +#### TDDの注意点 + +- テストファーストを守る: 実装の前に必ずテストを書く +- テストのコミットを分ける: テストと実装のコミットを分けることで、レビューしやすくなる +- 最小限の実装: テストを通すための最小限の実装から始める +- テストの変更を避ける: 実装中はテストを変更しない（テストが間違っている場合を除く） + +## リソース + +### assets/templates/ +- `requirements_template_ja.md`: 日本語の要件定義テンプレート +- `design_template_ja.md`: 日本語の設計テンプレート +- `tasks_template_ja.md`: 日本語のタスクテンプレート + +### references/ +- `ears_notation_ja.md`: EARS記法の完全な日本語リファレンス +- `examples_ja.md`: 3つすべてのドキュメントタイプの日本語例 + +## 具体的な支援内容 + +このスキルが有効な場合、以下のような支援を提供します： + +### 1. ドキュメント初期化 +プロジェクトに応じたカスタマイズされたテンプレートでdocsディレクトリを作成します。 + +### 2. 要件定義の支援 +- ユーザーストーリーの作成を支援 +- EARS記法に従った要件の記述をガイド +- 要件の曖昧さや不完全性を指摘 + +### 3. 設計文書の作成 +- アーキテクチャ図の作成支援（Mermaid形式） +- コンポーネント設計のテンプレート提供 +- 技術的決定事項の文書化支援 + +### 4. タスク分解 +- 機能を実装可能なタスクに分解 +- 依存関係の明確化 +- 適切な見積もりのガイダンス + +### 5. レビューと改善 +- EARS記法への準拠をチェック +- ドキュメントの完全性を確認 +- 改善点の提案 + +## 拡張可能性 + +このスキルは将来の機能拡張を考慮して設計されています： + +- **進捗管理**: タスクステータスの可視化とレポート生成 +- **自動検証**: EARS記法の自動チェックツール +- **統合機能**: GitHub Issues、Jiraなどとの連携 +- **多言語対応**: 英語版テンプレートの追加 +- **カスタムテンプレート**: プロジェクトタイプ別のテンプレート + +## よくある質問 + +**Q: なぜdocsディレクトリを使うのですか？** +A: `docs`ディレクトリは一般的で、Gitで管理しやすく、他のツールとの互換性が高いためです。 + +**Q: EARS記法は必須ですか？** +A: 推奨されますが、プロジェクトのニーズに応じて調整可能です。ただし、EARS記法を使用することで要件の明確性が大幅に向上します。 + +**Q: タスクのステータスはどのように管理しますか？** +A: マークダウンファイル内で直接更新します。将来的には自動化ツールの追加も検討しています。 + +**Q: このドキュメント形式の利点は何ですか？** +A: 要件・設計・タスクの3つのドキュメントに分けることで、「何を作るか」「どう作るか」「どのように実装するか」が明確に分離され、プロジェクトの見通しが良くなります。 \ No newline at end of file diff --git a/skills/sdd-docs/assets/templates/design_template_ja.md b/skills/sdd-docs/assets/templates/design_template_ja.md new file mode 100644 index 0000000..e8e4c14 --- /dev/null +++ b/skills/sdd-docs/assets/templates/design_template_ja.md @@ -0,0 +1,146 @@ +# 設計 + +## アーキテクチャ概要 +*システムアーキテクチャの高レベルな概要を提供してください。* + +```mermaid +graph TD + A[コンポーネントA] --> B[コンポーネントB] + B --> C[コンポーネントC] + A --> D[コンポーネントD] +``` + +## コンポーネント + +### コンポーネント1: [名前] +**目的**: *このコンポーネントの役割* +**責務**: +- 責務1 +- 責務2 + +**インターフェース**: +- API/メソッド1 +- API/メソッド2 + +### コンポーネント2: [名前] +**目的**: *このコンポーネントの役割* +**責務**: +- 責務1 +- 責務2 + +## データフロー + +### シーケンス: [プロセス名] +```mermaid +sequenceDiagram + participant ユーザー + participant システム + participant データベース + + ユーザー->>システム: リクエスト + システム->>データベース: クエリ + データベース-->>システム: レスポンス + システム-->>ユーザー: 結果 +``` + +## API設計 + +### エンドポイント: [/api/resource] +**メソッド**: GET/POST/PUT/DELETE +**目的**: *このエンドポイントの機能* +**リクエスト**: +```json +{ + "field1": "value1", + "field2": "value2" +} +``` +**レスポンス**: +```json +{ + "status": "success", + "data": {} +} +``` + +## データベーススキーマ + +### テーブル: [table_name] +| カラム | 型 | 制約 | 説明 | +|--------|------|-------------|-------------| +| id | UUID | PRIMARY KEY | 一意識別子 | +| created_at | TIMESTAMP | NOT NULL | 作成日時 | +| updated_at | TIMESTAMP | NOT NULL | 更新日時 | + +## 技術的決定事項 + +### 決定1: [技術/アプローチの選択] +**検討した選択肢**: +1. 選択肢A - メリット/デメリット +2. 選択肢B - メリット/デメリット + +**決定**: 選択肢A +**根拠**: *この選択肢を選んだ理由* + +## セキュリティ考慮事項 +*セキュリティ対策と考慮事項を記述してください。* + +## パフォーマンス考慮事項 +*パフォーマンス最適化と考慮事項を記述してください。* + +## エラー処理 +*エラー処理戦略と復旧メカニズムを記述してください。* + +--- + +## 設計書作成のガイド + +### アーキテクチャ図の種類 +- **コンポーネント図**: システムの主要な部品と関係性 +- **シーケンス図**: 処理の流れと相互作用 +- **データフロー図**: データの移動と変換 +- **配置図**: 物理的な構成とネットワーク + +### Mermaid図の基本構文 + +#### グラフ（フローチャート） +```mermaid +graph TD + A[開始] --> B{判定} + B -->|Yes| C[処理1] + B -->|No| D[処理2] + C --> E[終了] + D --> E +``` + +#### シーケンス図 +```mermaid +sequenceDiagram + participant A as クライアント + participant B as サーバー + participant C as DB + + A->>B: リクエスト送信 + B->>C: データ取得 + C-->>B: データ返却 + B-->>A: レスポンス返却 +``` + +### コンポーネント設計のポイント +1. **単一責任の原則**: 各コンポーネントは1つの明確な目的を持つ +2. **疎結合**: コンポーネント間の依存関係を最小限に +3. **高凝集**: 関連する機能を同じコンポーネントに +4. **インターフェース定義**: 明確な入出力を定義 + +### API設計のベストプラクティス +- RESTful原則に従う +- 適切なHTTPステータスコードを使用 +- バージョニング戦略を定義 +- エラーレスポンスの一貫性 +- ペイロードの検証とサニタイゼーション + +### データベース設計の考慮点 +- 正規化と非正規化のバランス +- インデックス戦略 +- トランザクション境界 +- バックアップとリカバリ計画 \ No newline at end of file diff --git a/skills/sdd-docs/assets/templates/requirements_template_ja.md b/skills/sdd-docs/assets/templates/requirements_template_ja.md new file mode 100644 index 0000000..a0d112b --- /dev/null +++ b/skills/sdd-docs/assets/templates/requirements_template_ja.md @@ -0,0 +1,67 @@ +# 要件定義 + +## 概要 +*この機能/システムの高レベルな目的と目標を記述してください。* + +## ユーザーストーリー + +### ストーリー1: [ユーザーストーリーのタイトル] +**私は** [ユーザーの種類]として +**〜したい** [目標/要望] +**なぜなら** [利益/価値] + +#### 受入基準（EARS記法） + +- **REQ-001**: [条件/トリガー]の時、システムは[期待される振る舞い]しなければならない +- **REQ-002**: もし[前提条件]ならば、システムは[期待される振る舞い]しなければならない +- **REQ-003**: [継続条件]の間、システムは[期待される振る舞い]しなければならない +- **REQ-004**: [場所/コンテキスト]において、システムは[期待される振る舞い]しなければならない + +### ストーリー2: [ユーザーストーリーのタイトル] +**私は** [ユーザーの種類]として +**〜したい** [目標/要望] +**なぜなら** [利益/価値] + +#### 受入基準（EARS記法） + +- **REQ-005**: [条件/トリガー]の時、システムは[期待される振る舞い]しなければならない + +## 非機能要件 + +### 性能要件 +- **NFR-001**: システムは[性能要件]を満たさなければならない + +### セキュリティ要件 +- **NFR-002**: システムは[セキュリティ要件]を満たさなければならない + +### ユーザビリティ要件 +- **NFR-003**: システムは[ユーザビリティ要件]を満たさなければならない + +## 依存関係 +*外部依存関係や前提条件をリストアップしてください。* + +## スコープ外 +*この仕様に含まれないものを明示的にリストアップしてください。* + +--- + +## EARS記法の書き方ガイド + +### 基本パターン +- **基本形**: システムは[振る舞い]しなければならない +- **イベント駆動**: [イベント]の時、システムは[振る舞い]しなければならない +- **条件付き**: もし[条件]ならば、システムは[振る舞い]しなければならない +- **継続的**: [状態]の間、システムは[振る舞い]しなければならない +- **場所/コンテキスト**: [場所]において、システムは[振る舞い]しなければならない + +### 良い要件の例 +- REQ-001: ユーザーがログインボタンをクリックした時、システムは2秒以内に認証処理を完了しなければならない +- REQ-002: もしパスワードが間違っている場合、システムはエラーメッセージを表示しなければならない +- REQ-003: ファイルアップロード中、システムは進捗状況を表示しなければならない +- REQ-004: モバイル環境において、システムはレスポンシブデザインで表示しなければならない +- NFR-001: システムは同時に1000人のユーザーアクセスを処理できなければならない + +### 避けるべき表現 +- 「〜すべきである」「〜することが望ましい」→ 「〜しなければならない」を使用 +- 曖昧な表現（「速く」「使いやすく」）→ 具体的な数値や基準を使用 +- 複合要件（複数の「しなければならない」）→ 個別の要件に分割 \ No newline at end of file diff --git a/skills/sdd-docs/assets/templates/tasks_template_ja.md b/skills/sdd-docs/assets/templates/tasks_template_ja.md new file mode 100644 index 0000000..6b66d47 --- /dev/null +++ b/skills/sdd-docs/assets/templates/tasks_template_ja.md @@ -0,0 +1,185 @@ +# タスク + +> このドキュメントはAIエージェント（Claude Code等）が実装を行うことを前提としています。 +> タスクは具体的なファイルパス、技術仕様、検証可能な受入基準を含めて記載してください。 + +## 実装計画 + +### フェーズ1: 基盤構築 +*推定期間: X分（AIエージェント作業時間）* + +#### タスク1.1: [タスクタイトル] +**説明**: +*AIエージェントが実装すべき内容を具体的に記載* +- 対象ファイルパス +- 実装する機能の詳細 +- 使用する技術・ライブラリ + +**技術的文脈**: +*AIエージェントの判断に必要な情報* +- 技術スタック +- 参照すべき既存コード +- コーディング規約 + +**受入基準**: +- [ ] *検証可能な基準（ファイル存在、機能動作、テスト通過など）* +- [ ] *検証可能な基準* + +**依存関係**: なし +**推定工数**: X分（AIエージェント作業時間） +**ステータス**: `TODO` + +#### タスク1.2: [タスクタイトル] +**説明**: +*AIエージェントが実装すべき内容を具体的に記載* +- 対象ファイルパス +- 実装する機能の詳細 +- 使用する技術・ライブラリ + +**技術的文脈**: +*AIエージェントの判断に必要な情報* + +**受入基準**: +- [ ] *検証可能な基準* +- [ ] *検証可能な基準* + +**依存関係**: タスク1.1 +**推定工数**: X分（AIエージェント作業時間） +**ステータス**: `TODO` + +### フェーズ2: コア機能 +*推定期間: X分（AIエージェント作業時間）* + +#### タスク2.1: [タスクタイトル] +**説明**: +*AIエージェントが実装すべき内容を具体的に記載* + +**技術的文脈**: +*AIエージェントの判断に必要な情報* + +**受入基準**: +- [ ] *検証可能な基準* +- [ ] *検証可能な基準* + +**依存関係**: フェーズ1 +**推定工数**: X分（AIエージェント作業時間） +**ステータス**: `TODO` + +#### タスク2.2: [タスクタイトル] +**説明**: +*AIエージェントが実装すべき内容を具体的に記載* + +**技術的文脈**: +*AIエージェントの判断に必要な情報* + +**受入基準**: +- [ ] *検証可能な基準* +- [ ] *検証可能な基準* + +**依存関係**: タスク2.1 +**推定工数**: X分（AIエージェント作業時間） +**ステータス**: `TODO` + +### フェーズ3: 統合とテスト +*推定期間: X分（AIエージェント作業時間）* + +#### タスク3.1: [タスクタイトル] +**説明**: +*AIエージェントが実装すべき内容を具体的に記載* + +**技術的文脈**: +*AIエージェントの判断に必要な情報* + +**受入基準**: +- [ ] *検証可能な基準* +- [ ] *検証可能な基準* + +**依存関係**: フェーズ2 +**推定工数**: X分（AIエージェント作業時間） +**ステータス**: `TODO` + +## タスクステータスの凡例 +- `TODO` - 未着手 +- `IN_PROGRESS` - 作業中 +- `BLOCKED` - 依存関係や問題によりブロック中 +- `REVIEW` - レビュー待ち +- `DONE` - 完了 + +## リスクと軽減策 + +### リスク1: [リスクの説明] +**影響度**: 高/中/低 +**発生確率**: 高/中/低 +**軽減策**: *このリスクへの対処方法* + +### リスク2: [リスクの説明] +**影響度**: 高/中/低 +**発生確率**: 高/中/低 +**軽減策**: *このリスクへの対処方法* + +## 備考 +*実装に関する追加の注意事項や考慮事項* + +--- + +## タスク管理のガイド + +### AIエージェント向けタスクの粒度 +適切なタスクサイズの目安（AIエージェント作業時間）： +- **シンプルな実装**: 10-20分（単一ファイル、基本的な関数、設定ファイル） +- **標準的な実装**: 20-40分（複数ファイル、APIエンドポイント、データモデル、基本テスト） +- **複雑な実装**: 40-90分（複数コンポーネント統合、複雑なロジック、包括的テスト） +- **非常に複雑**: 90分以上 → さらに分解を検討 + +### AIエージェント向け良いタスク定義の特徴 +1. **具体的**: ファイルパス、関数名、クラス名を明記 +2. **測定可能**: 検証可能な受入基準（テスト通過、ファイル存在など） +3. **達成可能**: AIエージェントが実行可能な粒度 +4. **文脈提供**: 技術スタック、参照コード、コーディング規約を明記 +5. **期限付き**: AIエージェント作業時間の見積もりを明記 + +### AIエージェント向け受入基準の書き方 +- チェックボックス形式で記載 +- AIエージェントが検証可能な基準（ファイル存在、テスト通過、エラーゼロなど） +- 具体的なファイルパスやコマンドを含める +- 技術的に測定可能な条件を明記 + +### 依存関係の管理 +- **前提タスク**: このタスクの開始前に完了が必要 +- **並行可能**: 同時に進められるタスク +- **後続タスク**: このタスクの完了後に開始可能 + +### ステータス遷移のルール +``` +TODO → IN_PROGRESS → REVIEW → DONE + ↓ + BLOCKED + ↓ + IN_PROGRESS +``` + +### フェーズ分けの考え方 +1. **基盤構築**: 環境設定、基本構造 +2. **コア機能**: 主要な機能の実装 +3. **拡張機能**: 追加機能、改善 +4. **統合・テスト**: 結合、品質保証 +5. **リリース準備**: デプロイ、文書化 + +### リスク評価のマトリクス +| | 低影響 | 中影響 | 高影響 | +|---|--------|--------|--------| +| **高確率** | 注意 | 対策必要 | 最優先対応 | +| **中確率** | 監視 | 注意 | 対策必要 | +| **低確率** | 受容 | 監視 | 注意 | + +### AIエージェント作業時間の見積もり +- 基本的な実装: 楽観的見積もり × 1.2-1.5 +- 不確実性が高い場合: × 1.5-2.0 +- 新しいライブラリや複雑な統合: × 2.0-2.5 +- AIエージェントの能力範囲内のタスクに限定すること + +### 進捗管理のヒント +- 毎日ステータスを更新 +- ブロッカーは即座に報告 +- 見積もりと実績の差を記録 +- 振り返りで改善点を特定 \ No newline at end of file diff --git a/skills/sdd-docs/references/ears_notation_ja.md b/skills/sdd-docs/references/ears_notation_ja.md new file mode 100644 index 0000000..598139a --- /dev/null +++ b/skills/sdd-docs/references/ears_notation_ja.md @@ -0,0 +1,197 @@ +# EARS記法リファレンス（日本語版） + +## EARS記法とは + +EARS（Easy Approach to Requirements Syntax）は、明確で、曖昧さがなく、テスト可能な要件を記述するための構造化された記法です。要件文書の曖昧さを減らし、品質を向上させるために開発されました。 + +## EARS記法のパターン + +### 基本パターン +``` +システムは[必要な振る舞い]しなければならない +``` +常に適用される要件に使用します。 + +**例**: +- REQ-001: システムは、すべてのパスワードをbcryptで最低12ラウンドで暗号化しなければならない + +### イベント駆動パターン +``` +[トリガーイベント]の時、システムは[必要な振る舞い]しなければならない +``` +特定のイベントによってトリガーされる要件に使用します。 + +**例**: +- REQ-002: ユーザーがログインフォームを送信した時、システムは2秒以内に認証を完了しなければならない +- REQ-003: データベース接続が失敗した時、システムは指数バックオフで最大3回まで再接続を試みなければならない + +### 条件パターン +``` +もし[前提条件]ならば、システムは[必要な振る舞い]しなければならない +``` +特定の状態や条件に依存する要件に使用します。 + +**例**: +- REQ-004: もしユーザーが認証されていない場合、システムはログインページにリダイレクトしなければならない +- REQ-005: もしキャッシュが5分以上古い場合、システムはデータベースからデータを更新しなければならない + +### 継続パターン +``` +[条件が真である]間、システムは[必要な振る舞い]しなければならない +``` +特定の条件下で維持されるべき要件に使用します。 + +**例**: +- REQ-006: ファイルアップロード中、システムは進捗インジケーターを表示しなければならない +- REQ-007: ユーザーセッションがアクティブな間、システムは15分ごとに認証トークンを更新しなければならない + +### 場所パターン +``` +[場所やコンテキスト]において、システムは[必要な振る舞い]しなければならない +``` +特定の場所やコンテキストに固有の要件に使用します。 + +**例**: +- REQ-008: ユーザーがEU地域にいる場合、システムはGDPR同意バナーを表示しなければならない +- REQ-009: ネットワーク遅延が100msを超える環境において、システムはローカルキャッシュを使用しなければならない + +### 複合パターン（組み合わせ） +``` +[イベント]の時、もし[条件]ならば、システムは[必要な振る舞い]しなければならない +``` +複数の条件を持つ要件に使用します。 + +**例**: +- REQ-010: ユーザーがフォームを送信した時、もしデータ検証が失敗した場合、システムはフィールド固有のエラーメッセージを表示しなければならない + +## ベストプラクティス + +### 1. 具体的で測定可能な用語を使用 +❌ **悪い例:** システムは速くなければならない +✅ **良い例:** システムはユーザークエリに200ミリ秒以内に応答しなければならない + +### 2. 1つの文に1つの要件 +❌ **悪い例:** システムはユーザーデータを検証し、保存し、確認メールを送信しなければならない +✅ **良い例:** +- REQ-011: システムは定義されたスキーマに対してユーザーデータを検証しなければならない +- REQ-012: ユーザーデータが正常に検証された時、システムはデータベースに保存しなければならない +- REQ-013: ユーザーデータが正常に保存された時、システムは確認メールを送信しなければならない + +### 3. 曖昧な用語を避ける +避けるべき用語: すべきである、できる、かもしれない、可能性がある、おそらく、通常、一般的に、しばしば、典型的に + +常に使用する: しなければならない（必須要件の場合） + +### 4. 受入基準を含める +各要件はテスト可能でなければなりません。自問してください：「この要件が満たされていることをどのように検証するか？」 + +### 5. 一貫した番号付けを使用 +- 機能要件: REQ-XXX（REQ-001、REQ-002など） +- 非機能要件: NFR-XXX（NFR-001、NFR-002など） + +## カテゴリー別の一般的なパターン + +### ユーザーインターフェース要件 +``` +[ユーザーアクション]の時、システムは[UI応答]しなければならない +``` +例: +- ツールチップアイコンにマウスを重ねた時、システムはヘルプテキストを表示しなければならない +- フォームフィールドがフォーカスを失った時、システムはフィールド内容を検証しなければならない + +### パフォーマンス要件 +``` +システムは[時間制限]内に[アクション]しなければならない +[条件]において、システムは[パフォーマンス制約]を満たさなければならない +``` +例: +- システムは4G接続でダッシュボードを3秒以内に読み込まなければならない +- 同時ユーザーが1000人を超える場合、システムは応答時間を5秒以下に保たなければならない + +### セキュリティ要件 +``` +システムは[セキュリティ対策]を実施しなければならない +もし[セキュリティ条件]ならば、システムは[セキュリティアクション]を実行しなければならない +``` +例: +- システムは管理者アカウントに多要素認証を強制しなければならない +- 5分以内に3回のログイン失敗が発生した場合、システムはアカウントを15分間ロックしなければならない + +### データ要件 +``` +[データイベント]の時、システムは[データアクション]を実行しなければならない +システムは[データ制約]を満たさなければならない +``` +例: +- ユーザーデータが削除された時、システムは90日間監査ログを保持しなければならない +- システムはタイムスタンプをUTC形式で保存しなければならない + +### 統合要件 +``` +[外部イベント]の時、システムは[統合アクション]を実行しなければならない +もし[統合条件]ならば、システムは[フォールバック動作]を実行しなければならない +``` +例: +- 決済プロバイダーからWebhookを受信した時、システムは注文ステータスを更新しなければならない +- もし外部APIが利用できない場合、システムはリクエストを再試行のためにキューに入れなければならない + +## 検証チェックリスト + +要件を最終決定する前に、以下を確認してください： + +- [ ] 各要件は「しなければならない」を使用している（すべきである/できる/かもしれないではない） +- [ ] 各要件は個別にテスト可能である +- [ ] 要件は一貫して番号付けされている（REQ-XXXまたはNFR-XXX） +- [ ] 要件に複数の「しなければならない」文が含まれていない +- [ ] すべてのトリガーイベントが明確に定義されている +- [ ] すべての時間制約に具体的な値が含まれている +- [ ] 曖昧な用語が使用されていない +- [ ] 各要件は独立している（コンテキストに依存しない） + +## 良く書かれた要件の例 + +### 認証システム +- REQ-101: システムはパスワードを最低12文字以上要求しなければならない +- REQ-102: ユーザーが誤ったパスワードを入力した時、システムは失敗ログインカウンターを増加させなければならない +- REQ-103: もし失敗ログインカウンターが5に達した場合、システムはアカウントを30分間ロックしなければならない +- REQ-104: アカウントがロックされている間、システムは残りのロック時間を表示しなければならない +- REQ-105: ロック期間が終了した時、システムは失敗ログインカウンターをゼロにリセットしなければならない + +### ファイルアップロードシステム +- REQ-201: システムは最大100MBまでのファイルアップロードを受け入れなければならない +- REQ-202: ファイルがアップロードされた時、システムはマルウェアをスキャンしなければならない +- REQ-203: もしマルウェアが検出された場合、システムはファイルを拒否し、インシデントをログに記録しなければならない +- REQ-204: ファイルがアップロードされている間、システムはアップロード進捗をパーセンテージで表示しなければならない +- REQ-205: ユーザーのストレージ容量を超過する場合、システムは適切なエラーメッセージと共にアップロードを拒否しなければならない + +### 通知システム +- REQ-301: システムはトリガーイベントから5分以内にメール通知を配信しなければならない +- REQ-302: 通知の送信に失敗した時、システムは指数バックオフで最大3回まで再試行しなければならない +- REQ-303: もしすべての再試行が失敗した場合、システムは失敗をログに記録し、運用チームに警告しなければならない +- REQ-304: システムはユーザーの通知設定を尊重しなければならない +- REQ-305: ユーザーがメール通知をオプトアウトしている場合、システムはアプリ内通知のみを送信しなければならない + +## 日本語でのEARS記法の注意点 + +### 文体の統一 +- 「しなければならない」で統一（「する必要がある」「するものとする」は使わない） +- 主語は「システムは」で統一 + +### 時制の扱い +- 現在形で記述（「した時」ではなく「する時」） +- 継続的な動作は「〜している間」 + +### 条件表現 +- 「もし〜ならば」（仮定） +- 「〜の場合」（状態） +- 「〜の時」（タイミング） + +### 数値の表記 +- アラビア数字を使用（「五分」ではなく「5分」） +- 単位を明確に記載 + +## 参考文献 + +- EARS - The Easy Approach to Requirements Syntax (Alistair Mavin et al.) +- IEEE 830-1998 Standard for Software Requirements Specifications +- ISO/IEC/IEEE 29148:2018 Requirements Engineering \ No newline at end of file diff --git a/skills/sdd-docs/references/examples_ja.md b/skills/sdd-docs/references/examples_ja.md new file mode 100644 index 0000000..99076f6 --- /dev/null +++ b/skills/sdd-docs/references/examples_ja.md @@ -0,0 +1,492 @@ +# ドキュメント例集（日本語版） + +## requirements.md の例 - ECショッピングカート + +```markdown +# 要件定義 + +## 概要 +本仕様は、ユーザーが商品を追加し、数量を管理し、チェックアウトに進むことができるECサイトのショッピングカート機能の要件を定義します。 + +## ユーザーストーリー + +### ストーリー1: 商品をカートに追加 +**私は** 顧客として +**商品をショッピングカートに追加したい** +**なぜなら** 一度の取引で複数の商品を購入できるから + +#### 受入基準（EARS記法） + +- **REQ-001**: ユーザーが「カートに追加」ボタンをクリックした時、システムは500ms以内に商品をショッピングカートに追加しなければならない +- **REQ-002**: 商品がカートに追加された時、システムは3秒間確認メッセージを表示しなければならない +- **REQ-003**: もし商品が既にカートに存在する場合、システムは重複エントリを追加する代わりに数量を増やさなければならない +- **REQ-004**: 商品の在庫がゼロの場合、システムは「カートに追加」ボタンを無効化し、「在庫切れ」と表示しなければならない + +### ストーリー2: カート内容の管理 +**私は** 顧客として +**カート内容を表示し、変更したい** +**なぜなら** チェックアウト前に購入内容を調整できるから + +#### 受入基準（EARS記法） + +- **REQ-005**: システムは商品名、価格、数量、小計を含むすべてのカート商品を表示しなければならない +- **REQ-006**: ユーザーが数量を変更した時、システムは200ms以内にカート合計を更新しなければならない +- **REQ-007**: ユーザーが「削除」をクリックした時、システムは確認後に商品をカートから削除しなければならない +- **REQ-008**: もしカートが空の場合、システムは「カートは空です」と買い物継続へのリンクを表示しなければならない +- **REQ-009**: カートに商品が含まれている間、システムは税金と配送見積もりを含む合計価格を表示しなければならない + +### ストーリー3: カート状態の永続化 +**私は** 顧客として +**カートを保存してもらいたい** +**なぜなら** 後で戻って購入を完了できるから + +#### 受入基準（EARS記法） + +- **REQ-010**: ログインユーザーがカートに商品を追加した時、システムはカートをデータベースに永続化しなければならない +- **REQ-011**: ログインユーザーがブラウザを閉じた後に戻った時、システムは以前のカートを復元しなければならない +- **REQ-012**: ユーザーがログインしていない場合、システムはカートをローカルストレージに30日間保存しなければならない +- **REQ-013**: 匿名ユーザーがログインした時、システムはローカルカートを既存の保存済みカートとマージしなければならない + +## 非機能要件 + +### パフォーマンス +- **NFR-001**: システムは4G接続でカートページを2秒以内に読み込まなければならない +- **NFR-002**: システムは最大10,000人のユーザーの同時カート操作を処理できなければならない + +### セキュリティ +- **NFR-003**: システムは不正操作を防ぐためすべての価格情報をサーバーサイドで検証しなければならない +- **NFR-004**: システムはカート関連のすべての通信にHTTPSを使用しなければならない + +### ユーザビリティ +- **NFR-005**: システムはWCAG 2.1レベルAAの基準に従ってアクセシブルでなければならない +- **NFR-006**: システムは320pxからの画面幅のモバイルデバイスをサポートしなければならない + +## 依存関係 +- 商品の在庫と価格情報のための商品カタログサービス +- ログインユーザーのカート永続化のためのユーザー認証サービス +- チェックアウト処理のための決済ゲートウェイ + +## スコープ外 +- ウィッシュリスト機能 +- あとで買う機能 +- カート共有機能 +- プロモーションコードの適用（チェックアウトサービスで処理） +``` + +## design.md の例 - タスク管理API + +```markdown +# 設計 + +## アーキテクチャ概要 +タスク管理APIは、タスク管理、ユーザー認証、通知サービス間の関心事を分離したマイクロサービスアプローチによるRESTfulアーキテクチャパターンに従います。 + +\`\`\`mermaid +graph TD + Client[クライアントアプリ] + Gateway[APIゲートウェイ] + Auth[認証サービス] + Task[タスクサービス] + Notification[通知サービス] + Cache[Redisキャッシュ] + DB[(PostgreSQL)] + Queue[メッセージキュー] + + Client --> Gateway + Gateway --> Auth + Gateway --> Task + Task --> Cache + Task --> DB + Task --> Queue + Queue --> Notification +\`\`\` + +## コンポーネント + +### コンポーネント1: APIゲートウェイ +**目的**: リクエストルーティング、認証処理、レート制限 +**責務**: +- 適切なマイクロサービスへのリクエストルーティング +- JWTトークン検証 +- レート制限（ユーザーあたり100リクエスト/分） +- リクエスト/レスポンスログ + +**インターフェース**: +- REST APIエンドポイント（パブリック向け） +- gRPCによる内部サービス通信 + +### コンポーネント2: タスクサービス +**目的**: タスク管理のコアビジネスロジック +**責務**: +- タスクのCRUD操作 +- タスク割り当てとステータス管理 +- 期限追跡とリマインダー +- タスク検索とフィルタリング + +**インターフェース**: +- POST /api/tasks - タスク作成 +- GET /api/tasks - タスク一覧 +- PUT /api/tasks/{id} - タスク更新 +- DELETE /api/tasks/{id} - タスク削除 + +### コンポーネント3: 通知サービス +**目的**: すべての通知配信を処理 +**責務**: +- タスク割り当てのメール通知 +- 期限リマインダー +- ステータス変更通知 +- 通知設定管理 + +## データフロー + +### シーケンス: 割り当て付きタスク作成 +\`\`\`mermaid +sequenceDiagram + participant Client as クライアント + participant Gateway as ゲートウェイ + participant Auth as 認証 + participant TaskService as タスクサービス + participant DB as データベース + participant Queue as キュー + participant NotificationService as 通知サービス + + Client->>Gateway: POST /api/tasks + Gateway->>Auth: JWT検証 + Auth-->>Gateway: ユーザー検証済み + Gateway->>TaskService: タスク作成リクエスト + TaskService->>DB: タスク挿入 + DB-->>TaskService: タスク作成完了 + TaskService->>Queue: 割り当てイベント発行 + TaskService-->>Gateway: タスクレスポンス + Gateway-->>Client: 201 Created + Queue->>NotificationService: 割り当てイベント + NotificationService->>NotificationService: メール送信 +\`\`\` + +## API設計 + +### エンドポイント: POST /api/tasks +**メソッド**: POST +**目的**: 新しいタスクを作成 +**リクエスト**: +\`\`\`json +{ + "title": "プロジェクト提案書の完成", + "description": "第4四半期プロジェクト提案書の草稿作成", + "assignee_id": "user-123", + "due_date": "2024-10-15T17:00:00Z", + "priority": "high", + "tags": ["project", "q4", "proposal"] +} +\`\`\` +**レスポンス**: +\`\`\`json +{ + "id": "task-456", + "title": "プロジェクト提案書の完成", + "status": "pending", + "created_at": "2024-10-01T10:30:00Z", + "created_by": "user-789" +} +\`\`\` + +## データベーススキーマ + +### テーブル: tasks +| カラム | 型 | 制約 | 説明 | +|--------|------|-------------|-------------| +| id | UUID | PRIMARY KEY | タスク識別子 | +| title | VARCHAR(255) | NOT NULL | タスクタイトル | +| description | TEXT | | タスク詳細説明 | +| status | ENUM | NOT NULL | pending, in_progress, completed, cancelled | +| assignee_id | UUID | FOREIGN KEY | usersテーブルへの参照 | +| due_date | TIMESTAMP | | タスク期限 | +| priority | ENUM | DEFAULT 'medium' | low, medium, high, urgent | +| created_at | TIMESTAMP | NOT NULL | 作成タイムスタンプ | +| updated_at | TIMESTAMP | NOT NULL | 最終更新タイムスタンプ | + +### テーブル: task_history +| カラム | 型 | 制約 | 説明 | +|--------|------|-------------|-------------| +| id | UUID | PRIMARY KEY | 履歴エントリ識別子 | +| task_id | UUID | FOREIGN KEY, NOT NULL | tasksテーブルへの参照 | +| user_id | UUID | FOREIGN KEY, NOT NULL | 変更を行ったユーザー | +| action | VARCHAR(50) | NOT NULL | 変更の種類 | +| old_value | JSONB | | 以前の状態 | +| new_value | JSONB | | 新しい状態 | +| created_at | TIMESTAMP | NOT NULL | 変更発生時刻 | + +## 技術的決定事項 + +### 決定1: データベースの選択 +**検討した選択肢**: +1. PostgreSQL - JSONB対応のリレーショナルデータベース +2. MongoDB - 柔軟なスキーマを持つドキュメントデータベース + +**決定**: PostgreSQL +**根拠**: 強い一貫性要件、エンティティ間の複雑な関係、ACIDトランザクションの必要性、チームのPostgreSQL専門知識 + +### 決定2: キャッシング戦略 +**検討した選択肢**: +1. Redis - 永続化オプション付きインメモリキャッシュ +2. Memcached - シンプルなインメモリキャッシュ + +**決定**: Redis +**根拠**: キャッシュ永続化の必要性、リアルタイム更新のためのpub/sub機能、複雑なデータ構造のサポート + +## セキュリティ考慮事項 +- ヘルスチェック以外のすべてのエンドポイントでJWT認証が必要 +- レート制限による悪用防止（ユーザーあたり100リク/分、書き込み操作は10リク/分） +- すべてのユーザー提供データの入力検証 +- パラメータ化クエリによるSQLインジェクション防止 +- 出力エンコーディングによるXSS防止 + +## パフォーマンス考慮事項 +- 頻繁にクエリされるカラムのデータベースインデックス（assignee_id、status、due_date） +- 頻繁にアクセスされるタスクのRedisキャッシュ（TTL: 5分） +- リストエンドポイントのページネーション（デフォルト: 20件、最大: 100件） +- メッセージキューによる通知の非同期処理 +- データベース接続のコネクションプーリング（プールサイズ: 20） + +## エラー処理 +- エラーコード付き構造化エラーレスポンス +- キャッシュ利用不可時のグレースフルデグレデーション +- 外部サービス呼び出しのサーキットブレーカー +- 一時的な障害に対する指数バックオフ付き再試行ロジック +- デバッグ用の包括的なログ記録 +``` + +## tasks.md の例 - ユーザー認証機能 + +```markdown +# タスク + +## 実装計画 + +### フェーズ1: 基盤構築 +*推定期間: 3日* + +#### タスク1.1: データベーススキーマ設定 +**説明**: ユーザー、セッション、パスワードリセットトークンのデータベーステーブルを作成 +**受入基準**: +- [ ] email、password_hash、created_at、updated_atを持つusersテーブル作成 +- [ ] token、user_id、expires_atを持つsessionsテーブル作成 +- [ ] パスワードリセットトークンテーブル作成 +- [ ] データベースマイグレーションは可逆的 +- [ ] パフォーマンス向上のためのインデックス追加 + +**依存関係**: なし +**推定工数**: 4時間 +**ステータス**: `TODO` + +#### タスク1.2: 環境設定 +**説明**: 環境変数と設定管理のセットアップ +**受入基準**: +- [ ] JWT秘密鍵の設定 +- [ ] データベース接続文字列の設定 +- [ ] メールサービス認証情報の設定 +- [ ] 起動時の設定検証 + +**依存関係**: なし +**推定工数**: 2時間 +**ステータス**: `TODO` + +### フェーズ2: コア認証 +*推定期間: 5日* + +#### タスク2.1: ユーザー登録エンドポイント +**説明**: POST /auth/registerエンドポイントの実装 +**受入基準**: +- [ ] メール検証実装 +- [ ] パスワード強度要件の強制（最低12文字、複雑性） +- [ ] bcryptでのパスワードハッシュ（12ラウンド） +- [ ] 重複メールチェック +- [ ] ウェルカムメール送信 +- [ ] 90%以上のカバレッジを持つユニットテスト + +**依存関係**: タスク1.1、タスク1.2 +**推定工数**: 8時間 +**ステータス**: `TODO` + +#### タスク2.2: ログインエンドポイント +**説明**: POST /auth/loginエンドポイントの実装 +**受入基準**: +- [ ] メール/パスワード検証 +- [ ] JWTトークン生成（15分有効期限） +- [ ] リフレッシュトークン生成（7日有効期限） +- [ ] 失敗ログイン試行の追跡 +- [ ] 5回失敗後のアカウントロックアウト +- [ ] 90%以上のカバレッジを持つユニットテスト + +**依存関係**: タスク2.1 +**推定工数**: 6時間 +**ステータス**: `TODO` + +#### タスク2.3: トークンリフレッシュエンドポイント +**説明**: POST /auth/refreshエンドポイントの実装 +**受入基準**: +- [ ] リフレッシュトークンの検証 +- [ ] 新しいアクセストークンの生成 +- [ ] リフレッシュトークンのローテーション +- [ ] 古いリフレッシュトークンの無効化 +- [ ] 期限切れトークンの適切な処理 + +**依存関係**: タスク2.2 +**推定工数**: 4時間 +**ステータス**: `TODO` + +#### タスク2.4: ログアウトエンドポイント +**説明**: POST /auth/logoutエンドポイントの実装 +**受入基準**: +- [ ] 現在のセッションの無効化 +- [ ] リフレッシュトークンのクリア +- [ ] セキュリティイベントのログ +- [ ] 既にログアウト済み状態の処理 + +**依存関係**: タスク2.2 +**推定工数**: 3時間 +**ステータス**: `TODO` + +### フェーズ3: パスワード管理 +*推定期間: 3日* + +#### タスク3.1: パスワードリセットリクエスト +**説明**: POST /auth/password-resetエンドポイントの実装 +**受入基準**: +- [ ] セキュアなリセットトークンの生成 +- [ ] リンク付きリセットメールの送信 +- [ ] 1時間後のトークン有効期限 +- [ ] リセットリクエストのレート制限（1時間に3回） +- [ ] セキュリティイベントのログ + +**依存関係**: タスク2.1 +**推定工数**: 5時間 +**ステータス**: `TODO` + +#### タスク3.2: パスワードリセット確認 +**説明**: POST /auth/password-reset/confirmエンドポイントの実装 +**受入基準**: +- [ ] リセットトークンの検証 +- [ ] パスワード要件の強制 +- [ ] すべての既存セッションの無効化 +- [ ] 確認メールの送信 +- [ ] トークン再利用の防止 + +**依存関係**: タスク3.1 +**推定工数**: 4時間 +**ステータス**: `TODO` + +### フェーズ4: 統合とテスト +*推定期間: 2日* + +#### タスク4.1: 統合テスト +**説明**: 包括的な統合テストの作成 +**受入基準**: +- [ ] 完全な登録フローのテスト +- [ ] ログイン/ログアウトサイクルのテスト +- [ ] パスワードリセットフローのテスト +- [ ] トークンリフレッシュフローのテスト +- [ ] エラーシナリオのテスト +- [ ] 85%以上のコードカバレッジ達成 + +**依存関係**: フェーズ2、フェーズ3 +**推定工数**: 8時間 +**ステータス**: `TODO` + +#### タスク4.2: セキュリティテスト +**説明**: セキュリティ検証の実施 +**受入基準**: +- [ ] SQLインジェクション防止のテスト +- [ ] XSS防止のテスト +- [ ] CSRF保護のテスト +- [ ] レート制限のテスト +- [ ] パスワードハッシュ強度のテスト +- [ ] セキュリティ対策の文書化 + +**依存関係**: タスク4.1 +**推定工数**: 6時間 +**ステータス**: `TODO` + +#### タスク4.3: ドキュメント作成 +**説明**: APIドキュメントとデプロイガイドの作成 +**受入基準**: +- [ ] OpenAPI/Swagger仕様の作成 +- [ ] セットアップ手順付きREADME +- [ ] セキュリティベストプラクティスの文書化 +- [ ] デプロイメントチェックリストの作成 +- [ ] Postmanコレクションのエクスポート + +**依存関係**: タスク4.1 +**推定工数**: 4時間 +**ステータス**: `TODO` + +## タスクステータスの凡例 +- `TODO` - 未着手 +- `IN_PROGRESS` - 現在作業中 +- `BLOCKED` - 依存関係または問題によりブロック +- `REVIEW` - コードレビュー待ち +- `DONE` - 完了済みおよびテスト済み + +## リスクと軽減策 + +### リスク1: メールサービスの利用不可 +**影響度**: 高 +**発生確率**: 低 +**軽減策**: 指数バックオフ付き再試行キューの実装、フォールバックメールプロバイダーの追加 + +### リスク2: JWT秘密鍵の漏洩 +**影響度**: 重大 +**発生確率**: 低 +**軽減策**: 鍵管理サービスの使用、鍵ローテーションの実装、不正なトークン使用の監視 + +### リスク3: ブルートフォース攻撃 +**影響度**: 高 +**発生確率**: 中 +**軽減策**: レート制限の実装、失敗試行後のCAPTCHA、アカウントロックアウト機構 + +## 備考 +- 将来のイテレーションでOAuthプロバイダーの実装を検討 +- 認証メトリクスの監視（ログイン成功率、パスワードリセット頻度） +- 複数デバイス間のセッション管理の計画 +- 次フェーズでの2要素認証の実装を検討 +``` + +## クイックリファレンス + +### 各ドキュメントの使用タイミング + +**requirements.md** +- システムが何をすべきかを記述 +- ユーザーストーリーと受入基準を定義 +- 測定可能でテスト可能な要件を指定 +- 明確性のためにEARS記法を使用 + +**design.md** +- システムがどのように動作するかを文書化 +- アーキテクチャとコンポーネントを定義 +- APIとデータモデルを指定 +- 技術的決定とトレードオフを含める + +**tasks.md** +- 実装を管理可能な部分に分解 +- タスク間の依存関係を定義 +- 進捗とステータスを追跡 +- リスクと軽減戦略を特定 + +### 避けるべき一般的な落とし穴 + +1. **曖昧な要件**: 常に具体的で測定可能に +2. **依存関係の欠落**: タスクの依存関係を明確に特定 +3. **不完全な受入基準**: すべてのタスクに明確な完了基準が必要 +4. **テスト不可能**: 要件とタスクは検証可能でなければならない +5. **非機能要件の無視**: パフォーマンス、セキュリティ、ユーザビリティを忘れない + +### 成功のためのヒント + +1. 「なぜ」を理解するためにユーザーストーリーから始める +2. 要件にはEARS記法を一貫して使用 +3. 設計文書には明確性のために図を含める +4. 大きなタスクを小さな管理可能な部分に分解 +5. 進捗を追跡するため定期的にタスクステータスを更新 +6. ステークホルダーとドキュメントをレビューし検証 +7. プロジェクトが進化するにつれてドキュメントを同期させる \ No newline at end of file