エージェント運用 — 6つの基本ルール

Plan 先・調査委譲・lessons・検証・簡潔さ・自律修正。詳細は下の折りたたみと agent-workflow-orchestration.mdc。

会話の文脈管理（2026）

AI の回答の質は、渡す情報の量より、余計な情報が少ないかで決まる。下表は状況別の推奨。

ツール横断の整理・公式 BP 対応表: ルール/プラン — 3ツール横断 · 公式ドキュメント。プロンプト: プロンプト設計。

Plan の置き場所（チャット / ファイル）

3 ステップ以上は Plan をファイル化。tasks/todo.md がチーム正本。Cursor は .cursor/plans/ が下書き。

Plan — ズレたら follow-up ではなく計画からやり直す

公式 BP: 意図と違う出力が出たら、追加入力で直すより変更を revert → Plan を具体化 → 再 Buildの方が速くきれいなことが多い。

1. Checkpoint / git で安全な地点に戻す
2. Plan（チャット or .cursor/plans/）に不足コンテキスト・完了条件を追記
3. ユーザー承認後に Agent で再実行
4. 検証コマンド（完了前検証）を Plan に含める

マルチエージェント協調

開発セッションでは、1つの会話にすべてを詰め込まず、別の AI 担当（Task / Subagent）に調査・分析を委譲し、メインは実装と判断に集中する。プロダクト実装（LangGraph・SDK）の詳細は Tool Use 参考 — マルチエージェント、RAG 統合は RAG 参考 — Agentic RAG。

基本 — 開発文脈でのマルチエージェント

マルチエージェントとは、役割とコンテキストを分けた複数の AI 実行単位が協調すること。Cursor では Task ツール、Claude Code では Subagents が相当する。

1. Plan — メインがゴール・サブタスク・並列可否を書く（Plan の置き場所）
2. 調査委譲 — 広い grep・複数ディレクトリ探索は Subagent に任せ、結果だけ戻す（調査の任せ方）
3. 執筆・実装 — メインが構造化された調査結果をもとにコード・ドキュメントを書く
4. 検証 — テスト・curl・本番 HEAD など完了条件を満たす（完了前の検証）

Cursor Task — subagent_type の使い分け

並列: 独立タスクは複数 Task を同時起動（ファンアウト）。集約ロジックを Plan に先に書く。

worktree 並列 · 複数モデル比較（Cursor 2026）

出典: 公式 BP。

• Git worktree — Agent ドロップダウンから worktree を選ぶと、ファイル変更が分離された作業ツリーで実行。完了後 Apply で現在ブランチへマージ
• 複数モデル — 同一プロンプトを複数モデルに送り、結果を横並び比較。難問・エッジケースの探索向け
• 通知 — 並列実行時は完了通知を有効化（長時間タスク）

調査だけ委譲する場合は Task / Subagent。実装の並列は worktree + Plan で衝突を防ぐ。

受け渡しスキーマ（データ契約）

Subagent からメインへ戻すのは構造化結果だけ。全文ダンプ・長い grep 出力は避ける。

{
  "paths": ["src/domain/order.ts", "src/api/routes/order.ts"],
  "summary": "OrderService.create が POST /orders から呼ばれる。認可は middleware/auth.ts。"
}

• paths — 触るべきファイル（最大10件程度）
• summary — 3〜5文の要点（メインが次のアクションを決めるのに足る量）
• 必要なら blockers — 調査だけでは解決できない不明点

協調パターン

下表はパターンごとの向き不向き。

チェックリスト

1. ゴール・サブタスク・並列可否を書く
2. 各エージェントに役割・ツール・構造化出力（データ契約）を割り当てる
3. 並列/直列の境界と受け渡しを固定する
4. 失敗時フォールバックを文章化する
5. まず 2 体パイプラインで固めてから段階的に増やす
6. ハンドオフ失敗・重複作業・品質低下・トークン肥大を監視する

よくある失敗

• 汎用エージェントだらけで特化のメリットが消える
• 出力形式未標準化で次段がパースできない
• 並列を早まりで増やし観測不能になる
• 段間エラー処理がなく連鎖失敗する
• トークンコストを軽視する

履歴・記録の残し方

「誰が・何を・どの粒度で読むか」を決めると、履歴の残し方がブレない。正本の置き場所は リポジトリ — docs / 作業履歴 を参照。

下表は記録の置き場所と粒度の早見。

Git log

TDD 採用チームは [RED] / [GREEN] / [REFACTOR] プレフィックスを使うと読みやすい。

* [REVIEW] address review comment: handle null in <field>
* [REFACTOR] extract _<helper> to private method
* [GREEN] implement <usecase>
* [RED] add failing tests for <usecase>
* docs: add docs/<feature>/ design docs + ADR-NNNN
* [PLAN] refine task breakdown before implementation
* feat: <user-visible summary>  (merge commit)

docs/ (公式)

• 要件・設計・DB・技術選定・テスト計画・ログ・デプロイが揃う
• 重要な意思決定は docs/adr/ に切り出す
• 共有したい知見は z_docs から docs/ へ昇格させる

作業履歴（Obsidian 正本 · z_docs 任意）

詳細・判断フロー: リポジトリ — docs / 作業履歴

• 必要なときだけ、フェーズ別意思決定を時系列で残す
• 後から自分で振り返りたいときの補助
• 共有したい知見だけ docs/ や PR に昇格すればよい

チャット履歴

• 各フェーズの冒頭で「フェーズN: 目的」を宣言
• 長くなったら新規チャット。@Past Chats で必要分だけ引き継ぐ（4章 会話の文脈管理）
• 引き継ぎ時、後任者が PR と履歴を読めば理解できる状態にする

AIのよくある誤り

プロジェクト固有のルールとは別に、AI がよく間違える論点の早見表。該当行があればテスト・docs・rules で先回りする。

下表は論点ごとの典型ミスと対策。プロジェクト docs に境界表・丸めポリシー等を書いておくと効く。

NOTE: 言語・FW・ライブラリの最新仕様は AI の学習データより古いことが多い。公式ドキュメント・チェンジログと突き合わせる習慣をつける。

ルールは古くなります。四半期見直し・チーム導入・コスト管理をセットで運用してください。

運用の注意