diagnostics-development について
Biome のルール、パーサー、サービス、インフラ向けに構造化診断を設計するスキルです。適切な診断 API の選択、問題・理由・対処法の整理、出力の検証を支援します。
主な機能
- 01RuleDiagnostic と単独型の選択
- 02メッセージ・マークアップ・ソース範囲の指針
- 03説明やアクションに使うアドバイス機構
- 04診断カテゴリと重大度の指針
- 05スナップショットとフィクスチャの検証項目
活用シーン
- 01lint または assist ルールの診断を設計
- 02パーサーや CLI 境界に構造化診断を追加
- 03強調範囲と対処アドバイスを確認
- 04条件付き診断メッセージをテスト
インストール
コマンドをコピーしてターミナルで実行します。
npx skills add https:/インストール後、Claude Code で/diagnostics-developmentを入力して読み込まれたか確認します。
詳細
診断の開発
API と設計の規範として crates/biome_diagnostics/CONTRIBUTING.md を使用してください。アドバイスの種類や derive の形を選ぶ前に、同じサブシステムの既存の診断を確認してください。
診断 API の選択
Lint ルールと assist ルールには RuleDiagnostic を使用してください。パーサー、サービス、CLI、設定、またはインフラストラクチャの境界で独自の構造化診断が必要な場合は、Diagnostic を derive する独立した型を使用してください。
1 行の lint メッセージをラップするだけの独立した型は導入しないでください。位置情報、サブ診断、条件付きアドバイスを含む複雑な診断を、所有型のほうが契約を明確に表現できる場合に RuleDiagnostic のチェーンへ無理に押し込まないでください。
3 つの質問
完全な診断は、次の問いに答えます。
- どのような状態が見つかりましたか？
- なぜそれが重要ですか？
- ユーザーは何をすればよいですか？
それぞれの役割を分けてください。
- 主メッセージは状態を特定します。
- 注記または詳細は、結果や根拠を説明します。
- アクション、差分、コマンド、または最後のアドバイスは、次の手順を示します。
根拠と修正方法を、曖昧な文章にまとめないでください。自動アクションがある場合、通常は注記で繰り返すのではなく、アクションのラベルで修正方法を示します。
メッセージとマークアップ
- 構文上の構成要素だけでなく、実際の問題に名前を付けてください。
- ユーザーが問題を理解する助けとなる、最小限のソース範囲を強調してください。
- 値は
markup!に直接補間してください。先にformat!で割り当てないでください。 - 走査しやすくなる場合は、ソース内の用語や設定値を強調してください。
- 主メッセージは短く保ち、説明はアドバイスに記載してください。
- 実装で裏付けられない結果を断定しないでください。
アドバイスの選択
ユーザーが必要とする情報に基づいてアドバイスを選択してください。
| 必要な情報 | 方法 |
|---|---|
| 説明または次の手順 | 注記またはログアドバイス |
| 関連するソース範囲の提示 | 詳細またはコードフレームアドバイス |
| 正確なテキスト変更の提示 | 差分アドバイスまたはコードアクション |
| 実行するコマンドの提示 | コマンドアドバイス |
| 任意で追加のコンテキストを提示 | 詳細アドバイス |
問題の場所を文章で説明するより、ソース内の根拠を優先してください。同じ事実を別の言葉で繰り返す注記を複数追加しないでください。
独立した診断
#[derive(Diagnostic)] では、サポート対象の属性について、最新のガイドと derive の実装を確認してください。一般的に確認すべき項目は次のとおりです。
- 重大度とカテゴリ
- 主メッセージとプレーンテキストの説明
- 場所のパス、ソース、範囲
- アドバイスと詳細アドバイス
- 修正可能、不要、非推奨、内部などのタグ
診断型は、報告境界で必要となる安定したデータを所有します。範囲と構造化された値で十分な場合は、大きなソースバッファーを保持したり、レンダリング済み文字列を割り当てたりしないでください。
カテゴリ
生成された診断カテゴリレジストリを手作業で編集しないでください。カテゴリを担当するルールのスキャフォールディングまたはジェネレーターを使用し、生成されたエントリとドキュメント URL を確認してください。
ルール以外の診断では、変更を加える前に、近接するカテゴリと現在のコード生成元を確認してください。生成ファイルからワークフローを推測しないでください。
重大度
確立されたサブシステムの方針に合わせてください。重大度は運用上の影響を伝えるものであり、メッセージに対する作者の感情の強さを示すものではありません。異なる重大度やタグを導入する前に、近接する診断と最新のコントリビューションガイドを確認してください。
検証
- 診断をレンダリングする、最小範囲のテストまたはフィクスチャを追加してください。
- スナップショットで、メッセージ、アドバイスの順序、マークアップ、パス、強調範囲を確認してください。
- 条件付きアドバイスは、すべての分岐でテストしてください。
- オフセットを手動で計算する場合は、範囲の前後にあるトリビアやマルチバイト文字を含めてテストしてください。
- lint 診断では、ルール固有のフィクスチャに
lint-rule-developmentとtesting-codegenを読み込んでください。
レビューのチェックリスト
- 主メッセージで、何が問題なのかを示しています。
- アドバイスで、理由と具体的な次の手順を説明しています。
- 強調表示する範囲が最小限かつ適切です。
- 構造化マークアップを使用し、事前フォーマット済み文字列の割り当てを回避しています。
- 選択した API が診断の複雑さに適しています。
- カテゴリーの変更には、サポートされているソースまたはジェネレーターを使用しています。
- スナップショットテストで、すべての条件付きメッセージやアドバイスのパスを確認しています。
参考資料
- 診断ガイド：
crates/biome_diagnostics/CONTRIBUTING.md - 診断トレイト：
crates/biome_diagnostics/src/diagnostic.rs - アドバイス API：
crates/biome_diagnostics/src/advice.rs - 既存の derive の例：
#[derive(Diagnostic)]を検索してください