smart-context-mcp

smart-context-mcp

インテリジェントなコンテキスト圧縮によって、AI エージェントのトークン使用量を最大 90％削減する MCP サーバーです（このプロジェクトで計測）。

概要

コードコンテキストを効率的に読み取り、検索、管理するための専用ツールを提供する MCP（Model Context Protocol）サーバーです。ファイル全体を読み込んだり、膨大な検索結果を返したりする代わりに、タスクに重要な情報を保持しながら圧縮します。

本番利用での実測値：

• 約 700 万トークン → 約 80 万トークン（約 89％削減）
• 開発全体で 1,500 件以上の操作を追跡
• ツールに応じた圧縮率：3 倍〜46 倍
• コンテキストのオーバーヘッドは別途追跡されるため、総削減量と純削減量の両方をレポートで確認できます

ワークフロー単位の削減効果：

• デバッグ：約 85〜90％のトークン削減
• コードレビュー：約 85〜90％のトークン削減
• リファクタリング：約 85〜90％のトークン削減
• テスト：約 85〜90％のトークン削減
• アーキテクチャ：約 85〜90％のトークン削減

複雑なタスクでの実際の導入状況：

• 複雑なタスクの約 70〜75％で devctx ツールを使用
• 最も使用されているツール：smart_read（850 回以上）、smart_search（280 回以上）、smart_shell（220 回以上）
• 使用されない主な理由：タスクが簡単すぎる、インデックスが未作成、標準ツールが優先される

詳しくは、ワークフロー指標と導入指標をご覧ください。

最新リリース：1.21.0

セマンティックエンジンを中心としたマイナーリリースです。MCP のツール数が20 → 22（smart_code + smart_output）に増えました。SQLite スキーマが 8 → 9 に更新されます（新しい outputs テーブルを追加。初回実行時に自動移行）。新たなランタイム依存関係はありません。TypeScript LanguageService は既にお使いの typescript パッケージから利用され、パッケージがない場合はフォールバックプロバイダーに切り替わります。

• smart_code（新しいツール）。 TypeScript LanguageService を介して JS/TS のセマンティックなコードナビゲーションを行います。行と列を指定する必要はなく、シンボル名（および任意の filePath）で解決します。アクション：definition、references、implementations、diagnostics、impact、rename。完全なファイル本文は返さず、コンパクトな位置情報（ファイル名と 1 始まりの開始位置／終了位置）を返します。includeTests=false にするとテストのパスを除外し、maxResults でペイロードの上限を設定します。
• 影響分析。 smart_code(action='impact') は、直接的なヒット（セマンティックな定義、参照、実装）と、トランジティブなファイル（インポートグラフ。maxHops のデフォルトは 2）、関連するテスト、カバレッジフラグを分けて返します。risk.level には basis: 'heuristic' というラベルが付いており、独自の note でもその旨が示されます。これは順位付けの補助であり、セマンティックな確実性を示すものではありません。
• スコープを考慮したリネーム。デフォルトはドライランです。 smart_code(action='rename') は findRenameLocations を使用し、デフォルトで dryRun: true です。最初の呼び出しでは、ファイルごとの変更予定差分（各行の before／after）を返しますが、書き込みは行いません。エラーとなる競合（無効な newName または予約名、同じ名前、対象を解決できない場合、パスの範囲外への移動、ファイルが見つからない場合、maxFiles を超える変更範囲）は、常に書き込みをブロックします。name-collision はヒューリスティックな警告であり、スコープの重複を検証しないため、strict: true の場合にのみ書き込みをブロックします。実際に書き込みを行った後、diagnosticsAfter は変更対象ファイルに残っている TypeScript エラーを報告します。セマンティックではないテキスト置換には、引き続き smart_edit を使用します。
• smart_output（新しいツール）。 永続的な出力／アーティファクトストア（shell、test、build、lint、diff）です。20 ターン前のスタックトレースも、コマンドを再実行せずに取り出せます。アクション：save、search、excerpt、summary、list、stats、prune。永続化の前に、コンテンツから秘密情報と思われる文字列を除去します。また、DEVCTX_OUTPUT_MAX_BYTES（256KB）を超える場合は先頭と末尾を残して切り詰めるため、エラーの末尾は常に保持されます。保持期間は DEVCTX_OUTPUT_RETENTION_DAYS（14）、種類ごとの最大件数は DEVCTX_OUTPUT_MAX_PER_KIND（50）で設定します。同じ kind と command の出力は重複排除され、repeat_count に集約されます。smart_shell／smart_test による自動キャプチャは、DEVCTX_OUTPUT_STORE=true でオプトインします（有効にすると smart_shell は outputRef を返します）。明示的な save／search は常に利用できます。SQLite が利用できないかロックされている場合、エラーをスローする代わりに degraded: true を返して機能を縮退させます。
• smart_context でのセマンティックな拡張はオプトインです。 include: ['semantic'] を指定すると、テキストの類似性ではなく、実際の定義、参照、実装をたどってコンテキストを拡張します。また、すべての項目に whyIncluded の説明が追加されます。precision@5 ベンチマークで有効性が確認されるまでは、デフォルトでオフです。
• ADR／仕様への対応強化とグラフパス。 同じロードマップの成果として、ADR のセクションは kind='adr'／'adr-section' としてインデックス化されます。また、smart_context は 2 つのファイルまたはシンボル間のグラフ上のパスを返せるようになりました。
• ツール間で共有される tokenBudget。 smart_read、smart_read_batch、smart_context、smart_turn（start + end）、smart_resume が tokenBudget: number | { id?, maxTokens, shared? } を受け付けるようになりました。shared:true（または id を設定）の場合、同じタスク内の呼び出し間で予算が再利用されます。そのため、複数ステップのエージェントのフローでも、呼び出しごとに管理しなくても厳格なトークン上限を超えずに済みます。予算によって出力が実際に変化した場合、レスポンスには taskBudget、remainingBudget、budgetDetails（scope、actions、縮退モード）が含まれます。
• smart_search の検索モード。 新しい mode: 'needle' | 'balanced' | 'semantic'（デフォルトは balanced）を追加しました。needle = リテラルの完全一致のみ（正規表現や語句の拡張なし）。デバッグクエリでノイズを抑えます。balanced = 完全一致 + 正規表現 + 語句の拡張。semantic = 完全一致を優先し、一致のシグナルが弱い場合に限りローカルのセマンティックブロックを追加します。従来の semantic: true フラグは、mode: 'semantic' のレガシーエイリアスとして引き続き使用できます。デフォルトの maxFiles を 15 → 5 に引き下げました。新しい maxTokens はレスポンス全体のトークン数を制限し、一致結果、診断情報、セマンティックブロックの順に適切に圧縮します。ファイルごとのランキングを matchedBy、boostSource、scoreBreakdown、whyRanked で確認できるようになりました。クエリの範囲が広すぎる場合や結果が空の場合、レスポンスには hasMore / totalFiles / nextSuggestedMaxFiles と、次に取るべき操作を示す suggestions も含まれます。
• smart_read の永続キャッシュと、予算に応じた full モードの縮退。 (filePath, mode, selector, content_hash) をキーとする新しい SQLite の read_cache テーブルを追加しました。変更のないファイルを2回目に読み取る際のコストはほぼゼロです。full モードは明示的な最終手段になりました。tokenBudget / maxTokens が設定されている場合、まず軽量なモード（outline → signatures → truncated）に縮退し、実際に使用したモードを fullMode + budgetDetails で報告します。新しい clearReadCachePersistent と、runStorageMaintenance への GC 統合も追加しました。
• smart_turn の簡易タスクスキップヒューリスティック。 プロンプトが短く（正規化後 40 文字以下）、簡易タスクに分類され、セッション／タスクが固定されていない場合、smart_turn(start) はオーケストレーション全体のコストをかけずに、recommendedPath.mode='simple_task_skip' とともに skipSmartTurn: true を返すようになりました。単純なプロンプトでは、継続性の解決にかかるオーバーヘッドを削減します。minimal の詳細度では、エージェントが実際に使用するフィールドに合わせて summary / refreshedContext もさらに圧縮されます。
• global_memory のノイズヒント。 プロジェクトごとの、サニタイズ済みのノイズテレメトリーを ~/.devctx/global.db（noise_hints テーブル）に永続化するようになりました。新しいアクション noise_stats と noise_reset（すべて、または query 経由）を追加しました。これにより、リポジトリ内ですでにノイズが多いとエージェントが判断したクエリを smart_search が学習し、コンテンツを漏えいすることなくランキングを調整できます。
• KPI ベースラインのインフラストラクチャ。 新しいスクリプト evals/kpi-baseline.js + evals/kpi-utils.js により、harness.js と realworld-eval.js の実行結果を、トップ5の適合率、再現率、再読み込みタスク／呼び出し率、タスクサイズ別（短／長）のバケットを含む単一の JSON スナップショットに集約します。リリース間のリグレッション検出用に kpi-baseline-latest.json を保存します。新しいテストスイート tests/eval-kpis.test.js も追加しました。

1.20.0 の主な変更点（現行バージョン）

1.19.0 と同じツール数ですが、複数のツールに厳格なトークン予算の制御、検索モードの使い分け、2 回目の読み取り時のキャッシュ再利用が追加されました。

• ツール間で共有できる tokenBudget。 smart_read、smart_read_batch、smart_context、smart_turn、smart_resume は tokenBudget: number | { id?, maxTokens, shared? } を受け付けます。同じタスク内の呼び出し間で再利用でき、複数ステップのフローを厳格な上限以内に収められます。
• smart_search のモード。 mode: 'needle' | 'balanced' | 'semantic'（デフォルトは balanced）、応答全体を上限内に収める maxTokens、および matchedBy ／ scoreBreakdown ／ whyRanked による確認可能なランキング情報を利用できます。
• smart_read の永続キャッシュ。 (filePath, mode, selector, content_hash) をキーとする SQLite の read_cache を使用します。変更されていないファイルを 2 回目に読み取る際のコストは実質ゼロです。モード full は予算に応じて軽量なモードに切り替わり、実際に使用されたモードを報告します。
• 短く単純なプロンプトでは smart_turn がスキップされ、global_memory のノイズヒントにより、smart_search はリポジトリごとにノイズが多いと判明したクエリを学習できます。
• 回帰検出のため、precision@5、recall、再読み取り率、レイテンシを記録する KPI ベースラインのインフラストラクチャ（evals/kpi-baseline.js）が追加されました。

1.19.0 の主な変更点

5段階の品質向上を、実際の使用を通じた検証を行いながら、順次コミットとして実施しました。MCP のツール数は 18 → 20 に増え、テストが68件追加され、新たな依存関係は ゼロ です。

• smart_playbook（新しいツール）。 複数の smart_* ツールを1回の MCP 呼び出しで実行する、宣言型の複合ワークフローです。パッケージには、組み込みのプレイブックが5つ付属します。preflight-merge（レビュー + 影響を受けるテスト + チェックポイント）、debug-flake（直近の失敗 + 厳選されたデバッグコンテキスト + 影響範囲）、refactor-safe（厳選されたコンテキスト + 影響範囲 + チェックポイント）、doc-sync（ADR の検索 + ドキュメントのコンテキスト）、ramp-up（ステータス + doctor + ADR の概要）です。.devctx/playbooks/*.{yaml,json} を使用してプロジェクト単位で上書きでき、{{args.X}} による補間、when / label / stopOnFail / dryRun に対応します。許可されるツールは smart_* に制限されています。依存関係はゼロで、組み込みの最小限の YAML パーサーを使用します。
• インデックス用のリアクティブな FS ウォッチャー。 fs.watch（ネイティブ、再帰的、600ms のデバウンス + 2秒ごとのバッチフラッシュ）により、呼び出しの間もシンボルインデックスを最新の状態に保ちます。.git、node_modules、.devctx、dist、build、ロックファイル、.min.*、.map、.snap、インデックス対象外の拡張子は除外されます。統計情報は smart_status に表示されます（enabled、flushes、eventsObserved、filesReindexed、filesRemoved、errors、lastFlushAt、pending）。DEVCTX_WATCH_INDEX=false で無効にできます。MCP のシャットダウン処理に接続されており、正常な終了と最終フラッシュを行います。
• Python / Go パーサーの強化と、プラグイン可能なパーサーレジストリ。 Python ではデコレーター（decorators: ["dataclass", ...]）、async def（種類は async-function / async-method）、TypeAlias、TypeVar / NewType / ParamSpec / TypeVarTuple（kind="type"）を取得するようになり、正確なスコープ判定のためにクラスのインデントも考慮します。Go ではレシーバー型を parent としてメソッドを取得するほか、インターフェースを kind="interface" として取得し、トップレベルの const / var にも対応します。src/parsers/registry.js で registerParser / getParser を公開し、index.js に手を加えずに、今後 tree-sitter パーサーを追加できるようになりました。INDEX_VERSION を6から7に引き上げました（自動で再インデックスされます）。
• smart_search でのローカルなセマンティック再ランキング。 オプトインで semantic: true（semanticLimit と併用）を指定すると、ハッシュ化 / TF-IDF 埋め込みによって順位付けされた semantic: { embedder, symbols[], files[] } ブロックを返します（256次元、FNV-1a バケット、L2 正規化、コサイン類似度、5ms 未満）。デフォルトの動作は変わりません。プラグイン可能な埋め込みインターフェース（id、dimensions、embed、similarity）を備えており、呼び出し側を変更せずに ONNX / transformers に切り替えられます。
• global_memory（新しいツール、オプトイン）。 プロジェクトをまたぐメモリを ~/.devctx/global.db に永続化します（DEVCTX_GLOBAL_DB で変更可能。DEVCTX_GLOBAL_MEMORY=true が必要です）。リポジトリをまたいで、確定した意思決定、繰り返し現れるパターン、プレイブックの草案、メモを保存します。永続化する前に、API キー / ベアラートークン / JWT / PEM 秘密鍵 / AWS / OpenAI / GitHub / Slack / Google API / DB URL / メールアドレス / ホームディレクトリのパスらしき内容を除去します。プロジェクトのパスはそのまま保存せず、FNV-1a ハッシュとして保存します。想起時の順位付けには、ローカルのハッシュ化 / TF-IDF 埋め込みを使用します。

v1.21.0 と v1.20.0 の全項目については、CHANGELOG.md をご覧ください。

全リリースの履歴については、CHANGELOG.md をご覧ください。

使用する場合（および使用しない場合）

devctx を使用する場合：

• 不慣れなコードベースを調査している
• タスクが複数のセッションにまたがる（チェックポイントでコンテキストを保存できます）
• ファイル同士の関係（グラフ／インポート）を理解する必要がある
• コンテキストが大きすぎて手動で管理できない
• 複雑な複数ファイルのリファクタリングや、レイヤーをまたぐデバッグを行っている

devctx を使用しない場合：

• 変更するファイルがすでに正確にわかっている
• 単一ファイルへの変更、またはピンポイントな変更である（編集は最大 2～3 箇所）
• 最近の調査ですでに全体像を把握している
• タスクには標準ツール（Grep、Read、StrReplace）のほうが直接的である

実際のユーザーによる率直な評価：

「MCP は、長期にわたる複数セッションのタスクや、コードベースを把握していない場合に真価を発揮します。変更箇所がすでにわかっている範囲の限られたリファクタリングなら、標準ツールも同じくらい速いか、それ以上に速いです。実際に価値があったのは、初期分析に使う smart_read(outline) と、セッション間で流れを見失わないためのチェックポイントでした。」

トークンを 90% 削減できるのは事実ですが、その効果を得るにはタスクの種類が適切である必要があります。

なぜ存在するのか

AI エージェントは、次の 3 つの理由でトークンを無駄にします。

1. 構造や特定の関数だけが必要なのに、ファイル全体を読む
2. 関係のない一致が何百件も含まれる膨大な検索結果
3. 会話のターンをまたいでコンテキストを繰り返す

この MCP は、圧縮され、順位付けされ、キャッシュされたコンテキストを返すツールを提供することで、これら 3 つすべてを解決します。

🚨 エージェントが devctx を無視した場合 → 次にこれを貼り付けてください

Use smart-context-mcp for this task.
Start with smart_turn(start), then use smart_context or smart_search before reading full files.
End with smart_turn(end) if you make progress.

Use devctx: smart_turn(start) → smart_context → smart_turn(end)

使用するタイミング： エージェントが Read で大きなファイルを読んだ、Grep を繰り返し使用した、または複雑なタスクで devctx ツールが使われていない場合。

こうなる理由： タスクが簡単に見えた、インデックスが構築されていなかった、標準ツールのほうが直接的に見えた、またはルールの指示が十分に強くなかったためです。

クイックスタート：どのクライアントを使えばよいですか？

🎯 迷ったら Cursor：最適な標準設定

次の場合に使用： Cursor IDE を使っており、適切なガイダンスと柔軟性の両立を求めている場合。

ワークフロー：

1. Install MCP → rules auto-load
2. Start task → agent reads .cursorrules
3. Agent decides when to use devctx
4. Use /prompt commands to force usage if needed

自動化レベル： デフォルトでは中程度です。タスクランナーのワークフローで、支援用ランチャー ./.devctx/bin/cursor-devctx を使用すると、中～高程度になります。

🔄 継続性を重視するなら Claude Desktop：最適な継続性

次の場合に使用： 自動的なコンテキスト復元による、セッションの継続性を最も重視する場合。

ワークフロー：

1. Install MCP + hooks
2. Start task → hook auto-triggers smart_turn(start)
3. Work with devctx tools
4. End task → hook auto-triggers smart_turn(end)

自動化レベル： 高（フック使用時）— セッションの開始／終了時に smart_turn を自動的に呼び出せます。

💻 ターミナルを使うなら Codex CLI / Qwen Code：最適なターミナル環境

次の場合に使用： ターミナルベースのワークフローやスクリプトを好む場合。

ワークフロー：

1. Install MCP
2. Rules embedded in prompts
3. Agent reads rules, decides when to use
4. Explicit instructions work best

自動化レベル： 低～中程度 — ルールは表示されますが、明示的な指示が必要です。

📊 クイック比較

重要： devctx を使用するかどうかは、常にエージェントが判断します。ルールによって使用の可能性は高まりますが、使用が保証されるわけではありません。

より再現性の高い方法を使う場合： ルールだけに頼るのではなく、タスクランナーまたは支援用ランチャーを使用してください。タスクランナーのワークフローを参照してください。

📖 セットアップの詳細： クライアントの互換性

🚀 MCP の呼び出し方

重要なポイント： MCP がプロンプトを自動的にインターセプトすることはありません。エージェントに MCP を使用するよう伝える必要があります。

1️⃣ MCP プロンプトを使用する（最も簡単 — Cursor のみ）

/prompt use-devctx

[Your task here]

その他のプロンプト：

• /prompt devctx-workflow — 完全なワークフロー
• /prompt devctx-preflight — インデックスを構築してセッションを開始

2️⃣ 明示的に指示する（すべてのクライアント）

Use smart_turn(start) to recover context, then [your task]

CLI でよりガイド付きの手順を使う場合：

smart-context-task task --prompt "your task"
smart-context-task implement --prompt "your task"
smart-context-task continue --session-id <session-id>
smart-context-task doctor

3️⃣ ルールで自動化する（保証なし）

ルールが有効な場合、複雑なタスクではエージェントが devctx を使用するはずです。

• Cursor：.cursorrules
• Claude Desktop：CLAUDE.md
• その他：AGENTS.md

ただし： エージェントはタスクの複雑さに基づいて判断します。

⚡ クイックリファレンス

推奨ワークフロー

✅ セットアップチェックリスト（プロジェクトで初めて使う場合）

複雑なタスクを始める前に、次の点を確認してください。

# 1. MCP is installed
npm list -g smart-context-mcp  # or check your MCP client

# 2. Build the index (IMPORTANT)
npm run build-index
# or tell the agent: "Run build_index tool"

# 3. Rules are active
# - Cursor: .cursorrules exists
# - Claude Desktop: CLAUDE.md exists
# - Other clients: AGENTS.md exists

# 4. Start with smart_turn
# Tell the agent: "Use smart_turn(start) to begin"

エージェントにコピーして貼り付けてください（初回のみ）：

Run build_index, then use smart_turn(start) to begin this task.

⚠️ インデックスが重要な理由

インデックスがない場合：

• ❌ smart_search は順位付けされていない結果を返します
• ❌ smart_context は最適なコンテキストを構築できません
• ❌ エージェントがネイティブツールを優先し、節約できない場合があります

インデックスがある場合：

• ✅ smart_search が関連性に基づいて順位付けします
• ✅ smart_context に関連ファイルが含まれます
• ✅ トークンを 90% 節約できます

再構築するタイミング：

• ✅ プロジェクトで初めて使うとき
• ✅ 大規模なリファクタリングの後（ファイルの移動、名前変更など）
• ✅ 多数の新しいファイルを追加した後
• ❌ 毎回のセッションでは不要です（インデックスは .devctx/ に保持されます）

エントリーポイント：smart_turn(start)

複雑なタスク（デバッグ、レビュー、リファクタリング、テスト、アーキテクチャ）では、次のフローが最適です。

0. build_index (if first time in project)
   ↓ enables search ranking and context quality
   
1. smart_turn(start, userPrompt, ensureSession=true)
   ↓ recovers previous context, classifies task, checks repo safety
   
2. smart_context(...) or smart_search(intent=...)
   ↓ builds context or finds relevant code
   
3. smart_read(mode=outline|signatures|symbol)
   ↓ reads compressed, cascades to full only if needed
   
4. [work: make changes, analyze, review]
   
5. smart_shell('npm test')
   ↓ verifies changes safely
   
6. smart_turn(end, event=milestone|blocker|task_complete)
   ↓ checkpoints progress for recovery

smart_turn から始める理由

• ✅ 前のタスクのチェックポイント（目標、ステータス、決定事項）を復元します
• ✅ タスクの続行か新規開始かを判別します
• ✅ リポジトリの安全性チェックを行います
• ✅ 中断された場合にタスクを復旧できます
• ✅ 最適化に役立つメトリクスを追跡します

smart_turn を省略するケース：

• ❌ 簡単なタスク（単一ファイルを読む、簡単な検索など）
• ❌ 一度限りの質問（継続性が不要な場合）
• ❌ 簡易診断（セッションのコンテキストが不要な場合）

製品のエントリーポイント：smart-context-task

同じライフサイクルを名前付きワークフローとして利用する場合は、タスクランナーを使います。

smart-context-task task --prompt "inspect the auth flow and continue the bugfix"
smart-context-task implement --prompt "add a token guard to loginHandler"
smart-context-task review --prompt "review the latest diff"
smart-context-task doctor

このレイヤーは、同じ smart_turn(start)／コンテキスト／チェックポイントのフローを実行し、さらに次の機能を追加します。

• ワークフロー固有の事前確認（smart_context または smart_search）
• 継続性を考慮したプロンプトのガイダンス
• ブロック状態から smart_doctor へのルーティング
• task_runner の品質シグナルの測定

すべてのコマンドとクライアント固有の使い方については、タスクランナーのワークフローを参照してください。

実際の動作

実情

この MCP は、プロンプトを魔法のように傍受することはありません。実際には次のように動作します。

1. プロンプトを入力します：「ログインのバグを修正して」
2. **エージェントがルールを読みます：**デバッグワークフローの提案を確認します
3. エージェントが判断します：「これはデバッグタスクなので、まず smart_turn(start) を実行します」
4. エージェントが呼び出します：smart_turn({ phase: 'start', userPrompt: '...', ensureSession: true })
5. **MCP が返します：**前のタスクのチェックポイント（存在する場合）とリポジトリの安全性チェック
6. **エージェントが続行します：**エラー箇所を特定するために smart_search(intent=debug) を呼び出します
7. **エージェントが読み取ります：**特定の関数について smart_read(mode=symbol) を呼び出します
8. **エージェントがバグを修正します：**変更を加えます
9. エージェントが検証します：smart_shell('npm test') を呼び出します
10. **エージェントがチェックポイントを作成します：**進捗を保存するために smart_turn(end) を呼び出します

要点：

• ✅ エージェントは devctx ツールを使うかどうかを選択します（強制ではありません）
• ✅ ルールはエージェントをガイドします（強制するものではありません）
• ✅ smart_turn(start) は、複雑なタスクの推奨エントリーポイントです
• ✅ 簡単なタスクでは、エージェントはワークフローを省略できます
• ✅ あなたが直接何かを制御することはなく、エージェントが判断します

得られるもの

ツール（22 個）： 組み込み操作の効率的な代替手段

• smart_read / smart_read_batch - 圧縮ファイル読み込み（概要、シグネチャ、シンボル、解説）
• smart_search - ランキング、ADR フィルタリング、オプトインのセマンティック再ランキングに対応した、意図を考慮するコード検索
• smart_context - グラフと paths: { from, to } のトラバーサルを使って、1 回の呼び出しでコンテキストを構築
• smart_test - グラフ、サンドボックス化されたランナー、永続化された last_failure による影響を受けるテストの特定
• smart_review - コードレビューの事前確認：差分、呼び出し元、ヒューリスティックな検出結果
• smart_code - シンボル名によるセマンティックナビゲーション：定義、参照、実装、診断、影響、ドライランの名前変更
• smart_output - 永続出力ストア（シェル／テスト／ビルド／lint／差分）：再実行せずに検索、抜粋、要約
• smart_playbook - 宣言型の複合ワークフロー（組み込み 5 種：preflight-merge、debug-flake、refactor-safe、doc-sync、ramp-up）
• smart_shell - 安全な診断コマンド（TAP／git-log／差分の圧縮）
• smart_turn / smart_resume - セッションの永続化と、機械可読な計画 nextActions[]
• smart_summary / smart_status / smart_doctor / smart_metrics / smart_edit
• global_memory - ~/.devctx/global.db に保存する、オプトインのプロジェクト横断メモリ（機密情報を除去し、セマンティック検索で想起）
• build_index / warm_cache / git_blame / cross_project

ルール（5 つのプロファイル）： タスク固有のワークフロー

• デバッグ：エラー優先、シンボル重視
• コードレビュー：差分を考慮、API 重視
• リファクタリング：グラフを考慮、テストで検証
• テスト：カバレッジを考慮、TDD に適合
• アーキテクチャ：インデックス優先、詳細は最小限

ストレージ（.devctx/）： ローカルコンテキストデータベース

• index.json - シンボルインデックス（関数、クラス、インポート、ADR、セクション）— INDEX_VERSION 7
• state.sqlite - セッション、メトリクス、パターン、タスクの引き継ぎ、テスト失敗、解説／読み込みキャッシュ、永続化された出力（Node 22+、node:sqlite、スキーマ 9）
• metrics.jsonl - オプトインのレガシーファイル。DEVCTX_METRICS_FILE=path.jsonl が設定されている場合のみ使用
• ~/.devctx/global.db - プロジェクト横断メモリ（DEVCTX_GLOBAL_MEMORY=true によるオプトイン）

永続タスクコンテキスト（対応している場合）

永続化されるもの：

• タスクのチェックポイント（目標、ステータス、決定事項、阻害要因）
• ファイルアクセスのパターン（予測用）
• トークンのメトリクス（最適化用）
• セッションの要約（約 100 トークンに圧縮）

参照されるタイミング：

• エージェントが smart_turn(start) を呼び出す - タスクのチェックポイントを復元
• エージェントが smart_context を呼び出す - パターンを予測に利用
• エージェントが smart_summary を呼び出す - タスクの要約を取得

永続化されないもの：

• ❌ 会話の完全な記録
• ❌ メッセージ履歴全体
• ❌ エージェントの推論や思考
• ❌ ユーザーのプロンプトそのまま

制限事項：

• エージェントが smart_turn を呼び出した場合にのみ機能します（自動ではありません）
• プロジェクト内でのみ永続化されます（.devctx/ はローカルです）
• セッション ID が一致した場合にのみ復元されます（手動または自動）
• クライアントが MCP に対応している必要があります（Cursor、Codex、Claude Desktop、Qwen）

率直に言うと： タスクコンテキストの永続化は、クライアントによる割り込みで自動的に行われるのではなく、エージェントの動作によるオプトインです。

これが意味すること

最良のケース：

• エージェントが一貫してルールに従う
• 操作の 50～80% で devctx ツールを使用する
• トークン使用量が 85～90% 減少する（実証済み、測定済み）
• 処理するデータが減るため、応答が速くなることが多い（トークン削減からの推定）

一般的なケース：

• エージェントが複雑なタスクで devctx ツールを使用する
• 単純なタスクでは組み込みツールを使用する
• トークン使用量が 60～80% 減少する
• 効率の改善を実感できる

最悪のケース：

• エージェントがルールを無視する（まれですが、起こり得ます）
• 組み込みツールのみを使用する
• トークン使用量に変化がない
• 害はありません（MCP は受動的です）

確認方法： npm run report:metrics を実行すると、実際のツール使用状況と測定された smart_turn の品質指標が表示されます。

「より良いコンテキスト」とは

改善する点：

• ✅ コンテキストの関連性（タスクに適したファイル）
• ✅ シグナル対ノイズ比（定型的な内容を減らし、有用な情報を増やす）
• ✅ コンテキスト効率（より関連性の高い情報を、より少ない容量で提供）
• ✅ 応答速度（処理するデータを減らす）

保証しない点：

• ❌ エージェントが常に正しいこと
• ❌ 応答が完璧であること
• ❌ タスクが常に成功すること
• ❌ 応答が「より正確」になること（正確さはコンテキストだけでなく、エージェントにも左右されます）

メリット： エージェントはより良い入力を使って作業できますが、出力の品質は引き続きエージェントの能力とタスクの複雑さに左右されます。

誠実な主張： ワークフローに従った場合、複雑なタスクでエージェントがより効率的に応答する助けとなり得る、より良いコンテキスト（関連性が高く、ノイズが少ないコンテキスト）を提供します。

実証済みの内容： トークンを90％削減（3,666件の操作を対象に測定）。
推定される内容： 品質の向上（より良い入力 → より良い出力につながる可能性がありますが、明示的には測定されていません）。
制御できない内容： エージェントの正確さ、タスクの成功、応答の正確さ。

ワークフローの例

デバッグ

// 1. Start session
smart_turn({ 
  phase: 'start', 
  userPrompt: 'TypeError: Cannot read property "user" of undefined',
  ensureSession: true 
})
// → Recovers: "Last worked on auth system, checked validateToken()"

// 2. Find error
smart_search({ 
  query: 'TypeError user undefined',
  intent: 'debug'
})
// → Returns: src/auth.js (error handling), src/routes/login.js (recent change)

// 3. Read structure
smart_read({ 
  filePath: 'src/routes/login.js',
  mode: 'signatures'
})
// → Returns: loginHandler, validateCredentials, generateToken

// 4. Extract failing function
smart_read({ 
  filePath: 'src/routes/login.js',
  mode: 'symbol',
  symbol: 'loginHandler'
})
// → Returns: Full function code (250 tokens vs 5K for full file)

// 5. Reproduce error
smart_shell({ command: 'npm test -- login.test.js' })
// → Returns: Test failure output

// [Fix bug]

// 6. Verify fix
smart_shell({ command: 'npm test -- login.test.js' })
// → Returns: Tests pass

// 7. Checkpoint
smart_turn({ 
  phase: 'end',
  event: 'milestone',
  summary: 'Fixed TypeError in loginHandler - null check added',
  nextStep: 'Consider adding integration tests'
})

トークン使用量： 150K → 15K（90％削減）

コードレビュー

// 1. Start session
smart_turn({ 
  phase: 'start',
  userPrompt: 'Review PR #123 - Add JWT refresh token support',
  ensureSession: true
})

// 2. Get changed files context
smart_context({ 
  diff: true,
  detail: 'balanced'
})
// → Returns: Changed files with graph, prioritizes API surface

// 3. Review API surface
smart_read({ 
  filePath: 'src/auth.js',
  mode: 'signatures'
})
// → Returns: Exported functions only

// 4. Check implementation
smart_read({ 
  filePath: 'src/auth.js',
  mode: 'symbol',
  symbol: 'refreshToken'
})

// 5. Check authorship
git_blame({ 
  mode: 'symbol',
  filePath: 'src/auth.js'
})
// → Returns: Who wrote each function

// 6. Verify tests
smart_shell({ command: 'npm test' })

// 7. Checkpoint
smart_turn({ 
  phase: 'end',
  event: 'milestone',
  summary: 'PR #123 approved - JWT refresh implemented correctly',
  nextStep: 'Monitor production metrics after deploy'
})

トークン使用量： 200K → 25K（87％削減）

リファクタリング

// 1. Start session
smart_turn({ 
  phase: 'start',
  userPrompt: 'Extract authentication logic into separate service',
  ensureSession: true
})

// 2. Build dependency graph
smart_context({ 
  entryFile: 'src/routes/login.js',
  detail: 'balanced'
})
// → Returns: Dependencies, imports, exports

// 3. Understand current structure
smart_read({ 
  filePath: 'src/routes/login.js',
  mode: 'signatures'
})

// 4. Extract target function
smart_read({ 
  filePath: 'src/routes/login.js',
  mode: 'symbol',
  symbol: 'validateCredentials'
})

// 5. Check authorship
git_blame({ 
  mode: 'symbol',
  filePath: 'src/routes/login.js'
})

// [Refactor: create src/services/auth.js, move logic]

// 6. Verify tests still pass
smart_shell({ command: 'npm test' })

// 7. Checkpoint
smart_turn({ 
  phase: 'end',
  event: 'milestone',
  summary: 'Extracted auth logic to AuthService - tests pass',
  nextStep: 'Update other routes to use AuthService'
})

トークン使用量： 180K → 20K（89％削減）

テスト

// 1. Start session
smart_turn({ 
  phase: 'start',
  userPrompt: 'Write tests for validateToken function',
  ensureSession: true
})

// 2. Find existing test patterns
smart_search({ 
  query: 'validateToken test',
  intent: 'tests'
})
// → Returns: Existing test files, test patterns

// 3. Read function to test
smart_read({ 
  filePath: 'src/auth.js',
  mode: 'symbol',
  symbol: 'validateToken'
})

// 4. Understand dependencies
smart_context({ 
  entryFile: 'src/auth.js',
  detail: 'minimal'
})
// → Returns: Dependencies (jwt, bcrypt, db)

// [Write test]

// 5. Run tests
smart_shell({ command: 'npm test -- auth.test.js' })

// 6. Checkpoint
smart_turn({ 
  phase: 'end',
  event: 'milestone',
  summary: 'Added 5 tests for validateToken - all pass',
  nextStep: 'Add edge case tests for expired tokens'
})

トークン使用量： 120K → 12K（90％削減）

アーキテクチャの調査

// 1. Start session
smart_turn({ 
  phase: 'start',
  userPrompt: 'Understand how authentication works in this codebase',
  ensureSession: true
})

// 2. Get high-level overview
smart_context({ 
  detail: 'minimal'
})
// → Returns: Project structure, key modules

// 3. Find auth-related code
smart_search({ 
  query: 'authentication authorization',
  intent: 'explore'
})
// → Returns: Ranked files by relevance

// 4. Review API surface
smart_read({ 
  filePath: 'src/auth.js',
  mode: 'signatures'
})
// → Returns: Exported functions only

// 5. Check cross-project patterns (if monorepo)
cross_project({ 
  mode: 'search',
  query: 'AuthService'
})
// → Returns: Similar auth patterns in other projects

// 6. Checkpoint
smart_turn({ 
  phase: 'end',
  event: 'milestone',
  summary: 'Auth uses JWT with 1h expiry, refresh tokens in Redis',
  nextStep: 'Document auth flow in architecture.md'
})

トークン使用量： 300K → 30K（90％削減）

コアツール

まず理解しておくべき重要なツールを紹介します。

smart_read

ファイル全体を読み込む代わりに、圧縮モードでファイルを読み取ります。

// Outline mode: structure only (~90% savings)
{ filePath: 'src/server.js', mode: 'outline' }

// Signatures mode: exported API only
{ filePath: 'src/api.js', mode: 'signatures' }

// Symbol mode: extract specific function/class
{ filePath: 'src/auth.js', mode: 'symbol', symbol: 'validateToken' }

モード： outline、signatures、symbol、range、full

使用する場面： ファイルの内容をすべて読まずに構造を把握したいとき。

smart_search

意図を考慮したコード検索を行い、順位付けおよび重複排除された結果を返し、インデックスによるブーストを適用します。

// Find where a symbol is used
{ query: 'validateToken', intent: 'implementation' }

// Debug intent: prioritizes errors, logs, exception handling
{ query: 'authentication error', intent: 'debug' }

// Limit results
{ query: 'UserModel', maxFiles: 5 }

検索意図： implementation、debug、tests、config、docs、explore

特に適している用途： シンボルの定義や使用箇所の検索、呼び出しチェーンの把握、実装箇所の特定。

あまり適していない用途： 完全一致検索（Grep を使用）、名前によるファイル検索（Glob を使用）、複数の単語を含む広範なクエリ（ノイズが発生します。30件を超えるファイルが一致すると、結果にヒントが含まれます）。

smart_context

1回の呼び出しでコンテキストを構築します：検索 + 読み取り + グラフの展開。

{
  task: 'Fix login authentication bug',
  detail: 'balanced'  // minimal | balanced | deep
}

圧縮された内容、シンボルの詳細、関連性グラフを含む、関連ファイルを返します。

スマートパターン検出： タスク内のリテラルパターン（TODO、FIXME、/**、console.log、debugger）を自動的に検出し、検索結果で優先します。

使用する場面： 新しいタスクを始めるときに、包括的なコンテキストが必要な場合。

build_index

プロジェクトのシンボルインデックス（関数、クラス、インポート）を作成します。

{ incremental: true }  // Only reindex changed files

使用する場面： チェックアウト後に一度、または大きな変更を加えた後に実行します。検索の順位付けとコンテキストの関連性が向上します。

smart_metrics

トークン削減量と使用統計を確認します。

{ window: '24h' }  // or '7d', '30d', 'all'

使用する場面： MCP が動作していることを確認し、実際の削減量を確認するとき。

高度なツール

これらのツールは、特定のワークフローに特化した機能を提供します。

smart_summary

セッションをまたいで圧縮されたタスク状態を維持します。

// Save checkpoint (flat API - recommended)
{ action: 'update', goal: '...', status: 'in_progress', nextStep: '...' }

// Or nested format (backward compatible)
{ action: 'update', update: { goal: '...', status: 'in_progress', nextStep: '...' }}

// Resume later
{ action: 'get' }

タスクのコンテキスト（目標、状態、決定事項、ブロッカー）を約100トークンに圧縮します。長時間にわたるタスクで重要です。フラット形式とネスト形式の両方をサポートします。 Git の衛生状態や SQLite の健全性がローカル状態に影響する場合、応答には mutationSafety、repoSafety、degradedMode、storageHealth も表示されます。

smart_doctor

リポジトリの衛生状態、SQLite の健全性、圧縮、レガシーのクリーンアップを対象に、運用前チェックを一度に実行します。

smart_doctor({})
smart_doctor({ verifyIntegrity: false })

リリース前、ローカルで長期間使用した後、または .devctx/state.sqlite に問題がありそうなときに実行してください。

smart_status

進捗を確認できる形で、現在のセッションコンテキストを表示します。

{ format: 'detailed' }  // Full formatted output with emojis
{ format: 'compact' }   // Minimal JSON

目標、ステータス、最近の決定事項、変更したファイル、固定されたコンテキスト、進捗統計を表示します。MCP 操作のたびに自動更新されます。 リポジトリの安全性や SQLite の健全性が状態に影響する場合でも、smart_status は縮退モードで引き続き有用であり、smart_turn と同じ mutationSafety コントラクトに加えて storageHealth も表示します。

smart_edit

パターン置換によって複数ファイルを一括編集します。

{
  pattern: 'console.log',
  replacement: 'logger.info',
  files: ['src/a.js', 'src/b.js'],
  mode: 'literal'  // or 'regex'
}

プレビューには dryRun: true を指定できます。大規模なリファクタリング、パターンの削除、ファイル間の名前変更に便利です。

smart_turn

タスクのチェックポイントを自動的に復旧しながら、ターンの開始と終了を調整します。

{ phase: 'start', prompt: '...' }  // Recovers task checkpoint
{ phase: 'end', event: 'milestone', update: {...} }  // Saves checkpoint

会話履歴全体ではなく、タスクの状態（目標、ステータス、決定事項、次のステップ）を復旧します。

smart_read_batch

1 回の呼び出しで複数のファイルを読み取ります。

{
  files: [
    { path: 'src/a.js', mode: 'outline' },
    { path: 'src/b.js', mode: 'signatures' }
  ]
}

複数のファイルが必要だと分かっている場合に、往復のレイテンシを削減します。

smart_shell

安全な診断コマンドの実行（許可リストに登録されたコマンドのみ）。

{ command: 'git status' }

設計上、シェル演算子と危険なコマンドはブロックされます。

差分を考慮したコンテキスト

Git の変更をインテリジェントに分析します（smart_context の機能の一部）。

{ task: 'Review changes', diff: 'main' }

変更の影響度に基づいて優先順位を付けた変更ファイルと、関連ファイル（テスト、インポーター）を返します。

コンテキスト予測

使用パターンから学習し、必要なファイルを予測します（smart_context の機能の一部）。

{ task: 'Implement authentication', prefetch: true }

類似タスクを 3 回以上実行すると、往復が 40〜60％減少し、さらに 15〜20％の節約につながります。

warm_cache

頻繁にアクセスするファイルを OS キャッシュに事前読み込みします。

{}  // No parameters

初回クエリ：250ms → 50ms（コールドスタートが 5 倍高速）。

git_blame

関数単位でコードの作成者を特定します。

// Who wrote each function?
{ mode: 'symbol', filePath: 'src/server.js' }

// Find code by author
{ mode: 'author', authorQuery: '[email protected]' }

// Recent changes
{ mode: 'recent', daysBack: 7 }

cross_project

モノレポやマイクロサービス間でコンテキストを共有します。

// Search all related projects
{ mode: 'search', query: 'AuthService' }

// Find symbol across projects
{ mode: 'symbol', symbolName: 'validateToken' }

.devctx-projects.json 設定ファイルが必要です。

クライアントの互換性

凡例：

• 🟢 高：フックが特定のタイミングでツールを自動起動できます
• 🟡 中／低：エージェントがルールを読み、ツールを使うタイミングを判断します
• ✅ 対応 | ⚠️ 一部対応 | ❌ 非対応

「ほぼ自動」の意味

🟢 高（フックを備えた Claude Desktop）：

• セッション開始時に、フックが smart_turn(start) を自動起動できます
• 重要なツールの使用後に、フックがチェックポイントを自動作成できます
• 各タスクでどの devctx ツールを使うかは、引き続きエージェントが判断します
• 利用可能な範囲で、これが最も「自動」に近い動作です

🟡 中（Cursor）：

• エージェントがベースルールを自動的に読み込みます（常時有効、150 トークン）
• 条件付きプロファイルは、ファイルの glob パターンに基づいて有効になります（デバッグ、レビューなど）
• タスクに応じて devctx ツールを使うタイミングは、エージェントが判断します
• smart_turn はエージェントが手動で呼び出す必要があります（自動起動されません）

🟡 低〜中（Codex、Qwen）：

• エージェントが埋め込みルールを自動的に読み込みます（常時有効、200 トークン）
• タスクに応じて devctx ツールを使うタイミングは、エージェントが判断します
• smart_turn はエージェントが手動で呼び出す必要があります（自動起動されません）
• 条件付きの有効化やフックはありません

「ほぼ自動」が意味しないこと

❌ プロンプトの自動インターセプトではありません - MCP は、エージェントがプロンプトを見る前に、そのプロンプトをインターセプトしたり変更したりできません
❌ ツールの強制使用ではありません - エージェントは、どのツールを使うかを常に自律的に決定できます
❌ ワークフローが保証されるわけではありません - エージェントは簡単なタスクでは devctx ツールを使わないことがあります（問題ありません）
❌ クライアント側の魔法ではありません - 動作は、エージェントがルールに従い、適切な判断をするかどうかに左右されます

実際の動作

すべてのクライアントは同じように動作します：

1. エージェントがルールを読みます（devctx ツールが役立つ場面についてのガイダンス）
2. エージェントがツールの使用を判断します（最適な方法を選ぶ自律性があります）
3. MCP がツールを提供します（受動的で、呼び出されたときだけ応答します）
4. メトリクスで確認します（npm run report:metrics）

違い：

• フック（Claude Desktop）は、特定のタイミングで特定のツールを自動的に起動できます（例：セッション開始時に smart_turn(start) を実行）
• 条件付きルール（Cursor）は固定のコンテキストコストを抑え、関連する場合にタスク固有のプロファイルを有効にします
• 埋め込みルール（Codex、Qwen）はシンプルで常に有効であり、どこでも機能します

どのクライアントを使うべきですか？

次の場合は Cursor を選んでください：

• ✅ 固定のコンテキストコストを最小限に抑えたい（ベース 150 トークン ＋ プロファイル有効時に 120 トークン）
• ✅ 複雑な複数ファイルのタスク（デバッグ、リファクタリング、アーキテクチャ）に取り組む
• ✅ ファイルパターンに基づいて有効になる条件付きルールを使いたい

次の場合は Claude Desktop を選んでください：

• ✅ 最も「自動」に近い動作を求める（フックで smart_turn を自動的に起動できます）
• ✅ 自動チェックポイント機能を備えた、セッションを認識するワークフローを使いたい
• ✅ フックのオプトイン設定を許容できる

次の場合は Codex または Qwen を選んでください：

• ✅ シンプルな埋め込みルールを使いたい（個別の設定ファイルは不要）
• ✅ 軽量なセットアップを好む（単一の AGENTS.md ファイル）
• ✅ smart_turn の手動呼び出しと、条件付き有効化がないことを許容できる

結論： どのクライアントも問題なく動作します。自動化のレベルとシンプルさのどちらを重視するかによって選択してください。

詳しい比較については、クライアント互換性ガイドをご覧ください。

インストール

ステップ 1：MCP サーバーをインストールする

最小構成（すべてのクライアント）

npm install -g smart-context-mcp
npx smart-context-init --target .

AI クライアントを再起動すれば完了です。

インストールを確認する

# Check installed version
npm list -g smart-context-mcp

# Should show: [email protected] (or later)

# Update to latest version
npm update -g smart-context-mcp

# Or reinstall from scratch
npm uninstall -g smart-context-mcp
npm install -g smart-context-mcp

更新後： バイナリはグローバルに更新されますが、各プロジェクトのエージェントルール（.cursorrules、CLAUDE.md、AGENTS.md）はインストール済みバージョンから生成されるため、自動的には更新されません。

最新のルールを適用するには、更新のたびに init を再実行してください：

# Re-apply rules to a project after updating
npx smart-context-init --target /path/to/your/project --clients cursor
# or for all clients
npx smart-context-init --target /path/to/your/project --clients all

その後、AI クライアントを再起動して新しいバージョンを読み込みます。

Cursor

npm install -g smart-context-mcp
npx smart-context-init --target . --clients cursor

Cursor を再起動してください。ツールがエージェントモードに表示されます。

作成されるファイル：

• .cursor/mcp.json - MCP サーバーの設定
• .cursor/rules/devctx.mdc - エージェントの基本ルール（10 行、常に有効）
• .cursor/rules/profiles-compact/*.mdc - タスクプロファイル（条件付き）
• .devctx/bin/cursor-devctx - 長時間のタスク向けの任意の補助ランチャー
• .git/hooks/pre-commit - 安全フック
• .gitignore - .devctx/ を追加

Codex CLI

npm install -g smart-context-mcp
npx smart-context-init --target . --clients codex

Codex を再起動してください。

作成されるファイル：

• .codex/config.toml - MCP サーバーの設定
• AGENTS.md - エージェントルール
• .git/hooks/pre-commit - 安全フック
• .gitignore - .devctx/ を追加

Claude Desktop

npm install -g smart-context-mcp
npx smart-context-init --target . --clients claude

Claude Desktop を再起動してください。

作成されるファイル：

• .mcp.json - MCP サーバーの設定
• .claude/settings.json - フックの設定
• CLAUDE.md - エージェントルール
• .git/hooks/pre-commit - 安全フック
• .gitignore - .devctx/ を追加

Qwen Code

npm install -g smart-context-mcp
npx smart-context-init --target . --clients qwen

Qwen Code を再起動してください。

作成されるファイル：

• .qwen/settings.json - MCP サーバーの設定
• AGENTS.md - エージェントルール
• .git/hooks/pre-commit - 安全フック
• .gitignore - .devctx/ を追加

エージェントルール：秘訣

この MCP の特徴は、タスク固有のエージェント向けガイダンスです。インストールすると、最適なワークフローをエージェントに教えるルールが生成されます。

デバッグプロファイル

smart_turn(start) → smart_search(intent=debug) → smart_read(symbol) → 
smart_shell('npm test') → fix → smart_turn(end)

削減率： 90%（150K → 15K トークン）

コードレビュープロファイル

smart_turn(start) → smart_context(diff=true) → smart_read(signatures) → 
review → smart_turn(end)

削減率： 87%（200K → 25K トークン）

リファクタリングプロファイル

smart_turn(start) → smart_context(entryFile) → smart_read(signatures) → 
refactor → smart_shell('npm test') → smart_turn(end)

削減率： 89%（180K → 20K トークン）

テストプロファイル

smart_turn(start) → smart_search(intent=tests) → smart_read(symbol) → 
write test → smart_shell('npm test') → smart_turn(end)

削減率： 90%（120K → 12K トークン）

アーキテクチャプロファイル

smart_turn(start) → smart_context(detail=minimal) → smart_read(signatures) → 
analyze → smart_turn(end)

削減率： 90%（300K → 30K トークン）

重要なポイント： 価値はツールそのものだけにあるのではなく、エージェントにツールをいつ、どのように使うかを教えることにもあります。

ステップ 2：エージェントルールを設定する（推奨）

エージェントが devctx を自動的に使用するように、クライアントごとのルールを設定します。

Cursor ユーザーの場合

すでに含まれています：プロジェクトに .cursorrules がコミットされています。

動作を確認するには：

• エージェントが devctx の使用ポリシーに言及する
• エージェントが devctx のツールを自動的に使用する
• 長時間のタスクでは、./.devctx/bin/cursor-devctx task --prompt "..." -- <agent-command> を優先する

Claude Desktop ユーザーの場合

プロジェクトのルートに CLAUDE.md を作成します。

# Copy template
cp docs/agent-rules-template.md CLAUDE.md
# Edit to keep only the CLAUDE.md section

または、docs/agent-rules-template.md の内容をコピーします。

その他のエージェントクライアントの場合

同じテンプレートを使用して、プロジェクトのルートに AGENTS.md を作成します。

これらのルールが重要な理由：

• ✅ エージェントが devctx を自動的に使用する（手動で強制する必要がありません）
• ✅ すべてのクライアントで一貫した動作になる
• ✅ devctx の使用時にフィードバックが表示される
• ✅ devctx を使うべきなのに使われていない場合に警告が表示される

完全な設定については、エージェントルールのテンプレートを参照してください。

使用されなかった場合のフィードバック

重要度の高いタスクでエージェントが devctx のツールを使用しない場合、次のメモが追加されます。

Note: devctx not used because: [reason]
To use devctx next time: "Use smart-context-mcp: smart_turn(start) → ..."

これが重要な理由：

• 未使用の状態を可視化する
• devctx が役立つ場面について理解を促す
• 次のターンで使用を促すプロンプトを提示する
• 設定の問題（MCP が利用できない、インデックスが未作成など）を特定する

devctx の使用を促す方法

次のプロンプトを使う場面：

• 重要度の高いタスクでエージェントが devctx を使用しなかった
• 保存されたタスクコンテキストを復元したい
• タスクが複雑である（デバッグ、レビュー、リファクタリング、テスト、アーキテクチャ）

公式プロンプト（ワークフロー全体）：

Use smart-context-mcp for this task:
1. Start with smart_turn(start, userPrompt, ensureSession=true) to recover context
2. Use smart_context or smart_search before reading files
3. Use smart_read(outline|signatures|symbol) instead of full reads
4. Close with smart_turn(end) when you reach a milestone

超短縮プロンプト（コピー＆ペーストですぐ使えます）：

Use devctx: smart_turn(start) → smart_context/smart_search → smart_read → smart_turn(end)

使用例：

User: "Debug the authentication error"
Agent: [uses native tools]
Agent: "Note: devctx not used because: already had sufficient context..."

User: "Use devctx: smart_turn(start) → smart_context/smart_search → smart_read → smart_turn(end)"
Agent: [uses smart_turn, smart_search, smart_read]
Agent: "Found the issue in validateToken()..."

完全なプロファイルについては、agent-rules/を参照してください。

はじめに

1 日目：インストールとインデックスの作成（必須）

1. インストール：

   npm install smart-context-mcp
   npx smart-context-init --target .
   

2. インデックスを作成する（品質確保に必須）：

   npm run build-index
   # or tell agent: "Run build_index tool"
   

   重要な理由： インデックスがないと、smart_search と smart_context の性能が低下します。エージェントがネイティブツールを優先する場合があります。トークンの削減効果はありません。

3. コアツールを使う：

   • ファイル構造には smart_read
   • コードの検索には smart_search
   • 包括的なコンテキストには smart_context
   • 削減効果の確認には smart_metrics

4. エージェントに判断させる： ツールの使用を強制しないでください。生成されたルールによって、エージェントが自然に使えるようになります。

1 週間後：高度なツールを追加する

• 長時間のタスクに取り組む場合は smart_summary
• Claude Code CLI を使用する場合は smart_turn
• コードの帰属を確認するには git_blame
• モノレポで作業する場合は cross_project

1 か月後：最適化する

• smart_metrics で使用パターンを確認する
• コールドスタートが遅い場合は warm_cache を有効にする
• 繰り返し発生するタスクでは、smart_context の prefetch を有効にする

メトリクスと検証

ベンチマークをすべて実行する

npm run benchmark

次の検証スイートをすべて実行します。

• 740 件以上のユニットテスト
• 14 件の機能検証
• 合成コーパスの評価
• 実際のプロジェクトでの評価
• オーケストレーションの回帰ベンチマーク（5 つのコアシナリオ）
• 本番メトリクスレポート

所要時間は 3～4 分です。詳細については、ベンチマークのドキュメントを参照してください。

オーケストレーション品質のリリースゲートは npm run benchmark:orchestration:release でも利用できます。また、prepublishOnly を通じて npm publish の実行時にもこのゲートが適用されるようになりました。

動作を確認する

npm run report:metrics

問題がないことを示す兆候：

• ツールの使用回数が 0 より大きい（エージェントが devctx を使用している）
• 削減率が 60～90%（圧縮が機能している）
• 複数のツールが使用されている（ワークフローが実行されている）

問題を示す兆候：

• ツールの使用回数が 0（エージェントが devctx を使用していない）
• 次を確認してください：ルールはインストール済みですか？ MCP は動作していますか？ タスクの複雑さは十分ですか？

出力例：

devctx metrics report

Entries:      3,696
Raw tokens:   14,492,131
Final tokens: 1,641,051
Saved tokens: 13,024,099 (89.87%)

By tool:
  smart_search   count=692  saved=5,817,485 (95.45%)
  smart_read     count=2108 saved=2,355,809 (70.52%)
  smart_summary  count=449  saved=1,897,628 (97.89%)

Adoption Analysis (Inferred from Tool Usage)

Total sessions:        156
Sessions with devctx:  89 (57%)
Sessions without:      67 (43%)

Non-Trivial Tasks Only:
Total:                 112
With devctx:           78 (70%)
Without devctx:        34 (30%)

By Inferred Complexity:
- complex      56/68 (82%)
- moderate     25/52 (48%)
- simple       8/36 (22%)

When devctx IS used:
Avg tools/session:     2.8
Avg token savings:     146,337 tokens

Top Tools Used:
- smart_read            89 sessions
- smart_search          67 sessions
- smart_context         45 sessions

Limitations:
- Complexity inferred from operation count (not actual task complexity)
- Can only measure when devctx IS used (tool calls visible)
- Cannot measure feedback shown or forcing prompts (requires agent cooperation)
- Sessions without devctx may be simple tasks (not adoption failures)

採用状況の指標（試験的）

指標レポートに採用状況の分析が追加され、devctx が実際にどの程度使用されているかを測定できるようになりました。

測定する内容：

• ✅ devctx のツールが使用されたセッション（ツール呼び出しから自動的に測定）
• ✅ 全体および推定された複雑さ別の採用率
• ✅ セッションごとに使用された上位のツール
• ✅ devctx を使用した場合の平均トークン削減量

測定しない内容：

• ❌ フィードバックの頻度（エージェントからの報告が必要です）
• ❌ フィードバックの理由（エージェントの協力が必要です）
• ❌ プロンプトの使用の強制（指標からは検出できません）
• ❌ 実際のタスクの複雑さ（操作数から推定するのみです）

制限事項：

• 複雑さは実際の複雑さではなく、操作数から推定されます
• devctx が使用された場合のみ測定できます（ツール呼び出しを確認できます）
• エージェントから報告されない限り、未使用であることは検出できません
• devctx が使用されなかったセッションは、失敗ではなく単純なタスクだった可能性があります

役立つ理由：

• devctx が実際に採用されているかを確認できます
• パターン（複雑なタスクほど採用率が高いなど）を特定できます
• ルールやオンボーディングが機能しているかを検証できます
• 圧縮の指標を使用状況の指標で補完できます

詳細な分析については、採用状況の指標の設計を参照してください。

リアルタイム使用状況フィードバック（新機能！）

各エージェントの応答で、devctx ツールの使用状況をすぐに確認できます。

デフォルトで有効 — devctx のツール呼び出しごとにフィードバックが表示されます。

表示が多すぎる場合は無効にできます：

export DEVCTX_SHOW_USAGE=false

表示される内容：

---

📊 **devctx usage this session:**
- **smart_read**: 3 calls | ~45.0K tokens saved (file1.js, file2.js, file3.js)
- **smart_search**: 1 call | ~12.0K tokens saved (query)

**Total saved:** ~57.0K tokens

*To disable this message: `export DEVCTX_SHOW_USAGE=false`*

メリット：

• ✅ エージェントが devctx を使用しているかすぐに確認できます
• ✅ トークン削減量をリアルタイムで確認できます
• ✅ 使用を強制するプロンプトが機能したか検証できます
• ✅ 採用に関する問題をすぐにデバッグできます

使用する場面：

• エージェントがルールに従っているかの確認
• devctx が使用されない理由のデバッグ
• リアルタイムでの効果の測定
• インストール後の設定の検証

詳しいガイドについては、使用状況フィードバックのドキュメントを参照してください。

意思決定の説明（新機能！）

エージェントがなぜdevctx ツールを選んだのか、どのようなメリットが期待されるのかを確認できます。

デフォルトで有効 — devctx のツール呼び出しごとに意思決定の説明が表示されます。

表示が多すぎる場合は無効にできます：

export DEVCTX_EXPLAIN=false

表示される内容：

---

🤖 **Decision explanations:**

**smart_read** (read src/server.js (outline mode))
- **Why:** File is large (2500 lines), outline mode extracts structure only
- **Instead of:** Read (full file)
- **Expected benefit:** ~45.0K tokens saved
- **Context:** 2500 lines, 50000 tokens → 5000 tokens

**smart_search** (search "authentication" (intent: debug))
- **Why:** Intent-aware search prioritizes relevant results
- **Instead of:** Grep (unranked results)
- **Expected benefit:** ~12.0K tokens saved, Better result ranking

*To disable: `export DEVCTX_EXPLAIN=false`*

メリット：

• ✅ エージェントの意思決定を理解できます
• ✅ どのツールをいつ使うかを学べます
• ✅ ツール選択に関する問題をデバッグできます
• ✅ エージェントが適切な選択をしているか検証できます

使用する場面：

• devctx の仕組みを学ぶとき
• 特定のツールが選ばれた理由をデバッグするとき
• エージェントの動作を検証するとき
• ベストプラクティスを理解するとき

使用状況フィードバックと組み合わせると、最大限の可視性が得られます：

export DEVCTX_SHOW_USAGE=true
export DEVCTX_EXPLAIN=true

詳しいガイドについては、意思決定説明のドキュメントを参照してください。

見逃された機会の検出（新機能！）

devctx が使用されるべきだったのに使用されなかった場面を検出します。

デフォルトで有効 — devctx の採用率が低い場合に警告が表示されます。

不要な場合は無効にできます：

export DEVCTX_DETECT_MISSED=false

表示される内容：

---

⚠️ **Missed devctx opportunities detected:**

**Session stats:**
- Duration: 420s
- devctx operations: 2
- Estimated total operations: 25
- devctx adoption: 8%

🟡 **low devctx adoption**
- **Issue:** Low devctx adoption: 2/25 operations (8%). Target: >50%.
- **Suggestion:** Agent may be using native tools. Consider forcing prompt.
- **Potential savings:** ~184.0K tokens

**How to fix:**
1. Use forcing prompt
2. Check if index is built
3. Verify MCP is active

検出する内容：

• 🔴 長時間のセッション（5 分超）で devctx が使用されていない
• 🟡 採用率が低い（操作の 30% 未満）
• 🟡 使用頻度が低下している（3 分超、呼び出しがない）

メリット：

• ✅ 採用の不足を特定できます
• ✅ 削減できた可能性のある量を定量化できます
• ✅ 使用を強制するプロンプトが機能したか検証できます
• ✅ エージェントがネイティブツールに切り替えたことを検出できます

制限事項：

• 操作の合計数は測定値ではなく推定値です
• 単純なタスクでは誤検出が起きる場合があります
• セッション単位でのみ有効です（再起動時にリセットされます）

すべての機能はデフォルトで有効です。すべて無効にするには：

export DEVCTX_SHOW_USAGE=false
export DEVCTX_EXPLAIN=false
export DEVCTX_DETECT_MISSED=false

詳しいガイドについては、見逃された機会のドキュメントを参照してください。

エージェントルール（マルチクライアント対応）

このプロジェクトには、さまざまなクライアントで devctx の使用を徹底するエージェントルールが含まれています。

• Cursor: .cursorrules（Git にコミット済み）
• Claude Desktop: docs/agent-rules-template.md のテンプレートから CLAUDE.md を作成します
• その他のエージェント: docs/agent-rules-template.md のテンプレートから AGENTS.md を作成します

すべてのルールで、同じポリシーを徹底します。

• Read の代わりに smart_read を使用します
• Grep の代わりに smart_search を使用します
• 複数回読み込む代わりに smart_context を使用します
• ネイティブツールを使用した場合は、その理由を説明します

設定手順については、エージェントルールのテンプレートを参照してください。

MCP プロンプト（自動的な使用強制）

MCP サーバーは、使用を強制する指示を自動的に挿入するプロンプトを提供します。

手早く使用を強制する方法：

/prompt use-devctx

次の内容が挿入されます：Use devctx: smart_turn(start) → smart_context/smart_search → smart_read → smart_turn(end)

利用可能なプロンプト：

• /prompt use-devctx - 超短縮版の使用強制プロンプト
• /prompt devctx-workflow - ワークフローの完全なテンプレート
• /prompt devctx-preflight - 事前チェックリスト（インデックス＋セッション初期化）

メリット：

• ✅ 使用強制の構文を覚えたり、入力したりする必要がありません
• ✅ 一元管理されるため、自動的に更新されます
• ✅ Cursor のプロンプトメニューから見つけられます
• ✅ 入力ミスがありません

完全なガイドについては、MCP プロンプトのドキュメントを参照してください。

簡単な確認

npm run verify  # Feature verification (22 tools)
npm test        # Unit tests (740+ tests)
npm run eval    # Synthetic corpus
npm run eval:self  # Real project

トラブルシューティング

エージェントが devctx ツールを使用しない

確認項目：

# 1. Rules installed?
cat .cursor/rules/devctx.mdc

# 2. MCP running?
# Cursor: Settings → MCP → Check "smart-context" active

# 3. Index built?
ls .devctx/index.json

# 4. Metrics show usage?
npm run report:metrics

考えられる原因：

• ルールがインストールされていない → npx smart-context-init --target . を実行します
• MCP が実行されていない → クライアントを再起動します
• インデックスが作成されていない → npm run build-index を実行するか、エージェントに「Run build_index tool」と伝えます
• タスクが単純すぎる → 組み込みツールで十分です（問題ありません）
• エージェントが Ask モードになっている → 読み取り専用で、MCP にアクセスできません

devctx の使用を強制する方法（コピーしてすぐに使えます）：

Use devctx: smart_turn(start) → smart_context/smart_search → smart_read → smart_turn(end)

完全なワークフローについては、devctx の使用を強制する方法を参照してください。

ワークフローの追跡を有効にする

ワークフロー全体（デバッグ、レビュー、リファクタリング、テスト、アーキテクチャ）を追跡するには、次の手順を実行します。

export DEVCTX_WORKFLOW_TRACKING=true

その後、AI クライアントを再起動します。ワークフローのメトリクスを表示するには、次のコマンドを実行します。

npm run report:workflows -- --summary

詳細については、ワークフローのメトリクスを参照してください。

devctx を使用しているのにトークン使用量が多い

確認項目：

npm run report:metrics

次の項目を確認してください：

• ツールの使用率が低い（操作全体の 20% 未満）
• full モードの使用率が高い（エージェントが段階的に処理していない）
• 圧縮率が低い（50% 未満）

考えられる原因：

• エージェントがワークフローに従っていない
• タスクが圧縮のメリットを得られない
• この種類のタスクに対するルールが不明確

コンテキストが保持されない

確認項目：

# 1. Node version (need 22+ for SQLite)
node --version

# 2. SQLite exists?
ls -lh .devctx/state.sqlite

# 3. Agent calling smart_turn?
sqlite3 .devctx/state.sqlite "SELECT COUNT(*) FROM sessions"

考えられる原因：

• Node 18-20 → SQLite を使用できません（22 以降にアップグレードしてください）
• エージェントが smart_turn を呼び出していない → タスクのチェックポイントが作成されません
• セッション ID が一致しない → チェックポイントを復元できません
• .devctx/state.sqlite が追跡対象またはステージ済みになっている → Git の状態が整理されるまで、実行時のコンテキスト書き込みは意図的にブロックされます
• .devctx/state.sqlite がロックされている、破損している、またはサイズ超過している → smart_status または smart_metrics の storageHealth を確認してください
• より広範なローカル状態の事前チェック → smart_doctor または smart-context-doctor --json を実行します

復旧手順：

• missing → smart_summary update や smart_turn end など、状態を永続化する操作を実行します
• oversized → smart_summary compact を実行します
• locked → 競合している devctx プロセスを停止してから、再試行します
• corrupted → .devctx/state.sqlite をバックアップして削除し、devctx にローカル状態を再作成させます

ルールが適用されない

確認項目：

cat .cursor/rules/devctx.mdc  # or AGENTS.md, CLAUDE.md

存在しない場合：

npx smart-context-init --target .

存在するのにエージェントが無視する場合：

• これは想定された動作です（ルールはガイダンスであり、強制するものではありません）
• エージェントはタスクに応じて判断します
• メトリクスで実際の使用状況を確認してください

対応言語

ファーストクラス対応（AST 解析）： JavaScript、TypeScript、JSX、TSX

ヒューリスティック解析： Python、Go、Rust、Java、C#、Kotlin、PHP、Swift

構造抽出： Shell、Terraform、HCL、Dockerfile、SQL、JSON、YAML、TOML

設定

環境変数

# Point to different project
export DEVCTX_PROJECT_ROOT=/path/to/project

# Disable cache warming
export DEVCTX_CACHE_WARMING=false

# Change warm file count
export DEVCTX_WARM_FILES=100

プロジェクト横断の設定

.devctx-projects.json を作成します。

{
  "version": "1.0",
  "projects": [
    { "name": "main-app", "path": ".", "type": "main" },
    { "name": "shared-lib", "path": "../shared-lib", "type": "library" },
    { "name": "api-service", "path": "../api-service", "type": "service" }
  ]
}

各プロジェクトのインデックスを作成します。

cd main-app && npx build-index
cd ../shared-lib && npx build-index
cd ../api-service && npx build-index

ストレージ

すべてのデータは .devctx/ に保存されます。

• index.json - シンボルインデックス（INDEX_VERSION 7：ADR と ADR セクション、拡張された Python/Go 対応）
• state.sqlite - セッション、メトリクス、パターン、タスクの引き継ぎ、テスト失敗、説明キャッシュ（Node 22+）
• metrics.jsonl - オプトインのレガシーファイル。DEVCTX_METRICS_FILE=path.jsonl が設定されている場合のみ使用されます

プロジェクト間で共有（DEVCTX_GLOBAL_MEMORY=true によるオプトイン）：

• ~/.devctx/global.db - スクラブ済みの意思決定、パターン、プレイブック、メモを含む、セマンティック検索用データベース

.gitignore に追加します。

.devctx/

セキュリティ

この MCP はデフォルトで安全です。

• ✅ 許可リストにあるコマンドのみ - 安全な診断コマンド（ls、git status、npm test など）のみ実行できます
• ✅ シェル演算子なし - |、&、;、>、<、`、$() をブロックします
• ✅ パスの検証 - プロジェクトのルート外にはアクセスできません
• ✅ 書き込みアクセスなし - コードを変更できません
• ✅ リポジトリの安全性 - ローカル状態を誤ってコミットするのを防ぎます
• ✅ リソース制限 - タイムアウト 15 秒、バッファー 10MB

smart_shell で実行できるコマンド：

# Allowed
git status              # ✓ Safe git read operations
npm test                # ✓ Safe package manager scripts
find . -name "*.js"     # ✓ File discovery
rg "pattern"            # ✓ Code search

# Blocked
git commit              # ✗ Write operations blocked
npm install pkg         # ✗ Package changes blocked
ls | grep secret        # ✗ Shell operators blocked
rm -rf /                # ✗ Dangerous commands blocked

実際の拒否例：

// Shell operator blocked
smartShell({ command: "ls | grep secret" })
→ { exitCode: 126, blocked: true, output: "Shell operators are not allowed..." }

// Dangerous command blocked
smartShell({ command: "rm -rf /" })
→ { exitCode: 126, blocked: true, output: "Dangerous pattern detected..." }

// Git write blocked
smartShell({ command: "git commit -m 'test'" })
→ { exitCode: 126, blocked: true, output: "Git subcommand not allowed: commit..." }

// Package install blocked
smartShell({ command: "npm install malicious" })
→ { exitCode: 126, blocked: true, output: "Package manager subcommand not allowed: install..." }

検証：

# Run 60+ security tests to verify behavior
cd tools/devctx && npm test -- tests/smart-shell-security.test.js

設定：

# Disable shell execution entirely
export DEVCTX_SHELL_DISABLED=true

# Disable cache warming
export DEVCTX_CACHE_WARMING=false

セキュリティに関するドキュメント一式：

• SECURITY.md - セキュリティポリシーの全文
• セキュリティ拒否の例 - 50 件以上の具体例

要件

• Node.js： 18+（SQLite 機能には 22+ を推奨）
• Git： 差分対応コンテキストと git blame に必要です
• ripgrep： @vscode/ripgrep 経由で同梱（システムへのインストールは不要）

パフォーマンス比較

ドキュメント

機能

• ストリーミング進捗 - リアルタイムの進捗通知
• コンテキスト予測 - インテリジェントなファイル予測
• 差分対応コンテキスト - スマートな変更分析
• キャッシュの事前読み込み - コールドスタートの最適化
• Git Blame - コードの作成者情報
• プロジェクト間コンテキスト - 複数プロジェクトへの対応

セキュリティ

• セキュリティポリシー - セキュリティ保証と脅威モデル
• 脅威モデル - 攻撃対象領域の分析
• セキュリティ設定 - セキュリティ強化とプロファイル

検証

• ベンチマーク - 再現可能なベンチマーク
• E2E テストレポート - 本番環境での使用状況分析
• 検証レポート - 機能の検証
• ワークフローメトリクス - ワークフロー全体の削減効果

開発

• アーキテクチャ - リポジトリ構成と開発ガイド
• コントリビューション - 貢献方法
• 変更履歴 - バージョン履歴

API リファレンス

コアツール

smart_read

{
  filePath: string;
  mode?: 'outline' | 'signatures' | 'symbol' | 'range' | 'full';
  symbol?: string | string[];
  startLine?: number;
  endLine?: number;
  maxTokens?: number;
  context?: boolean;
}

smart_search

{
  query: string;
  intent?: 'implementation' | 'debug' | 'tests' | 'config' | 'docs' | 'explore';
  cwd?: string;
  maxFiles?: number; // 1-50, default 15
}

smart_context

{
  task: string;
  intent?: string;
  detail?: 'minimal' | 'balanced' | 'deep';
  maxTokens?: number;
  entryFile?: string;
  diff?: boolean | string;
  prefetch?: boolean;
  include?: string[];
}

build_index

{
  incremental?: boolean;
  warmCache?: boolean;
}

smart_metrics

{
  window?: '24h' | '7d' | '30d' | 'all';
  tool?: string;
  sessionId?: string;
}

高度なツール

smart_summary

{
  action: 'get' | 'update' | 'append' | 'checkpoint' | 'reset' | 'list_sessions';
  sessionId?: string;
  update?: {
    goal?: string;
    status?: 'planning' | 'in_progress' | 'blocked' | 'completed';
    nextStep?: string;
    completed?: string[];
    decisions?: string[];
  };
  maxTokens?: number;
}

smart_turn

{
  phase: 'start' | 'end';
  prompt?: string;
  event?: string;
  update?: object;
}

smart_read_batch

{
  files: Array<{
    path: string;
    mode?: string;
    symbol?: string;
  }>;
  maxTokens?: number;
}

smart_shell

{
  command: string;
}

warm_cache

{}  // No parameters

git_blame

{
  mode: 'symbol' | 'file' | 'author' | 'recent';
  filePath?: string;
  authorQuery?: string;
  limit?: number;
  daysBack?: number;
}

cross_project

{
  mode: 'discover' | 'search' | 'read' | 'symbol' | 'deps' | 'stats';
  query?: string;
  symbolName?: string;
  maxResultsPerProject?: number;
}

主な機能

• ✅ インテリジェントな圧縮によるトークンの90％削減
• ✅ 共有レイヤーとクライアントアダプターによる自動オーケストレーション
• ✅ SQLite による状態の永続化でセッションを継続
• ✅ ワークフローの追跡（デバッグ、コードレビュー、リファクタリング、テスト、アーキテクチャ）
• ✅ 継続性を考慮したワークフローに対応するタスクランナー CLI
• ✅ クライアント間のベンチマークに対応する比較指標
• ✅ 740 件以上のテストとリリース条件付きベンチマークを備え、本番環境で利用可能

リリース履歴の全容については、CHANGELOG.md をご覧ください。

リポジトリ構成

このリポジトリには、tools/devctx/ に smart-context-mcp npm パッケージが含まれています。

/
├── tools/devctx/          ← Publishable package
│   ├── src/               ← Source code
│   ├── tests/             ← 740+ unit tests
│   ├── evals/             ← Benchmarks & scenarios
│   ├── scripts/           ← CLI binaries
│   └── package.json       ← Package metadata (v1.21.0)
├── docs/                  ← Documentation (GitHub only)
├── .github/workflows/     ← CI/CD with release gating
└── README.md              ← This file

npm に公開される内容： tools/devctx/ の内容のみ（src + scripts）

開発： すべての作業は tools/devctx/ で行います。

開発環境のセットアップについては、CONTRIBUTING.md をご覧ください。

コントリビューション

以下の内容に関するプルリクエストを歓迎します。

• 追加の言語パーサー
• パフォーマンスの最適化
• バグ修正

ガイドラインについては、CONTRIBUTING.md をご覧ください。

作者

Francisco Caballero Portero
メール：[email protected]
GitHub：@Arrayo

ライセンス

MIT ライセンスです。詳細は LICENSE ファイルをご覧ください。

リンク

• GitHub リポジトリ
• npm パッケージ
• 課題トラッカー