# 変更管理方針（Change Management Policy）

**文書番号:** PM-005  
**バージョン:** 1.0  
**作成日:** 2025-11-03  
**最終更新:** 2025-11-03

---

## 1. 目的

本文書は、Tree-sitter Analyzerプロジェクトにおける変更管理の方針を定義し、PMP準拠ドキュメントとOpenSpecの適切な使い分けを明確化する。

---

## 2. 変更管理の基本原則

### 2.1 二層管理アプローチ

本プロジェクトは、**戦略層（PMP）**と**戦術層（OpenSpec）**の二層構造で変更を管理する。

```
┌─────────────────────────────────────────────┐
│    戦略層：PMP準拠ドキュメント                │
│    プロジェクト全体の方向性・品質基準         │
│    更新頻度：四半期 / 重大変更時              │
└─────────────────────────────────────────────┘
                    ↓
┌─────────────────────────────────────────────┐
│    戦術層：OpenSpec                          │
│    個別機能の変更・実装管理                   │
│    更新頻度：継続的（開発サイクルに同期）     │
└─────────────────────────────────────────────┘
                    ↓
┌─────────────────────────────────────────────┐
│    実装層：コード・テスト・詳細ドキュメント   │
│    日々の開発作業                            │
└─────────────────────────────────────────────┘
```

---

## 3. 管理手法の使い分け

### 3.1 PMP準拠ドキュメントで管理すべき変更

#### 📊 対象変更
- ✅ プロジェクト全体の方向性変更
- ✅ 品質基準の大幅変更
- ✅ 技術スタック・アーキテクチャの重大変更
- ✅ ステークホルダー体制の変更
- ✅ 新しいドキュメントカテゴリの追加
- ✅ ドキュメント体系全体の再構築

#### 📝 管理対象ドキュメント
- `docs/ja/project-management/00_プロジェクト憲章.md` (PM-001)
- `docs/ja/project-management/01_スコープ定義書.md` (PM-002)
- `docs/ja/project-management/02_WBS.md` (PM-003)
- `docs/ja/project-management/03_品質管理計画.md` (PM-004)
- `docs/ja/test-management/00_テスト戦略.md` (TEST-001)
- `docs/ja/test-management/01_テストケース一覧.md` (TEST-002)

#### 📅 更新タイミング
- **四半期レビュー**：3ヶ月ごとの定期見直し
- **マイルストーン達成時**：v2.0リリースなど
- **重大変更時**：即座に更新

#### ✍️ 更新プロセス
1. 変更提案（Issue作成）
2. 影響分析（スコープ、品質、リソース）
3. レビュー・承認（プロジェクトオーナー）
4. ドキュメント更新
5. チーム周知

---

### 3.2 OpenSpecで管理すべき変更

#### 🚀 対象変更
- ✅ 新機能追加
- ✅ 既存機能の変更・改善
- ✅ 重要なバグ修正
- ✅ リファクタリング
- ✅ パフォーマンス最適化
- ✅ 新言語サポート追加
- ✅ API変更

#### 📝 OpenSpecワークフロー
```bash
# 1. 変更提案
openspec propose <change-id>

# 2. 詳細設計
# - proposal.md: 目的、価値、影響範囲
# - design.md: アーキテクチャ、技術選定
# - specs/: 詳細要件
# - tasks.md: 実装タスク

# 3. レビュー・承認
openspec validate <change-id> --strict

# 4. 実装
# コード変更、テスト追加

# 5. 完了後
openspec show <change-id>
# → 必要に応じてPMPドキュメント更新
```

#### 📅 更新タイミング
- **継続的**：開発サイクルに同期
- **機能開発ごと**：新機能、改善、修正

---

### 3.3 どちらでも管理しない変更

以下は、Issue/PRのみで管理し、正式な変更管理プロセスは不要：

- ❌ 誤字脱字の修正
- ❌ コメントの改善
- ❌ コードフォーマット
- ❌ 軽微なドキュメント改善
- ❌ 依存関係の定期アップデート（セキュリティ以外）

---

## 4. 判断フローチャート

### 4.1 変更の影響範囲による判断

```
変更を検討
    │
    ▼
プロジェクト全体に影響？
    │
    ├─ Yes → PMP準拠ドキュメント更新
    │         ├─ プロジェクト憲章
    │         ├─ スコープ定義
    │         ├─ WBS
    │         └─ 品質管理計画
    │
    └─ No → 特定機能に影響？
              │
              ├─ Yes → OpenSpec
              │         └─ openspec propose
              │
              └─ No → Issue/PR
                       └─ 直接実装
```

### 4.2 具体例による判断基準

| 変更内容 | 管理手法 | 理由 |
|---------|---------|------|
| 新言語サポート（Ruby） | OpenSpec | 明確な機能追加、実装タスクが具体的 |
| ドキュメント体系再構築 | PMP | プロジェクト全体の管理方法の変更 |
| パフォーマンス最適化 | OpenSpec | 技術的改善、測定可能な目標 |
| 品質基準変更（カバレッジ目標90%） | PMP | 全体の品質方針に影響 |
| バグ修正（パストラバーサル） | OpenSpec | 重要な機能修正、設計影響あり |
| README誤字修正 | なし（PR） | 軽微な変更 |
| 新MCPツール追加 | OpenSpec | 機能追加、API変更 |
| CI/CD改善 | OpenSpec | インフラ改善、明確なタスク |
| プロジェクト目標変更 | PMP | 戦略的方向性の変更 |
| テストケース追加 | なし（PR） | 日常的な品質向上活動 |

---

## 5. 統合管理プロセス

### 5.1 OpenSpec完了時のPMP更新

OpenSpecで管理した変更が完了したら、必要に応じてPMPドキュメントを更新：

**チェックリスト：**
- [ ] WBSの完了状況を更新
- [ ] テストケース一覧に新規テストを追加
- [ ] 品質メトリクスを記録
- [ ] スコープ定義書に新機能を反映（重要な場合）

**例：Ruby言語サポート追加完了時**
```markdown
# 更新箇所
1. WBS (PM-003)
   - 1.2.3 「将来の言語拡張」セクション
   - 1.2.3.5 「Rubyプラグイン」項目追加・完了マーク

2. テストケース一覧 (TEST-002)
   - Rubyプラグインテスト（80+ケース）追加

3. スコープ定義書 (PM-002)
   - サポート言語リストに「Ruby（完全サポート）」追加
```

### 5.2 四半期レビュープロセス

**実施時期：** 四半期末（3月、6月、9月、12月）

**レビュー内容：**

#### Phase 1: 達成状況の評価
```bash
# 1. OpenSpecの変更履歴レビュー
openspec list --status merged --since "3 months ago"

# 2. 主要メトリクスの確認
- テスト数の推移
- カバレッジの推移
- 新機能の数
- バグ修正の数
```

#### Phase 2: PMPドキュメント更新
- [ ] プロジェクト憲章：マイルストーン達成状況
- [ ] スコープ定義書：機能グループの追加・変更
- [ ] WBS：完了作業の記録、新規作業の追加
- [ ] 品質管理計画：KPI達成状況、品質基準の調整
- [ ] テスト戦略：テストアプローチの改善

#### Phase 3: 次期計画
- [ ] 次四半期の目標設定
- [ ] 優先順位の見直し
- [ ] リソース配分の調整

---

## 6. 役割と責任

### 6.1 変更管理の役割

| 役割 | 責任 | 担当者 |
|------|------|--------|
| **プロジェクトオーナー** | PMP変更の最終承認 | aisheng.yu |
| **開発リード** | OpenSpec変更の承認 | コアメンバー |
| **QAリード** | 品質基準変更の承認 | QAチーム |
| **開発者** | OpenSpecベースの実装 | 全開発者 |
| **ドキュメント管理者** | ドキュメント整合性維持 | 全メンバー |

### 6.2 承認権限

| 変更タイプ | 承認者 | 承認プロセス |
|-----------|--------|-------------|
| **PMP重大変更** | プロジェクトオーナー | Issue + レビュー + 承認 |
| **PMP軽微変更** | 開発リード | レビュー + 承認 |
| **OpenSpec機能追加** | 開発リード + 1名 | PR + 2承認 |
| **OpenSpec改善** | 開発リード | PR + 1承認 |
| **日常的変更** | レビュアー1名 | PR + 1承認 |

---

## 7. 実践例

### 例1: 新言語サポート追加（Ruby）

#### Step 1: PMPレベルでの確認
```markdown
1. スコープ定義書 (PM-002) 確認
   - 「1.2 言語サポート」に言語追加は In-Scope
   - ✅ プラグインアーキテクチャで対応可能

2. WBS (PM-003) 確認
   - 「1.2.3 将来の言語拡張（計画中）」セクションに作業追加
   - 1.2.3.5として「Rubyプラグイン」項目を追加

3. 品質管理計画 (PM-004) 確認
   - テスト基準：カバレッジ > 80%
   - 新言語テストケース作成必須
```

#### Step 2: OpenSpecで詳細化
```bash
openspec propose add-ruby-language-support

# proposal.md を作成
## 目的
Rubyコミュニティからの要望に応え、Rails開発者の支援

## ユーザー価値
- Ruby/Rails開発者がTree-sitter Analyzerを利用可能に
- Rubyエコシステムへの貢献

## 影響範囲
- 新規プラグイン追加
- 既存システムへの影響なし

# design.md を作成
## アーキテクチャ
- 既存のLanguagePluginインターフェース実装
- tree-sitter-rubyライブラリ統合

# specs/ruby-parser/spec.md を作成
## 要件
- Rubyクラス、メソッド抽出
- ブロック、yield対応
- メタプログラミング対応

# tasks.md を作成
- [ ] tree-sitter-ruby統合
- [ ] RubyPluginクラス実装
- [ ] テストケース作成（80+件）
- [ ] サンプルコード追加
- [ ] ドキュメント更新
```

#### Step 3: 実装・テスト

#### Step 4: 完了後のPMP更新
```markdown
1. WBS (PM-003) 更新
   - 1.2.3 「将来の言語拡張」セクション
   - 1.2.3.5 「Rubyプラグイン」✅ 完了

2. スコープ定義書 (PM-002) 更新
   - サポート言語リストに「Ruby（完全サポート）」追加

3. テストケース一覧 (TEST-002) 更新
   - Rubyプラグインテスト（85ケース）追加
```

---

### 例2: ドキュメント体系再構築

#### Step 1: PMP変更として管理
```markdown
理由：
- プロジェクト全体の管理方法に影響
- 複数のPMPドキュメントを新規作成
- 長期的な品質保証の枠組み変更

管理方法：
- Issue作成：「PMP準拠のドキュメント体系構築」
- 影響分析：全ステークホルダー、ドキュメント管理プロセス
- 承認：プロジェクトオーナー
```

#### Step 2: 実装
```markdown
作成ドキュメント：
- PM-001: プロジェクト憲章
- PM-002: スコープ定義書
- PM-003: WBS
- PM-004: 品質管理計画
- PM-005: 変更管理方針（本文書）
- SPEC-001: システム概要
- TEST-001: テスト戦略
- TEST-002: テストケース一覧
```

#### Step 3: レビュー・承認・適用

---

### 例3: パフォーマンス最適化

#### Step 1: PMPレベルでの確認
```markdown
1. 品質管理計画 (PM-004) 確認
   - 非機能要件：10,000行/秒
   - 現状：評価必要

2. 目標設定
   - 目標：15,000行/秒（50%向上）
```

#### Step 2: OpenSpecで詳細化
```bash
openspec propose optimize-parser-performance

# proposal.md
## 現状の問題
- 大規模ファイル（50,000行+）の解析が遅い
- キャッシュヒット率が低い（60%）

## 目標
- 解析速度：15,000行/秒
- キャッシュヒット率：90%

# design.md
## アプローチ
1. キャッシュ戦略の改善
   - LRUキャッシュサイズ最適化
   - キャッシュキーの改善

2. 並行処理の強化
   - ファイル単位の並行解析
   - CPU コア数の活用

# tasks.md
- [ ] 現状のプロファイリング
- [ ] キャッシュロジック改善
- [ ] 並行処理実装
- [ ] ベンチマーク実行
- [ ] ドキュメント更新
```

#### Step 3: 完了後のPMP更新
```markdown
1. 品質管理計画 (PM-004) 更新
   - 達成メトリクス：15,000行/秒（目標達成）
   - キャッシュヒット率：92%（目標達成）

2. 次期目標設定
   - 次四半期：20,000行/秒
```

---

## 8. ツールとテンプレート

### 8.1 PMP変更提案テンプレート

```markdown
# PMP変更提案

## 変更概要
[変更内容の簡潔な説明]

## 影響範囲
- [ ] プロジェクト憲章
- [ ] スコープ定義書
- [ ] WBS
- [ ] 品質管理計画
- [ ] テスト戦略

## 変更理由
[なぜこの変更が必要か]

## 期待される効果
[変更による利益]

## リスクと緩和策
[潜在的なリスクと対応]

## 承認
- 提案者：
- レビュアー：
- 承認者：
```

### 8.2 四半期レビューチェックリスト

```markdown
# 四半期レビュー（YYYY-QN）

## Phase 1: 達成状況評価

### OpenSpec変更履歴
- [ ] 完了したchangeの確認
- [ ] 主要な機能追加
- [ ] 重要なバグ修正

### 品質メトリクス
- [ ] テスト数：[現在の数] (前期: [前期の数])
- [ ] カバレッジ：[%] (目標: 80%)
- [ ] テスト合格率：[%] (目標: 100%)
- [ ] mypyエラー：[数] (目標: < 100)

## Phase 2: PMPドキュメント更新

- [ ] プロジェクト憲章：マイルストーン達成状況
- [ ] スコープ定義書：機能追加・変更の反映
- [ ] WBS：完了作業の記録
- [ ] 品質管理計画：KPI達成状況
- [ ] テスト戦略：改善点の反映
- [ ] テストケース一覧：新規テストの追加

## Phase 3: 次期計画

### 目標設定
- [ ] 次四半期の主要目標
- [ ] KPI目標値
- [ ] 優先機能

### リソース計画
- [ ] 重点領域
- [ ] 技術的負債対応

## 承認
- レビュアー：
- 承認者：
- 日付：
```

---

## 9. よくある質問（FAQ）

### Q1: どちらで管理すべきか迷う場合は？

**A:** 以下の基準で判断：
1. **影響範囲**: プロジェクト全体 → PMP、特定機能 → OpenSpec
2. **期間**: 長期的（数ヶ月以上）→ PMP、短期的 → OpenSpec
3. **変更タイプ**: 戦略的 → PMP、戦術的 → OpenSpec

迷ったら、**まずIssueで議論**し、チームで決定する。

---

### Q2: 小さな変更でもOpenSpecは必要？

**A:** 以下の場合はOpenSpec不要：
- 誤字脱字修正
- コメント改善
- 軽微なリファクタリング（機能変更なし）
- 単純なバグ修正（1ファイル、影響小）

**OpenSpecが必要な場合：**
- 複数ファイルにまたがる変更
- API変更
- アーキテクチャ変更
- 新機能追加
- パフォーマンスに影響する変更

---

### Q3: PMPドキュメントの更新を忘れたら？

**A:** 四半期レビュー時に一括更新可能。ただし、**重大な変更は即座更新**を推奨。

---

### Q4: OpenSpecとPMPで矛盾が生じたら？

**A:** **PMPが優先**。OpenSpecはPMPの方針内で実装を管理する手段。
矛盾が生じた場合：
1. PMPドキュメントを確認
2. 必要ならPMP変更を提案
3. OpenSpecを調整

---

## 10. 改訂履歴

| バージョン | 日付       | 変更内容                                                                                                                                                                               | 承認者     |
| ---------- | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
| 1.0        | 2025-11-03 | 初版作成 - PMP/OpenSpec使い分けルール策定                                                                                                                                              | aisheng.yu |
| 1.1        | 2025-11-03 | WBS更新との整合性確保<br>- Ruby例のWBS参照を修正: 「1.2.3.4」→「1.2.3.5」（1.2.3セクション名変更対応）<br>- WBS確認手順を更新: 「基本サポート言語実装」→「将来の言語拡張（計画中）」 | aisheng.yu |

---

## 付録A: クイックリファレンス

### 変更管理の判断基準（1分チェック）

```
□ プロジェクト全体の方向性に影響？ → Yes: PMP
□ 品質基準の変更？ → Yes: PMP
□ 技術スタック変更？ → Yes: PMP
□ 新機能追加？ → Yes: OpenSpec
□ 既存機能の改善？ → Yes: OpenSpec
□ 重要なバグ修正？ → Yes: OpenSpec
□ 軽微な修正？ → No: PR直接
```

### 連絡先
- PMP変更相談：プロジェクトオーナー
- OpenSpec相談：開発リード
- 不明点：Issue作成
