運用設計パターン集

claude-configで培った運用知見をNexusCoreの開発・運用に還元する設計パターン集。

§1: ツール使用トラッキング

元資料: claude-config「ツール使用トラッカー」（2026-05-05）

目的

LLM呼び出しやツール使用の頻度を追跡し、コスト最適化の判断材料とする。

NexusCoreでの適用状況

NexusCoreは llm_calls.jsonl ですでにツール使用トラッキングを実装済み:

logs/llm_calls.jsonl
→ ts, task_type, model, provider, mode, input_tokens, output_tokens, cost_est_usd, duration_sec

RoutedLLM.execute() が全呼び出しをJSONLに記録（Phase 1でproviderフィールド追加済み）。

設計パターン

CSVロギング + 集計スクリプト（claude-config実績）:

  1. フック層でツール名・セッションID・タイムスタンプをCSVに追記
  2. 集計スクリプトで日次・時間帯別・ツール別の分布を可視化
  3. トークン直接計測が不可能な環境では、ツール呼び出し回数をコストのプロキシとして利用

NexusCoreでの推奨:

  • llm_calls.jsonl を集計スクリプトの入力として使用
  • provider + mode 別にリアル/スタブ比率を監視
  • レート制限（rate-limited）の発生頻度をフォールバック健全性の指標として活用

コスト監視の指針

指標 取得方法 閾値の目安
1日あたりコスト cost_est_usd の合計 日次上限（デフォルト$5）
リアル/スタブ比率 mode フィールドの集計 スタブ>50%は要調査
429発生率 mode=rate-limited の比率 >10%はフォールバック確認
レスポンス時間 duration_sec の平均 >30秒はプロバイダー確認

§2: ドキュメントINDEX自動更新

元資料: claude-config「INDEX自動更新システム」（2026-05-05）

目的

ドキュメントの新規追加を自動検知し、INDEX.mdの更新漏れを防ぐ。

設計パターン

差分検知 → タグ付与 → 手動キュレーションの3段階ワークフロー:

  1. 検知: セッション開始時にファイル数とINDEX エントリ数を比較
  2. 警告: 差分がある場合「📋 [INDEX差分検知]」を表示
  3. 生成: generate-decision-indexes コマンドで新規ファイルをINDEXに追加（【要更新】タグ付与）
  4. キュレーション: 人間が説明文を記入し、【要更新】タグを除去

NexusCoreへの適用指針

NexusCoreの docs/ は以下の構造を持つ:

docs/
├── api/                  # 60+ completion reports
├── architecture/         # システム設計
├── governance/           # ガバナンス文書
├── testing/              # テストガイド
├── setup/                # 環境セットアップ
├── refactoring/          # リファクタリング計画
└── ...

推奨アプローチ:

  • docs/ 直下に _INDEX.md を配置し、全ファイルの概要を管理
  • CIまたはセッション開始時に差分検知スクリプトを実行
  • 新規ファイル追加時は _INDEX.md の更新をコミット条件に含める

実装のポイント

  • 既存エントリは保持（上書きしない）
  • 新規エントリは「## 新規（要キュレーション）」セクションに追加
  • ファイル数とINDEX数の単純比較で高速に差分検知
  • INDEX更新は手動（自動生成した説明文の品質担保のため）
This site uses Just the Docs, a documentation theme for Jekyll.