audit-and-migrate

コードベースの体系的な監査と移行

技術的負債が蓄積したコードベースに取り組むための体系的な手法です。監査（問題を把握して固定する）、移行（証拠を確認しながら段階的に負債を返済する）、完了処理（残存物を取り除き、リポジトリが実際にリリース可能な状態であることを証明する）の3つのフェーズで進めます。

この手法が必要な理由

構造化されていないエージェントは、大規模なリファクタリングで次の4つの点に失敗します。

1. 作業のずれ — 何が完了したかを忘れ、完了済みの作業をやり直したり、セッションをまたいで作業を中途半端なまま残したりします。時間を浪費し、競合を引き起こします。
2. 残存コード — 置き換えたコードを削除せずに新しい実装を追加します。コードベースは縮小すべきときに肥大化します。
3. 直感に頼った確信 — 証明する代わりに「これなら動くはず」と言います。エージェントが合格した決定論的なチェックを示せない場合、その確信には根拠がありません。
4. 見せかけの完了 — 新しい経路が動作した時点で作業を止め、暫定アダプター、古いドキュメント、孤立した依存関係、リリースを妨げる問題を残してしまいます。

この手法の各ルールは、これら4つの失敗のいずれかを防ぎます。ルールが煩雑に感じられるなら、それこそがルールを設ける理由です。

---

セッションプロトコル

毎回のセッション開始時に実施してください。 これにより、コンテキストの圧縮やセッションの切り替えを経ても、この手法を継続できます。

セッションの開始

1. 制御プレーンの成果物があるか確認します（.claude/migration/ またはプロジェクトで成果物を保存している場所を確認してください）。
   • CHARTER.md、DECISIONS.md、SLICES.yaml、MAP.csv、RATCHETS.yaml、SHIP_CHECKLIST.md
   • 以前のセッションで移行に取り組んでいる場合は、最新の HANDOFF.md
2. 成果物がない場合 → 新たに開始します。フェーズ1（監査）から始めてください。
3. 成果物がある場合 → 次の順序で読みます。 a. CHARTER.md — ミッションと不変条件を再確認します b. SHIP_CHECKLIST.md — プロジェクト固有の「リリース可能」の定義を再確認します c. DECISIONS.md — 決定事項とその理由を把握します d. 最新の HANDOFF.md — 現在の状況とブロッカーをすばやく確認します e. SLICES.yaml にあるすべての in_progress スライス — これが現在の作業です f. ガードスクリプトを実行して現在の状況を確認します

セッションの終了

HANDOFF.md を作成または更新します（または、引き継ぎ内容が少ない場合は最新のコミットメッセージに追記します）。次の5項目を必ず含めてください。

1. 変更内容 — 変更したファイル、進捗したスライス、決定事項
2. 現在確定していること — 新しい不変条件、完了したスライス、更新した予算
3. 残作業 — 未完了のスライス、既知のリスク、ブロッキングの問題
4. 現時点でリリースを妨げているもの — 明示的なブロッカー、または None
5. 次の具体的な手順 — 次に実行するコマンドまたはテストの手順

例：

## Handoff — 2026-03-01
### Changed
- Completed slice-003 (user routes auth migration)
- Ratchet budget for jwt.verify decreased from 8 → 5

### Now True
- All user route auth goes through withAuth() middleware
- Behavioral tests cover user routes at 100%

### Remains
- slice-004 (data routes) ready to start
- slice-005 (admin routes) blocked on Decision 4 re: webhook auth

### Shipping Blockers
- None

### Next Steps
1. Run `./guard.sh --status` to confirm baseline
2. Start slice-004: mark in_progress in SLICES.yaml
3. Write behavioral tests for src/api/posts.ts and src/api/comments.ts

この形式なら、コンテキストが圧縮されても情報が失われません。次のセッション（または別のエージェント）は、情報を失ったり、リポジトリが本当にリリース可能か推測したりすることなく、作業を引き継げます。

---

フェーズ1：監査

監査フェーズでは、本番コードを変更する前に問題の範囲を把握します。まず測定することで、安全な移行の基盤を作ります。また、早い段階でリリースの判定基準を定めることで、実装は取り込まれたものの、後続の実行にクリーンアップ作業が持ち越されるというよくある失敗を防ぎます。

ステップ 1：憲章を作成する

references/templates/CHARTER.md のテンプレートを使って CHARTER.md を作成します。次の項目を定義します。

• ミッション — 何を、なぜ移行するのかを一文で記述します
• 重要なワークフロー — 退行してはならない、ユーザーに見える操作経路
• 外部インターフェース — 移行によって、リポジトリ外に影響が及ぶおそれのある公開 API、環境変数、ダッシュボード、Webhook、CLI エントリーポイント、データ契約、自動化フック
• 不変条件 — 移行中も維持しなければならない条件（例：「既存のテストがすべて成功する」「ユーザー向けの動作に変更がない」）
• 対象外 — 明示的に実施しないこと（スコープの拡大を防ぎます）
• ガードレール — プロセス上のルール
• リリース条件 — 移行の完了を宣言する前に必要となる、自動および手動の証拠を明確に定めます

憲章は、いわば憲法です。スコープに迷ったら、憲章を確認してください。

ステップ 2：問題領域を棚卸しする

対象領域に含まれるコード、テスト、スクリプト、ドキュメント、設定、ツール、依存関係をすべて洗い出します。各項目のレバレッジを次のように分類します。

• 高 — 維持して拡張します。移行の基盤となる優れたコードです。
• 中 — 維持してリファクタリングします。構造は健全ですが、更新が必要です。
• 低 — 置き換えます。これが解消する技術的負債です。

漏れなく洗い出してください。ここで見落としたものは、後になって不要なコードとして残るおそれがあります。レバレッジが低い項目については、何に置き換えるのか、またはどのスライスで削除するのかを記録します。

ステップ 2b：重要なワークフローと注意すべき箇所を記録する

スライスを設計する前に、後々問題になりやすいシステムの部分を調査します。

• 重要なワークフロー — 絶対に退行させてはならない、ユーザー向けの操作経路
• 既知の注意箇所 — 直近でバグ修正が相次いだ箇所、TODO/FIXME/HACK の集中箇所、不安定なテスト、脆弱なサブシステム
• 手動でしか確認できないインターフェース — 自動化では完全に検証できない、視覚的な確認、ハードウェア、サードパーティの UI フロー

これらを、スライスのスモークテスト、手動確認、リリース条件の入力情報として使います。

ステップ 3：アンチパターンを測定する

grep/ripgrep を使って、特定の好ましくないパターンの数を数えます。目指すのは、感覚的な評価ではなく具体的な数値です。

各パターンについて、次の情報を記録します。

• 検出に使用した grep パターン
• 検索対象の範囲
• 現在の件数
• 問題となる理由

例（コードベースに合わせて調整してください）。

Pattern: source\.contains\(        Scope: test/          Count: 43    Problem: Tests code shape, not behavior
Pattern: Task\.sleep\(             Scope: test/          Count: 17    Problem: Non-deterministic timing
Pattern: struct Scenario           Scope: test/          Count: 22    Problem: Duplicated test scaffolding
Pattern: require\(.*/utils/old-    Scope: src/ docs/     Count: 8     Problem: Imports from deprecated module

ステップ 4：CI ラチェットで現状を固定する

測定したアンチパターンごとに、現在の件数を上限とするラチェットを作成します。手法については、CI ラチェットパターンを参照してください。

これが最も重要なステップです。ラチェットを設ければ、技術的負債を減らすことだけが可能になります。人間もエージェントも、解消済みのパターンを誤って再び持ち込むことはできません。クエリと検索範囲が明示され、ファイル数ではなく一致件数が測定されている場合に限り、ラチェットを信頼できます。

references/templates/RATCHETS.yaml のテンプレートを使って、これらのラチェットを RATCHETS.yaml に記述します。ガードスクリプトだけに予算を記載してはいけません。

ステップ 5：監査ドキュメントを作成する

包括的な監査ドキュメントを作成します。次の内容を含めてください。

• 使用した手法（棚卸しと測定の方法）
• 現在の指標（すべてのアンチパターンの件数）
• レバレッジの評価（高・中・低の各項目）
• 重要なワークフローと既知の注意箇所
• 率直な結論（変更が必要なこと）
• 追加したガードレール（現在 CI に導入されているチェック）
• リリース基準と手動でしか確認できないインターフェース
• 提案するスライス（フェーズ 2 の初期計画）

ステップ 5b：実用的なリファレンス資料を作成する

コントロールプレーンの成果物と併せて、実際の移行作業を効率化する、ドメイン固有のリファレンス資料を作成します。

• 翻訳ガイド — 古いパターンと新しいパターンの対応関係を示す参照表です（例：生の SQL クエリ → ORM 呼び出し、Redux のパターン → Zustand のパターン）。各スライスが翻訳方法を一から考え直す手間を省けます。
• エッジケースと注意点 — 古い方法から新しい方法に変換する際の既知の落とし穴を記録します。一見単純な置き換えに見えても、動作に微妙な違いがあるケースを取り上げます。
• コードパターンの例 — よくある移行シナリオについて、移行前と移行後の具体的なコード例を示します。

こうした資料は何度も作成コストを回収できます。資料がなければ、各スライス（および各エージェントセッション）が同じ変換パターンを個別に再発見することになります。資料があれば、知識を一度記録するだけで、その後の作業で再利用できます。

ステップ 6：残りの成果物を作成する

references/templates/ のテンプレートを使用します。

• DECISIONS.md — 監査で判明したアーキテクチャ上の決定事項を記入します
• SLICES.yaml — 監査ドキュメントで提案されたスライスを記入します
• MAP.csv — インベントリに含まれるすべてのファイルを記入します
• RATCHETS.yaml — アンチパターンの予算と適用範囲を機械可読形式で記述します
• SHIP_CHECKLIST.md — リリースゲートを一度正確に定義し、完了時に実行します

---

フェーズ 2：移行

移行は、スライス単位で負債を返済するプロセスです。各スライスは、個別に検証できる、成果ベースの垂直的な作業単位です。

開始前の調整

コードベース全体にアクセスせずに監査を行った場合（説明や部分的な調査に基づく場合など）、フェーズ 2 で最初に行うのは、ラチェットの予算を実態に合わせて調整することです。監査ドキュメントにあるすべての grep パターンを実行し、実際の件数に基づいてガードスクリプトの予算を更新します。短時間で大きな効果が得られる手順です。予算が不正確だと、誤検出による失敗（予算が少なすぎる）や、回帰の見逃し（予算が多すぎる）が発生します。

また、スライスの作業を始める前に、ガードスクリプトに --status フラグを追加している場合は、そのフラグを使って実行し、初期状態が問題なくクリーンであることを確認します。

さらに、SHIP_CHECKLIST.md にプレースホルダーではなく、具体的なコマンドとシナリオが記載されていることを確認します。完了フェーズの質は、実行するチェックリストの質に左右されます。

完了時の統合スライスを確保する

実装を始める前に、SLICES.yaml に最終的な統合スライスを確保します。このスライスはすべての実装スライスに依存し、コードベース全体のクリーンアップを担当します。対象には、残存物の一掃、依存関係の整理、ドキュメントと設定の整合、SHIP_CHECKLIST.md の実行が含まれます。

このスライスをあらかじめ確保しておかないと、クリーンアップが「後でやる作業」になり、その「後の作業」がいつの間にか別の移行になってしまいます。

次のスライスの選択

SLICES.yaml を確認し、ブロックされていないスライスの中から、最も効果の大きいものを選びます。

1. 依存関係を確認します。依存先が done になっていないスライスには着手しません。
2. 効果の大きいスライス（最も多くのアンチパターンを解消するもの、または他のスライスのブロックを解除するもの）を優先します。
3. 効果が同程度なら、影響範囲が小さいものを優先します。

スライスのライフサイクル

すべての実装スライスは、次の 5 つのステージに従います。

A. 開始

1. SLICES.yaml でスライスを in_progress にします。
2. このスライスで変更するすべてのファイルが MAP.csv に記載されていることを確認します。
3. コードを書く前に、SLICES.yaml で deletion_targets、temp_artifacts、dependency_changes、residue_queries、verification_commands、docs_to_update と、変更対象となる external_surfaces を定義します。
4. ガードスクリプトを実行し、クリーンな初期状態を取得します。

B. ビルド（TDD 優先）

1. 新しい動作がなければ失敗するテストを作成します。 これらのテストで、この範囲の「完了」を定義します。実装の詳細ではなく、公開インターフェースを通じて動作をテストします。
2. 標準的な経路を実装します。 その機能を実現する、新しく正しい方法です。
3. 呼び出し箇所を移行します。 古い経路を使用しているすべての箇所を更新し、新しい経路を使うようにします。
4. この範囲で関連する成果物も更新します。 ドキュメント、設定、環境変数の例、スクリプト、フィクスチャ、CI の参照は移行の一部であり、後回しにする作業ではありません。
5. 置き換えられたコードは、この範囲で削除します。 これは厳守事項です。理由は、削除を後回しにするエージェントは忘れてしまうからです。古いコードは使われないまま残り、誰かが気づく頃には、呼び出し箇所がまた古いコードを使うように変わっています。同じ変更内で削除すれば、移行をアトミックに完了できます。
6. 一時的な足場は削除するか、明示的に追跡します。 アダプター、デバッグ用ヘルパー、一度限りのスクリプト、一時的なフラグは、この範囲で削除するか、担当する範囲とともに temp_artifacts に記録します。

C. クリーンアップの総点検

範囲を「検証済み」とする前に、変更したパスとその隣接モジュールを対象に、残存物を重点的に確認します。

1. この範囲で明らかになった孤立ファイル、未使用のエクスポート、不要なテスト、古いアダプター、使われていない分岐、古いドキュメントや設定、未使用の依存関係を検索します。
2. 不要であることが確認できたものは、すぐに削除します。
3. 不要かもしれないものの、まだ証明できない場合は、明示的なブロッキングフォローアップ範囲にするか、担当者と完了条件を記載して DECISIONS.md に記録します。

クリーンアップとは、「削除する予定だったものを削除する」だけではありません。「この範囲の周辺に残存物を残していないことを確認する」ことです。

残存物の検索クエリは、具体的かつ対象を絞ったものにします。保持すべき名前がリポジトリ内にまだ存在する場合があるため、リポジトリ全体に対する legacy のような広範なパターンは避けます。代わりに、検索対象を明示して import.*legacy-auth、LEGACY_COOKIE_NAME、TODO\\(migration\\) のようなクエリを使います。

D. 検証

該当するチェックをすべて実行します。

1. ガードスクリプトが成功すること — マッピング漏れ、denylist 違反、残存物に関する違反がないこと
2. verification_commands が成功すること — SLICES.yaml に記録された自動コマンドを正確に実行します。
3. リプレイ／スモークシナリオが成功すること — SLICES.yaml で定義されている場合は実行します。
4. residue_queries が一致なしを返すこと — 古い名前、フラグ、TODO マーカー、一時マーカーが実際に削除されていること
5. チャーターの不変条件と、関連する出荷チェックリストの要件が引き続き満たされていること
6. 手動チェックは自動化で網羅できない箇所に限り、その結果を範囲のメモに記録すること
7. 外部向けのインターフェースが引き続き動作すること — この範囲の影響を受けるダッシュボード、公開エクスポート、環境変数の契約、Webhook、CLI エントリーポイントを明示的に再確認します。

E. 完了

1. すべての deletion_targets が実際に削除されていることを確認します（コメントアウトされていないこと、フラグで無効化されているだけでないこと。完全に削除されていること）。
2. すべての temp_artifacts が削除されているか、担当する後続の範囲に明示的に引き継がれていることを確認します。
3. docs_to_update と dependency_changes の内容を照合します。
4. 範囲によって不要になった空のディレクトリと移行専用の足場を削除します。
5. MAP.csv を更新します — 移行済みのファイルに印を付け、削除済みのファイルを取り除き、ドキュメント、設定、ツール関連のエントリを同期させます。
6. SLICES.yaml を更新します — 範囲を done にし、実施内容と合格した証拠を記録します。
7. RATCHETS.yaml を更新します — 予算を減らし、ゼロになったラチェットについてメモを追加します。
8. 削除した名前やパスのパターンを denylist に追加します。
9. 新たな決定事項を DECISIONS.md に記録します。

クリーンアップの総点検で、当初の deletion_targets 以外にも不要なコードが見つかった場合は、今すぐ削除するか、現在の範囲を完了とする前に明示的なフォローアップ範囲を作成します。新たに見つかった残存物を、気づかれないままの負債として残さないでください。

---

フェーズ 3：完了処理とリリース判定ゲート

最後の実装スライスが完了しても、移行は完了ではありません。リポジトリ全体がクリーンで、プロジェクト固有のリリース判定ゲートを通過した時点で完了です。

完了処理は後回しにせず、収束に向けた実作業のスライスとして扱ってください。

1. インベントリを再実行します。 MAP.csv を実態と照合します。マッピングされていないファイル、置き換え先のないファイル、見落とされた副次的な成果物があってはなりません。
2. 移行全体の残存物を一掃します。 コード、テスト、ドキュメント、設定、ツール、依存関係を検索し、古いシンボル、不要なファイル、古いアダプター、未使用パッケージ、一時的なフラグ、作業用スクリプト、デバッグログ、移行で導入された TODO/FIXME/HACK マーカーを確認します。
3. 依存関係を整理して検証します。 未使用のパッケージやスクリプト、機能フラグ、ロックファイルの不要な差分、移行専用のヘルパーを削除します。
4. 運用に関わる箇所を整合させます。 README、ADR、環境変数のサンプル、CI ワークフロー、ダッシュボード、公開 API、Webhook、CLI のエントリーポイント、開発者向けドキュメントには、古いアーキテクチャではなく新しいアーキテクチャを反映させます。
5. SHIP_CHECKLIST.md を実行します。 監査時に定義した正確な lint、型チェック、ビルド、テスト、リプレイ、スモークテスト、手動チェックを実行します。可能な限り自動化し、自動化では検証できない視覚的、使用感、ハードウェア、サードパーティー関連の確認に限り、手動チェックを行います。
6. リリース候補として差分をレビューします。 意図しない変更、空のディレクトリ、バックアップファイル、コメントアウトされたコード、不要なログ、old／new／final の成果物がないか確認します。
7. 最終引き継ぎを作成します。 Ready to ship と明記するか、残っているブロッカーを正確に列挙します。負債を意図的に残す場合は、担当者と解消条件を DECISIONS.md に記録します。

---

CI ラチェットパターン

この手法を象徴するテクニックです。好ましくないパターンを一度にすべてなくすのではなく、次のように進めます。

1. 数える：パターンを数えます（例：source.contains のアサーションが 43 件）
2. 上限を設定する：CI の上限を現在の件数（43 件）に設定します
3. 減らす：パターンを削除するスライスごとに上限を引き下げます
4. 強制する：件数が上限を超えた場合、CI を失敗させます
5. ゼロにする：上限が最終的に 0 になり、パターンを完全に排除します
6. ガードを維持する：恒久的なリグレッション防止策として、チェックを 0 件の状態で維持します

エージェントで特に効果的な理由： 明確で機械的な合否判定が得られるためです。数件なら「許容範囲」かどうかを判断する必要はありません。ラチェットが明確に判定します。進捗も 43 → 38 → 29 → 15 → 7 → 0 と具体的な推移で確認できます。

実装方法： 通常は、パターンを grep で検索して一致件数を数え、上限と比較し、件数が上限を超えた場合にゼロ以外の終了コードを返すシェルスクリプトを使用します。一致したファイル数ではなく、完全な一致件数を数え、検索範囲を明確にしてください。上限はスクリプト内だけでなく、RATCHETS.yaml に記述します。パターンについては references/guard-script-pattern.md を参照してください。CI または pre-commit フックに組み込みます。

---

残存コードを残さないための規律

残存コード、つまり置き換えられたのに削除されていない古いコードは、エージェントを活用した開発におけるコードベース肥大化の最大の原因です。エージェントは「新しいものが動くか？」を優先し、「古いものを削除したか？」を確認しない傾向があります。

スライスごとに、次のことを行います。

1. 実装前に deletion_targets を定義します。 作業を始める前に SLICES.yaml に記載します。これにより説明責任が生まれ、事前に定義しておくことで削除を「忘れる」ことがなくなります。

2. 削除した名前やパスの拒否リストパターンを追加します。 コードを削除した後、ガードスクリプトに grep パターンを追加し、その名前が再び現れた場合に失敗するようにします。コードベース内のどこであっても再導入を検出できるため、テストカバレッジより強力です。

3. 削除したアーキテクチャを説明するドキュメントを削除します。 削除済みシステムに関する古いドキュメントは、将来のエージェントや開発者を積極的に誤解させます。

4. 不要になったスクリプト、設定、環境変数のフォールバックを削除します。 削除済み機能の設定は、気づかれにくい負債です。

5. 次の要件を満たさない「一時的な」アダプターを作成しません。 担当するスライス ID、有効期限の条件、明示的な削除対象が必要です。削除予定のないアダプターは、いつまでも残り続けます。

6. 移行マーカーを取り除きます。 TODO(migration)、一時的なデバッグログ、作業用ファイル、old／new／final のコピーは、無害なメモではなく残骸です。

---

スライス設計のルール

各スライスは次の条件を満たす必要があります。

• 垂直的で、成果を基準にしていること — 「すべてのファイル名を変更する」「すべてのインポートを更新する」といった横断的な作業ではなく、機能を完全に実現します。垂直スライスは、それぞれが独立して意味を持ちます。
• 判断が完結していること — ロジックの所有者が明確です。境界が曖昧な共有所有は避けます。
• 個別に検証できること — 決定論的なチェックを備えます。正しさを確認するガードやテストを書けない場合、そのスライスは曖昧すぎます。
• クリーンアップまで完了していること — 表面化した周辺の不要なコード、ドキュメント、設定、一時的な足場も担当します。「機能は動く。クリーンアップは後で」は認めません。
• 影響範囲が限定されていること — レビューやロールバックを問題なく行えるほど小さくします。ロールバックに 40 個のファイルを整理する必要があるなら、分割します。

---

信頼度モデル

スライスの正しさを検証するときは、優先順位に従って段階的な証拠を使用します。

1. 決定論的な再生（最も信頼度が高い） — 入力を再実行し、出力を既知の正常なベースラインと比較します
2. 自動スモークテスト — 重要なユーザー向けワークフローをエンドツーエンドで実行します
3. テストスイート全体 — コードベースのすべてのテストを実行します
4. 手動チェック（最も信頼度が低い） — リスクの高い UX の変更に限って実施します

証拠の情報源が食い違う場合は、決定論的な再生を優先します。「テストは通るが、再生差分が異なる」場合は、何かに問題があります。無視せず、調査してください。

チェックを自動化できる場合は、人の記憶や将来の TODO に頼らず、verification_commands に記載します。

---

コントロールプレーン

移行は 7 つの成果物によって管理されます。テンプレートは references/templates/ にあります。

成果物	目的	更新頻度
CHARTER.md	ミッション、不変条件、対象外事項、ガードレール	まれ（スコープ変更時のみ）
DECISIONS.md	追記専用のアーキテクチャ上の決定事項	決定を伴うスライスごと
SLICES.yaml	機械可読なスライス台帳	各スライスの開始時と完了時
MAP.csv	信頼できる唯一の情報源となるパスの対応表	各スライスの開始時と完了時
RATCHETS.yaml	機械可読なアンチパターンの予算、適用範囲、根拠	監査時に初期設定し、予算を引き下げる際に更新
SHIP_CHECKLIST.md	プロジェクト固有のリリースゲートと完了チェックリスト	監査時に初期設定し、完了時に実施
ガードスクリプト	CI で強制される不変条件のチェック	ラチェットを追加／削除するとき

DECISIONS.md のプロトコル

• 追記専用です。 過去の項目は編集しません。
• 決定の撤回は新しい項目として記録します。 決定 #3 の考えを変えた場合は、「#3 を置き換える」と記し、その理由を説明する決定 #7 を追加します。
• 黙って書き換えることは禁止です。 コードベースの変遷を理解するうえで、決定の履歴は重要です。
• 例外措置には期限を設けます。 残存する負債や一時的な例外を残したままリリースする場合は、担当者と終了条件を記録します。

SLICES.yaml のフィールド

各スライスでは、id、type（implementation または convergence）、name、status（proposed → in_progress → done）、dependencies、touched_paths、external_surfaces、contracts（追加／変更／削除）、denylist_patterns、deletion_targets、temp_artifacts、docs_to_update、dependency_changes、residue_queries、verification_commands、replay_scenarios、smoke_scenarios、manual_checks、risks、notesを追跡します。

MAP.csv の列

slice_id, kind, capability, current_path, target_path, status, delete_in_pr, verification, notes

移行で変更するすべてのファイルを含める必要があります。これにより、見落とされるファイルを防ぎます。kindを使って、ドキュメント／設定／ツールを見えない付随作業にせず、第一級の項目として扱います。また、verificationには、成果物が引き続き有効であることを証明するコマンドまたはシナリオを記録します。

---

エージェントの連携

複数のエージェントや並行セッションを使用する場合：

1. 並行作業は、本当に独立したファイル群に限定します。 同じブランチで2つのエージェントがコミットすると、互いの作業が気付かないうちに上書きされることがあります。スライスの境界は、重複しないファイル群に対応させます。

2. CI の段階的な厳格化は、エージェントにとって最も扱いやすいガードレールです。 「安全な変更かどうか」の判断を求めるよりも、機械的な合否判定が優れています。

3. 拒否リストのパターンは、テストよりも確実にリグレッションを防ぎます。 「この関数名はこのディレクトリに出現してはならない」と判定する正規表現の CI チェックは、テストカバレッジが再導入を検出することに期待するよりも強力です。

4. 引き継ぎの契約は譲れません。 これがないと、コンテキストの圧縮によって、エージェントが完了済みの作業をやり直したり、残りの作業を飛ばしたりします。

5. 完了作業の取りまとめは、1つのスライスが担当します。 ファイル群が重複しない実装スライスは並行化しますが、最終的な残存項目の洗い出しとリリース判定は、1つの集約スライスが担当するようにします。

---

コード以外の領域

この方法論は、スクリプト、ドキュメント、ツール、設定など、コード以外の領域にも有効です。サイクルは同じです。棚卸し → 測定 → 凍結 → 段階的な解消。「同じ変更で削除する」という原則と、不要な残存物の一掃は、ドキュメントを統合したり、重複するスクリプトをなくしたりする場合にも同じように役立ちます。