cargo-project

Cargo プロジェクト — リポジトリ内で宣言する Cargo ワークスペース

このスキルを使って TypeScript で Cargo ワークスペースを定義します（@cargo-ai/cdk の define* ビルダーを使用）。さらに、cargo-ai project deploy で稼働中のインフラストラクチャと同期します。これは命令型の各機能スキルに対する宣言型のアプローチです。リソースごとに CLI コマンドを実行する代わりに、グラフ全体を一度記述して繰り返しデプロイし、ワークスペース内に保持するデプロイ状態を使います。コミット済みの cargo.state.json で指定されるこの状態が、コードと Cargo が作成したリソースを結び付けます。プロジェクトとは、cargo.json（{ "resources": "infra" }）を含むフォルダーです。すべての cargo-ai project コマンドは、実行場所より上にある最寄りのプロジェクトを探し、見つからなければ停止します。

「プロジェクト」と「ワークスペース」は別物です。混同しないでください。
ワークスペースはサインインする Cargo テナントです。モデル、コネクター、エージェント、メールボックス、クレジットが含まれます。また、login --workspace-name で選択され、whoami が報告する対象です。プロジェクトはリソースを宣言してワークスペースにデプロイする cargo.json を含むフォルダーです。project init がひな形を作成し、cargo.state.json を置く場所であり、すべてのコマンドが最寄りの cargo.json まで上にたどって見つける対象です。1 つのリポジトリに複数のプロジェクトを置くことができ、それぞれに cargo.json が 1 つあります。1 つのプロジェクトが一度にデプロイできるワークスペースは 1 つです。状態のワークスペースが選択中のものと一致しない場合、ワークスペースガードがデプロイを拒否します。同じプロジェクトを開発用と本番用のワークスペースにデプロイするには、それぞれ異なるデプロイ状態を使います。これを「プロジェクト」と呼び、プロジェクトディレクトリに my-workspace という名前を付けないでください。

ブートストラップ

すでにサインイン済みで（cargo-ai whoami がワークスペースを返す場合）、次のセクションに進んでください。

npm install -g @cargo-ai/cli            # no global install? prefix every command with `npx @cargo-ai/cli`
cargo-ai login --email [email protected]  # emailed code, no browser; creates the account on first use
                                        # alternatives: --oauth (browser) · --token <api-token> (CI)
cargo-ai whoami                         # confirm the active workspace before any write
cargo-ai project --help                     # `unknown command` = CLI too old; reinstall @cargo-ai/cli@latest

プロジェクト固有の追加事項は 2 つあります。インポートする define* ビルダーを使うには、プロジェクトに依存関係として @cargo-ai/cdk が必要です（cargo-ai project init はこれを含む package.json をひな形として作成します。その後、npm install を実行してください）。また、cargo-ai project ドメインは CLI 自体に含まれています。

すべてのコマンドは JSON を標準出力に出力し、失敗時は {"errorMessage": "..."} を返して 0 以外で終了します。実行やバッチを作成する処理はすべて非同期です。--wait-until-finished を渡すか、対応する get を使って状態を確認してください。スキル一式をインストールすると、../cargo/references/prerequisites.md に CLI のバージョン固定、トークンのスコープ、管理者限定の機能が追加されます。

1) このスキルの対象

• 作成：define* ビルダーを使って Cargo のあらゆるリソースを定義し、ハンドルを返します。ハンドルを互いに渡してリソースを接続します（依存関係グラフが変数グラフになります）。
• デプロイ：グラフに対して plan（オフライン差分）→ deploy（作成／更新して状態を書き込む）→ destroy（削除）を実行します。ドリフトへの対応（refresh）、既存リソースの取り込み（import）、復旧（rollback）も行います。
• 型付け：ワークスペースの実際のインテグレーションスキーマに対して設定の型を検査します（cargo-ai project types）。

プロジェクトはすべてのリソース種別に対応するため、命令型のすべての機能スキル（cargo-connection、cargo-storage、cargo-ai、cargo-orchestration、cargo-content、cargo-hosting など）と領域が重なります。どのスキルを使うかが、最初に決めることです。

2) プロジェクトか CLI か？ — ルーティングの判断

宣言型（このスキル）と命令型（機能スキル）。

ユーザーがリソースを成果物として管理している場合は、プロジェクトを使用します。

• 「ワークスペース全体をセットアップ／構築／ブートストラップする（コードとして／テンプレートから）。」
• 「再現可能にする／バージョン管理する／git に入れる／環境間（dev → prod）で繰り返し実行できるようにする。」
• 「これらのコネクター、モデル、エージェントをまとめてデプロイする」（依存関係で接続された複数リソースのグラフ）。
• 再実行や差分比較が必要で、定義を失うと困るもの。

ユーザーが単発の操作や探索を行っている場合は、該当する機能スキル（命令型の cargo-ai <domain>）を使用します。

• 「コネクターを1つ作成する」「このモデルに列を追加する」「コネクターを一覧表示する」「このワークフローを実行する」「ストレージにクエリする」「このエージェントのメモリを読み取る。」
• コードに残す必要のない、読み取り、アドホックなクエリ、単一の変更操作。

判断に迷ったら、結果をコミットして再デプロイできるようにすべきかを確認してください。そうであれば → プロジェクトです。簡単な操作や読み取りであれば → 機能スキルです（適切なドメインを選ぶには、cargo router を参照してください）。

3) ライフサイクル

cargo-ai project init <dir>     scaffold the Cargo template: cargo.json + cargo.state.json, resources in infra/
        │
cargo-ai project types          generate per-workspace types for typed config (optional)
        │
   (author define* files)   importing a .ts file IS registration — no list to keep
        │
cargo-ai project plan           compile the graph, diff against the deploy state (creates nothing)
        │
cargo-ai project deploy         create/update resources in dependency order, write state
        │
cargo-ai project destroy        tear down resources recorded in state

project plan は変更されるリソースを示しますが、プレイの内容は示しません。 3つを超えるノードを持つ definePlay／defineTool グラフでは、プランと併せてノードグラフの Mermaid フローチャートを提示してください。ルーティング、フォールバック、スケジュール実行のたびに課金されるノードは、レビュー担当者が承認する内容です。最初のデプロイ後はデプロイ済みのリリースから、作成中はノード配列から生成してください。 ../cargo-orchestration/references/node-diagram.md。

関連するサブコマンド：cargo-ai project check（ツリーを検証します。状態へのアクセスや API 呼び出しはありません。plan のうち CI／エディターで使う機能です） · cargo-ai project info（ここにあるものを表示します。宣言されたすべてのリソース、宣言元のファイル、デプロイ済みかどうか） · cargo-ai project refresh（読み取り専用のドリフトレポート） · deploy --refresh（コードを適用し、範囲外で行われた編集を上書きします） · deploy --prune（コードから削除されたリソースを削除します） · cargo-ai project import <id> <uuid>（既存の稼働中リソースを状態に紐付けます） · cargo-ai project pull（稼働中のワークスペースから define* ソースを生成して取り込みます） · cargo-ai project rollback（デプロイ前の状態スナップショットを復元します） · cargo-ai project state（デプロイ状態を確認し、参照先を変更します）。

plan と info は異なる問いに答えます。 plan が答えるのは デプロイで何が行われるか です。単位は変更で、CI でゲートできるよう、変更がある場合はゼロ以外の終了コードを返します。info が答えるのは ここに何があるか です。単位はリソースで、エラー終了することはありません。check は差分表示を除いた plan です。状態を必要としないため、エディターやコミット前フックで実行します。サブコマンドを指定せずに cargo-ai project を実行すると、ヘルプが表示されます。

4) ドキュメントの階層

• レベル 1 — SKILL.md（このファイル）：判断モデル、ライフサイクル、重要なルール、ルーティング。
• レベル 2 — ガイド： guides/authoring-resources.md、 guides/deploy-and-state.md、 guides/typed-config.md。
• レベル 2.5 — レシピ：recipes/*.md — 実行計画として従う、手順ごとのプレイブック。
• リファレンス — references/resources.md（ビルダーの完全なカタログ）、references/commands.md（すべての cargo-ai project サブコマンドとフラグ）、 references/troubleshooting.md、および references/examples/full-workspace.md。

5) 読み取り動作 — タスクに合ったドキュメントを選んで読みます

タスクの内容…	最初に読むもの	内容
define* ファイルの作成、リソースの接続、secret()／env()、defineWorkflow 本体（ツール／プレイのロジック）	guides/authoring-resources.md	ビルダーの一覧、ハンドル／参照モデル、シークレット、ワークフロー本体のコンパイル方法。
plan／deploy／destroy、状態ファイル、ドリフト、既存リソースの取り込み、CI	guides/deploy-and-state.md	デプロイのライフサイクル、cargo.state.json の仕様、ドリフト／インポート／ロールバック、非同期ビルド。
型付き設定、cargo-ai project types、tsconfig の接続、ワークフロー本体での uses.<key>.<action> コネクター呼び出し	guides/typed-config.md	project types が生成するものと、プロジェクトへの接続方法。
特定のビルダーのフィールド／仕様／出力	references/resources.md	すべてのビルダー → 仕様フィールド → 受け取る参照 → 出力。
正確なコマンドフラグ	references/commands.md	すべての cargo-ai project サブコマンドとそのフラグ。
デプロイエラー／落とし穴	references/troubleshooting.md	既知の失敗要因と対処法。
作成前に把握しておきたい既知の GTM 成果、または設定後に提案すべき内容	references/cookbooks.md	クックブックの一覧。ステージ順に、実際のプロジェクト例を含む gtm-skills、それぞれがサポートする応用方法、次に提案すべきものを掲載しています。

クックブック — よくある成果をゼロから作る前に、メニューを確認してください

getcargohq/gtm-skills には、単発のスキルに加えて、 クックブックがあります。これは、成果物が継続的に生成されるデプロイ済みパイプラインと同じ役割を担う、 実際のプロジェクトリソースを含むスキルです（TAM の構築、アカウントスコアリング、通話の記録、 インバウンドの選別、CRM のエンリッチメント、停滞案件への働きかけなど）。各フォルダーはそれぞれ独立しており、 独自のモデル、コネクター、フォルダーを備えています。共有の基盤も、依存関係のグラフもありません。

メニューはローカルにあります：references/cookbooks.md。 よくある GTM の成果を ゼロから作成する前に確認し、クックブックをセットアップした後にももう一度確認してください。 メニューにはステージ順にクックブックが並んでおり、次に提案するものは、その順序でまだセットアップされていない最初の クックブックです。gtm-skills の catalog.json から生成されるため、内容が食い違うことはありません。

クックブックは記入用のテンプレートではなく、実例です。 各クックブックの SKILL.md には、変更可能なもの、 動作を続けるために維持しなければならない条件、どちらの場合でも確認が必要な事項が記載されており、 独自の手順も含まれています。project add は、その手順におけるコピーの工程です。

cargo-ai project add cookbook/tam-building               # inside a project
cargo-ai project init my-project --cookbook tam-building # no project yet: both at once

これにより、リソースは infra/tam-building/ に、手順は .claude/skills/tam-building/ に書き込まれ、 上書きされるファイルはスキップされます。その後、スキルの Adapt セクションから始めてください。 冒頭の手順は、GitHub でフォルダーを見つけ、まだ配置していない人向けに書かれています。 最初から順に進めると、2 つ目のプロジェクトを作成し、フォルダーを再度コピーすることになります。

コピー後に残る作業は、あなただけができることです。すでに宣言されている内容と照合し、コピーしたファイルを プロジェクトの実際の構成に合わせてその場で調整します（スキルの説明文から再生成しないでください。 安全性は TypeScript によって確保されています）。計画を立てて停止し、承認されたらデプロイし、 Done when の条件を確認します。

作業の途中で、このセッションにスキルがない場合は、npx skills add getcargohq/gtm-skills/<slug> で手順だけを取得でき、.agents/skills/<slug>/SKILL.md を直接読めます。 再読み込みは不要です。インストールせずに読むには、npx skills use getcargohq/gtm-skills@<slug> を実行すると 内容が表示されます。どちらもプロジェクトリソースは取得しないため、リソースには引き続き project add を使ってください。

振り分けのルール：単発か、継続運用か。 今日のリストが欲しいユーザーには cargo-gtm（または gtm-skills の単発スキル build-tam-list）が適しています。 リストを継続的に生成するパイプラインが欲しいユーザーには tam-building が適しています。 同じ言葉がどちらも指すことがあります（「TAM を構築する」）。そのため、成果物を継続的に生成する意図があるかを確認してください。 合致するクックブックがあれば、インストールして手順に従います。合致するものがなければ、以下のレシピを使って作成します。

空でないディレクトリで cargo-ai project init --force を実行しないでください。 プロジェクトの package.json が置き換えられ、調整済みのコードが元に戻ります。一方、cargo.state.json は残るため、 次の plan では、稼働中のワークスペースと、誰も作成していないコードが比較されます。代わりに、スキルフォルダーを兄弟ディレクトリとしてコピーしてください。

注意：例は型チェックに通りますが、実際のワークスペースへのデプロイ検証はまだ済んでおらず、すべて to-be-approved です。各スキルの Done when を受け入れテストとして扱い、デプロイ前に必ず cargo-ai project plan を確認してください。

レシピ — 該当するものがあれば、手順に沿って進めてください

レシピ	使用する場面…
recipes/scaffold-a-project.md	新しいプロジェクトをゼロから立ち上げるとき（init → 型 → plan → deploy）。
recipes/add-connector-and-model.md	データソースと、そこからデータを取得するモデルを追加し、ハンドルで接続するとき。
recipes/build-an-agent.md	モデル、ツール、エージェントを組み合わせ（uses 経由で接続）、デプロイするとき。
recipes/migrate-existing-workspace.md	project import を使って、すでに稼働しているワークスペースをプロジェクトに取り込むとき。
recipes/deploy-from-ci.md	CI から非対話的にデプロイするとき（トークン認証とコミット済みの状態）。

6) 重要なルール

• cargo.state.json をコミットしてください。現在は状態そのものではなく、ポインターです。 デプロイ状態はワークスペースに保存され、リポジトリにコミットされるのは {"stateUuid": "8f2c…"} だけです。project init は状態を作成してそのポインターを書き込むため、スキャフォールドのコミットに含まれます。必ずコミットしてください。UUID がないと、新しいチェックアウトから状態を見つけられず、デプロイ時に代わりの状態がひそかに作成されることもありません（その場合、以前の状態が追跡しているものすべてが孤立してしまいます）。状態に記録されるのは UUID、ハッシュ、出力のみで、シークレット値は記録されません。デプロイ済みのプレイ、エージェント、アラート（これらにはスラッグがありません）を特定するためのハンドルは、今もこれだけです。リンクを紛失した場合は project state bind <uuid>、またはリソースごとに cargo-ai project import で復元してください。作業ファイルは Git で無視してください（project init がこの設定をスキャフォールドします）。

  .cargo-ai/
  cargo.state.lock
  cargo.state.bak.json
  cargo.state.cache.json
  cargo.state.audit.jsonl
  

  プロジェクトごとに状態は 1 つ、ワークスペースあたりの有効な状態は最大 10 個です。

  cargo-ai project state list            # every state here, and which one this project is on
  cargo-ai project state create          # create one for this project, write the pointer
  cargo-ai project state bind <uuid>     # repoint at an existing one
  

  状態がワークスペースに移される前にスキャフォールドされたプロジェクトでは、リソースマップが cargo.state.json にインラインで格納されており、そのファイルが残っている限り、そのファイルを使ってデプロイが続けられます。裏で移行されることはありません。移行には state create を実行します。マップが新しい状態に移り、ファイルはポインターになり、それをコミットします。チームに知らせずに移行しないでください。新しいポインターをプルする前にチームメンバーがデプロイすると、すでに存在しない状態からデプロイすることになるためです。（状態を削除するには、cargo-ai project state remove <uuid> を実行すると、追跡対象の有効なリソースには触れずに状態が削除されます。cargo.state.json がその状態を参照している場合は --force を指定してください。）
• 値を渡す方法は 3 つありますが、互いに置き換えられるものではありません。
  • secret("ENV_VAR") — デプロイ時に自分の環境から読み取られ、コンテンツハッシュと状態から除外されます。デプロイ前に環境変数をエクスポートしてください。未設定の場合、未解決の ${ENV_VAR} プレースホルダーとしてデプロイが失敗します。
  • env("ENV_VAR") — ロード時に自分の環境から読み取られ、その値が仕様に含まれるため、コンテンツハッシュにも反映されます。したがって、値を変更するとドリフトとして表示されます。追跡したい非シークレットの設定に使用してください。
  • workspaceEnv("NAME") — ワークスペースの環境変数カタログのエントリーを指すポインターです。ローカルでは何も読み取られず、エラーになることもありません。値はサーバー側に保持され、使用するたびに再読み込みされるため、ワークスペースで値をローテーションしても、再デプロイなしでリソースに反映されます。cargo-ai workspaceManagement envVar でカタログを管理してください（../cargo-workspace-management/SKILL.md を参照）。 secret() と workspaceEnv() は、secret 型のスキーマ位置でのみ受け付けられます。cargo-ai project types は、該当する位置でユニオン型を出力します。リソース自身の env ブロックでは env() または secret() を使用し、ポインターは拒否されます。ワーカー、アプリ、エージェント、スクリプトは、すでにワークスペースのカタログ全体を継承しているためです。ここでポインターを使っても、すでに読み取り可能な変数を再指定するだけです。
• ローテーションした secret() を反映するには、通常のデプロイだけでは不十分です。 値をコンテンツハッシュに含めないことで、ローテーションがドリフトとして検出されるのを防ぎます。同時に、ハッシュに変更がないためリソースが再適用されず、deploy では新しい値が反映されません。deploy --refresh を使うか、そのリソースに別の変更を加えてください。workspaceEnv() にはこの手順が不要で、それが主な利点のひとつです。
• .uuid ではなく、ハンドルで接続してください。 define* のハンドルを直接渡す（connector: hubspot、uses: [enrich]）か、コードで定義していないリソースには xxRef("uuid") を使います（connectorRef、modelRef、folderRef、toolRef、agentRef など）。参照に呼び出しごとのオプションが必要な場合は、{ ref, …options } でラップします（例：uses: [{ ref: contacts, readOnly: true }]`）。
• ワークスペースのインテグレーションを変更した後は、cargo-ai project types を実行してください。これにより .cargo-ai/ が再生成され、defineConnector／defineModel の設定（およびワークフロー本体の uses 経由で呼び出されるコネクターアクション）が実際のスキーマに対して型チェックされます。型チェックはあくまで付加的なもので、必須条件ではありません。なくてもデプロイは機能します。
• プロジェクトとは、cargo.json があるフォルダーです（@cargo-ai/cdk ≥ 1.0.112）。 このファイルで、.ts ファイルの読み込み元となるフォルダー（{ "resources": "infra" }）と、実行データの保存先（省略時は cargo.json と同階層の outputs/）を指定できます。すべてのコマンドは実行場所からリポジトリのルートまで上方向にたどり、最も近い cargo.json を探すため、どのサブディレクトリからでも実行できます。複数のプロジェクトがあるリポジトリでは、それぞれに cargo.json が必要で、最も近いものが選ばれます。cargo.json がない場合、コマンドは停止します。infra/ フォルダーや package.json からの推測は行わず、プロジェクトのルートに追加するための行を表示します。

  echo '{ "resources": "infra" }' > cargo.json
  

  cargo.state.json は cargo.json と同階層に置きます。infra/ の中には置きません。infra/cargo.state.json が残っていると、実行するすべてのコマンドが停止し、実行すべき mv コマンドが表示されます（状態ファイルが2つある場合も停止します。プロジェクトの状態を指す方を残してください）。--dir <path> は引き続き使用できます。これは検索開始位置を指定します。リソースはルートではなく infra/ に置きます。ローダーは resources で指定されたフォルダー以下の .ts ファイルをすべてインポートするためです。リポジトリのルートには scripts/ もあり、そのファイルはインポート時に実行されます。
• CI では --yes を指定してください。 deploy と destroy は確認を求めます。非対話型の実行では --yes を渡す必要があります。
• 有料ノードを含む definePlay／defineTool のグラフは、広く展開する前にサンプル実行してください。 デプロイは実行ではありませんが、デプロイ済みのプレイを実行する最初の処理は、通常、セグメント全体に対する一括処理です。また、スケジュールされたプレイでは、実行のたびにすべてのノードの料金が再度発生します。すべてに登録する（またはスケジュールを有効にする）前に、デプロイ済みのワークフローを 10～20 件のレコードで実行してください。たとえば cargo-ai orchestration batch create --workflow-uuid <uuid> --data '{"kind":"filter","modelUuid":"…","filter":…,"limit":15}' を使います。または batch create --file ./plays/x.ts --data '…' を使うと、デプロイせずにモジュールをテスト実行できます。その後、レコード数とクレジットの見積もりを提示して、全件登録についてユーザーの承認を得てください。プロバイダーのプレイブック（../cargo-gtm/provider-playbooks/<slug>.md、特に Recurring use セクション）と、../cargo-gtm/references/cost-discipline.md のゲートを確認してください。
• 有料ノードを呼び出すアクションを持つ defineAlert は、条件に該当するたびに料金が再度発生します。 アラートの actions は実際の実行として処理されるため、間隔の短い schedule に対して threshold の設定が不適切だと、毎回条件に該当して料金が発生する可能性があります。デプロイ前に cargo-ai observability alert preview でしきい値を調整し、ファンアウトする処理よりも、安価な通知アクション（投稿するエージェントやコネクター通知など）を優先してください。アクションがクレジット制のプロバイダーを呼び出す場合は、上記と同じコスト確認を行ってください。スコープ／しきい値と発火の動作については、../cargo-observability/SKILL.md を参照してください。
• defineMailbox は毎月課金され、defineDomain は DNS ゾーンを書き換えます。 メールボックスは存在する限り、毎月 100～125 クレジット（共有／プライベートは 100、google は 125）かかります（最新の数値は cargo-ai mailboxManagement pricing get で確認できます）。そのため、プランに + create mailbox:… とある場合、これは一度限りではなく継続的な料金であり、ユーザーの承認が必要です。domain、username、type は作成時にのみ設定できます。これらを変更するには、削除して再作成する必要があります。つまり、受信箱が新規作成され、45 日間のウォームアップの最初に戻ります。メールボックスを作成する前に、デプロイ処理はドメインの refreshStatus を最大 5 分間ポーリングして、ドメインが active になるのを待ちます。新しいメールボックスは待ちません。プロバイダーが認証情報を発行するまで pending のままです。defineDomain の dnsRecords は、パッチではなくゾーン全体を表します。これを宣言すると、購入時にレジストラーが設定したものも含め、現在のすべてのレコードが置き換えられます。省略した場合はゾーンに変更を加えません。ゾーンを置き換えずに設定する場合は、redirectUrl、dmarcEmail、dmarcPolicy が追加方式で使える正式な手段です。すべてのレコードを管理する場合に限り、dnsRecords を使用してください。UI で購入したドメインまたはメールボックスには adopt: true を指定してください。ウォームアップ、抑制、送信については、../cargo-mailbox-management/SKILL.md を参照してください。
• プロジェクト管理のリソースは、明確なラベルを付けたフォルダーに振り分けてください。 各ビルダーに folder: を設定し、プロジェクトが所有するすべてのリソースを、UI を使う人が「コード管理 — 手動で編集しない」と分かる名前の専用フォルダーにまとめます（UI で手動編集すると、次の plan でドリフトとして検出されます）。フォルダーは種類ごとに分かれるため、種類ごとにフォルダーを作成しつつ、短く認識しやすい共通の接頭辞を付けてください。推奨：🔒 Project（例：🔒 Project Models、🔒 Project Agents）。フォルダーツリーでは長いラベルが省略されるため、名前は短くしてください。ロックの絵文字が「触らないでください」という目印になります。詳しくは guides/authoring-resources.md を参照してください。

ヘルプ

• ライブフラグの一覧については、cargo-ai project --help および cargo-ai project <subcommand> --help を参照してください。
• ドキュメントに記載されたコマンド／フラグ／応答が実際の動作と一致しない場合は、cargo-ai workspaceManagement report create で報告してください（../cargo-workspace-management/SKILL.md を参照）。