pma-rust

Rust プロジェクト実装・受け入れガイド

このスキルは /pma と併用してください。/pma はワークフロー、承認、タスク追跡を管理し、このガイドはすべての PMA-Rust プロジェクトにおける製品品質の受け入れ基準を定めます。

このスキルではバージョンを指定しません。すべてのクレート、ツールチェーン、エディション、ベースイメージには、レジストリで確認した最新の安定版を使用します（/pma references/workflow.md の Dependency Freshness を参照）。references/evidence.md に記載されたバージョンは根拠であり、目標ではありません。

厳守事項

references/baseline.md の Hard Locks に定義されています。これを緩和する場合は、同ファイルの Known Trade-offs セクションに従います。これらが適用されていない場合、/pma は実装承認を拒否します。

1. 成熟したクレートを優先します。純粋な Rust は必須ではありませんが、すべてのリリース対象でビルドできる必要があります
2. rustls のみを使用し、main() で aws-lc-rs プロバイダーをインストールします
3. すべてのクレートルートに #![forbid(unsafe_code)] を設定します
4. 警告の拒否は CLI ではなく [workspace.lints] で設定します
5. MSRV を宣言し、CI で検証します
6. ランタイムパスで unwrap / expect / panic! を使用しません
7. 最新の安定版エディションを使用します
8. マージ前に品質ゲートを通過させます（references/delivery.md）

模範プロジェクトの基準

すべての推奨事項は、クローンして検証した10のプロジェクト（cargo、rust-analyzer、reth、vector、tokio、axum、linkerd2-proxy、uv、ruff、quickwit）のファイルと行番号を示す根拠に基づいています。引用は references/evidence.md に記載されています。

読み込み順

必ず最初に references/baseline.md を読み込んでください。その後、タスクに関連するパックを読み込みます。

1. references/baseline.md — 厳守事項、技術スタック、命名、コード品質（常に必須）
2. references/toolchain-and-workspace.md — ワークスペースの構成、エディション、[workspace.lints] とビルドフラグの使い分け、ツールチェーンの固定、開発ループ用ツール
3. references/runtime-and-data.md — Axum + tower + tokio ランタイム、IntoResponse によるエラー処理、SQLx/SeaORM/Diesel の選定、階層化された設定、グレースフルシャットダウン
4. references/delivery.md — セキュリティ、シークレット、OTLP オブザーバビリティ、テストレイヤー、サプライチェーン（cargo-deny/cargo-shear/typos）、リリース自動化、CI
5. references/evidence.md — 根拠を示す引用（スキルの検証または拡張時に読み込み）

すばやい参照先

タスクの対象…	読み込むファイル
新しいワークスペース、Lint、ツールチェーン、開発ツール	toolchain-and-workspace.md
Axum/tower のハンドラー、DB アクセス、設定、シャットダウン	runtime-and-data.md
テスト、CI、オブザーバビリティ、リリース、シークレット、サプライチェーン	delivery.md
「このルールがあるのはなぜか？」／「X がベストプラクティスだと示す根拠は？」	evidence.md
その他すべて（常に）	baseline.md

受け入れチェックリスト（PMA ゲート）

/pma が Rust クレートまたはサービスを本番環境向けとして受け入れる前に、以下を確認します。

• ワークスペースで最新の安定版 edition と rust-version を宣言している
• すべてのクレートに #![forbid(unsafe_code)] を設定している（または例外を文書化している）
• CI で以下を実行している：fmt ＋ ワークスペース全体の deny-warnings ポリシーを適用した clippy ＋ nextest ＋ --doc テスト ＋ cargo-deny ＋ cargo-shear（または machete）＋ typos ＋ MSRV チェック（cargo hack check --rust-version または cargo msrv verify）
• 推移的依存関係に openssl／native-tls が含まれていない（cargo deny bans で確認）
• すべての TLS で rustls を使用している。aws-lc-rs プロバイダーを main の早い段階でインストールしている（標準スニペット：references/baseline.md Lock 2）
• 本番環境で JSON フォーマッターを使って Tracing を初期化している。OTLP は任意
• サービスに /livez（ライブネス）と /readyz（レディネス）のエンドポイントがある
• axum::serve(...).with_graceful_shutdown(...) ＋ CancellationToken（または同等のもの）でグレースフルシャットダウンを実装している
• シークレットを secrecy::SecretString／SecretBox<T> でラップしており、Debug 形式で出力していない
• 設定をデフォルト値 → ファイル → 環境変数 → CLI の順に重ね合わせ、マージ後に検証している
• クレートごとに型付きエラー（thiserror）を使用している。anyhow／eyre はバイナリーのエントリーポイントでのみ使用している
• リリースパイプラインが再現可能である：タグ → CI → 署名済みバイナリー（cargo-dist またはカスタム）
• プロジェクトがポータブルな CLI バイナリーを配布する場合、配布用バイナリーを *-unknown-linux-musl ＋ +crt-static でビルドしている（ldd の出力が「not a dynamic executable」であることを確認）
• CLI バイナリーを配布する場合、サイズを最適化するオプション（lto=fat、codegen-units=1、panic=abort、strip=symbols）を指定した [profile.dist] を定義している
• コンテナーのベースイメージを意図をもって選び、docs/decisions/ に文書化している：運用上のニーズ（最小限のランタイム、デバッグのしやすさ、glibc への依存、企業指定のベース、マルチアーキテクチャ）に応じて選択します。固定のサイズ目標はありません。適切なサイズは、選択したベースとバイナリーに必要なサイズです
• 到達可能なすべてのレイヤーでコアダンプを抑制している — main の早い段階でプロセス内の rlimit::setrlimit(Resource::CORE, 0, 0) を常に設定し、環境に応じて systemd の LimitCORE=0／コンテナーの --ulimit core=0:0／K8s の読み取り専用 rootfs／カーネルの kernel.core_pattern = \|/bin/false も設定している
• main にパニックフックを設定し、ランタイムが異常終了する前にバックトレース付きの構造化された tracing::error! を出力している。本番ログで、事後解析用のコアダンプを代替します

いずれかの項目を満たさない場合、プロジェクトは本番環境に対応できる状態ではありません。