# v1.8 アップデート
Release Date: 2026-02 (予定)
**注**: このバージョンは元々v1.7として計画されていましたが、v1.7で並列実行の検証を優先するため、v1.8に繰り下げました。
## 概要
v1.8 ではパフォーマンス最適化と機能拡張を実施。改善サイクルログの無効化、PRE_COMMIT順序変更によるパフォーマンス向上、および探索のみモード（--only-explore）による調査タスクの効率化を実現。
**パフォーマンス改善**:
- v1.7の並列実行（27-35秒削減）: search_text複数パターン、Read/Grep並列実行
- v1.8独自の最適化（6-9秒削減）: 改善サイクルログ無効化、PRE_COMMIT順序変更
- **合計削減: 33-44秒**（約8-11%高速化）
## 背景
実測データ（session_20260123_160021）から以下のボトルネックが判明：
| フェーズ | 所要時間 | ツール実行 | LLM思考 | 改善余地 |
|---------|----------|----------|---------|---------|
| 準備フェーズ | 117秒 | 11.5秒 (10%) | 105秒 (90%) | 高 |
| EXPLORATIONフェーズ | 52秒 | 0.06秒 (0.1%) | 52秒 (99.9%) | 高 |
| 全体 | 402秒 | 110秒 (27%) | 292秒 (73%) | - |
**主な問題**:
- ツール間のLLM往復で待機時間が発生（1往復 = 2-3秒）
- 逐次実行で並列化できる処理を逐次実行
- 不要なログ記録によるツール呼び出し増加
## 設計原則
### パフォーマンス最適化の3原則
1. **LLM往復の削減**: バッチ化で複数ツールを1往復に統合
2. **並列実行の活用**: 独立した処理は並列実行
3. **適応性の維持**: 速度優先で思考能力を犠牲にしない
### v1.8の実装内容
| 優先度 | 対象 | 削減見込み | 実装難易度 | リスク | 状態 |
|--------|------|----------|------------|--------|------|
| 🔥🔥🔥 | 改善サイクルログ無効化 | 4-6秒 | 低 | 低 | ✅ 完了 |
| 🔥🔥 | PRE_COMMIT順序変更 | 2-3秒 | 中 | 低 | ✅ 完了 |
| 🔥 | 並列実行（v1.7） | **27-35秒** | 低 | 中 | ✅ 実装済み（v1.7） |
| 📦 | 探索のみモード | - | 低 | 低 | ✅ 完了 |
**v1.7の並列実行最適化**（v1.8でも利用可能）:
- EXPLORATION: search_text 複数パターン並列実行（20秒削減）
- READY: Read/Grep 並列実行（5-10秒削減）
- その他: コード確認の並列化（2-5秒削減）
---
## 新機能
### 1. 改善サイクルログの無効化
#### 背景
outcomes.jsonl / decisions.jsonl による改善サイクル機能（v1.0導入）が以下の問題を抱えていた：
1. **機能不全**:
- `get_session_status` は完了済みセッションを返さない
- Step 0 の失敗検出が動作しない
- 類似性マッチングも未実装
2. **パフォーマンス影響**:
- Step 0: 失敗チェック（2-3秒）
- Step 11: `record_outcome` 呼び出し（2-3秒）
- 合計: 4-6秒の無駄
#### 変更内容
**ファイル変更**:
```python
# tools/outcome_log.py
def record_outcome(outcome_log: OutcomeLog) -> dict:
# DISABLED: Log output disabled for performance
# with open(OUTCOME_LOG_FILE, "a", encoding="utf-8") as f:
# f.write(json.dumps(record, ensure_ascii=False) + "\n")
return {"success": True, ...}
def record_decision(decision_log: dict) -> dict:
# DISABLED: Log output disabled for performance
# with open(DECISION_LOG_FILE, "a", encoding="utf-8") as f:
# f.write(json.dumps(decision_log, ensure_ascii=False) + "\n")
return {"success": True, ...}
```
```python
# code_intel_server.py (line 278-290)
# DISABLED: Decision log disabled for performance (v3.10 feature)
# if plan.decision_log:
# decision_dict = plan.decision_log.to_dict()
# record_decision(decision_dict)
# (line 2186, 2052)
# "next_step": "Call merge_to_base to merge back to original branch.",
# DISABLED: record_outcome removed
```
```markdown
# .claude/commands/code.md
<!-- DISABLED: Step 0 disabled for performance (improvement cycle feature)
## Step 0: Failure Check
...
-->
```
**削減**: 4-6秒（LLM往復2-3回分）
#### 将来の改善方向
改善サイクル機能を再実装する場合：
- セッション永続化の見直し
- 完了セッションの検索方法改善
- 類似性マッチングの実装
---
### 2. EXPLORATION フェーズの並列化（v1.7で実装済み）
**注**: この機能はv1.7で実装済みです。v1.8では既存機能として利用可能です。
#### 背景
EXPLORATION フェーズ（Step 4）は適応的探索を実施：
```
現在のフロー（4往復）:
semantic_search → 結果を見る → search_text("modal")
1秒 8秒 0.023秒
↓
結果を見る → search_text("background")
11秒 0.024秒
↓
結果を見る → search_text("overlay")
9秒 0.011秒
↓
結果統合
24秒
合計: 0.058秒（実行）+ 52秒（LLM思考）= 52秒
```
**問題点**:
- search_text 間の待機（11秒 + 9秒 = 20秒）
- 各検索は独立しているため並列実行可能
**重要**: semantic_search の結果を見てから検索パターンを決定する必要があるため、完全な事前バッチ化は不可
#### 設計: search_text 複数パターン対応
`search_text` を複数パターン並列実行に拡張：
```python
def search_text(
session_id: str,
patterns: str | list[str], # 単一 or 複数
max_results: int = 50
) -> dict:
"""
テキスト検索。複数パターン指定で並列実行。
Args:
patterns: 検索パターン（文字列 or リスト）
Returns:
単一: {"matches": [...], "count": N}
複数: {"results": {"modal": {...}, "background": {...}}}
"""
if isinstance(patterns, str):
return _search_single(session_id, patterns, max_results)
else:
with ThreadPoolExecutor() as executor:
futures = {
p: executor.submit(_search_single, session_id, p, max_results)
for p in patterns
}
return {
"results": {p: f.result() for p, f in futures.items()}
}
```
**フロー改善**:
```
改善後（2往復）:
semantic_search
↓ [8秒] 結果を見て判断
↓ → 複数パターン決定: ["modal", "background", "overlay"]
search_text(patterns=["modal", "background", "overlay"])
↓ [0.06秒] 3つ並列実行
↓ [24秒] 全結果統合
合計: 0.06秒（実行）+ 32秒（LLM思考）= 32秒
```
**削減**: 20秒（52秒 → 32秒、38%削減）
#### なぜ事前バッチ化しないか
検討された代替案：
1. **QueryFrame拡張**: クエリから検索パターンを事前抽出
- 問題: タスクごとに全く異なるパターン（汎用性なし）
- 削減: +8秒（合計28秒削減）だが、適応性を犠牲
2. **基本パターン並列**: semantic と固定パターンを並列実行
- 問題: 「基本パターン」という概念自体が成立しない
- 削減: +8秒だが、無駄な検索や検索漏れのリスク
**結論**: 適応性を維持しつつ最大の効果を得るため、`search_text` 複数パターン対応のみを実装
---
### 3. PRE_COMMIT + QUALITY_REVIEW 順序変更
#### 背景
現在の実装ではコミット後に品質チェックを実施:
```
現在のフロー:
Step 10: PRE_COMMIT
├─ review_changes（ゴミ検出 + keep/discard判断）
├─ finalize_changes（コミット実行）★ここでコミット
└─ PRE_COMMIT完了
Step 10.5: QUALITY_REVIEW
├─ quality_review.md に基づいて品質チェック
├─ 問題発見 → READYに戻る（修正後、再度PRE_COMMIT → 新しいコミット）
└─ 問題なし → merge_to_base
```
**問題点**:
1. **コミット後に品質チェック** → リワーク時にコミット増加
2. **Git履歴の複雑化**: 修正のたびに新しいコミットが作成される
3. **非効率**: コミット前に品質チェックすれば1回で完了
#### 設計: コミット前品質チェック
順序を変更してコミット前に品質チェックを実施:
```
改善後のフロー:
Step 10: PRE_COMMIT (統合フロー)
├─ review_changes（ゴミ検出 + keep/discard判断）
├─ 品質チェック（quality_review.md）
├─ 問題あり？
│ YES → READYに戻る
│ NO → finalize_changes（コミット実行）★問題なければコミット
└─ merge_to_baseへ
```
#### 実装方法
**Phase遷移の変更**:
```python
# finalize_changes の変更
def finalize_changes(...):
# 1. reviewed_filesを適用（keep/discard）
_apply_reviewed_files(reviewed_files)
# 2. コミット準備（実行はまだ）
_prepare_commit(commit_message)
# 3. QUALITY_REVIEWフェーズへ移行（コミットは未実行）
session.phase = Phase.QUALITY_REVIEW
return {
"success": True,
"prepared": True,
"next_step": "Perform quality review before commit"
}
# submit_quality_review の変更
def submit_quality_review(...):
if issues_found:
# 問題あり → READYに戻る（コミット未実行）
session.phase = Phase.READY
return {"phase": "READY", "issues": issues}
else:
# 問題なし → コミット実行
commit_hash = _execute_commit()
session.phase = Phase.COMPLETED
return {
"commit_hash": commit_hash,
"next_step": "Call merge_to_base to complete"
}
```
#### code.md の変更
**Step 10の説明更新**:
```markdown
## Step 10: PRE_COMMIT Phase (Garbage Detection + Quality Review)
### 10.1: Review Changes
mcp__code-intel__review_changes
→ ゴミ検出、keep/discard判断
### 10.2: Prepare Commit
mcp__code-intel__finalize_changes
reviewed_files: [...]
commit_message: "..."
→ コミット準備（実行はまだ）
### 10.3: Quality Review
.code-intel/review_prompts/quality_review.md を確認
→ 品質チェック実施
### 10.4: Submit Quality Review
mcp__code-intel__submit_quality_review
issues_found: false
→ 問題なければコミット実行
```
**削減**: 2-3秒（finalize → quality 間の待機）
**主な効果**:
- Git履歴のクリーン化（1タスク = 1コミット）
- リワーク時のコミット削減
**詳細設計**: [docs/draft/pre_commit_quality_order_issue.md](../draft/pre_commit_quality_order_issue.md)
---
## 実装状況
### v1.7 並列化検証の結果次第
#### ケース1: v1.7 並列化が成功した場合（確率 75-85%）
| 機能 | 状態 | 削減見込み |
|------|------|----------|
| 改善サイクルログ無効化 | ✅ 完了（v1.6） | 4-6秒 |
| 準備フェーズバッチ化 | 📋 設計完了 | 5秒 |
| PRE_COMMIT順序変更 | 📋 設計完了 | 2-3秒 |
| **並列実行最適化** | ✅ v1.7で実装済み | **27-35秒** |
| - EXPLORATION | search_text 拡張 | 20秒 |
| - READY | Read/Grep 並列化 | 5-10秒 |
| - その他 | コード確認並列化 | 2-5秒 |
| **合計** | - | **38-49秒** |
**現在**: 約402秒（6分42秒）
**改善後**: 約353-364秒（5分53秒-6分4秒）
**削減率**: 9-12%
#### ケース2: v1.7 並列化が失敗した場合（確率 15-25%）
| 機能 | 状態 | 削減見込み |
|------|------|----------|
| 改善サイクルログ無効化 | ✅ 完了（v1.6） | 4-6秒 |
| 準備フェーズバッチ化 | 📋 設計完了 | 5秒 |
| PRE_COMMIT順序変更 | 📋 設計完了 | 2-3秒 |
| 並列実行最適化 | ❌ v1.7で保留 | 0秒 |
| **合計** | - | **11-14秒** |
**現在**: 約402秒（6分42秒）
**改善後**: 約388-391秒（6分28-31秒）
**削減率**: 3-3.5%
**注**: 並列化はv1.9以降で別アプローチ（自動並列化など）を検討
---
### 4. 探索のみモード（Intent-based + --only-explore）
#### 背景
コードベースの問題調査や影響範囲の分析など、実装を伴わない探索タスクにおいて、以下の問題があった：
1. **不要なフェーズの実行**:
- 探索だけで十分なのに READY, POST_IMPL_VERIFY, PRE_COMMIT, QUALITY_REVIEW も実行
- 実装フェーズをスキップする手段がない
2. **既存オプションの不足**:
- `--only-verify`: 検証のみ（探索もスキップ）
- `--quick` / `--fast`: 探索をスキップ（実装を実行）
- 「探索のみ実行」オプションが存在しない
#### 変更内容
探索のみモードを**2つの方法**で実現：
##### A. Intent-based Automatic Mode（自動判定）
**Intent Classification による自動設定**:
- Intent=INVESTIGATE または Intent=QUESTION → 自動的に `skip_implementation=true`, `skip_branch=true`
- フラグ指定不要（システムが自動判定）
**使用例**:
```bash
# これらは自動的に探索のみモードになる
/code sample/calculator.py の実装内容を教えて # Intent=QUESTION
/code 認証処理がどう実装されているか調査 # Intent=INVESTIGATE
```
##### B. --only-explore フラグ（明示的指定）
**任意のIntentで探索のみモード**:
- `--only-explore` / `-e` フラグで明示的に指定
- Intent=IMPLEMENT/MODIFY でも探索のみ実行可能
**使用例**:
```bash
# 実装はせず、調査のみ
/code --only-explore ログイン機能を追加 # Intent=IMPLEMENT だが探索のみ
/code -e このバグを修正 # Intent=MODIFY だが探索のみ
```
**2つの方法の違い**:
| 方法 | トリガー | Intent | ブランチ |
|------|---------|--------|---------|
| Intent-based | 自動（INVESTIGATE/QUESTION） | INVESTIGATE/QUESTION | 作成されない |
| --only-explore | 明示的フラグ | 任意 | 作成されない |
**実行されるフェーズ**（両方共通）:
```
✅ DOCUMENT_RESEARCH
✅ EXPLORATION (find_definitions, find_references, search_text)
✅ Symbol Validation
✅ SEMANTIC (必要な場合)
✅ VERIFICATION (必要な場合)
✅ IMPACT_ANALYSIS
✅ 調査結果をユーザーに報告
❌ READY (実装) - スキップ
❌ POST_IMPL_VERIFY - スキップ
❌ PRE_COMMIT - スキップ
❌ QUALITY_REVIEW - スキップ
❌ ブランチ作成 - なし（探索専用のため）
```
**フェーズマトリックス**:
| オプション | 探索 | 実装 | 検証 | 介入 | ゴミ取 | 品質 | ブランチ |
|-----------|:----:|:----:|:----:|:----:|:------:|:----:|:-------:|
| Intent=INVESTIGATE/QUESTION | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
| `--only-explore` / `-e` | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
#### 実装詳細
**ファイル変更**:
1. `.claude/commands/code.md`:
- Step 1: Intent Classification に INVESTIGATE/QUESTION の説明追加
- Step 2: Session Start に Intent-based skip_implementation 自動設定ロジック追加
- Step 3.5: begin_phase_gate に skip_branch 判定ロジック追加（skip_implementation=true → skip_branch=true）
- Step -1: Flag Check に `--only-explore` / `-e` 処理追加
- Step 8: IMPACT_ANALYSIS に探索完了時の終了処理を追加
2. `tools/session.py`:
- `SessionState` に `skip_implementation: bool` フラグ追加
- `submit_impact_analysis` で `skip_implementation=True` 時に `exploration_complete=true` を返却
3. `code_intel_server.py`:
- `start_session` に `skip_implementation` パラメータ追加
- `begin_phase_gate` に skip_implementation 判定追加（skip_implementation=true → skip_branch=true, phase=EXPLORATION）
**ブランチ作成の修正**:
- 探索専用モード（skip_implementation=true）の場合、ブランチは作成されない
- `begin_phase_gate` で skip_branch=true を自動設定
- 理由: 探索のみでコード変更がないため、ブランチ不要
**削減効果**: なし（探索のみ実行のため、時間削減ではなく用途拡張）
**ユースケース**:
- コードベースの問題点調査（Intent=INVESTIGATE で自動）
- セキュリティ監査の事前調査（Intent=INVESTIGATE で自動）
- アーキテクチャの理解（Intent=QUESTION で自動）
- 影響範囲の分析（Intent=INVESTIGATE で自動、または --only-explore で明示的）
---
## 今後の最適化方向
### v1.7（検証フェーズ）
- 🔬 EXPLORATION並列化の検証
- code.md に並列実行の指示追加
- LLMの動作パターン確認
- 成功すれば実装、失敗すれば v1.9 以降で再検討
### v1.8（確実な最適化 - このバージョン）
- 🚧 prepare_session_batch 実装
- 🚧 PRE_COMMIT順序変更（ゴミ取り → 品質チェック → コミット）
- ✅ v1.7並列化成功時: search_text 複数パターン対応も含む
### v1.9以降（さらなる改善）
- sync_index 高速化（Embedding バッチ処理）→ [v1.9](v1.9_ja.md) で実装予定
- VERIFICATION + IMPACT_ANALYSIS 統合（10秒削減可能性）→ [v1.9](v1.9_ja.md) で実装予定
- DOCUMENT_RESEARCH の選択的実行（別途計画中）
### 長期
- フェーズ間の待機時間削減
- LLM思考の効率化（より単純なフロー設計）
---
## 参考資料
- [準備フェーズ詳細分析](../draft/preparation_phase_detailed_analysis.md)
- [EXPLORATIONフェーズ詳細分析](../draft/exploration_phase_detailed_analysis.md)
- [フェーズ分析（実測）](../draft/phase_analysis_actual_execution.md)
- [準備フェーズバッチ化設計](../draft/preparation_batch_design.md)
- [Symbol Validation分析](../draft/symbol_validation_analysis.md)
- [SEMANTIC & VERIFICATION分析](../draft/semantic_verification_analysis.md)
- [IMPACT_ANALYSIS分析](../draft/impact_analysis_phase.md)
- [PRE_COMMIT + QUALITY_REVIEW 順序問題](../draft/pre_commit_quality_order_issue.md)
---
## 関連変更
- `tools/outcome_log.py`: ファイル書き込み無効化
- `code_intel_server.py`: record_decision 呼び出し削除
- `.claude/commands/code.md`: Step 0 無効化、Step番号更新
