panbergco/agent-cli-writer

Agent CLIライター

エージェントはマニュアルではなく、コマンドを求めます。ドキュメントにのみ存在するルールは、エージェントがたまたまそれを読んだときにだけ守られます。この背景にある測定結果は references/evidence.md にあります。

ルール： ツールのすべてのルールは、ツール自体が、それが適用される瞬間に示します。ツールが表示するもの、拒否するもの、簡単にするもの、それこそがマニュアルです。

エージェントがツールで行うこと

• まずコマンドを求めます。確信がない場合にのみマニュアルを開きますが、確信があっても間違っていることがよくあります。
• 既に立てた計画を確認するために読みます。構文を探し、ルールは探しません。
• セッション間ですべてを忘れ、そのたびにツールを再び学習します。
• 複数の呼び出しを同時に送信します。
• ツールが出力したすべての文字に対して、後続のリクエストごとに再び支払います。
• 安価に待つことができません。ポーリングまたはスリープし、各ポーリングは有料リクエストになります。
• 目の前にある答えに書かれていることを、以前にドキュメントで言われたことよりも確実に実行します。

方法

12のチェック項目。それぞれに検証方法があります。tool は架空のコマンドです。

1. 使用時点で教える。 コマンドへの応答が、今取った経路のコストを示し、より良い経路を指名します。

   $ tool machine new
   created m-41 (stops by itself in 60 min)
   note: work started by hand in this machine keeps no run record.
         for a job you need to follow:  tool job start --from <dir> -- <cmd>
   

   検証：既知の誤用があるすべての動詞は、その出力自体の中でそれを伝えます。
2. 拒否は教訓である。 何が拒否されたか、その理由、そして呼び出し元の引数を埋めた正確な次のコマンドを伝えます。すべての問題を一度の応答で伝えます。ゼロ以外の終了コードで終わる場合、必ずメッセージを出力します。使用法エラーの場合は、そのサブコマンドの正しい形式のみを出力します。

   tool: refused: `job wait j-7` would hold this turn for up to 40 min.
         next:  tool job show j-7          (how it stands now)
                tool job start … --notify  (be told when it ends)
   

   検証：メッセージなしで終了する経路がないこと。すべての拒否に next: が含まれていること。
3. マニュアルをツールに内蔵する。 tool rules が動作ルール全体を、バージョンコードで終わる形式で表示します。エージェントが手動で操作する動詞は、現在のコード（TOOL_RULES=<code>）を設定していない非対話型の呼び出し元を、1行で拒否します。マシンインターフェースである動詞は制限なく受け付けます。コードはルールが変更されると変わります。 検証：コマンド名だけを与えられた新しいエージェントが、作成・変更・削除を行う最初の呼び出しの前に、コンテキスト内にルールを持っていること。
4. 正しい経路を簡単な経路にする。 「Xを推奨」と書く前に、Xが仕事全体を行うようにします。つまり、エージェントが実際に持つ入力を受け付け、すぐに返答し、記録を保持します。エージェントは、ブロックする、履歴を捨てる、または入力を取れない推奨コマンドを迂回します。好みではなく結果を述べます。「Yは記録を保持しない」は、「Xを推奨」が効かないところで効果を発揮します。 検証：ドキュメント内の「推奨」ごとに、回避された経路が推奨経路に欠けているものを特定し、そのギャップを埋めます。
5. 「現在の状況とその理由」に答える単一のコマンド。 tool status が数行で表示するもの：自分に属するもの、実行中のもの、最後の処理がどのように終了したかとその理由、次に何をすべきか。エージェントがツールのストレージやログを直接読み取る場合、それはステータスに事実が欠けていることを意味します。 検証：実際のトランスクリプトでそのような読み取りをカウントします。最もよくある3つの質問がステータスに含まれているべきです。
6. 長時間の処理：開始、返却、通知。 約1分を超える場合：start は即座にハンドルを返します。show <handle> は、ワーカーが消えた後や呼び出し元が死んだ後でも、タイムライン、終了コード、最終行を提供します。終了は結果と理由を付けて呼び出し元に通知されます。メッセージは、エージェントが今すぐ行動できる新しい情報を運ぶ場合にのみ適格です。「継続してください」という定期的なメッセージはありません。 検証：デフォルトで60秒を超えてブロックするものがないこと。すべてのジョブに記録と、結果、理由、次のステップを含む終了通知があること。
7. 出力を最小限に。 デフォルトの出力は1画面に収まるようにします。約40行または2,000文字。それ以上は、パスが表示されるファイルか、--full の背後に出力します。バナーや進捗アニメーションはなし。セッション中は一度だけの指示。出力がカットされた場合は、その旨と残りがどこにあるかを示します。 検証：実際の1週間の各コマンドが返す文字数を測定し、上位3つの合計に予算を割り当てます。
8. 2つの読み手：人間とプログラム。 端末にはテキスト。パイプ、または --json の場合：JSON Linesのみ、安定したフィールド名、最後に1つのサマリー。終了コードが結果を示します：0は完了、拒否、誤った使用法、タイムアウト、未実行は別のコード。診断情報は標準エラー出力に。 検証：tool <verb> | cat がパースできること。--help がすべての終了コードをリストすること。
9. 繰り返しても安全、すぐに安全。 コマンドを2回実行しても、2回実行されないか、既に実行済みであることを伝えます。1つのエージェントからの2つの同時呼び出しが互いの書き込みを失わないこと：ロックするか、文章で拒否します。破壊的な動詞は明示的なフラグが必要で、--dry-run を提供します。 検証：すべての書き込み動詞を同時に2回実行するテスト。
10. 制限を設け、記録を残す。 デフォルトの時間制限。ツールが作成するものは自動的に期限切れになります。list は残骸を表示します。cleanup はこの呼び出し元が作成したものを削除します。1つのことを行うコストは1コマンド。すべてのアクションは誰が、いつ、ツールのビルドとともに記録されます。tool version がそれを示します。 検証：呼び出し元を実行中に強制終了します。無制限に実行されるものはなく、記録に何が起こったかが示されていること。
11. 一つのものに一つの名前。 コマンド、その出力、エラー、ドキュメントで同じ名詞を使用。一つのアクションには名詞間で一つの動詞。未知のフラグや余分な引数は拒否され、無視されることはありません。 検証：ツールが出力する名詞をリストします。各概念に正確に一つの名詞があること。
12. 機密情報は外部に漏らさない。 コマンドラインに決して表示されず、エコーされず、記録にも残りません。ファイル、標準入力、または環境変数から取得し、出力ではマスクします。

ツールのマニュアルを書く

マニュアルは説明します。ツールは強制します。拘束力のあるものはマニュアルだけに存在してはなりません。

• 説明： ツールが何をするか、いつロードするかを、タスクが使う言葉で、動詞を明示して記述します。
• 順序： 最初に拘束力のあるルールを、それぞれの結果とともに。次に、目標とコマンドの短い表。次に、失敗とその対処法。
• サイズ： 最大150行、各行100文字以内。エージェントは長い行がカットされたファイルを表示し、すべての広いテーブル行の末尾を失います。
• テーブル： テーブルセル内に拘束力のあるものを入れないこと。

新しいエージェントで証明する

ツールやそのマニュアルを見たことがなく、実際のタスクとコマンド名を与えられた新しいセッション：

1. すべての呼び出し、その出力、終了コードを記録します。
2. カウント：ヘルプ参照、失敗した呼び出し、失敗した呼び出しの再試行、ポーリング、ストレージやログの直接読み取り、返された文字数。
3. ゼロより大きいすべてのカウントは、エージェントではなくツールの欠陥です。メッセージまたは経路を修正し、別の新しいセッションで再実行します。
4. マニュアルを読み込んだ状態でもう一度実行します。何も悪化してはならず、マニュアルがツールと矛盾してはなりません。

新しいエージェントが、ヘルプ参照なし、推測して脱出する必要のない失敗した呼び出しなし、ポーリングなし、ストレージの直接読み取りなしでタスクを完了したら完了です。

失敗モード

マニュアルのみのルール（ツールがそれを示さない） · 無言の失敗（ゼロ以外の終了コード、メッセージなし） · 理由だけで次の手順なし（理由とコマンドがない） · 全ヘルプダンプ · 推奨だが劣る（推奨経路に他の経路が持つ機能が欠けている） · ステータスギャップ（エージェントがストレージを読む） · ブロッカー（コマンドがターンを保持する） · ナグ（新しい情報のない定期的なメッセージ） · 確認してくる通知（何かが起こったことではなく、内容を言わない） · テキストの壁 · 無言のカット · 書き込みロスト（同時に2回の呼び出しで、1つの結果） · 二つの名前 · 残骸（何も期限切れにならない）。