エージェントが止まるとき
サブエージェントに実装＋検証をまとめて任せると、途中で環境が理由で進めなくなることがある。 そのときに何を返させるかを先に決めておかないと、レポートが信用できなくなる。
結論
指示に3値を持たせる。成功 / 失敗 / 未実施 を混ぜない。
指示文にはこの一文を入れる。
未実施を成功扱いしない。実行できなかった検証は「未実施」と明記し、
PR作成まで進めずに現状をIssueへ書き出して停止すること。
停止したら新しいsub-issueを起こさせ、確認できた範囲 と 対応案 を書かせる。
親Issueは OPEN のまま残す。ここでcloseさせると、未検証の変更が完了扱いで埋もれる。
実際に踏んだ環境エラー
Docker daemon への接続が権限拒否
エージェントからは「Dockerが使えない」としか見えないが、原因は複数ある。
| 症状 | 実際の原因 | 確認 |
|---|---|---|
| daemon接続が拒否される | Docker Desktop が落ちている | docker info が返るか |
| 起動しているのに未起動判定 | launchd実行時に PATH が足りない | plist の EnvironmentVariables |
| コンテナは動くが遅い | 割り当てが小さい | docker info の NCPU / MemTotal |
docker info --format '{{.ServerVersion}} {{.NCPU}} {{.MemTotal}}' を検証の前段に必ず置く。
返らなければその時点で未実施として止める。ここを省くと、
DBが必要なテストがタイムアウトで落ちて「テスト失敗」として報告されてしまう。
専用worktreeで npm ci が EPERM
worktreeを切って依存を入れ直す構成だと、node_modules が作られないまま先へ進むことがある。
ls -d <worktree>/<app>/node_modules # No such file or directory なら依存は未導入
依存が無い状態では型検査もlintもfocused testも意味を持たない。
npm ci の完了を検証の前提条件（preflight）に含め、
失敗したらそこで止める。後続の結果を集めても全部ノイズになる。
既存の型検査・lintエラー
作業前から失敗しているものは、その回の変更と切り離す。 混ぜると「自分の変更が壊した」のか「元から壊れていた」のかが判定できず、 エージェントが直さなくていいものを直しはじめる。
作業開始時に一度走らせて、既存エラーの一覧をIssueへ貼っておく。
preflightに入れる項目
長い検証を任せる前に、この順で確認させる。
package-lock.jsonの存在と、対象worktreeのnode_modulesdocker infoの応答（ServerVersion / NCPU / MemTotal）- 必要なコンテナの
healthy状態 - 変更前の型検査・lintの結果（既存エラーの把握）
1つでも欠けたら未実施で停止。これを入れてから、 「動いていないのに通ったことになっている」レポートが出なくなった。
関連
- 開発日記: エージェントが「できませんでした」で止まった日