Claude Media
Claude CodeのConvexプラグインでバックエンド設計を任せる
Claude CodeClaude連携チュートリアル

Claude CodeのConvexプラグインでバックエンド設計を任せる

Convex公式プラグインを入れると、平易な依頼がConvexの設計スキルに自動で振り分けられます。導入、quickstart、保存時の検査フック、送信されるデータの止め方までを扱います。

読了目安 約11分

Convexの公式プラグインは、バックエンドの依頼をConvexの流儀で書かせるための一式です。設計スキル、/quickstart、コードを書く専用サブエージェント、保存時と終了時の検査フック、エラー監視、MCPサーバーが1回の導入で入ります。Claude Codeに「友達と映画の投票ができるアプリを作りたい」と頼むだけで、スキルが自動で選ばれる作りです。MCPサーバー単体の接続はConvexのMCPサーバー解説にあり、ここではスキルとフックの側を扱います。

導入は1行、ローカルでも試せる

Claude Codeの中で次を実行します。

/plugin install convex@claude-plugins-official

表記は出典ごとに違います。GitHubのREADMEは/plugin install convexと短く書き、Convexのドキュメントは@claude-plugins-official付きの形を載せ、マーケットプレイスの掲載ページではプラグイン名がconvex-backendです。入らないときは、/pluginのマーケットプレイス一覧で、どの表記が同じプラグインに当たるかを確かめられます。

マーケットプレイスを使わずに、リポジトリを手元に置いて読み込むこともできます。

git clone https://github.com/get-convex/convex-backend-skill \
  ~/.claude-plugins/convex-backend-skill
claude --plugin-dir ~/.claude-plugins/convex-backend-skill

--plugin-dirはClaude Codeの標準フラグで、開発中のプラグインをフォルダから直接読み込みます。中身を読んでから入れたい人や、フックの挙動を確かめたい人に向く経路です。導入後に消費するコンテキストの量は、claude plugin detailsの解説の手順で測れます。

何が同梱されるのか

同梱されるのは、設計スキル、quickstartスキル、convex-expertサブエージェント、MCPサーバー、フック2種、監視3種です。

構成

同梱される部品

  • 設計スキル

    バックエンドの依頼を検知すると、コンテキストに読み込まれます。設計の考え方、アンチパターン、実行時エラーの読み解きを担います。

  • convex-expertサブエージェント

    コードを書く規則を持つ専用エージェントです。委任されたときだけ読み込まれるため、メインのコンテキストを食いません。

  • フックと監視

    保存時の検査、ターン終了時の検証、ログとOCC競合の監視が、依頼とは無関係に裏で動きます。

サブエージェントの規則は、オブジェクト形式の構文、検証子の必須化、索引の命名、内部関数と公開関数の区別、スキーマの変更手順、リソース上限、コンポーネントの使い方です。メインに全部載せず、書く場面でだけ呼ぶ分担になっています。

平易な依頼がどう振り分けられるか

依頼は3種類に分かれます。どれも、プラグインを明示的に呼ぶ必要はありません。

依頼の型例着地点
平易な依頼例「ワークアウトの記録を共有できるサイトを作って」着地点quickstartでアプリを立ち上げる
技術的な依頼例「ワークスペースとロールを持つマルチテナントのスキーマを設計して」着地点設計スキルとサブエージェント
悩みの依頼例「RLSのポリシーに疲れた。代わりの案を見せて」着地点Convexの代替案を提示する

3つ目の型は他のスタックで困っている人向けです。例として挙がるのは、書き込み後にキャッシュが古くなる、ORMがN+1クエリを出す、フロントとバックエンドのcodegenを毎回忘れる、の3つが並びます。移行の相談を、Convexの流儀に着地させる入口になっています。

技術的な依頼に対して、プラグインが選ぶ部品は次のとおりです。

やりたいこと選ばれる部品
認証選ばれる部品Convex AuthかWorkOS AuthKit。薄いusersテーブルだけ持つ
バックグラウンド処理選ばれる部品単発はctx.scheduler、定期実行はcrons.ts、複数段階は@convex-dev/workflow
チャットとエージェント選ばれる部品@convex-dev/agent
ベクトル検索・全文検索選ばれる部品defineTable(...).vectorIndex(...)と.searchIndex(...)
レート制限選ばれる部品@convex-dev/rate-limiter
ファイル保存選ばれる部品ctx.storageと署名付きアップロードURL

何が自動で選ばれるかは、自分の依頼文が決めます。「ログインを足して」と書けば認証の部品に着地します。設計を任せたいなら、手段ではなく結果を書くほうが振り分けに乗ります。Convexのドキュメントも、「プロフィール画像をアップロードできるようにして」のような書き方を勧めています。

quickstartは「1文からアプリ」を最後まで走らせる

/quickstartは、思いつきから動くアプリまでを1分以内で進めるスキルです。次の順に動きます。

手順

/quickstartの流れ

  1. 1

    雛形を作る

    Next.jsとshadcnで「wow-shell」と呼ぶ雛形を作り、画面の端にChefパネルを出します。進捗の一覧、点滅するTODO、絞り込みの質問、機能リクエストのフォームが入ります。

  2. 2

    開発サーバーを起動する

    convex devとnext devを、エラー監視を有効にしたまま起動します。

  3. 3

    ブラウザを開く

    動き出した画面をそのまま見せます。

  4. 4

    アイデアを作り込む

    起動した画面を見ながらライブで作ります。convex/配下のコードはconvex-expertに任せます。

作っている途中でChefパネルから機能リクエストを送ると、監視がそれを拾い、ターンをまたいでもエージェントに通知します。ログを見張る必要はありません。ローカルや匿名のデプロイメントでも動きます。

保存時とターン終了時に働く2つのフック

プラグインの価値は、書いた後を検査する2つのフックにあります。

  • 保存前の検査(PreToolUse): dbクエリの.filter(q => q.field(...))と、古い位置引数の関数構文を、ディスクに書かれる前に拒否します。拒否メッセージには正しい書き方が入ります。argsとreturnsの検証子が欠けている場合は、拒否せず助言として表示します
  • ターン終了時の検証(Stop): convex/*.tsに未コミットの変更が残ったまま終わろうとすると、convex codegenとtsc --noEmitを走らせます。.env.localがCONVEX_DEPLOYMENTを指しているときに限り、convex dev --onceも走らせます。デプロイメントを新しく作ることはしません

本物のエラーがあるとき、Stopフックは終了コード2で止めます。止められたエージェントは、直してからでないと終われません。無限ループにならないようstop_hook_activeで守り、全体で約90秒の予算を超えたときは止めずに通します。

Stopフックが止め続けて抜けられない症状は、CLAUDE_CODE_STOP_HOOK_BLOCK_CAPの解説のように別の面から対処できます。

監視は通知で届く

3つの監視は、問題が起きた瞬間にClaude Codeへ通知を出します。

監視見ているもの通知の条件
ランタイムエラー見ているものnpx convex logsのストリーム通知の条件型エラー、スキーマ検証、実行時例外、OCC競合に一致したとき
OCC・インサイト見ているもの10分ごとのnpx convex insights通知の条件新しいOCC競合か読み取り上限が出たとき
機能リクエスト見ているものChefパネルの未処理リクエスト通知の条件新しいリクエストが届いたとき

OCC・インサイトの監視は、ユーザー認証を使うクラウドのデプロイメントでだけ動き、それ以外のデプロイメントでは通知を出しません。通知には対処の定石が付き、トランザクションを小さくする、ホットなカウンターには@convex-dev/aggregateを使う、読み取り上限には.withIndex()か.paginate()を使う、の3つが挙がります。ランタイムエラーの監視は、Convexに紐づいていないプロジェクトでは自分で止まる作りです。

送信されるデータを知って、止める

プラグインは3種類のデータをマシンの外へ出しえます。送信内容を止め方と並べると次のとおりです。

種類送られるもの止め方
使用状況の計測送られるもの乱数のデバイスID、プラグインのバージョン、OSとNode.jsのバージョン、粗いイベント名止め方CONVEX_PLUGIN_TELEMETRY=0かDO_NOT_TRACK=1
アプリの雛形作成送られるもの/quickstartや/addに渡した入力止め方そのフローを呼ばない
セッションの共有送られるもの秘密情報を伏せたセッションの写し止め方/improve-convex-pluginを呼ばない。常に拒否はCONVEX_IMPROVE_CONSENT=never

計測は既定でオンです。.env.localか.envにCONVEX_DEPLOYMENTの行があると、セッション開始のイベントにデプロイメント名とチーム名も載ります。コード、ファイルパス、プロンプトは送信対象に含まれません。

Claude Codeの設定のenvに書けば、全セッションで計測を切れます。

{
  "env": {
    "CONVEX_PLUGIN_TELEMETRY": "0",
    "CONVEX_IMPROVE_CONSENT": "never"
  }
}

/improve-convex-pluginは、最初に使うときに「常に・今回のみ・しない」を聞かれます。「常に」と「しない」は~/.convex/improve-consentに保存され、消せば聞き直されます。エージェントが自分から勧めることはありません。

設計を任せるときのCLAUDE.md

プラグインの規則は汎用です。自分のアプリ固有の制約は、CLAUDE.mdに足します。次は一例です。

## バックエンド
- 新しい機能は、先にテーブル設計と読み取りパスの索引を文章で示してから実装する
- 認証はConvex Authを使い、独自のセッションテーブルを作らない
- 変更の最後に`npx convex codegen`と`npx tsc --noEmit`を実行し、出力を読んで報告する
- 本番デプロイメントには触れない

検証コマンドを最後に実行させる行は、Stopフックと二重になります。フックが動かない環境(プラグインを外した、--plugin-dirを付け忘れた)でも、同じ検証が走るためです。

使い始めの切り分け

切り分け

スキルが効いていないと感じたとき

  1. Q/pluginの一覧にconvexが有効で出ているか？
    答えが入れ直す

    /plugin install convex@claude-plugins-officialを実行し、--plugin-dirで起動した場合は、起動コマンドにフラグが付いているか確かめます。

    答えがはい
  2. Q依頼文に手段の指定が入っていないか？
    答えが結果で書き直す

    「テーブルを3つ作って」より、「ユーザーが投稿に画像を付けられるようにして」のように、結果で頼みます。

    答えがはい
  3. QカレントディレクトリがConvexのプロジェクトか？
    答えがプロジェクトに移る

    エラー監視は、Convexに紐づいていないプロジェクトでは止まります。.env.localにCONVEX_DEPLOYMENTがあるかも確認します。

    答えがはい

それでも振り分けられない

依頼文に/quickstartのようにスキル名を書いて呼びます。

プラグイン一般の入れ方、更新、無効化の手順はプラグイン完全ガイドにまとまっています。

まとめ

このプラグインは、依頼の言葉をConvexの部品に翻訳し、書いた直後に検査する仕組みです。設計を任せる価値は、スキルよりもフックの検査に表れます。一方で、計測が既定でオンで、雛形作成が入力を外部に送る点は、導入前に知っておく条件です。会社のコードで使うなら、環境変数で計測を切り、--plugin-dirで中身を読んでから入れる順が確実です。

この記事を共有:XはてブLinkedIn

関連する記事

Claude Code をもっと見る →