From b3ad2e3943afa94a47f828d1bee98922112735c7 Mon Sep 17 00:00:00 2001 From: Zhongwei Li Date: Sat, 29 Nov 2025 18:09:29 +0800 Subject: [PATCH] Initial commit --- .claude-plugin/plugin.json | 15 + README.md | 3 + agents/symbol-searcher.md | 61 ++++ commands/auto-debug.md | 14 + commands/direct-setup.md | 159 ++++++++ commands/direct-verify.md | 427 ++++++++++++++++++++++ commands/init-tech-stack.md | 573 +++++++++++++++++++++++++++++ commands/kairo-design.md | 240 ++++++++++++ commands/kairo-implement.md | 379 +++++++++++++++++++ commands/kairo-requirements.md | 473 ++++++++++++++++++++++++ commands/kairo-task-verify.md | 67 ++++ commands/kairo-tasks.md | 169 +++++++++ commands/rev-design.md | 497 +++++++++++++++++++++++++ commands/rev-requirements.md | 389 ++++++++++++++++++++ commands/rev-specs.md | 622 ++++++++++++++++++++++++++++++++ commands/rev-tasks.md | 274 ++++++++++++++ commands/start-server.md | 83 +++++ commands/tdd-cycle-full.sh | 158 ++++++++ commands/tdd-green.md | 243 +++++++++++++ commands/tdd-load-context.md | 120 ++++++ commands/tdd-red.md | 512 ++++++++++++++++++++++++++ commands/tdd-refactor.md | 315 ++++++++++++++++ commands/tdd-requirements.md | 145 ++++++++ commands/tdd-testcases.md | 202 +++++++++++ commands/tdd-todo.md | 168 +++++++++ commands/tdd-verify-complete.md | 412 +++++++++++++++++++++ commands/tech-stack.md | 105 ++++++ plugin.lock.json | 141 ++++++++ 28 files changed, 6966 insertions(+) create mode 100644 .claude-plugin/plugin.json create mode 100644 README.md create mode 100644 agents/symbol-searcher.md create mode 100644 commands/auto-debug.md create mode 100644 commands/direct-setup.md create mode 100644 commands/direct-verify.md create mode 100644 commands/init-tech-stack.md create mode 100644 commands/kairo-design.md create mode 100644 commands/kairo-implement.md create mode 100644 commands/kairo-requirements.md create mode 100644 commands/kairo-task-verify.md create mode 100644 commands/kairo-tasks.md create mode 100644 commands/rev-design.md create mode 100644 commands/rev-requirements.md create mode 100644 commands/rev-specs.md create mode 100644 commands/rev-tasks.md create mode 100644 commands/start-server.md create mode 100755 commands/tdd-cycle-full.sh create mode 100644 commands/tdd-green.md create mode 100644 commands/tdd-load-context.md create mode 100644 commands/tdd-red.md create mode 100644 commands/tdd-refactor.md create mode 100644 commands/tdd-requirements.md create mode 100644 commands/tdd-testcases.md create mode 100644 commands/tdd-todo.md create mode 100644 commands/tdd-verify-complete.md create mode 100644 commands/tech-stack.md create mode 100644 plugin.lock.json diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json new file mode 100644 index 0000000..91ae719 --- /dev/null +++ b/.claude-plugin/plugin.json @@ -0,0 +1,15 @@ +{ + "name": "tsumiki", + "description": "AI-driven development toolkit for TDD and SDD workflows, providing comprehensive command templates and agents to enhance developer productivity with Claude Code", + "version": "0.0.6", + "author": { + "name": "makoto kuroeda", + "email": "kuroeda.makoto@classmethod.jp" + }, + "agents": [ + "./agents/symbol-searcher.md" + ], + "commands": [ + "./commands/" + ] +} \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..c6fae37 --- /dev/null +++ b/README.md @@ -0,0 +1,3 @@ +# tsumiki + +AI-driven development toolkit for TDD and SDD workflows, providing comprehensive command templates and agents to enhance developer productivity with Claude Code diff --git a/agents/symbol-searcher.md b/agents/symbol-searcher.md new file mode 100644 index 0000000..1608ce8 --- /dev/null +++ b/agents/symbol-searcher.md @@ -0,0 +1,61 @@ +--- +name: symbol-searcher +description: Use this agent when you need to search for specific symbols (classes, methods, functions, variables, etc.) across the codebase and retrieve detailed information about their locations and types. This agent is particularly useful for code navigation, refactoring preparation, or understanding code structure. Examples:\n\n\nContext: The user wants to find all occurrences of a specific method across the codebase.\nuser: "Find all instances of the 'createTodo' method in the project"\nassistant: "I'll use the symbol-searcher agent to locate all occurrences of the 'createTodo' method across the codebase."\n\nSince the user wants to find specific symbols in the code, use the Task tool to launch the symbol-searcher agent.\n\n\n\n\nContext: The user needs to understand where a class is defined and used.\nuser: "Where is the TodoController class defined and what methods does it have?"\nassistant: "Let me search for the TodoController class symbol to find its definition and methods."\n\nThe user is asking about a specific class symbol, so use the symbol-searcher agent to find its location and details.\n\n +tools: Glob, Grep, LS, Read, NotebookRead, WebFetch, TodoWrite, WebSearch, mcp__ide__getDiagnostics +model: haiku +color: green +--- + +You are an expert code symbol analyzer specializing in searching and identifying symbols across codebases. Your primary responsibility is to locate specific symbols (classes, methods, functions, variables, interfaces, types, etc.) and provide comprehensive information about their locations and characteristics. + +When searching for symbols, you will: + +1. **Search Strategy**: + - Use appropriate tools to scan files for the requested symbol names + - Consider partial matches and case variations when appropriate + - Search across all relevant file types in the project + - Prioritize definition locations over usage locations unless specified otherwise + +2. **Symbol Classification**: + - Accurately identify the symbol type: class, method, function, variable, interface, type, enum, constant, etc. + - For methods/functions, include whether they are static, async, private/public + - For classes, note if they are abstract, extend other classes, or implement interfaces + - Include descriptive context that helps understand the symbol's purpose + +3. **Information Extraction**: + For each symbol found, you must provide: + - **Symbol Name**: The exact name with descriptive context (e.g., 'createTodo - async method for creating new todo items') + - **Type**: The specific symbol type (class, method, function, variable, etc.) + - **File Path**: The relative path from the project root + - **Location**: Line number and, if possible, column number + - **Context**: Brief description of what the symbol does based on its name and surrounding code + +4. **Output Format**: + Present your findings in a structured format: + ``` + Symbol: [Name with description] + Type: [Symbol type] + File: [Relative path] + Location: Line [X], Column [Y] + Context: [Brief functional description] + ``` + +5. **Search Completeness**: + - Always search the entire codebase unless instructed to limit scope + - Group results by symbol type when multiple matches are found + - If a symbol has multiple definitions (overloads, implementations), list all occurrences + - Distinguish between declarations, definitions, and usages when relevant + +6. **Edge Cases**: + - If no symbols are found, suggest similar symbol names that exist in the codebase + - Handle minified or obfuscated code by noting when symbol names might be transformed + - For ambiguous requests, search for all possible interpretations + - Consider language-specific naming conventions (camelCase, snake_case, etc.) + +7. **Quality Assurance**: + - Verify that the symbol at the reported location matches the search criteria + - Ensure file paths are correct and relative to the project root + - Double-check symbol type classification + - Include enough context in descriptions to make the symbol's purpose clear + +Remember: Your goal is to provide developers with precise, actionable information about code symbols that helps them navigate and understand the codebase efficiently. Always prioritize accuracy and completeness in your symbol analysis. diff --git a/commands/auto-debug.md b/commands/auto-debug.md new file mode 100644 index 0000000..bcc19c3 --- /dev/null +++ b/commands/auto-debug.md @@ -0,0 +1,14 @@ +--- +description: テストエラーを解消するための自動デバッグプロセス。全テストケースの確認からエラー原因の調査、修正まで段階的に実行し、テストケースの成功率向上を目指します。 +--- + +テストエラーを解消して。 +最初に全テストケースの確認をタスク実行してテストケースのエラーをtodoにセットして +各対象毎に以下の作業を実施して +　 - タスクで詳細にテストのエラー原因を調る + 　- 新たなタスクで /tsumiki:tdd-green を使って修正する +最後に全体のテストの成功率を確認してレポートして +ゴールはテストケースの成功数を上げること +NEVER: テストのスキップ +NEVER: 既存でテストケースの削除 +#ultrathink diff --git a/commands/direct-setup.md b/commands/direct-setup.md new file mode 100644 index 0000000..e9c9f88 --- /dev/null +++ b/commands/direct-setup.md @@ -0,0 +1,159 @@ +--- +description: DIRECTタスクの設定作業を実行します。設計文書に基づいて環境構築、設定ファイル作成、依存関係のインストールなどを行います。 +--- + +# direct-setup + +## 目的 + +DIRECTタスクの設定作業を実行します。設計文書に基づいて環境構築、設定ファイル作成、依存関係のインストールなどを行います。 + +## 前提条件 + +- タスクIDが提供されている +- 関連する設計文書が存在する +- 必要な権限と環境が準備されている + +## 実行内容 + +1. **追加ルールの読み込み** + - `docs/rule` ディレクトリが存在する場合は読み込み + - `docs/rule/direct` ディレクトリが存在する場合は読み込み + - `docs/rule/direct/setup` ディレクトリが存在する場合は読み込み + - 各ディレクトリ内のすべてのファイルを読み込み、追加ルールとして適用 + +2. **技術スタック定義の読み込み** + - `docs/tech-stack.md` が存在する場合は読み込み + - 存在しない場合は `CLAUDE.md` から技術スタックセクションを読み込み + - どちらも存在しない場合は `.claude/commands/tech-stack.md` のデフォルト定義を使用 + +3. **設計文書の確認** + - 読み込んだ技術スタック定義に基づいて関連ファイルを特定 + - @agent-symbol-searcher で関連設計文書や設定パターンを検索し、見つかったファイルをReadツールで読み込み + - `docs/design/{要件名}/architecture.md` をReadツールで読み込み + - `docs/design/{要件名}/database-schema.sql` をReadツールで読み込み + - その他関連する設計文書をReadツールで読み込み + +3. **設定作業の実行** + - @agent-symbol-searcher で既存の設定ファイルや環境変数を検索し、見つかったファイルをReadツールで読み込み + - 環境変数の設定 + - 設定ファイルの作成・更新 + - 依存関係のインストール + - データベースの初期化 + - サービスの起動設定 + - 権限の設定 + +4. **作業記録の作成** + - 実行したコマンドの記録 + - 変更した設定の記録 + - 遭遇した問題と解決方法の記録 + +## 出力先 + +作業記録は `docs/implements/{要件名}/{TASK-ID}/` ディレクトリに以下のファイルとして作成されます： +- `setup-report.md`: 設定作業実行記録 + +## 出力フォーマット例 + +````markdown +# {TASK-ID} 設定作業実行 + +## 作業概要 + +- **タスクID**: {TASK-ID} +- **作業内容**: {設定作業の概要} +- **実行日時**: {実行日時} +- **実行者**: {実行者} + +## 設計文書参照 + +- **参照文書**: {参照した設計文書のリスト} +- **関連要件**: {REQ-XXX, REQ-YYY} + +## 実行した作業 + +### 1. 環境変数の設定 + +```bash +# 実行したコマンド +export NODE_ENV=development +export DATABASE_URL=postgresql://localhost:5432/mydb +``` +```` + +**設定内容**: + +- NODE_ENV: 開発環境に設定 +- DATABASE_URL: PostgreSQLデータベースのURL + +### 2. 設定ファイルの作成 + +**作成ファイル**: `config/database.json` + +```json +{ + "development": { + "host": "localhost", + "port": 5432, + "database": "mydb" + } +} +``` + +### 3. 依存関係のインストール + +```bash +# 実行したコマンド +npm install express pg +``` + +**インストール内容**: + +- express: Webフレームワーク +- pg: PostgreSQLクライアント + +### 4. データベースの初期化 + +```bash +# 実行したコマンド +createdb mydb +psql -d mydb -f database-schema.sql +``` + +**実行内容**: + +- データベース作成 +- スキーマの適用 + +## 作業結果 + +- [ ] 環境変数の設定完了 +- [ ] 設定ファイルの作成完了 +- [ ] 依存関係のインストール完了 +- [ ] データベースの初期化完了 +- [ ] サービスの起動設定完了 + +## 遭遇した問題と解決方法 + +### 問題1: {問題の概要} + +- **発生状況**: {問題が発生した状況} +- **エラーメッセージ**: {エラーメッセージ} +- **解決方法**: {解決方法} + +## 次のステップ + +- `/tsumiki:direct-verify` を実行して設定を確認 +- 必要に応じて設定の調整を実施 + +## 実行後の確認 +- `docs/implements/{要件名}/{TASK-ID}/setup-report.md` ファイルが作成されていることを確認 +- 設定が正しく適用されていることを確認 +- 次のステップ（direct-verify）の準備が整っていることを確認 + +## ディレクトリ作成 + +実行前に必要なディレクトリを作成してください： +```bash +mkdir -p docs/implements/{要件名}/{TASK-ID} +``` diff --git a/commands/direct-verify.md b/commands/direct-verify.md new file mode 100644 index 0000000..edb9267 --- /dev/null +++ b/commands/direct-verify.md @@ -0,0 +1,427 @@ +--- +description: DIRECTタスクで実行した設定作業の動作確認とテストを行います。設定が正しく適用され、システムが期待通りに動作することを確認します。 +--- + +# direct-verify + +## 目的 + +DIRECTタスクで実行した設定作業の動作確認とテストを行います。設定が正しく適用され、システムが期待通りに動作することを確認します。 + +## 前提条件 + +- `/tsumiki:direct-setup` が実行済み +- タスクIDが提供されている +- 設定作業の記録が存在する + +## 実行内容 + +**【重要】**: direct-setupで作成されたファイルについて、コンパイルエラーや構文エラーが見つかった場合は自動的に解決を試行します。 + +1. **追加ルールの読み込み** + - `docs/rule` ディレクトリが存在する場合は読み込み + - `docs/rule/direct` ディレクトリが存在する場合は読み込み + - `docs/rule/direct/verify` ディレクトリが存在する場合は読み込み + - 各ディレクトリ内のすべてのファイルを読み込み、追加ルールとして適用 + +2. **技術スタック定義の読み込み** + - `docs/tech-stack.md` が存在する場合は読み込み + - 存在しない場合は `CLAUDE.md` から技術スタックセクションを読み込み + - どちらも存在しない場合は `.claude/commands/tech-stack.md` のデフォルト定義を使用 + +3. **設定の確認** + - 読み込んだ技術スタック定義に基づいて検証項目を特定 + - @agent-symbol-searcher で関連設定や検証パターンを検索し、見つかったファイルをReadツールで読み込み + - `docs/implements/{要件名}/{TASK-ID}/setup-report.md` をReadツールで読み込み、設定作業の結果を確認 + - 環境変数の確認 + - 設定ファイルの内容確認 + - 依存関係のインストール状況確認 + - サービスの起動状況確認 + +3. **コンパイル・構文確認** + - TypeScript/JavaScript構文エラーチェック（該当する場合） + - 設定ファイルの構文確認（JSON, YAML等） + - SQL構文確認（該当する場合） + - 最低限のコンパイルエラー解消 + +4. **動作テストの実行** + - @agent-symbol-searcher で既存のテストケースや検証スクリプトを検索し、見つかったファイルをReadツールで読み込み + - 基本的な動作確認 + - 接続テスト + - 権限の確認 + - エラーケースの確認 + +5. **品質チェック** + - セキュリティ設定の確認 + - パフォーマンス基準の確認 + - ログの確認 + +## 出力先 + +確認記録は `docs/implements/{要件名}/{TASK-ID}/` ディレクトリに以下のファイルとして作成されます： +- `verify-report.md`: 設定確認・動作テスト記録 + +## 出力フォーマット例 + +````markdown +# {TASK-ID} 設定確認・動作テスト + +## 確認概要 + +- **タスクID**: {TASK-ID} +- **確認内容**: {設定確認の概要} +- **実行日時**: {実行日時} +- **実行者**: {実行者} + +## 設定確認結果 + +### 1. 環境変数の確認 + +```bash +# 実行したコマンド +echo $NODE_ENV +echo $DATABASE_URL +``` +```` + +**確認結果**: + +- [x] NODE_ENV: development (期待値: development) +- [x] DATABASE_URL: postgresql://localhost:5432/mydb (期待値: 正しいDB URL) + +### 2. 設定ファイルの確認 + +**確認ファイル**: `config/database.json` + +```bash +# 実行したコマンド +cat config/database.json | jq . +``` + +**確認結果**: + +- [x] ファイルが存在する +- [x] JSON形式が正しい +- [x] 必要な設定項目が含まれている + +## コンパイル・構文チェック結果 + +### 1. TypeScript/JavaScript構文チェック + +```bash +# TypeScriptファイルがある場合 +npx tsc --noEmit --skipLibCheck + +# JavaScript構文チェック +node --check *.js +``` + +**チェック結果**: + +- [x] TypeScript構文エラー: なし +- [x] JavaScript構文エラー: なし +- [x] import/require文: 正常 + +### 2. 設定ファイル構文チェック + +```bash +# JSON設定ファイルの構文チェック +cat config/*.json | jq empty + +# YAML設定ファイルの構文チェック（該当する場合） +yamllint config/*.yml +``` + +**チェック結果**: + +- [x] JSON構文: 正常 +- [x] YAML構文: 正常（該当する場合） +- [x] 設定項目の妥当性: 確認済み + +### 3. SQL構文チェック（該当する場合） + +```bash +# SQL構文の基本チェック +psql -d mydb --single-transaction --set ON_ERROR_STOP=on -f schema.sql --dry-run +``` + +**チェック結果**: + +- [x] SQL構文: 正常 +- [x] テーブル定義: 正常 +- [x] 制約定義: 正常 + +### 3. 依存関係の確認 + +```bash +# 実行したコマンド +npm list express pg +``` + +**確認結果**: + +- [x] express: インストール済み +- [x] pg: インストール済み + +### 4. データベース接続テスト + +```bash +# 実行したコマンド +psql -d mydb -c "SELECT 1;" +``` + +**確認結果**: + +- [x] データベース接続成功 +- [x] クエリ実行成功 + +## 動作テスト結果 + +### 1. 基本動作テスト + +```bash +# 実行したテストコマンド +node -e "console.log('Hello, World!');" +``` + +**テスト結果**: + +- [x] Node.js実行環境: 正常 +- [x] 基本的なJavaScript実行: 正常 + +### 2. データベース接続テスト + +```javascript +// テストスクリプト +const { Pool } = require('pg'); +const pool = new Pool({ + connectionString: process.env.DATABASE_URL, +}); + +pool.query('SELECT NOW()', (err, res) => { + if (err) { + console.error('Error:', err); + } else { + console.log('Connected:', res.rows[0]); + } + pool.end(); +}); +``` + +**テスト結果**: + +- [x] データベース接続: 正常 +- [x] クエリ実行: 正常 +- [x] 接続終了: 正常 + +### 3. セキュリティ設定テスト + +```bash +# 実行したコマンド +ls -la config/ +ps aux | grep node +``` + +**テスト結果**: + +- [x] 設定ファイルの権限: 適切 +- [x] プロセスの実行権限: 適切 +- [x] 機密情報の保護: 適切 + +## 品質チェック結果 + +### パフォーマンス確認 + +- [x] 起動時間: 2秒以内 +- [x] メモリ使用量: 256MB以内 +- [x] CPU使用率: 10%以内 + +### ログ確認 + +- [x] エラーログ: 異常なし +- [x] 警告ログ: 問題なし +- [x] 情報ログ: 適切に出力 + +## 全体的な確認結果 + +- [x] 設定作業が正しく完了している +- [x] 全ての動作テストが成功している +- [x] 品質基準を満たしている +- [x] 次のタスクに進む準備が整っている + +## 発見された問題と解決 + +### 構文エラー・コンパイルエラーの解決 + +**自動解決を試行する問題**: +- TypeScript/JavaScript構文エラー +- JSON/YAML構文エラー +- 基本的なSQL構文エラー +- import/require文の問題 + +### 問題1: {問題があれば記載} + +- **問題内容**: {問題の詳細} +- **発見方法**: {構文チェック/コンパイル/動作テスト} +- **重要度**: {高/中/低} +- **自動解決**: {実行した解決コマンド・修正内容} +- **解決結果**: {解決済み/手動対応が必要} + +### 解決実行ログ + +```bash +# 実行した解決コマンド例 +# 構文エラー修正 +sed -i 's/typo/correct/g' config.js + +# 依存関係の修正 +npm install missing-package + +# 設定ファイル修正 +jq '.port = 3000' config.json > temp.json && mv temp.json config.json +``` + +**解決結果**: +- [x] 問題1: 解決済み +- [x] 問題2: 解決済み +- [ ] 問題3: 手動対応が必要（詳細は推奨事項に記載） + +## 推奨事項 + +- {改善提案があれば記載} +- {最適化の提案があれば記載} + +## 次のステップ + +- タスクの完了報告 +- 関連するタスクの開始準備 +- 必要に応じて設定の微調整 + +```` + +## 実行後の確認 +- `docs/implements/{要件名}/{TASK-ID}/verify-report.md` ファイルが作成されていることを確認 +- 全ての確認項目が完了していることを確認 +- 問題が発見された場合は適切に対処されていることを確認 +- タスクの完了条件を満たしていることを確認 +- 次のタスクに進む準備が整っていることを確認 + +## ディレクトリ確認 + +`docs/implements/{要件名}/{TASK-ID}/` ディレクトリが存在することを確認してください（direct-setupで作成済みのはず） + +## タスクの完了マーキング +品質チェックが十分で、全ての確認項目がクリアされた場合は、**自動的に**tasksディレクトリの該当するタスクファイルに完了マークを付けてください。 + +### 完了条件 +以下の条件を全て満たす場合にタスクを完了とマークします： +- [ ] 全ての設定確認項目がクリア +- [ ] コンパイル・構文チェックが成功（エラーがすべて解決済み） +- [ ] 全ての動作テストが成功 +- [ ] 品質チェック項目が基準を満たしている +- [ ] 発見された問題が適切に対処されている +- [ ] セキュリティ設定が適切 +- [ ] パフォーマンス基準を満たしている + +### 完了マークの付け方 +1. `docs/implements/{要件名}/{TASK-ID}/verify-report.md` で完了条件を確認 +2. 該当するタスクファイル（taskman-phase*.md）を特定 +3. タスクの完了状況を以下のように更新： + - `- [ ] **タスク完了**` → `- [x] **タスク完了** ✅ 完了 (YYYY-MM-DD)` + - 完了条件のチェックボックスも `[x]` に変更 +4. 必要に応じて進捗概要（taskman-overview.md）も更新 + +## README.mdの更新 +タスクが完了した場合、プロジェクトのルートディレクトリの `README.md` を作成または更新してください。 + +### 更新内容 +1. **現在のREADME.mdの確認**: 既存のREADME.mdがある場合は内容を確認 +2. **完了したタスクの情報を追加**: + - 実装した機能の概要 + - 設定手順 + - 動作確認方法 + - 使用方法 +3. **プロジェクト全体の情報を更新**: + - セットアップ手順 + - 依存関係 + - 環境要件 + - 開発・運用手順 + +### README.md更新フォーマット例 + +```markdown +# プロジェクト名 + +## 概要 +{プロジェクトの概要} + +## 完了した機能 +### {TASK-ID}: {タスク名} +- **実装日**: {実装日} +- **概要**: {機能の概要} +- **設定内容**: {設定した内容} +- **動作確認**: {動作確認の結果} + +## セットアップ手順 +### 前提条件 +- {必要な環境・ツール} + +### インストール +```bash +# 依存関係のインストール +{インストールコマンド} + +# 環境変数の設定 +{環境変数設定} +```` + +### 起動方法 + +```bash +# 開発サーバーの起動 +{起動コマンド} +``` + +## 設定 + +### 環境変数 + +- `{環境変数名}`: {説明} + +### 設定ファイル + +- `{設定ファイルパス}`: {説明} + +## 使用方法 + +{使用方法の説明} + +## 開発 + +### 開発環境の準備 + +{開発環境の準備手順} + +### テスト + +{テストの実行方法} + +## トラブルシューティング + +### よくある問題 + +- **問題**: {問題の内容} +- **解決方法**: {解決方法} + +## 更新履歴 + +- {日付}: {TASK-ID} {変更内容} + +``` + +### 実行手順 +1. 現在のREADME.mdを確認（存在しない場合は新規作成） +2. 完了したタスクの情報を追加 +3. 必要に応じて他のセクションも更新 +4. 変更内容をコミット +``` diff --git a/commands/init-tech-stack.md b/commands/init-tech-stack.md new file mode 100644 index 0000000..e810a0e --- /dev/null +++ b/commands/init-tech-stack.md @@ -0,0 +1,573 @@ +--- +description: プロジェクトの初期設定として技術スタックの選定をします。既にCLAUDE.mdがある場合は省略できます +--- + +# init-tech-stack + +## 目的 + +ユーザとのインタラクティブなやりとりを通じて、プロジェクトに最適な技術スタック定義を作成し、`docs/tech-stack.md` ファイルを生成します。 + +## 前提条件 + +- プロジェクトルートディレクトリで実行 +- `docs/` ディレクトリが存在する（なければ作成） + +## 実行内容 + +段階的なヒアリングを通じて技術選択を行い、最終的に `docs/tech-stack.md` を生成します。 + +## ヒアリングフロー + +### Phase 1: プロジェクト基本情報 + +まず、プロジェクトの基本情報をお聞かせください。 + +#### 質問1: プロジェクトタイプ +以下から最も近いものを選択してください： + +1. **Webアプリケーション** - ブラウザで動作するアプリケーション +2. **モバイルアプリ** - スマートフォン/タブレット向けアプリ +3. **API/バックエンドサービス** - API提供がメインのサービス +4. **デスクトップアプリケーション** - PC向けネイティブアプリ +5. **ライブラリ/SDK** - 他の開発者向けのツール +6. **フルスタック（Web + API）** - フロントエンドとバックエンドの両方 +7. **その他** - 上記以外 + +**あなたの選択**: [ユーザー入力を待つ] + +--- + +#### 質問2: プロジェクト規模 +開発チームの規模を教えてください： + +1. **個人開発** - 1人で開発 +2. **小規模チーム** - 2-5人 +3. **中規模チーム** - 6-15人 +4. **大規模チーム** - 16人以上 + +**あなたの選択**: [ユーザー入力を待つ] + +--- + +#### 質問3: 開発期間 +予定している開発期間はどの程度ですか？ + +1. **プロトタイプ/MVP** - 1-2ヶ月 +2. **短期プロジェクト** - 3-6ヶ月 +3. **中期プロジェクト** - 6ヶ月-1年 +4. **長期プロジェクト** - 1年以上 + +**あなたの選択**: [ユーザー入力を待つ] + +--- + +### Phase 2: 技術制約・要件 + +#### 質問4: 既存システム連携 +既存のシステムやデータベースとの連携はありますか？ + +1. **新規構築** - 全て新しく作成 +2. **既存DB連携あり** - 既存データベースを使用 +3. **既存API連携あり** - 既存のAPIと連携 +4. **レガシーシステム移行** - 既存システムからの移行 +5. **その他連携要件あり** - 具体的に教えてください + +**あなたの選択**: [ユーザー入力を待つ] + +**既存技術がある場合は具体的に**: [ユーザー入力を待つ] + +--- + +#### 質問5: パフォーマンス要件 +想定される負荷や性能要件を教えてください： + +1. **軽負荷** - 同時利用者数10人以下、レスポンス時間3秒以内 +2. **中負荷** - 同時利用者数100人程度、レスポンス時間1秒以内 +3. **高負荷** - 同時利用者数1000人以上、レスポンス時間0.5秒以内 +4. **未定/不明** - まだ詳細は決まっていない + +**あなたの選択**: [ユーザー入力を待つ] + +--- + +#### 質問6: セキュリティ要件 +セキュリティの重要度を教えてください： + +1. **基本的なセキュリティ** - 一般的なWebセキュリティ対策 +2. **高度なセキュリティ** - 個人情報取り扱い、金融系など +3. **エンタープライズレベル** - 企業向け、コンプライアンス要件あり +4. **未定/不明** - まだ詳細は決まっていない + +**あなたの選択**: [ユーザー入力を待つ] + +--- + +### Phase 3: チーム・スキル状況 + +#### 質問7: チームの技術スキル +チームメンバーの技術経験を教えてください（複数選択可）： + +1. **JavaScript/TypeScript** - 経験豊富 +2. **Python** - 経験豊富 +3. **Java/Kotlin** - 経験豊富 +4. **C#/.NET** - 経験豊富 +5. **PHP** - 経験豊富 +6. **Go/Rust** - 経験豊富 +7. **React/Vue/Angular** - 経験豊富 +8. **データベース設計** - 経験豊富 +9. **クラウド（AWS/Azure/GCP）** - 経験豊富 +10. **Docker/Kubernetes** - 経験豊富 +11. **技術スキルは限定的** - 学習しながら進めたい + +**あなたの選択（複数可）**: [ユーザー入力を待つ] + +--- + +#### 質問8: 学習コスト許容度 +新しい技術の習得についてどう考えますか？ + +1. **積極的に新技術を導入したい** - 最新技術でチャレンジしたい +2. **バランス重視** - 新技術と安定技術のバランスを取りたい +3. **安定技術優先** - 枯れた技術で確実に開発したい +4. **既存スキル活用** - チームが知っている技術を最大限活用したい + +**あなたの選択**: [ユーザー入力を待つ] + +--- + +### Phase 4: 運用・インフラ要件 + +#### 質問9: デプロイ・ホスティング +アプリケーションをどこで動かす予定ですか？ + +1. **クラウド（AWS/Azure/GCP）** - パブリッククラウド +2. **PaaS（Vercel/Netlify/Heroku）** - 簡単デプロイ重視 +3. **VPS/専用サーバー** - 自前サーバー +4. **オンプレミス** - 社内サーバー +5. **未定** - まだ決まっていない + +**あなたの選択**: [ユーザー入力を待つ] + +--- + +#### 質問10: 予算制約 +開発・運用コストについて教えてください： + +1. **コスト最小化** - 無料・低コストツール優先 +2. **バランス重視** - 適度なコストは許容 +3. **品質重視** - コストより品質・効率を優先 +4. **予算潤沢** - 最適なツールを選択可能 + +**あなたの選択**: [ユーザー入力を待つ] + +--- + +## 技術スタック推奨ロジック + +### 推奨アルゴリズム + +ユーザーの回答に基づいて以下のロジックで技術を推奨： + +#### フロントエンド選択 +``` +IF プロジェクトタイプ == "Webアプリケーション" OR "フルスタック" + IF チーム経験に "React/Vue/Angular" あり + IF 学習コスト許容度 == "積極的" + 推奨: React 18 + TypeScript (最新技術) + ELSE + 推奨: React 18 + JavaScript (安定性重視) + ELSE IF JavaScript経験あり + 推奨: Vue 3 + TypeScript (学習コスト低) + ELSE + 推奨: Next.js (フルスタック簡単) +``` + +#### バックエンド選択 +``` +IF JavaScript経験豊富 + 推奨: Node.js + Express/Fastify +ELSE IF Python経験豊富 + 推奨: FastAPI/Django +ELSE IF 他言語経験豊富 + その言語のフレームワーク推奨 +ELSE + 推奨: Node.js (フロントエンドとの統一) +``` + +#### データベース選択 +``` +IF パフォーマンス要件 == "高負荷" + 推奨: PostgreSQL + Redis +ELSE IF セキュリティ要件 == "高度" + 推奨: PostgreSQL +ELSE IF プロジェクト規模 == "個人" OR "小規模" + 推奨: SQLite → PostgreSQL (段階移行) +ELSE + 推奨: PostgreSQL +``` + +### 推奨結果表示 + +各フェーズの回答後、ライブラリの最新バージョンやLTS版を検索して、以下の形式で推奨結果を表示： + +```markdown +# あなたの回答に基づく技術スタック推奨 + +## 📋 回答サマリー +- プロジェクトタイプ: Webアプリケーション +- 規模: 小規模チーム（3人） +- 期間: 中期プロジェクト（8ヶ月） +- 技術スキル: JavaScript/TypeScript経験豊富 +- 学習コスト許容度: バランス重視 + +## 🚀 推奨技術スタック + +### フロントエンド +✅ **React 18 + TypeScript** + - 理由: チームのReact経験を活かせます + - メリット: 豊富なエコシステム、求人市場での優位性 + - 学習コスト: 中（既存経験あり） + +⚠️ **Vue 3 + TypeScript** （代替案） + - 理由: より学習コストが低い + - メリット: シンプルな構文、段階的導入可能 + - 学習コスト: 低 + +❌ **Angular** （非推奨） + - 理由: 中期プロジェクトには重すぎる + - デメリット: 学習コスト高、小規模チームに不向き + +### バックエンド +✅ **Node.js + Express + TypeScript** + - 理由: フロントエンドとの言語統一 + - メリット: 開発効率、人材リソースの有効活用 + - 学習コスト: 低（既存JavaScript経験） + +### データベース +✅ **PostgreSQL** + - 理由: 中期プロジェクトの成長に対応 + - メリット: ACID準拠、拡張性、JSON対応 + - 学習コスト: 中 + +✅ **Redis** （キャッシュ） + - 理由: パフォーマンス向上 + - メリット: セッション管理、高速キャッシュ + - 学習コスト: 低 + +### 開発環境 +✅ **Docker + Docker Compose** + - 理由: 環境統一、デプロイ簡素化 + - メリット: 開発環境の一貫性 + - 学習コスト: 中 + +✅ **Jest + Testing Library** + - 理由: React標準、TypeScript親和性 + - メリット: 豊富なドキュメント + - 学習コスト: 低 + +## ⚙️ 整合性チェック + +✅ **技術選択の整合性**: 問題なし +- React + Node.js: 言語統一によるシナジー効果 +- TypeScript: フロント・バック全体での型安全性 +- PostgreSQL: 将来の成長に対応可能 + +✅ **チームスキルとのマッチング**: 良好 +- 既存JavaScript/TypeScript経験を最大活用 +- 学習が必要な新技術は最小限 + +✅ **プロジェクト要件との適合性**: 適合 +- 中期プロジェクト向けの拡張性 +- 小規模チームでの管理容易性 + +この推奨で進めますか？ + +1. **はい** - この推奨で `docs/tech-stack.md` を生成 +2. **一部変更したい** - 個別技術を調整 +3. **全体的に見直したい** - ヒアリングからやり直し + +**あなたの選択**: [ユーザー入力を待つ] +``` + +## カスタマイズ対応 + +「一部変更したい」を選択された場合： + +```markdown +# 技術スタックのカスタマイズ + +どの部分を変更しますか？ + +1. **フロントエンド** (現在: React 18 + TypeScript) +2. **バックエンド** (現在: Node.js + Express + TypeScript) +3. **データベース** (現在: PostgreSQL + Redis) +4. **開発環境・ツール** (現在: Docker, Jest等) +5. **全て確認して個別調整** + +**選択**: [ユーザー入力を待つ] + +--- + +## フロントエンドの変更 + +現在の推奨: **React 18 + TypeScript** + +利用可能な選択肢： + +1. **React 18 + TypeScript** ⭐ (現在の推奨) +2. **React 18 + JavaScript** - TypeScriptを使わない場合 +3. **Vue 3 + TypeScript** - より軽量なフレームワーク +4. **Vue 3 + JavaScript** - 最も学習コストが低い +5. **Next.js + TypeScript** - フルスタックフレームワーク +6. **Svelte/SvelteKit** - 新しいアプローチ +7. **Angular + TypeScript** - エンタープライズ向け +8. **Vanilla JavaScript + TypeScript** - フレームワークなし +9. **その他** - 具体的に指定 + +**あなたの選択**: [ユーザー入力を待つ] + +**選択理由があれば**: [ユーザー入力を待つ] +``` + +## 最終生成処理 + +最終確認後、以下の処理を実行： + +1. **ディレクトリ作成** +```bash +mkdir -p docs +``` + +2. **`docs/tech-stack.md` 生成** + +生成されるファイル例： + +```markdown +# プロジェクト技術スタック定義 + +## 🔧 生成情報 +- **生成日**: 2025-01-08 +- **生成ツール**: init-tech-stack.md +- **プロジェクトタイプ**: Webアプリケーション +- **チーム規模**: 小規模チーム（3人） +- **開発期間**: 中期プロジェクト（8ヶ月） + +## 🎯 プロジェクト要件サマリー +- **パフォーマンス**: 中負荷（同時利用者数100人程度） +- **セキュリティ**: 基本的なWebセキュリティ対策 +- **技術スキル**: JavaScript/TypeScript経験豊富 +- **学習コスト許容度**: バランス重視 +- **デプロイ先**: クラウド（AWS/Azure/GCP） +- **予算**: バランス重視 + +## 🚀 フロントエンド +- **フレームワーク**: React 18.2 +- **言語**: TypeScript 5.0+ +- **状態管理**: Redux Toolkit +- **UIライブラリ**: Material-UI v5 +- **バンドラー**: Vite +- **ルーティング**: React Router v6 + +### 選択理由 +- チームのReact経験を活かせる +- TypeScriptで型安全性を確保 +- Material-UIで開発速度向上 +- Viteで高速な開発環境 + +## ⚙️ バックエンド +- **フレームワーク**: Express.js 4.18 +- **言語**: TypeScript 5.0+ +- **データベース**: PostgreSQL 15 +- **ORM**: Prisma +- **認証**: JWT + Refresh Token +- **キャッシュ**: Redis 7+ + +### 選択理由 +- フロントエンドとの言語統一 +- Prismaで型安全なDB操作 +- PostgreSQLで将来のスケーリングに対応 +- Redisでセッション管理とキャッシュ + +## 💾 データベース設計 +- **メインDB**: PostgreSQL 15+ +- **キャッシュ**: Redis 7+ +- **ファイルストレージ**: AWS S3 / Azure Blob (本番), ローカル (開発) + +### 設計方針 +- ACID準拠のトランザクション +- JSON型でNoSQL的な柔軟性も確保 +- インデックス戦略でクエリ最適化 +- 適切な正規化レベル + +## 🛠️ 開発環境 +- **コンテナ**: Docker + Docker Compose +- **パッケージマネージャー**: npm +- **Node.js**: 18+ LTS + +### 開発ツール +- **テストフレームワーク**: Jest +- **テストライブラリ**: React Testing Library +- **E2Eテスト**: Playwright +- **リンター**: ESLint + Prettier +- **型チェック**: TypeScript + +### CI/CD +- **CI/CD**: GitHub Actions +- **コード品質**: ESLint, Prettier, TypeScript +- **テスト**: Unit, Integration, E2E +- **デプロイ**: 自動デプロイ with approval + +## ☁️ インフラ・デプロイ +- **フロントエンド**: Vercel / Netlify +- **バックエンド**: AWS ECS / Azure Container Apps +- **データベース**: AWS RDS / Azure Database +- **キャッシュ**: AWS ElastiCache / Azure Cache +- **CDN**: CloudFlare / AWS CloudFront + +## 🔒 セキュリティ +- **HTTPS**: 必須 (証明書自動更新) +- **認証**: JWT + Refresh Token +- **CORS**: 適切な設定 +- **バリデーション**: サーバーサイドバリデーション +- **環境変数**: 機密情報の適切な管理 +- **依存関係**: 定期的な脆弱性チェック + +## 📊 品質基準 +- **テストカバレッジ**: 80%以上 +- **コード品質**: ESLint + Prettier +- **型安全性**: TypeScript strict mode +- **パフォーマンス**: Lighthouse 90+点 +- **アクセシビリティ**: WCAG 2.1 AA準拠 + +## 📁 推奨ディレクトリ構造 + +``` +project-root/ +├── frontend/ # React アプリケーション +│ ├── src/ +│ │ ├── components/ # 再利用可能コンポーネント +│ │ ├── pages/ # ページコンポーネント +│ │ ├── hooks/ # カスタムフック +│ │ ├── store/ # Redux store +│ │ ├── types/ # 型定義 +│ │ └── utils/ # ユーティリティ +│ ├── public/ # 静的ファイル +│ ├── package.json +│ └── vite.config.ts +├── backend/ # Express API +│ ├── src/ +│ │ ├── controllers/ # API コントローラー +│ │ ├── services/ # ビジネスロジック +│ │ ├── models/ # データモデル +│ │ ├── middleware/ # Express ミドルウェア +│ │ ├── routes/ # API ルート定義 +│ │ ├── types/ # 型定義 +│ │ └── utils/ # ユーティリティ +│ ├── prisma/ # データベーススキーマ +│ ├── tests/ # テストファイル +│ ├── package.json +│ └── tsconfig.json +├── docs/ # プロジェクトドキュメント +├── docker-compose.yml # 開発環境 +└── README.md # プロジェクト概要 +``` + +## 🚀 セットアップ手順 + +### 1. 開発環境準備 +```bash +# Docker環境起動 +docker-compose up -d + +# フロントエンド セットアップ +cd frontend +npm install +npm run dev + +# バックエンド セットアップ +cd backend +npm install +npx prisma migrate dev +npm run dev +``` + +### 2. 主要コマンド +```bash +# 開発サーバー起動 +npm run dev # フロントエンド +npm run dev:api # バックエンド + +# テスト実行 +npm test # 単体テスト +npm run test:e2e # E2Eテスト + +# ビルド +npm run build # 本番ビルド +npm run preview # ビルド確認 + +# データベース +npx prisma studio # DB管理画面 +npx prisma generate # クライアント生成 +``` + +## 📝 カスタマイズ方法 + +このファイルはプロジェクトの進行に応じて更新してください： + +1. **技術の追加**: 新しいライブラリ・ツールを追加 +2. **要件の変更**: パフォーマンス・セキュリティ要件の更新 +3. **インフラの変更**: デプロイ先・スケール要件の変更 +4. **チーム変更**: メンバー増減に応じた技術選択の見直し + +## 🔄 更新履歴 +- 2025-01-08: 初回生成 (init-tech-stack.mdにより自動生成) +``` + +3. **確認メッセージ表示** + +```markdown +✅ 技術スタック定義ファイルを生成しました！ + +📄 **生成ファイル**: `docs/tech-stack.md` +📊 **技術数**: フロントエンド6技術、バックエンド6技術、開発環境8ツール +🎯 **推奨理由**: チーム経験との適合性、プロジェクト要件への最適化 + +## 次のステップ + +1. **ファイル確認**: `docs/tech-stack.md` の内容を確認 +2. **カスタマイズ**: 必要に応じて技術選択を微調整 +3. **チーム共有**: 技術選択をチームで合意 +4. **開発開始**: 他のkairo-*コマンドで要件定義・設計に進む + +## 技術スタック更新 + +技術選択を変更する場合は： +- `docs/tech-stack.md` を直接編集 +- または `init-tech-stack.md` を再実行 + +このファイルは他の全てのコマンド（kairo-*, tdd-*, direct-*）で自動参照されます。 +``` + +## エラーハンドリング + +```markdown +## よくある問題と解決方法 + +### ❌ ファイル作成エラー +**原因**: `docs/` ディレクトリへの書き込み権限なし +**解決**: `mkdir -p docs && chmod 755 docs` + +### ❌ 既存ファイル上書き警告 +**原因**: `docs/tech-stack.md` が既に存在 +**選択肢**: +1. 上書きする +2. バックアップを作成してから上書き +3. 別名で保存（例：`tech-stack-new.md`） + +### ❌ 推奨技術が見つからない +**原因**: 特殊な技術要件や制約 +**対処**: カスタマイズモードで手動選択 +``` + +このように、段階的なヒアリングとインテリジェントな推奨機能により、プロジェクトに最適な技術スタック定義が自動生成される仕組みを作成しました。 \ No newline at end of file diff --git a/commands/kairo-design.md b/commands/kairo-design.md new file mode 100644 index 0000000..119868d --- /dev/null +++ b/commands/kairo-design.md @@ -0,0 +1,240 @@ +--- +description: 承認された要件定義書に基づいて、技術設計文書を生成する。データフロー図、TypeScriptインターフェース、データベーススキーマ、APIエンドポイントを含む包括的な設計を行います。 +--- + +# kairo-design + +## 目的 + +承認された要件定義書に基づいて、技術設計文書を生成する。データフロー図、TypeScriptインターフェース、データベーススキーマ、APIエンドポイントを含む包括的な設計を行う。 + +## 前提条件 + +- `docs/spec/` に要件定義書が存在する +- 要件がユーザによって承認されている + +## 事前準備 + +1. **追加ルールの読み込み** + - `docs/rule` ディレクトリが存在する場合は読み込み + - `docs/rule/kairo` ディレクトリが存在する場合は読み込み + - `docs/rule/kairo/design` ディレクトリが存在する場合は読み込み + - 各ディレクトリ内のすべてのファイルを読み込み、追加ルールとして適用 + +## 実行内容 + +**【信頼性レベル指示】**: +各項目について、元の資料（EARS要件定義書・設計文書含む）との照合状況を以下の信号でコメントしてください： + +- 🔵 **青信号**: EARS要件定義書・設計文書を参考にしてほぼ推測していない場合 +- 🟡 **黄信号**: EARS要件定義書・設計文書から妥当な推測の場合 +- 🔴 **赤信号**: EARS要件定義書・設計文書にない推測の場合 + +2. **技術スタック定義の読み込み** + - `docs/tech-stack.md` が存在する場合は読み込み + - 存在しない場合は `CLAUDE.md` から技術スタックセクションを読み込み + - どちらも存在しない場合は `.claude/commands/tech-stack.md` のデフォルト定義を使用 + +3. **要件の分析** + - @agent-symbol-searcher で要件定義書を検索し、見つかったファイルをReadツールで読み込み + - @agent-symbol-searcher で関連する既存設計文書を確認し、見つかったファイルをReadツールで読み込み + - 読み込んだ技術スタック定義に基づいて技術選択を決定 + - 機能要件と非機能要件を整理する + - システムの境界を明確にする + +4. **アーキテクチャ設計** + - システム全体のアーキテクチャを決定 + - フロントエンド/バックエンドの分離 + - マイクロサービスの必要性を検討 + +5. **データフロー図の作成** + - Mermaid記法でデータフローを可視化 + - ユーザーインタラクションの流れ + - システム間のデータの流れ + +6. **TypeScriptインターフェースの定義** + - NEVER 対象言語がTypeScriptで無い場合はそれに合わせたファイル形式に変更する。インタフェース定義が不要なら生成しない + - エンティティの型定義 + - APIリクエスト/レスポンスの型定義 + - 共通型の定義 + +8. **データベーススキーマの設計** + - NEVER 対象がデータベーススキーマが不要の場合は生成しない + - テーブル定義 + - リレーションシップ + - インデックス戦略 + - 正規化レベルの決定 + +9. **APIエンドポイントの設計** + - NEVER 対象にAPIではない場合、または既存のAPIを利用する場合は生成しない + - RESTful API設計 + - エンドポイントの命名規則 + - HTTPメソッドの適切な使用 + - リクエスト/レスポンスの構造 + +10. **ファイルの作成** + - `docs/design/{要件名}/` ディレクトリに以下を作成： + - `architecture.md` - アーキテクチャ概要 + - `dataflow.md` - データフロー図 + - `interfaces.ts` - TypeScript型定義 + - `database-schema.sql` - DBスキーマ + - `api-endpoints.md` - API仕様 + +## 出力フォーマット例 + +### architecture.md + +```markdown +# {要件名} アーキテクチャ設計 + +## システム概要 + +{システムの概要説明} + +## アーキテクチャパターン + +- パターン: {選択したパターン} +- 理由: {選択理由} + +## コンポーネント構成 + +### フロントエンド + +- フレームワーク: {使用フレームワーク} +- 状態管理: {状態管理方法} + +### バックエンド + +- フレームワーク: {使用フレームワーク} +- 認証方式: {認証方法} + +### データベース + +- DBMS: {使用するDBMS} +- キャッシュ: {キャッシュ戦略} +``` + +### dataflow.md + +```markdown +# データフロー図 + +## ユーザーインタラクションフロー + +\`\`\`mermaid +flowchart TD +A[ユーザー] --> B[フロントエンド] +B --> C[API Gateway] +C --> D[バックエンド] +D --> E[データベース] +\`\`\` + +## データ処理フロー + +\`\`\`mermaid +sequenceDiagram +participant U as ユーザー +participant F as フロントエンド +participant B as バックエンド +participant D as データベース + + U->>F: アクション + F->>B: APIリクエスト + B->>D: クエリ実行 + D-->>B: 結果返却 + B-->>F: レスポンス + F-->>U: 画面更新 + +\`\`\` +``` + +### interfaces.ts + +```typescript +// エンティティ定義 +export interface User { + id: string; + email: string; + name: string; + createdAt: Date; + updatedAt: Date; +} + +// APIリクエスト/レスポンス +export interface CreateUserRequest { + email: string; + name: string; + password: string; +} + +export interface ApiResponse { + success: boolean; + data?: T; + error?: { + code: string; + message: string; + }; +} +``` + +### database-schema.sql + +```sql +-- ユーザーテーブル +CREATE TABLE users ( + id UUID PRIMARY KEY DEFAULT gen_random_uuid(), + email VARCHAR(255) UNIQUE NOT NULL, + name VARCHAR(255) NOT NULL, + created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP, + updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP +); + +-- インデックス +CREATE INDEX idx_users_email ON users(email); +``` + +### api-endpoints.md + +```markdown +# API エンドポイント仕様 + +## 認証 + +### POST /auth/login + +リクエスト: +\`\`\`json +{ +"email": "user@example.com", +"password": "password" +} +\`\`\` + +レスポンス: +\`\`\`json +{ +"success": true, +"data": { +"token": "jwt-token", +"user": { ... } +} +} +\`\`\` + +## ユーザー管理 + +### GET /users/:id + +### POST /users + +### PUT /users/:id + +### DELETE /users/:id +``` + +## 実行後の確認 + +- @agent-symbol-searcher で作成した設計と既存システムとの整合性を確認 +- 作成したファイルの一覧を表示 +- 設計の主要なポイントをサマリーで表示 +- ユーザに確認を促すメッセージを表示 diff --git a/commands/kairo-implement.md b/commands/kairo-implement.md new file mode 100644 index 0000000..4011d87 --- /dev/null +++ b/commands/kairo-implement.md @@ -0,0 +1,379 @@ +--- +description: 分割されたタスクを順番に、またはユーザが指定したタスクを実装します。既存のTDDコマンドを活用して品質の高い実装を行います。 +--- +あなたは実装担当者です。残タスクを調べて 指定されたコマンドを駆使して実装をしてください + +# kairo-implement + +## 目的 + +分割されたタスクを順番に、またはユーザが指定したタスクを実装する。既存のTDDコマンドを活用して品質の高い実装を行う。 + +## 前提条件 + +- `docs/tasks/{要件名}-tasks.md` にタスク一覧が存在する +- ユーザがタスクの実装を承認している +- 既存のTDDコマンドが利用可能である +- 実装用のワークスペースが設定されている +- task_id は　`TASK-{4桁の数字}` (例 TASK-0001 ) である + +## 実行内容 + +**【信頼性レベル指示】**: +各項目について、元の資料（EARS要件定義書・設計文書含む）との照合状況を以下の信号でコメントしてください： + +- 🔵 **青信号**: EARS要件定義書・設計文書を参考にしてほぼ推測していない場合 +- 🟡 **黄信号**: EARS要件定義書・設計文書から妥当な推測の場合 +- 🔴 **赤信号**: EARS要件定義書・設計文書にない推測の場合 + +1. **追加ルールの読み込み** + - `docs/rule` ディレクトリが存在する場合は読み込み + - `docs/rule/kairo` ディレクトリが存在する場合は読み込み + - `docs/rule/kairo/implement` ディレクトリが存在する場合は読み込み + - 各ディレクトリ内のすべてのファイルを読み込み、追加ルールとして適用 + +2. **技術スタック定義の読み込み** + - `docs/tech-stack.md` が存在する場合は読み込み + - 存在しない場合は `CLAUDE.md` から技術スタックセクションを読み込み + - どちらも存在しない場合は `.claude/commands/tech-stack.md` のデフォルト定義を使用 + +3. **タスクの選択** + - @agent-symbol-searcher で指定されたタスクID(TASK-0000形式)を検索し、見つかったタスクファイルをReadツールで読み込み + - ユーザが指定したタスクIDを確認 + - 指定がない場合は、依存関係に基づいて次のタスクを自動選択 + - 選択したタスクの詳細を表示 + - 読み込んだ技術スタック定義に基づいて実装方針を決定 + +4. **依存関係の確認** + - @agent-symbol-searcher で依存タスクの状態を検索し、見つかったタスクファイルをReadツールで読み込み + - 依存タスクが完了しているか確認 + - 未完了の依存タスクがある場合は警告 + +5. **実装ディレクトリの準備** + - 現在のワークスペースで作業を行う + - 必要に応じてディレクトリ構造を確認 + +6. **実装タイプの判定** + - タスクの性質を分析（コード実装 vs 準備作業） + - 実装方式を決定（TDD vs 直接作業） + +7. **実装プロセスの実行** + + ### A. **TDDプロセス**（コード実装タスク用） + + a. **要件定義** - `@task general-purpose /tsumiki:tdd-requirements` + ``` + Task実行: TDD要件定義フェーズ + 目的: タスクの詳細要件を記述し、受け入れ基準を明確化する + コマンド: /tsumiki:tdd-requirements + 実行方式: 個別Task実行 + ``` + + b. **テストケース作成** - `@task general-purpose /tsumiki:tdd-testcases` + ``` + Task実行: TDDテストケース作成フェーズ + 目的: 単体テストケースを作成し、エッジケースを考慮する + コマンド: /tsumiki:tdd-testcases + 実行方式: 個別Task実行 + ``` + + c. **テスト実装** - `@task general-purpose /tsumiki:tdd-red` + ``` + Task実行: TDDレッドフェーズ + 目的: 失敗するテストを実装し、テストが失敗することを確認する + コマンド: /tsumiki:tdd-red + 実行方式: 個別Task実行 + ``` + + d. **最小実装** - `@task general-purpose /tsumiki:tdd-green` + ``` + Task実行: TDDグリーンフェーズ + 目的: テストが通る最小限の実装を行い、過度な実装を避ける + コマンド: /tsumiki:tdd-green + 実行方式: 個別Task実行 + ``` + + e. **リファクタリング** - `@task general-purpose /tsumiki:tdd-refactor` + ``` + Task実行: TDDリファクタリングフェーズ + 目的: コードの品質向上と保守性の改善を行う + コマンド: /tsumiki:tdd-refactor + 実行方式: 個別Task実行 + ``` + + f. **品質確認** - `@task general-purpose /tsumiki:tdd-verify-complete` + ``` + Task実行: TDD品質確認フェーズ + 目的: 実装の完成度を確認し、不足があればc-fを繰り返す + コマンド: /tsumiki:tdd-verify-complete + 実行方式: 個別Task実行 + ``` + + ### B. **直接作業プロセス**（準備作業タスク用） + + a. **準備作業の実行** - `@task general-purpose /tsumiki:direct-setup` + ``` + Task実行: 直接作業実行フェーズ + 目的: ディレクトリ作成、設定ファイル作成、依存関係のインストール、環境設定を行う + 作業内容: + - ディレクトリ作成 + - 設定ファイル作成 + - 依存関係のインストール + - 環境設定 + 実行方式: 個別Task実行 + ``` + + b. **作業結果の確認** - `@task general-purpose /tsumiki:direct-verify` + ``` + Task実行: 直接作業確認フェーズ + 目的: 作業完了の検証と成果物確認を行う + 作業内容: + - 作業完了の検証 + - 期待された成果物の確認 + - 次のタスクへの準備状況確認 + 実行方式: 個別Task実行 + ``` + +8. **タスクの完了処理** + - タスクのステータスを更新（タスクファイルのチェックボックスにチェックを入れる） + - 実装結果をドキュメント化 + - 次のタスクを提案 + +## 実行フロー + +```mermaid +flowchart TD + A[タスク選択] --> B{依存関係OK?} + B -->|No| C[警告表示] + B -->|Yes| D[実装開始] + D --> E{タスクタイプ判定} + E -->|コード実装| F[TDDプロセス] + E -->|準備作業| G[直接作業プロセス] + + F --> F1[tdd-requirements] + F1 --> F2[tdd-testcases] + F2 --> F3[tdd-red] + F3 --> F4[tdd-green] + F4 --> F5[tdd-refactor] + F5 --> F6[tdd-verify-complete] + F6 --> F7{品質OK?} + F7 -->|No| F3 + F7 -->|Yes| H[タスク完了] + + G --> G1[準備作業実行] + G1 --> G2[作業結果確認] + G2 --> H + + H --> I{他のタスク?} + I -->|Yes| A + I -->|No| J[全タスク完了] +``` + +## コマンド実行例 + +```bash +# 全タスクを順番に実装 +$ claude code kairo-implement --all + +# 特定のタスクを実装 +$ claude code kairo-implement --task {{task_id}} + +# 並行実行可能なタスクを一覧表示 +$ claude code kairo-implement --list-parallel + +# 現在の進捗を表示 +$ claude code kairo-implement --status +``` + +## 実装タイプ判定基準 + +### TDDプロセス（コード実装タスク） + +以下の条件に当てはまるタスク： + +- 新しいコンポーネント、サービス、フック等の実装 +- 既存コードの機能追加・修正 +- ビジネスロジックの実装 +- API実装 + +**例**: TaskService実装、UIコンポーネント作成、状態管理実装 + +### 直接作業プロセス（準備作業タスク） + +以下の条件に当てはまるタスク： + +- プロジェクト初期化・環境構築 +- ディレクトリ構造作成 +- 設定ファイル作成・更新 +- 依存関係のインストール +- ツール設定・設定 + +**例**: プロジェクト初期化、データベース設定、開発環境設定 + +## 個別Task実行アプローチ + +### Task実行の方針 + +各実装ステップを個別のTaskとして実行することで、以下のメリットが得られます： + +1. **独立性**: 各ステップが独立して実行され、エラー発生時の切り分けが容易 +2. **再実行性**: 特定のステップのみ再実行が可能 +3. **並列性**: 依存関係のないステップは並列実行可能 +4. **追跡性**: 各ステップの実行状況と結果が明確に記録される + +### Task実行パターン + +```bash +# TDDプロセスの場合 +@task general-purpose /tsumiki:tdd-requirements +@task general-purpose /tsumiki:tdd-testcases +@task general-purpose /tsumiki:tdd-red +@task general-purpose /tsumiki:tdd-green +@task general-purpose /tsumiki:tdd-refactor +@task general-purpose /tsumiki:tdd-verify-complete + +# 直接作業プロセスの場合 +@task general-purpose /tsumiki:direct-setup +@task general-purpose /tsumiki:direct-verify +``` + +## 実装時の注意事項 + +### TDDプロセス用 + +1. **テストファースト** + - 必ずテストを先に書く + - テストが失敗することを確認してから実装 + +2. **インクリメンタルな実装** + - 一度に全てを実装しない + - 小さなステップで進める + +3. **継続的な品質確認** + - 各ステップで品質を確認 + - 技術的負債を作らない + +### 直接作業プロセス用 + +1. **作業の段階的実行** + - 依存関係を考慮した順序で実行 + - 各ステップの完了を確認 + +2. **設定の検証** + - 作成した設定ファイルの動作確認 + - 環境の正常性チェック + +3. **ドキュメントの更新** + - 実装と同時にドキュメントも更新 + - 他の開発者が理解できるように + +## 出力フォーマット + +### タスク開始時（TDDプロセス） + +``` +🚀 タスク {{task_id}}: {{task_name}} の実装を開始します + +📋 タスク詳細: +- 要件: REQ-101, REQ-102 +- 依存: {{依存タスクID}} ✅ +- 推定時間: 4時間 +- 実装タイプ: TDDプロセス + +🔄 TDDプロセスを開始します... +``` + +### タスク開始時（直接作業プロセス） + +``` +🚀 タスク {{task_id}}: {{task_name}} の実装を開始します + +📋 タスク詳細: +- 要件: REQ-402, REQ-006 +- 依存: {{依存タスクID}} ✅ +- 推定時間: 3時間 +- 実装タイプ: 直接作業プロセス + +🔧 準備作業を開始します... +``` + +### 各ステップ完了時（TDD） + +``` +✅ Task 1/6: @task /tsumiki:tdd-requirements 完了 + ファイル: docs/implements/{要件名}/{{task_id}}/{要件名}-requirements.md + Task実行結果: 要件定義書作成完了 + +🏃 Task 2/6: @task /tsumiki:tdd-testcases 実行中... + Task実行: TDDテストケース作成フェーズを開始 +``` + +### 各ステップ完了時（直接作業） + +``` +✅ Task 1/2: @task /tsumiki:direct-setup 完了 + 作成ファイル: 8個、設定更新: 3個 + Task実行結果: 準備作業実行完了 + +🏃 Task 2/2: @task /tsumiki:direct-verify 実行中... + Task実行: 直接作業確認フェーズを開始 +``` + +### タスク完了時（TDD） + +``` +🎉 タスク {{task_id}} が完了しました！ + +✅ タスクファイルのチェックボックスを更新しました + - [ ] **タスク完了** → [x] **タスク完了** + +📊 実装サマリー: +- 実装タイプ: TDDプロセス (個別Task実行) +- 実行Taskステップ: 6個 (全て成功) +- 作成ファイル: 12個 +- テストケース: 25個 (全て成功) +- カバレッジ: 95% +- 所要時間: 3時間45分 + +📝 次の推奨タスク: +- {{次のタスクID}}: {{次のタスク名}} +- {{関連タスクID}}: {{関連タスク名}}（依存関係あり） + +続けて実装しますか？ (y/n) +``` + +### タスク完了時（直接作業） + +``` +🎉 タスク {{task_id}} が完了しました！ + +✅ タスクファイルのチェックボックスを更新しました + - [ ] **タスク完了** → [x] **タスク完了** + +📊 実装サマリー: +- 実装タイプ: 直接作業プロセス (個別Task実行) +- 実行Taskステップ: 2個 (全て成功) +- 作成ファイル: 8個 +- 設定更新: 3個 +- 環境確認: 正常 +- 所要時間: 2時間30分 + +📝 次の推奨タスク: +- {{次のタスクID}}: {{次のタスク名}} +- {{関連タスクID}}: {{関連タスク名}}（依存関係あり） + +続けて実装しますか？ (y/n) +``` + +## エラーハンドリング + +- 依存タスク未完了: 警告を表示し、確認を求める +- テスト失敗: 詳細なエラー情報を表示 +- ファイル競合: バックアップを作成してから上書き + +## 実行後の確認 + +- 実装したファイルの一覧を表示 +- テスト結果のサマリーを表示 +- 残りのタスクと進捗率を表示 +- 次のタスクの提案を表示 diff --git a/commands/kairo-requirements.md b/commands/kairo-requirements.md new file mode 100644 index 0000000..3a08717 --- /dev/null +++ b/commands/kairo-requirements.md @@ -0,0 +1,473 @@ +--- +description: ユーザから提供された要件の概要を分析し、EARS（Easy Approach to Requirements Syntax）記法を使用して詳細な受け入れ基準を含む要件定義書を作成します。 +--- + +# kairo-requirements + +## 目的 + +既存プロジェクトの情報を収集・分析し、ユーザから要件をヒアリングして、EARS（Easy Approach to Requirements Syntax）記法を使用した詳細な受け入れ基準を含む要件定義書を作成する。 +ユーザに要件をヒアリングするときは一問一答形式で選択肢から選ぶか自由入力を可能にする + +## 前提条件 + +- 既存プロジェクト（コードベース、設計文書等）が存在する +- `docs/spec/` ディレクトリが存在する（なければ作成） + +## 実行フロー + +### Phase 0: 既存プロジェクト情報の網羅的収集 + +**【信頼性レベル指示】**: +各項目について、元の資料（EARS要件定義書・設計文書・ユーザヒアリング含む）との照合状況を以下の信号でコメントしてください： + +- 🔵 **青信号**: EARS要件定義書・設計文書・ユーザヒアリングを参考にしてほぼ推測していない場合 +- 🟡 **黄信号**: EARS要件定義書・設計文書・ユーザヒアリングから妥当な推測の場合 +- 🔴 **赤信号**: EARS要件定義書・設計文書・ユーザヒアリングにない推測の場合 + +1. **追加ルールの読み込み** + - `docs/rule` ディレクトリが存在する場合は読み込み + - `docs/rule/kairo` ディレクトリが存在する場合は読み込み + - `docs/rule/kairo/requirements` ディレクトリが存在する場合は読み込み + - 各ディレクトリ内のすべてのファイルを読み込み、追加ルールとして適用 + +2. **プロジェクト基本情報収集** + - `CLAUDE.md` の内容を読み込み（プロジェクト概要・技術スタック・制約） + - `README.md` が存在する場合は読み込み + - プロジェクト構造（ディレクトリ構成）を把握 + +3. **既存設計文書・仕様書の調査** + - `docs/` ディレクトリ配下の全設計文書を確認 + - 既存の要件定義書・設計書を読み込み + - タスク管理ファイル（phase*.md）の内容確認 + - API仕様書・DB設計書があれば確認 + +4. **既存コードベース・開発状況の分析** + - @agent-symbol-searcher で既存仕様・実装の網羅的調査 + - git status/log で現在の開発状況・進捗確認 + - 実装済み機能 vs 設計書の差分分析 + - 残タスク・未実装部分の特定 + +5. **収集情報のサマリー作成** + - 既存プロジェクトの全体像整理 + - 定義済み要件・未定義部分の特定 + - 技術制約・非機能要件の整理 + - ギャップ分析（設計 vs 実装 vs ユーザー期待） + +### Phase 1: 既存情報ベースの差分ヒアリング + +6. **既存設計の妥当性・過不足確認** + - 既存の機能要件・非機能要件の確認質問 + - 現在の制約事項（性能・データ制限等）の妥当性確認 + - 技術スタック選択の再確認 + - 既存設計で実現困難・不適切な部分の特定 + +7. **未定義・曖昧部分の詳細化ヒアリング** + - 設計文書で詳細が不明な機能の具体化 + - ユーザーの実際の業務フロー・ユースケースの確認 + - 入出力データの詳細仕様確認 + - UI/UX の具体的な期待値確認 + +8. **追加・変更要件の特定** + - 既存設計にない新規機能要件の聞き出し + - 外部システム連携の追加需要確認 + - レポート・分析機能等の追加需要確認 + - 運用・メンテナンス要件の追加確認 + +9. **既存機能への影響範囲確認** + - 新規要件による既存機能への影響許容度確認 + - パフォーマンス要件への影響確認 + - セキュリティ・アクセシビリティ要件への影響確認 + - データ移行・互換性要件の確認 + +10. **優先順位・スコープ調整** + - Must Have / Should Have / Could Have / Won't Have の分類 + - リリーススコープ・段階的リリース計画の確認 + - 予算・スケジュール制約に基づく優先順位調整 + +### Phase 2: 統合要件定義書作成 + +11. **ユーザストーリーの作成・更新** + - WHO（誰が）、WHAT（何を）、WHY（なぜ）の形式で記述 + - 既存ユーザストーリーの更新・新規ストーリーの追加 + - 各機能の価値・優先順位を明確化 + +12. **EARS記法による統合要件定義** + - **通常要件（SHALL）**: システムが通常実行すべき動作 + - **条件付き要件（WHEN/IF-THEN）**: 特定の条件下での動作 + - **不要要件（WHERE）**: 特定の状態での動作 + - **オプション要件（MAY）**: 任意の機能 + - **制約要件（MUST）**: システムの制約事項 + - 既存要件との統合・重複排除・矛盾解決 + +13. **Edgeケース・非機能要件の定義** + - 異常系の処理・エラーハンドリング + - 境界値の処理・データ制限 + - パフォーマンス・セキュリティ・ユーザビリティ要件 + - 運用・保守・移行要件 + +14. **統合要件定義書ファイルの作成** + - `docs/spec/{要件名}-requirements.md`: 統合機能要件と関連文書へのリンク + - `docs/spec/{要件名}-user-stories.md`: 詳細なユーザストーリー + - `docs/spec/{要件名}-acceptance-criteria.md`: 受け入れ基準とテスト項目 + - 既存要件からの変更点・追加点を明記 + **【信頼性レベル指示】**: + 各項目について、元の資料（EARS要件定義書・設計文書・ユーザヒアリング含む）との照合状況を以下の信号でコメントしてください： + + - 🔵 **青信号**: EARS要件定義書・設計文書・ユーザヒアリングを参考にしてほぼ推測していない場合 + - 🟡 **黄信号**: EARS要件定義書・設計文書・ユーザヒアリングから妥当な推測の場合 + - 🔴 **赤信号**: EARS要件定義書・設計文書・ユーザヒアリングにない推測の場合 + +## 出力フォーマット例 + +### 1. requirements.md（メインファイル） + +```markdown +# {要件名} 要件定義書 + +## 概要 + +{要件の概要} + +## 関連文書 + +- **ユーザストーリー**: [📖 {要件名}-user-stories.md]({要件名}-user-stories.md) +- **受け入れ基準**: [✅ {要件名}-acceptance-criteria.md]({要件名}-acceptance-criteria.md) + +## 機能要件（EARS記法） + +**【信頼性レベル凡例】**: +- 🔵 **青信号**: EARS要件定義書・設計文書・ユーザヒアリングを参考にした確実な要件 +- 🟡 **黄信号**: EARS要件定義書・設計文書・ユーザヒアリングから妥当な推測による要件 +- 🔴 **赤信号**: EARS要件定義書・設計文書・ユーザヒアリングにない推測による要件 + +### 通常要件 + +- REQ-001: システムは {通常の動作} しなければならない 🔵 *EARS要件定義書第3章より* +- REQ-002: システムは {通常の動作} しなければならない 🟡 *設計文書から妥当な推測* +- REQ-003: システムは {通常の動作} しなければならない 🔵 *ユーザヒアリング2024-01-15より* + +### 条件付き要件 + +- REQ-101: {条件} の場合、システムは {動作} しなければならない 🔵 *ユーザー要件・API仕様書より* +- REQ-102: {条件} の場合、システムは {動作} しなければならない 🔴 *設計文書にない推測* +- REQ-103: {条件} の場合、システムは {動作} しなければならない 🟡 *ユーザヒアリング内容から妥当な推測* + +### 状態要件 + +- REQ-201: {状態} にある場合、システムは {動作} しなければならない 🟡 *DB設計書から妥当な推測* + +### オプション要件 + +- REQ-301: システムは {オプション機能} してもよい 🔵 *CLAUDE.md技術制約より* + +### 制約要件 + +- REQ-401: システムは {制約事項} しなければならない 🔵 *CLAUDE.md・既存実装より* + +## 非機能要件 + +### パフォーマンス + +- NFR-001: {パフォーマンス要件} 🟡 *CLAUDE.md制約から妥当な推測* + +### セキュリティ + +- NFR-101: {セキュリティ要件} 🔵 *セキュリティ設計書・実装より* + +### ユーザビリティ + +- NFR-201: {ユーザビリティ要件} 🔴 *ユーザー要件にない推測* +- NFR-202: {ユーザビリティ要件} 🔵 *ユーザヒアリング2024-01-20 UX要望より* + +## Edgeケース + +### エラー処理 + +- EDGE-001: {エラーケース} 🟡 *既存実装から妥当な推測* + +### 境界値 + +- EDGE-101: {境界値ケース} 🔵 *API仕様書・テストケースより* +``` + +### 2. user-stories.md（詳細なユーザストーリー） + +```markdown +# {要件名} ユーザストーリー + +## 概要 + +このドキュメントは{要件名}機能の詳細なユーザストーリーを記載します。 + +## ユーザー種別の定義 + +### プライマリユーザー + +- **エンドユーザー**: {エンドユーザーの詳細説明} +- **管理者**: {管理者の詳細説明} +- **開発者**: {開発者の詳細説明} + +### セカンダリユーザー + +- **システム管理者**: {システム管理者の詳細説明} +- **外部システム**: {外部システムの詳細説明} + +## ユーザストーリー + +**【信頼性レベル凡例】**: +- 🔵 **青信号**: EARS要件定義書・設計文書・ユーザヒアリングを参考にした確実なストーリー +- 🟡 **黄信号**: EARS要件定義書・設計文書・ユーザヒアリングから妥当な推測によるストーリー +- 🔴 **赤信号**: EARS要件定義書・設計文書・ユーザヒアリングにない推測によるストーリー + +### 📚 エピック1: {大きな機能グループ} 🔵 *ユーザヒアリング2024-01-15より* + +#### ストーリー1.1: {具体的なストーリー名} 🔵 *EARS要件定義書・ユーザヒアリングより* + +**ユーザストーリー**: +- **私は** {ユーザー種別} **として** +- **{具体的な状況・コンテキスト} において** +- **{実現したい行動・操作} をしたい** +- **そうすることで** {得られる価値・解決される問題} + +**詳細説明**: +- **背景**: {なぜこの機能が必要なのか} +- **前提条件**: {このストーリーの前提となる状況} +- **利用シーン**: {具体的な利用場面の例} +- **期待する体験**: {ユーザーが期待する体験の詳細} + +**関連要件**: REQ-001, REQ-002 + +**優先度**: 高/中/低 + +**見積もり**: {ストーリーポイントまたは工数} + +#### ストーリー1.2: {具体的なストーリー名} 🟡 *設計文書から妥当な推測* + +{同様の形式で記載} + +### 📚 エピック2: {大きな機能グループ} 🔴 *既存資料にない推測* + +{同様の形式で記載} + +## ユーザージャーニー + +### ジャーニー1: {代表的な利用フロー} 🔵 *ユーザヒアリング業務フローより* + +```mermaid +journey + title {ユーザージャーニーのタイトル} + section {フェーズ1} + {アクション1}: 5: {ユーザー種別} + {アクション2}: 3: {ユーザー種別} + section {フェーズ2} + {アクション3}: 4: {ユーザー種別} + {アクション4}: 5: {ユーザー種別} +``` + +**詳細**: +1. **{アクション1}**: {詳細な説明} +2. **{アクション2}**: {詳細な説明} + +## ペルソナ定義 + +### ペルソナ1: {代表的ユーザー名} 🔵 *ユーザヒアリング2024-01-18 ペルソナ調査より* + +- **基本情報**: {年齢、職業、技術レベル等} +- **ゴール**: {このユーザーが達成したいこと} +- **課題**: {現在抱えている問題} +- **行動パターン**: {典型的な行動の特徴} +- **利用環境**: {使用するデバイス、環境等} + +## 非機能的ユーザー要求 + +### ユーザビリティ要求 + +- **学習容易性**: {初回利用時の学習コスト} +- **効率性**: {熟練後の作業効率} +- **記憶しやすさ**: {再利用時の記憶のしやすさ} +- **エラー対応**: {エラー時の対応しやすさ} +- **満足度**: {主観的な満足度} + +### アクセシビリティ要求 + +- **視覚**: {視覚障害者への配慮} +- **聴覚**: {聴覚障害者への配慮} +- **運動**: {運動機能障害者への配慮} +- **認知**: {認知障害者への配慮} +``` + +### 3. acceptance-criteria.md（受け入れ基準） + +```markdown +# {要件名} 受け入れ基準 + +## 概要 + +このドキュメントは{要件名}機能の受け入れ基準とテスト項目を記載します。 + +## 機能テスト基準 + +**【信頼性レベル凡例】**: +- 🔵 **青信号**: EARS要件定義書・設計文書・ユーザヒアリングを参考にした確実なテスト基準 +- 🟡 **黄信号**: EARS要件定義書・設計文書・ユーザヒアリングから妥当な推測によるテスト基準 +- 🔴 **赤信号**: EARS要件定義書・設計文書・ユーザヒアリングにない推測によるテスト基準 + +### REQ-001: {要件名} の受け入れ基準 🔵 *EARS要件定義書・既存テスト仕様より* + +**Given（前提条件）**: +- {テスト実行前の状態} +- {必要な初期データ} + +**When（実行条件）**: +- {実行するアクション} +- {入力するデータ} + +**Then（期待結果）**: +- {期待される出力・状態} +- {確認すべき副作用} + +**テストケース**: +- [ ] 正常系: {正常なケースの詳細} +- [ ] 異常系: {異常なケースの詳細} +- [ ] 境界値: {境界値テストの詳細} + +### REQ-002: {要件名} の受け入れ基準 🟡 *ユーザヒアリング要望から妥当な推測* + +{同様の形式で記載} + +## 非機能テスト基準 + +### パフォーマンステスト + +**NFR-001: {パフォーマンス要件} 🔵 *CLAUDE.md制約・ユーザヒアリングより*** + +- [ ] 応答時間: {具体的な時間基準} +- [ ] スループット: {処理量の基準} +- [ ] 同時接続数: {同時利用者数の基準} +- [ ] リソース使用量: {CPU・メモリ使用量の基準} + +**テスト方法**: +- 負荷テストツール: {使用するツール} +- テストシナリオ: {具体的なテスト手順} +- 合格基準: {定量的な合格ライン} + +### セキュリティテスト + +**NFR-101: {セキュリティ要件} 🟡 *セキュリティ設計書から妥当な推測*** + +- [ ] 認証: {認証機能のテスト項目} +- [ ] 認可: {権限制御のテスト項目} +- [ ] データ保護: {データ暗号化のテスト項目} +- [ ] 脆弱性: {セキュリティ脆弱性のテスト項目} + +## ユーザビリティテスト基準 + +### UX/UIテスト + +- [ ] 直感的操作性: {操作の分かりやすさ} +- [ ] レスポンシブデザイン: {各デバイスでの表示} +- [ ] アクセシビリティ: {WCAG 2.1準拠} +- [ ] エラーメッセージ: {分かりやすいエラー表示} + +**テスト方法**: +- ユーザビリティテスト: {実施方法} +- A/Bテスト: {比較テストの方法} +- アクセシビリティチェック: {使用するツール} + +## Edgeケーステスト基準 + +### EDGE-001: {エラーケース} の受け入れ基準 🔴 *既存資料にない推測* + +**テストシナリオ**: +- {異常な状況の設定} +- {期待されるエラーハンドリング} +- {ユーザーへの適切な通知} + +**合格基準**: +- [ ] システムがクラッシュしない +- [ ] 適切なエラーメッセージが表示される +- [ ] データの整合性が保たれる +- [ ] 復旧可能な状態を維持する + +## 統合テスト基準 + +### システム間連携テスト + +- [ ] 外部API連携: {外部システムとの連携テスト} +- [ ] データベース連携: {DB操作の整合性テスト} +- [ ] ファイルシステム: {ファイル操作のテスト} + +## リグレッションテスト基準 + +### 既存機能影響確認 + +- [ ] 既存機能の動作確認: {影響範囲の特定と確認} +- [ ] パフォーマンス劣化確認: {既存機能の性能確認} +- [ ] セキュリティ設定確認: {セキュリティ機能の継続確認} + +## 受け入れテスト実行チェックリスト + +### テスト実行前 + +- [ ] テスト環境の準備完了 +- [ ] テストデータの準備完了 +- [ ] テストツールの準備完了 +- [ ] 実行担当者の確認完了 + +### テスト実行中 + +- [ ] 全機能テストの実行 +- [ ] 全非機能テストの実行 +- [ ] 問題発見時の記録 +- [ ] 修正後の再テスト + +### テスト完了後 + +- [ ] テスト結果の記録 +- [ ] 残存問題の整理 +- [ ] 受け入れ可否の判定 +- [ ] ステークホルダーへの報告 +``` + +## ヒアリング質問例 + +### 既存設計確認系質問 + +- "現在のCLAUDE.mdで定義されている{制約事項}について、実際の運用で問題ないでしょうか？" +- "技術スタック（{技術名}）について、変更希望や追加制約はありますか？" +- "既存の{機能名}機能で、想定しているユースケースに追加はありますか？" +- "パフォーマンス要件（{具体的な数値}）で、実際の業務に支障はないでしょうか？" + +### 詳細化系質問 + +- "{機能名}で、具体的にどのような操作フローを想定していますか？" +- "データの入力項目について、{項目名}以外に必要なものはありますか？" +- "エラーが発生した場合、どのような通知・対応を期待しますか？" +- "外部システムとの連携で、{システム名}との接続は必要ですか？" + +### 追加要件系質問 + +- "現在の設計にない機能で、実現したいものはありますか？" +- "レポート・分析機能は必要ですか？必要な場合、どのような情報が欲しいですか？" +- "モバイルアプリでの利用は想定していますか？" +- "複数人での同時利用・権限管理は必要ですか？" + +### 影響確認系質問 + +- "この新機能により、既存の{機能名}の変更は許容できますか？" +- "データ移行が発生する場合、どの程度の作業時間が許容できますか？" +- "パフォーマンスへの影響で、許容できる範囲を教えてください" +- "セキュリティ要件で、追加で考慮すべき点はありますか？" + +## 実行後の確認 + +- Phase 0で収集した既存プロジェクト情報のサマリーを表示 +- Phase 1でのヒアリング結果と既存情報との差分を明確化 +- 作成した3つのファイルのパスを表示 + - `docs/spec/{要件名}-requirements.md` + - `docs/spec/{要件名}-user-stories.md` + - `docs/spec/{要件名}-acceptance-criteria.md` +- 既存要件からの変更点・追加点の件数を報告 +- 各ファイル内のリンクが正しく設定されていることを確認 +- 既存設計書・実装との整合性確認を促すメッセージを表示 diff --git a/commands/kairo-task-verify.md b/commands/kairo-task-verify.md new file mode 100644 index 0000000..b13db42 --- /dev/null +++ b/commands/kairo-task-verify.md @@ -0,0 +1,67 @@ +--- +description: 作成されたタスクファイルの内容を確認し、出力フォーマット例に沿った情報が抜けていたら追加します。 +--- + +# kairo-task-verify + +## 目的 + +作成されたタスクファイルの内容を確認し、出力フォーマット例に沿った情報が抜けていたら追加する。 + +## 前提条件 + +- `docs/tasks/{要件名}-tasks.md` が存在する +- kairo-tasksコマンドによってタスクファイルが作成済みである + +## 実行内容 + +**【信頼性レベル指示】**: +各項目について、元の資料（EARS要件定義書・設計文書含む）との照合状況を以下の信号でコメントしてください： + +- 🔵 **青信号**: EARS要件定義書・設計文書を参考にしてほぼ推測していない場合 +- 🟡 **黄信号**: EARS要件定義書・設計文書から妥当な推測の場合 +- 🔴 **赤信号**: EARS要件定義書・設計文書にない推測の場合 + +1. **追加ルールの読み込み** + - `docs/rule` ディレクトリが存在する場合は読み込み + - `docs/rule/kairo` ディレクトリが存在する場合は読み込み + - `docs/rule/kairo/task-verify` ディレクトリが存在する場合は読み込み + - 各ディレクトリ内のすべてのファイルを読み込み、追加ルールとして適用 + +2. **技術スタック定義の読み込み** + - `docs/tech-stack.md` が存在する場合は読み込み + - 存在しない場合は `CLAUDE.md` から技術スタックセクションを読み込み + - どちらも存在しない場合は `.claude/commands/tech-stack.md` のデフォルト定義を使用 + +3. **タスクファイルの確認** + - @agent-symbol-searcher でタスクファイルを検索し、見つかったファイルをReadツールで読み込み + - `docs/tasks/{要件名}-tasks.md` をReadツールで読み込み + +4. **出力フォーマット例との比較** + - @agent-symbol-searcher で関連するタスクフォーマットを検索し、見つかったファイルをReadツールで読み込み + - kairo-tasksコマンドファイルをReadツールで読み込み、出力フォーマット例を確認 + - 作成されたタスクファイルに不足している情報を特定 + +5. **不足情報の追加** + 以下の項目が含まれているか確認し、不足していれば追加： + - 概要セクション（全タスク数、推定作業時間、クリティカルパス） + - 各タスクのチェックボックス + - タスクタイプ（TDD/DIRECT）の明記 + - 要件リンク + - 依存タスク + - 実装詳細 + - テスト要件 + - UI/UX要件（フロントエンドタスクの場合） + - エラーハンドリング要件 + - 完了条件 + - 実行順序（Mermaidガントチャート） + - サブタスクテンプレート情報 + +6. **ファイルの更新** + - 不足している情報を追加してファイルを更新 + +## 実行後の確認 + +- 更新したファイルのパスを表示 +- 追加した情報の概要を表示 +- タスクファイルが完全になったことを確認 diff --git a/commands/kairo-tasks.md b/commands/kairo-tasks.md new file mode 100644 index 0000000..6ecc275 --- /dev/null +++ b/commands/kairo-tasks.md @@ -0,0 +1,169 @@ +--- +description: 設計文書に基づいて実装タスクを1日単位の粒度で分割し、1ヶ月単位のフェーズに整理します。各フェーズ毎に個別のタスクファイルを作成し、依存関係を考慮した適切な順序で管理します。 +--- + +# kairo-tasks + +## 目的 + +設計文書に基づいて実装タスクを1日単位の粒度で分割し、1ヶ月単位のフェーズに整理する。各フェーズ毎に個別のタスクファイルを作成し、依存関係を考慮した適切な順序で管理する。 + +## 前提条件 + +- `docs/design/{要件名}/` に設計文書が存在する +- 設計がユーザによって承認されている（または承認が省略されている） +- `docs/tasks/` ディレクトリが存在する（なければ作成） +- 思考は英語で実施。ファイルは日本語で記述 +- NEVER: task_id は　`TASK-{4桁の数字}` (例 TASK-0001 )にする + +## 実行内容 + +**【信頼性レベル指示】**: +各項目について、元の資料（EARS要件定義書・設計文書含む）との照合状況を以下の信号でコメントしてください： + +- 🔵 **青信号**: EARS要件定義書・設計文書を参考にしてほぼ推測していない場合 +- 🟡 **黄信号**: EARS要件定義書・設計文書から妥当な推測の場合 +- 🔴 **赤信号**: EARS要件定義書・設計文書にない推測の場合 + +1. **追加ルールの読み込み** + - `docs/rule` ディレクトリが存在する場合は読み込み + - `docs/rule/kairo` ディレクトリが存在する場合は読み込み + - `docs/rule/kairo/tasks` ディレクトリが存在する場合は読み込み + - 各ディレクトリ内のすべてのファイルを読み込み、追加ルールとして適用 + +2. **技術スタック定義の読み込み** + - `docs/tech-stack.md` が存在する場合は読み込み + - 存在しない場合は `CLAUDE.md` から技術スタックセクションを読み込み + - どちらも存在しない場合は `.claude/commands/tech-stack.md` のデフォルト定義を使用 + +3. **設計文書の分析** + - @agent-symbol-searcher で設計文書を検索し、見つかったファイルをReadツールで読み込み + - `docs/design/{要件名}/architecture.md` をReadツールで読み込み + - `docs/design/{要件名}/database-schema.sql` をReadツールで読み込み + - `docs/design/{要件名}/api-endpoints.md` をReadツールで読み込み + - `docs/design/{要件名}/interfaces.ts` をReadツールで読み込み + - `docs/design/{要件名}/dataflow.md` をReadツールで読み込み + - 読み込んだ技術スタック定義に基づいて実装技術を特定 + +4. **既存タスクファイルの確認** + - @agent-symbol-searcher で既存タスクIDを検索し、見つかったタスクファイルをReadツールで読み込み + - 既存の`docs/tasks/{要件名}-*.md`ファイルをReadツールで読み込み + - 使用済みタスク番号（TASK-0000形式）を抽出 + - 新規タスクで重複しない番号を割り当て + +5. **タスクの洗い出し** + - 基盤タスク（DB設定、環境構築など） + - バックエンドタスク（API実装） + - フロントエンドタスク（UI実装） + - 画面のグループ毎に細かく分割する + - 統合タスク（E2Eテストなど） + +6. **依存関係の分析** + - タスク間の依存関係を明確化 + - 並行実行可能なタスクを識別 + - クリティカルパスを特定 + +7. **タスクの詳細化** + 各タスクに以下を含める： + - タスクID（TASK-0000形式） + - タスク名 + - タスクタイプ（TDD/DIRECT） + - **TDD**: コーディング、ビジネスロジック実装、UI実装、テスト実装など開発作業 + - **DIRECT**: 環境構築、設定ファイル作成、ドキュメント作成、ビルド設定など準備作業 + - 要件へのリンク + - 依存タスク + - 実装詳細 + - 単体テスト要件 + - 統合テスト要件 + - UI/UX要件（該当する場合） + - ローディング状態 + - エラー表示 + - モバイル対応 + - アクセシビリティ要件 + +8. **タスクの順序付け** + - 依存関係に基づいて実行順序を決定 + - マイルストーンを設定 + - 並行実行可能なタスクをグループ化 + +9. **フェーズ分割** + - 各タスクを1日単位の粒度で設計 + - タスクを1ヶ月(20日想定)以内の期間でフェーズに分割 + - NEVER タスクの情報の省略 + - YOU MUST 180時間を超えるようなフェーズは分割する + - IMPORTANT フェーズ数は固定しない + - IMPORTANT フェーズは500行未満で分割する + - YOU MUST フェーズの分割はアーキテクチャのレイヤーを基準にする + - NEVER 事前検討した分割基準を前提としない + +10. **ファイル作成** + - ファイル作成は ファイル毎に @task で実行する + - 各フェーズ毎に個別のタスクファイルを日本語で作成 + - NEVER タスクの情報の省略 + - `docs/tasks/{要件名}-phase1.md`: フェーズ1の詳細タスク + - `docs/tasks/{要件名}-phase2.md`: フェーズ2の詳細タスク + - （以下、フェーズ数に応じて継続） + - `docs/tasks/{要件名}-overview.md`: 全体概要とフェーズ一覧 + - 各タスクにチェックボックスを追加してタスクの完了状況を追跡可能にする + - 各タスクには 要件名 の定義を含める + +## 出力ファイル構造 + +作成するファイル: +- `docs/tasks/{要件名}-overview.md`: 全体概要とフェーズ一覧 +- `docs/tasks/{要件名}-phase1.md`: フェーズ1詳細タスク +- `docs/tasks/{要件名}-phase2.md`: フェーズ2詳細タスク +- （フェーズ数に応じて継続） + +## 必須構成要素 + +### Overview.mdの必須項目 +- プロジェクト概要（期間・工数・総タスク数） +- フェーズ構成テーブル（期間・成果物・タスク数・工数・ファイルリンク） +- 既存タスク番号管理（使用済み番号・次回開始番号） +- 全体進捗チェックボックス +- マイルストーン定義 + +### Phase.mdの必須項目 +- フェーズ概要（期間・目標・成果物） +- 週次計画（Week 1-4の目標・成果物） +- 日次タスク（TASK-0000形式、8時間単位） +- 各タスクの詳細構成: + - タスク完了チェックボックス + - 推定工数・タスクタイプ（TDD/DIRECT） + - 要件リンク・依存タスク + - 要件名 + - 実装詳細・完了条件 + - テスト要件（TDDタスクの場合） + +## タスクプロセス定義 + +### TDDタスク +1. `/tsumiki:tdd-requirements` - 詳細要件定義 +2. `/tsumiki:tdd-testcases` - テストケース作成 +3. `/tsumiki:tdd-red` - テスト実装（失敗） +4. `/tsumiki:tdd-green` - 最小実装 +5. `/tsumiki:tdd-refactor` - リファクタリング +6. `/tsumiki:tdd-verify-complete` - 品質確認 + +### DIRECTタスク +1. `/tsumiki:direct-setup` - 直接実装・設定 +2. `/tsumiki:direct-verify` - 動作確認・品質確認 + +## 実行フロー + +1. **追加ルール読み込み**: `docs/rule` → `docs/rule/kairo` → `docs/rule/kairo/tasks` +2. **技術スタック読み込み**: `docs/tech-stack.md` → `CLAUDE.md` → `.claude/commands/tech-stack.md` +3. **設計文書分析**: @agent-symbol-searcher で検索後、Readツールで各ファイル読み込み +4. **既存タスク確認**: @agent-symbol-searcher + Readで使用済み番号抽出 +5. **タスク洗い出し**: 基盤→バックエンド→フロントエンド→統合の順 +6. **フェーズ分割**: 180時間・500行を超えない単位で分割 +7. **ファイル作成**: overview.md + phase*.md作成 + +## 品質基準 + +- **フェーズ制限**: 180時間以内、500行未満 +- **タスク粒度**: 1日8時間単位 +- **番号管理**: TASK-0000形式、重複なし +- **完了条件**: 各タスクにチェックボックスと完了条件 +- **依存関係**: 前タスク完了後の実行順序明記 diff --git a/commands/rev-design.md b/commands/rev-design.md new file mode 100644 index 0000000..49b5c91 --- /dev/null +++ b/commands/rev-design.md @@ -0,0 +1,497 @@ +--- +description: 既存のコードベースから技術設計文書を逆生成します。実装されたアーキテクチャ、データフロー、API仕様、データベーススキーマ、TypeScriptインターフェースを分析し、設計書として文書化します。 +--- + +# rev-design + +## 目的 + +既存のコードベースから技術設計文書を逆生成する。実装されたアーキテクチャ、データフロー、API仕様、データベーススキーマ、TypeScriptインターフェースを分析し、設計書として文書化する。 + +## 前提条件 + +- 分析対象のコードベースが存在する +- `docs/reverse/` ディレクトリが存在する（なければ作成） +- 可能であれば事前に `/tsumiki:rev-tasks` を実行済み + +## 実行内容 + +1. **アーキテクチャの分析** + - プロジェクト構造からアーキテクチャパターンを特定 + - レイヤー構成の確認（MVC、Clean Architecture等） + - マイクロサービス構成の有無 + - フロントエンド/バックエンドの分離状況 + +2. **データフローの抽出** + - ユーザーインタラクションの流れ + - API呼び出しの流れ + - データベースアクセスパターン + - 状態管理の流れ + +3. **API仕様の抽出** + - エンドポイント一覧の生成 + - リクエスト/レスポンス構造の分析 + - 認証・認可方式の確認 + - エラーレスポンス形式 + +4. **データベーススキーマの逆生成** + - テーブル定義の抽出 + - リレーションシップの分析 + - インデックス設定の確認 + - 制約条件の抽出 + +5. **TypeScript型定義の整理** + - エンティティ型の抽出 + - API型の抽出 + - 共通型の整理 + - 型の依存関係分析 + +6. **コンポーネント設計の分析** + - UIコンポーネント階層 + - Propsインターフェース + - 状態管理の設計 + - ルーティング設計 + +7. **ファイルの作成** + - `docs/reverse/{プロジェクト名}-architecture.md` - アーキテクチャ概要 + - `docs/reverse/{プロジェクト名}-dataflow.md` - データフロー図 + - `docs/reverse/{プロジェクト名}-api-specs.md` - API仕様 + - `docs/reverse/{プロジェクト名}-database.md` - DB設計 + - `docs/reverse/{プロジェクト名}-interfaces.ts` - 型定義集約 + +## 出力フォーマット例 + +### architecture.md + +```markdown +# {プロジェクト名} アーキテクチャ設計（逆生成） + +## 分析日時 +{実行日時} + +## システム概要 + +### 実装されたアーキテクチャ +- **パターン**: {特定されたアーキテクチャパターン} +- **フレームワーク**: {使用フレームワーク} +- **構成**: {発見された構成} + +### 技術スタック + +#### フロントエンド +- **フレームワーク**: {React/Vue/Angular等} +- **状態管理**: {Redux/Zustand/Pinia等} +- **UI ライブラリ**: {Material-UI/Ant Design等} +- **スタイリング**: {CSS Modules/styled-components等} + +#### バックエンド +- **フレームワーク**: {Express/NestJS/FastAPI等} +- **認証方式**: {JWT/Session/OAuth等} +- **ORM/データアクセス**: {TypeORM/Prisma/Sequelize等} +- **バリデーション**: {Joi/Yup/zod等} + +#### データベース +- **DBMS**: {PostgreSQL/MySQL/MongoDB等} +- **キャッシュ**: {Redis/Memcached等 or なし} +- **接続プール**: {実装されているか} + +#### インフラ・ツール +- **ビルドツール**: {Webpack/Vite/Rollup等} +- **テストフレームワーク**: {Jest/Vitest/Pytest等} +- **コード品質**: {ESLint/Prettier/SonarQube等} + +## レイヤー構成 + +### 発見されたレイヤー +``` +{実際のディレクトリ構造} +``` + +### レイヤー責務分析 +- **プレゼンテーション層**: {実装状況} +- **アプリケーション層**: {実装状況} +- **ドメイン層**: {実装状況} +- **インフラストラクチャ層**: {実装状況} + +## デザインパターン + +### 発見されたパターン +- **Dependency Injection**: {実装されているか} +- **Repository Pattern**: {実装されているか} +- **Factory Pattern**: {使用箇所} +- **Observer Pattern**: {使用箇所} +- **Strategy Pattern**: {使用箇所} + +## 非機能要件の実装状況 + +### セキュリティ +- **認証**: {実装方式} +- **認可**: {実装方式} +- **CORS設定**: {設定状況} +- **HTTPS対応**: {対応状況} + +### パフォーマンス +- **キャッシュ**: {実装状況} +- **データベース最適化**: {インデックス等} +- **CDN**: {使用状況} +- **画像最適化**: {実装状況} + +### 運用・監視 +- **ログ出力**: {実装状況} +- **エラートラッキング**: {実装状況} +- **メトリクス収集**: {実装状況} +- **ヘルスチェック**: {実装状況} +``` + +### dataflow.md + +```markdown +# データフロー図（逆生成） + +## ユーザーインタラクションフロー + +### 認証フロー +\`\`\`mermaid +sequenceDiagram + participant U as ユーザー + participant F as フロントエンド + participant B as バックエンド + participant D as データベース + + U->>F: ログイン情報入力 + F->>B: POST /auth/login + B->>D: ユーザー検証 + D-->>B: ユーザー情報 + B-->>F: JWTトークン + F-->>U: ログイン完了 +\`\`\` + +### データ取得フロー +\`\`\`mermaid +flowchart TD + A[ユーザーアクション] --> B[Reactコンポーネント] + B --> C[useQueryフック] + C --> D[Axios HTTP Client] + D --> E[API Gateway/Express] + E --> F[コントローラー] + F --> G[サービス層] + G --> H[リポジトリ層] + H --> I[データベース] + I --> H + H --> G + G --> F + F --> E + E --> D + D --> C + C --> B + B --> J[UI更新] +\`\`\` + +## 状態管理フロー + +### {使用されている状態管理ライブラリ} フロー +\`\`\`mermaid +flowchart LR + A[コンポーネント] --> B[Action Dispatch] + B --> C[Reducer/Store] + C --> D[State更新] + D --> A +\`\`\` + +## エラーハンドリングフロー + +\`\`\`mermaid +flowchart TD + A[エラー発生] --> B{エラー種別} + B -->|認証エラー| C[リダイレクト to ログイン] + B -->|ネットワークエラー| D[リトライ機能] + B -->|バリデーションエラー| E[フォームエラー表示] + B -->|サーバーエラー| F[エラートースト表示] +\`\`\` +``` + +### api-specs.md + +```markdown +# API仕様書（逆生成） + +## ベースURL +\`{発見されたベースURL}\` + +## 認証方式 +{発見された認証方式の詳細} + +## エンドポイント一覧 + +### 認証関連 + +#### POST /auth/login +**説明**: ユーザーログイン + +**リクエスト**: +\`\`\`typescript +{ + email: string; + password: string; +} +\`\`\` + +**レスポンス**: +\`\`\`typescript +{ + success: boolean; + data: { + token: string; + user: { + id: string; + email: string; + name: string; + } + }; +} +\`\`\` + +**エラーレスポンス**: +\`\`\`typescript +{ + success: false; + error: { + code: string; + message: string; + } +} +\`\`\` + +#### POST /auth/logout +**説明**: ユーザーログアウト + +**ヘッダー**: +\`\`\` +Authorization: Bearer {token} +\`\`\` + +### {その他のエンドポイント} + +## エラーコード一覧 + +| コード | メッセージ | 説明 | +|--------|------------|------| +| AUTH_001 | Invalid credentials | 認証情報が無効 | +| AUTH_002 | Token expired | トークンが期限切れ | +| VALID_001 | Validation failed | バリデーションエラー | + +## レスポンス共通形式 + +### 成功レスポンス +\`\`\`typescript +{ + success: true; + data: T; // 型は endpoint によって変動 +} +\`\`\` + +### エラーレスポンス +\`\`\`typescript +{ + success: false; + error: { + code: string; + message: string; + details?: any; + } +} +\`\`\` +``` + +### database.md + +```markdown +# データベース設計（逆生成） + +## スキーマ概要 + +### テーブル一覧 +{発見されたテーブル一覧} + +### ER図 +\`\`\`mermaid +erDiagram + USERS { + uuid id PK + varchar email UK + varchar name + timestamp created_at + timestamp updated_at + } + + POSTS { + uuid id PK + uuid user_id FK + varchar title + text content + timestamp created_at + timestamp updated_at + } + + USERS ||--o{ POSTS : creates +\`\`\` + +## テーブル詳細 + +### users テーブル +\`\`\`sql +{実際のCREATE TABLE文} +\`\`\` + +**カラム説明**: +- \`id\`: {説明} +- \`email\`: {説明} +- \`name\`: {説明} + +**インデックス**: +- \`idx_users_email\`: email カラムの検索用 + +### {その他のテーブル} + +## 制約・関係性 + +### 外部キー制約 +{発見された外部キー制約} + +### ユニーク制約 +{発見されたユニーク制約} + +## データアクセスパターン + +### よく使用されるクエリ +{コードから発見されたクエリパターン} + +### パフォーマンス考慮事項 +{発見されたインデックス戦略} +``` + +### interfaces.ts + +```typescript +// ====================== +// エンティティ型定義 +// ====================== + +export interface User { + id: string; + email: string; + name: string; + createdAt: Date; + updatedAt: Date; +} + +export interface Post { + id: string; + userId: string; + title: string; + content: string; + createdAt: Date; + updatedAt: Date; + user?: User; +} + +// ====================== +// API型定義 +// ====================== + +export interface LoginRequest { + email: string; + password: string; +} + +export interface LoginResponse { + success: boolean; + data: { + token: string; + user: User; + }; +} + +export interface ApiResponse { + success: boolean; + data?: T; + error?: { + code: string; + message: string; + details?: any; + }; +} + +// ====================== +// コンポーネントProps型 +// ====================== + +export interface LoginFormProps { + onSubmit: (data: LoginRequest) => void; + loading?: boolean; + error?: string; +} + +// ====================== +// 状態管理型 +// ====================== + +export interface AuthState { + user: User | null; + token: string | null; + isAuthenticated: boolean; + loading: boolean; +} + +// ====================== +// 設定型 +// ====================== + +export interface AppConfig { + apiBaseUrl: string; + tokenStorageKey: string; + supportedLanguages: string[]; +} +``` + +## 分析アルゴリズム + +### 1. ファイル走査・パターンマッチング +- AST解析による関数・クラス・インターフェース抽出 +- 正規表現による設定ファイル解析 +- ディレクトリ構造からのアーキテクチャ推定 + +### 2. API仕様の自動生成 +- Express/NestJS ルート定義の解析 +- FastAPI スキーマ定義の解析 +- TypeScript型定義からのリクエスト/レスポンス推定 + +### 3. データベーススキーマの抽出 +- マイグレーションファイルの解析 +- ORM モデル定義の解析 +- SQL ファイルの解析 + +## 実行コマンド例 + +```bash +# フル分析（全設計書生成） +claude code rev-design + +# 特定の設計書のみ生成 +claude code rev-design --target architecture +claude code rev-design --target api +claude code rev-design --target database + +# 特定のディレクトリを分析 +claude code rev-design --path ./backend + +# 出力形式指定 +claude code rev-design --format markdown,openapi +``` + +## 実行後の確認 + +- 生成された設計書ファイルの一覧を表示 +- 抽出されたAPI数、テーブル数、型定義数等の統計情報を表示 +- 不足している設計要素や推奨改善点を提示 +- 次のリバースエンジニアリングステップ（要件定義生成等）を提案 diff --git a/commands/rev-requirements.md b/commands/rev-requirements.md new file mode 100644 index 0000000..54e3ba8 --- /dev/null +++ b/commands/rev-requirements.md @@ -0,0 +1,389 @@ +--- +description: 既存のコードベースから要件定義書を逆生成します。実装された機能を分析し、EARS（Easy Approach to Requirements Syntax）記法を用いて機能要件、非機能要件、ユーザーストーリーを抽出・文書化します。 +--- + +# rev-requirements + +## 目的 + +既存のコードベースから要件定義書を逆生成する。実装された機能を分析し、EARS（Easy Approach to Requirements Syntax）記法を用いて機能要件、非機能要件、ユーザーストーリーを抽出・文書化する。 + +## 前提条件 + +- 分析対象のコードベースが存在する +- `docs/reverse/` ディレクトリが存在する（なければ作成） +- 可能であれば事前に `/tsumiki:rev-tasks` および `/tsumiki:rev-design` を実行済み + +## 実行内容 + +1. **機能の特定と分析** + - UI コンポーネントから画面機能を抽出 + - API エンドポイントからビジネス機能を特定 + - データベーススキーマからデータ要件を推定 + - テストコードから期待動作を確認 + +2. **ユーザーストーリーの逆算** + - 実装された機能からユーザーの意図を推定 + - WHO（ユーザー種別）の特定 + - WHAT（実現したいこと）の抽出 + - WHY（得られる価値）の推定 + +3. **EARS記法による要件分類** + - **通常要件（SHALL）**: 標準的な機能実装から抽出 + - **条件付き要件（WHEN/IF-THEN）**: 条件分岐ロジックから抽出 + - **状態要件（WHERE）**: 状態管理実装から抽出 + - **オプション要件（MAY）**: 設定可能機能から抽出 + - **制約要件（MUST）**: バリデーション・制限ロジックから抽出 + +4. **非機能要件の推定** + - パフォーマンス要件：実装されたキャッシュ、最適化から推定 + - セキュリティ要件：認証・認可実装から抽出 + - ユーザビリティ要件：UI/UX実装から抽出 + - 運用要件：ログ、監視実装から抽出 + +5. **Edgeケースの特定** + - エラーハンドリング実装から異常系要件を抽出 + - バリデーション実装から境界値要件を抽出 + - テストケースから想定されるエラーケースを抽出 + +6. **受け入れ基準の生成** + - 実装されたテストから受け入れ基準を逆算 + - 未実装のテストケースを推奨事項として提示 + +7. **ファイルの作成** + - `docs/reverse/{プロジェクト名}-requirements.md` として保存 + +## 出力フォーマット例 + +```markdown +# {プロジェクト名} 要件定義書（逆生成） + +## 分析概要 + +**分析日時**: {実行日時} +**対象コードベース**: {パス} +**抽出要件数**: {機能要件数}個の機能要件、{非機能要件数}個の非機能要件 +**信頼度**: {分析の信頼度} % （実装カバレッジに基づく） + +## システム概要 + +### 推定されたシステム目的 +{実装された機能から推測されるシステムの目的} + +### 対象ユーザー +{UIコンポーネントや機能から推定されるユーザー種別} + +## ユーザーストーリー + +### ストーリー1: ユーザー認証 +- **である** 未登録・既存ユーザー **として** +- **私は** システムに安全にログイン **をしたい** +- **そうすることで** 個人的な情報やサービスにアクセスできる + +**実装根拠**: +- `LoginForm.tsx` - ログインフォーム実装 +- `POST /auth/login` - 認証API実装 +- `useAuth` フック - 認証状態管理 + +### ストーリー2: {その他のストーリー} + +{実装された機能から推定される追加のユーザーストーリー} + +## 機能要件（EARS記法） + +### 通常要件 + +#### REQ-001: ユーザー認証 +システムは有効なメールアドレスとパスワードでのユーザーログインを提供しなければならない。 + +**実装根拠**: +- `auth.service.ts:login()` メソッド +- `POST /auth/login` エンドポイント +- JWTトークン発行実装 + +#### REQ-002: セッション管理 +システムはログイン後のユーザーセッションを管理しなければならない。 + +**実装根拠**: +- JWT トークンによるセッション管理 +- `useAuth` フックでの状態管理 +- ローカルストレージでのトークン永続化 + +### 条件付き要件 + +#### REQ-101: 認証失敗時の処理 +無効な認証情報が提供された場合、システムは適切なエラーメッセージを表示しなければならない。 + +**実装根拠**: +- `auth.controller.ts` のエラーハンドリング +- `LoginForm.tsx` のエラー表示実装 + +#### REQ-102: トークン期限切れ時の処理 +JWTトークンが期限切れの場合、システムはユーザーを再ログインページにリダイレクトしなければならない。 + +**実装根拠**: +- `axios.interceptors` での401エラーハンドリング +- 自動ログアウト機能の実装 + +### 状態要件 + +#### REQ-201: ログイン状態での表示 +ユーザーがログイン状態にある場合、システムは認証済みユーザー向けのUIを表示しなければならない。 + +**実装根拠**: +- `useAuth` フックでの認証状態確認 +- 認証状態による条件分岐レンダリング + +### オプション要件 + +#### REQ-301: ログイン状態の記憶 +システムはユーザーのログイン状態を記憶してもよい。 + +**実装根拠**: +- ローカルストレージでのトークン保存 +- 自動ログイン機能の実装 + +### 制約要件 + +#### REQ-401: パスワード要件 +システムはパスワードに最小8文字の制約を設けなければならない。 + +**実装根拠**: +- フロントエンドバリデーション実装 +- `yup` スキーマでの制約定義 + +#### REQ-402: レート制限 +システムはログイン試行に対してレート制限を設けなければならない。 + +**実装根拠**: +- `express-rate-limit` ミドルウェアの実装 + +## 非機能要件 + +### パフォーマンス + +#### NFR-001: ログイン応答時間 +システムは通常のログイン処理を2秒以内に完了しなければならない。 + +**実装根拠**: +- データベースインデックス設定 +- 効率的なクエリ実装 + +#### NFR-002: 同時ユーザー数 +システムは同時に100ユーザーのアクセスを処理できなければならない。 + +**推定根拠**: +- 接続プール設定 +- サーバー構成 + +### セキュリティ + +#### NFR-101: 認証トークン暗号化 +システムはJWTトークンを適切に暗号化しなければならない。 + +**実装根拠**: +- `jsonwebtoken` ライブラリの使用 +- 秘密鍵による署名実装 + +#### NFR-102: HTTPS通信 +システムは本番環境でHTTPS通信を強制しなければならない。 + +**実装根拠**: +- SSL設定ファイル +- HTTPS リダイレクト実装 + +### ユーザビリティ + +#### NFR-201: レスポンシブデザイン +システムはモバイルデバイスでも利用可能でなければならない。 + +**実装根拠**: +- CSS メディアクエリの実装 +- レスポンシブUIコンポーネント + +#### NFR-202: アクセシビリティ +システムは基本的なアクセシビリティ要件を満たさなければならない。 + +**実装根拠**: +- ARIA属性の使用 +- セマンティックHTML構造 + +### 運用性 + +#### NFR-301: ログ出力 +システムは重要な操作をログに記録しなければならない。 + +**実装根拠**: +- `winston` ログライブラリの使用 +- 構造化ログの実装 + +#### NFR-302: エラー追跡 +システムは発生したエラーを追跡可能でなければならない。 + +**実装根拠**: +- エラーハンドリング実装 +- ログ出力による追跡機能 + +## Edgeケース + +### エラー処理 + +#### EDGE-001: ネットワーク障害 +ネットワーク接続が不安定な場合のリトライ処理 + +**実装根拠**: +- `axios` のリトライ設定 +- エラートースト表示 + +#### EDGE-002: サーバーダウン +バックエンドサーバーが利用できない場合の処理 + +**実装根拠**: +- フォールバック機能 +- エラーページ表示 + +### 境界値 + +#### EDGE-101: 最大文字数制限 +入力フィールドの最大文字数制限 + +**実装根拠**: +- フォームバリデーション実装 +- データベース制約 + +#### EDGE-102: 空文字・null値処理 +空文字やnull値に対する適切な処理 + +**実装根拠**: +- バリデーション実装 +- デフォルト値設定 + +## 受け入れ基準 + +### 実装済み機能テスト + +- [x] ユーザーログイン機能 + - [x] 有効な認証情報でのログイン成功 + - [x] 無効な認証情報でのログイン失敗 + - [x] エラーメッセージの適切な表示 +- [x] セッション管理機能 + - [x] ログイン状態の維持 + - [x] ログアウト機能 + - [x] トークン期限切れ処理 + +### 推奨追加テスト + +- [ ] **パフォーマンステスト** + - [ ] ログイン応答時間測定 + - [ ] 同時アクセス負荷テスト +- [ ] **セキュリティテスト** + - [ ] SQLインジェクション対策テスト + - [ ] XSS対策テスト + - [ ] CSRF対策テスト +- [ ] **アクセシビリティテスト** + - [ ] スクリーンリーダー対応テスト + - [ ] キーボード操作テスト + +## 推定されていない要件 + +### 不明確な部分 + +以下の要件は実装から推定が困難なため、ステークホルダーとの確認が必要： + +1. **ビジネス要件** + - システムの使用目的の詳細 + - 対象ユーザーの詳細な属性 + - 収益モデルや事業目標 + +2. **運用要件** + - バックアップ・復旧要件 + - SLA（サービスレベル合意） + - 監視・アラート要件 + +3. **法的・コンプライアンス要件** + - データ保護規則への準拠 + - 業界固有の規制要件 + +### 推奨される次ステップ + +1. **ステークホルダーインタビュー** - 推定された要件の確認 +2. **ユーザビリティテスト** - 実際のユーザビリティ要件の確認 +3. **パフォーマンステスト** - 非機能要件の検証 +4. **セキュリティ監査** - セキュリティ要件の詳細検証 + +## 分析の制約事項 + +### 信頼度に影響する要因 + +- **コメント不足**: 開発者の意図を推定で補完 +- **テストカバレッジ**: {%}% - 未テスト部分の要件は推定 +- **ドキュメント不足**: 外部仕様書が存在しない +- **レガシーコード**: 古い実装パターンによる推定の難しさ + +### 推定の根拠 + +- **強い根拠**: 実装 + テスト + 明確な動作 +- **中程度の根拠**: 実装 + 部分的テスト +- **弱い根拠**: 実装のみ、推定で補完 + +``` + +## 要件抽出アルゴリズム + +### 1. 機能要件の抽出プロセス + +``` +1. APIエンドポイント → ビジネス機能要件 +2. UIコンポーネント → ユーザーインターフェース要件 +3. データベーススキーマ → データ要件 +4. バリデーション実装 → 制約要件 +5. 条件分岐 → 条件付き要件 +``` + +### 2. 非機能要件の推定プロセス + +``` +1. 設定ファイル + ライブラリ → パフォーマンス・セキュリティ要件 +2. UI実装パターン → ユーザビリティ要件 +3. ログ・監視実装 → 運用要件 +4. テスト実装 → 品質要件 +``` + +### 3. ユーザーストーリーの逆算プロセス + +``` +1. 画面遷移フロー → ユーザージャーニー +2. フォーム・入力項目 → ユーザーアクション +3. データの CRUD操作 → ユーザーニーズ +4. 権限・ロール実装 → ユーザー種別 +``` + +## 実行コマンド例 + +```bash +# フル分析（全要件抽出） +claude code rev-requirements + +# 特定の要件カテゴリのみ抽出 +claude code rev-requirements --target functional +claude code rev-requirements --target non-functional +claude code rev-requirements --target user-stories + +# 信頼度フィルタ +claude code rev-requirements --confidence high +claude code rev-requirements --confidence medium + +# 特定のディレクトリを分析 +claude code rev-requirements --path ./src + +# 出力形式指定 +claude code rev-requirements --format markdown,json +``` + +## 実行後の確認 + +- 抽出された要件数（機能要件・非機能要件）を表示 +- 分析の信頼度と根拠の強さを報告 +- 推定が困難な要件や確認が必要な項目を提示 +- ステークホルダー確認のための質問リストを生成 +- 次の推奨アクション（テスト追加、ドキュメント整備等）を提案 diff --git a/commands/rev-specs.md b/commands/rev-specs.md new file mode 100644 index 0000000..b4e1db6 --- /dev/null +++ b/commands/rev-specs.md @@ -0,0 +1,622 @@ +--- +description: 既存のコードベースから包括的なテストケースと仕様書を逆生成します。実装されたビジネスロジック、API動作、UI コンポーネントの動作を分析し、不足しているテストケースを特定・生成し、仕様書として文書化します。 +--- + +# rev-specs + +## 目的 + +既存のコードベースから包括的なテストケースと仕様書を逆生成する。実装されたビジネスロジック、API動作、UI コンポーネントの動作を分析し、不足しているテストケースを特定・生成し、仕様書として文書化する。 + +## 前提条件 + +- 分析対象のコードベースが存在する +- `docs/reverse/` ディレクトリが存在する（なければ作成） +- 可能であれば事前に `/tsumiki:rev-requirements`, `/tsumiki:rev-design` を実行済み + +## 実行内容 + +1. **既存テストの分析** + - 単体テスト（Unit Test）の実装状況確認 + - 統合テスト（Integration Test）の実装状況確認 + - E2Eテスト（End-to-End Test）の実装状況確認 + - テストカバレッジの測定 + +2. **実装コードからテストケースの逆生成** + - 関数・メソッドの引数・戻り値からのテストケース生成 + - 条件分岐からの境界値テスト生成 + - エラーハンドリングからの異常系テスト生成 + - データベース操作からのデータテスト生成 + +3. **API仕様からテストケースの生成** + - 各エンドポイントの正常系テスト + - 認証・認可テスト + - バリデーションエラーテスト + - HTTPステータスコードテスト + +4. **UI コンポーネントからテストケースの生成** + - コンポーネントレンダリングテスト + - ユーザーインタラクションテスト + - 状態変更テスト + - プロパティ変更テスト + +5. **パフォーマンス・セキュリティテストケースの生成** + - 負荷テストシナリオ + - セキュリティ脆弱性テスト + - レスポンス時間テスト + +6. **テスト仕様書の生成** + - テスト計画書 + - テストケース一覧 + - テスト環境仕様 + - テスト手順書 + +7. **ファイルの作成** + - `docs/reverse/{プロジェクト名}-test-specs.md` - テスト仕様書 + - `docs/reverse/{プロジェクト名}-test-cases.md` - テストケース一覧 + - `docs/reverse/tests/` - 生成されたテストコード + +## 出力フォーマット例 + +### test-specs.md + +```markdown +# {プロジェクト名} テスト仕様書（逆生成） + +## 分析概要 + +**分析日時**: {実行日時} +**対象コードベース**: {パス} +**テストカバレッジ**: {現在のカバレッジ}% +**生成テストケース数**: {生成数}個 +**実装推奨テスト数**: {推奨数}個 + +## 現在のテスト実装状況 + +### テストフレームワーク +- **単体テスト**: {Jest/Vitest/pytest等} +- **統合テスト**: {Supertest/TestContainers等} +- **E2Eテスト**: {Cypress/Playwright等} +- **コードカバレッジ**: {istanbul/c8等} + +### テストカバレッジ詳細 + +| ファイル/ディレクトリ | 行カバレッジ | 分岐カバレッジ | 関数カバレッジ | +|---------------------|-------------|-------------|-------------| +| src/auth/ | 85% | 75% | 90% | +| src/users/ | 60% | 45% | 70% | +| src/components/ | 40% | 30% | 50% | +| **全体** | **65%** | **55%** | **75%** | + +### テストカテゴリ別実装状況 + +#### 単体テスト +- [x] **認証サービス**: auth.service.spec.ts +- [x] **ユーザーサービス**: user.service.spec.ts +- [ ] **データ変換ユーティリティ**: 未実装 +- [ ] **バリデーションヘルパー**: 未実装 + +#### 統合テスト +- [x] **認証API**: auth.controller.spec.ts +- [ ] **ユーザー管理API**: 未実装 +- [ ] **データベース操作**: 未実装 + +#### E2Eテスト +- [ ] **ユーザーログインフロー**: 未実装 +- [ ] **データ操作フロー**: 未実装 +- [ ] **エラーハンドリング**: 未実装 + +## 生成されたテストケース + +### API テストケース + +#### POST /auth/login - ログイン認証 + +**正常系テスト** +```typescript +describe('POST /auth/login', () => { + it('有効な認証情報でログイン成功', async () => { + const response = await request(app) + .post('/auth/login') + .send({ + email: 'test@example.com', + password: 'password123' + }); + + expect(response.status).toBe(200); + expect(response.body.success).toBe(true); + expect(response.body.data.token).toBeDefined(); + expect(response.body.data.user.email).toBe('test@example.com'); + }); + + it('JWTトークンが正しい形式で返される', async () => { + const response = await request(app) + .post('/auth/login') + .send(validCredentials); + + const token = response.body.data.token; + expect(token).toMatch(/^[A-Za-z0-9-_]+\.[A-Za-z0-9-_]+\.[A-Za-z0-9-_]+$/); + }); +}); +``` + +**異常系テスト** +```typescript +describe('POST /auth/login - 異常系', () => { + it('無効なメールアドレスでエラー', async () => { + const response = await request(app) + .post('/auth/login') + .send({ + email: 'invalid-email', + password: 'password123' + }); + + expect(response.status).toBe(400); + expect(response.body.success).toBe(false); + expect(response.body.error.code).toBe('VALIDATION_ERROR'); + }); + + it('存在しないユーザーでエラー', async () => { + const response = await request(app) + .post('/auth/login') + .send({ + email: 'nonexistent@example.com', + password: 'password123' + }); + + expect(response.status).toBe(401); + expect(response.body.error.code).toBe('INVALID_CREDENTIALS'); + }); + + it('パスワード間違いでエラー', async () => { + const response = await request(app) + .post('/auth/login') + .send({ + email: 'test@example.com', + password: 'wrongpassword' + }); + + expect(response.status).toBe(401); + expect(response.body.error.code).toBe('INVALID_CREDENTIALS'); + }); +}); +``` + +**境界値テスト** +```typescript +describe('POST /auth/login - 境界値', () => { + it('最小文字数パスワードでテスト', async () => { + // 8文字（最小要件） + const response = await request(app) + .post('/auth/login') + .send({ + email: 'test@example.com', + password: '12345678' + }); + + expect(response.status).toBe(200); + }); + + it('最大文字数メールアドレスでテスト', async () => { + // 255文字（最大要件） + const longEmail = 'a'.repeat(243) + '@example.com'; + const response = await request(app) + .post('/auth/login') + .send({ + email: longEmail, + password: 'password123' + }); + + expect(response.status).toBe(400); + }); +}); +``` + +### UIコンポーネントテストケース + +#### LoginForm コンポーネント + +**レンダリングテスト** +```typescript +import { render, screen } from '@testing-library/react'; +import { LoginForm } from './LoginForm'; + +describe('LoginForm', () => { + it('必要な要素が表示される', () => { + render(); + + expect(screen.getByLabelText('メールアドレス')).toBeInTheDocument(); + expect(screen.getByLabelText('パスワード')).toBeInTheDocument(); + expect(screen.getByRole('button', { name: 'ログイン' })).toBeInTheDocument(); + }); + + it('初期状態でエラーメッセージが非表示', () => { + render(); + + expect(screen.queryByText(/エラー/)).not.toBeInTheDocument(); + }); +}); +``` + +**ユーザーインタラクションテスト** +```typescript +import { render, screen, fireEvent, waitFor } from '@testing-library/react'; +import userEvent from '@testing-library/user-event'; + +describe('LoginForm - ユーザーインタラクション', () => { + it('フォーム送信時にonSubmitが呼ばれる', async () => { + const mockSubmit = jest.fn(); + render(); + + await userEvent.type(screen.getByLabelText('メールアドレス'), 'test@example.com'); + await userEvent.type(screen.getByLabelText('パスワード'), 'password123'); + await userEvent.click(screen.getByRole('button', { name: 'ログイン' })); + + expect(mockSubmit).toHaveBeenCalledWith({ + email: 'test@example.com', + password: 'password123' + }); + }); + + it('バリデーションエラー時に送信されない', async () => { + const mockSubmit = jest.fn(); + render(); + + await userEvent.click(screen.getByRole('button', { name: 'ログイン' })); + + expect(mockSubmit).not.toHaveBeenCalled(); + expect(screen.getByText('メールアドレスは必須です')).toBeInTheDocument(); + }); +}); +``` + +### サービス層テストケース + +#### AuthService 単体テスト + +```typescript +import { AuthService } from './auth.service'; +import { UserRepository } from './user.repository'; + +jest.mock('./user.repository'); + +describe('AuthService', () => { + let authService: AuthService; + let mockUserRepository: jest.Mocked; + + beforeEach(() => { + mockUserRepository = new UserRepository() as jest.Mocked; + authService = new AuthService(mockUserRepository); + }); + + describe('login', () => { + it('有効な認証情報でユーザー情報とトークンを返す', async () => { + const mockUser = { + id: '1', + email: 'test@example.com', + hashedPassword: 'hashed_password' + }; + + mockUserRepository.findByEmail.mockResolvedValue(mockUser); + jest.spyOn(authService, 'verifyPassword').mockResolvedValue(true); + jest.spyOn(authService, 'generateToken').mockReturnValue('mock_token'); + + const result = await authService.login('test@example.com', 'password'); + + expect(result).toEqual({ + user: { id: '1', email: 'test@example.com' }, + token: 'mock_token' + }); + }); + + it('存在しないユーザーでエラーをスロー', async () => { + mockUserRepository.findByEmail.mockResolvedValue(null); + + await expect( + authService.login('nonexistent@example.com', 'password') + ).rejects.toThrow('Invalid credentials'); + }); + }); +}); +``` + +## パフォーマンステストケース + +### 負荷テスト + +```typescript +describe('パフォーマンステスト', () => { + it('ログインAPI - 100同時接続テスト', async () => { + const promises = Array.from({ length: 100 }, () => + request(app).post('/auth/login').send(validCredentials) + ); + + const startTime = Date.now(); + const responses = await Promise.all(promises); + const endTime = Date.now(); + + // 全てのリクエストが成功 + responses.forEach(response => { + expect(response.status).toBe(200); + }); + + // 応答時間が5秒以内 + expect(endTime - startTime).toBeLessThan(5000); + }); + + it('データベース - 大量データ検索性能', async () => { + // 1000件のテストデータを作成 + await createTestData(1000); + + const startTime = Date.now(); + const response = await request(app) + .get('/users') + .query({ limit: 100, offset: 0 }); + const endTime = Date.now(); + + expect(response.status).toBe(200); + expect(endTime - startTime).toBeLessThan(1000); // 1秒以内 + }); +}); +``` + +### セキュリティテスト + +```typescript +describe('セキュリティテスト', () => { + it('SQLインジェクション対策', async () => { + const maliciousInput = "'; DROP TABLE users; --"; + + const response = await request(app) + .post('/auth/login') + .send({ + email: maliciousInput, + password: 'password' + }); + + // システムが正常に動作し、データベースが破損していない + expect(response.status).toBe(400); + + // ユーザーテーブルが依然として存在することを確認 + const usersResponse = await request(app) + .get('/users') + .set('Authorization', 'Bearer ' + validToken); + expect(usersResponse.status).not.toBe(500); + }); + + it('XSS対策', async () => { + const xssPayload = ''; + + const response = await request(app) + .post('/users') + .set('Authorization', 'Bearer ' + validToken) + .send({ + name: xssPayload, + email: 'test@example.com' + }); + + // レスポンスでスクリプトがエスケープされている + expect(response.body.data.name).not.toContain('