HubSpot CRM 操作は何をしますか？

このスキルを使用して、HubSpot CRM v3 API を介してHubSpot CRMデータを読み取り、明示的な確認を得て更新します：連絡先レコード、連絡先検索、商談パイプライン表示、商談ステージ変更。これは1つのCRMベンダー（HubSpot）向けのツールスキルです。HubSpotアプリやワークフローの構築はアプリケーション開発です。このスキルは日常的なエージェントワークフローを担当します：「この連絡先は誰？」「パイプラインはどうなっている？」といった質問に答え、確認済みのステージ変更を適用します。

運用契約

変更を行う前に読み取り専用で調査する。 連絡先の一覧表示と検索、商談とパイプラインの表示は自由に行います。バンドルされている crm-cli スクリプトは読み取り操作では何も書き込みません。
対象、範囲、ロールバック経路を確認してから行動する。 商談を新しいステージに移動すると、収益レポートが参照する共有パイプラインが変更されます。そのため、商談名と対象ステージを明示した人間の指示、さらに crm-cli による --dry-run プレビューと --yes 確認が必要です。ステージの移動は元に戻せますが、監査履歴は残ります。行動する前に確認してください。
制限付き読み取りを尊重する。 HubSpotは limit でページネーションします。タスクに必要な範囲を超えてページングしないでください。crm-cli --limit はすべての一覧表示と検索を制限します。
証拠をコンパクトに保つ。 短い名前、メールアドレス、金額、ステージラベルを引用し、完全なレコード、トークン、生のペイロードをチャットにダンプしないでください。
オブジェクトモデルを理解する。 連絡先と商談はプロパティマップを持つ別個のオブジェクトです。ステージ遷移には、商談のパイプライン（pipelines list）からのステージIDを使用する必要があり、ステージラベルではありません。

crm-cli スクリプト

scripts/crm-cli は、HubSpot CRM v3 API に対するエージェントファーストでstdlibのみのCLIです。課題の全範囲をカバーします：レコード、検索、パイプライン表示。

crm/scripts/crm-cli --help                                # トークンやネットワークは不要
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   # プレビュー
crm/scripts/crm-cli deals update-stage --id 901 --stage closedwon --yes       # 確認済み

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

運用ループ

質問の範囲を定める：これは検索（CRMに誰/何がいるか）か、それとも変更（商談を移動する）か？contacts search/contacts list または deals list でオブジェクトを特定します。
制限付きで読み取る：1件のレコードには contacts get、パイプライン表示（オプションでパイプラインとステージでフィルタ）には deals list、ステージラベルをIDに解決するには pipelines list を使用します。
回答をトリアージする：質問を証拠（連絡先詳細、商談金額/ステージ、パイプライン分布）にマッピングします。
確認を得て行動する：変更を指示する人間の指示のみ、--dry-run でプレビューし、--yes で確認します。
検証する：商談を再読み取り（deals list --stage <target>）し、ステージが移動したことを確認します。

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

連絡先レコード（/objects/contacts）：一覧表示（GET）または1件取得（GET by ID）。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：制限付き、stdlibのみのCLI（連絡先一覧/取得/検索、商談一覧/ステージ更新、パイプライン一覧；--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マーケティングサーフェスであり、このスキルがカバーするCRM APIではありません。
他のCRM（Salesforce、Pipedrive、Zoho） — それぞれ独自のAPIとツールがあります。このスキルはHubSpotをカバーします。
CRM戦略、営業プロセス設計、パイプライン方法論 — これは組織/戦略の作業であり、API操作ではありません。

HubSpot CRM 操作