Share
Embed
Transcript
25 slides
-
hcコマンドをエージェントに操らせる 並列でエージェントを⾛らせることで開発は速くなったが、 ⼀⽅で、乱⽴するエージェントの管理が⾯倒になってきた • どのセッションに何を頼んだか、どこまで進んだかを覚えておく • 終わったのを⾒つけて、次の作業を渡す • どれを先に、どれを同時に進めてよいかを、そのつど考える •
思いついた作業を、⼿の空いたセッションができるまで覚えておく • 作業中に⾒つかった別の問題を、忘れないように控えておく • 報告を読み、本当にできているかを確かめる • ⽇をまたぐと、残りが何だったかを思い出すところから始まる → この調整役を、エージェント x hcコマンド x 独⾃バックログ で実現する 3 -
全体像 ⼦ 🟦 Claude: 実装 ⼈ 指⽰‧要約 司令塔(Claude Code) 1
⾏ずつ渡す (hc 経由) 報告 ⼦ 🟩 Claude: レビュー 積む 次に渡すタスクを読む バックログ(backlog.md) ⼦ 🟧 Codex: 追加レビュー • Claude Code のセッション 1 つを「司令塔」にして、実装は⼦セッションに任せる(スキルで指⽰) • ⼈が話す相⼿は基本的には司令塔だけ(ただし、⼦セッションに直接介⼊することもできる) • 作業の⼀覧は 1 ⾏ずつ積むバックログのファイルで持つ(履歴もバックログのフォルダに持つ) 4 -
バックログ: 指⽰を積むキュー • 指⽰は、すぐ実⾏せずにバックログファイルへ 1 ⾏で積む • 1 つの作業領域につき 1
フォルダ <領域>/ backlog.md 2026-11/ done.md log.md <タスクの id>/ 片付いていないタスク 片付いたタスク(月ごと、追記のみ) 出来事の記録(月ごと、追記のみ) 子に渡したタスク文、報告 ⽚付いた⾏は done.md に移す。⼦に渡したタスク⽂、報告も保存する バックログは「残っているもの」だけで短いまま • タスクを確認‧操作するコマンドを⽤意 → 司令塔が⾃由に編集して壊さないように&トークン消費を若⼲抑えるため (サンドボックスの外で動く必要があり、サンドボックスの除外コマンドに⼊れて利⽤) 5 -
バックログの書式 # backlog: shop-app repo: /path/to/shop-app ## Tasks - 🟩
? [coupon-expiry] impl app/models: 期限切れクーポンが一覧に出る → spec が通る | ask: PR を出すか - 注文キャンセル時の 500 を直す - 🟦 [cancel-plan] plan api: 原因を調べ計画を書く → 計画ファイル | started: 2026-11-14 - 実装 | after: cancel-plan - [cancel-api] impl api: キャンセル処理を直す → テストが通る - [cancel-ui] impl web: エラー表示を直す → 画面で確認 | after: coupon-expiry - [cancel-go] human: 本番相当のデータで試すか決める | after: cancel-api, cancel-ui - [cancel-review] review-high 上の差分: レビュー → 指摘の一覧 | after: cancel-go - 依存の更新で見つかった件 - [ci-node-warning] impl-light .github/workflows: 非推奨の警告を消す → CI が通る | found-by: cancel-plan - [readme-setup] impl-light README.md: 古いセットアップ手順を直す → 差分 | found-by: cancel-plan - [search-slow] impl api: 商品検索が遅い原因を調べる → 報告 <状態> [id] 種類 <場所>: やること → 完了条件 | 項目: 値 | … 6 -
バックログの書式:決めたことと、やめたこと 決めたこと: やめたこと‧選ばなかったもの: 1 タスク 1 ⾏ - 経緯や細かい指⽰は、⾏ではなくタスク⽂のファイルに書く 候補
理由 チェックボックス ([ ] [x]) 片付いた行が残って長くなる。片付い たら別ファイルへ移す 番号付きリスト 並びが順序に見える。順序は after: だけにした #タグ でのまと まり 書き忘れる。インデントと id の先頭で 足りた JSON / YAML 人が直接読み書きしづらい Issue トラッカー タスクの粒度が小さいので管理しづら い。読むたびに通信が要る。 id は司令塔が短い英語で付ける(cancel-api、search-slow) - 会話でも出⼒でもその名前で呼べる 状態は印で表す - 印なし = 未着⼿、⾊ = 実⾏中、⾊と ? = ⼈の確認待ち 完了条件を必ず書く - 決められないときだけ、司令塔が⼈に質問する 順序は after: だけ - 並びは優先の順で、待つ‧待たないは決めない まとまりはインデントで表す - id の無い⾏が⾒出しで、下のタスクをまとめる 7 -
効果1:指⽰を⾮同期で出せる • ⼦が動いている最中でも、思いついた指⽰をそのまま⾔える ‒ 司令塔はタスクを積んだ上で、次に進むべきタスクを提案 ‒ 今までは、別途TODOリストに⼊れて(頭の中のTODOリストかもしれな い)、タイミングを⾒計らってAIに指⽰しないといけなかった • バックログはファイルに保存されてるので、セッションを切っても⽣き残る
‒ (マシン間で共有したい場合はiCloude等に置く。ただし、サンドボックス の抜け道を防ぐためコマンドが扱える特定のディレクトリに限定しているの で、シンボリックリンクを貼る) 8 -
効果2:依存関係が整理された形で積まれる 「計画して、実装して、レビューして」と⾔うと、司令塔が複数のタスクを依存 関係を考慮しながら積む • 積んだ結果は⽬で確かめられる - 依存関係があれば after: を付けて積む -
after の後には、依存する複数のタスク(id)を書く • ⼈の⼿が要る⼿順もタスクになる(種類: human) - インフラのデプロイや特定の条件下での動作確認など 9 -
効果3:並列と直列を分けて進められる • 次に進めるタスクを機械的に出した上でAIに次のタスク候補を挙げさせる - 既定は 1 件ずつ。並列にするのは、⼈が認めて、作業が重ならないとき - 並列にしたときは、AIが追加でバッティングしないか考えて進める 並列で
4 件を起動しました。どれも shop-app のタスクです。 🟦 ci-node-warning|起動|impl-light で CI の非推奨の警告を解消|操作なし 🟩 readme-setup|起動|impl-light で古いセットアップ手順を修正|操作なし 🟧 search-slow|起動|impl で商品検索が遅い原因を調査(読み取りのみ)|操作なし 🟪 cancel-plan|起動|plan でキャンセル時の 500 の原因を調査(読み取りのみ)|操作なし 同時に動かす件数 - コードを書き換えるのは ci-node-warning と readme-setup の 2 件だけです。 2 件とも別ブランチで作業します。 - 残りの 2 件は読み取りのみです。 重なりの確認 - 2 件の対象は、前者が .github/workflows、後者が README.md です。 - 重なりは見込みで、衝突は確かめていません。対象のファイルは重なりません。 今回は渡さなかったもの - cancel-api と cancel-ui: cancel-plan の計画がまだ無いためです。 - coupon-expiry-followup: #128 がまだ OPEN で、マージ後と note にあるためです。 - lint-rule-cleanup: 40 ファイルに触るので ci-node-warning と重なる見込みがあり、後に回しました。 - cart-total-rounding: 設計に加えて再現テストも要るため、後に回しました。 10 -
効果4:次に何をすればいいか把握しやすい • ⼦セッション完了後、何を確認すべきかを好みのフォーマットで出⼒する 🟧 coupon-expiry|完了|draft PR #128、CI は成功|操作なし 変更: 一覧の取得条件に有効期限を足し、期限切れのクーポンを除いた(4
ファイル、うちテスト 1 ファイル)。 型エラーの数は増えていない。 判断(子の選択): 期限が当日のクーポンは、その日の終わりまで有効として残した。期限が未設定のクーポンは 「無期限」として出し続ける。この 2 点が意図どおりか、PR で見てください。 検証: 子の報告では、新規テスト 2 件は修正前に失敗し、修正後に通る。CI は成功(私が gh で確認)。差分の 中身は私は読んでいない。 未実施: タイムゾーンをまたぐ場合のテストは、書けなかった(報告に理由あり)。 人の確認: /coupons を開く。期限が昨日のクーポンが出ず、期限が今日のクーポンは出ること。 これで cancel-ui の待ちが解けました。渡してよいか、ご指示ください。 ── 返事待ち(1 件)── 🟩 cancel-review|レビューをもう 1 種類足すか(http://shop.localhost/orders でキャンセルの動作確 認)|1) 足す / 2) 足さない -
効果5:並列でも進捗が追いやすい • 進⾏中のタスクに⾊を 1 つ割り当てる - バックログの⾏、⼦のターミナル、司令塔の出⼒で同じ⾊ • 司令塔の出⼒は 1
件 1 ⾏、複数の決まった欄 🟦 cancel-plan|実行中|テストを書いている(開始 10 分)|操作なし 🟩 coupon-expiry|報告|修正済み、確認待ち|PR を出すか決める 🟧 cancel-review|許可待ち|gh pr diff の実行許可|t9 で「Yes」を選ぶ(読み取りのみ) - 最後の欄は「⼈が何をすればよいか」。操作が無ければ「操作なし」 - ⾏の id と⾊が、そのまま出⼒の⾒出しになる。id が短く意味の分かる名 前なので、「cancel-ui を先に」と⾔えば通じる 12 -
効果6:途中で⾒つかった問題も⾃動で積まれる ⼦には「範囲外で⾒つけた問題は直さず、報告に 別件: として書く」と伝える 司令塔がそれを新しいタスクとして積む(found-by: に⾒つけたタスクの id) • ⼦が範囲を広げない ‒
⼦のコンテキストを汚さない • 気づいたことが、会話と⼀緒に流れない ‒ ⾃分でTODOリストに積む⼿間が省ける 13 -
効果7:AIの成果物を⾒失わない • ⽚付いた⾏は `done.md` に移る - `PR:`、`branch:`、`output:`(計画や報告のファイル) - あとから id
で探せば、PR とブランチが分かる • ⼦に渡したタスク⽂と、⼦の報告は、タスクごとのフォルダに残る ‒ あとから主要な報告を⾒返せる / 検索できる • 上記は⽉別のフォルダに置かれる 14 -
なぜ⼦エージェントではなく⼦セッションなのか • Claude / Codex などを使い分けられる - モデルの選択範囲が拡がることで、より適材適所で適⽤できる • 任せた仕事を、⼈がいつでも引き取れる
‒ どの⼦が今どうなっているか、ひと⽬で分かる ‒ 詰まったときも確認のときも、⼦に直接⾔える ‒ あとで聞ける: 数⽇後でも、作業した本⼈に聞ける ‒ (⼦エージェントでもできなくないが、UI的にいまいち) 15 -
注意1:⼦とのやり取りを絞る 司令塔は hcコマンド を直接は呼ばない。薄いラッパーのコマンドを 1 つ挟む • ラッパーが許すのは決まった操作だけ - 決まった種類の⼦を、登録した
repo の下で起動する - ⾃分が起動した⼦を読む、送る、⽌める - ⼦から親への報告 - バックログの⾏を⾜す、状態を変える ‒ 理由: 司令塔は⼦の報告や diff という「信⽤できない⽂」を読む。そこに 指⽰が紛れていても、できることが増えないようにする 16 -
注意2: 権限 ⼦の権限は、⼦が起動したディレクトリの設定で決まる - ⼈がそこで⼿で起動したときと同じ。司令塔の設定は引き継がれない - サンドボックスなどの守りはユーザー設定(グローバル)に置く。どのディレ クトリで起動した⼦にも効く 許可の問い合わせは⼈が答える -
司令塔は、許可待ちの⼦に⽂を送れない - 組織の管理設定で ask になっているコマンドは、どう設定しても毎回聞かれ る。⼦がよく使うものは、聞かれない専⽤コマンドを⽤意したほうが早い - 司令塔と⼦が使うラッパーは、エージェントが書き換えられない場所に置く 17 -
注意3:レビューと検証 • 司令塔は、報告の⽂⾯から成功を推測しない ‒ diff を読む(範囲外の変更が無いか) ‒ ⾏に書いた verify: のコマンドを⾃分で実⾏し直す
‒ ⾜りなければ差し戻す。回数は⾏に残る • レビューは実装した⼦とは別の⼦に渡す ‒ リスクが⾼い変更は、レビューの強度を上げる(review-high) ‒ 込み⼊った変更には、別モデル(Codex)の追加レビューを並べて⾛らせる (codex-review) 18 -
注意4: モデルと費⽤ • タスク⽂の質と報告の検証が、全体の質を決める - そのため、司令塔は上位のモデルで動かすことが推奨されると思う - ただ、現時点のSonnetでも何とかなる(おそらくタスク関係がそこまで込み ⼊ってなければ) •
⼦は種類ごとにモデルと推論の強さを決めておく - 計画は強く、実装は普通、定型作業は弱く • 同時に動かす⼦の数に上限を置く - 並列にすると、トークンは⼦の数だけ出ていく - 検証環境のリソースの⽅が先に逼迫する可能性がある 19 -
その他の改善 • 状態の変更はコマンド 1 回で、バックログ‧done‧log をまとめて書き換える • 同時に書き換えないように、領域ごとにロックを取る • 司令塔⾃⾝のコンテキストも節約する:
⼦の画⾯は必要な⾏数だけ読む、報告は 写すだけで読み直さない • ⼈が下書きを⼊⼒している間は、⼦からの報告の差し込みを待たせる • 続きの作業は同じ⼦に⾜す:⼦が読んだ内容を使い回し、PR 1 つで済ませる • 休憩の時刻から逆算する:休憩の場合は⻑いタスクを直前に渡し、終了の場合 は終わる⾒込みのないタスクは渡さない。区切りで compact を勧める 20 -
使ってみて • ⼤きめの作業に向く ‒ フレームワークの更新を、計画 → 段階ごとの実装 → レビュー →
マージ待 ちで数⽇かけて進める ‒ 課題 → 調査 → 計画 → “司令塔スキル” → サブプランを並列実⾏、という 流れがいい ‒ 途中で⾒つかった課題も⾒逃さない • ⼩さな修正 1 件には⼤げさ。トークンのオーバーヘッドもあるので • 使いながらすぐに改善していける ‒ ⾏が読みにくい → 書式を変える、など ‒ 要件さえあれば、⾃作するのはそんなに時間かからない 21 -
まとめ • ⼦の起動とやり取りは herdr-core に任せた • 作業の状態は、会話ではなくファイルに置いた。そこから得たもの ‒ ⾮同期に指⽰できる ‒
依存が⾒える。だから並列にできる ‒ ⾊と id で追える ‒ 途中で⾒つかった問題も⾃動で積まれる • ⾃分好みの司令塔を⼿軽に作れる ‒ ただし、セキュリティには注意を払う 22 -
参考資料 herdr-core: herdr-core の公式ページ。hc でできることと、アプリとの関係 Herdr.app と hc の上で Claude
Code の司令塔を回している(hoshinotsuyoshi さん、2026-11-09): 司令塔を置く考え⽅と、報告の待ち⽅ 23