log

天井の低いセッションでタスクを送るためのバッチ生成方法論

セッション寿命が短いAIエージェント環境で、複数タスクを整合性を保ったまま段階的に送るための「バッチ再編プロンプト」と出力フォーマットの型。ユーザーがタスク一覧+現状メモを投げるだけで、エージェントが3ブロック構造の指示書を生成できる。

この記事の目的

Parlourite Notes の開発は、天井の低いチャットセッション(2〜3往復で切れる可能性のある環境)でAIエージェントに依頼している。この制約下でリファクタや機能追加を「複数タスクまとめて」渡すと、以下が起きる。

  • エージェントが優先度順に着手して途中で切れ、同じファイルを次セッションが別方針で触って整合性が壊れる
  • タスク粒度がバラバラで、1メッセージに収まるはずのものが分割される
  • 引継ぎ書に「何が終わって何が残っているか」が正確に書かれず、次セッションが再調査から始める

この記事は、上記を避けるための 「タスク一覧 → 分割バッチ指示書」変換プロンプト と、その出力フォーマットの型を残す。実際にこの方法論で 8 タスクを 7 バッチに再編し、Batch 1 の指示書を運用開始した経験に基づく。

使い方(ユーザー視点の3ステップ)

Step 1: タスクを溜める

思いついた順にタスクを箇条書きでメモする。粒度・優先度・依存関係は気にしない。既存の引継ぎ書や設計ドキュメント(本ブログでは docs/handover/ や meta/SCHEMA.md)に断片的に散っていてよい。

Step 2: プロンプトと一緒にエージェントに投げる

後述の「エージェント向けプロンプト」を先頭に置き、続けて以下を貼る。

  • タスク一覧(優先度順に並べたもの。詳細は書けるだけでよい)
  • 現在のプロジェクト状態(重要ファイル一覧・基本設計・不変制約)

エージェントは重複・依存関係を可視化した上で「N バッチへの再編案」を返す。この段階では実装はしない。壁打ちのみ。

Step 3: バッチ指示書として1つずつ送る

再編案に合意できたら、エージェントに「Batch 1 の完成版指示書を生成せよ」と依頼する。以降は 1 バッチ = 1 セッションで実装依頼する。

エージェント向けプロンプト(コピペ用)

以下をそのまま新規セッションの冒頭に貼る。

あなたはタスク再編アシスタント。以下のタスク一覧と現状メモを受け取り、送付単位を再整理せよ。
## 再編ルール
1. **同一ファイル群を触るタスクは合体させる**。分割送付は整合性破壊の元
2. **依存関係のあるタスクは前段バッチを先に置く**(例: schema変更 → それを使うUI改修)
3. **独立性の高いタスクは最後にまとめる**(仕上げ枠)
4. **1バッチは1セッションで完了可能な粒度に収める**。過大なら分割、過小なら合体
5. **元の優先度は尊重するが、効率メリットが大きい場合は入れ替えを提案してよい**(理由必須)
## 出力手順
### フェーズA: 再編提案(実装しない)
- 現状分析: タスク × 触るファイル × 依存の一覧表
- 問題点: 重複・依存の指摘
- 再編案: N バッチへの集約と、各バッチの根拠
- 注意点: 優先度入れ替えがあれば明示
### フェーズB: 完成版指示書生成(ユーザー合意後)
下記「出力フォーマット」に従い、3ブロック構造で生成する。
## 出力フォーマット(3ブロック構造)
### ブロック1: バッチ全体マップ
- 全バッチの一覧表(Batch番号 / 内容 / 状態)
- 「← 今ここ」「✓」で進捗管理する運用を明示
- 全バッチ共通の遵守事項(想像禁止・1メッセージ完結・ネスト禁止・引継ぎ書作成 等)
### ブロック2: 今回のスコープ
- サブタスク分割(1-A, 1-B, ...)
- 触ってよいファイル
- 触ってはいけないファイル(他バッチの領域を明示)
- 完了条件(チェックボックス形式)
- 次バッチへの申し送りテンプレ(このバッチで確定した情報の受け渡し欄)
### ブロック3: 前提条件とプロジェクトについて
- 現在の基本設計(確定・不変事項)
- 現在のルーティング
- 重要ファイル一覧と役割
- 型定義など変わらない参照情報
- プロジェクト固有の落とし穴
- 環境情報
## 遵守事項
- 想像でタスクを追加しない。渡されたタスクの再編に徹する
- ブロック3は毎回同じものを貼る想定。省略可の指示があった場合のみ簡略化する
- 出力はMarkdown。コードブロックのネスト禁止

バッチ設計の判断基準

再編時にエージェントが使う判断軸を明文化しておく。

統合すべきケース

  • 同一ファイルを複数タスクが触る: 例)詳細ページ末尾に「related表示」と「backlink表示」を追加する2タスクは、[id].astro の同じ箇所を触るため必ず合体
  • 同一の設定ファイルを連続で編集する: 例)remark プラグイン追加と rehype プラグイン追加は astro.config.mjs を連続編集するため、隣接バッチに置く
  • UI基盤系タスクの相互依存: 例)サイドバー刷新とTOC新設は、同じコンポーネント外枠(SidebarShell)を共有するため不可分

分離すべきケース

  • セマンティクスが異なる: 例)schema変更(データ層)とUI改修(表示層)は同じ日に触っても分離する
  • 検証手段が異なる: 例)ビルド検証で済むものと、実ブラウザでの表示確認が必要なものは分離
  • リスク階層が異なる: 例)不変制約に近い部分(type色ロジック等)を触るバッチは、独立させてレビュー密度を上げる

順序決定

  • 前段が後段の材料を作る依存: 前段を先に
  • 入れ替えで効率が上がる場合: 元優先度を破ってもよい。ただし提案時に理由を明示
  • 独立仕上げ枠: RSS追加・OGP生成など「他バッチに影響しない追加系」は最後にまとめる

出力フォーマット仕様

ブロック1: バッチ全体マップ

必須項目:

  • サイト・エージェント役割の1行宣言
  • 全バッチ一覧表(3列: Batch番号 / 内容 / 状態)
  • 進捗記号の運用ルール
  • 全バッチ共通の遵守事項リスト(プロジェクト不変制約を含む)

ブロック2: 今回のスコープ

必須項目:

  • サブタスク(1-A, 1-B 形式で番号化)
  • 各サブタスクの具体的な仕様・出力例
  • 触ってよいファイルの列挙
  • 触ってはいけないファイルの列挙(理由となる他バッチ名を併記)
  • 完了条件(チェックボックス、ビルド成功を必ず含む)
  • 次バッチへの申し送りテンプレ

ブロック3: 前提条件とプロジェクトについて

必須項目:

  • 基本設計の確定事項
  • ルーティング一覧
  • 重要ファイル一覧と役割
  • 主要な型定義
  • 動作確認手順
  • プロジェクト固有の落とし穴
  • 環境情報

このブロックは毎回ほぼ同一。プロジェクトの現状変化に応じて バッチ完了時に更新し、次バッチ生成時にはユーザーが最新版を貼る。

アンチパターン

「優先度順に上から N 個」で切る

優先度は思考の起点であって、送付単位ではない。同一ファイルを触るタスクが優先度で離れて配置されていると、必ず整合性が壊れる。

1バッチに全部詰め込む

「まとめて渡せば済む」と考えて 8 タスクを 1 メッセージに詰めると、エージェントは冒頭タスクだけ完遂して切れる。バッチ分割の目的は「1セッションで完結する粒度」を守ること。

触ってはいけないファイルを列挙しない

「触ってよい」だけ書くと、エージェントは境界を推測で拡張する。他バッチの領域を明示的に禁止することで、越境時に自発的に停止させる。

申し送りテンプレを省略する

「必要なら書いてくれ」では書かれない。このバッチで確定した情報を次に渡すための空欄を先渡ししておくと、埋める運用が定着する。

プロジェクト前提ブロックを略す

「前回と同じだから省略」とすると、新規セッションのエージェントは知らない。毎回貼る。文字数は運用コストとして受容する。

リファレンス

本方法論で実際に生成された Batch 1 の完成版指示書は、Parlourite Notes リポジトリの開発履歴に残っている。3ブロック構造の実物として参照可能。

再編プロセス自体の記録として、以下も残っている:

  • タスク棚卸し時の重複・依存分析(現状分析表)
  • 再編案(8タスク → 7バッチへの集約と根拠)
  • タイポグラフィ変更の判断過程([[2026-09-22-typography-redesign]])

この方法論の適用範囲

  • Parlourite Notes の開発タスク(本用途)
  • 他プロジェクトでも「AIエージェント + 短セッション + 複数タスク」の組み合わせなら流用可
  • 逆に、長時間セッションが確保できる環境・単発タスクの依頼では過剰。素直に1メッセージで投げてよい

更新運用

この記事は方法論の SSOT として扱う。実運用で判明した改善点は updates に追記して本文を書き換える。バッチ再編プロセスそのものの改善履歴は別 log として起票する。