Fleet Brief (フリート概要書)
並列エージェントは共有グラウンドで失敗します — 2つのレーンが1つのファイルを編集するケースです。概要書は、派遣前にその衝突を不可能にするために存在します。実際のファイルマップから境界を導出し、決して推測してはいけません。
この順序で概要書を作成する
1. 最初にファイルをマッピングする
レーンを定義する前に、提案された各変更が影響するファイルをリストアップしてください。それらを読み込んでください。ファイルを読まずに定義されたレーンは、衝突が起きるのを待っているようなものです。
2. 排他的所有権を割り当てる
すべてのファイルには正確に1つの所有レーンがあります。以下の表を作成します。
| レーン | 所有（書き込み） | 読み取りのみ |
|---|---|---|
| W1 — <名前> | path/a.ts、path/b.ts | path/shared.ts |
2つのレーンが1つのファイルに書き込む必要がある場合、3つの選択肢があります — 明示的に1つを選び、曖昧なままにしてはいけません。
- 順序化する（W2はW1のマージを待つ）
- 1つのレーンに統合する
- シームを入れる：一方のレーンが拡張ポイントを追加し、もう一方がそれを利用する
3. 共有グラウンドを名前付ける
複数のレーンが読み取るすべてのファイルをリストアップし、誰が書き込んでもよいかを明記します。
このリストは目の前のコードベースから導出してください — 別のプロジェクトのリストを流用してはいけません。チェックすべき繰り返し発生するパターンは以下の通りです。
- ライブインバウンドパス。 Webhookやユーザートラフィックを受信するもの。ここでの並行編集はテストではなく本番で失敗します。
- 複数の機能が呼び出すエンジンモジュールとディスパッチャモジュール。
- 追加専用のマニフェスト — デプロイ設定、ルートテーブル、関数リスト。プラットフォームには制限（関数数、ファイルサイズ）があり、2つのレーンが独立して追加すると制限を超える可能性があります。
- 広くインポートされているエクスポート。 追加的に拡張します；名前変更はすべての呼び出し元に波及します。
- 生成またはベンダリングされたファイル — どのレーンも手動で編集すべきではありません。
一度衝突を引き起こしたファイルは、永久に共有グラウンドと見なします。それを概要書に記録し、次のフリートがその知識を継承できるようにします。
4. DO-NOTリストを導出する
各DO-NOTには、ファイルまたは動作の名前とその理由を記載します。理由のない禁止は無視されますが、根拠のあるものは守られます。
ほとんどのコードベースに一般化できるエントリ：
- 競合解決中に決して
git add -Aを行わない — 競合マーカーや他のレーンの作業がステージングされます。 - ワーカーはリンクされたワークツリーでコミットしません；オーケストレーターがコミットします。
- テストスイートがデータベースをグローバルにモックしている場合、ユニットテストが成功してもデータベースについては何も証明しません。そのことを明示的に述べてください。
- 理由を一行で説明せずに依存関係を追加しないでください。
- レーン内からスキーママイグレーションを適用しないでください。レビューされる単一のステップに延期してください。
- サイレントに失敗するCLI呼び出しに注意してください — 例：
gh pr createには明示的な--baseが必要であり、連鎖heredocはエラーを飲み込む可能性があります。
次に、プロジェクト固有のものを追加します。夜を費やしたすべてのインシデントは、その理由とともにここに属します。
5. ゲートを設定する
レーンごとに、「完了」の意味、それを証明する証拠、マージ前にレビューする担当者を明示的に述べてください。
デフォルトとして維持する価値があるのはレビュー後のライブリリースです — ビルド、独立した行レビュー、修正必須ラウンド、マージ。レーンをその作成者だけの判断でマージしてはいけません。作成者のエージェントは、自身の差分にとって最悪のレビュアーです。
6. 保留されているものをマークする
あえて未完了 — 人間の判断が必要 セクション。明示的な承認のために保留されている項目は、意図的に保留されています。準備ができているように見えても、レーンに実行させてはいけません。
分離
ビルドはgit worktreesで実行し、メインチェックアウトでは実行しないでください — 1つのワーキングディレクトリを共有するフリートは編集が混在します。マップにもかかわらずレーンが重複するファイルを変更する場合は、各レーンに独自のworktreeを割り当ててください。
サイジング
レーンは独立してマージ可能であるべきです。あるレーンが別のレーンのPRなしではマージできない場合、それはレーンではなくフェーズです。フェーズは順序化し、レーンは並列化します。
出力
プロジェクトが計画を保持する場所に概要書を書き込み、「確認し、決して推測するな」という警告とともに開いてください。ソースドキュメント内のステータス行はチェックポイントであり、権威ではありません — 派遣前にライブコミット、データベース状態、PRチェック、ワークツリーヘッドを再確認してください。