Library Development Standards

高品質で汎用性が高く、メンテナンスしやすい Rust ライブラリを構築するための設計思想と指針。この文書は、新たな知見が得られるたびに更新・進化し続けるものである。

1. 抽象代数的アプローチによる設計 (Abstract Algebraic Design)

特定の型（i64 等）やそのドメイン（定義域）への依存を排除し、計算に本質的に必要な「代数的性質」のみを要求する。

•ドメイン依存からの脱却: From<i64> を避ける本質的な理由は、型 T が「整数そのもの」であるという強い仮定を排除することにある。これにより、ModInt、行列、多項式、ベクトル空間といった「整数ではないが、加法やスカラー倍の性質を持つ抽象的な対象」を同じインターフェースで扱えるようにする。
•
「変換」から「作用・系内部の演算」への転換:
- •スカラー倍の作用 (Mul<i64>): $n$ 倍の計算が必要な場合、整数 $n$ を T に「変換」して掛けるのではなく、T に対して整数 $n$ が「作用（スカラー倍）」できることを要求する。これにより、型 T の正体が何であるかではなく、どのように振る舞うかに焦点を当てる。
- •系内部での単位元生成 (Sum): 0.into() のように外部の値を持ち込むのではなく、代数系が持つ演算ルール（Sum 等）から単位元を導き出す。これにより、T が数値概念から切り離された抽象的な構造であっても、その系内部で完結した処理が可能になる。
•インターフェースの純粋化: 型の「ドメイン（何であるか）」ではなく「能力（何ができるか）」に基づいてトレイト境界を定義し、利用可能な型の集合を最大化する。

対になる概念（最小/最大、正/負など）を扱うファイル群は、ミラー構造を維持する。

•クローン構造の追求: 行数、空行の位置、インポートの順序、メソッドの定義順を完全に一致させることで、「実装対象の違い」のみを浮き彫りにする。
•メンテナンス性の同期: symmetry-syncer スキルを用い、スタイル上のノイズを徹底的に排除する。これにより、一方への修正（バグ修正や機能追加）を、構造を壊すことなく機械的かつ安全に他方へ適用可能にする。

cargo-snippet で展開されるコードの依存グラフを最小限に保ち、不要な依存の波及を防止する。

•コア実装の隔離: ベースとなるスニペット（例: mod_ext_int）には、その機能に本質的に必要な依存のみを含める。
•拡張機能の外出し: 特定の外部トレイト（Bounded 等）の実装などは、mod_xxx_bounded のように別スニペットとして定義する。これは、拡張機能を追加するためにコア実装に「依存スニペット」を増やさないためであり、利用者がベース機能だけを最小の依存で利用できるようにするためである。

•知見の集約: ライブラリ開発を通じて得られた新たな知見や、設計上の失敗、より優れた抽象化手法を発見した際には、速やかにこの lib-dev-standards を更新し、プロジェクト全体の設計品質を底上げする。

リファクタリング等により型、関数、定数などのシンボル名を変更した際は、それに関連するテストコードの命名も一貫性を持って同期させる。

•テスト名の同期: 型名 OldType を NewType に変更した場合、対応するテスト関数 test_old_type_behavior も test_new_type_behavior へと改称することを常に検討する。
•一括置換の徹底: 「一括置換」の指示があった場合、対象は PascalCase の型名だけでなく、スネークケースで書かれた関連するテスト名や変数名も含まれると解釈し、プロアクティブに整合性を保つ。
•意図の確認: 命名の乖離が設計上の意図（例：特定のインターフェース名をテスト名に残したい等）によるものか、単なる更新漏れかを判断し、不明な場合はユーザーに確認する。

抽象代数系（特に無限大を含む系）における演算子実装の標準パターン。

•無限大と 0 の乗算: Z-加群としての作用を模す場合、原則として $ \infty \times 0 = 0 $ と定義する。これは「無限大を 0 回足した結果は単位元である」という解釈に基づく。
•ドメイン外の入力とパニック: 演算の引数が型の定義域や代数系の前提（例：非負整数倍を想定している箇所に負の数）を外れる場合は、妥協して結果を返すのではなく、速やかに panic! させる。