crm-builder

CRM ビルダースキル

このスキルでできること

このスキルでは、CRM ツールの構築方法を定義します。CRM ツールとは、連絡先、企業、案件、およびそれらの間の関係を管理するシステムです。

CRM は、構造上 CPQ や trades-builder とは異なります。

• CPQ / Trades ＝1 つのレコードが順次ステージを進みます（ステッパーナビゲーション）。
• CRM ＝複数のエンティティタイプが相互に関係します（エンティティナビゲーション）。

左サイドバーでは、ナビゲーターパターン（連絡先、企業、案件、パイプライン、アクティビティ）を使用します。ステッパーではありません。ユーザーは順次ステージではなく、エンティティビューを切り替えます。

一般的な業種： 営業チーム、コンサルティング会社、代理店、専門サービス、不動産、人材採用、B2B サービス、および関係や案件を追跡するあらゆるビジネス。

ビルダーはこのスキルを読み、特定のビジネス用語やパイプラインのステージが記載された DOMAIN.md を読み込み、顧客固有のエンティティ、フィールド、ワークフローを備えた動作するプロトタイプを生成します。

このスキルを使用するタイミング

トランスクリプトまたは DOMAIN.md に次のような兆候がある場合は、このスキルを使用してください。

兆候	例
連絡先・人物の追跡	「顧客データがあちこちにある」、「誰と話したか見つけられない」、「連絡先をスプレッドシートで管理している」
営業パイプライン	「案件」、「商談」、「パイプライン」、「ステージ」、「受注／失注」
フォローアップの追跡	「フォローアップが抜け落ちる」、「最後に誰が電話したか誰も把握していない」
関係管理	「紹介」、「誰が誰を知っているか」、「アカウント管理」
リード管理	「ウェブサイトからのリード」、「インバウンドの問い合わせ」、「リードソースの追跡」

次の用途にはこのスキルを使用しないでください。

• 価格設定を伴う製品構成 → cpq-builder を使用してください
• 建設／工事プロジェクトの追跡 → trades-builder を使用してください
• 在庫管理 → erp-builder を使用してください（今後対応予定）

---

テンプレートの契約事項

構築を始める前に、テンプレートに含まれるものと、このスキルが追加するものを確認してください。以下が契約事項です。

テンプレート（app/layouts/MainLayout.tsx）には、次のものが含まれています。

• SidebarProvider、Sidebar、SidebarContent、SidebarInset、SidebarTrigger — すでに配線済みです
• SidebarContent は空です — ここが実装領域です
• ヘッダー内のブランドスロット 1 つ（ロゴのプレースホルダー＋会社名）
• ヘッダー右側のまとまりにある ModeToggle とユーザーメニュー

このスキルで実装するもの：

• SidebarContent — エンティティナビゲーション（パイプライン、連絡先、企業、案件、アクティビティ）、クイックフィルター、最近のレコードを配置します（後述のレイアウトパターンを参照）
• ヘッダーのブランドスロット — DOMAIN.md に記載されたクライアントのロゴと会社名を配置します
• ヘッダー右側のまとまり — 既存のユーザーメニューの前にロール切り替え用の DropdownMenu を追加します。余裕があればグローバル検索入力欄も追加します
• <main> 内の <Outlet /> — 各エンティティビューのルートコンポーネントから設定します（デフォルトはパイプラインです）

このスキルでは、次のことは行いません。

• 2 つ目の Sidebar コンポーネントを追加すること。サイドバーは 1 つだけです。
• SidebarContent 内にブランドタイルを配置すること。ブランドはヘッダーのみに配置します。
• SidebarProvider を再配線したり、折りたたみ動作を置き換えたりすること。既存のものを使用してください。
• ステッパーを構築すること。CRM では、順次ステージではなく、並列のビューを切り替えるエンティティナビゲーションを使用します。
• デフォルトで詳細ビューをポップオーバーやモーダルに折りたたむこと。リスト／詳細はフルページパターンです（リストビュー → クリック → メインコンテンツ領域の詳細ビュー）。

MainLayout.tsx を再構成したくなった場合は、作業を止めてください。ほとんどの場合、答えは SidebarContent を埋めることです。

---

セクションの定義

CRM ツールには5 つのセクションがあります。CPQ／trades-builder とは異なり、これらは順次ステージではなく、並列のエンティティビューです。ユーザーは自由にセクション間を移動できます。

セクション 1：パイプライン

概要： ステージごとに進行中の案件を視覚的に表示するボードです。

表示内容：

• DOMAIN.md のパイプラインステージごとに列を設けた、カンバン形式の表示
• DOMAIN.md にステージの定義がない場合は、次を使用します：リード → 見込みあり → 提案 → 交渉 → 受注 / 失注
• 各案件には、案件名、会社、金額、担当者、ステージに滞在している日数を表示します
• 列間のドラッグ＆ドロップ（またはクリックしてステージを移動）
• 各列に「案件を追加」ボタン
• 担当者、日付範囲、案件金額で絞り込み

DOMAIN.md にパイプラインステージがない場合は、上記のデフォルトを使用します。顧客はプロトタイプを見た後にステージを調整します。

セクション 2：連絡先

概要： 人物の一覧／詳細表示です。

一覧表示：

• 連絡先をテーブルまたはシンプルなリストで表示
• 列：氏名、メールアドレス、電話番号、会社、最終アクティビティ、タグ
• 検索と絞り込み
• 「連絡先を追加」ボタン

詳細表示（連絡先をクリック）：

• 連絡先の詳細：氏名、メールアドレス、電話番号、会社（リンク付き）、役職、ソース、メモ
• 下部にアクティビティのタイムラインを表示：通話、メール、会議、メモ（新しい順）
• 関連案件：この連絡先に関連付けられた案件の一覧
• 「アクティビティを記録」ボタン：日付と説明を入力して、通話、メール、会議、またはメモをすばやく追加

DOMAIN.md のフィールド：

• Entity Registry → Contact エンティティのフィールドを、連絡先の詳細フィールドとして使用します
• Terminology Glossary → 正確なフィールド名とラベルを使用します
• DOMAIN.md に連絡先のフィールドが定義されていない場合は、氏名、メールアドレス、電話番号、会社、役職、ソース、メモを使用します

セクション 3：会社

概要： 組織の一覧／詳細表示です。

一覧表示：

• 会社のテーブル
• 列：会社名、業種、連絡先数、案件数、案件総額
• 検索と絞り込み
• 「会社を追加」ボタン

詳細表示（会社をクリック）：

• 会社の詳細：会社名、業種、規模、ウェブサイト、住所、メモ
• 連絡先タブ：この会社に関連付けられた人物の一覧
• 案件タブ：この会社に関連付けられた案件の一覧
• アクティビティのタイムライン：この会社のすべての連絡先のアクティビティを集約して表示

DOMAIN.md のフィールド：

• Entity Registry → Company/Account エンティティのフィールド
• 定義されていない場合は、会社名、業種、規模、ウェブサイト、住所、メモを使用します

セクション 4：案件

概要： 案件／商談の一覧／詳細表示です。

一覧表示：

• 案件のテーブル
• 列：案件名、会社、連絡先、金額、ステージ（バッジ）、成約予定日、担当者
• 金額、ステージ、成約予定日で並べ替え
• ステージ、担当者で絞り込み
• 「案件を追加」ボタン

詳細表示（案件をクリック）：

• 案件の詳細：案件名、金額、ステージ（選択可能なドロップダウン）、成約予定日、確度、担当者
• 関連する連絡先と会社（クリック可能なリンク）
• この案件固有のアクティビティのタイムライン
• メモセクション
• 最終ステージでは「受注としてマーク」／「失注としてマーク」アクションボタンを表示

ステージの進行：

• 案件のステージは、DOMAIN.md のパイプラインステージから選択肢を設定した Select ドロップダウンです
• ステージを変更すると、パイプラインのボード表示が自動的に更新されます
• 受注／失注は終端ステージです。選択時に受注／失注理由のフィールドを表示します

セクション 5：アクティビティ

概要： CRM 全体のすべてのアクティビティを時系列で表示するフィードです。

表示内容：

• タイムライン／フィード形式で表示し、新しい順に並べます
• 各アクティビティには、種類を示すアイコン（通話／メール／会議／メモ）、説明、関連する連絡先、関連する案件、日付、記録者を表示します
• アクティビティの種類、日付範囲、人物で絞り込み
• 上部に「アクティビティを記録」ボタン

アクティビティの種類： 通話、メール、会議、メモ、タスク。アイコンで区別します。

• DOMAIN.md で異なるアクティビティの種類が定義されている場合は、そちらを使用します。

レイアウトパターン

CRM ツールは、デフォルトで2 パネルレイアウト（左サイドバー＋メインコンテンツ）を使用します。レコードの詳細を表示すると、状況に応じて右サイドバーが表示されます。

これはステッパーレイアウトではありません。 左サイドバーはエンティティのナビゲーション用であり、順次進行するステージではありません。

左サイドバー（常時表示、折りたたみ可能）

テンプレートには、すでに app/layouts/MainLayout.tsx に設定済みの SidebarProvider、Sidebar、SidebarContent、SidebarTrigger が含まれています。SidebarContent は空です。このスキルでは、その領域にエンティティのナビゲーションを追加します。サイドバーを再設定したり、2つ目の Sidebar コンポーネントを追加したり、サイドバー内にブランドタイルを配置したりしないでください。ブランドアイデンティティはヘッダーのみに配置します（上記のテンプレート要件を参照）。

サイドバーの見出し：「CRM」や「事業名 + CRM」のように、コンテキストに合ったラベルを使用してください。事業名が短ければ「[事業名] CRM」が自然です。長ければ「CRM」だけでかまいません。見出しはナビゲーションが何であるかを示します。

コンポーネント	内容
エンティティナビゲーション	SidebarContent 内に、5つのセクション（Pipeline、Contacts、Companies、Deals、Activities）を含む縦型のナビゲーションリストを配置します。各ナビゲーション項目には、アイコン、ラベル、レコード件数バッジを表示します。クリックすると、そのエンティティのビューに移動します。これはナビゲーターであり、ステッパーではありません。ステップ番号、完了状態、順次進行するフローは使用しません。
クイックフィルター	ナビゲーションの下に、ユーザーが作成した保存済みフィルターやビューを表示します。例：「自分の案件」、「有望なリード」、「今週のフォローアップ」。
最近のレコード	フィルターの下に、最近アクセスしたレコード（エンティティの種類は問いません）を3～5件表示し、すばやく移動できるようにします。各項目には名前とエンティティタイプのバッジを表示します。スクロールしなくても常に見えるよう、このセクションをサイドバーの下部付近に固定します。

メインコンテンツ（中央 — セクションごとに切り替わる）

選択したナビゲーション項目に応じて、アクティブなセクションを表示します。 一度に表示するセクションは1つだけです。

{activeSection === "pipeline" && <PipelineView />}
{activeSection === "contacts" && <ContactsView />}
{activeSection === "companies" && <CompaniesView />}
{activeSection === "deals" && <DealsView />}
{activeSection === "activities" && <ActivitiesView />}

各セクション内のリスト／詳細パターン：

• デフォルトでは、エンティティに応じてリストビュー、テーブル、または軽量なボードを表示します。
• レコードをクリックすると、全幅セクション、アクティビティタイムライン、リンクされたレコードを含む詳細ビューを表示します。
• リストに戻るには、「リストに戻る」ボタンまたはパンくずリストを使用します。
• これはSalesforce／HubSpotで一般的なパターンです。

右サイドバー（コンテキストに応じて表示 — 詳細ビュー上）

レコードの詳細（連絡先、会社、案件）を表示するとき、右サイドバーに次の情報を表示できます。

• クイックサマリー — 主要フィールドをひと目で確認できます。
• リンクされたレコード — 関連する連絡先、案件、会社を表示します。
• 今後のアクティビティ — 次に予定されている通話／会議を表示します。

このサイドバーはプロトタイプでは省略可能です。メインコンテンツ領域に十分なスペースがあれば、詳細ビューを単一パネルにできます。レコードの詳細でコンテキストを同時に確認できる利点がある場合にのみ、右サイドバーを追加してください。

RBACの動作

• DOMAIN.md の User Roles または Stakeholder Map に記載されたロールを localStorage に初期データとして設定します。
• ロール切り替えは、ヘッダーバー内の単一の DropdownMenu ドロップダウンで行います。
• 担当者によるフィルタリング：ロールが有効な場合、必要に応じてパイプラインビューと案件ビューをフィルタリングし、その担当者に割り当てられたレコードのみを表示します。
• アクティビティの帰属：記録されるアクティビティは、アクティブなロールに帰属させます。
• CRMでは通常、CPQほど厳格な権限ゲートは必要ありません。ほとんどのユーザーはすべてを閲覧できますが、自分に割り当てられたレコードを管理します。

価格／金額の表示

• パイプライン項目、案件リスト、案件詳細に案件金額を表示します。
• パイプラインビューの上部に、ステージごとのパイプライン総額を表示します。
• DOMAIN.md に記載された通貨を使用します。
• 表記例：DOMAIN.md の内容に応じて「$25,000」または「$25,000 CAD」。

shadcn/ui コンポーネントのマッピング

カードは例外として扱い、標準のレイアウト要素にはしないでください。可能な限り、コンテンツはページ本文に直接配置します。カードを使うのは、強調、分離、繰り返し、またはダイアログや詳細表示の枠組みが本当に必要な場合に限ります。カードだらけのダッシュボード、カードの中のカード、汎用的な浮動パネルのグリッドは作らないでください。

CRM 要素	shadcn コンポーネント	使用上の注意
エンティティのナビゲーション項目	縦に並べた Button variant="ghost"	SidebarContent 内に配置します。アクティブな項目にはアクセント背景を付けます。アイコン＋ラベル＋件数バッジを表示します。
パイプラインの列	列セクション。案件が多い場合は ScrollArea	列のヘッダーにはステージ名＋案件数＋合計金額を表示します。項目を明確に分離する必要がある場合に限り、カードを使います。
案件項目（パイプライン）	クリック可能なコンパクトな行、または控えめな項目ブロック	案件名、会社名、金額、担当者のアバターを表示します。
連絡先／会社の一覧	Table	列の並べ替えに対応し、上部に検索入力欄を配置します。
レコードの詳細	Separator を使った全幅のセクション	詳細はメインページ本文に直接配置します。
アクティビティのタイムライン	アイコン付きのカスタムリスト	各項目に、種類を示すアイコン、説明、日付、リンク先レコードを表示します。人物には Avatar を使います。
ステージバッジ	Badge	ステージごとに色を分けます：リード＝グレー、有望＝ブルー、提案＝アンバー、交渉中＝パープル、成約＝グリーン、失注＝レッド。
案件金額	text-lg font-semibold	パイプライン項目と詳細表示で目立たせます。
担当者のドロップダウン	Select	DOMAIN.md の関係者名から選択肢を設定します。自由入力にはしません。
アクティビティの種類セレクター	Select または RadioGroup	電話、メール、ミーティング、メモ、タスク。
検索入力欄	検索アイコン付きの Input	すべての一覧表示の上部に配置します。
アクションボタン	Button	主な操作：「連絡先を追加」、「アクティビティを記録」。破壊的な操作：「削除」、「失注にする」。
リンクされたレコードのチップ	Badge variant="outline"	クリック可能にし、リンク先のレコードに移動します。
クイック追加フォーム	Dialog またはインラインフォーム	現在の表示から離れずに連絡先／案件をすばやく追加できるモーダルです。
空の状態	中央揃えのテキスト＋アクションを含むインラインの空ブロック	「連絡先はまだありません。最初の連絡先を追加してください。」
確認ダイアログ	AlertDialog	レコードの削除、案件の失注処理に使用します。
トースト通知	Sonner / toast()	作成、更新、削除、アクティビティの記録後に表示します。

決定論的なマッピングルール

エンティティ → CRM レコードのマッピング

DOMAIN.md のエンティティパターン	マッピング先	セクション
Contact / Person / Lead / Customer	連絡先レコード	連絡先
Company / Account / Organization / Business	会社レコード	会社
Deal / Opportunity / Sale / Prospect	案件レコード	案件＋パイプライン
Activity / Call / Meeting / Email / Note	アクティビティ項目	アクティビティ＋レコードのタイムライン
Pipeline / Stage / Status	パイプラインのステージ列	パイプライン
Referral / Source / Lead source	連絡先または案件のソースフィールド	連絡先／案件の詳細

関係性のマッピング

DOMAIN.md の関係性	実装
連絡先が会社に所属する	連絡先に会社フィールド（Select ドロップダウン）を設けます。会社の詳細には、リンクされた連絡先を表示します。
案件に連絡先がある	案件に連絡先フィールド（Select ドロップダウン）を設けます。連絡先の詳細には、リンクされた案件を表示します。
案件に会社がある	案件に会社フィールドを設けます（連絡先の会社から自動入力し、編集可能にします）。
アクティビティが連絡先／案件に紐付く	アクティビティに連絡先フィールドと案件フィールド（Select ドロップダウン）を設けます。

ビジネスルール → 動作のマッピング

DOMAIN.md のルールパターン	実装
「パイプラインのステージ：X、Y、Z」	パイプラインの列に、指定された名称をそのまま使います。
「[role] のみが案件を成約できる」	「成約にする／失注にする」ボタンに RBAC の制御を適用します。
「X 日以内にフォローアップ」	最近アクティビティがない連絡先／案件に、期限超過バッジを表示します。
「$X を超える案件には承認が必要」	高額案件に承認要件の注記を表示します。
「紹介元のトラッキング」	定義済みのドロップダウン値を持つソースフィールドを連絡先に設けます。
通貨／税金／条件	案件金額や請求関連の表示に反映します。

パイプラインのステージのデフォルト

DOMAIN.mdでパイプラインのステージが定義されていない場合は、以下を使用します。

ステージ	色	意味
Lead	グレー	新規の未評価の問い合わせ
Qualified	青	実際の商談であることが確認済み
Proposal	アンバー	提案または見積もりを送付済み
Negotiation	紫	条件を調整しながら交渉中
Closed Won	緑	契約締結、売上計上済み
Closed Lost	赤	商談不成立

これらのデフォルトは、DOMAIN.mdのステートモデルで上書きできます。

実際のCRMから学ぶ主要なUXパターン

これらのパターンは、Salesforce、HubSpot、Pipedrive、Freshsalesを参考にしています。CRMユーザーにとって馴染みのあるプロトタイプにするため、以下に従ってください。

1. あらゆる情報を相互にリンクする

連絡先は企業にリンクします。商談は連絡先と企業にリンクします。アクティビティは連絡先と商談にリンクします。リンクされた名前はすべてクリック可能にし、クリックするとそのレコードの詳細画面に移動します。

2. アクティビティのタイムラインが中心となる

すべてのレコード（連絡先、企業、商談）にアクティビティのタイムラインを表示します。最も重要なのは直近のやり取りです。「この人と最後に話したのはいつか？」が一目でわかるようにします。

3. パイプラインをホーム画面にする

パイプラインのボードビューをデフォルトのランディングページにします。営業チームはここを中心に作業します。ステージごとのパイプラインの合計金額を上部に表示します。

4. どこからでもクイック追加できるようにする

「通話を記録」と「商談を追加」は、フローティングアクションボタン、またはヘッダーに常時表示する「クイック追加」から、どのビューからでも利用できるようにします。ユーザーがやり取りを記録するために別の画面へ移動する必要がないようにします。

5. 全体検索を用意する

名前で連絡先、企業、商談を検索できる検索バーを1つ用意します。検索結果はエンティティの種類ごとにグループ化します。

6. 空の状態から次のアクションを案内する

セクションにレコードがない場合は、役立つ空の状態を表示します。「商談はまだありません。最初の商談を追加して、パイプラインの追跡を始めましょう。」のように案内し、主要なアクションボタンを含めます。

参照ファイル

このスキルでは、以下のファイルが存在することを前提としています。

ファイル	用途
DOMAIN.md or .tasks/domain.md	ビジネス用語、エンティティ、パイプラインのステージ、役割、ブランドデータ

ビルダーはコードを書く前に、DOMAIN.mdまたは.tasks/domain.mdを読む必要があります。