開発者ガイド (Development Guide)

1. 開発の基本コンセプト

TelosDB の開発においては、「確信の持てるコード」と「自動化された環境」を重視します。Windows 環境特有の DLL 競合やビルドエラーを避けるため、環境構築手順を簡略化しています。

2. 環境構築の手順

2.1 必要なツール

• Rust: 最新の Stable ツールチェーン。
• Node.js: フロントエンド資材の管理用。
• VS Code: 推奨エディタ（Tauri / Rust 拡張機能）。

2.2 初回セットアップ

1. リポジトリをクローン。
2. npm install を実行（sqlite-vec などのバイナリ等が含まれます）。
3. src-tauri/resources/ に指定の推論モデル（Gemma-3 GGUF）を配置。

3. ビルドと実行

# 開発モード（ホットリロード有効）
npm run tauri dev

[!NOTE] 開発時に DLL のエラーが出る場合は、一度 cargo clean を行い、build.rs による DLL 再生成を促してください。

4. 拡張手順 (MCP ツールの追加)

新しい機能を MCP 経由で公開する場合は、以下のファイルを修正します。

1. mcp.rs: JSON-RPC ハンドラーに新しいメソッドを追加。
2. document/mcp.json: ツールのスキーマ（引数定義）を記述。エージェントがこの定義を読み取ります。
3. 04_mcp_api_specification.md: 仕様書を更新。

5. コーディング規約とテスト

• 非同期処理: SQLite 操作や通信はすべて tokio ランタイム上で行い、UI をブロックしないようにします。
• ログ: log::info! / log::error! を使用してください。ログは src-tauri/logs/ に自動出力されます。
• テスト: ロジックの変更後は必ず scripts/test_mcp_client.mjs を実行し、既存ツールが壊れていないか確認してください。

6. Issue管理ルール

GitBucket との連携においては、以下のルールに従います。

• 同期方向: 原則として GitBucket が正（Source of Truth）です。
• 自動同期: node tools/scripts/sync_issues.mjs でローカル Markdown とリモート Issue を同期します。
• 日英併記の義務化:
  • すべての Issue は日本語と英語を併記しなければなりません。
  • 片方の言語だけで記述されている場合は、不足している言語の翻訳を補完してください。
• Issueのクローズ:
  • GitBucket API（PATCH）の制約により、スクリプトからの自動クローズは行いません。
  • 作業完了後、ローカル Markdown の state を closed にして同期スクリプトを実行すると、手動クローズ用のURLが表示されます。
  • 表示されたURLからブラウザで手動クローズを行ってください。
• Git追跡除外: docs/issues/ は .gitignore により Git 追跡から除外されています。個々の Issue の更新履歴は GitBucket 側で管理されます。