3行でいうと

  • 「人がいない場所」で動かす道は、大きく4つです。画面なしで1回呼ぶ agent -p（ヘッドレス）、GitHub Actionsなどのシェルが使えるCIの中でCLIを動かす方法、クラウドで動くCloud Agents（Automations、APIを含む）、PRを自動で見るBugbotです。
  • ヘッドレスでは、何を許可するかを自分で決めます。公式は、--force を付けないと変更は「提案」だけで、付けると確認なしでファイルを書き換える、と書いています。CIには、プロンプトでの禁止だけに頼らず、permissions の許可と禁止を書き、git操作やPRコメントはCIの別のステップに任せる「制限つきの自律」が推奨されています。
  • 認証は、ブラウザのログイン（agent login）と、ダッシュボードで作るAPIキー（環境変数 CURSOR_API_KEY）の2つです。CIにはAPIキーを使い、リポジトリのSecretsに入れます。ただし、両方があるときの優先順位は、読んだ範囲では書かれていませんでした。
  • Cloud AgentsとBugbotは使った分の課金です。Cloud Agentsは、端末のコマンドを承認なしで自動実行するので、公式は外向きの通信の制限とドラフトPRのレビューを勧めています。Cloud Agents APIは公開ベータで、変わることがあります。

この記事は、実際に使って確かめた記録ではありません。運営者はCursorを入れていますが、使い心地はこの記事には書いていません。この記事は、2026年10月24日にCursorの公式ドキュメント、ヘルプ、更新履歴を読んでまとめたものです。コマンド名、オプション名、設定のキー、メニュー名は、公式に書かれているとおりに写したもので、動作確認はしていません。公式の文章は要約の形で取得したため、引用は最小限にして、ほとんどを言い換えています。バージョン、価格、上限は、更新で変わることがあります。

先に結論

前提：用語をそろえる

どの道を選ぶか（公式の説明の整理）

道 動く場所 きっかけ 認証 公式のどこか
agent -p 自分の機械かCIの機械 自分、スクリプト、CI ログインか CURSOR_API_KEY Headless / CI
CI（GitHub Actionsなど） CIのランナー ワークフローの設定 CURSOR_API_KEY（Secrets） CLI in GitHub Actions
Cloud Agents Cursorのクラウドの仮想マシン Web、Slack、@cursor、API、& アカウント、APIキー Cloud Agents、API
Automations 同上 時刻、GitHub、Slack、Webhookなど 実行する主体（自分かサービスアカウント） Automations
Bugbot Cursor側 PRの更新、PRへのコメント リポジトリの接続（接続する人は、読んだ範囲では未確認） Bugbot
SDK 手元かクラウド 自分のコードから CURSOR_API_KEY TypeScript SDK

道1：agent -p（コマンド1回で完結）

基本の形と公式の例

公式のHeadless / CIのページによると、-p（--print）を付けると画面なしで動き、答えがコンソールに出ます。既定の出力は text で、最後の答えだけが出ます。自動化では、agent login ではなく環境変数 CURSOR_API_KEY を使います（次の「認証」）。公式の例のうち、レビューをファイルに書かせるスクリプトは次のとおりです（公式は simple-code-review.sh として載せています。絵文字は省きました）。

#!/bin/bash
# simple-code-review.sh - Basic code review script

echo "Starting code review..."

# Review recent changes
agent -p --force --output-format text \
  "Review the recent code changes and provide feedback on:
  - Code quality and readability
  - Potential bugs or issues
  - Security considerations
  - Best practices compliance

  Provide specific suggestions for improvement and write to review.txt"

if [ $? -eq 0 ]; then
  echo "Code review completed successfully"
else
  echo "Code review failed"
  exit 1
fi

この例は --force を付けているので、エージェントが review.txt を直接書きます。画像の説明を取り出す例は、agent -p --output-format json "Analyze this image ...: $IMAGE_PATH" | jq -r '.result' という形です。画像や動画は、ファイルのパスをプロンプトに書くと、エージェントが道具で読む、と公式は説明しています。

主なオプション（公式の「CLI Parameters」の整理）

オプション 公式の説明の要点
-p, --print 結果をコンソールに出す。書き込みとシェルを含むすべての道具が使える、とある
--output-format <format> text（既定）、json、stream-json。--print のときだけ
--stream-partial-output 部分的な出力を差分で流す。stream-json のときだけ
-f, --force（別名 --yolo） 明示的に拒否されていない限り、コマンドを許可する
--trust 確認なしでワークスペースを信頼する。表には「headless modeのみ」とある
--approve-mcps すべてのMCPサーバーを自動で承認する
--sandbox <enabled\|disabled> サンドボックスのモードを指定する
--workspace <path> 使うワークスペースのフォルダ
--model <model>、--list-models モデルの指定、使えるモデルの一覧
--mode <plan\|ask>、--plan 計画モード、読み取り専用のAskモード。指定しなければAgentモード
--resume [chatId]、--continue チャットの再開、直前のセッションの続き
--api-key <key> APIキー。環境変数 CURSOR_API_KEY でも渡せる
-w, --worktree [name] 新しいGitのワークツリー（~/.cursor/worktrees/<リポジトリ名>/<名前>）で動かす。名前を省くと自動で付く
--worktree-base <branch> 新しいワークツリーの土台にするブランチやref。既定は現在のHEAD
--skip-worktree-setup .cursor/worktrees.json に書いたセットアップのスクリプトを飛ばす

サブコマンドには、login、logout、status（別名 whoami）、about、models、mcp、update、ls、resume、workerなどがあります。ページに、ベータや実験的という表記は見当たりませんでした（sandbox と acp は「hidden」）。なお、更新履歴（v2026.06.22）には、Auto-reviewを --auto-review で有効にできるとありますが、この旗は「CLI Parameters」の表には見つかりませんでした。使う前に agent --help で確かめてください。

出力の形：json と stream-json

公式の「Output Format」によると、json は、完了したときに1つのJSONを出します（途中の差分や道具のイベントは含まれない）。公式の成功時の例は次のとおりです。

{"type":"result","subtype":"success","is_error":false,"duration_ms":1234,
 "duration_api_ms":1234,"result":"<full assistant text>",
 "session_id":"<uuid>","request_id":"<optional>"}

stream-json は、1行1つのJSON（NDJSON）です。イベントは system（最初に1回。apiKeySource が env、flag、login のどれかを示す）、user、assistant、tool_call（started と completed）、result です。--stream-partial-output を付けると、メッセージが複数の assistant イベントに分かれ、一部は重複です。公式の見分け方は、timestamp_ms があって model_call_id がないものが流れてくる差分（使う）、両方あるものは道具の呼び出しの前の吐き出し（重複、読み飛ばす）、どちらもないものはターンの終わりの吐き出し（重複、読み飛ばす）です。

公式の注意（ページ末尾の「Notes」と、各形式の説明）は、実務で効きます。

終了コードの種類、レート制限、タイムアウト、費用の目安は、読んだ範囲のどのページにも書かれていませんでした。

ヘッドレスまわりの更新履歴（Cursor CLIの更新履歴、10月24日確認）
  • 2026年1月：信頼されていないワークスペースでの非対話の実行は、--trust か --force を付けないと失敗する、とあります。
  • 2026年2月：--worktree（-w）が追加され、-p が止まる不具合が直されました。--yolo は、信頼、MCP、コマンドの確認を自動で承認する、とあります。
  • v2026.06.09：管理者が、ヘッドレスのモードを組織全体で無効にできるようになった、とあります。設定の場所は、読んだ範囲では見つかりませんでした。
  • v2026.07.20：--trust が、対話のセッションでも使えるようになりました（以前はヘッドレス専用。「CLI Parameters」の表の書き方は、この変更の前のものかもしれません。僕らの推測です）。
  • v2026.08.11：ヘッドレスは、委任したサブエージェントの終了を待ってから終わるようになりました。ローカルのシェル実行で、管理者のコマンド拒否リストが守られるようになった、ともあります。
  • v2026.08.26：agent persist で、切断したあともエージェントを動かし続けられるようになりました。詳しい使い方は読んでいません。

認証：人のログインと、CI用のAPIキー

公式の「CLI Authentication」によると、方法は2つです。

方法 やり方（公式の記載） 向く場面
ブラウザのログイン（公式が推奨） agent login。ブラウザを開かずURLだけ出すなら NO_OPEN_BROWSER=1 agent login。資格情報はログイン後にローカルに保存される、とある（保存先は書かれていない） 自分のパソコン
APIキー ダッシュボードの API Keys でユーザーのAPIキーを作り、環境変数 CURSOR_API_KEY（公式が推奨）か --api-key で渡す 自動化、スクリプト、CI

公式の例は、export CURSOR_API_KEY=your_api_key_here のあとに agent "implement user authentication" を動かす形です。agent status で、認証の状態、アカウント、接続先を見られます。「Not authenticated」と出たら、agent login をやり直すか、キーの設定を確かめる、とあります。

読んだ範囲で書かれていないことを、分けておきます。

agent -p --output-format stream-json "say hi" | jq -r 'select(.type=="system") | .apiKeySource'

env、flag、login のどれかが出る、と公式の出力形式のページにあります。 - CI専用の手順。 認証のページは、APIキーが自動化とCI向けだと書くだけです。 - 資格情報の保存先。 更新履歴（v2026.06.29）に、AGENT_CLI_CREDENTIAL_STORE=file で、macOSのキーチェーンがないサンドボックス向けに、持ち主だけが読めるファイルに保存できる、とあります。 - プロキシ。 設定のページに、HTTP_PROXY、HTTPS_PROXY、NODE_USE_ENV_PROXY=1、NODE_EXTRA_CA_CERTS が挙がっています。

APIキーの種類は、道で変わります。Cloud Agents APIでは、ユーザーのAPIキーか、チーム設定のサービスアカウントのAPIキーを使います。SDKでも両方が使え、チームのAdminのAPIキーには「まだ対応していない」とあります。僕らの見立てですが、CIには、持ち主が人に依存しないキーのほうが、担当者が変わったとき困りません。ただし、CLIでサービスアカウントのキーが使えるかは、読んだ範囲のCLIのページには書かれていませんでした。

権限：誰も答えられない場所で、何を許すか

前のガイド（02）の承認の仕組みは、画面に人がいる前提でした。ヘッドレスでは、次のものが「事前の答え」になります。

決めること 手段 公式の記載
変更を書き込んでよいか --force 付けないと変更は提案だけ。付けると確認なしで直接書き換える（Headless / CI）
何を許し、何を禁じるか permissions.allow と permissions.deny 拒否が許可より優先される（CLI Permissions）
フォルダを信頼するか --trust 確認なしで信頼する
MCPを使ってよいか --approve-mcps すべてのMCPを自動で承認する
コマンドを箱に入れるか --sandbox enabled サンドボックスのモードを指定する

許可と禁止の書き方。 設定ファイルは、全体が ~/.cursor/cli-config.json、プロジェクトが <プロジェクト>/.cursor/cli.json です。プロジェクト側に書けるのは権限だけだと、設定のページにあります。形式は、Shell(コマンドの先頭)、Read(パスかglob)、Write(パスかglob)、WebFetch(ドメイン)、Mcp(サーバー:ツール) です。Shell は最初の語で照合し、Shell(curl:*) のように、コマンドと引数をコロンで分ける書き方もあります。公式が警告しているのは、WebFetch(*)（どのドメインでも取得してよい）と Mcp(*:*)（すべてのMCPツールを許可）です。公式の例では、Read(.env*)、Write(**/*.key) のように、秘密のファイルが拒否の側に入っています（拒否に入れるよう勧める文は、読んだ範囲では見つかりませんでした）。

重要な食い違い。 ヘッドレスで、--force なしに書き込めるかについて、公式のページの書きぶりがそろっていません。Headless / CIは「付けないと提案だけ」と書き、CLI Parametersの表は、-p が書き込みとシェルを含むすべての道具を使えると書き、CLIのCapabilitiesのページは、非対話モードで「フルの書き込み権限がある」という趣旨を書いています。CLI Permissionsのページは、printモードは書き込みとシェルの道具を使え、permissions.allow、permissions.deny、--force が確認なしで動く範囲を決める、という書き方です。つまり4つ目の記述は、許可と禁止、そして --force が実際の線引きだという側を支持しています。ただ、どれが現在の動きかは、読んだ範囲では決められませんでした。僕らの見立てですが、CIに載せる前に、小さなテスト用のリポジトリで、--force なしに書き込まれないか、拒否のルールが効くかを確かめておくのが安全です。

道2：CIで動かす（GitHub Actions）

公式の「CLI in GitHub Actions」は、CLIを入れてから、APIキーを環境変数で渡して agent -p を動かす2段の形を書いています。公式の例は次のとおりです（動作確認はしていません）。

- name: Install Cursor CLI
  run: |
    curl https://cursor.com/install -fsS | bash
    echo "$HOME/.cursor/bin" >> $GITHUB_PATH
- name: Run Cursor Agent
  env:
    CURSOR_API_KEY: ${{ secrets.CURSOR_API_KEY }}
  run: |
    agent -p "Your prompt here" --model gpt-5

Windowsのランナーは、PowerShellで irm 'https://cursor.com/install?win32=true' | iex を使います。GitHub以外のCIでも、シェルの実行、APIキーを環境変数で渡せること、CursorのAPIへ届くインターネット、の3つがあれば動く、と書かれています。

PATHに注意。 上の例は $HOME/.cursor/bin をPATHに足していますが、インストールのページ（前のガイド01）は ~/.local/bin を足すよう書いています。どちらが現在の実際のインストール先かは、読んだ範囲では分かりません。コマンドが見つからないときは、インストール後に場所を確かめて、PATHを合わせてください（僕らの見立てです）。

鍵の登録。 公式は、GitHub CLIでの登録を例にしています（画面なら Settings、Secrets and variables、Actions）。組織で共有するなら、--org と --visibility all を付けます。

gh secret set CURSOR_API_KEY --repo OWNER/REPO --body "$CURSOR_API_KEY"

2つの自律の度合い。 Full autonomy（完全な自律）は、gitの操作、GitHub CLI、PRの操作まで任せる形で、設定は簡単だが、より多くの信頼が要る、とあります。Restricted autonomy（制限つきの自律）は、エージェントが分析とファイルの編集だけを行い、コミット、プッシュ、PRコメントはCIの別のステップが行う形で、本番に推奨されています。その最初のステップのプロンプトは、公式では「ブランチを作らない、コミットしない、プッシュしない、PRにコメントしない。作業フォルダのファイルだけ変える」という趣旨です。公式は、プロンプトだけでなくCLIの水準でも制限するよう勧め、次の設定を例にしています。

{
  "permissions": {
    "allow": [
      "Read(**/*.md)",
      "Write(docs/**/*)",
      "Shell(grep)",
      "Shell(find)"
    ],
    "deny": ["Shell(git)", "Shell(gh)", "Write(.env*)", "Write(package.json)"]
  }
}

この例では、Markdownを読み、docs/ の下だけに書き、grep と find を走らせられます。git、gh、.env、package.json への書き込みは禁止です。

1本のワークフローにまとめる（僕らの整理。動作確認はしていません）

公式の「制限つきの自律」は、3つのステップです。エージェントに編集だけさせるステップ、git checkout -B "docs/${{ github.head_ref }}"、git add -A、git commit、git push origin ... を行う決まったステップ、gh pr comment でコメントするステップです（公式に載るのはステップの断片で、on:、permissions:、actions/checkout を含む1本のファイルは載っていませんでした）。それに、僕らが外側を足した形が次です。on:、permissions:、チェックアウト、fetch-depth は僕らの仮置きで、GITHUB_TOKEN の権限やフォークからのPRでSecretsが使えるかは、GitHub側の公式を読んでいないので、ここでは扱いません。

name: docs-update
on:
  pull_request:
permissions:
  contents: write
  pull-requests: write
jobs:
  docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - name: Install Cursor CLI
        run: |
          curl https://cursor.com/install -fsS | bash
          echo "$HOME/.cursor/bin" >> $GITHUB_PATH
      - name: Generate docs updates (restricted)
        env:
          CURSOR_API_KEY: ${{ secrets.CURSOR_API_KEY }}
        run: |
          agent -p --force "IMPORTANT: Do NOT create branches, commit, push, or post PR comments. Only modify files in the working directory. Update docs for the changes in this PR."
      - name: Publish docs branch (deterministic)
        run: |
          git checkout -B "docs/${{ github.head_ref }}"
          git add -A
          git commit -m "docs: update for PR"
          git push origin "docs/${{ github.head_ref }}"
      - name: Post PR comment (deterministic)
        env:
          GH_TOKEN: ${{ github.token }}
        run: gh pr comment ${{ github.event.pull_request.number }} --body "Docs updated"

読み方の要点は3つです。(1) 編集のステップに --force を付けるのは、書き込みを cli.json の許可で docs/ の下に絞っているからです（僕らの整理）。(2) 上の deny と allow は、リポジトリの .cursor/cli.json に入れておく形になります（プロジェクト側に書けるのは権限だけ、と設定のページにあります）。(3) 変更がないときに git commit が失敗する点などは、公式の例には出てこないので、実際のリポジトリで確かめてください。

道3：Cloud Agents（留守番）

始め方、料金、ブランチ

公式の「Cloud Agents」によると、隔離されたクラウドの仮想マシンで動き、リポジトリのクローン、依存関係、シークレットを持ちます。入口は、iOSアプリ、cursor.com/agents、デスクトップの入力欄で「Cloud」を選ぶ、Slackの @cursor、GitHubとBitbucketのPRやIssueへの @cursor コメント、Linear、API、そして（CLIの概要のページによると）CLIのメッセージの先頭の & です。リポジトリを使うには、アカウントの管理者が先にソース管理（GitHub、GitLab、Bitbucket Cloud、Azure DevOps）を接続している必要があります。

使うには有料プランが必要で、The X Subscriptionなら Premium 以上、Teams、Enterprise、または旧プランの有料プランです。Free と Plus には含まれません（確認日2026年10月24日の表示）。最初に使うとき、支出の上限を決めるよう求められ、使った分は、選んだモデルの料金でプランの使用量から引かれます。ヘルプによると、「Move to Cloud」は、会話の履歴と文脈は渡すが、コミットしていない変更は渡しません。

エージェントは別のブランチで作業します。APIでは、workOnCurrentBranch が false（初期値）なら新しい cursor/... ブランチに押し上げます。セキュリティのページによると、押し上げてドラフトPRを作るところまでで、人がレビューするまでマージされません。ヘルプによると、コミットの作者は、依頼した人ではなくエージェントです。

環境、シークレット、ネットワーク

環境は、エージェント主導の設定（公式の推奨）、スナップショット、.cursor/environment.json のDockerfileで作ります。公式の例は次のとおりです。

{
  "build": {
    "dockerfile": "Dockerfile",
    "context": ".."
  },
  "install": "pnpm install && ./custom_script.sh"
}

install は、ビルドを作るときにバックグラウンドで動き、プロジェクトのルートから実行されます。何度動いても同じ結果になるように書くこと、長く動かすプロセスは入れないこと、と書かれています。環境は、個人の保存環境、チームの保存環境、リポジトリの .cursor/environment.json（単一のリポジトリの実行だけ）の順で選ばれます。

安全（公式の警告）

セキュリティのページに、Cloud Agentsは端末のコマンドを承認なしで自動実行し、前景のエージェントより自律的だと書かれています。リスクとして、エージェントが読む内容に仕込まれた指示（プロンプトインジェクション）で、コードが外部に送られる恐れが挙げられ、対策として、外向きの通信の制限、Runtime Secrets（値が記録や出力から取り除かれ、モデルに渡らない）、.cursorignore、ドラフトPRのレビュー、フックとBugbotでの確認が勧められています。Privacy Modeが必須で、旧Privacy Modeには対応しません。スナップショットは、30日使われなければ削除され、要求しても消せない、とあります。設定のページによると、管理者が「チームの追従メッセージ」を有効にすると（Disabled、Service accounts only、All の3段階）、他の人が作ったエージェントに指示を送れますが、公式は、他の人のシークレットで動くものを指示することになるので、共有のSSH鍵と同じ慎重さで、と書いています。

Cloud Agents API（公開ベータ）

公式のAPIの一覧に「Beta」とあり、エンドポイントのページにも、一般提供の前に変わることがある、と書かれています。ベースのURLは https://api.cursor.com で、認証はBasicかBearer（両方同じ）です。レート制限は、APIの一覧で「標準のレート制限」とされています。同じページに、エンドポイントが別の値を書かない限りの既定（毎分20リクエスト）という一般的な記述がありましたが、Cloud Agents APIにも当てはまるかは書かれていませんでした。公式の例は次のとおりです。

curl --request GET \
  --url 'https://api.cursor.com/v1/agents?limit=20' \
  -u YOUR_API_KEY:
操作 メソッドとパス 要点
作って最初の実行を始める POST /v1/agents prompt.text（必須）、model、repos[].url、repos[].startingRef、repos[].prUrl、autoCreatePR、mode（agent か plan）など
追加の実行 POST /v1/agents/{id}/runs 実行中なら409（agent_busy）
実行の状態 GET /v1/agents/{id}/runs/{runId} CREATING、RUNNING、FINISHED、ERROR、CANCELLED、EXPIRED。終わると result（最後の返答の文）、ブランチを押し上げたときは git.branches[]（repoUrl、branch、prUrl）が入る
実行の流れ GET .../runs/{runId}/stream SSE。Last-Event-ID で再開
取り消す POST .../runs/{runId}/cancel 取り消すと CANCELLED になり、再開できない（続けるなら同じエージェントに新しい実行を作る）。終わった実行の取り消しは409（run_not_cancellable）
削除 DELETE /v1/agents/{id} 完全に消える

作成の上限として、リポジトリ500件、MCPサーバー50件、画像5枚（1枚15MB）などが書かれています。envVars は、アカウントで有効でないと黙って無視される「ベータ」の項目です。成功時のHTTPの状態コードは、読んだ範囲では書かれていませんでした。このページは、末尾の約6千6百字を読めていません。

Webhookのページによると、エージェントを作るときにWebhookのURLを渡すと、ERROR か FINISHED になったとき、statusChange がPOSTで届きます。署名は、ヘッダー X-Webhook-Signature に sha256=<hex> で入り、生の本文をHMAC-SHA256にかけた値と比べます。ほかに、ヘッダー X-Webhook-ID（配信ごとの識別子）、X-Webhook-Event（今は statusChange だけ）、ユーザーエージェント Cursor-Agent-Webhook/1.0 が送られ、本文には event、timestamp、id（エージェントのID）、status、source（リポジトリとref）、target（エージェントのURL、ブランチ名、PRのURL）、任意の summary が入ります（一部は取れたときだけ）。エラーが返ると再送されうるので、2xxをなるべく早く返すよう公式は書いていますが、タイムアウトの長さと再送の回数は書かれていませんでした。署名の確認は、次のように書けます。公式の例の写しではなく、この記事で書いた形で、この記事では動作を確かめていません（公式のページは、生の本文を、解析する前に使うよう書いています。定数時間の比較は僕らの足したものです）。

const crypto = require("crypto");

function isValidSignature(secret, rawBody, signatureHeader) {
  const digest = crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
  const expected = Buffer.from("sha256=" + digest);
  const received = Buffer.from(signatureHeader || "");
  return expected.length === received.length && crypto.timingSafeEqual(expected, received);
}

ただし、APIの一覧には、Webhookは「v1では近日対応、v0では対応」とあり、このページがどちらの版の話かは、確かめられませんでした。

Automations（きっかけで起動する）

公式の「Automations」は、Cloud Agentsを、スケジュール（cron式も可）や、GitHub、GitLab、Bitbucket Cloud、Slack、Webhook、Linear、Sentry、PagerDutyの出来事で起動します。作るのは、エージェントウィンドウ、cursor.com/automations、/automate、Marketplaceのテンプレートです。公式の注意は次のとおりです。

プランの条件と、回数や時間の上限の数字は、ページには見つかりませんでした（前のガイド04のとおり、プランの表では、Premium以上に含まれ、Plusには含まれません）。

最初の1本の作り方。 公式のページに書かれている手順は、(1) きっかけを選ぶ（定期的なスケジュール、PRのイベントなど。複数でもよく、どれかが起きれば動く）、(2) エージェントへの指示を書く、(3) 使う道具を選ぶ（Slackへの送信、PRへのコメント、MCPサーバーなど。省いてもよい）、(4) リポジトリの扱いを選ぶ（なし、1つ、複数。GitHubなどのきっかけには必須）、(5) 保存して有効にする、の5つです。公式は、指示は「何を調べ、何を変えるか」を具体的に書き、使える道具を名指しし、判断の基準、PRを開く・コメントする品質の基準、出力の形も書くよう勧めています。公式は、ひな形の名前として find-bugs、find-vulnerabilities、fix-slack-bugs、daily-digest、triage-github-workflow-failures、autofix-pr-review-comments、investigate-sentry-issues を挙げていますが、見本の指示文は載せていませんでした。

僕らの見立てです。最初の1本は、書き込みもPRも作らない、読むだけの定期の要約（daily-digest のようなもの）から始めるのが安全です。「Run as」は、チームでは共有の画面から選べ、「Service account」を選べるのは管理者だけです。フォークからのPRできっかけが動かない問題には、公式の回避策があります（同じリポジトリにブランチを押し上げて、そこからPRを開く）。

Bugbot（PRを自動で見る）

公式の「Bugbot」は、PRを調べて、バグやセキュリティの問題にコメントします。対応は、Origin、GitHub、GitLab、Bitbucket、Azure DevOps（Servicesのみ）です。

公式の .cursor/config/bugbot.yaml の例から、選べる値の部分を抜き出すと次のとおりです。公式のページには、キーの階層が triggers、review、prSummary、autofix の下に分かれた1つの例があり、書いてよい項目はすべて任意で、ファイルは64KBより大きいと無視される、とあります（階層は公式の説明にそろえました。値の選択肢は公式の例のコメントのとおりです）。足りない項目や正しくない項目は、その項目だけが無視され、次の優先順位の設定に戻ります。

version: 1
triggers:
  frequency: everyPush   # everyPush | oncePerPr
review:
  effort: default        # low | default | high | smart
prSummary:
  mode: comment          # disabled | description | comment
autofix:
  mode: disabled         # disabled | newBranch | existingBranch

autofix.mode は、ダッシュボードのAutofixのモードを下げることはできますが、上げることはできません（公式の記載）。

.cursor/BUGBOT.md の置き方は、公式のページに、プロジェクトのルートの .cursor/BUGBOT.md は常に含まれ、backend/.cursor/BUGBOT.md のような入れ子は、そのフォルダのファイルを見るときに含まれる、という配置図があります。中身の見本は、読んだ範囲では載っていませんでした。次は僕らが作った雛形で、公式の例ではありません。

# レビューの方針
- 外部入力を扱う関数には、入力の検証があるかを見る。
- データベースのマイグレーションは、元に戻せるかを見る。
- スタイルの指摘は不要（フォーマッタが直す）。

PRを指定してレビューを起動するAPI（POST /bugbot/review）は、Enterpriseだけです。/review-bugbot はCLIでも使える、とBugbotのページにありますが、CLIのスラッシュコマンドの一覧には載っていませんでした。

SDK：自分のコードから呼ぶ

公式の「TypeScript SDK」は、npm install @cursor/sdk（Node.js 22.13以上）で入り、Agent.create() に local か cloud を渡して選びます。認証は CURSOR_API_KEY です。ローカルの道具の呼び出しは、承認なしで動くのが既定で、止めるにはフックか local.sandboxOptions を使う、とあります。Python SDKは読んでいません。

最小の自動化レシピ（ここからは僕らの整理です）

公式の部品を並べ替えたもので、動かして確かめてはいません。

レシピA：読むだけの質問をCIで。 --force を付けず、cli.json で書き込みを絞ります。公式の制限つきの例の deny（Shell(git)、Shell(gh)、Write(.env*)）に、書き込み全体を拒否する Write(**) を足すのは、僕らの広げ方です。この書き方が期待どおりに効くかは、確かめられていません。

- name: Ask the agent (read only)
  env:
    CURSOR_API_KEY: ${{ secrets.CURSOR_API_KEY }}
  run: agent -p --output-format text "Summarize the risks in the last commit"

.cursor/cli.json の中身は、この記事で公式の部品を並べた例です（公式の写しではなく、この記事では動作を確かめていません）。

{
  "permissions": {
    "deny": ["Write(**)", "Shell(git)", "Shell(gh)", "Read(.env*)"]
  }
}

レシピB：編集だけ任せ、公開はCIが行う。 公式の制限つきの自律です。エージェントのステップに「コミットも、プッシュも、コメントもしない」と書き、cli.json で Shell(git) と Shell(gh) を拒否し、続くステップで普通の git と gh を使います。ステップの流れは、上の「1本のワークフローにまとめる」にあります。複数のジョブを並べるときは、-w（--worktree）で作業の場所を分けられます。ただ、並列で使うときの注意は、公式のパラメータの表には書かれていませんでした（僕らの見立てです）。

レシピC：失敗を取りこぼさない。 json か stream-json を使うなら、result の有無ではなく、終了コードで成否を決めます（公式の失敗時の説明にそろえた形）。シェルでは、たとえば次のように書けます（この記事の例で、動作は確かめていません）。

agent -p --output-format json "Summarize the risks in the last commit" > out.json
rc=$?
if [ $rc -ne 0 ]; then
  echo "agent failed with exit code $rc" >&2
  exit $rc
fi
jq -r '.result' out.json

終了コードの種類が公式のどのページにも書かれていないので、ここでは「0かそれ以外か」だけで分けています。CIの既定のシェルが途中の失敗で止まる設定かどうかは、CI側の仕様なので、このように明示すると安全です（僕らの見立てです）。

したいこと まず検討する道（僕らの見立て）
手元で1回質問する agent -p（--force なし）
PRごとに決まった確認をする CIで agent -p。制限つきの自律
留守に長い作業を任せる Cloud Agents。通信の制限とドラフトPRのレビューを先に決める
出来事をきっかけに動かす Automations
PRの一般的なバグを見つける Bugbot

最初の10分でやること

公式に書かれている範囲を、僕らが順に並べました。

  1. ダッシュボードの API Keys で、ユーザーのAPIキーを作り、すぐ控える。
  2. 手元で agent status を確かめる。 認証の状態と接続先が出ます。
  3. 読むだけの質問を、agent -p --output-format json で1つ投げる。 --force は付けず、result と終了コードを見ます。stream-json に替えて、最初の system イベントの apiKeySource も見ておくと、どの認証が使われたか分かります。
  4. 小さなテスト用のリポジトリで、--force なしの書き込みと、deny の効き方を確かめる。 上の「重要な食い違い」を、自分の環境で決着させます。
  5. gh secret set CURSOR_API_KEY ... で、Secretsに登録する。
  6. 公式のワークフローの例に cli.json の許可と禁止を足して、テスト用のリポジトリで動かす。
  7. Cloud AgentsやBugbotを試す前に、支出の上限を確かめる。

気をつけること

出典