HDL 最小修復と整合性チェック
HDL デザインバグを修正するための最小限の安全なパッチを生成し、その後、修正がハードウェア契約を破ったり、成果物間の不整合を残さないことを検証するワークフロー。
このスキルがカバーする範囲
このスキルは、2 つのスキルからなるパイプライン(ローカライゼーション → 修復)の修復部分です。2 つのエントリパスを受け入れます。
- 根本原因仮説ノート付き(
hdl-fault-localizationまたは同等のものから)— ノートを解析し、最良の仮説を選択して処理を進めます。 - 既存の修復意図あり— ユーザーまたは事前のエージェントが既に特定のバグの場所、修正方針、またはパッチ差分を指定している場合、その意図を暫定仮説に昇格させて処理を進めます。
このスキルは、以下の 4 つのことのみを行い、それ以外は行いません。
- 最小限のパッチ計画 — 選択された仮説に対処するための最小限の変更セット。無関係な変更は含みません。
- 副作用スキャナ — ハードウェア契約ペア(ready/valid、リセット/フラッシュ/リプレイ、FSM 遷移、古い状態、パイプライン順序)をチェックします。
- アーティファクトリンクチェッカ — 設定ファイル、生成ファイル、レジスタ記述、ジェネレータスクリプトの一貫性を維持します。
- テスト検証 — テストスイートを実行し、フォールバック仮説を介して失敗を処理します。
このスキルはフォールトローカリゼーションを実行しません。バグがローカライズされていない場合は、停止して最初にローカライゼーションを要求します。
このスキルを使用するタイミング
このスキルは、問題が既にローカライズされている場合にのみアクティブになります。以下のいずれかが存在すれば、エントリするのに十分です。
- 根本原因仮説ノートが提供されている(
hdl-fault-localizationまたは同等のものから)。 - ユーザーまたは事前のエージェントが、明示的なバグの場所(ファイル、モジュール、信号)と修正方針(何を、なぜ変更するか)を指定している。
- ユーザーが明確な修復意図を述べている(例:「このポインタを広げる」「スキッドバッファを追加する」「FSM 遷移を修正する」)。
- 既存のパッチ差分があり、副作用や整合性についてレビューする必要がある。
これらのエントリシグナルのいずれも存在しない場合 — バグがローカライズされておらず、仮説もなく、昇格させる特定の修復意図もない — 停止し、最初にローカライゼーションを要求します。 バグの診断を試みないでください。それは別のフォールトローカライゼーションスキルの責任です。「このバグを修正して」「何かがおかしい」「テストベンチが失敗する」といった、ローカライズ情報なしの漠然とした要求はエントリシグナルではありません — このスキルの修復のみの範囲に必要な具体性が欠けています。
典型的なトリガーフレーズ:「修正を適用する」「パッチを作成する」「修復を実装する」「このパッチの副作用をチェックする」「この変更後のハードウェア契約を検証する」「成果物間の整合性を監査する」。
入力要件
開始する前に、以下の少なくとも 1 つが存在している必要があります。存在しない場合は、停止して最初にローカライゼーションを要求します。
- 根本原因仮説ノート — 1 つ以上の仮説を、それぞれ証拠の強さと根拠とともに記述したファイルまたはインラインテキスト。これが推奨される入力であり、
hdl-fault-localizationによって生成されます。 - 明示的なバグの場所 + 修正方針 — ユーザーまたは事前のエージェントが特定のファイル、モジュール、または信号を特定し、どのような変更を行うかを説明している。この修復意図を暫定仮説に昇格させます。
- 既存の修復意図 — 記述された計画(例:「ポインタを 4 ビットから 5 ビットに広げる」)。これを単一仮説ノートとして扱うことができます。
- 既存のパッチ差分 — 副作用とアーティファクトの整合性をレビューするための提案されたコード変更。
さらに、以下を収集します。
- 関連するソースファイル — 関連する HDL モジュール、テストベンチ、およびサポートコードへのパス。
- テストコマンド — テストスイートを実行するための正確なコマンド。
- 失敗ログ — オプションですが、コンテキストに推奨されます。
コアワークフロー
以下の手順を順番に実行します。各ステップは、次のステップにフィードする出力を生成します。
ステップ 0:エントリゲートチェック(コード分析の前)
ソースファイル、ログ、または波形を読み取る前に、ユーザーのメッセージに少なくとも 1 つのエントリシグナルが存在することを確認します。以下の順序でチェックします。
- 根本原因仮説ノート(ファイルパス、インライン YAML、またはラベル付けされた仮説と証拠を持つ構造化テキスト)はありますか?
- ユーザーは具体的なバグの場所と修正方針を指定しましたか(特定のファイル、モジュール、または信号と、どのような変更を行うかの説明 — 「修正して」や「何かがおかしい」だけではありません)?
- ユーザーは具体的な修復意図を述べましたか(例:「ポインタを 5 ビットに広げる」「スキッドバッファを追加する」「FSM 遷移を A から B に変更する」)?
- レビューするための既存のパッチ差分はありますか?
これらのいずれも存在しない場合 — ユーザーが「このバグを修正して」「テストベンチが失敗する」「何かがおかしい」などの漠然とした要求のみを行い、ローカライゼーションがない場合 — 直ちに停止します。 ソースコードを読まないでください。バグの診断を試みないでください。以下を出力します。
このスキルは事前のローカライゼーションが必要です。最初にフォールトローカリゼーション(hdl-fault-localization)を実行するか、以下のいずれかを提供してください。
- 根本原因仮説ノート
- 明示的なバグの場所(ファイル/モジュール/信号)と修正方針
- 特定の修復意図(何を、なぜ変更するか)
- レビューする既存のパッチ差分
エントリシグナルが存在することを確認した後、ステップ 1 にのみ進みます。
ステップ 1:修復仮説の確立
正式な根本原因仮説ノートが利用可能な場合、それを解析して以下を抽出します。
- 各仮説、ラベル付けおよび説明。
- 各仮説を支持する証拠(強い、中程度、弱い)。
- 各仮説の推奨される修正方針。
- 仮説間のフォールバック順序または依存関係。
ノートに複数の仮説が含まれている場合、すべてをリストアップします。1 つのみ含まれている場合、選択は簡略化されますが、それでもコミットする前にその証拠の強さを評価します。
仮説ノートが提供されていないが、修復意図(明示的なバグの場所 + 修正方針、記述された修復計画、または既存のパッチ差分)が存在する場合、その意図を暫定仮説に昇格させます。ラベル(例:「P1-sync-fifo-pointer-widen」)を付け、ユーザーの説明からそれを支持する証拠を文書化します。この暫定仮説は、ステップ 2 ~ 7 の唯一の仮説として扱われます。代替仮説を生成したり、フォールトローカリゼーションを実行したりしないでください — このスキルの範囲は修復の実行で終了します。
ステップ 2:最初にパッチを適用する最良の仮説の選択
すべての仮説が等しいわけではありません。以下の選択基準を適用します。
- 証拠の強さ — 具体的な証拠(波形トレース、ログパターン、再現可能な条件)を持つ仮説を、推測的なものより優先します。
- パッチのリスク — 修正がローカライズされている(1 つまたは 2 つのモジュール、構造変更なし)仮説を、広範な書き換えが必要なものより優先します。
- 可逆性 — パッチが機能しない場合に元に戻しやすい仮説を優先します。
- 依存関係の順序 — 仮説 B が仮説 A が正しいことに依存している場合、最初に A にパッチを適用します。
代替案よりもこの仮説を選択した理由を文書化します。同じくらい強い 2 つの仮説の間で決定できない場合は、パッチリスクが低い方を選択し、もう一方を主要なフォールバックとしてメモします。
ステップ 3:最小限のパッチ計画の生成
「最小限のパッチ」とは「1 つのファイルのみを変更する」という意味ではありません。意味は、選択された仮説に正しく対処するための最小限の変更セットであり、無関係な変更は含まれません。
変更を計画する各ファイルについて、以下に答えます。
- このファイルを変更する必要があるのはなぜか? — 仮説からこの特定の変更に至る因果関係の連鎖をトレースします。
- 正確には何が変わるのか? — 実装の詳細ではなく、信号/ロジックレベルで変更を説明します。
- なぜこれが最小限の変更なのか? — より小さな変更では不十分であり、より大きな変更が不要である理由を説明します。
以下の変更は拒否します。
- 表面的なもの(フォーマット、名前変更、バグに関係のないコメントの更新)。
- リファクタリング(「ついでに、これをクリーンアップしておこう」)。
- テストをパスさせるためのテスト期待値のハードコーディング。
- テスト自体が間違っているという証拠なしにテストファイルを変更すること。
ステップ 4:副作用スキャナの実行
ハードウェアデザインには、信号間の暗黙の契約があります。契約の一方を変更すると、多くの場合、もう一方が壊れます。パッチを適用する前に、これらの契約違反をスキャンします。
ready/valid ペア
変更されたモジュールとその直接の隣接モジュール内のすべての ready/valid ハンドシェイクペアについて:
- パッチは
validがアサートまたはデアサートされるタイミングを変更しますか?もしそうなら、コンシューマーのreadyロジックはまだ正しく動作しますか? - パッチは
readyがサンプリングまたは駆動されるタイミングを変更しますか?もしそうなら、プロデューサーのvalidロジックはまだ意味をなしますか? - バックプレッシャーはまだ正しく処理されていますか — パイプラインはデータをドロップせずにストールできますか?
リセット/フラッシュ/リプレイ
すべてのリセット、フラッシュ、またはリプレイ信号について:
- パッチは、リセット時にクリアまたは保持される状態を変更しますか?
- フラッシュパスは、インフライトデータを正しくドレインまたは無効化しますか?
- リプレイパスは、状態を正しいチェックポイントに復元しますか?
FSM 遷移の完全性
パッチによって影響を受けるすべての有限状態マシンについて:
- すべての状態がリセットから到達可能ですか?
- FSM はデッドロックする可能性がありますか(状態からの有効な出口がない)?
- FSM はライブロックする可能性がありますか(進行なしで状態間の無限ループ)?
- パッチは状態遷移を追加または削除しますか?もしそうなら、新しい遷移テーブルが完全であることを確認します。
古い状態
- パッチは、トランザクション間またはクロックサイクル間で、クリアされるべきときに古い値を保持できるレジスタまたは信号を導入しますか?
- パッチは、正しく発火しなくなったメカニズムによって信号がクリアされることに依存していますか?
パイプライン順序
- パッチはパイプライン内の操作の順序を変更しますか?もしそうなら、下流のステージは依然として期待される順序でデータを受信しますか?
- パッチはパイプラインの深さを変更しますか(ステージの追加または削除)?もしそうなら、すべてのバイパスおよびフォワーディングパスは調整されていますか?
結果が「問題なし」であっても、各カテゴリの調査結果を文書化します。
ステップ 5:アーティファクトリンクチェッカの実行
HDL プロジェクトには、HDL ソースと同期を保つ必要がある設定ファイル、レジスタマップ、および生成コードが含まれることがよくあります。以下のリンクをチェックします。
設定ファイル
パッチによって影響を受ける信号、パラメータ、またはモジュールを参照する設定ファイル(YAML、HJSON、JSON、TOML、INI など)をスキャンします。パッチがパラメータ値、モジュール名、またはポートリストを変更する場合は、設定を一致するように更新します。
生成ファイル
プロジェクト内のファイルが(コードジェネレータ、スクリプト、またはビルドステップによって)自動生成されているかどうかを確認します。パッチがジェネレータに供給するソースを変更する場合は、以下のいずれかを行います。
- 出力ファイルを再生成する。
- 手動での再生成のために不整合をフラグする。
レジスタ記述
デザインにレジスタマップ(CSV、XML、IP-XACT、SystemRDL など)が含まれている場合、パッチ後にレジスタフィールドの位置、幅、アクセスタイプが HDL からずれていないかをチェックします。
ジェネレータスクリプト
HDL または設定ファイルを生成する Python、Perl、Tcl、またはシェルスクリプトをチェックします。パッチがこれらのスクリプトが依存するパターン(命名規則、信号幅、インターフェイスプロトコル)を変更する場合、スクリプトは壊れた出力を生成する可能性があります。
チェックされたすべてのアーティファクトと、見つかった不整合を文書化します。
パッチが内部ロジックのみを変更する場合(パブリックインターフェイス、パラメータ、レジスタフィールド、アドレスマップ、生成ソース、または設定から見える動作を変更しない)、アーティファクトリンクチェックは「該当なし — 成果物間の影響がない内部のみのパッチ」に縮小されます。変更によって影響を受ける可能性がないアーティファクトについて、プロジェクトツリー全体をスキャンすることは避けてください。パッチが上記のサーフェスのいずれかに触れる場合にのみ、完全なアーティファクト検索を実行します。
ステップ 6:パッチの適用とテストの実行
実際のソースファイルにパッチを適用します。その後、テストコマンドを実行します。
- テストスイートを 1 回実行します。
- すべてのテストに合格した場合 — 結果を文書化し、ステップ 7 に進みます。
- 一部のテストが失敗した場合 — 分析します。
- 失敗は既存のものですか? 失敗ログをチェックして、これらのテストがパッチの前に失敗したかどうかを確認します。既存の失敗はパッチのせいではありません — メモしますが、修正をブロックしないでください。
- 失敗はパッチによって引き起こされましたか? パッチが新しい失敗を導入した場合、修正は不完全または不正確です。フォールバックパスに進みます。
- 失敗はテストのバグを明らかにしていますか? この結論に達するのは、テスト期待値が間違っているという具体的な証拠がある場合のみであり、パッチが動作を変更したからという理由だけではありません。
ステップ 7:失敗の処理 — 次の仮説へのフォールバック
パッチがテストに失敗した場合(パッチによって引き起こされたものであり、既存のものやテストのバグではない場合):
- アドホックな微調整でパッチを救おうとしないでください。 それは仮説駆動型の修正を当て推量に変えてしまいます。
- 実行環境がクリーンなロールバックをサポートしている場合(例:
git checkout、git stash、またはパッチ状態を管理する外部ハーネス)、フォールバックを試みる前に失敗したパッチを元に戻します。ロールバックがサポートされていない場合、続行する前に明示的に失敗した編集を検査して元に戻します — 壊れたパッチの上に新しいパッチを重ねないでください。 - 仮説ノートから次の仮説を選択します(証拠とリスクの組み合わせが次に良いもの)。
- パッチ決定ノートに文書化します:どの仮説が失敗したか、なぜか(どのテストが壊れたか)、そして現在どの仮説が試行されているか。
- フォールバック仮説でステップ 2 に戻ります。
すべての仮説を使い果たしても、テストに合格するパッチがない場合は、仮説セットが不十分であると報告します — 根本原因が仮説のいずれにも捕捉されていない可能性があります。
出力:パッチ決定ノート
ワークフローの最後に(パッチが成功したか失敗したかにかかわらず)、以下の正確な構造を使用してパッチ決定ノートを生成します。
patch_decision_note:
selected_hypothesis: <パッチが適用された仮説>
patch_scope: <パッチが何を変更するかの 1 文の要約>
modified_files:
- <ファイルパス>: <このファイルを変更する必要があった理由>
- <ファイルパス>: <このファイルを変更する必要があった理由>
side_effect_scan:
ready_valid_pairs: <パス/フェイル/該当なし + 簡単な説明>
reset_flush_replay: <パス/フェイル/該当なし + 簡単な説明>
fsm_transitions: <パス/フェイル/該当なし + 簡単な説明>
stale_state: <パス/フェイル/該当なし + 簡単な説明>
pipeline_ordering: <パス/フェイル/該当なし + 簡単な説明>
artifact_link_check:
config_files: <パス/フェイル/該当なし + 簡単な説明>
generated_files: <パス/フェイル/該当なし + 簡単な説明>
register_descriptions: <パス/フェイル/該当なし + 簡単な説明>
generator_scripts: <パス/フェイル/該当なし + 簡単な説明>
test_results:
command: <実行された正確なテストコマンド>
passed: <合格したテストの数>
failed: <失敗したテストの数>
new_failures: <パッチに起因する新しい失敗の数(該当する場合)>
pre_existing_failures: <パッチ前に存在した失敗の数(該当する場合)>
outcome: <SUCCESS | FAILED_WITH_FALLBACK | ALL_HYPOTHESES_EXHAUSTED>
fallback_hypothesis: <使用されたフォールバック仮説(該当する場合)、または NONE>
このノートにより、後続のワークフロー(ハードウェア契約の検証、アーティファクト監査、人間のレビューを含む)は、何が行われたか、なぜ行われたかを正確に把握できます。