# 開発者ガイド (Development Guide)

## 1. 開発の基本コンセプト (Core Concepts)

TelosDB の開発においては、**「確信の持てるコード」**と**「自動化された環境」**を重視します。Windows 環境特有の DLL 競合やビルドエラーを避けるため、環境構築手順を簡略化しています。
In TelosDB development, we emphasize **"code you can trust"** and an **"automated environment."** To avoid DLL conflicts and build errors specific to the Windows environment, we have simplified the setup procedures.

## 2. 環境構築の手順 (Setup Procedures)

### 2.1 必要なツール (Required Tools)

- **Rust**: 最新の Stable ツールチェーン。 (Latest Stable toolchain)
- **Node.js**: フロントエンド資材の管理用。 (For managing frontend assets)
- **VS Code**: 推奨エディタ（Tauri / Rust 拡張機能）。 (Recommended editor with Tauri/Rust extensions)

### 2.2 初回セットアップ (Initial Setup)

1. リポジトリをクローン。 (Clone the repository)
2. `npm install` を実行（`sqlite-vec` などのバイナリ等が含まれます）。 (Run `npm install`, which includes binaries like `sqlite-vec`)
3. `src/backend/resources/` に指定の推論モデル（Gemma-3 GGUF）を配置。 (Place the specified inference model in `src/backend/resources/`)

## 3. ビルドと実行 (Build and Run)

```bash
# 開発モード（ホットリロード有効）
# Development mode (Hot reload enabled)
npm run tauri dev
```

> [!NOTE]
> 開発時に DLL のエラーが出る場合は、一度 `cargo clean` を行い、`build.rs` による DLL 再生成を促してください。
> If a DLL error occurs during development, perform `cargo clean` once to prompt DLL regeneration via `build.rs`.

## 4. 拡張手順 (MCP ツールの追加) (Extension Procedures: Adding MCP Tools)

新しい機能を MCP 経由で公開する場合は、以下のファイルを修正します。
To expose a new feature via MCP, modify the following files:

1. **`mcp.rs`**: JSON-RPC ハンドラーに新しいメソッドを追加。 (Add a new method to the JSON-RPC handler)
2. **`document/mcp.json`**: ツールのスキーマ（引数定義）を記述。エージェントがこの定義を読み取ります。 (Describe the tool schema/argument definitions. The agent reads this definition)
3. **`04_mcp_api_specification.md`**: 仕様書を更新。 (Update the specification document)

## 5. コーディング規約とテスト (Coding Conventions and Testing)

- **非同期処理 (Asynchronous Processing)**: SQLite 操作や通信はすべて `tokio` ランタイム上で行い、UI をブロックしないようにします。
  All SQLite operations and communications are performed on the `tokio` runtime to avoid blocking the UI.
- **ログ (Logging)**: `log::info!` / `log::error!` を使用してください。ログは `src/backend/logs/` に自動出力されます。
  Use `log::info!` / `log::error!`. Logs are automatically output to `src/backend/logs/`.
- **テスト (Testing)**: ロジックの変更後は必ず `scripts/test_mcp_client.mjs` を実行し、既存ツールが壊れていないか確認してください。
  Always run `scripts/test_mcp_client.mjs` after logic changes to ensure existing tools are not broken.

## 6. ライセンスと貢献 (License and Contribution)

TelosDB は MIT ライセンスの下で公開されています。貢献については、プロジェクトルートの `CONTRIBUTING.md`（存在する場合）またはリポジトリの運用方針を参照してください。
TelosDB is published under the MIT license. For contributions, please refer to `CONTRIBUTING.md` (if it exists) in the project root or the repository's operational policy.
