変更の計画

handbook plan --source <repo> --handbook <dir> --request "<text>" --out plan.md

プランナーは 読み取り専用 のエージェントです。一覧・読み取り・grep を行います — 書き込みツールは無効化されたものすら一切持ちません — そしてその出力は、別の何かが実行する ためのプランです。

ループ

1. ハンドブックでルーティングする: どのファイル、関数、状態がスコープに入るか?
2. 見つけたすべてのアドレスで 実際のソース を読む。
3. バイト単位で正確な old と new テキストを持つ ### EDIT n ブロックを出力する。
4. JSON の宣言ブロックで締めくくる。

良いリクエストの書き方

欲しい振る舞い を述べてください。それがあると思うファイル名ではありません。ファイルを 指名すると、プランナーの探索はあなたがすでに思いついた場所に狭められます — それでは本末転倒 です。

プランの読み方

### EDIT 1

- file: `src/upload.py`
- where: `Uploader.send (~88)` — wrap the request in the retry helper

```old
    response = self._client.put(url, data)
```

```new
    response = self._retry(lambda: self._client.put(url, data), attempts=3)
```

### EDIT 2

- file: `src/upload.py`
- where: `Uploader` — add the helper

```old
    def send(self, url, data):
```

```new
    def _retry(self, call, attempts):
        last = None
        for _ in range(attempts):
            try:
                return call()
            except TransientError as exc:
                last = exc
        raise last

    def send(self, url, data):
```

Both call sites now share one retry policy.

```json
{ "will_modify": ["Uploader.send"], "will_add": ["Uploader._retry"], "will_remove": [] }
```

このフォーマットが従うルール:

• old は バイト単位で正確 に、ファイル内に ちょうど 1 回 現れなければなりません。
• 空 の old は「このファイルを作成する」を意味します。
• 編集は番号付きで、上から下へ 昇順 に並びます。
• 末尾の json ブロックは resync に消費され、リフレッシュ範囲を絞り込むのに使われます。

適用する前にプランを読んでください。 ドライランが教えてくれるのは適用 できる か どうかです。適用 すべき かどうかを判断できるのはあなただけです。

諦めたとき

plan は 非ゼロで終了します — スクリプトが apply に流し込んでしまうような謝罪文を plan.md に書き込んだりはしません。

チューニング

ハンドブックなしの場合

handbook plan --source ~/code/api --request "…"

動作はします — プランナーはソースを直接探索するモードにフォールバックします — が、これは 劣化モードです。ハンドブックが存在するのはまさに、ガイドなしの探索は自明な箇所を見つけて 散在した箇所を見逃すからです。

サンドボックスが許可すること

list_dir(path)
read_file(path, start_line?, end_line?)
grep(pattern, path)
finish(plan)

• すべてのパスはサンドボックスルートの内側で解決されます。シンボリックリンク経由を含め、 外への脱出は拒否されます。
• ハンドブックは __handbook__/ に読み取り専用でマウントされます。これはソースとは 別個の サンドボックスです。
• 読み取りは 60,000 文字が上限、grep は 100 ヒットが上限で、5 MB を超えるファイルは スキップされます。
• 破滅的な正規表現 — (a+)+ や (.*)* のような、量指定子を含むグループへの無制限の 量指定子 — は、実行をハングさせる代わりに、穏当なツールエラーとして拒否されます。

次へ