はじめに

前回の記事で紹介した Code Intelligence MCP Server が、v1.6 まで大幅に進化しました。

前回は「調べずに書くを物理的に禁止する」フェーズゲート方式を紹介しましたが、今回は以下の機能を追加しました：

v1.2: Git ブランチによるゴミ検出
v1.3: 設計ドキュメントから自動でルールを抽出するサブエージェント
v1.4: 検証ループでハマった時の介入システム
v1.5: 実装後の品質レビュー
v1.6: stale ブランチ警告とブランチライフサイクル管理

v1.2: Git ブランチによるゴミ検出

問題：LLMは「ついでに」余計なものを書く

LLMにコード修正を依頼すると、こんなことがよく起こります：

# 依頼: AuthService のバグ修正

# LLMが書いたコード
def login(self, username, password):
    print(f"DEBUG: username={username}")  # ← デバッグログ
    print(f"DEBUG: password={password}")  # ← 本番に入れたらまずい
    # 以下修正コード...

他にも：

console.log() が残ったまま
古いコードがコメントアウトで残っている
依頼していないファイルまで修正している
test.py や debug.html が生成されている

解決策: Git ブランチ + PRE_COMMIT フェーズ

v1.2 では、LLMの書き込みを Git ブランチで隔離し、コミット前に全変更をレビューできるようにしました。

┌──────────────────────────────────────────────────────────┐
│  Base Branch (例: main, feature/xxx)                      │
│  └── タスク開始時の状態                                   │
├──────────────────────────────────────────────────────────┤
│  Task Branch (llm_task_{session_id}_from_{base})          │
│  └── LLMの変更がここに蓄積                                │
└──────────────────────────────────────────────────────────┘

新しいワークフロー

EXPLORATION → ... → READY → PRE_COMMIT → QUALITY_REVIEW → Finalize
                      ↓         ↓              ↓
                   実装完了   ゴミ検出      品質チェック
                              keep/discard

PRE_COMMIT フェーズでできること：

# 全変更を確認
mcp__code-intel__review_changes

# 結果例
{
  "changes": [
    {"path": "auth/service.py", "change_type": "modified", "diff": "..."},
    {"path": "debug.log", "change_type": "added", "diff": "..."},  # ← 怪しい
    {"path": "auth/test_tmp.py", "change_type": "added", "diff": "..."}  # ← 怪しい
  ]
}

# keep/discard を指定してコミット
mcp__code-intel__finalize_changes
  reviewed_files: [
    {"path": "auth/service.py", "decision": "keep"},
    {"path": "debug.log", "decision": "discard", "reason": "デバッグ出力"},
    {"path": "auth/test_tmp.py", "decision": "discard", "reason": "一時ファイル"}
  ]
  commit_message: "fix: AuthService の認証バグを修正"

Git ブランチ統合

start_session → 元ブランチを記録
begin_phase_gate → llm_task_{session_id}_from_{base} ブランチ作成
実装中 → タスクブランチに変更が蓄積
finalize_changes → keep のみをコミット、discard は破棄
merge_to_base → 元ブランチにマージ、タスクブランチ削除

中断時のクリーンアップ：

# 中断したセッションのゴミを一括削除
/code --clean

v1.3: Document Research（設計ドキュメント自動調査）

問題：プロジェクトルールが多すぎて伝えきれない

大規模プロジェクトでは、守るべきルールが散在しています：

docs/
├── Architecture/
│   ├── app.md           ← "イベント/リスナーパターンを使え"
│   └── notes.md         ← "Octane環境ではファイルセッションNG"
├── DB/
│   └── customers.md     ← "会員は仮登録/本登録の2状態がある"
└── Security/
    └── auth.md          ← "パスワードは必ずHash::make()"

これらを毎回プロンプトに書くのは現実的ではないし、タスクに関係ないルールまで入れると無駄にコンテキストを消費します。

解決策: サブエージェントによる動的ルール抽出

v1.3 では、実装開始前にサブエージェントが設計ドキュメントを調査し、そのタスクに関係するルールだけを抽出します。

┌────────────────────────────────────────────────────────┐
│  Layer 1: project_rules (常に適用)                      │
│  └── CLAUDE.md から抽出した DO/DON'T リスト            │
│      例: "Service層でビジネスロジック"                  │
│          "Controllerに複雑なロジック禁止"               │
└────────────────────────────────────────────────────────┘
                         ↓
┌────────────────────────────────────────────────────────┐
│  Layer 2: mandatory_rules (タスク固有)                  │
│  └── サブエージェントが docs/ を調査して抽出            │
│      例: "会員登録 → customers.md の2状態ルール必須"    │
│          "メール送信 → Events/Listeners パターン必須"   │
└────────────────────────────────────────────────────────┘

実際の動作

ユーザー: /code 会員登録機能を実装して

[DOCUMENT_RESEARCH フェーズ]
サブエージェント: docs/ を調査中...
  → docs/DB/customers.md を発見
  → "会員は provisional/active の2状態" (line 127-130)
  → docs/Architecture/app.md を発見
  → "メール送信は Events/Listeners" (line 495-574)

mandatory_rules:
  - R1: "Members have two states: provisional and active" (customers.md:127)
  - R2: "Use Events/Listeners pattern for email" (app.md:495)

[EXPLORATION フェーズ]
submit_understanding:
  rule_acknowledgment: ["R1", "R2"]  ← 必須
  rule_compliance_plan:
    R1: "Member モデルに status enum を追加"
    R2: "MemberRegistered イベントを作成"

ルール適用の強制

acknowledge しないと先に進めない：

// NG: ルール無視で submit_understanding
{
  "error": "rule_acknowledgment_missing",
  "missing_rules": ["R1", "R2"],
  "hint": "All mandatory_rules must be acknowledged"
}

v1.4: Intervention System（介入システム）

問題：検証が通らずにループする

LLMが実装 → 検証失敗 → 修正 → 検証失敗... を繰り返すことがあります。同じアプローチで何度もリトライしても解決しません。

解決策: 介入プロンプト

3回連続で検証に失敗すると、介入プロンプトが発動します：

実装 → 検証失敗 → 修正 → 検証失敗 → 修正 → 検証失敗
                                              ↓
                                     介入プロンプト発動
                                     「別のアプローチを試せ」

.code-intel/interventions/ にプロンプトを配置：

.code-intel/interventions/
├── verification_loop.md  ← 検証ループ時の介入
└── custom.md             ← カスタム介入

介入プロンプト例（verification_loop.md）：

## 検証が3回連続で失敗しました

現在のアプローチでは解決できていません。以下を試してください：

1. エラーメッセージを再度確認
2. 根本的に異なるアプローチを検討
3. 必要なら EXPLORATION に戻って調査

v1.5: Quality Review（品質レビュー）

問題：コードは動くけど品質が低い

検証は通ったけど、こんなコードが残っていることがあります：

未使用の import
デッドコード
ハードコードされた秘密情報
命名規則違反

解決策: QUALITY_REVIEW フェーズ

PRE_COMMIT（ゴミ検出）の後に、品質チェックを追加しました：

READY → POST_IMPL_VERIFY → PRE_COMMIT → QUALITY_REVIEW → Finalize
                                              ↓
                                         問題あり？
                                              ↓
                                         READY に戻る

品質レビューのチェック項目（.code-intel/review_prompts/quality_review.md）：

カテゴリ	チェック項目
Code Quality	未使用 import、デッドコード、重複コード
Conventions	CLAUDE.md ルール、命名規則、ファイル構造
Security	ハードコード秘密、ログに機密情報、入力検証
Performance	N+1 クエリ、不要ループ、メモリリーク

問題があれば READY に戻してやり直し：

// 品質レビュー結果
{
  "issues_found": true,
  "issues": [
    "Unused import 'os' in auth/service.py:3",
    "console.log left in auth/service.js:45"
  ],
  "next_action": "Fix the issues in READY phase"
}

v1.6: Branch Lifecycle（ブランチライフサイクル）

問題：前回のタスクブランチが残ったまま

セッションが中断された場合、llm_task_* ブランチが残ったまま次のタスクを始めようとすることがあります。

解決策: begin_phase_gate での stale ブランチ検出

v1.6 では、ブランチ作成を begin_phase_gate に分離し、stale ブランチ警告を追加しました：

start_session (ブランチ作成なし)
    ↓
begin_phase_gate
    ↓
[stale ブランチあり？] → ユーザーに確認
    ↓                    ├─ 削除して続行
    ↓                    ├─ マージして続行
    ↓                    └─ そのまま続行
ブランチ作成 → フェーズゲート開始

ユーザーへの確認：

前回のタスクブランチが残っています：
  - llm_task_xyz_from_main (3 commits)

どうしますか？
1. 削除して続行（変更を破棄）
2. マージして続行（変更を取り込む）
3. そのまま続行（前回のブランチは残す）

フェーズマトリックス

各オプションで何が有効になるかの一覧：

オプション	探索	実装	検証	介入	ゴミ取	品質	ブランチ
(デフォルト)	✅	✅	✅	✅	✅	✅	✅
`--no-verify`	✅	✅	❌	❌	✅	✅	✅
`--no-quality`	✅	✅	✅	✅	✅	❌	✅
`--fast` / `-f`	❌	✅	✅	✅	✅	❌	✅
`--quick` / `-q`	❌	✅	✅	❌	❌	❌	❌

コマンドフラグ（v1.6）

# フルモード（全フェーズ実行）
/code add login feature

# 高速モード（探索スキップ、ブランチあり、既知の修正向け）
/code -f fix known issue in login validation

# クイックモード（探索スキップ、ブランチなし、単純タスク向け）
/code -q change button color to blue

# 検証のみ（既存コードをテスト）
/code -v sample/hello.html

# 検証スキップ
/code --no-verify fix typo

# 品質レビュースキップ
/code --no-quality quick fix

# ドキュメント調査をカスタマイズ
/code --doc-research=security,database add user management

# ドキュメント調査をスキップ
/code --no-doc-research fix README typo

# 介入システムをスキップ
/code -ni fix obvious bug

# クリーンアップ（中断セッションのゴミ削除）
/code -c

# フルリビルド（インデックス再構築）
/code -r

セットアップ

新規セットアップ

# 1. MCP サーバーをクローン
git clone https://github.com/tech-spoke/llm-helper.git
cd llm-helper
./setup.sh

# 2. プロジェクト初期化
./init-project.sh /path/to/your-project

# 3. .mcp.json 設定（init-project.sh の出力をコピー）

# 4. スキルをコピー（オプション）
cp .claude/commands/*.md /path/to/your-project/.claude/commands/

# 5. Claude Code 再起動

作成されるディレクトリ：

your-project/
└── .code-intel/
    ├── config.json        ← 設定
    ├── context.yml        ← プロジェクトルール・ドキュメント調査設定
    ├── chroma/            ← ChromaDB データ
    ├── agreements/        ← 成功パターン保存
    ├── logs/              ← DecisionLog, OutcomeLog
    ├── verifiers/         ← 検証プロンプト
    ├── doc_research/      ← ドキュメント調査プロンプト
    ├── interventions/     ← 介入プロンプト
    └── review_prompts/    ← 品質レビュープロンプト

既存ユーザーのアップグレード（v1.2 以前から）

新規セットアップの場合は不要です。init-project.sh がすべてのディレクトリを作成します。

# 1. MCP サーバー更新
cd /path/to/llm-helper
git pull
./setup.sh

# 2. スキル更新
cp .claude/commands/*.md /path/to/your-project/.claude/commands/

# 3. 不足ディレクトリ作成
cd /path/to/your-project
mkdir -p .code-intel/{logs,verifiers,doc_research,interventions,review_prompts}

# 4. テンプレートコピー（既存ファイルは上書きしない）
cp -n /path/to/llm-helper/.code-intel/verifiers/*.md .code-intel/verifiers/
cp -n /path/to/llm-helper/.code-intel/doc_research/*.md .code-intel/doc_research/
cp -n /path/to/llm-helper/.code-intel/interventions/*.md .code-intel/interventions/
cp -n /path/to/llm-helper/.code-intel/review_prompts/*.md .code-intel/review_prompts/

まとめ

バージョン	追加機能	解決する問題
v1.1	マークアップ緩和	UI修正に過剰な調査
v1.2	Git ブランチ + PRE_COMMIT	デバッグログ、ゴミファイル混入
v1.3	Document Research	プロジェクトルールの伝達漏れ
v1.3	Verifier	書いて終わり、テストしない
v1.4	Intervention System	検証ループでハマる
v1.5	Quality Review	コードは動くけど品質が低い
v1.6	Branch Lifecycle	前回のブランチが残ったまま

「調べて→書いて→確認して→品質チェック→クリーンアップ」の全工程を強制することで、LLMは単なるコード生成機ではなく、責任あるエンジニアの思考プロセスをトレースするようになります。

リンク

GitHub: https://github.com/tech-spoke/llm-helper
v1.6 リリースノート: docs/updates/v1.6.md
ライセンス: MIT

タグ

Claude MCP AI コード生成 開発効率化 オープンソース LLM Git コードレビュー 品質管理