rust-cli-agent-style

OpenAI Codex Rust CLI エージェントのベストプラクティス

このスキルでは、50 個のクレートと 787 個の Rust ファイルで構成される、本番環境向けの CLI／エージェントシステムである OpenAI Codex コードベースのスタイルで Rust コードを書く方法を学びます。

主な特徴

• Edition 2024 と厳格な Clippy 設定
• テスト以外のコードでは unwrap／expect を一切使用しない（ワークスペースレベルで適用）
• 適切な Send + Sync 境界を持つ Tokio 非同期ランタイム
• ライブラリエラーには thiserror、アプリケーションコードには anyhow
• 依存関係を一元管理する フラットなワークスペース構成

適用する場面

次の場合にこのスキルを適用してください。

• Rust で CLI ツールやエージェントシステムを構築する
• Tokio を使って非同期 Rust を記述する
• Rust ワークスペースの構成を設計する
• エラー処理のパターンを実装する
• 本番環境向けの Rust コードベースを扱う

クイックリファレンス

重要なルール（必ず守ること）

ルール	説明
err-no-unwrap	テスト以外のコードでは unwrap() を絶対に使用しない
err-no-expect	ライブラリコードでは expect() を避ける
err-thiserror-domain	ドメインエラーには thiserror を使用する
err-context-chain	.context() を使ってエラーにコンテキストを追加する

エラー処理

ルール	説明
err-anyhow-application	エントリーポイントには anyhow::Result を使用する
err-from-derive	エラー変換には #[from] を使用する
err-transparent	ラップされたエラーには #[error(transparent)] を使用する
err-structured-variants	エラーのバリアントに関連データを含める
err-io-result	I/O 関数には std::io::Result を使用する
err-map-err-conversion	エラー変換には map_err を使用する
err-doc-errors	エラー条件をドキュメントに記載する

構成

ルール	説明
org-workspace-flat	utils サブディレクトリを含むフラットなワークスペース
org-crate-naming	ディレクトリには kebab-case を使用し、プロジェクトの接頭辞を付ける
org-module-visibility	内部 API には pub(crate) を使用する
org-test-common-crate	テストユーティリティを共有するクレート
org-integration-tests-suite	suite ディレクトリにテストを配置する
org-feature-modules	機能ベースでモジュールを構成する
org-handlers-subdir	専用のサブディレクトリにハンドラーを配置する
org-errors-file	専用ファイルにエラーを定義する

コンポーネントパターン

ルール	説明
mod-derive-order	derive マクロの順序を統一します
mod-async-trait-macro	非同期トレイトには #[async_trait] を使用します
mod-trait-bounds	並行処理を行うトレイトには Send + Sync + 'static を指定します
mod-extension-trait-suffix	拡張トレイトには Ext サフィックスを付けます
mod-builder-pattern	複雑な設定には Builder パターンを使用します
mod-type-alias-complex	複雑なジェネリクスには型エイリアスを使用します
mod-impl-block-order	impl ブロックの順序を統一します
mod-generic-constraints	複雑な境界条件には where 句を使用します
mod-newtype-pattern	型安全性のために Newtype を使用します
mod-struct-visibility	フィールドを非公開にし、公開コンストラクターを用意します
mod-serde-rename	wire format には Serde の rename を使用します
mod-jsonschema-derive	API 型には JsonSchema を使用します

命名規則

ルール	説明
name-async-no-suffix	非同期関数に _async サフィックスを付けません
name-try-prefix-fallible	失敗する可能性のあるコンストラクターには try_ プレフィックスを付けます
name-with-prefix-builder	ビルダーメソッドには with_ プレフィックスを付けます
name-handler-suffix	ハンドラーには Handler サフィックスを付けます
name-error-suffix	エラー型には Error サフィックスを付けます
name-result-type-alias	クレート固有の Result エイリアスを使用します
name-const-env-var	環境変数定数には _ENV_VAR サフィックスを付けます
name-request-response	Request/Response 型をペアにします
name-options-suffix	設定のまとめには Options サフィックスを付けます
name-info-suffix	読み取り専用データには Info サフィックスを付けます
name-provider-suffix	サービスには Provider サフィックスを付けます
name-client-suffix	API クライアントには Client サフィックスを付けます
name-manager-suffix	ライフサイクル管理には Manager サフィックスを付けます
name-bool-is-prefix	ブール値には is_/has_/should_ を使用します
name-plural-collections	コレクションには複数形の名前を使用します

スタイル

ルール	説明
style-import-granularity	use 文ごとに項目を1つだけ指定します
style-deny-stdout	ライブラリで stdout/stderr を禁止します
style-inline-format-args	format 引数をインライン化します
style-module-docs	モジュールレベルのドキュメントを記述します
style-expect-reason	lint には理由を添えて #[expect] を使用します
style-cfg-test-module	単体テストは mod tests に記述します

クレート間

ルール	説明
cross-workspace-lints	ワークスペースレベルの lint 設定
cross-workspace-deps	依存関係のバージョンを一元管理します

例：適切なエラー処理

use thiserror::Error;
use anyhow::Context;

// Domain error with thiserror
#[derive(Debug, Error)]
pub enum ConfigError {
    #[error("failed to read config file: {path}")]
    ReadFailed {
        path: PathBuf,
        #[source]
        source: std::io::Error,
    },

    #[error(transparent)]
    Parse(#[from] toml::de::Error),
}

// Library function returns domain error
pub fn load_config(path: &Path) -> Result<Config, ConfigError> {
    let content = fs::read_to_string(path)
        .map_err(|source| ConfigError::ReadFailed {
            path: path.to_owned(),
            source,
        })?;
    toml::from_str(&content).map_err(Into::into)
}

// Application code uses anyhow with context
fn main() -> anyhow::Result<()> {
    let config = load_config(Path::new("config.toml"))
        .context("failed to load configuration")?;
    run(config).await
}

出典

OpenAI Codex（codex-rs/ サブディレクトリ）から抽出したパターンです。50 個のクレートと 787 個の Rust ファイルで構成される、本番環境で使用されている Rust コードベースです。