CRM ビルダースキル

このスキルについて

このスキルは、CRM ツール — コンタクト、企業、ディール、およびそれらの間の関係を管理するシステムの構築方法を定義します。

CRM は構造的には CPQ とトレーズビルダーとは異なります:

• CPQ / Trades = 1 つのレコードが連続したステージを通過する (ステッパーナビゲーション)
• CRM = 複数のエンティティタイプが相互に関係性を持つ (エンティティナビゲーション)

左サイドバーは ナビゲーターパターン (Contacts、Companies、Deals、Pipeline、Activities) を使用します — ステッパーではありません。ユーザーは連続したステージではなく、エンティティビュー間を切り替えます。

一般的な業種: 営業チーム、コンサルティング企業、エージェンシー、プロフェッショナルサービス、不動産、人材採用、B2B サービス、関係性とディールを追跡するあらゆるビジネス。

ビルダーはこのスキルを読み、特定のビジネス用語とパイプラインステージに関する DOMAIN.md を読んで、顧客の実際のエンティティ、フィールド、ワークフローを含む動作するプロトタイプを生成します。

このスキルを使用する場合

トランスクリプトまたは DOMAIN.md に以下のシグナルが含まれる場合、このスキルを使用してください:

シグナル	例
コンタクト/人物追跡	「顧客データが散在している」、「誰と話したか見つけられない」、「スプレッドシートに連絡先がある」
営業パイプライン	「ディール」、「営業機会」、「パイプライン」、「ステージ」、「成約/失注」
フォローアップ追跡	「フォローアップが漏れている」、「誰が最後に電話したか分からない」
関係管理	「紹介」、「誰が誰を知っているか」、「アカウント管理」
リード管理	「ウェブサイトからのリード」、「インバウンド問い合わせ」、「リード源追跡」

このスキルを使用しないケース:

• 価格設定を伴う製品構成 → cpq-builder を使用
• 建設/トレード業プロジェクト追跡 → trades-builder を使用
• 在庫・ストック管理 → erp-builder を使用 (今後予定)

---

テンプレートコントラクト

構築を開始する前に、テンプレートが提供するもの、このスキルが追加するものを理解してください。これはコントラクトです:

テンプレート (app/layouts/MainLayout.tsx) が含むもの:

• SidebarProvider、Sidebar、SidebarContent、SidebarInset、SidebarTrigger — すでに配線済み
• SidebarContent は 空 — これがあなたの着地点です
• ヘッダー内の 1 つのブランドスロット (ロゴプレースホルダー + 企業名)
• ヘッダーの右クラスタに ModeToggle とユーザーメニュー

このスキルが提供するもの:

• SidebarContent — エンティティナビゲーション (Pipeline、Contacts、Companies、Deals、Activities)、クイックフィルター、最近のレコード (下記のレイアウトパターン参照)
• ヘッダーのブランドスロット — DOMAIN.md からの顧客ロゴと企業名
• ヘッダーの右クラスタ — 既存ユーザーメニューの前にロール切り替え DropdownMenu を追加、スペースがあればグローバル検索入力も追加
• <Outlet /> in <main> — 各エンティティビューのルートコンポーネント経由 (Pipeline がデフォルト)

このスキルが提供しないもの:

• 2 番目の Sidebar コンポーネント。サイドバーは 1 つです。
• SidebarContent 内のブランドタイル。ブランドはヘッダーのみに配置されます。
• SidebarProvider の再配線または折りたたみ動作の置き換え。存在するものを使用してください。
• ステッパーの構築。CRM はエンティティナビゲーション — 連続ステージではなく、並行ビュー。
• 詳細ビューをポップオーバーまたはモーダルに折りたたむこと。リスト/詳細は全ページパターンです (リストビュー → クリック → メインコンテンツ領域の詳細ビュー)。

MainLayout.tsx を再構築したいと思う場合は、やめてください — 答えはほぼ常に SidebarContent を埋めることです。

---

セクション定義

CRM ツールには 5 つのセクション があります。CPQ/トレーズビルダーとは異なり、これらは連続したステージではなく、並行したエンティティビューです。ユーザーはそれらを自由に移動できます。

セクション 1: Pipeline

目的: ディールがステージを通じて移動する視覚的なボードビュー。

表示:

• Kanban スタイルの列、DOMAIN.md の各パイプラインステージに 1 つずつ
• DOMAIN.md がステージを定義していない場合、デフォルトを使用: Lead → Qualified → Proposal → Negotiation → Closed Won / Closed Lost
• 各ディール項目には以下を表示: ディール名、企業、金額、割り当て対象、ステージ内の日数
• 列間のドラッグ&ドロップ (またはクリックしてステージを移動)
• 各列に「ディール追加」ボタン
• 割り当て対象者、日付範囲、またはディール金額でフィルター

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

セクション 2: Contacts

目的: 人物のリスト/詳細ビュー。

リストビュー:

• コンタクトのテーブルまたは軽量リスト
• 列: 名前、メール、電話、企業、最後のアクティビティ、タグ
• 検索とフィルター
• 「コンタクト追加」ボタン

詳細ビュー (コンタクトをクリック):

• コンタクト詳細: 名前、メール、電話、企業 (リンク)、役職/肩書き、ソース、メモ
• 以下のアクティビティタイムライン: 電話、メール、会議、メモ — 最新順
• リンクされたディール: このコンタクトに関連するディールのリスト
• 「アクティビティログ」ボタン: 日付と説明を含む電話、メール、会議、またはメモをすばやく追加

DOMAIN.md からのフィールド:

• Entity Registry → Contact エンティティフィールドがコンタクト詳細フィールドになります
• Terminology Glossary → 正確なフィールド名とラベル
• DOMAIN.md がコンタクトフィールドを定義していない場合、デフォルトを使用: 名前、メール、電話、企業、役職、ソース、メモ

セクション 3: Companies

目的: 組織のリスト/詳細ビュー。

リストビュー:

• 企業のテーブル
• 列: 企業名、業種、コンタクト数、ディール数、ディール総額
• 検索とフィルター
• 「企業追加」ボタン

詳細ビュー (企業をクリック):

• 企業詳細: 名前、業種、規模、ウェブサイト、住所、メモ
• Contacts タブ: この企業にリンクされた人物のリスト
• Deals タブ: この企業にリンクされたディールのリスト
• アクティビティタイムライン: この企業のすべてのコンタクトから集約

DOMAIN.md からのフィールド:

• Entity Registry → Company/Account エンティティフィールド
• 定義されていない場合: 名前、業種、規模、ウェブサイト、住所、メモ

セクション 4: Deals

目的: ディール/営業機会のリスト/詳細ビュー。

リストビュー:

• ディールのテーブル
• 列: ディール名、企業、コンタクト、金額、ステージ (バッジ)、クローズ日、割り当て対象
• 金額、ステージ、クローズ日でソート
• ステージ、割り当て対象者でフィルター
• 「ディール追加」ボタン

詳細ビュー (ディールをクリック):

• ディール詳細: 名前、金額、ステージ (選択可能ドロップダウン)、予想クローズ日、成約可能性、割り当て対象
• リンクされたコンタクトと企業 (クリック可能なリンク)
• このディール特有のアクティビティタイムライン
• メモセクション
• 最終ステージにある場合、「成約にマーク」/「失注にマーク」アクション ボタン

ステージ進行:

• ディールステージは、DOMAIN.md パイプラインステージから入力された Select ドロップダウン
• ステージを変更すると、Pipeline ボードビューが自動更新
• Won/Lost はターミナルステージ — 選択時に win/loss 理由フィールドを表示

セクション 5: Activities

目的: CRM 全体のすべてのアクティビティの時系列フィード。

表示:

• タイムライン/フィードビュー、最新順
• 各アクティビティは以下を表示: タイプアイコン (電話/メール/会議/メモ)、説明、リンクされたコンタクト、リンクされたディール、日付、ログ者
• アクティビティタイプ、日付範囲、人物でフィルター
• 上部に「アクティビティログ」ボタン

アクティビティタイプ: Call、Email、Meeting、Note、Task。区別するためにアイコンを使用します。

• DOMAIN.md が異なるアクティビティタイプを定義している場合、代わりにそれらを使用してください。

レイアウトパターン

CRM ツールはデフォルトで 2 パネルレイアウト (左サイドバー + メインコンテンツ) を使用します。レコード詳細を表示する場合、右サイドバーは文脈的に表示されます。

これはステッパーレイアウトではありません。 左サイドバーはエンティティナビゲーション、連続ステージではありません。

左サイドバー (常に表示、折りたたみ可能)

テンプレートは SidebarProvider、Sidebar、SidebarContent、および SidebarTrigger を app/layouts/MainLayout.tsx に既に配線済みで提供しています。SidebarContent は空です — これはこのスキルがエンティティナビゲーションで埋める場所です。サイドバーを再配線せず、2 番目の Sidebar コンポーネントを追加しないでください。ブランドタイルをその内部に配置しないでください。ブランドアイデンティティはヘッダーのみに配置されます (上記のテンプレートコントラクト参照)。

サイドバーヘッダー: 「CRM」またはビジネス名 + 「CRM」のような文脈的ラベルを使用してください — ワークフロー説明ではなく。ビジネス名が短い場合、「[Business] CRM」は自然に読めます。長い場合、「CRM」だけで問題ありません。ヘッダーはナビゲーションが「何であるか」を説明します。

コンポーネント	コンテンツ
エンティティナビゲーション	SidebarContent 内の垂直ナビリスト、5 つのセクション: Pipeline、Contacts、Companies、Deals、Activities。各ナビ項目: アイコン、ラベル、レコード数バッジ。クリックするとそのエンティティのビューにナビゲート。これはナビゲーター、ステッパーではありません — ステップ番号なし、完了状態なし、連続フロー無し。
クイックフィルター	ナビの下、ユーザーが作成した場合は保存されたフィルターまたはビューを表示。例: 「My deals」、「Hot leads」、「This week's follow-ups」。
最近のレコード	フィルターの下、最近アクセスしたレコード 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 またはステークホルダーマップからロールで localStorage をシード。
• ロール切り替え は、ヘッダーバー内の 単一の DropdownMenu ドロップダウン。
• 割り当てフィルタリング: ロールがアクティブな場合、オプションで pipeline と deal ビューをフィルターして、その人物に割り当てられたレコードのみを表示。
• アクティビティ帰属: ログされたアクティビティはアクティブロールに帰属されるべき。
• CRM は通常、CPQ より厳しいハードパーミッションゲートが少なくなります — ほとんどのユーザーはすべてを見ることができますが、割り当てられたレコードを所有しています。

価格/価値の表示

• Pipeline アイテム、Deal リスト、Deal 詳細にディール値を表示。
• Pipeline ビューの最上部に、ステージごとの総 pipeline 値を表示。
• DOMAIN.md からの通貨を使用。
• フォーマット: 「$25,000」または「$25,000 CAD」、DOMAIN.md に応じて。

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

カードを例外として扱い、デフォルトレイアウトプリミティブではありません。可能な限りコンテンツをページ本文にインラインします。何かが強調、分離、繰り返し、またはダイアログ/詳細フレーミングが本当に必要な場合のみカードを使用します。カード集約的ダッシュボード、カード内のカード、または浮遊パネルの一般グリッドを構築しないでください。

CRM 要素	shadcn コンポーネント	使用注
エンティティナビ項目	垂直スタック内の Button variant="ghost"	SidebarContent 内。アクティブ項目はアクセント背景を取得。アイコン + ラベル + カウントバッジ。
Pipeline 列	列セクション、多数のディール場合 ScrollArea	列ヘッダーはステージ名 + ディール数 + 総値を表示。アイテムが強い分離を必要とする場合のみカードを使用。
ディール項目 (pipeline)	コンパクトクリック可能行または微妙なアイテムブロック	ディール名、企業、値、割り当て avatar。
コンタクト/企業リスト	Table	ソート可能列、上部の検索入力。
レコード詳細	フルウィドスセクション Separator	詳細をメインページ本文にインラインで保持。
アクティビティタイムライン	アイコン付きカスタムリスト	各アイテム: タイプアイコン、説明、日付、リンクされたレコード。人物には Avatar を使用。
ステージバッジ	Badge	ステージ別カラーコーディング: lead=gray、qualified=blue、proposal=amber、negotiation=purple、won=green、lost=red。
ディール値	text-lg font-semibold	Pipeline アイテムと詳細ビューで顕著。
割り当てドロップダウン	Select	DOMAIN.md ステークホルダー名から入力。フリーテキストではありません。
アクティビティタイプセレクタ	Select または RadioGroup	Call、Email、Meeting、Note、Task。
検索入力	検索アイコン付き Input	すべてのリストビューの上部。
アクション ボタン	Button	プライマリ: 「Add contact」、「Log activity」。破壊的: 「Delete」、「Mark as Lost」。
リンクされたレコードチップ	Badge variant="outline"	クリック可能 — リンクされたレコードにナビゲート。
クイック追加フォーム	Dialog またはインラインフォーム	モーダル、現在のビューを離れずにコンタクト/ディールをすばやく追加。
空の状態	中央テキスト + アクション付きインライン空ブロック	「No contacts yet. Add your first contact.」
確認ダイアログ	AlertDialog	レコード削除、ディール失注マーク。
トースト通知	Sonner / toast()	作成、更新、削除、アクティビティログ後。

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

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

DOMAIN.md エンティティパターン	マップ先	セクション内
Contact / Person / Lead / Customer	Contact レコード	Contacts
Company / Account / Organization / Business	Company レコード	Companies
Deal / Opportunity / Sale / Prospect	Deal レコード	Deals + Pipeline
Activity / Call / Meeting / Email / Note	Activity エントリ	Activities + レコードタイムライン
Pipeline / Stage / Status	Pipeline ステージ列	Pipeline
Referral / Source / Lead source	Contact または Deal の Source フィールド	Contact/Deal 詳細

関係マッピング

DOMAIN.md 関係	実装
Contact は Company に属する	Contact には Company フィールド (Select ドロップダウン) があります。Company 詳細はリンクされたコンタクトを表示します。
Deal は Contact を持つ	Deal には Contact フィールド (Select ドロップダウン) があります。Contact 詳細はリンクされたディールを表示します。
Deal は Company を持つ	Deal には Company フィールド (コンタクトの企業から自動入力、編集可能) があります。
Activity は Contact/Deal に結びつく	Activity には Contact および Deal フィールド (Select ドロップダウン) があります。

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

DOMAIN.md ルールパターン	実装
「pipeline stages: X, Y, Z」	Pipeline 列はそれらの正確な名前を使用
「[role] のみディールをクローズできる」	「Mark as Won/Lost」ボタン上の RBAC ゲート
「X 日以内にフォローアップ」	最近のアクティビティなしのコンタクト/ディールに超過バッジを表示
「$X を超えるディールは承認が必要」	高額ディールに承認要件メモを表示
「紹介ソース追跡」	定義済みドロップダウン値を持つコンタクト上の Source フィールド
通貨/税/条件	ディール値およびあらゆる請求書作成ビューに表示

Pipeline ステージデフォルト

DOMAIN.md がパイプラインステージを定義していない場合、以下を使用してください:

ステージ	色	意味
Lead	Gray	新規、未適格な問い合わせ
Qualified	Blue	本当の営業機会として確認
Proposal	Amber	提案または見積が送信
Negotiation	Purple	協議中、条件検討中
Closed Won	Green	ディール署名、収益計上
Closed Lost	Red	ディール未クローズ

これらのデフォルトは DOMAIN.md 状態モデルによってオーバーライド可能です。

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

これらのパターンは Salesforce、HubSpot、Pipedrive、Freshsales から引き出されたものです。CRM ユーザーに馴染みのあるプロトタイプの場合、それに従ってください:

1. すべてがすべてにリンクする

コンタクトは企業にリンク。ディールはコンタクトと企業にリンク。アクティビティはコンタクトとディールにリンク。すべてのリンク名はクリック可能 — クリックするとそのレコードの詳細ビューにナビゲート。

2. アクティビティタイムラインが心臓

すべてのレコード (コンタクト、企業、ディール) はアクティビティタイムラインを表示。最近のインタラクションが最も重要。「この人と最後に話したのはいつ?」は一目で答えられるべき。

3. Pipeline がホームスクリーン

Pipeline ボードビューはデフォルトのランディングページ。営業チームはここで活動。ステージごとの総 pipeline 値は上部に表示。

4. クイック追加はいたるところ

「Log a call」と「Add a deal」はあらゆるビューからアクセス可能であるべき — フローティングアクションボタンまたは永続的な「Quick add」をヘッダーで。ユーザーはインタラクションをログするために移動する必要があります。

5. 検索はグローバル

1 つの検索バー、名前でコンタクト、企業、ディールを検索。結果はエンティティタイプ別にグループ化。

6. 空の状態はアクションをガイド

セクションにレコードがない場合、有用な空の状態を表示: 「No deals yet. Add your first deal to start tracking your pipeline.」プライマリアクションボタンを含める。

リファレンスファイル

このスキルは以下のファイルが存在することを期待します:

ファイル	目的
DOMAIN.md または .tasks/domain.md	ビジネス用語、エンティティ、パイプラインステージ、ロール、ブランドデータ

ビルダーはコード作成の前に DOMAIN.md または .tasks/domain.md を読むべき。