update-design

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

設計書の評価と改善

設計書（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/requirements.md）との整合性
• 関連するソースコード（src/ 配下）

---

Phase 2: 100点満点の自己評価

以下の10カテゴリ × 10点満点で評価する。各カテゴリの採点基準に従い、厳密に採点すること。

評価カテゴリ

#	カテゴリ	配点	評価観点
1	基本構造	10点	必須セクション（概要・変換仕様・実装詳細・テスト・エラー処理）が揃っているか
2	目的・スコープの明確性	10点	何を実装するか、何を実装しないかが明確か。読み手が迷わないか
3	変換ロジックの完全性	10点	SKILL.md→POWER.md変換の仕様が網羅されているか。frontmatter→frontmatter、body→steering、resources→resourcesのマッピングが明記されているか
4	CLI設計	10点	Commanderコマンド・オプション設計（convert、--overwrite、--dry-run、--keywords、--mcp-template、--no-resources）が明記されているか
5	内部アーキテクチャ	10点	ファイル構成（types/helpers/converter/cli/index）、モジュール間のデータフローが記述されているか
6	エッジケース・異常系	10点	境界条件（空SKILL.md、既存出力ディレクトリ、不正frontmatter、日本語ファイル名）への対処が考慮されているか
7	テスト戦略	10点	ユニットテストの方針と具体的なテストケース（helpers純関数テスト、converter tmpディレクトリテスト）があるか
8	キーワード抽出設計	10点	英語トークナイズ（ストップワード除去）、日本語候補抽出、頻度分析、上限制御の仕様が明記されているか
9	技術選定の根拠	10点	Commander, gray-matter, fs-extra, YAML等の採用理由が明記されているか
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 | 変換ロジックの完全性 | X/10 | ... |
| 4 | CLI設計 | 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セクションの追加・改善
• 具体的に何を書くかまで記述する（例: 「キーワード抽出セクションに日本語トークナイズの仕様を追記」）

Step 3-2: タスクの実行（設計書の更新）

タスクリストに従い、設計書を更新する。

更新ルール:

• 既存の記述は尊重する: 矛盾がない限り既存内容を変更しない
• セクションの追加: 不足しているセクションは既存設計書のフォーマットに合わせて追加
• 具体性を重視: 抽象的な記述より、コード例・型定義・テーブルを含む具体的な記述
• 実装コードとの整合性: ソースコードが既に存在する場合、実装と一致させる
• 日本語で記述: 開発ドキュメントは日本語

Step 3-3: 各タスク完了後の確認

タスクを1つ完了するごとに:

1. 該当セクションを再読して自然な文章になっているか確認
2. 前後のセクションとの整合性を確認
3. TodoWriteでタスクを完了済みにする

---

Phase 4: 最終検証（矛盾・収載漏れチェック）

設計書の更新が完了したら、全文を再読して以下を検証する。

Step 4-1: 内部一貫性チェック

• 型定義（src/types.ts）と設計書の型名が一致しているか
• 概要セクションで述べたスコープと、実装計画でカバーされている範囲が一致しているか
• 要件定義書（docs/requirements.md）の機能スコープと、設計書の記述が矛盾していないか
• ファイル構成が実装詳細・実装計画の両方で一致しているか
• CLIオプション（src/cli.ts）と設計書のオプション定義が一致しているか

Step 4-2: 収載漏れチェック

• 全CLIオプション（--overwrite, --dry-run, --keywords, --mcp-template, --no-resources）の仕様が記載されているか
• 変換フロー（SKILL.md読込→POWER.md生成→steering生成→resources複製→manifest出力）が記載されているか
• キーワード抽出の3段階フォールバック（forced→frontmatter→auto-extract）が記載されているか
• エラー時の挙動（SKILL.md不在、出力先既存、mcpテンプレ不在）が記載されているか
• 将来拡張として言及されている機能がPhase分割に含まれているか

Step 4-3: ソースコードとの整合性

既に実装が存在する場合:

• 型名が src/types.ts のソースコードと一致しているか
• 関数シグネチャ（src/helpers.ts, src/converter.ts）がソースコードと一致しているか
• デフォルト値がソースコードと一致しているか
• ファイルパスが実際のディレクトリ構成と一致しているか

Step 4-4: 問題が見つかった場合

矛盾や漏れが見つかった場合:

1. 問題箇所を特定する
2. 設計書を修正する
3. 再度 Step 4-1 〜 4-3 を実行する

問題がなくなるまで繰り返す（最大3回）。

---

Phase 5: 評価結果の報告

最終的な評価結果をユーザーに報告する。

報告フォーマット:

## 設計書評価レポート: <設計書名>

### 初回評価: XX/100点
### 改善後評価: YY/100点

### 改善内容
- <改善1>
- <改善2>
- ...

### 最終検証結果
- 内部一貫性: ✅ / ⚠️（詳細）
- 収載漏れ: ✅ / ⚠️（詳細）
- ソースコード整合性: ✅ / ⚠️（詳細） / N/A（未実装）

---

注意事項

• 設計書が存在しない場合は、既存の要件定義書（docs/requirements.md）のフォーマットを参考に新規作成を提案する
• 甘い採点は禁止。実装に必要な情報が欠けていれば容赦なく減点する
• 評価は設計書の「実装着手に十分な情報があるか」を基準とする
• 100点は理想的な状態であり、90点以上であれば実装着手可能と判断する

---