crm

HubSpot CRM オペレーション

このスキルを使用すると、HubSpot CRM v3 API を通じて HubSpot CRM データを読み取り、明示的な確認を得たうえで更新できます。対象は、コンタクトレコード、コンタクト検索、取引パイプラインの表示、取引ステージの変更です。これは単一の CRM ベンダー（HubSpot）向けのツールスキルです。HubSpot アプリやワークフローの構築はアプリケーション開発にあたります。このスキルが担うのは、日常的なエージェントのワークフロー、つまり「このコンタクトは誰か？」「パイプラインには何があるか？」への回答と、確認済みのステージ変更の適用です。

運用上の契約

1. 変更を加える前に、読み取り専用で情報を確認します。 コンタクトの一覧表示や検索、取引やパイプラインの表示は自由に行えます。付属の crm-cli スクリプトは書き込みを一切行わずに読み取りを実行します。
2. 実行前に対象、範囲、ロールバック手段を確認します。 取引を新しいステージに移動すると、収益レポートが参照する共有パイプラインが変更されます。そのため、取引と移動先のステージを指定する明示的な人間の指示に加え、crm-cli による --dry-run のプレビューと --yes による確認が必要です。ステージの移動は元に戻せますが、監査履歴は残ります。実行前に確認してください。
3. 読み取りの範囲を守ります。 HubSpot のページには limit を指定します。タスクに必要な範囲を超えてページを取得しないでください。crm-cli --limit は、すべての一覧表示と検索の件数に上限を設定します。
4. 提示する根拠の範囲を絞ります。 短い名前、メールアドレス、金額、ステージラベルを引用してください。完全なレコード、トークン、生のペイロードをチャットに出力しないでください。
5. オブジェクトモデルを把握します。 コンタクトと取引は、プロパティマップを持つ別々のオブジェクトです。ステージの移行には、ステージラベルではなく、取引のパイプラインから取得したステージ ID（pipelines list）を使用する必要があります。

crm-cli スクリプト

scripts/crm-cli は、HubSpot CRM v3 API を利用する、エージェント優先設計の標準ライブラリのみを使った CLI です。対象となる課題の範囲全体、つまりレコード、検索、パイプラインの表示に対応します。

crm/scripts/crm-cli --help                                # no token or network needed
crm/scripts/crm-cli --json --limit 20 contacts list
crm/scripts/crm-cli --json contacts get --id 51
crm/scripts/crm-cli --json contacts search --query "ada"
crm/scripts/crm-cli --json --limit 20 deals list
crm/scripts/crm-cli --json deals list --pipeline default --stage appointmentscheduled
crm/scripts/crm-cli --json pipelines list
crm/scripts/crm-cli deals update-stage --id 901 --stage closedwon --dry-run   # preview
crm/scripts/crm-cli deals update-stage --id 901 --stage closedwon --yes       # confirmed

終了コード：成功は 0、API エラーまたはチェック失敗は 1、使用方法のエラーは 2 です。ステージの変更にはガードが設けられています。--dry-run または --yes がない場合、スクリプトは終了コード 1 で処理を拒否し、API を呼び出しません。読み取りは --limit の値（デフォルトは 20、最大は 100）で上限が設定されます。

運用の流れ

1. 質問の範囲を定める：CRM 内の人や情報を調べるのか、取引を移動するのかを確認します。contacts search／contacts list または deals list でオブジェクトを特定します。
2. 範囲を絞って読み取る：1 件のレコードには contacts get、パイプラインの表示には deals list（必要に応じてパイプラインやステージで絞り込み）を使用し、ステージラベルを ID に対応付けるには pipelines list を使用します。
3. 回答に必要な情報を整理する：質問に合わせて、コンタクトの詳細、取引金額やステージ、パイプラインの内訳などの根拠をまとめます。
4. 確認を得て実行する：変更を求める人間の指示がある場合に限り、--dry-run でプレビューし、--yes で確認して実行します。
5. 結果を検証する：取引を再読み取り（deals list --stage <target>）し、ステージが変更されたことを確認します。

レコード、検索、パイプラインの表示

• コンタクトレコード（/objects/contacts）：一覧表示（GET）または 1 件の取得（ID による GET）ができます。CLI は名、姓、メールアドレス、会社、作成日を要約します。検索（POST /objects/contacts/search）では、クエリテキストを使ってコンタクトを検索し、--limit で件数を制限します。
• 取引パイプラインの表示（/objects/deals）：金額、パイプライン、ステージとともに取引を一覧表示できます。1 つのパイプラインまたはステージで絞り込むこともできます。pipelines list（/pipelines/deals）は、ステージ ID とラベルを含むパイプラインを返します。絞り込みや更新にはステージ ID を使用してください。
• ステージの変更（PATCH /objects/deals/{id}）：dealstage プロパティを設定する、ガード付きの変更です。--dry-run で移動先のステージをプレビューし、--yes で確認してから、再度読み取って結果を検証してください。対象範囲はステージの移動のみです。その他の取引プロパティの編集はアプリケーション開発にあたります。

アクセスモデル

• HubSpot のプライベートアプリのアクセストークン（pat_...）は、オブジェクトごとに読み取り／書き込みのスコープが設定されています。読み取りには crm.objects.contacts.read と crm.objects.deals.read が必要です。ステージの更新には crm.objects.deals.write が必要です。
• レコードには、プロパティ名（例：dealstage、dealname、amount）をキーとする properties マップが含まれます。プロパティ値は文字列です。CLI は、このスキルが使用するフィールドを要約します。
• トークンは認証情報です。HUBSPOT_TOKEN に保存し、コード、チャット、コミットには決して含めないでください。トークンが漏えいした場合は、プライベートアプリの設定でローテーションしてください。

リファレンスの参照先

次の場合に読み込む	リファレンス
ソース、スコープ表、更新手順	references/00-source-index.md
エンドポイント、ページネーション、オブジェクトモデル、ステージ更新、エラー	references/01-hubspot-crm-operations.md

含まれる成果物

• scripts/crm-cli：範囲を限定した、標準ライブラリのみを使用する CLI（contacts list/get/search、deals list/update-stage、pipelines list、--json、--limit、変更操作は --dry-run／--yes で制御）。
• tests/test_crm_cli.py：変更操作のゲートと読み取り専用の契約を含む、スタブ HubSpot API に対する再現可能なテスト 13 件。
• references/：日付付きのソースインデックスと HubSpot CRM 操作リファレンス。
• evals/evals.json：エージェントの実行結果を評価する、出力品質の評価ケース 6 件。

検証の範囲

主張	最低限必要な証拠
コンタクトが存在する	crm-cli contacts search --query ... --json または contacts get がレコードを返す
パイプラインの表示が正確である	crm-cli deals list --json が、ステージ ID と適用済みフィルターを含む取引を返す
ステージラベルが ID に対応している	crm-cli pipelines list --json がパイプラインのステージマップを返す
ステージ変更が反映された	crm-cli deals update-stage --yes が終了コード 0 で終了し、続けて実行した deals list --stage に該当する取引が表示される
変更操作を安全に実行できる	crm-cli deals update-stage --dry-run が対象の取引と変更先のステージを正確に表示する

厳守事項

• 人間からの指示、--dry-run によるプレビュー、--yes による確認なしに、取引のステージを変更してはいけません。パイプラインの変更は売上レポートと監査履歴に反映されます。
• トークンにオブジェクトのスコープがない可能性がある場合、レコードが存在しないと断言してはいけません。まずアクセスモデルを確認してください。
• --limit を超えて読み取りをページングしてはいけません。レコード全体、トークン、生のペイロードをチャットに出力してはいけません。
• このスキルは HubSpot CRM API を操作します。HubSpot アプリの構築や、他の CRM は対象外です。

使用しない場合

• HubSpot アプリ、ワークフロー自動化、カスタムオブジェクトの構築 — これは HubSpot アプリの開発です。サービス設計については backend-engineering を参照してください。
• HubSpot のマーケティング、シーケンス、メール自動化 — これらは HubSpot Marketing の領域であり、このスキルが対象とする CRM API ではありません。
• 他の CRM（Salesforce、Pipedrive、Zoho）— それぞれ独自の API とツールがあります。このスキルの対象は HubSpot です。
• CRM 戦略、営業プロセスの設計、パイプラインの方法論 — これらは組織・戦略上の業務であり、API 操作ではありません。