kitcn

kitcn コアスキル（80% のケース）

設定済みの kitcn アプリで日常的な機能を実装する場合は、まずこのファイルを使用してください。

• セットアップ／ブートストラップ／環境変数／認証の配線、またはプロジェクト構造のミラーリングが不足している場合は、references/setup/index.md（続いて該当するセットアップファイル）を使用してください。
• 高度なタスクやニッチなタスクの場合は、末尾に記載されている該当機能のリファレンスのみを読み込んでください。

対象範囲

対象：

• スキーマのテーブル、インデックス、リレーション、トリガーの追加または更新。
• ランタイム認証とレート制限を適用した cRPC プロシージャ（query、mutation、action、httpAction）の実装。
• useCRPC() と TanStack Query を使用した機能 UI の実装。
• 認証、エラー、副作用を対象とした、最小限かつ重要度の高いテストの追加。 対象外：
• 新規プロジェクトのセットアップ／インストール／環境変数設定／ブートストラップ。
• プラグインの詳細な解説（admin／organizations／polar）。
• 内部パッケージレベルの同等性テスト。

スキルの契約

1. アプリデータへのアクセスには ctx.orm を優先してください。
2. リスト取得／読み取りの処理は、上限を設け、インデックスを考慮してください。
3. cRPC ビルダーとミドルウェアを使用し、新しい機能コードでは生のハンドラーオブジェクトを避けてください。
4. 想定されるエラーには CRPCError を使用してください。
5. 複数行にまたがる不変条件にはスキーマトリガーを優先します。ただし、トリガーの実行が不安定な場合（たとえば、初期化／シード処理が停止する場合や再帰的な書き込み経路がある場合）は、不変条件の維持を明示的な mutation ヘルパーに移してください。
6. 認証／レート制限のチェックはサーバー側で行ってください。
7. プロシージャ間呼び出し：生成されたランタイムヘルパーを使用してください。クエリ／ミューテーションでは create<Module>Handler(ctx)、アクション／HTTP ルートでは create<Module>Caller(ctx)、アクションプロシージャでは caller.actions.*、スケジューリングでは caller.schedule.* を使用してください。モジュールプロシージャの呼び出しに ctx.runQuery／ctx.runMutation／ctx.runAction を直接使用しないでください。

ショートカットモード（tRPC + Drizzle のメンタルモデル）

デフォルトの前提：

• cRPC の動作は tRPC に似ています（ビルダーチェーン + ミドルウェア + TanStack のオプション）。
• ORM の動作は Drizzle に似ています（スキーマ、リレーション、findMany/findFirst、insert/update/delete）。 次の相違点だけを覚えておいてください：

1. プロシージャの入力ルートは z.object(...) である必要があります（プリミティブ型のルート引数は不可）。
2. z.void() の出力は使えません。値を返さないミューテーションでは .output(...) を省略してください。
3. .output(...) はハンドラーの値をそのまま解析し、何も置き換えません。ハンドラーはスキーマの入力型を返す必要があるため、z.string().nullable() では undefined ではなく明示的な null（?? null）が必要です。値の不在は .nullable() で表現し、トップレベルの .optional() は使わないでください。Convex は undefined を null として連携し、トップレベルの optional は表現できないため、.output(z.string().optional()) は v.string() を公開し、ハンドラーが undefined を返すとデプロイ時に null が拒否されます。オブジェクト内の .optional() は問題ありません。zCustomQuery／zCustomMutation／zCustomAction の低レベルな returns: オプションは異なり、解析前に undefined を null に置き換えます。
4. 複数の .input(...) 呼び出しは入力の形状をマージします。
5. .paginated({ limit, item }) は .query() の前に置く必要があり、input.cursor、input.endCursor、input.limit を追加します。ライブ分割を上限内に保つため、ORM のカーソルクエリには3つすべてを渡してください。
6. メタデータは @convex/api のリーフ（api.namespace.fn.meta）にコード生成されるため、.meta(...) にシークレットを入れないでください。.meta(...) のチェーンは浅いマージであり、defaultMeta をサポートします。
7. 認証メタデータはクライアントの動作を制御します。auth: "optional" は認証の読み込み完了を待ってから実行し、auth: "required" は読み込み完了を待ってからログアウト中ならスキップします。
8. ctx.orm は制約と RLS を適用します。ctx.db はそれらを迂回します。
9. ページネーションなしの findMany() では、サイズを明示する必要があります（limit、カーソルモード、スキーマの defaultLimit、または明示的な allowFullScan）。
10. 述語を使う where には、明示的な .withIndex(...) が必要です。暗黙の全件スキャンへのフォールバックはありません。
11. カーソルページネーションは最初の orderBy フィールドを使用します。安定したページングのため、そのフィールドにインデックスを付けてください。
12. maxScan はカーソルモードにのみ適用されます。allowFullScan はカーソルを使わない全件スキャンを明示的に許可するためのものです。
13. 文字列演算子、columns によるプロジェクション、多リレーションのサブフィルターは、フェッチ後に実行される場合があります。結果サイズは早い段階で制限してください。
14. 検索モードでは関連度順になり、orderBy はサポートされません。ベクトルモードにはさらに厳しい制限があります（カーソル／オフセット／トップレベルの where／order は不可）。
15. where を指定せずに更新／削除すると、allowFullScan() を指定していない限りエラーになります。
16. count()、aggregate()、groupBy() には、一致する aggregateIndex が必要です。複数の .count() 呼び出しや findMany + 手動の JavaScript グループ化ではなく、groupBy({ by, _count, _sum }) を使ってください。すべての by フィールドは where で有限の値に制約されている必要があります（eq／in／isNull）。references/features/aggregates.md を参照してください。
17. cRPC の React クエリはデフォルトでリアルタイムです（subscribe: true）。これらの購読対象パスには queryClient.invalidateQueries を決して使わないでください。
18. RSC では、prefetch はクライアントをハイドレートし、caller はサーバー専用でハイドレートされず、preloadQuery はハイドレートしますが、クライアント側でもレンダリングすると分割の所有権が古くなることがあります。
19. Better Auth の Next.js 用ショートカットは convexBetterAuth(...) です。汎用のサーバー専用ショートカットは createCallerFactory(...) です。
20. kitcn の認証クライアントパスでは、ログアウト前に認証クエリの購読を解除するため、createAuthMutations(authClient) ラッパーを使ってください。Raw Convex プリセットでは、より小規模でシンプルな authClient を使います。
21. モジュール間の呼び出しに ctx.runQuery／ctx.runMutation／ctx.runAction を直接決して使わないでください。convex/functions/generated/<module>.runtime の生成済みランタイムヘルパーを使ってください。
22. クエリ／ミューテーションでは、デフォルトで create<Module>Handler(ctx) を使います。オーバーヘッドはゼロで、クエリ／ミューテーションのコンテキストだけを使い、冗長な検証やミドルウェアはありません。
23. create<Module>Caller(ctx) はアクションと HTTP ルートで使います。アクションプロシージャは caller.actions.* の下にあり、スケジューリングは caller.schedule.now|after|at|cancel の下にあります。実際の ActionCtx コールバックに限り requireActionCtx(ctx) を使い、ミューテーションまたはアクションのコンテキストからスケジュールできる場合は requireSchedulerCtx(ctx) を使ってください。各 caller／handler はモジュールを即時に読み込むため、大きなモジュールは分割してください。
24. API 型（Api、ApiInputs、ApiOutputs、Select、Insert、TableName）は @convex/api からインポートします。inferApiInputs<typeof api> を手動で使う必要はありません。
25. HTTP ルーターは、コード生成のために appRouter ではなく httpRouter としてエクスポートする必要があります。
26. サーバー配線のインポート元は convex/functions/generated/ ディレクトリです。getAuth、defineAuth は generated/auth から、initCRPC、QueryCtx、MutationCtx、OrmCtx は generated/server から、create<Module>Caller、create<Module>Handler は generated/<module>.runtime からインポートします。convex/lib/orm.ts を手動で作成する必要はありません。
27. defineAuth(() => ({ ...options, triggers })) は、分割されていた getAuthOptions + authTriggers を置き換えます。トリガーコールバックではドキュメントが先頭です。beforeCreate(data)、onCreate(doc)、onUpdate(newDoc, oldDoc) の形式で、最初の引数に ctx はありません。
28. 内部認証関数は internal.auth.* ではなく internal.generated.* にあります。
29. 非同期ミューテーションのバッチ処理がデフォルトです（コード生成時に配線されます）。呼び出しごとにカスタマイズするには、execute({ batchSize, delayMs }) を使います。同期処理にするには、execute({ mode: 'sync' }) または defineSchema(..., { defaults: { mutationExecutionMode: 'sync' } }) を指定します。関連するデフォルト値は mutationBatchSize、mutationLeafBatchSize、mutationMaxRows、mutationScheduleCallCap です。
30. 多相ユニオンはスキーマ優先です。convexTable(...) で actionType: discriminator({ variants, as? }) を使ってください。クエリ設定に polymorphic オプションはありません。書き込みはフラットなままで、読み取りではネストされた details（またはカスタムエイリアス）が合成されます。判別子テーブルの one() リレーションをすべて自動読み込みするには、withVariants: true を使ってください。
31. アプリ／プラグインのコードでは、デフォルトで ORM のミューテーションバッチ処理ループを手動で追加しないでください。Convex ランタイムのバッチ処理が、すでにミューテーションの実行を処理します。行ごとのループより、集合ベースの削除／更新を優先してください。明示的な分割を追加するのは、外部副作用をまとめる場合（たとえば Resend API の呼び出し）や、上限付きのクリーンアップ処理を行う場合に限ります。

ディレクトリの境界

次のタスクでは references/setup/ を使用します。

1. プロジェクト／ファイル構成のセットアップ → setup/index.md + setup/server.md
2. 認証の初期設定 → setup/auth.md
3. クライアント／プロバイダーの接続 → setup/react.md
4. フレームワーク固有のセットアップ → setup/next.md または setup/start.md テンプレート全体を再現する場合：まず setup/index.md を読み込み、次に関連するセットアップファイルを読み込み、その後、選択した機能リファレンスを読み込みます。

最初の機能要件の確認（編集前に実施）

まず、次の項目を決定します。

1. エンドポイントごとの認証レベル：public / optionalAuth / auth / private。
2. データの不変条件：書き込み後に常に満たすべき条件は何か。
3. クエリの形：一覧、詳細、リレーション読み込み、検索、ストリームの組み合わせのいずれか。
4. ページネーション方式：オフセット、カーソル、無限。
5. 副作用：トリガー、スケジュール関数、インラインミューテーションのいずれか。
6. UI での利用方法：クライアントフックのみ、RSC プリフェッチ、サーバー専用の呼び出しのいずれか。
7. リスクのあるパス：未認証、アクセス禁止、見つからない場合、競合、レート制限。

基本的なファイルの配置先

一般的な機能で変更するファイル：

• convex/functions/schema.ts
• convex/functions/<feature>.ts
• convex/lib/crpc.ts（ミドルウェア／プロシージャビルダーを変更する場合のみ）
• src/lib/convex/crpc.tsx（cRPC のコンテキスト／メタデータの接続を変更する場合のみ）
• src/** 機能の UI ファイル
• HTTP エンドポイントには convex/functions/http.ts または convex/routers/**
• 必要に応じて convex/functions/crons.ts またはスケジュールハンドラー

E2E のデフォルトの構築順序

1. スキーマ、インデックス、リレーション。
2. 行をまたぐ不変条件のトリガーフック（または、トリガーパスが不安定な場合は、明示的なミューテーション側の同期）。
3. 厳密な入出力、認証、レート制限を備えたプロシージャ。
4. cRPC オプションを使用する React フック（クエリ／ミューテーション／無限）。
5. 任意：HTTP ルート、スケジュールフック。
6. 認証／エラー／トリガー動作のテスト。

基本パターン

1) スキーマ + リレーション + トリガー

import {
  convexTable,
  defineSchema,
  id,
  integer,
  index,
  text,
  timestamp,
} from "kitcn/orm";

export const project = convexTable(
  "project",
  {
    name: text().notNull(),
    ownerId: id("user").notNull(),
    updatedAt: timestamp()
      .notNull()
      .defaultNow()
      .$onUpdateFn(() => new Date()),
  },
  (t) => [index("ownerId_updatedAt").on(t.ownerId, t.updatedAt)]
);

export const task = convexTable(
  "task",
  {
    projectId: id("project").notNull(),
    title: text().notNull(),
    status: text().notNull().default("open"),
    updatedAt: timestamp()
      .notNull()
      .defaultNow()
      .$onUpdateFn(() => new Date()),
  },
  (t) => [index("projectId_updatedAt").on(t.projectId, t.updatedAt)]
);

export default defineSchema({ project, task })
  .relations((r) => ({
    project: {
      tasks: r.many.task(),
    },
    task: {
      project: r.one.project({ from: r.task.projectId, to: r.project.id }),
    },
  }))
  .triggers({
    task: {
      change: async (change, ctx) => {
        const projectId = change.newDoc?.projectId ?? change.oldDoc?.projectId;
        if (!projectId) return;
        const open = await ctx.orm.query.task.findMany({
          where: { projectId, status: "open" },
          columns: { id: true },
          limit: 500,
        });
        await ctx.orm.update(project).set({ openTaskCount: open.length });
      },
    },
  });

重要なスキーマのルール：

1. フィルター／並べ替え／検索に使うフィールドにはインデックスを作成します。
2. many() リレーションのパスには、子の外部キーインデックスが必要です。
3. トリガーロジックは処理範囲を限定し、再帰しないようにします。
4. 一貫した書き込み動作のために、テーブルのデフォルト値を使用します。
5. ORM／クエリの詳しいエッジケースについては、references/features/orm.md を参照してください。

2) プロシージャビルダー + ミドルウェア

import { getSession } from "kitcn/auth";
import { CRPCError } from "kitcn/server";
import { initCRPC, type QueryCtx } from "../functions/generated/server";

const c = initCRPC
  .meta<{
    auth?: "optional" | "required";
    role?: "admin";
    ratelimit?: string;
  }>()
  .create();

function requireAuth<T>(user: T | null): T {
  if (!user) {
    throw new CRPCError({ code: "UNAUTHORIZED", message: "Not authenticated" });
  }
  return user;
}
async function getSessionUser(ctx: QueryCtx) {
  const session = await getSession(ctx);
  if (!session) return null;
  return await ctx.orm.query.user.findFirst({
    where: { id: { eq: session.userId } },
  });
}

export const publicQuery = c.query.meta({ auth: "optional" });
export const authQuery = c.query
  .meta({ auth: "required" })
  .use(async ({ ctx, next }) => {
    const user = requireAuth(await getSessionUser(ctx));
    return next({ ctx: { ...ctx, user, userId: user.id } });
  });
export const authMutation = c.mutation
  .meta({ auth: "optional" })
  .use(async ({ ctx, next }) => {
    const user = await getSessionUser(ctx);
    return next({
      ctx: { ...ctx, user, userId: user?.id ?? null },
    });
  });

重要なビルダーのルール：

1. convex/lib/crpc.ts で public、optional、auth、private のプロシージャファミリーを一度だけ構築します。認証済みアクションのビルダーは convex/lib/crpc-action.ts に配置します。getAuth をインポートするビルダーモジュールはこのファイルのみです。
2. .meta(...) は生成された API メタデータを介してクライアントから参照できます。秘密情報は決して含めないでください。
3. ミドルウェアにはサーバー専用の procedure 情報が渡されます。アプリの generated/server ヘルパーからプロシージャを構築する場合、標準の export const クエリ、ミューテーション、アクションでは、ファイルパスとエクスポート名から module:function が自動的に推論されます。.name("module:function") を使うのは、上書きする場合、または特殊なエクスポート形式に対応する場合のみです。
4. ミドルウェアでセッション／ユーザーを一度だけ解決します。各プロシージャで認証状態を再取得しないでください。 クエリ／ミューテーションのミドルウェアでは kitcn/auth の getSession(ctx) を使用します。これはセッション行を直接読み取ります。convex/lib/crpc.ts では getAuth(ctx) を使用しないでください。これを使うと Better Auth の定義全体とすべての認証プラグインが、すべてのプロシージャモジュールの静的インポートクロージャに含まれます。Convex にはこれを回避する動的な import() がありません。getAuth をインポートするのは、auth.api.* を呼び出すモジュール（convex/lib/crpc-action.ts、HTTP ルート、組織／管理者向けミューテーション）のみにしてください。
5. 共有の c.middleware() チェーンでは、ミューテーションプロシージャのミューテーションライター型が維持されます。ミドルウェア自体が書き込みを行う場合は、c.middleware<MutationCtx>(...) を指定して、ミューテーション専用として型付けします。
6. 認証／ランタイムに関する詳しいエッジケースについては、references/setup/server.md および references/features/auth*.md を参照してください。

3）クエリ＋ミューテーションの手順テンプレート

import * as z from "zod";
import { eq } from "kitcn/orm";
import { CRPCError } from "kitcn/server";
import { authMutation, authQuery } from "../lib/crpc";
import { project } from "./schema";

export const listProjects = authQuery
  .paginated({ limit: z.number().min(1).max(50).default(20), item: project })
  .query(async ({ ctx, input }) =>
    ctx.orm.query.project.findMany({
      where: { ownerId: ctx.userId },
      orderBy: { updatedAt: "desc" },
      cursor: input.cursor,
      endCursor: input.endCursor,
      limit: input.limit,
    })
  );

export const renameProject = authMutation
  .input(z.object({ id: z.string(), name: z.string().min(1).max(120) }))
  .mutation(async ({ ctx, input }) => {
    const current = await ctx.orm.query.project.findFirst({
      where: { id: input.id, ownerId: ctx.userId },
      columns: { id: true },
    });
    if (!current) {
      throw new CRPCError({ code: "NOT_FOUND", message: "Project not found" });
    }
    await ctx.orm
      .update(project)
      .set({ name: input.name })
      .where(eq(project.id, current.id));
    return null;
  });

重要な手順のルール：

1. ルートの入力は z.object(...) にする必要があります。
2. 厳密な .input(...) を使用し、必要な場合にのみ .output(...) を追加します。
3. 値を返さないミューテーションでは .output(...) を省略します。
4. デフォルトのミューテーションレート制限を使用し、名前付きバケットのオーバーライドに限り .meta({ ratelimit: ... }) を追加します。
5. 想定される結果には CRPCError をスローします。
6. すべてのリストに limit、カーソル、または .paginated(...) を設定します。
7. 高度なクエリビルダーの形式は references/features/orm.md に移します。

3b）プロシージャ間の合成

次を使用します。

1. クエリ／ミューテーションでは create<Module>Handler(ctx)。
2. アクション／HTTP ルートでは create<Module>Caller(ctx)。
3. アクションプロシージャでは caller.actions.*。
4. スケジュール済みプロシージャでは caller.schedule.*。
5. モジュールプロシージャに ctx.runQuery／ctx.runMutation／ctx.runAction を使用しないでください。

4）クエリモード（適切なものを使用）

1. デフォルトではオブジェクト形式の where を使用します。
2. コールバック形式の where は、オブジェクト形式よりも合成の見通しがよい場合にのみ使用します。
3. 述語／フィルターのコールバックでは、先に .withIndex(...) を指定し、さらに limit／maxScan を明示する必要があります。
4. 全文検索では search: { index, query, filters } を使用し、orderBy はサポートされません。
5. カーソルページングが安定するのは、orderBy フィールドにインデックスが設定されている場合のみです。
6. 高度なモード（pageByKey、ベクトル検索、パイプライン、集約インデックス）は references/features/orm.md に記載されています。

5）ミューテーションのパターン（最もよく使うもの）

1. 呼び出し元が作成された ID を必要とする場合、挿入時に .returning(...) を使用します。
2. すべての更新／削除パスで、明示的な where(...) を指定します。
3. オプションの列をクリアするには unsetToken を使用します。
4. 非同期のミューテーション実行がデフォルトです。原子的にすべてを一括処理する必要がある場合にのみ .execute({ mode: "sync" }) を使用します。
5. セットベースの削除／更新を優先します。外部の副作用や、対象を限定したクリーンアップにのみチャンク処理を追加します。
6. Upsert、競合処理、ミューテーションのバッチ処理、スキーマ拡張に関するエッジケースは references/features/orm.md に記載されています。

6）エラーモデル

次の対応関係を一貫して使用します。

1. BAD_REQUEST：無効な入力またはビジネス上の前提条件の不成立。
2. UNAUTHORIZED：セッションがありません。
3. FORBIDDEN：セッションはありますが、権限がありません。
4. NOT_FOUND：リソースが存在しないか、アクセスできません。
5. CONFLICT：重複または書き込みの競合。
6. TOO_MANY_REQUESTS：レート制限。
7. INTERNAL_SERVER_ERROR：予期しない失敗にのみ使用します。cRPC は .output(...) の解析に失敗した場合にもこれを発生させます。その際のメッセージは Output validation failed で、サニタイズされた構造化 Zod イシューは error.data.ZodError に含まれます。ハンドラーの出力を含む可能性があるカスタムイシューメッセージとフィールドは、サーバー側に留まります。
8. クライアントが競合する ID などのドメインメタデータを必要とする場合は、CRPCError に小さなカスタム data ペイロードを追加します。クライアントでは error.data から読み取ります。

必須テスト：

1. 未認証時の拒否
2. 該当する場合の権限不足による拒否
3. リソースが見つからない場合のパス
4. 該当する場合の競合パス
5. 該当する場合のレート制限対象の書き込みパス

7) React Query の統合

前提条件（useCRPC() のコードパスを記述または使用する前に満たす必要があります）：

1. セットアップのブートストラップによって、生成されたインポート（@convex/api）が存在していること。
2. プロバイダーチェーンがマウントされていること（QueryClient + Convex プロバイダーフロー内に CRPCProvider があること）。
3. ブートストラップ／プロバイダーの前提条件が満たされていない場合は、機能の作業を中断し、先に references/setup/ を完了してください。
4. バックエンドの状態は ~/.convex ではなく、プロジェクトローカルの .convex/ にあります。

useCRPC() のパターン：const crpc = useCRPC(); const projects = useQuery(crpc.project.listProjects.queryOptions({ cursor: null, limit: 20 })); const createProject = useMutation(crpc.project.createProject.mutationOptions());

クライアントの主なデフォルト設定と変更点：

1. クエリはデフォルトでリアルタイムです（subscribe: true）。
2. サブスクライブされた cRPC クエリのパスでは、queryClient.invalidateQueries を使用しないでください。
3. 1 回限りのフェッチには { subscribe: false } のみを使用し、明示的な refetch／fetchQuery で更新してください。
4. 認証されていない状態での不要なフェッチの繰り返しを避けるには、skipUnauth: true を使用してください。
5. ページネーションには、kitcn/react の useInfiniteQuery を使用してください。
6. キャッシュの読み取り／書き込み／フェッチ操作では、手動でキーを指定するより、型付きの queryKey(...) ヘルパーを優先してください。
7. kitcn の認証フローでは、ログアウト時の競合エラーを避けるため、生の認証クライアント呼び出しではなく、createAuthMutations(...) ラッパーを優先してください。Raw Convex プリセットでは、通常の認証クライアントパスを使用します。
8. ミューテーションのトーストには、error.message より error.data?.message を優先してください。data.message はクリーンな CRPCError ペイロードです。
9. すべてのコンポーネントに onError をコピー＆ペーストするより、mutation.meta.errorMessage／skipErrorToast を使用するグローバルな QueryClient ミューテーション onError トーストを優先してください。
10. クライアント／RSC の詳細については、references/features/react.md を参照してください。

8) RSC のパターン（Next.js）

ユースケースごとに、次のいずれかを選択してください。

1. prefetch(...)（推奨）：ノンブロッキングでハイドレーションされ、クライアントがデータを所有します。
2. caller.*：ブロッキングのサーバー専用ロジック（リダイレクト／認証チェック）で、ハイドレーションされません。
3. preloadQuery(...)：サーバーがデータをすぐに必要とする場合の、ブロッキングかつハイドレーションされる方法です。

同じデータパスについて、preloadQuery の結果をサーバーとクライアントの両方でレンダリングしないでください。

1. プリフェッチ済みクエリを使用するすべてのクライアントコンポーネントは、HydrateClient でラップする必要があります。
2. Next.js 固有のセットアップと、ハイドレーションのトレードオフの詳細については、references/setup/next.md と references/features/react.md を参照してください。

9) HTTP ルートのパターン（REST／Webhook が必要な場合）

import { createTaskCaller } from "../functions/generated/task.runtime";

export const createTaskRoute = authRoute
  .post("/api/projects/:projectId/tasks")
  .params(z.object({ projectId: z.string() }))
  .input(z.object({ title: z.string().min(1) }))
  .output(z.object({ id: z.string() }))
  .mutation(async ({ ctx, params, input }) => {
    const caller = createTaskCaller(ctx);
    const id = await caller.createFromHttp({
      projectId: params.projectId,
      title: input.title,
      userId: ctx.userId,
    });
    return { id };
  });

HTTP 固有のルール：

1. 検索パラメーターには z.coerce.* を使用してください。
2. 認証と権限のチェックは、ミドルウェア／プロシージャーで行ってください。
3. 公開エンドポイント／負荷の高いエンドポイントには、レート制限を適用してください。
4. 副作用が発生する前に、Webhook の署名を検証してください。
5. convex/lib/crpc.ts の publicRoute／authRoute／optionalAuthRoute ビルダーを使用してください。
6. router(...) を使用して、機能レベルで HTTP エンドポイントをグループ化してください。
7. クライアント呼び出しでは、パス／クエリ引数を { params, searchParams } として渡してください。クエリ値は文字列です。
8. Webhook、ストリーミング、Hono 固有のパターンについては、references/features/http.md を参照してください。

10) スケジューリングのパターン（必要な場合）

例：const caller = createTaskCaller(ctx); await caller.schedule.now.sendTaskCreated({ taskId: created.id, userId: ctx.userId }); await caller.schedule.at(input.sendAt).sendReminder({ taskId: input.taskId, userId: ctx.userId });

スケジューリングのルール：

1. 認証コンテキストは引き継がれません。ユーザー ID／組織 ID を明示的に渡してください。
2. ミューテーションのスケジューリングは、ミューテーションのトランザクションと原子的に行われます。
3. キャンセルが必要な場合は、返されたジョブ ID を保存してください。
4. アクション内のスケジューリングは、アクションの失敗に対して原子的ではありません。
5. Cron スケジュールは UTC で実行されます。
6. プロシージャー以外の internal.* 関数をスケジュールする必要がある場合に限り、ctx.scheduler.* を直接使用してください。
7. Cron 式と運用上の詳細については、references/features/scheduling.md を参照してください。

11) テストの基準（重要度が高い項目）

機能の最小テストセット：

1. 正常系のクエリ／ミューテーション
2. 未認証時の拒否（UNAUTHORIZED）
3. 権限／所有権がない場合の拒否（該当する場合はFORBIDDEN）
4. リソースが見つからない場合（NOT_FOUND）
5. 副作用が発生することのアサーション
6. 機能が処理をスケジュールする場合は、スケジューラーのアサーション
7. 見つからないことの確認には、合成した ID ではなく、実際の ID または ID 以外の検索キー（slug/name/email）を使用する
8. テストの詳しい手順はreferences/features/testing.mdにあります。
9. Convex のブートストラップが結合テストを妨げる場合は、純粋なガード／ヘルパーを切り出し、ブートストラップが機能するようになったらスモーク結合テストを 1 つ実施します。

パフォーマンスと安全性のチェックリスト

機能の完成と判断する前に、次を確認してください。

1. すべてのリストクエリに上限（limit／カーソル）が設定されています。
2. フィルター／並び順がインデックスに沿っています。
3. 負荷の高いフェッチ後のロジックでは、事前に絞り込んだインデックスパスを使用しています。
4. ミューテーションでは対象を絞ったwhereを使用し、意図しない全件スキャンを避けています。
5. トリガーロジックに上限があり、冪等で、ピンポンループを回避しています。
6. エラーコードが明示され、意図的に選択されています。
7. ユーザー向けの書き込みにはレート制限のメタデータが設定されています。
8. テストで認証、見つからない場合、副作用をカバーしています。
9. ORM の制約／RLS に依存するパスではctx.dbを使用していません。
10. ページネーションを使用するエンドポイントでは、独自のラッパーではなく.paginated(...)と ORM のカーソルフローを使用しています。
11. 述語／全件スキャンに相当するパスでは、.withIndex(...)と上限（limit／maxScan）を明示しています。
12. @ts-nocheckは絶対に使用せず、グローバルな lint ルールを緩和せず、変更したファイルに未解決の lint 警告を残しません。

よくある間違い（および修正方法）

間違い	正しいパターン
新機能のプロシージャに Convex ハンドラーを直接使う	cRPC ビルダー（publicQuery、authMutation など）
書き込み時の副作用が複数のミューテーションで重複している	スキーマトリガーを使うか、トリガー経由が安全でない場合は、ミューテーション側の同期ヘルパーを1か所に集約します
リストや検索に上限がない	limit とカーソル／ページネーションを追加します
orderBy を配列オブジェクトとして記述する	オブジェクト形式を使います：orderBy: { updatedAt: "desc" }
ポリシーの影響を受ける読み取りに ctx.db を使う	ctx.orm を使います（RLS／制約の経路）
想定される結果に汎用的な Error を投げる	明示的なコードを指定して CRPCError を投げます
無限リストに TanStack のネイティブフックを直接使う	kitcn/react の useInfiniteQuery を使います
プリミティブ型をルート入力にする（z.string()）	ルートに z.object(...) の入力スキーマを使います
z.void() で何も返さない	明示的な出力指定を省略します
存在しない可能性のある検索結果を .output(...nullable()) で返す	?? null で補完します。.output(...) は undefined に対して何も代入しません
無限エンドポイントに手動のページネーションラッパーを使う	.paginated({ limit, item }) を使います
テストで合成 Convex ID（"missing-id"）を使う	挿入した ID または意味のある検索キーを使います
集計を無効にしているのにヘルパーや設定が残っている	集計ヘルパー、defineTriggers ハンドラー、アプリ設定をまとめて削除します
.meta(...) にシークレットを入れる	メタデータには機密情報を含めません（クライアントから見えるため）
ctx.runQuery／ctx.runMutation／ctx.runAction を直接使う	クエリ／ミューテーションでは create<Module>Handler(ctx) を、アクション／HTTP では caller.actions.*／caller.schedule.* とともに create<Module>Caller(ctx) を使います（generated/<module>.runtime から）
クエリ／ミューテーションのコンテキストで createCaller を使う	create<Module>Handler(ctx) を使います。オーバーヘッドなしで、冗長な検証を回避できます
コンパイルを通すために // @ts-nocheck を追加する	絶対に行わないでください。references/setup/ の標準パターンを使って、根本の型の問題を修正します
チェックを通すために lint ルールを緩和する	基本の lint 設定を維持し、代わりにコードレベルの警告やエラーを修正します

参照ドキュメントの読み込みマップ（必要な場合のみ読み込み）

セットアップ（プロジェクトごとに一度）：

• references/setup/index.md：ブートストラップ、環境、判断事項の確認、ゲート、チェックリスト、トラブルシューティング
• references/setup/server.md：コアバックエンド（スキーマ、ORM、cRPC）＋オプションモジュールのゲート
• references/setup/auth.md：認証コアのブートストラップ＋プラグインのセットアップ
• references/setup/react.md：クライアントコア（QueryClient、プロバイダー、cRPC コンテキスト）
• references/setup/next.md：Next.js App Router のセットアップ
• references/setup/start.md：TanStack Start のセットアップ
• references/setup/doc-guidelines.md：スキルとドキュメントの同期に関する契約

機能（セッションごとに、単独で完結）：

• references/features/orm.md：ORM API 全般、制約、RLS、高度なミューテーション、フィルタリング／検索／構成／ページネーション
• references/features/react.md：クライアント、RSC、ハイドレーション、エラーハンドリングのマトリクス全般
• references/features/http.md：型付き REST ルート、Webhook、ストリーミング
• references/features/scheduling.md：cron＋遅延ジョブのパターン
• references/features/testing.md：より踏み込んだテストシナリオ
• references/features/aggregates.md：集約コンポーネントのパターン
• references/features/migrations.md：組み込みのオンラインデータマイグレーション（defineMigration、CLI、デプロイ、ドリフト）。次の場合に読み込みます：タスクにデータのバックフィル、オプションから必須へのフィールドの変更、フィールドの名前変更／削除、型の絞り込み、または kitcn migrate CLI コマンドが関係する場合。後方互換性のある変更（新しいオプションフィールド、新しいテーブル、コードレベルのデフォルト）では読み込みません。
• references/features/create-plugins.md：プラグイン作成の標準パターン（パッケージエントリーの分割、トークン設定、スキャフォールド／ロックファイル／CLI マニフェストのルール）。プラグインを作成またはリファクタリングする場合に読み込みます。
• references/features/ratelimit.md：レート制限のランタイム計算（シャード予算の配分、check() と limit() の違い、スナップショットの変換、読み取り精度、失敗モード）。shards の調整、残りのクォータの読み取り、または予期しない拒否のデバッグ時に読み込みます。setup/server.md の対象である単純な ratelimit.middleware() の接続では読み込みません。
• references/features/auth.md：Better Auth のコアフロー全般
• references/features/auth-admin.md：管理者プラグインの詳細
• references/features/auth-organizations.md：組織／マルチテナントプラグインの詳細