213 lines
9.9 KiB
Markdown
213 lines
9.9 KiB
Markdown
# /compact-progress-document: 進捗ドキュメント圧縮コマンド
|
||
|
||
あなたは矛盾解消駆動開発を実践するAIエージェントです。このコマンドは、進捗ドキュメントファイルが大きくなりすぎた際に、情報量を保持したまま文量を削減する圧縮を行います。
|
||
|
||
## 使用方法
|
||
|
||
```bash
|
||
/compact-progress-document # state.ymlから選択
|
||
/compact-progress-document https://github.com/owner/repo/issues/123 # Issue URL指定
|
||
/compact-progress-document 123 # Issue番号指定
|
||
```
|
||
|
||
## 実行フロー
|
||
|
||
### 1. 進捗ドキュメントの理解
|
||
|
||
まず、`/issync:understand-progress`コマンドを内部で呼び出して、進捗ドキュメントを読み込みます。
|
||
|
||
```bash
|
||
/issync:understand-progress <issue_url_or_number>
|
||
```
|
||
|
||
引数が指定されている場合はそのまま渡し、指定されていない場合は引数なしで実行します。
|
||
|
||
### 2. 進捗ドキュメントの読み込みと分析
|
||
|
||
指定された進捗ドキュメントファイルを読み込み、以下を分析してください：
|
||
- 総行数
|
||
- 各セクションの行数
|
||
- 重複している内容
|
||
- 完了済みのPhaseとタスク
|
||
- 解決済みのOpen Questions
|
||
- 矛盾する記述
|
||
|
||
### 3. バージョン比較とprogress-document-template.mdとの比較
|
||
|
||
#### a) バージョンヘッダーの確認
|
||
|
||
進捗ドキュメントの先頭行から、バージョンヘッダーを確認してください：
|
||
```markdown
|
||
<!-- Template Version: N (YYYY-MM-DD) -->
|
||
```
|
||
|
||
**バージョンヘッダーが存在しない場合**:
|
||
```
|
||
⚠️ 進捗ドキュメントにバージョンヘッダーがありません。
|
||
Version 1 (2025-10-15) 以前のテンプレートを使用している可能性があります。
|
||
|
||
バージョンヘッダーを追加しますか？ (y/n)
|
||
```
|
||
|
||
承認された場合、以下を追加：
|
||
```markdown
|
||
<!-- Template Version: 1 (2025-10-15) -->
|
||
```
|
||
|
||
#### b) progress-document-template.mdのバージョン取得
|
||
|
||
公式テンプレート（`https://raw.githubusercontent.com/MH4GF/issync/refs/heads/main/docs/progress-document-template.md`）を取得し、バージョンヘッダーを確認してください。
|
||
|
||
#### c) バージョン比較
|
||
|
||
進捗ドキュメントのバージョンと、progress-document-template.mdのバージョンを比較してください：
|
||
|
||
**バージョンが同じ場合**: 通常の圧縮処理を続行
|
||
|
||
**バージョンが古い場合**: マイグレーション提案を表示
|
||
```
|
||
⚠️ 進捗ドキュメントのバージョンが古い可能性があります
|
||
現在のバージョン: Version [X] ([YYYY-MM-DD])
|
||
最新のバージョン: Version [Y] ([YYYY-MM-DD])
|
||
|
||
マイグレーションが必要です。
|
||
詳細: docs/MIGRATION_GUIDE.md または https://raw.githubusercontent.com/MH4GF/issync/refs/heads/main/docs/MIGRATION_GUIDE.md
|
||
|
||
マイグレーションを実行しますか？ (y/n)
|
||
```
|
||
|
||
**マイグレーション実行時**:
|
||
1. MIGRATION_GUIDE.mdを参照（ローカルに存在すればローカル、なければGitHubから取得）
|
||
2. 該当するバージョン間のマイグレーション手順を確認
|
||
3. 自動マイグレーション可能な変更を適用
|
||
4. 手動確認が必要な変更をユーザーに通知
|
||
|
||
#### d) テンプレート準拠性の確認
|
||
|
||
以下を確認・修正してください：
|
||
- セクション順序がテンプレートと一致しているか → 不一致の場合は並び替え
|
||
- 各セクションの「📝 記入タイミング」「✍️ 記入内容」ガイダンスがテンプレートと完全一致しているか → 不一致の場合はテンプレートの文言に更新
|
||
- 不要なカスタムセクションがないか → **テンプレートに存在しないセクションは削除**（内容が重要な場合は適切なセクションに統合）
|
||
|
||
**テンプレート準拠の価値**:
|
||
ガイダンスをテンプレートと完全一致させることで、AIエージェントが「今何を書くべきか」を迷わず判断できるようになり、作業効率が大幅に向上します。カスタムセクションの削除により、情報の一元化とメンテナンス性が改善されます。
|
||
|
||
### 4. 圧縮処理
|
||
|
||
以下の観点で圧縮を実行してください：
|
||
|
||
#### a) テンプレート準拠性の修正（最優先）
|
||
- **セクション順序をテンプレートに合わせる**: 並び順が異なる場合は、テンプレート通りの順序に並び替え
|
||
- **ガイダンス文言をテンプレートと完全一致させる**: 「📝 記入タイミング」「✍️ 記入内容」の文言をテンプレートからコピーして上書き（内容の微妙な差異も統一）
|
||
- **不要なカスタムセクションを削除**: テンプレートに存在しないセクションは削除し、重要な内容は適切なセクションに統合
|
||
- **ガイダンスに沿わない記述を適切なセクションに移動**: 例えば「Specification」に書くべき内容が「Purpose」に書かれている場合は移動
|
||
|
||
#### b) 重複情報の削減
|
||
- 同じ内容が複数セクションで繰り返されている場合、参照形式に変換
|
||
- 例: 「詳細はSpecificationセクション参照」
|
||
|
||
#### c) 解決済みOpen Questionsの整理
|
||
- ✅ 解決済みマークのついたOpen Questionsを「解決済み（アーカイブ）」セクションに移動
|
||
- または、Decision Logへの参照のみ残して削除
|
||
|
||
#### d) 完了済みPhaseの簡潔化
|
||
- 完了したPhaseのタスク詳細をOutcomes & Retrospectivesに統合
|
||
- Work Planでは要約のみ残す
|
||
|
||
例:
|
||
```markdown
|
||
### Phase 1: ✅ 完了 (2025-10-14)
|
||
**ゴール**: [簡潔な説明]
|
||
**成果**: Outcomes & Retrospectives 参照
|
||
```
|
||
|
||
#### e) 冗長な説明の簡潔化
|
||
- 長文を箇条書きに変換
|
||
- 過剰に詳細な説明を要約
|
||
- 大きな図表や詳細仕様は外部ファイル化を提案（実行はしない）
|
||
|
||
#### f) 完了済みタスクの整理
|
||
- Tasksセクションから✅完了済みタスクを削除
|
||
- 完了内容はOutcomes & Retrospectivesに統合されているか確認
|
||
|
||
### 5. 矛盾検出と報告
|
||
|
||
以下のような矛盾を検出し、ユーザーに報告してください：
|
||
- Decision Logで矛盾する決定（例: 「A採用」→後で「Bに変更」だが撤回理由が不明確）
|
||
- Work PlanとTasksセクションで内容が一致しない
|
||
- Acceptance CriteriaとValidation & Acceptance Criteriaで基準が異なる
|
||
- Open QuestionsとDecision Logで同じ質問が両方に存在
|
||
|
||
矛盾を発見した場合、Open Questionsに追加する提案をしてください。
|
||
|
||
### 6. 圧縮後の進捗ドキュメントを保存して同期
|
||
|
||
圧縮処理を適用した進捗ドキュメントを保存し、GitHub Issueに同期してください。
|
||
|
||
```bash
|
||
issync push
|
||
```
|
||
|
||
## 出力形式
|
||
|
||
圧縮完了後、以下の形式でレポートを出力してください：
|
||
|
||
```markdown
|
||
## /issync:compact-progress-document 実行結果
|
||
|
||
### バージョン情報
|
||
- 進捗ドキュメント: Version [X] ([YYYY-MM-DD])
|
||
- progress-document-template.md: Version [Y] ([YYYY-MM-DD])
|
||
- マイグレーション: [実施した/不要/スキップ]
|
||
|
||
### 圧縮サマリー
|
||
- 文量: [元の行数]行 → [圧縮後の行数]行（[削減率]%削減）
|
||
- 削除した重複: [件数]箇所
|
||
- 整理したOpen Questions: [件数]件（解決済み）
|
||
- 簡潔化したPhase: Phase [X]（[行数]行 → [行数]行）
|
||
- 完了タスク削除: [件数]件
|
||
|
||
### 適用した圧縮処理
|
||
- ✅ バージョン比較・マイグレーション
|
||
- バージョンヘッダー追加: [実施/不要]
|
||
- テンプレートバージョンアップ: [実施/不要]
|
||
- マイグレーション手順適用: [件数]項目
|
||
- ✅ テンプレート準拠性の修正
|
||
- セクション順序の並び替え: [変更有無]
|
||
- ガイダンス文言の完全一致: [更新したセクション数]箇所
|
||
- カスタムセクション削除: [削除したセクション名]（[件数]件）
|
||
- ✅ 重複情報の削減（[件数]箇所）
|
||
- ✅ 解決済みOpen Questions整理（[件数]件）
|
||
- ✅ 完了Phase簡潔化（Phase [X]）
|
||
- ✅ 冗長な説明の簡潔化（[件数]箇所）
|
||
- ✅ 完了タスク削除（[件数]件）
|
||
|
||
### ⚠️ 矛盾検出
|
||
[矛盾が検出された場合のみ表示]
|
||
- 矛盾1: [詳細な説明]
|
||
- 場所: [セクション名]
|
||
- 推奨対応: [対処方法]
|
||
- 矛盾2: [詳細な説明]
|
||
- 場所: [セクション名]
|
||
- 推奨対応: [対処方法]
|
||
|
||
### 次のアクション
|
||
- [ ] 圧縮結果をレビュー
|
||
- [ ] 矛盾が検出された場合は解消してください
|
||
- [ ] マイグレーションで手動確認が必要な変更を確認してください（該当する場合）
|
||
```
|
||
|
||
## 重要な注意事項
|
||
|
||
1. **バージョン比較を最初に実施**: 進捗ドキュメントのバージョンを必ず確認し、古い場合はマイグレーションを提案すること
|
||
2. **テンプレート準拠が最優先**: セクション順序とガイダンス文言は必ずテンプレートと完全一致させること。これによりAIエージェントの作業効率が大幅に向上する
|
||
3. **カスタムセクションは削除**: テンプレートに存在しないセクションは削除し、重要な内容は適切なセクションに統合すること
|
||
4. **情報量は変えない**: 削減するのは文量のみで、情報は失わないこと
|
||
5. **矛盾は報告のみ**: 矛盾を勝手に解消せず、ユーザーに報告して判断を仰ぐこと
|
||
6. **外部ファイル化は提案のみ**: 大きな図表や詳細仕様の外部ファイル化は実行せず、提案のみ行うこと
|
||
7. **issync同期**: 圧縮完了後は必ず`issync push`を実行してGitHub Issueに同期すること
|
||
|
||
## 実行を開始
|
||
|
||
それでは、上記のフローに従って進捗ドキュメントの圧縮を開始してください。
|