llmlb: Instructions file for Claude Code

CLAUDE.md

このファイルは、このリポジトリでコードを扱う際のガイダンスを提供します。 短く「何を・どこを見るか」を示し、詳細は既存ドキュメントに段階的に委譲します （参考: Writing a good CLAUDE.md）。

まず読む 90秒版

• 何を作る: Rust製ロードバランサー（llmlb/）＋ llama.cppベースのC++推論エンジン（xLLM: https://github.com/akiojin/xLLM）。Ollamaは一切使わない／復活させない。
• どこを見る: README.md（全体像）→ DEVELOPMENT.md（セットアップ）→ GitHub Issue（gwt-specラベル、要件とタスク）。
• 守る: ブランチ／worktree作成・切替禁止、作業ディレクトリ移動禁止、必ずローカルで全テスト実行。
• HFカタログ利用時はHF_TOKEN（任意）と必要に応じHF_BASE_URLを環境にセットしておく。
• まず実行: make quality-checks（CI 相当の検証集合は Makefile の quality-checks ターゲットが定義する）。
• 迷ったら: memory/constitution.mdとこのファイル後半の詳細ルールを再確認。
• セッション開始時: memory/lessons.md を確認し、過去の修正パターンを踏まえて作業する。
• 回答は日本語で行う。

ディレクトリ構成

llmlb/
├── llmlb/          # Rust製ロードバランサー（APIサーバー・管理UI・共通型定義）
├── xLLM (external)  # <https://github.com/akiojin/xLLM>
├── scripts/         # プロジェクトスクリプト（checks等）
├── memory/          # プロジェクト憲章・メモリファイル
├── docs/            # ドキュメント
├── .claude-plugin/   # Claude Codeプラグイン定義（skills含む）
├── poc/             # 概念実証・実験コード
└── vendor/          # サードパーティ依存（サブモジュール）

用語定義

用語	説明
llmlb（ロードバランサー）	Rust製のAPIゲートウェイ。OpenAI互換APIを提供し、リクエストを適切なエンドポイントに振り分ける。ダッシュボード（管理UI）も内蔵。
エンドポイント	llmlbが管理する推論サービスの接続先。xLLM、Ollama、vLLM、その他OpenAI互換APIなど多様なバックエンドを統一的に扱う。
xLLM	本プロジェクト独自のC++製推論エンジン。llama.cpp/whisper.cpp/stable-diffusion.cppなどを統合し、GPUを活用したローカル推論を提供。vLLM/Ollamaと同列のエンドポイントタイプとして扱う。

システムアーキテクチャ

ロードバランサー（llmlb/ - Rust製）

リクエストの受付・振り分け・管理を担当するコンポーネント。

• OpenAI互換APIの提供: /v1/chat/completions, /v1/embeddings等のエンドポイント
• 認証: JWT認証（ダッシュボード）、APIキー認証（API）
• エンドポイント管理: 複数エンドポイントの登録・ヘルスチェック・負荷分散
• モデルカタログ: HuggingFaceカタログとの連携、モデルメタデータ管理
• リクエストルーティング: 適切なエンドポイントへのリクエスト転送
• ダッシュボード: 管理UI（SPA）の提供

xLLM（external repo - C++製、llama.cppベース）

実際のLLM推論を担当するコンポーネント。vLLM/Ollamaと同列のエンドポイントタイプ。

• モデルロード: GGUFファイルのロード・VRAM管理
• 推論実行: テキスト生成、埋め込み計算
• GPU管理: VRAM監視、モデルのロード/アンロード
• ストリーミング: トークン単位のレスポンス