tsumugi AGENTS.md

tsumugi — AI 開発ガイド（必読）

新規実装の前に必ず最初に読むこと。書く場所と再利用ルールを規定する。

ディレクトリ構造（書く場所のルール）

層	役割	何を書く
core/	ビジネスロジック（純粋）	use case、検索アルゴリズム
data/	永続化	Drizzle schema、repository
external/	外部 I/O	embeddingなどの非LLMアダプタ
interfaces/	入力アダプタ	MCP tool、REST handler、transport
lib/	横断ユーティリティ	id、errors、config

依存方向: interfaces → core → (data, external) → lib

逆方向の import 禁止（lib は循環依存禁止）。

詳細なファイル一覧はソースツリーを正とし、このガイドでは固定しない。新しい機能も上記の 依存方向と責務に従って配置する。external/llm/ や同等のserver-side LLM clientは作らない。

既存資産（再実装禁止）

ID 生成

lib/id.ts の newId(prefix) を必ず使う。

import { newId } from "../lib/id.js";
const id = newId("obs");

DB アクセス

data/repos/<entity>.ts 経由で行う。db を直接触らない（schema 定義 / migration ファイル以外）。

import { observationRepo } from "../../data/repos/observation.js";
await observationRepo.insert(row);

Embedder

external/embedding/singleton.ts の getEmbedder()。

import { getEmbedder } from "../../external/embedding/singleton.js";
const embedding = await getEmbedder().embed(text);

検索

core/search/hybrid.ts の hybridSearch()。bigm/vector を直接呼ばない。

import { hybridSearch } from "../../core/search/hybrid.js";
const hits = await hybridSearch(input);

設定

lib/config.ts の loadConfig()。process.env 直接読み禁止。

エラー

lib/errors.ts の TsumugiError 派生を使う。new Error() しない。

import { ValidationError, ExternalError } from "../../lib/errors.js";
throw new ValidationError("content is required");

採用パターン

Use case の形

• ファイル: core/<domain>/<verb>.ts（例: core/observation/save.ts）
• 入口で Zod parse、出力は型付きオブジェクト
• repo / external を直接 import で呼ぶ（DI コンテナ不要）
• 副作用は use case 内で完結

Repository の形

• ファイル: data/repos/<entity>.ts
• export const xxxRepo = { method1, method2 } で集約
• Drizzle の $inferSelect / $inferInsert で型を取り出す