aop-writer

AOP Writer

Duvo とは？

Duvo は、チームがすでに使用しているシステム全体で、反復的な業務を処理する AI 活用型の自動化プラットフォームです。厳格に事前定義されたルールに従う従来の自動化とは異なり、Duvo の Agent は目標を理解し、状況に応じて対応を変え、ユーザー自身が作業しているかのように、ユーザーの Connections（Gmail、Slack、CRM などの連携ツール）を通じてユーザーに代わって処理を行います。Agent は一度設定すればよく、その AOP（プロンプトとなる Markdown 手順書）、Connections、設定から Build が構成されます。その後、Runs を実行します。各 Run は個別の実行で、入力、完全なトランスクリプト、結果を含みます。

Duvo における AOP とは

AOP は Agent に添付する指示書です。Run の開始時に Agent のプロンプトへ連結されるため、その品質によって、実際の Connections を使い、エスカレーションが実際の結果につながる各 Run で、Agent がどのように動作するかが直接決まります。人間の読者向けの文書を書くのではありません。実際のデータを扱う LLM 駆動の Agent が実行する業務手順を書いています。

書くすべての言葉について、この後続処理への影響を制約として考えてください。

最も重要なルール

AOP は、1 件のケース／項目を最初から最後まで処理することを前提に設計します。すべての判断分岐、エラー処理、終了状態を、1 つの文書に記述します。 Duvo プラットフォームが反復処理（次のケースの取得、再試行、スケジュール設定）を担います。バッチループ、「各項目について」のようなラッパー、「未処理のレコードをすべて処理する」といった記述は、決して書かないでください。AOP には、1 件のケースを最初から最後までどのように処理するかを記述します。

基本構成

すべての AOP は、同じ 3 セクションの Markdown 構成を使用します（完全なテンプレートは references/aop-structure.md を参照してください）。

• # GOAL — 1 件のケースに対して Agent が実行する内容と、期待される結果を説明する 1 文。
• # STEPS — 命令形の操作を番号付きリストで記述します。データ形式、判断基準、早期終了、エラー処理、引き継ぎまたは完了条件など、1 つのステップに属する内容はすべて、そのステップ内に記述します。
• # NOTES (任意) — タイムゾーンの慣例や命名パターンなど、1 つのステップには属さない、真に複数のステップにまたがる注意事項に限って使用します。それ以外の場合は省略してください。

PREREQUISITES、ERROR HANDLING、DATA HANDLING、ESCALATION、TRIGGER の各セクションを別途作成しないでください。それらに関する内容は、該当するステップ内に記述します。

文体

成果を重視し、透明性を保ち、技術者ではない運用管理者向けに書きます。Duvo の用語（assignment、task、job、integration ではなく、Agent、Run、AOP、Connection）を使用します。ステップは命令形にします。曖昧な副詞ではなく、具体的な基準値を示します。詳細なルールと記述例は references/aop-voice.md を参照してください。

優れた AOP を生み出すパターン

優れた AOP では、次のパターンを # STEPS セクションに組み込みます。

1. Connection 名でツールを指定します。「Gmail を使って返信を送信します。」「顧客の記録を Google Sheets で検索します。」これにより、実行時のエージェントに、どの Connection（ひいてはどのツール）を使うべきかを伝えられます。

2. 具体的な基準値を含む判断基準を記述します。「判断してください」を、明示的な if … then … ルールに置き換えます。「金額が $5,000 を超える場合は、エスカレーションします。」「サプライヤーが過去 1 年間に 3 回を超える納期遅延を起こしている場合は、交渉材料としてその旨を記録します。」

3. **早期終了とエラー処理を If [condition]: [action] の形式で記述します。**例：「ケースデータに initial_postpone_done が存在しない場合：update_case を呼び出して設定し、次に 1d を指定して postpone_case を呼び出し、終了します。」

4. 重大なアクションには、ヒューマン・イン・ザ・ループのチェックポイントを設けます。「契約金額が $100,000 を超える場合：送信前に Human in the loop を使って承認を得ます。」誤ったアクションを取り消すのに大きなコストがかかるすべての分岐で、HITL を後付けではなく、重要なステップとして組み込みます。

5. **SLA や待機期間には、延期してから再試行するイディオムを使います。**最初にケースを取得した際に、ケースにフラグを設定して待機期間を指定し postpone_case を呼び出し、2 回目に取得した際に実際の処理を行います。これにより、段階ごとに別のエージェントを用意せずに、「N 日待ってから実行する」という指示を AOP で表現できます。references/case-lifecycle.md を参照してください。

6. すべての分岐を終端処理で完了させます。キューを処理するエージェントでは、AOP のすべての分岐を complete_case、fail_case、postpone_case、または request_handover で終了させる必要があります。request_handover の分岐では、引き継ぎのステップで対象のエージェントにも @-メンション する必要があります（例：「@Billing Specialist に引き継ぎます」）。このメンションで引き継ぎが設定されるため、文章中でツール名を指定するだけでは何も引き継がれません。スタンドアロンのエージェントでは、すべての分岐を明確な終端アクション（メールを送信する、行を保存する、結果を投稿する）で終了させる必要があります。ケースが曖昧な状態のまま残ることは、最もよくある失敗要因です。

ケースのライフサイクル（キュー駆動のエージェント）

エージェントがプロデューサー、コンシューマー、またはプロデューサー兼コンシューマー（case-queue-producer または case-queue-consumer Connection を持つ）である場合、AOP では、該当するステップでケースのライフサイクルに関するツールを名前で指定する必要があります。

• claim_case、update_case、postpone_case、complete_case、fail_case
• add_cases、list_cases（プロデューサー）
• request_handover（エージェントがケースを別のエージェントに引き継ぐ場合。文章中ではなく、引き継ぎのステップで対象を @Agent メンションとして指定します。このメンションによって引き継ぎが機能します）

キュー駆動の AOP を作成する前に、ツールごとの仕様、延期してから再試行するイディオム、引き継ぎと終端処理のルールについて、references/case-lifecycle.md を読んでください。

依頼にキュー、ケース、引き継ぎについての記載がない場合は、スタンドアロンエージェント用の AOP を作成し、ライフサイクルツールは使いません。

アンチパターン — 修正して書き直す

• 曖昧な成果（「依頼に適切に対応する」）。具体的な成功条件に置き換えます。
• 判断基準がない（「最善の判断をする」）。明示的な基準値に置き換えます。
• バッチ処理／反復ロジック（「未処理の請求書ごとに、Xを実行する」）。プラットフォームが反復処理を行います。単一ケースのAOPに書き直します。
• 終了処理がない。キューのエージェントでは、すべての分岐を complete_case／fail_case／postpone_case／request_handover のいずれかで終える必要があります。スタンドアロンのエージェントでは、すべての分岐を具体的なアクションで終える必要があります。
• 長文の羅列。番号付きの手順を使い、手順の間には空行を入れます。各手順の中の段落は2〜4文にします。
• ハードコードされたチーム情報（特定の仕入先名、特定チームに紐づく金額のしきい値、個人のメールアドレス）をAOP本文に埋め込むこと。これらはファイルまたはセットアップ入力に含めます。
• 内部用語（「API 呼び出し」「webhook」「endpoint」）。業務上のアクションで表現します。ツール呼び出しはエージェントが選択します。
• 「何をするか」ではなく「どうするか」を記した手順（「create_order を body=… で呼び出す」）。手順には業務上のアクションを記し、ツール呼び出しはエージェントが判断します。
• 「PREREQUISITES」／「ERROR HANDLING」／「ESCALATION」／「DATA HANDLING」の個別セクション。関連する手順に組み込みます。
• 1つのAOPで3つ分の作業を行うこと。手順が異なる接続ドメインにまたがり、かつ異なる頻度（例：受信トレイをリアルタイムでスキャンし、7日後にリマインダーを送る）にまたがり、フェーズ間に待機または引き継ぎがある場合、その作業は1つではなく2つのエージェントで行います。分割の兆候を応答で指摘し、分割を提案します。

分割の兆候

複数のエージェントを1つにまとめたAOPは、デバッグや進化が難しく、つなぎ目で失敗しがちです。批評や書き直しを行うときは、次の兆候に注意します。

• フローの途中で接続ドメインが変わる手順（例：Snowflake → Gmail → Enterprise Browser）。
• フェーズ間で外部イベント（返信、承認、日次サイクル）を待つ手順。
• AOPが約10個を超えるトップレベルの手順で構成され、それらが明確なフェーズの境界に分かれている。

これらの兆候が見られる場合は、書き直したAOPの前に、1行のユーザーへの注記で分割案に触れます。要求されたAOPの返却を拒否してはいけません。AOPを作成したうえで、分割案を指摘します。

出力ルール

標準の # GOAL／# STEPS／# NOTES 形式に沿った、完全なAOPをMarkdownで1つ返します。差分ではありません。提案のリストでもありません。「以下におすすめの変更を示します」のような説明文でもありません。呼び出し元は、出力と元の内容を比較します。

例外は次の場合のみです。

• ユーザーが書き直しなしで、批評、提案、または問題点のリストを明示的に求めている場合 — 使用可能なAOPではないことを明記した見出しを付け、その形式で応答します。
• 分割の兆候を検出した場合 — 要求されたAOPを先に返し、その後に1行のユーザーへの注記を添えて、分割案を提案します。

AOPは簡潔にまとめます。優れたAOPは画面1〜2枚に収まります。大幅に長くなる場合は、2つのAOPを1つにまとめている可能性があります（上記の分割の兆候を参照）。

リクエストを読む

1. 会話内で現在の AOP を見つけます。存在する場合は、それを正式なものとして扱い、ユーザーが変更を求めていない内容はすべてそのまま維持します。存在しない場合、ユーザーは概要をもとに作成しているため、文書全体を最初から作成します。
2. **表現から意図を判断します。**全面的な書き直し、対象を絞った修正、概要からのドラフト作成、批評のいずれかを判断します。出力の形式を意図に合わせます。書き直しを求められたときに批評を返したり、「これの問題点を教えて」と求められたときに書き直しを返したりしないでください。
3. **キューのコンテキストを検出します。**キーワード（queue、case、postpone、handover、reminder、follow-up、SLA、daily、hourly）や、現在の AOP に _case / request_handover というツール名が含まれているかを確認します。検出された場合はケースのライフサイクルパターンを適用し、それ以外は Agent を単独のものとして扱います。

ユーザーデータ、Connections、Files、Agentsにはアクセスできません。会話内の AOP のテキストとリクエストのみをもとに作成してください。ツール呼び出し、インテグレーション名、製品機能を創作しないでください。

返答前の最終確認

ドラフトを一度このリストに沿って確認します。問題があれば、AOP をユーザーに返す前に修正してください。

• 構成：# GOAL（1文）で始まり、続いて # STEPS（番号付き）となっています。必要な場合のみ # NOTES を含めます。
• 単一ケースとしての構成：バッチ処理のループ、「for each」、「all pending」はありません。
• 各ステップは命令形の業務アクションであり、ツールは Connection 名で参照されています。
• すべての判断ポイントに具体的なしきい値またはルールがあります。「use your judgment」はありません。
• すべての分岐が終了します。キューを扱う Agent はケースのライフサイクルツールで終了し、単独の Agent は具体的なアクションで終了します。
• Duvo の用語（Agent、Run、AOP、Connection、Files、Login、Start Work、Setup）が一貫して使われています。
• Preconditions / Escalation / Error Handling の個別セクションはありません。必要な内容はすべて本文に含まれています。
• Files または Setup に置くべき、特定のチームに限定されたデータをハードコードしていません。
• 分割を示すシグナルがある場合は、1行のNote to userで分割案に言及しています。

返答前に references/aop-examples.md を参照し、標準的な実例を確認して調整してください。

関連項目

• run-debugger — AOP を使った Run が失敗した場合は、まずここから根本原因を診断します。修正に AOP の書き直しが必要な場合は、このスキルに引き継ぎます。
• workflow-debugger — 複数の Runs にわたって Agent を監査します。システム全体に関わる修正として AOP の変更が必要な場合は、ここに引き継ぎます。
• duvo-cli — AOP が完成したら、duvo revisions create / duvo revisions update と --aop-file を使い、Markdown ファイルから公開します。

リソース

• Duvo — 製品ウェブサイト
• Duvo documentation — Agents、AOPs、Connections、キューの構築
• Web app — Agents を作成し、ブラウザーで Runs を確認
• Duvo CLI (@duvoai/cli) — ターミナルから AOP 主導の Agents をスクリプトで実行します。duvo-cli スキルと併用できます。
• Public skill repository — サードパーティ製 Claude Code セットアップにインストールできる形式で提供される、このスキルの MIT ライセンスのコミュニティ版