zhongwei/gh-classmethod-tsumiki
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
master
gh-classmethod-tsumiki/commands/rev-requirements.md
Zhongwei Li b3ad2e3943 Initial commit
2025-11-29 18:09:29 +08:00

12 KiB
Raw Permalink Blame History

description
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 として保存

出力フォーマット例

# {プロジェクト名} 要件定義書（逆生成）

## 分析概要

**分析日時**: {実行日時}
**対象コードベース**: {パス}
**抽出要件数**: {機能要件数}個の機能要件、{非機能要件数}個の非機能要件
**信頼度**: {分析の信頼度} % （実装カバレッジに基づく）

## システム概要

### 推定されたシステム目的
{実装された機能から推測されるシステムの目的}

### 対象ユーザー
{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. 権限・ロール実装 → ユーザー種別

実行コマンド例

# フル分析（全要件抽出）
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

実行後の確認

  • 抽出された要件数（機能要件・非機能要件）を表示
  • 分析の信頼度と根拠の強さを報告
  • 推定が困難な要件や確認が必要な項目を提示
  • ステークホルダー確認のための質問リストを生成
  • 次の推奨アクション（テスト追加、ドキュメント整備等）を提案
Reference in New Issue View Git Blame Copy Permalink