effect-review-v4

Effect v4 のレビュー

プログラムの動作と、プログラムが公開する契約をレビューします。カスタムのキャンセル、スケジューリング、リソース管理、協調ロジックを取り除ける場合は、Effect のプリミティブを優先してください。意味上の利点を説明してください。Effect API の数はコード品質の指標ではありません。

ユーザーから修正も依頼されている場合を除き、このスキルは読み取り専用で使用してください。このスキル自体のレビューや改善を求められた場合は、その指示と例を確認し、プロダクトコードの監査は開始しないでください。

**デフォルトではレビュー担当者は 1 人（現在のエージェントのみ、サブエージェントは 0 人）**とし、リポジトリ全体の監査も同様とします。セクション 3 の委任とコンテキストの制限に従ってください。

1. 対象範囲と事実関係を確認する

指摘を行う前に、version-grounding.md と該当するリポジトリの指示を読んでください。

• 明示されたファイル／ディレクトリ、PR、ブランチ、過去の会話を尊重します。「私の変更」は通常、作業中の変更があればそれを指し、なければ現在のブランチの実際のベースを調査します。推定した対象範囲を明示してください。レビューに重大な影響を与える曖昧さが解消されない場合に限り、確認を求めてください。
• PR／ブランチ：実際のベースを特定し、マージベースとの差分と関連する呼び出し元を調査します。作業中の変更：ステージ済み、未ステージ、および関連する未追跡ファイルを含めます。差分が空でもコマンドの失敗ではありません。HEAD~1 を黙ってレビューしないでください。
• リポジトリ：生成物／依存関係／参照用ツリーを除外し、第一者ソースを特定します。.context は API の根拠資料であり、レビュー対象のプロダクトコードではありません。
• 拡張子だけでなく、内容と所有者に基づいて分類します。index.ts、設定ファイル、.tsx、.spec.*、型テストには、重要な Effect の動作が含まれる場合があります。契約を追跡する際は、間接的な利用者とランタイムアダプターも含めます。
• 実際のパッケージ解決とパッチを特定します。このスキルの例は、テスト済みバージョンについての根拠であり、異なるインストール済みバージョンに対する権威ではありません。

任意で読み取り専用のインベントリヘルパーを使用できます（実際のパスを指定してください）。

node <skill>/scripts/inspect-project.mjs --project <repo> --mode working
node <skill>/scripts/inspect-project.mjs --project <repo> --mode diff --base <actual-base>
node <skill>/scripts/inspect-project.mjs --project <repo> --mode repo

ヘルパーは候補と除外対象を一覧表示しますが、意味上のレビュー範囲を網羅すると保証するものではなく、PR のベースを特定するものでもありません。ユーザーが指定したパスに絞り、関連する非ソースの契約も読んでください。

2. 関連する動作を追跡する

過去に提案された修正が安全でなかった条件について、known-pitfalls.md を読んでください。そのうえで、関連する経路を追跡します。

入力 → スキーマ → サービス → ドライバー／リソース → エラーマッピング → 利用側 → テスト

スタイル変更を提案する前に、Effect を使用する処理について、エラーとライフタイムの両面から確認してください。該当する懸念がある場合は、ほかのリファレンスも参照してください。

懸念事項	リファレンス
想定される失敗、欠陥、中断、復旧、公開契約	errors-and-cause.md
リソーススコープ、ファイバー、キャンセル、状態、バックプレッシャー	resources-concurrency.md
プリミティブの選択、HTTP、リトライ、キャッシュ、ポーリング、データ変換	primitives.md
遅延構築、ジェネレーター、トレーシング、Promise 相互運用	effect-fn-and-gen.md
依存関係、レイヤーの取得／メモ化、設定	services-layers.md
デコード／構築／エンコード、オプショナリティ、ブランド	schema.md
トレース／ログ／メトリクスのコンテキスト、ステータス、エクスポートのライフタイム	observability.md
Atom の同一性、ランタイムの所有権、非同期状態、無効化	effect-atom.md
動作アサーション、クロック、レイヤー、型付き失敗	test-patterns.md

カスタムの仕組みごとに、既存の Effect プリミティブまたはリポジトリの抽象化で置き換えられるか検討します。提案する前に、API の利用可能性、ライフタイム、失敗／キャンセルのセマンティクス、パフォーマンス、影響を受ける呼び出し元を確認してください。短いコンビネータチェーン、ローカル変数、網羅的な switch、ネイティブ境界のアダプターが、最も明確で正しい実装である場合もあります。

3. デフォルトでは1人のエージェントでレビューする

委任の予算はデフォルトでゼロです。ユーザーが並列レビューまたは独立したエージェントによるレビューを明示的に求めた場合に限り、サブエージェントは合計2人まで使用できます。 リポジトリの規模、ファイル数、利用可能な枠、徹底的な監査の依頼があっても、委任は許可されません。日常的にエージェントの追加を求めず、ローカルで作業を続けてください。ユーザーが明示的により多い人数を指定した場合は、ホストのルールに従うことを条件に、この上限を変更できます。ユーザーまたはホストがより少ない上限を定めている場合は、常にその上限が適用されます。

• 上限は同時に稼働するエージェント数や各ラウンドの数ではなく、レビュー全体に適用されます。再利用したエージェントを含め、委任したレビュー担当者はそれぞれ数えてください。別の懸念事項、フェーズ、再試行、検証のために予算をリセットしてはいけません。
• 再帰的な委任は禁止です。委任されたレビュー担当者は、全員単独で作業する必要があります。ファイル、懸念事項、指摘、または分割した対象と懸念事項の組み合わせごとにエージェントを割り当ててはいけません。
• メインレビューとの重複を避けられる、範囲が限定された独立した作業だけを委任してください。別々のサブシステムを割り当てるか、独立した確認が求められている場合は、未解決の具体的な主張を割り当ててください。統合と最終検証はメインのレビュー担当者が行います。検証担当の第2チームを自動的に編成してはいけません。
• 簡潔なタスクを送り、担当パス、確認済みのバージョンやパッチ、適用される規約、関連する参照パス、期待する結果を指定してください。会話全体、スキルや参照資料の全体、差分、リポジトリ全体を各プロンプトにコピーしないでください。対応している場合は、履歴を引き継がない独立したコンテキストを選択してください。短いプロンプトだけでは、ホストが会話全体を引き継がない保証にはなりません。レビュー担当者は、証拠として担当範囲外の呼び出し元を読んでもかまいません。
• 確認済みの指摘、必要な証拠、重要な網羅性の不足を報告するよう依頼してください。報告は通常600語以内とします。再現手順が長い場合はファイル参照を使い、ソースを繰り返し貼り付けたり、確認したすべてのファイルについて逐一説明したりしないでください。
• 予算を使い切った場合やレビュー担当者が失敗した場合は、残りの作業をローカルで進めてください。既存のレビュー担当者を再利用するのは、具体的な確認事項が不足している場合に限ります。完了済みのレビューを再開したり、上限を回避するために代替エージェントを追加したりしてはいけません。

関連するパスはまとめて一度確認し、該当する懸念事項をまとめて適用してください。確認済みのバージョンやポリシーの証拠を短いメモに記録し、関連する参照セクションだけを読み込んでください。大規模な監査では簡潔な網羅性台帳を使い、証拠の追加が必要な場合を除き、確認済みの範囲を再読せずに順番に進めてください。依頼された確認範囲と重要な検証を維持し、実際に確認できなかった点があれば報告してください。特定のツール、モデル、トークン計測機能が利用できると想定したり、計測せずにトークン節約量を主張したりしてはいけません。

4. 検証して報告する

review-protocol.md に従ってください。任意の提案も含め、提案するすべてのAPIについて、バージョンに適合する証拠が必要です。重要な指摘には、具体的な発生条件、裏付けとなる肯定的な証拠、および指摘を否定しようとした検証が必要です。

次の3種類の出力を分けてください。

• 正確性： 観察可能な失敗、失われた保証、または実証されたコスト。
• リポジトリのポリシー： 適用されるローカル要件と、その出典への引用。
• 任意の簡素化： 動作を維持したまま、より明確なプリミティブの使用を提案するもの。構文が異なるというだけでブロッキングな不具合として扱ってはいけません。

コメントは意図の証拠ですが、免責にはなりません。安全でない修正案は、実在するバグへの反証にはなりません。未解決の主張は格下げした指摘にせず、未解決の質問として記載してください。実行結果やソースの証拠が得られない場合は、不確実性を維持してください。

影響の大きい確認済みの指摘から順に、場所、発生条件、影響、ルール、証拠、修正の方向性とリスク、検証結果を記載してください。対象範囲、確認範囲、実施したチェックも含めてください。任意の改善案は簡潔にし、分けて記載してください。確認済みの不具合がない場合は、重要な確認範囲の制限とともに、その旨を明記してください。内容のないカテゴリ見出し、数値による準拠スコア、ファイルのランキングは記載しないでください。

このスキルのメンテナンス

完全な TypeScript の例は、examples/README.mdと隣接するソースファイルにあります。検証されていない GOOD ブロックに重複して記載しないでください。 これらの例には、安全でないパターンが失敗する理由を示すネガティブコントロールテストが含まれています。Node とプロジェクトにインストール済みの依存関係を使って、scripts/check-examples.mjs --project <repo>を実行してください。パッケージのインストールやアップグレードは行いません。

API／ランタイムに関するガイダンスや依存関係を変更した場合は、該当するソースとパッチを確認し、関連する例を実行してください。指示のみを変更した場合は、メタデータ、リンク、一貫性を確認してください。エージェントやベンチマーク全体を自動的に起動しないでください。 レビュー動作の比較を依頼された場合は、総委任予算を同じにしてevals/evals.jsonを使用してください。通常のコードレビューでは、このスキルのメンテナンス評価を実行しません。 evals/README.mdを参照してください。スナップショットや結果は、すべてのスキル検出ルートの外に保管してください。たとえば、~/.agents/skill-workspaces/effect-review-v4です。 ~/.agents/skills内にSKILL.mdを含むバックアップは、このスキル自身のディレクトリ外にあっても、別のインストール済みスキルとして検出されることがあります。