メモの自動実行で、見ていなくても作業を進める
たまったメモを、1 件ずつ見張らなくても片付けられるようにするための型です。しばらく動かしてみて役に立った進めかたで、唯一の方法ではありません。 画面や状態の細かい説明は、すべて メモを自動で実行する にあります。このページでは何を書き、どう設定するかを説明し、それ以外はそちらにリンクします。
| あなたがすること | エージェントがすること |
|---|---|
| 詳しい手順はリポジトリに置き、常設の指示は短く書いて、そちらを指す | セッションの開始時に指示を読み、指された手順に沿って進める |
| 作業項目ごとに 1 つのメモを、範囲と範囲外を添えて書く | 実行待ちのメモを順に、「1 セッションに渡すメモの数」の件数ずつ取って実行する |
| 大きな作業の残りを Issue に書き、続きのメモを積める回数に上限をつける | 1 つの部分だけを進め、残りを記録して終わる |
| 実行履歴を読み、セッションが追加したメモを承認し、止まった実行を終える | セッションが待つものがなくなると実行を終え、セッションを停止する |
自動実行を選ぶとき
Section titled “自動実行を選ぶとき”| こんなとき | 使うもの |
|---|---|
| 同じ指示で 1 件ずつ片付けたい作業がたまっていく | メモの自動実行 |
| 決まった時刻に同じプロンプトを実行したい | スケジュール |
| 見ている 1 つの作業を、いくつかに分けて進めたい | 子セッション |
| チャットでいくつものセッションを動かし、途中で自分が決めたい | フリート・オペレーター |
自動実行に向くのは、1 回の実行で終わる大きさで、途中であなたの答えがいらないほど明確な作業です。ほとんどの項目で人の判断が必要なら、待つ場所が変わるだけです。
- 短い指示を書き(次の節)、「自動で実行する」をオフのまま設定を保存します。保存しても何も始まりません
- 内容に自信のあるメモを 1、2 件追加します
- 「今すぐ実行」を 1 回押し、セッションと結果を読みます
- 指示を直します。大きく変えたときは、もう 1 回動かします
- 「自動で実行する」をオンにします
先に次の項目を決めておきます(項目)。
| 項目 | 目安 |
|---|---|
| 費用の上限(USD) | 数字を決めます。0 は上限なしで、実行がおかしくなっても、ほかに歯止めがありません(予算) |
| 1 セッションに渡すメモの数 | 1 にします。1 回の実行が作業項目 1 つ、レビューするプルリクエスト 1 つになります。2 以上だと 1 回の実行が複数のメモを取り、このページが前提にする分離が崩れます |
| 同時に動かすセッション数 | 1 か 2 から始めます。1 つのカテゴリで最大 6 つ、すべての自動実行のカテゴリの合計で最大 4 つまでです |
| 1 日の実行回数 | 見込みより少し多めにします。暴走を抑えます |
| 実行するタイミング | 離席中やホストが空いている時間だけ動かしたいときは「時間帯」にします |
| 承認なしで実行が追加できる続きの数 | パートに分ける作業では 4 のまま、どの実行にも見えないままメモを追加させたくないカテゴリでは 0(続き) |
| 自分で起動したセッションのメモは、承認なしで受け付ける | セッションが追加したメモをいくつか読むまではオフのままにします(承認) |
セッションが追加したメモは承認を待ちます。実行が承認なしで追加できるのは、受け取ったメモと同じ作業項目の続きだけで、カテゴリの数までです(続き)。承認のカードに並ぶメモは、次のセッションへの指示になるので、そのつもりで読んでください(承認する)。
誰も見ていない前提で、常設の指示を書く
Section titled “誰も見ていない前提で、常設の指示を書く”指示は短く、手順はリポジトリに置きます。 リポジトリにあるスキルや指示ファイルは、版が管理され、レビューされ、共有されます。指示には、どれに従うかだけを書きます。
メモごとに <手順を書いたスキルまたはファイル> に従うこと。このリポジトリの中だけで作業し、1 つのメモの作業項目だけを進めること。変更はプルリクエストにすること。<マージしてよいかをここに書く>最後の返答の前に、自分で始めたウォッチと子セッションを止めること。最後の返答は、「Done:」「Partial:」「Deferred:」「Too large:」のどれかで始まる要約とし、人が判断すべきことを 1 行で添えること。セッションは、開始するときに指示を読みます。指示やファイルを直しても、すでに動いている実行は変わりません。次の実行から新しい内容を読みます。
そこにいない読み手に向けて、手順を書きます。
- 質問で終わらせません。 「続けてよいか教えてください」は、間に合うように読まれることがありません。実行は「あなたの対応待ち」のまま枠を持ち続けます。自分で決めるか、理由を書いて止まります
- 人が決めることは、プルリクエストか Issue に書き、要約でもそう伝えます。停止したセッションのチャットは、誰も見に行きません
- 飛ばす条件を書きます。 Issue が閉じている、すでに直っている、まだ決まっていない判断を待っている、などです。飛ばしたときは
Deferred:で始まる要約で終わります。それは良い結果です - 最後の返答の前に片付けます。 自分で始めたウォッチとタイマー、子セッションを止めます。待つものがなくなって、初めて実行は終わります(実行が終わるまで)
- してはいけないことを書きます。 安全に使う のとおりです。指示にパスワードやトークンは書きません
メモ 1 つが作業項目 1 つです。メモは何をするかを示すだけで、指示の範囲を広げることはできません(セッションに渡されるもの)。
<項目の名前、または Issue へのリンク>範囲: <変えるもの>範囲外: <触らないもの。ほかのどの項目が受け持つか>依存: <項目、または「なし」>- 範囲と範囲外を書きます。 端のない項目は膨らみます。外すものを書いておくと、1 回の実行が 1 つのプルリクエストに収まります
- 依存の行を、決まった形で本文に書きます。
依存: …のように書くと、読む人も次のセッションも気づけます。順序が大事なときは、メモにも「先に終わるべきメモ」を設定します(メモを別のメモの後に実行する)。行は人のためで、キューが従うのは待つ設定のほうです - 作業項目は、本文を写さずリンクします。 セッションが Issue を自分で読みます(作業項目を追加する)
- 決めてから積みます。 常設の指示で、判断が要る項目は飛ばすよう(
Deferred:)セッションに伝えておくと、人のいない実行はそうします。伝えていないと、答える人がいません。先に Issue へ、選んだ案を書いたコメントを残し、メモには「Issue の最新のコメントで決めたとおりに実装する」と書きます - メモは短くします。 項目の詳細は、人も読める Issue に置きます
順序と同時実行
Section titled “順序と同時実行”- キューの順が優先順位です。 実行は、実行待ちのいちばん古いメモから取ります。先にやりたい項目を上に置きます
- 同じファイルを触る項目は、同時に動かしません。 同じファイルを触る 2 つの実行は、プルリクエストがぶつかります。そのカテゴリの「同時に動かすセッション数」を 1 にするか、一方のメモに他方を待たせます
- ほかのメモを待つメモは、枠を使いません。 キューが待たせるだけで、後ろのメモは先に動きます。待つ先のメモがうまく終わり、その実行のプルリクエストがすべてマージされると動き出します
- ウォッチを待つセッションは、実行を開いたまま枠を持ち続けます。 レビューやビルドを長く待つ実行は、そのあいだずっと「同時に動かすセッション数」の 1 つを使います。順序が分かっているなら、待つセッションよりも、メモに待たせる設定のほうを選びます
1 回の実行に収まらない作業は、キューを通して部分に分けて進めます。
- 1 回の実行で 1 つの部分だけを進めます。 どの部分かは、メモに書きます
- どの部分も、それだけでメイン ブランチをリリースできる状態にします。 新しい動作には到達できないようにするか、今の既定の裏に置きます。つなぎ込みの途中の画面はマージしません。単独でリリースできない部分は大きすぎるので、切り方を変えます
- 終わる前に、残りを Issue に書きます。 Issue のチェックリストで足ります。キューは、開始済みのメモを自動ではもう一度動かさないので、残りは Issue に残します。例外は、今はできない作業として実行がメモを差し戻したときで、そのメモは後で新しい実行として動きます(実行がメモを差し戻す)
- 続きの部分は、メモに上限を書いたうえで、実行に積ませてもかまいません。 たとえば
Part 2 of at most 5です。最初のメモの承認は、同じ作業項目について、カテゴリの「承認なしで実行が追加できる続きの数」(変えなければ 4)までの続きも承認したことになるので、5 パートの作業の承認は 4 回ではなく 1 回で済みます(続き)。その数は、パートの数から 1 を引いた数以上にしてください。メモの中の数は実行への助言で、Control Plane が数えるのはカテゴリの数です。超えた分の次のパートは承認カードで待ち、承認すると新しい連鎖が始まります。実行には、次のパートを同じ作業項目(同じ参照)で、自分のプルリクエストがマージされたあとにだけ追加し、上限に着いたらその旨を伝えて何も追加しないよう伝えてください - この部分がマージされなかったなら、次の部分を積みません。 実行には、次の部分を自分のプルリクエストがマージされたあとにだけ追加するよう伝えます。途中で止まった実行や、プルリクエストがまだ開いている実行は、何も追加しません。マージされないかもしれないプルリクエストを待つメモが残ることもありません
- 要約の頭に付けます。 作業が残った部分は
Partial:、やらなかった項目はDeferred:、切り直しが必要な項目はToo large:です。実行履歴 で、ひと目で読み分けられます
1 件ずつ人が見なくても、レビューしてマージする
Section titled “1 件ずつ人が見なくても、レビューしてマージする”これは進めかたの 1 つです。別のモデルのレビューでマージしてよい変更に向きます。それ以外は、マージを自分の手元に残します。
何がマージを止めるかを、常設の指示とレビュー役への依頼の両方に書きます。 止めるのは、メイン ブランチに対する退行、1 つの障害でその変更自身の動作が壊れること、データの消失、セキュリティの穴、その変更のテストの不足です。独立した障害が 2 つ以上同時に起きて初めて出る指摘や、プルリクエストを超える設計の変更でしか塞げない指摘は、メイン ブランチより悪くならないなら、続きの Issue と Known limits の節に回し、プルリクエストはマージします。これがないと、厳しいレビュー役は毎回さらに深い組み合わせを見つけて、その部分はいつまでもマージされません。
- 別のモデルでレビューします。 別のモデルのレビュー役のセッションがプルリクエストを読み、開いたセッションに報告します(子セッション)
- レビューしたコミットだけをマージします。 レビューが見た先頭のコミットにマージを固定します。たとえば
gh pr merge --match-head-commit <sha>です。先頭が変わっていたら、マージは断られます - 最後のレビューの回は慎重に扱います。 最後のレビューのあとにコミットを足すと、先頭はレビューされていないものになります。最後の回は、マージを止める指摘だけを直し、軽い指摘は別の Issue に切り出します
- 人が行うマージを残します。 CI やリリースのワークフローの変更と、データを消したり書き換えたりするマイグレーションです。前にしか進められないマイグレーションは、リリースを戻しても元に戻せません
- 人の確認は、リリースの関門かステージング環境に寄せます。 実機での確認が要るプルリクエストにラベルを付けて、そこに一覧しておくと、確認はプルリクエストごとではなく、リリースごとに 1 回で済みます
セッションがどこまでしてよいかは、指示に書きます。マージしてはいけないセッションは、要約にそう書き、プルリクエストをそのままにします。
- 実行履歴 を読みます。要約の頭に上の語が付いていれば、1 日分の実行が一覧として読めます
- 開いたままの実行は、「終わっていない理由」に理由が出ます。もう要らない実行は、その行の「終了」を押します。枠が空き、セッションとそれが起動したセッションが停止します(実行を自分で終える)
- 最初のターンの失敗が 2 回続くと、カテゴリは一時停止します。原因を直して再開します(一時停止と再開)
- 設定の通知で「自動実行」の行を確かめておくと、期限超過や一時停止が届きます(通知を受け取る)
つまずきやすいところ
Section titled “つまずきやすいところ”- 指示を直しても、動いている実行は変わりません。 次の実行から効きます
- PR がマージされたあとも開いたままの Issue は、実行を無駄にします。 次の実行がそれを選び、やることがなくて
Deferred:で終わります。Issue を閉じるか、積む前に確かめます - 待っている実行は枠を持ち続けます。 ウォッチを待つ実行が 4 つあると、4 つの枠が埋まって、ほかは何も始まりません。終わらせるか、待たせるメモで順序をはっきりさせます
- 開始済みのメモは、実行が差し戻した場合(実行がメモを差し戻す)を除き、自動ではもう一度動きません。 作業が残って終わった実行の残りは、Issue にあります。「キューに戻す」は、プルリクエストを確かめてから押します(実行のメモをキューに戻す)
- 連鎖を並行して走らせると、承認カードが埋まり続けます。 連鎖の最初のメモは、自分で書いたものと、自分が起動したセッションが追加して設定がオンのものは承認が要らず、それ以外のセッションのメモには承認が要ります。「承認なしで実行が追加できる続きの数」を超えた部分も承認カードで待ちます。承認すると、そこからその数までの新しい連鎖が始まります(続き)。その数は、パートの数から 1 を引いた数以上にしてください
- 続きの Issue は増え続けます。 実行は、見送った指摘ごとに Issue を立てるので、キューが収束しても Issue の数は増えます。自動ではキューに積まれないので、ときどき仕分けてください
- 最初から「自動で実行する」をオンにしません。 「今すぐ実行」で 1 回試してからオンにし、その前に費用の上限を決めます