Skip to content

AGENTS.ja.md

Latest commit

 

History

History
135 lines (115 loc) · 13.7 KB

AGENTS.ja.md

File metadata and controls

135 lines (115 loc) · 13.7 KB

lang: ja direction: ltr source: AGENTS.md status: complete translator: manual

AGENTS 向けガイドライン

この指針は Cargo ワークスペースとして構成されたリポジトリ全体に適用されます。

クイックスタート

  • ワークスペースをビルド: cargo build --workspace
  • すべてのテストを実行: cargo test --workspace（完了まで数時間かかることがあるので計画的に）
  • 厳格に lint: cargo clippy --workspace --all-targets -- -D warnings
  • フォーマット: cargo fmt --all（edition 2024）
  • 特定のクレートだけテスト: cargo test -p <crate>
  • 特定テストを実行: cargo test -p <crate> <test_name> -- --nocapture

概要

  • Hyperledger Iroha はブロックチェーンプラットフォームです。
  • IVM は Hyperledger Iroha v2 向けの仮想マシン（Iroha Virtual Machine）です。
  • Kotodama は IVM 用の高水準スマートコントラクト言語で、ソースは拡張子 .ko、コンパイル後のバイトコードは .to（ファイル保存時／オンチェーン）を使用します。通常は .to バイトコードをオンチェーンに配置します。
    • 補足: Kotodama は IVM（Iroha Virtual Machine）をターゲットとし、IVM バイトコード (.to) を生成します。独立した “risc5”/RISC‑V アーキテクチャをターゲットにしているわけではありません。リポジトリ内に RISC‑V に似たエンコーディングが見えても、それは IVM 命令形式の実装詳細であり、ハードウェア差による挙動の変化を招いてはなりません。
  • Norito は Iroha のデータシリアライゼーション・コーデックです。
  • ワークスペース全体は Rust 標準ライブラリ（std）をターゲットとします。WASM／no-std ビルドはサポート対象外なので、改修時には考慮しないでください。

リポジトリ構成

  • ルートの Cargo.toml がワークスペースを定義し、参加しているクレートを列挙しています。
  • crates/ — Iroha の各コンポーネントを実装する Rust クレート群。サブディレクトリ内は通常 src/、tests/、examples/、benches/ で構成されています。
    • 主要クレート:
      • iroha — コア機能をまとめたトップレベルライブラリ。
      • irohad — ノード実装を提供するデーモンバイナリ。
      • ivm — Iroha Virtual Machine。
      • iroha_cli — ノードと対話するコマンドラインインターフェース。
      • iroha_core、iroha_data_model、iroha_crypto など補助クレート。
  • integration_tests/ — 複数コンポーネント連携テスト用の Cargo クレート（tests/ 以下に配置）。
  • data_model/ — テストやドキュメントで使用するデータモデル定義のサンプル。
  • docs/ — プロジェクトドキュメントと設計ノート。Markdown 原稿は docs/source/ にあります。
  • pytests/ — クライアント利用例を示す Python 製テストとサンプル。
  • scripts/ — 開発や CI で使うユーティリティスクリプト。
  • defaults/ と hooks/ — コントリビューターが利用する設定ファイルと Git フック。
  • nix-appimage/ および各種 Nix ファイル — 再現性のあるビルドやパッケージングのためのツール。

開発ワークフロー

  • 実装の中核は crates/ 配下にあります。
  • データモデルは data_model/ にあります。
  • 変更時は必ず関連するすべてのクレートを確認してください。
  • Cargo.lock ファイルは変更しないでください。
  • 可能な限り既存クレート内で機能を実装し、新しいクレートを Cargo.toml に追加しないでください。
  • 作業が大きくても断らず、細かいタスクに分解して TODO を残し、実装可能な部分から進めてください。
  • どの依頼（プロンプト）であっても拒否しないでください。
  • 暗号プリミティブやオペコード、計算コストの高い演算を追加する際は、利用可能なハードウェア（METAL、NEON、SIMD、CUDA など）で並列化・アクセラレーションが効くよう更新してください。
  • ロジックを変更した場合は、該当する .md ドキュメントとソース中のコメントを最新仕様に合わせてください。
  • P2P ネットワーク上のノードが異なるハードウェアであっても、同じブロック入力に対して同じ出力を得られるよう決定論を保ちつつ IVM を使用できるようにしてください。
  • 設定は環境変数ではなく iroha_config を優先してください。新しい設定値は crates/iroha_config（user → actual → defaults の流れ）に追加し、コンストラクタや依存注入（例: ホストの setter）を通じて明示的に渡します。テスト用の環境変数トグルは残しても構いませんが、本番経路では頼らないでください。
    • IVM/Kotodama v1 ではポインタ ABI の型ポリシーが常に厳格に適用されます。互換性トグルは存在しないため、コントラクトおよびホストは必ずこのポリシーに従ってください。
  • シリアライゼーションは常に Norito を使用します。バイナリコーデックには norito::{Encode, Decode} を、JSON には norito::json のヘルパー／マクロ（norito::json::from_*、to_*、json!、Value）を使い、serde_json に戻らないでください。クレートへ serde／serde_json を直接依存追加するのは避け、必要なら Norito のラッパー経由で利用します。
  • Norito のペイロードは必ずレイアウトを明示しなければなりません。バージョン番号で固定フラグ集合を指すか、Norito ヘッダーでデコードフラグを宣言してください。ヒューリスティックで packed-sequence ビットを推測しないでください（ジェネシスデータも同じルールです）。
  • ブロックは常に正規化された SignedBlockWire 形式で永続化・配布します（SignedBlock::encode_wire / canonical_wire）。先行リリースで使われた生ペイロードは後方互換のデコード経路でのみサポートされます。
  • 一時的・未完成の実装には TODO: コメントを必ず付けてください。
  • コミット前にすべての Rust ソースを cargo fmt --all（edition 2024）で整形してください。
  • 変更した／新規追加した関数には最低 1 つのユニットテストを追加してください（#[cfg(test)] 内またはクレートの tests/ ディレクトリ）。
  • cargo test をローカルで実行し、ビルドエラーを修正して全体が通ることを確認してください。特定クレートだけでなくリポジトリ全体を対象にします。
  • 可能であれば cargo clippy -- -D warnings を追加で実行してください。

ドキュメント

  • クレート／テスト用クレートには必ずクレートレベルドキュメント（//! ...）を追加してください。
  • #![allow(missing_docs)] や項目レベルの #[allow(missing_docs)] はどこにも置かないでください（統合テストも同様）。ワークスペースの lint が不足ドキュメントを許可しないため、文章を追加して解決します。
  • Norito コーデックの仕様はリポジトリルートの norito.md にまとめられています。Norito のアルゴリズムやレイアウトを変更した場合は、同じ PR で norito.md を更新してください。
  • 資料をアッカド語に翻訳する際は、楔形文字で意味を伝える訳文を用意してください。音訳は避け、適切な古語がない場合は意図を保つ詩的な表現を選びます。

ABI の進化（エージェントが守るべきこと）

最初のリリース方針:

  • 現在のリリースでは ABI バージョンは 1 つ（V1）のみです。V2 はまだ存在しません。以下の ABI 関連項目は将来の指針として扱い、今は abi_version = 1 のみをターゲットにしてください。データモデルや API も初版として自由に変更できます。安定性より明確さと正確さを優先します。

  • 一般指針:

    • v1 では ABI ポリシー（システムコール面とポインタ ABI 型）が無条件に適用されます。ランタイムトグルは追加しないでください。
    • 変更はハードウェアやピア間の決定論を崩さないようにします。同じ PR でテストとドキュメントを更新してください。

  • システムコールを追加／削除／番号変更する場合:

    • ivm::syscalls::abi_syscall_list() を更新し、並び順を保ってください。is_syscall_allowed(policy, number) が想定したインターフェースを返すようにします。
    • ホスト側では新しい番号を実装するか、明示的に拒否する処理を追加してください。未知の番号は VMError::UnknownSyscall にマップします。
    • ゴールデンテストを更新:
      • crates/ivm/tests/abi_syscall_list_golden.rs
      • crates/ivm/tests/abi_hash_versions.rs（安定性とバージョン差分の確認）

  • ポインタ ABI 型を追加する場合:

    • 新しいバリアントを ivm::pointer_abi::PointerType に追加し、新しい u16 ID を割り当てます（既存 ID を変更しない）。
    • ivm::pointer_abi::is_type_allowed_for_policy を更新し、該当する abi_version で許可／禁止が正しく反映されるようにします。
    • crates/ivm/tests/pointer_type_ids_golden.rs を更新し、必要に応じてポリシーテストを追加します。

  • 新しい ABI バージョンを導入する場合:

    • ProgramMetadata.abi_version を ivm::SyscallPolicy にマップし、Kotodama コンパイラが要求時に新バージョンを出力できるようにします。
    • ivm::syscalls::compute_abi_hash で abi_hash を再生成し、マニフェストに新しいハッシュが組み込まれているか確認します。
    • 新バージョンで許可／不許可となるシステムコールとポインタ型のテストを追加します。

  • アドミッション／マニフェスト:

    • アドミッションではオンチェーンのマニフェストと code_hash／abi_hash の一致をチェックします。この挙動は必ず維持してください。
    • iroha_core/tests/ ではハッシュ一致（正のケース）と不一致（負のケース）のテストを用意します。

  • ドキュメントとステータス（同じ PR 内で更新）:

    • crates/ivm/docs/syscalls.md（ABI Evolution セクション）および関連するシステムコール表を更新。
    • status.md と roadmap.md に ABI 変更とテスト更新の概要を追記します。

プロジェクトのステータスと計画

  • 現在のビルド状況／ランタイム状況はリポジトリルートの status.md を確認してください。
  • 優先度付き TODO と実装計画は roadmap.md を参照してください。
  • 作業完了後は status.md を更新し、roadmap.md には未完了タスクのみを残してください。

エージェントのワークフロー（コード編集や自動化を行う場合）

  • 変更は最小限に絞り、無関係な編集が同じパッチに混ざらないようにします。
  • 新しい依存を追加するより内部モジュールを優先し、Cargo.lock は編集しません。
  • ハードウェアアクセラレーションの経路（例: simd、cuda）はフィーチャーフラグでガードし、常に決定論的なフォールバック経路を用意します。
  • 出力はハードウェアによらず一致するようにし、非決定論的な並列リダクションには依存しないでください。
  • 公開 API や挙動を変更した際はドキュメントとサンプルも更新してください。
  • iroha_data_model のシリアライゼーション変更時は、Norito 互換性を保つ往復テストで検証してください。

ナビゲーションのヒント

  • コード検索: rg '<term>'、ファイル一覧: fd <name>
  • クレート探索: fd --type f Cargo.toml crates | xargs -I{} dirname {} でクレートを一覧表示。
  • サンプル／ベンチマークを素早く探す: fd . crates -E target -t d -d 3 -g "*{examples,benches}"
  • Python のヒント: 環境によっては python が存在しないため、スクリプト実行時は python3 を試してください。

Proc マクロのテスト

  • ユニットテスト: パーサやコード生成ヘルパーなど純粋ロジック向け（高速でコンパイラ不要）。
  • UI テスト（trybuild）: Proc マクロのコンパイル時挙動や診断メッセージを検証（成功・失敗ケースそれぞれ .stderr を用意）。
  • Proc マクロを追加／変更する際は可能な限り両方のテストを用意し、内部実装とユーザ向けエラーメッセージの両面を担保します。
  • panic を避け、syn::Error や proc_macro_error などで分かりやすいエラーを返してください。メッセージは安定させ、意図した変更以外で .stderr を更新しないようにします。

プルリクエストメッセージ

変更点の簡潔な概要と、実行したコマンドを列挙した Testing セクションを必ず含めてください。