diff --git a/.agent/rules/development_guide.md b/.agent/rules/development_guide.md new file mode 100644 index 0000000..d7e12e8 --- /dev/null +++ b/.agent/rules/development_guide.md @@ -0,0 +1,55 @@ +# 開発者ガイド (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. diff --git a/.agent/rules/issue_management.md b/.agent/rules/issue_management.md new file mode 100644 index 0000000..df3f507 --- /dev/null +++ b/.agent/rules/issue_management.md @@ -0,0 +1,35 @@ +# Issue管理ワークフロー (Issue Management Workflow) + +このリポジトリにおける Issue の管理および同期に関する運用ルールです。 +These are the operational rules for managing and synchronizing issues in this repository. + +## 1. 外部トラッカーとの同期 (Synchronization with External Tracker) + +本プロジェクトでは、上流の Issue トラッカー (GitHub 互換 API) とローカルの Markdown ファイルを同期させて開発を進めます。 +In this project, development proceeds by synchronizing the upstream issue tracker (GitHub-compatible API) with local Markdown files. + +- **同期方向 (Direction)**: 原則として上流の Issue トラッカーが正(Source of Truth)です。 + As a rule, the upstream issue tracker is the Source of Truth. +- **自動同期 (Auto-sync)**: `node tools/scripts/sync_issues.mjs` を実行して、リモートの最新状態を `docs/issues/` に反映、またはローカルの新規 Issue をリモートに作成します。 + Run `node tools/scripts/sync_issues.mjs` to reflect the latest remote state in `docs/issues/` or create new local issues on the remote. +- **Git追跡除外 (Git Ignore)**: `docs/issues/` は `.gitignore` により Git 追跡から除外されています。 + `docs/issues/` is excluded from Git tracking via `.gitignore`. + +## 2. 記述規約 (Writing Conventions) + +- **日英併記の義務化 (Mandatory Bilingual Description)**: + - すべての Issue は**日本語と英語を併記**しなければなりません。 + All issues **must be written in both Japanese and English**. + - 片方の言語だけで記述されている場合は、不足している言語の翻訳を補完してください。 + If an issue is written in only one language, please supplement it with a translation in the missing language. + +## 3. クローズとクリーンアップ (Closing and Cleanup) + +- **手動クローズ (Manual Closing)**: + - トラッカー API の制約により、スクリプトからの自動クローズは行いません。 + Due to tracker API constraints, automatic closing from scripts is not performed. + - 作業完了後、ローカル Markdown の `state` を `closed` にして同期スクリプトを実行すると、手動クローズ用のURLが表示されます。 + After completing work, set the `state` of the local Markdown to `closed` and run the sync script to display the URL for manual closing. +- **ローカルの自動削除 (Local Auto-deletion)**: + - 上流トラッカー側で `closed` になった Issue は、同期スクリプト実行時にローカルの Markdown ファイルが自動的に削除されます。 + Issues that are `closed` on the upstream tracker side will have their local Markdown files automatically deleted when the sync script is run. diff --git "a/journals/20260223-0014-\351\201\213\347\224\250\343\203\253\343\203\274\343\203\253\343\201\256.agent_rules\343\201\270\343\201\256\347\247\273\350\241\214\343\201\250\346\227\245\350\213\261\344\275\265\350\250\230\345\214\226.md" "b/journals/20260223-0014-\351\201\213\347\224\250\343\203\253\343\203\274\343\203\253\343\201\256.agent_rules\343\201\270\343\201\256\347\247\273\350\241\214\343\201\250\346\227\245\350\213\261\344\275\265\350\250\230\345\214\226.md" new file mode 100644 index 0000000..aa6b3ab --- /dev/null +++ "b/journals/20260223-0014-\351\201\213\347\224\250\343\203\253\343\203\274\343\203\253\343\201\256.agent_rules\343\201\270\343\201\256\347\247\273\350\241\214\343\201\250\346\227\245\350\213\261\344\275\265\350\250\230\345\214\226.md" @@ -0,0 +1,43 @@ +# Journal: 20260223-0014-運用ルールの.agent_rulesへの移行と日英併記化 + +## 1. 作業実施の理由 + +ユーザー指示に基づき、プロジェクトの運用ルールをAIエージェントが優先的に読み込む `.agent/rules` ディレクトリへ集約し、かつ日英併記のポリシーを適用するため。 + +## 2. 指示(背景、観点、意図を含む) + +- **背景**: これまで `docs/` 配下に「仕様」と「運用ルール」が混在していた。 +- **観点**: AIエージェントの動作を規定するルールを `.agent/rules` に配置することで、セッション開始時に自動的にコンテキスト化されるようにする。 +- **意図**: ルール自体を日英併記にすることで、グローバルな開発環境およびAIとの協調を円滑にする。 + +## 3. 指記内容とその対応 + +- **ルール配置の修正**: `issue_management.md` と `development_guide.md` を `.agent/rules` へ移動。 +- **日英併記**: 両ファイルの内容に英語翻訳を追加。 +- **不要ファイルの削除**: `docs/` 内の移動元ファイルおよび空になったディレクトリを削除。 + +## 4. 作業詳細 + +AIエージェントは以下の手順で作業を実施した。 + +1. `docs/workflow/issue_management.md` を抽出し、英語翻訳を付加して `.agent/rules/issue_management.md` を作成。 +2. `docs/specification/06_development_guide.md` を抽出し、英語翻訳を付加して `.agent/rules/development_guide.md` を作成。 +3. `docs/` 配下の古いファイルを削除し、不要なディレクトリ構造(`docs/workflow`)をクリーンアップした。 + +## 5. AI視点での結果 + +運用ルールが `.agent/rules` に集約されたことで、AIエージェントとしての自己規律(Self-Correction)の精度向上が期待できる。また、日英併記化により、仕様とルールの双方がプロジェクトのポリシーに従った一貫性のある状態となった。 + +```mermaid +graph LR + subgraph Docs [docs/] + A[Issue Management] + B[Development Guide] + end + subgraph AgentRules [.agent/rules/] + C[Issue Management (Bilingual)] + D[Development Guide (Bilingual)] + end + A -->|Move & Translate| C + B -->|Move & Translate| D +```