operate.txtの紹介：SaaS製品をナビゲートするAIエージェントのためのYAML仕様

開発者が、AIエージェントがWebアプリケーションとどのように対話すべきかを文書化する仕様であるoperate.txtを作成しました。このファイルは、SaaS製品をナビゲートするためにClaudeのコンピューター使用機能を利用する際に遭遇した問題、つまりAIエージェントがローディング画面が機能障害を示しているかどうかを繰り返し質問した問題に対処します。

問題と解決策

Claude Code + コンピューター使用機能を利用して、初回ユーザーとしてBrandyBee（SaaS製品）をナビゲートする際、開発者はClaudeが苦戦した特定の課題を特定しました：

• 90〜120秒かかるブランド分析中、28%完了時点でClaudeが「これはローディング状態ですか、それとも何か問題がありますか？」と質問
• 確認UIなしで有料API呼び出しをトリガーする「承認」ボタン
• 国を選択した後にのみ表示される言語ドロップダウン
• 2〜5分かかり、停止しているように見える非同期プロセス

毎回、応答は「いいえ、それは正常です、ただ待ってください」でした。これにより、クローラー向けのrobots.txtや検索エンジン向けのsitemap.xmlに相当するが、特に製品を操作するAIエージェント向けのoperate.txtの作成につながりました。

operate.txt仕様

operate.txtファイルは、yourdomain.com/operate.txtでホストされるYAMLファイルで、以下を文書化します：

• 各画面が何であるか
• ローディング状態がどのように見え、どれくらいの時間がかかるか
• どのアクションが不可逆的か
• 一般的なタスクの段階的なパス
• エージェントが絶対にすべきでないこと

最も有用なセクションはasync_actionsで、「このプロセスは90〜120秒かかり、更新しないでください、離れないでください、これが通過する段階です」などの詳細をエージェントに伝えます。

作成プロセスと例

開発者は、自社のSaaS、eコマーステンプレート、SaaSダッシュボードテンプレートを含む実際の例とともに仕様をオープンソース化しました：https://github.com/serdem1/operate.txt。

作成プロセスは、Claudeに製品をナビゲートさせ、躊躇する箇所を観察し、次にClaudeにoperate.txtファイルを起草させることを含みます。開発者はClaudeが間違えた部分を修正し、AIがギャップを見つけ、人間がそれを埋めるフィードバックループを作成します。