adopt-better-result

Adopt better-result

まず根拠を確認し、次にユーザーが指定した範囲で作業します。

分岐を選択する

• 監査ブランチ： リポジトリ全体の監査や提案をユーザーが求めている場合、または実装範囲を指定していない場合に使用します。本番コードを変更する前に、監査ブランチを完了してください。
• 指定範囲ブランチ： ユーザーが関数、モジュール、境界、または以前に提案した範囲の実装を明示的に求めている場合に使用します。根拠の収集は、その範囲と呼び出し経路に限定してください。

監査ブランチで承認された範囲は、指定範囲ブランチに引き継がれます。

監査ブランチ：リポジトリ全体の提案

1. リポジトリと API の事実を確認する

リポジトリの指示、パッケージマニフェスト、ソースレイアウト、テストコマンド、アーキテクチャドキュメントを読みます。better-result がインストールされているか、どのバージョン／API を利用できるかを確認します。記憶上の API より、インストール済みの型とソースを優先してください。

個々の障害を調査する前に、本番コードのすべての領域を把握します。監査では生成コードとベンダーコードを除外し、意図された動作を確認するためにテストを調べます。

完了条件： 本番コードのすべての領域が列挙され、検証コマンドが判明し、利用可能な better-result API が検証されていること。

2. 本番コードのすべての領域を監査する

references/repository-audit.md に従います。検索で得られた根拠をエンドツーエンドの障害経路まで追跡し、グループ化した箇所は件数で管理し、見えない経路は不明として記録します。

監査結果は、リポジトリで定められたドキュメントまたは計画用の場所に記録します。該当する場所がない場合は、docs/better-result-adoption.md を使用します。

完了条件： レポートが repository-audit.md の網羅性と完了要件を満たしていること。

3. 目標モデルを設計する

references/tagged-errors.md の障害分類を適用し、references/result-boundaries.md を使って各境界の判断を行います。提案する処置、ユーザー向けのマッピング、境界の判断、優先順位を付けた垂直移行範囲をレポートに追加します。

最初に取り組む範囲を推奨し、その範囲が限定的でありながら価値がある理由を説明します。

完了条件： カタログ化したすべての障害に処置が定められ、すべての境界でエンコード／デコードの判断が記録され、最初に取り組む範囲が1つ推奨されていること。

4. 承認ゲートを提示する

レポートと推奨内容を提示します。監査ブランチでリポジトリに加える変更は、レポートのみです。

完了条件： レポートが提示されていること。1つの指定された垂直移行範囲が明示的に承認された場合は、実装ブランチを開始します。それ以外の場合は、ここで実行を終了します。

指定範囲ブランチ：実装

1. 範囲と API の事実を確認する

リポジトリの指示、検証コマンド、インストール済みの better-result API、関連する本番コードとテストを読みます。指定された障害の発生源から、直近の呼び出し元を経て、処理または転送の境界まで追跡します。既存の導入レポートがあれば再利用し、なければ根拠を実装の要約に記録します。

完了条件： 範囲の境界、現在の動作、障害の種類、呼び出し元、副作用、転送境界を把握し、利用可能な API を検証していること。

2. 垂直移行範囲を1つ実装する

references/vertical-slice-migration.md に従い、障害の処置には references/tagged-errors.md を、境界の契約には references/result-boundaries.md を使用します。実装は、指定された呼び出し経路内に限定してください。

完了条件： 障害の発生源から選択した処理境界までの経路が一貫して Result ベースであり、すべてのエラー種類が処理され、すべての制御フローの接続点が考慮されていること。

3. 検証して報告する

リポジトリに該当するフォーマット、lint、型チェック、および関連テストのコマンドを実行します。既存の導入レポートがあれば、完了した作業、逸脱、発見事項、検証の根拠を更新します。なければ、それらをユーザー向けの概要に記載します。次に取り組む範囲を提案して終了します。

完了条件： 該当するすべてのチェックに合格するか、失敗した場合はすべて根拠を添えて報告し、レポートまたは概要でリポジトリの現在の状態を正確に説明していること。