---

name: update-design description: "設計書を作成・更新した後に発動。100点満点で自己評価し、不足点をタスクリストにして設計書を改善。矛盾や収載漏れがないことを最終確認する。"

update-design — 設計書の評価と改善

設計書を作成・更新した後に発動。100点満点で自己評価し、不足点をタスクリストにして設計書を改善。矛盾や収載漏れがないことを最終確認する。

🎯 発動タイミング

以下の作業が完了した後に実行:

• 新規設計書の作成
• 既存設計書の更新・修正
• 要件定義書、API設計書、DB設計書などの作成

---

📋 実行手順

Step 1: 自己評価（100点満点）

設計書を以下の観点で評価し、点数をつける:

評価項目	配点	チェック内容
完全性	25点	必要な情報がすべて記載されているか
一貫性	25点	用語・形式・命名規則が統一されているか
明確性	20点	曖昧な表現がなく、具体的に書かれているか
整合性	20点	他のドキュメントや実装と矛盾がないか
可読性	10点	構造が整理され、読みやすいか

評価フォーマット・改善タスクリストフォーマット・最終確認チェックリスト・使用例は references/template-evaluation.md を参照。

Step 2: 不足点のタスクリスト化

評価で見つかった不足点を具体的なタスクに変換（テンプレート参照）。

Step 3: 改善の実施

タスクリストに基づいて設計書を修正:

• 1タスクずつ対応
• 対応完了したらチェックを入れる
• 大きな変更は差分を明示

Step 4: 最終確認チェックリスト

改善後、矛盾チェック・収載漏れチェック・フォーマットチェック・メタ情報チェックを実施（テンプレート参照）。

---

🔄 評価基準の詳細

完全性（25点）

必須項目の確認:

• 目的・背景
• スコープ（対象範囲と対象外）
• 前提条件・制約
• 用語定義
• 詳細設計
• エラーハンドリング
• 非機能要件（該当する場合）

一貫性（25点）

チェックポイント:

• 同じ概念に同じ用語を使用
• 日付形式の統一（YYYY-MM-DD等）
• コード例の言語・スタイル統一
• 図表の番号付けルール統一

明確性（20点）

NG表現の例:

• 「適宜」「必要に応じて」「など」→ 具体的に列挙
• 「大量の」「高速な」→ 数値で定義
• 「〜と思われる」「〜かもしれない」→ 断定または条件明示

整合性（20点）

確認対象:

• 他の設計書との整合
• 実装コードとの整合
• 外部API仕様との整合
• チーム内の設計規約との整合

可読性（10点）

改善ポイント:

• 1段落は3-5文以内
• 長いリストは分類してグループ化
• 複雑な条件は表やフローチャートで表現
• 適切な見出しレベルの使用

---

📊 評価結果の目安

点数	評価	アクション
90-100	優秀	軽微な修正後、レビュー依頼可能
70-89	良好	タスクリスト対応後、再評価
50-69	要改善	大幅な加筆・修正が必要
0-49	不十分	構成から見直しが必要

---

💡 Tips

• 80点以上を目指す: 最初から100点は難しい。80点で一旦区切り、レビューで改善
• 差分を残す: 大きな変更は git diff やコメントで変更理由を残す
• 繰り返し実行: 改善後も再度このスキルを実行して品質向上
• チーム共有: 評価基準をチームで共有し、設計書品質を標準化

⚠️ よくある落とし穴

• 曖昧な表現を見落とす: 「適宜」「必要に応じて」「など」といった表現は具体性が欠如しているが、書いた本人には自然に見えるため自己評価で見落としやすい。明確性の評価では意識的にこれらの表現を検索すること
• 関連ドキュメントとの整合性チェックを省略する: 設計書単体では矛盾がなくても、API仕様書やDB設計書と不整合が生じていることがある。整合性チェックでは必ず関連ドキュメントを開いて突き合わせる
• 改善後の再評価を忘れる: タスクリストを消化しても再評価しないと、修正で新たな矛盾が入り込むことがある。改善後は必ずStep 1からやり直す