dsh-code-review

DeepSeek-Harness PR のレビュー

このスキルはガイダンスであり、完全なチェックリストではありません。 PR の最新のベースと正確なヘッドを確認して取得し、差分を読む前に pnpm --silent run change-scope --base <verified-base-ref> --head <verified-head-ref> を実行してから、設計を理解するために十分な周辺コードも読んでください。レポートは対象パスと変更の影響を受けるレイヤーを示しますが、意味的なレビューに取って代わるものではありません。ターゲット変更またはマージの後は、ベースを再確認して再実行してください。スタイルよりも正確性、ライフサイクル、セキュリティ、必須動作の破損を優先してください。根拠のあるブロッカーを1つ指摘する短いレビューのほうが、些細な指摘を並べるより優れています。

差分を評価する前に要件を読んでください。 変更されたパスを以下の成果物に対応付け、信頼できる情報源から各成果物の所有ページを開き、その要件と照らし合わせてから差分を読んでください。ルールの記憶だけを頼りに差分を評価すると、違反を見逃してしまいます。

信頼できる情報源

• AGENTS.md と packages/AGENTS.md：リポジトリおよびパッケージの恒常的な作成ルールです。
• docs/defensive-patterns/：変更が満たすべきアーキテクチャ要件と、その背景にある習慣です。各ページはそれぞれ1つの成果物を担当します。差分が触れるすべてのページを読んでください。
  • general.md — タイミング、非同期状態、値の表現、共有所有権、分散化、リファクタリング、移行、パフォーマンスの根拠、破棄、コールバック、サブプロセス。
  • package-surface.md — エクスポート、パッケージ構成、ビルド対象、依存関係の宣言、解決フック。
  • remote-and-api.md — リモートサービス、@Remote メソッド、API のディスパッチ、packages/api におけるビジネスロジックの所有権。
  • client-components.md — クライアントコンポーネント、スロット、ストア、フック、エフェクト、共有ベースパッケージ。
  • conversation-and-session.md — 投影の読み取り、Session の保持、会話ノード、レンダラー。
• docs/AGENTS.md：ドキュメントの配置と文章作成の規律です。
• dsh-prose-standard：コメント、ドキュメント、プロンプト、表示文字列に求められる網羅性と編集上の判断基準です。
• dsh-ci-test-reliability：リソースを所有するテスト、非同期テスト、不安定なテストおよびフィクスチャの分離と回帰防止のルールです。
• dsh-client-ui-ux：ユーザーへのフィードバック方法の選択、オーバーレイの安全性、プラットフォームのウィンドウへの適応、製品ユーザーに表示される GUI 変更におけるビジュアルトークンの規律です。
• dsh-error-handling：障害の分類、処理の所有権、封じ込め、状態の保証、実行可能な報告です。
• dsh-session-projection：投影の所有権、状態のサイズ、履歴の読み取り、移行です。
• docs/testing.md と 品質ゲートのリファレンス：必須のテスト段階とゲートです。
• エージェントノート：設計上の根拠です。エージェントノートとの相違は、即時の却下理由ではなく、設計に関する議論として扱ってください。
• バイリンガルの変更では、translation-rules.md と terminology.md を読んでください。拡張翻訳スキルは自動レビューの対象外で、ユーザーが明示的に呼び出した場合にのみ実行されます。

ブロッキング要件

1. 新しい文章には意味内容のレビューが必要です。 dsh-prose-standard を使用して、追加または変更されたすべての Markdown の文章、JSDoc、コメント、プロンプト、説明、診断メッセージ、表示文字列を批判的にレビューします。必須の網羅性、正確性、配置、編集品質を、該当するコードまたは動作と照らして確認してください。自動チェックでは、これらの特性は確認できません。
2. ドキュメントをコードに合わせます。 設定、デフォルト値、エラー、ワイヤーフィールド、イベント、公開動作を変更した場合は、同じ差分でパッケージの README と JSDoc も更新します。コメントには自明でない契約を記載します。実装の説明、テストの手順、レビュー履歴、重複する根拠は、削除するか、記載元へのリンクにするよう指摘してください。
3. コア型のドキュメントを一致させます。 spine または seam の用語を変更した場合は、該当する サブシステムのページと type-equiv の項目も更新します。内部型にはカタログ項目は不要です。
4. Cordis の所有権とクリーンアップ。 Cordis プラグインコード、またはそのエントリーポイントから到達可能なヘルパーをレビューする場合は、cordis-styling-nitpicking を読み込み、変更した動作と影響を受けるコンシューマーに適用します。P0 ルールの 3 項目（シングルトン状態、効果の未解除、コンシューマーが処理を終える前に解放されるクリーンアップ依存関係）を確認してください。新しいレジストリへの登録がそれぞれ、packages/AGENTS.md で必須とされる破棄テストに合格することを確認します。
5. 必須のエビデンスを確認します。 差分に関連する ローカルチェックを作成者が実行したこと、および CI が網羅的なマトリックスをカバーしていることを確認します。どちらでも検出できない意味上のギャップもレビューしてください。
6. クライアント UI の文言はロケールで管理します。 JSX、テンプレート、ヘルパーの戻り値、アクセシビリティ属性、プリミティブのデフォルト値に埋め込まれたプロダクト文言は却下します。型付き辞書キー、標準の t シートまたは明示的にローカライズされた props、verify-client-ui-i18n、および影響を受ける各ロケールでの動作エビデンスを必須とします。ユーザー、モデル、ワイヤーのデータとコードトークンは、原文のまま保持してください。

手動チェック

• 意図とインターフェース契約： 変更した各インターフェースの両側を追跡します。エラー、キャンセル、所有権、破棄を含め、実装が PR および Agent Note に沿っていることを確認します。
• エラー処理： 変更した失敗経路に dsh-error-handling を適用します。状態の保証と、最終的にユーザーに表示される報告も対象です。状態の所有者が、復旧後も含めて後続処理の前提条件が満たされると確認していない限り、エラーを捕捉して処理を続けることは認めません。
• ライフサイクルと並行処理： 非同期セットアップ、コールバック、プロセス、または終了処理には、defensive-patterns/general.md を適用します。公開前の競合、await 中のキャンセル、個別のエラー報告、コールバックの隔離、再入前の所有権、完全なデタッチ処理、静止状態での破棄を確認します。
• スコープ、所有権、必要性： 新たな区別、フィールド、アダプター、ステートマシン、オプション、防御的コピー、互換性経路のそれぞれについて、まず必要な動作を特定します。PR が導入した要件、チェック、Agent Note は評価すべき設計上の選択であり、必要性を示す独立した根拠ではありません。別の表現を受け入れる前に、既存のソースフィールド、判別子、その利用側を比較します。概念の削除と、その宣言位置の移動を区別してください。不要な概念を所有者の近くに移すことは簡素化ではありません。無関係な機能や推測的な汎用化には、ルートルールに照らして異議を唱えます。
• 機能と利用側との適合性： 現在の利用側をすべて追跡し、パッケージルールに基づいて、利用側固有の動作がインターフェースに漏れ出していないか指摘します。必要な動作については、ローカル実装の複雑さがほとんど増えない場合、既存の拡張ポイントを提供元または利用側の近くで優先します。その際、所有権ルールに従い、提供元が所有する宣言マージと、離れたコアまたは共有型宣言への変更を比較します。逆のケースも指摘します。汎用サービス（レジストリ、セッション、エージェント）に、その内部利用側だけが呼び出す新たな公開メソッドを追加することは、不要な API 拡張です。代わりに、構築時にその利用側へ渡すプライベートな機能クロージャーを求めます。
• 設定と公開上の選択： 新たな CLI または設定のパススルーを受け入れる前に、信頼できる値の読み取り元と優先順位を追跡します。転送された値が、使用前に上書きされることもあります。各デフォルト、公開操作セット、形式、インポートされた外部概念を裏付ける、現在の利用側の根拠や先行事例を確認します。その根拠がない場合は、明示的に選択するか、判断を保留するよう求めます。
• モデルの観点： 影響を受ける各モードで、モデルが受け取る正確なプロンプト、ツールスキーマ、結果、診断情報を確認します。モデルのタスク外の概念を指摘し、スナップショットまたはエンドツーエンドテストを通じて、固定テキストが一字一句維持されていることと、動的な動作を検証します。
• 強制適用： 拒否経路を、それが拒否する操作の実行箇所まで追跡します。スキーマ、プロンプト、ファサード、ラッパー、リスナーの順序を迂回できる、直接呼び出し元や別経路の呼び出し元をテストします。
• 借用状態と派生状態： 保持される各値がパッケージ契約上、借用か所有かを判断し、通知とすべてのキャッシュ、プロンプト、UI エコー、再生、クエリ表示について、文書化された成功点と信頼できるソースまで追跡します。
• 上限は最終操作に適用する： ラッパーやメタデータも含め、出力または保持される結果全体の所有者を特定します。バイト数の上限では、非常に小さい上限、上限ぴったりの値、上限を超える単一チャンク、マルチバイト文字列を検証します。
• 実際のエントリーパス： 関連する場合、テストでは配布される Loader、bin、ワーカー、ACP ブリッジ、またはサブプロセスを実行します。プラグインを手動でマウントしても、無効な Loader エクスポートは検出できません。関数プラグインは名前付きエクスポートで名前空間をエクスポートし、デフォルトエクスポートを持たない必要があります。
• テストの強度： アサーションが対象の回帰で失敗し、実装を言い換えたりエージェントの報告を信頼したりするのではなく、外部状態、ログ、イベント、または破棄を検証していることを確認します。カバレッジは必要ですが、シナリオが正しいことの根拠にはなりません。
• テストの信頼性： リソースを所有するテスト、非同期テスト、プラットフォーム依存のテスト、または不安定なテストには、実際のワーカー／ジョブ構成、リソース割り当て、グローバル状態の復元、同期、タイムアウトの予算、静止状態での終了処理を対象として dsh-ci-test-reliability を適用します。
• ネガティブコントロール： 変更した各受け入れルールについて、意図的に無効なケースが実際のランナーで失敗することを確認します。
• 実装済み Agent Note と配布時の実態の一致： PR が提案済み Agent Note を実装する場合、同じ差分内でそれを移動し、配布済みの状態を表す現在形に書き直します。その後、パス、名前、仕組みが実装と一致することを検証します。
• トランスクリプトの変更： エディター表示またはモデル表示に影響する変更では、スナップショットを更新するか、スナップショットが該当しない理由を説明します。期待出力の差分は、書式上のノイズではなく動作の変更としてレビューします。
• バイリンガルの変更： 両言語の意味と用語を比較します。ペアリングハッシュが一致していても、翻訳品質が保証されるわけではありません。

問題点の報告

不具合の内容、場所、影響、根拠を記載してください。局所的な不具合は、該当する差分のうち最も狭い範囲にインラインで指摘し、アーキテクチャ全体、スコープ、レビュー全体の総括については PR レベルのコメントを使用してください。ブロッカーと提案は分け、合格したゲートですでに検出されている問題は省いてください。返信には既存の GitHub レビュースレッドを使用してください。レビューを受けた場合は、各指摘を検証し、技術的な根拠に基づいて修正または反論してください。形式的に同意する必要はありません。