rust

Rust のベストプラクティス

Rust コードの作成、レビュー、リファクタリング、テスト、デバッグを行う際は、以下のガイドラインに従ってください。

作業の進め方

• まず、対象となるコード、テスト、Cargo.toml、ツールチェーンの固定設定、CI コマンドを確認してください。 プロジェクトのエディション、MSRV、フィーチャーの組み合わせ、規約を尊重してください。
• 対象のクレートで Bevy を使用している場合は、システム関数に一般的な借用、インポート、lint のアドバイスを適用する前に、Bevy のプラクティスを読んでください。
• アプリケーションコードは直接的に保ち、具体的な型とシンプルな制御フローを使い、推測に基づくトレイトやビルダーは使わないでください。外部から呼び出されるライブラリでは、パブリックな契約を慎重に定めてください。
• Rust の所有権、列挙型、トレイト、Result を使ってドメインをモデル化してください。他の言語の継承や例外のパターンを機械的に置き換えないでください。
• リファクタリングでは、変更が対象範囲に含まれない限り、パブリックシグネチャ、エラーのバリアント、出力順序、動作を維持してください。契約の変更が必要な場合は説明してください。スタイル上の好みだけを理由に、ゲッターの名前を変更したり、既存のパラメーターを置き換えたりしないでください。
• 読み取り専用のレビューでは、修正ではなく指摘事項を提示してください。依頼された変更の範囲を守ってください。このスキルによって、ツールのインストール、依存関係のアップグレード、公開が暗黙に求められることはありません。

タスク別のリファレンス

判断を行う前に、関連するリファレンスを読んでください。各トピックには詳細なルールと例が記載されています。タスクが別の領域にまたがる場合に限り、相互リンク先も確認してください。

タスク	リファレンス
借用チェッカーに関する問題、イテレーター、インポート、関数の抽出	コーディングのイディオム
Clippy の警告、抑制、ワークスペースの lint 設定	Clippy と lint
プロファイリング、アロケーション、クローン、ホットパス	パフォーマンス
失敗する可能性のある操作、ライブラリのエラー型、リソースのクリーンアップ	エラー処理
回帰テスト、プロパティテスト、統合テスト、スナップショットテスト、制御可能な I/O	テスト
クロージャーの境界、トレイトの契約、静的ディスパッチ、トレイトオブジェクト	ジェネリクスとディスパッチ
コンパイル時の状態遷移	型状態
コメント、パブリックドキュメント、実行可能な例	ドキュメント
ライフタイム、スマートポインター、内部可変性、共有所有権	ポインターと所有権
Tokio のタスク、チャネル、キャンセル、非同期の共有状態	Tokio による非同期処理
パブリック型、コンストラクター、標準トレイト、API の進化	API 設計
unsafe ブロック、raw ポインター、ネイティブハンドル、外部インターフェース	unsafe と FFI
Cargo マニフェスト、依存関係、フィーチャー、MSRV、no_std	クレートと依存関係
宣言的マクロ／手続き的マクロ、生成された API、展開時の診断	マクロ
キューに入れられたアクション、設定可能なアルゴリズム、AST の走査、ツリー変換	振る舞いのパターン
Bevy のシステム、クエリ、スケジューリング、遅延変更、ECS テスト	Bevy

コアルール

• 所有権は意図的に扱います。読み取りには借用し、消費する場合はムーブし、複数の所有者が必要な設計の場合に限り共有します。ディープコピーを追加する前に、借用のスコープを解決します。
• 型を使ってドメインの不変条件を表し、公開コントラクトを意図的に設計します。具体的なコードを優先し、実際に必要な場合にのみトレイト、ビルダー、マクロ、型状態を導入します。
• 失敗する可能性のある操作には Result、通常の不在には Option を返します。テスト以外では unwrap()／expect() を使いません。ライブラリのエラーには thiserror、バイナリには anyhow を使い、原因を保持して有用なコンテキストを追加します。通常のエラー処理としてパニックや catch_unwind を使いません。Drop でパニックを起こさないようにします。
• 所有権、アロケーション、ディスパッチ、同期を変更する前に、リリースビルドでパフォーマンスを測定します。制御フローをより明確に表現できる場合は、ループを維持します。
• ブロッキング I/O と負荷の高い CPU 処理を、非同期ワーカーで実行しないようにします。.await の前に同期ロックガードのスコープを終わらせます。その操作で必要な場合にのみ非同期同期機構を選びます。同時実行数を制限し、キャンセルに対応し、外部への呼び出しにはタイムアウトを設定します。
• unsafe コードは、小さく健全性が保証された境界内に置きます。各 unsafe 操作の不変条件を文書化し、すべての unsafe fn の # Safety に呼び出し元の義務を記載します。
• フォーマットと lint のポリシーを、プロジェクトおよび MSRV と互換性のあるものに保ちます。抑制は対象を絞って正当な理由を添え、ソース内で一律に #![deny(warnings)] を使うのではなく、CI で警告をエラーとして扱います。
• 失敗や境界条件も含め、観測可能な動作をテストします。バグは修正前に再現し、それぞれのコントラクトに応じてユニットテスト、統合テスト、ドキュメントテストを使います。
• 理由には //、API の使い方やコントラクトには ///／//! を使います。TODO は issue に紐づけ、必要に応じてエラー、パニック、安全性を文書化し、#![deny(missing_docs)] でライブラリのドキュメントを徹底します。失敗する可能性のあるドキュメント例は ? を使って実行可能に保ちます。

引き渡し前の検証

プロジェクトで指定されているコマンドと、サポート対象の機能／ターゲットのマトリックスを使います。コードを変更した場合は、フォーマットチェック、Clippy、関連するテストを実行します。公開 API やドキュメントを変更した場合は、ドキュメントテストと cargo doc --no-deps も実行します。新しい構文や依存関係が MSRV に適合することを確認します。unsafe、FFI、パフォーマンスに関する変更では、該当する Miri、プラットフォームテスト、リリースベンチマークも必要です。実際に実行した内容と制約事項を報告し、実行していないチェックに合格したと主張しないでください。