Handoff MCP v0.21–0.26 — ドキュメント管理・検索品質・Codex CLI 対応

Handoff MCP v0.21 から v0.26 までの更新をまとめてお知らせします。ドキュメント管理の本格化、メモリ検索の精度向上、セットアップの簡素化、そして Codex CLI への正式対応が主な柱です。

ドキュメント管理の本格化 (v0.21–v0.25)

プロジェクトの仕様書や設計書を .handoff/ 内で一元管理できるようになりました。

ストレージとツール

• YAML フロントマター単一ファイル形式 — メタデータと本文が1つの .md ファイルに収まる形式に移行しました。既存データは初回アクセス時に自動マイグレーションされます。
• doc_update_section — 見出しパスを指定して、ドキュメントの一部だけを更新できます。
• doc_graph — 管理対象ドキュメントをグラフ構造で返します。親子関係・関連リンク・共有タスクによる暗黙の接続をノードとエッジで表現します。
• doc_trace — ドキュメントの系譜をたどります。上流・下流の追跡、フォーク分岐の検出、循環参照の検出に対応。
• append_body — 既存ドキュメントへのセクション追記を、本文全体の書き換えなしに行えます。
• suggest_refs — ソースファイルをスキャンして、ドキュメント見出しに対する関連リファレンスを提案します。

Verification Matrix（検証マトリクス）

ドキュメントの各セクションを検証項目として管理し、レビュー進捗を追跡できます。

• doc_verify — セクション見出しごとに検証状態（チェック済み・スキップ・フラグ付き）を記録。ドキュメント編集後の sync で項目を自動整合。
• doc_verify_status — 検証の進捗サマリー（総数・チェック済み・未チェック・スキップ）を取得。
• task_checklist — タスクの done_criteria とリンクされたドキュメントの検証進捗を統合表示。generate アクションでスペックのセクションから done_criteria を自動生成。

メモリ・ドキュメント検索の品質向上 (v0.24.7–v0.24.9)

検索エンジンを重み付き BM25 に切り替え、日本語テキストの検索精度を大幅に改善しました。

• 重み付き BM25 — 日本語の格助詞（は・が・を・で・に…）が修飾する内容語をブーストし、ストップワードと CL-CnG トライグラムをコーパス統計から除外。実プロジェクトメモリ35件・13クエリの評価で MRR 0.923 → 0.936。
• 相対閾値フィルタ — トップスコアに対する比率でカットオフし、強いヒットに便乗する低関連度の「テールノイズ」を排除。
• min_score を 0.1 → 2.0 に引き上げ — 重み付き BM25 のスケールに合わせて調整。無関連プロンプトの偽陽性注入が大幅に減少。
• lexsim 0.7.0 — ドキュメント側キーワードに明示的な TF ブースト、コンテンツ由来トライグラムの復元。

セットアップの自動化 (v0.24.3–v0.24.5)

handoff-mcp setup コマンドが大幅に強化されました。

• .mcp.json 自動構成 — handoff サーバーエントリの自動追加。--mcp-json でエントリの追加のみも可能。
• --global フラグ — ~/.claude/settings.json にグローバルインストール。
• CLAUDE.md テンプレート注入 — セッションライフサイクルの手順セクションを自動追記。--force で既存セクションの更新も。
• --check の拡充 — hooks・.mcp.json・CLAUDE.md の状態をまとめて報告。

セッション管理の改善 (v0.22–v0.24.6)

• session-loop v2 — 実装 → テスト → レビューを3段直列に簡素化。エージェント起動数を最大26から8に削減。
• セッションフィールドの保全 — save_context で未指定のフィールド（decisions, handoff_notes 等）が空で上書きされる問題を修正。
• マルチバイト文字の安全な切り詰め — 日本語テキストのバイト位置スライスによるパニックを修正。
• read_config の曜日名対応 — VSCode 拡張が書く ["sun", "sat"] 形式を受け入れるカスタムデシリアライザ。

Codex CLI 対応 (v0.26)

Handoff MCP プラグインが OpenAI の Codex CLI でも動作するようになりました。

• agents/openai.yaml — 全6スキルに Codex UI メタデータ（display_name、short_description、default_prompt）と MCP ツール依存宣言を追加。
• AGENTS.md — Codex ユーザー向けのセッションハンドオフ手順テンプレート。~/.codex/AGENTS.md にコピーすれば自動的にセッション管理が有効に。

その他の修正

• npm ソースビルド修正 (v0.25.1) — templates/ が npm パッケージに含まれておらず、プリビルドバイナリのないプラットフォームで cargo build が失敗する問題を修正。
• hooks プラグインの安定化 (v0.24.1–v0.24.4) — MCP サーバー名の解決、.mcp.json なしでのフック動作を修正。
• estimate_hours ルール緩和 (v0.23) — todo のリーフタスクは見積もり不要に。見積もりは in_progress 以降で強制。

インストール・アップデート

npx handoff-mcp-server@latest

Claude Code のプラグインとして使っている場合:

/plugin install alphaelements/handoff-mcp

Handoff の実績ページを見る