tomevault-io 設計書の評価と改善
設計書（docs/design/*.md）を作成・更新した直後に実行する。
設計書の品質を100点満点で自己評価し、不足点を特定・改善し、最終的に矛盾や漏れがないことを確認する。
ultrathink
Phase 1: 設計書の読み込みと現状把握
Step 1-1: 対象の特定
引数で指定された設計書、または直前に作成・更新した設計書を特定する。
# 引数がない場合、最近変更された設計書を特定
git diff --name-only HEAD~3 -- docs/design/
Step 1-2: 設計書の全文読み込み
対象の設計書を全文読み込む。同時に、関連するソースコードも確認する。
確認対象:
- 設計書本体（
docs/design/<feature>.md） - 対応する実装計画書（
docs/impl/<feature>.md）があれば参照 - 関連するソースコード（
src/配下）
Phase 2: 100点満点の自己評価
以下の10カテゴリ × 10点満点で評価する。各カテゴリの採点基準に従い、厳密に採点すること。
評価カテゴリ
| # | カテゴリ | 配点 | 評価観点 |
|---|---|---|---|
| 1 | 基本構造 | 10点 | 必須セクション（概要・API設計・実装詳細・テスト・セキュリティ）が揃っているか |
| 2 | 目的・スコープの明確性 | 10点 | 何を実装するか、何を実装しないかが明確か。読み手が迷わないか |
| 3 | API設計の完全性 | 10点 | シグネチャ、型定義、オプション、戻り値が網羅されているか |
| 4 | Streamlitとの比較 | 10点 | Streamlit対応APIとの差分・優位性・未対応項目が明記されているか |
| 5 | 内部アーキテクチャ | 10点 | ファイル構成、クラス設計、データフロー等が記述されているか |
| 6 | エッジケース・異常系 | 10点 | 境界条件、エラー処理、不正入力への対処が考慮されているか |
| 7 | テスト戦略 | 10点 | ユニットテスト・E2Eテストの方針と具体的なテストケースがあるか |
| 8 | セキュリティ考慮 | 10点 | XSS、入力検証、機密データ、認証認可等が検討されているか |
| 9 | 技術選定の根拠 | 10点 | Web標準API・Honoの活用方針、採用・不採用の理由が明記されているか |
| 10 | 実装計画 | 10点 | Phase/Iteration分割、ファイル構成、依存関係が具体的か |
採点基準（各カテゴリ共通）
| 点数 | 基準 |
|---|---|
| 9-10 | 完璧。追加すべき内容がない |
| 7-8 | 良好。軽微な追記で完成する |
| 5-6 | 普通。重要な情報が一部欠けている |
| 3-4 | 不十分。大幅な追記が必要 |
| 1-2 | 骨格のみ。ほぼ未記述 |
| 0 | セクション自体が存在しない |
Step 2-1: 採点の実施
各カテゴリを採点し、以下のフォーマットで結果を出力する:
## 自己評価結果
| # | カテゴリ | 点数 | 評価コメント |
|---|---------|------|-------------|
| 1 | 基本構造 | X/10 | ... |
| 2 | 目的・スコープの明確性 | X/10 | ... |
| 3 | API設計の完全性 | X/10 | ... |
| 4 | Streamlitとの比較 | X/10 | ... |
| 5 | 内部アーキテクチャ | X/10 | ... |
| 6 | エッジケース・異常系 | X/10 | ... |
| 7 | テスト戦略 | X/10 | ... |
| 8 | セキュリティ考慮 | X/10 | ... |
| 9 | 技術選定の根拠 | X/10 | ... |
| 10 | 実装計画 | X/10 | ... |
| | **合計** | **XX/100** | |
Step 2-2: 重要度による分類
8点未満のカテゴリを改善対象として抽出し、優先度を付ける:
- Critical（0-4点）: 設計書として機能しない。即座に対応が必要
- Major（5-6点）: 実装着手に支障あり。改善が強く推奨される
- Minor（7点）: 品質向上のため推奨。なくても実装は可能
Phase 3: 改善タスクリストの作成と設計書の更新
Step 3-1: タスクリストの作成
Phase 2の評価結果からタスクリストを作成する。TodoWriteツールを使用してタスクを管理する。
タスクの粒度:
- 1タスク = 設計書の1セクションの追加・改善
- 具体的に何を書くかまで記述する（例: 「セキュリティセクションにXSS対策を追記」）
Step 3-2: タスクの実行（設計書の更新）
タスクリストに従い、設計書を更新する。
更新ルール:
- 既存の記述は尊重する: 矛盾がない限り既存内容を変更しない
- セクションの追加: 不足しているセクションは既存設計書のフォーマットに合わせて追加
- 具体性を重視: 抽象的な記述より、コード例・型定義・テーブルを含む具体的な記述
- 実装コードとの整合性: ソースコードが既に存在する場合、実装と一致させる
- 日本語で記述: 開発ドキュメントは日本語
Step 3-3: 各タスク完了後の確認
タスクを1つ完了するごとに:
- 該当セクションを再読して自然な文章になっているか確認
- 前後のセクションとの整合性を確認
- TodoWriteでタスクを完了済みにする
Phase 4: 最終検証（矛盾・収載漏れチェック）
設計書の更新が完了したら、全文を再読して以下を検証する。
Step 4-1: 内部一貫性チェック
- API設計セクションの型定義と、テストセクションのテストコードで使用されている型が一致しているか
- 概要セクションで述べたスコープと、実装計画でカバーされている範囲が一致しているか
- Streamlit比較表の「対応状況」と、API設計セクションの記述が矛盾していないか
- ファイル構成が実装詳細・実装計画の両方で一致しているか
- コード例のimport文やAPI呼び出しが、型定義セクションと整合しているか
Step 4-2: 収載漏れチェック
- 全APIメソッドに型定義が記載されているか
- 全APIメソッドに使用例が記載されているか
- オプションパラメータのデフォルト値が明記されているか
- エラー時の挙動が記載されているか
- 将来拡張として言及されている機能がPhase分割に含まれているか
Step 4-3: ソースコードとの整合性
既に実装が存在する場合:
- 型名が
src/のソースコードと一致しているか - 関数シグネチャがソースコードと一致しているか
- デフォルト値がソースコードと一致しているか
- ファイルパスが実際のディレクトリ構造と一致しているか
Step 4-4: 問題が見つかった場合
矛盾や漏れが見つかった場合:
- 問題箇所を特定する
- 設計書を修正する
- 再度 Step 4-1 〜 4-3 を実行する
問題がなくなるまで繰り返す（最大3回）。
Phase 5: 評価結果の報告
最終的な評価結果をユーザーに報告する。
報告フォーマット:
## 設計書評価レポート: <設計書名>
### 初回評価: XX/100点
### 改善後評価: YY/100点
### 改善内容
- <改善1>
- <改善2>
- ...
### 最終検証結果
- 内部一貫性: ✅ / ⚠️（詳細）
- 収載漏れ: ✅ / ⚠️（詳細）
- ソースコード整合性: ✅ / ⚠️（詳細） / N/A（未実装）
注意事項
- 設計書が存在しない場合は、既存設計書（
docs/design/cache-api.md等）のフォーマットに従って新規作成を提案する - 甘い採点は禁止。実装に必要な情報が欠けていれば容赦なく減点する
- 評価は設計書の「実装着手に十分な情報があるか」を基準とする
- 100点は理想的な状態であり、90点以上であれば実装着手可能と判断する
- 90点未満の場合は、実装着手前に設計書の改善が必要であることを明確に伝える
Converted and distributed by TomeVault — claim your Tome and manage your conversions.