better-chatbot

better-chatbot の貢献と標準スキル

ステータス：本番環境で使用可能 バージョン：3.0.0（段階的開示により最適化） 最終更新日：2025-12-17 依存関係：なし（better-chatbot プロジェクトを参照） 最新バージョン：Next.js 16.0.3、Vercel AI SDK 5.0.98、Better Auth 1.3.34、Drizzle ORM 0.41.0

---

概要

better-chatbot は、Next.js 15 と Vercel AI SDK v5 で構築された、個人やチーム向けのオープンソース AI チャットボットプラットフォームです。マルチモデル AI のサポート（OpenAI、Anthropic、Google、xAI、Ollama、OpenRouter）に加え、MCP（Model Context Protocol）ツールの統合、ビジュアルワークフロービルダー、リアルタイム音声アシスタント、チームコラボレーションなどの高度な機能を備えています。

このスキルでは、better-chatbot で使用されているプロジェクト固有の規約とパターンを Claude に教えます。これにより、貢献が確立された標準に従い、よくある問題を避けられるようになります。

---

クイックスタート

開発環境のセットアップ

# Clone and install
git clone https://github.com/cgoinglove/better-chatbot.git
cd better-chatbot
pnpm install

# Configure environment
cp .env.example .env
# Add your API keys: OPENAI_API_KEY, ANTHROPIC_API_KEY, etc.
# Add database URL: DATABASE_URL="postgresql://..."
# Add auth secret: BETTER_AUTH_SECRET="your-secret"

# Run development server
pnpm dev

主なコマンド

• pnpm dev - 開発サーバーを起動
• pnpm build - 本番ビルド
• pnpm test - 単体テストを実行
• pnpm test:e2e - E2E テストを実行（DB と API キーが必要）
• pnpm check - リント、型チェック、テストを実行（PR の前に実行）

リポジトリ構成

better-chatbot/
├── src/
│   ├── app/                # Next.js routes + API
│   ├── components/         # UI components by domain
│   ├── lib/               # Core logic (ai, db, validations)
│   ├── hooks/             # React hooks
│   └── types/             # TypeScript types
├── tests/                 # E2E Playwright tests
└── drizzle/              # Database migrations

---

コアアーキテクチャ

3 層ツールシステム

Better-chatbot は、AI 機能に 3 層のツールアーキテクチャを採用しています。

1. MCP ツール - Model Context Protocol を介した外部ツール
2. ワークフローツール - ビジュアルな DAG ベースのワークフロー
3. デフォルトツール - アプリに組み込まれたツール（ウェブ検索、画像生成など）

詳細：ツールの実装や実行方法の理解には、references/tool-system.md を読み込んでください。

API パターン

ルートは、ストリーミングを優先するアーキテクチャと safe() ラッパーを使用した防御的プログラミングを取り入れた、RESTful な規約に従っています。

詳細：API ルートの構築やストリーミングの実装には、references/api-architecture.md を読み込んでください。

コンポーネントの設計方針

コンポーネントは複合コンポーネントパターンを使用し、機能ごとに整理されています。ツールの実行処理とレンダリングは分離されています。

詳細：UI コンポーネントの構築には、references/component-patterns.md を読み込んでください。

データベースとリポジトリパターン

すべてのデータベースアクセスは、Drizzle ORM を使用するリポジトリクラスを介して抽象化されています。

詳細：データベースクエリの実装には、references/database-patterns.md を読み込んでください。

---

知っておくべき主なエラー 5 件

エラー #1：サーバーアクションの認証チェック忘れ

エラー：認証されていないユーザーが保護されたアクションにアクセスする 理由：認証を手動で実装すると一貫性がなくなる 防止策：validatedActionWithUser または validatedActionWithAdminPermission を使用する

// ❌ BAD: Manual auth check
export async function updateProfile(data: ProfileData) {
  const session = await getSession()
  if (!session) throw new Error("Unauthorized")
  // ... rest of logic
}

// ✅ GOOD: Use validator
export const updateProfile = validatedActionWithUser(
  profileSchema,
  async (data, formData, user) => {
    // user is guaranteed to exist, auto-error handling
  }
)

エラー #2：ツールの型の不一致

エラー：ツール実行時のランタイム型エラー 理由：実行前にツールの型を確認していない 防止策：実行時の型の絞り込みにはブランド型タグを使用する

// ❌ BAD: Assuming tool type
const result = await executeMcpTool(tool)

// ✅ GOOD: Check tool type
if (VercelAIMcpToolTag.isMaybe(tool)) {
  const result = await executeMcpTool(tool)
} else if (VercelAIWorkflowToolTag.isMaybe(tool)) {
  const result = await executeWorkflowTool(tool)
}

エラー #3：FormData の解析エラー

エラー：フォーム送信時のエラー処理に一貫性がない 理由：場当たり的な検証を伴う FormData の手動解析 防止策：バリデーターによる自動解析を使用する

// ❌ BAD: Manual parsing
const name = formData.get("name") as string
if (!name) throw new Error("Name required")

// ✅ GOOD: Validator with Zod
const schema = z.object({ name: z.string().min(1) })
export const action = validatedAction(schema, async (data) => {
  // data.name is validated and typed
})

エラー #4：フィールド間の検証の問題

エラー：パスワードの不一致が検証されない 理由：関連するフィールドを個別に検証している 防止策：Zod の superRefine を使用する

// ❌ BAD: Separate checks
if (data.password !== data.confirmPassword) { /* error */ }

// ✅ GOOD: Zod superRefine
const schema = z.object({
  password: z.string(),
  confirmPassword: z.string()
}).superRefine((data, ctx) => {
  if (data.password !== data.confirmPassword) {
    ctx.addIssue({
      code: z.ZodIssueCode.custom,
      message: "Passwords don't match",
      path: ["confirmPassword"]
    })
  }
})

エラー #5：Zustand の状態変更

エラー：状態を更新しても再レンダリングされない 理由：新しいオブジェクトを作成せず、状態を直接変更している 防止策：スプレッド演算子を使った浅い更新を使用する

// ❌ BAD: Direct mutation
set((state) => {
  state.user.name = "New Name" // Mutation!
})

// ✅ GOOD: Shallow update
set((state) => ({
  user: { ...state.user, name: "New Name" }
}))

すべてのエラーについて：上位 5 件以外の問題のデバッグには、references/common-errors.md を読み込んでください。

---

重要なルール

必ず行うこと

✅ サーバーアクションには validatedActionWithUser または validatedActionWithAdminPermission を使用する ✅ 実行前にブランド型タグでツールの型を確認する ✅ フィールド間の検証には Zod の superRefine を使用する ✅ 単体テストを追加する（正常系＋失敗ケースを1つ） ✅ PR を提出する前に pnpm check を実行する ✅ UI を変更した場合は、視覚的なドキュメントを含める ✅ PR タイトルには Conventional Commit 形式を使用する ✅ 重要なフローに触れた場合は E2E テストを実行する

絶対に行わないこと

❌ 認証バリデーターを使わずにサーバーアクションを実装する ❌ 実行時チェックをせずにツールの型を決めつける ❌ FormData を手動で解析する（バリデーターを使用する） ❌ Zustand の状態を直接変更する（浅い更新を使用する） ❌ クリーンなデータベースで初回ユーザーのテストを省略する ❌ pnpm check を実行せずにコミットする ❌ 視覚的なドキュメントなしで PR を提出する（UI を変更した場合） ❌ Conventional Commit 以外の形式を使用する

---

参照資料を読み込むタイミング

better-chatbot の特定の側面に取り組む際は、参照ファイルを読み込んでください。

API アーキテクチャ（references/api-architecture.md）

以下の場合に読み込みます：

• 新しい API ルートやエンドポイントを実装するとき
• ルートハンドラーのパターンを理解するとき
• ストリーミングレスポンスを扱うとき
• safe() を使った防御的プログラミングを実装するとき
• API 関連の問題をトラブルシューティングするとき
• 共有ビジネスロジックを構築するとき

ツールシステム（references/tool-system.md）

以下の場合に読み込みます：

• 新しい MCP ツールを追加するとき
• ワークフローツールを作成するとき
• ツールのライフサイクルを理解するとき
• ツールの実行をデバッグするとき
• ツールのフィルタリングやメンションを実装するとき
• 3 層のツールアーキテクチャを扱うとき

コンポーネントのパターン（references/component-patterns.md）

以下の場合に読み込みます：

• 新しい UI コンポーネントを構築するとき
• 複合コンポーネントのパターンを理解するとき
• 状態管理を実装するとき
• Zustand ストアを扱うとき
• コンポーネント API を設計するとき
• ツールの実行とレンダリングを分離するとき

データベースのパターン（references/database-patterns.md）

以下の場合に読み込みます：

• 新しいリポジトリークラスを作成するとき
• 複雑なデータベースクエリーを記述するとき
• トランザクションを実装するとき
• リポジトリーパターンを理解するとき
• データベースの問題をトラブルシューティングするとき
• Drizzle ORM を扱うとき

アーキテクチャ原則（references/architectural-principles.md）

以下の場合に読み込みます：

• アーキテクチャ上の判断を行うとき
• 設計思想を理解するとき
• プログレッシブエンハンスメントを実装するとき
• ストリーミング優先のパターンに従うとき
• 防御的プログラミングを徹底するとき
• DRY 原則の適用方法を理解するとき

拡張ポイント（references/extension-points.md）

以下の場合に読み込みます：

• チャットボットをカスタム機能で拡張するとき
• 新しいツールタイプを追加するとき
• 既存の動作をカスタマイズするとき
• プラグインアーキテクチャを理解するとき
• 外部サービスを統合するとき

UX パターン（references/ux-patterns.md）

以下の場合に読み込みます：

• @mention 機能を実装するとき
• UX パターンを理解するとき
• 複数モデルのサポートを扱うとき
• インタラクションフローを設計するとき
• チャット UI コンポーネントを構築するとき

テンプレート（references/templates.md）

以下の場合に読み込みます：

• 新しいルート、ツール、コンポーネントを追加するとき
• コードテンプレートに従うとき
• 実装全体の例を理解するとき
• 新機能をゼロから始めるとき
• 標準的なパターンを実装するとき

サーバーアクション（references/server-actions.md）

以下の場合に読み込みます：

• サーバーアクションを実装するとき
• アクションバリデーターを理解するとき
• サーバー側の検証パターンに従うとき
• サーバーアクションの問題をトラブルシューティングするとき
• FormData を扱うとき

よくあるエラー（references/common-errors.md）

以下の場合に読み込みます：

• 上位 5 件以外の問題をデバッグするとき
• 特定のエラーメッセージに遭遇したとき
• エラーのパターンを理解するとき
• よくある問題の解決策を探すとき
• 既知の問題を防ぐとき

リポジトリーのガイドライン（references/AGENTS.md）

以下の場合に読み込みます：

• プロジェクト構成を理解するとき
• コーディング規約に従うとき
• 開発環境をセットアップするとき
• テストやビルドを実行するとき
• コミットや PR のガイドラインを理解するとき

コントリビューション（references/CONTRIBUTING.md）

以下の場合に読み込みます：

• コントリビュートの準備をするとき
• PR のプロセスを理解するとき
• コミットメッセージの規約に従うとき
• プルリクエストを提出するとき
• 視覚的なドキュメントを追加するとき

---

バンドルされたリソースの使用

このスキルには、12 個のリファレンスファイルが含まれています。

技術リファレンス（10 ファイル）：

• api-architecture.md - API パターンとルートハンドラー
• tool-system.md - 3 層のツールアーキテクチャ
• component-patterns.md - UI コンポーネントの設計
• database-patterns.md - リポジトリパターンと Drizzle ORM
• architectural-principles.md - 設計思想
• extension-points.md - システムの拡張方法
• ux-patterns.md - UX パターンと @mentions
• templates.md - ルート／ツール／コンポーネントのコードテンプレート
• server-actions.md - サーバーアクションのバリデーター
• common-errors.md - エラーの完全なカタログ

リポジトリリファレンス（2 ファイル）：

• AGENTS.md - リポジトリ構成と開発コマンド
• CONTRIBUTING.md - コントリビューションのワークフローと PR ガイドライン

特定の情報が必要な場合は、必要に応じてリファレンスを読み込んでください。読み込むタイミングについては、「リファレンスを読み込むタイミング」セクションを参照してください。

---

依存関係

コア：

• Next.js 15+（App Router）
• Vercel AI SDK 5+
• Better Auth 1.3+
• Drizzle ORM 0.40+
• PostgreSQL

テスト：

• Vitest（単体テスト）
• Playwright（E2E テスト）

ツール：

• TypeScript 5+
• Biome（フォーマット＋リント）
• pnpm 8+

---

公式ドキュメント

• リポジトリ：https://github.com/cgoinglove/better-chatbot
• Vercel AI SDK：https://sdk.vercel.ai/docs
• Better Auth：https://www.better-auth.com/docs
• Drizzle ORM：https://orm.drizzle.team/docs/overview
• MCP Spec：https://modelcontextprotocol.io/introduction

---

本番環境での例

このスキルは、本番環境で稼働する better-chatbot リポジトリを基にしています。コア機能を対象とした 48 件の E2E テストがあり、現在も積極的に開発が進められ、コミュニティからのコントリビューションも増えています。

---

最終確認日：2025-12-17 | バージョン：3.0.0