Beautiful Rust — скиллы, которые учат ИИ-агентов писать идиоматичный Rust

Beautiful Rust — набор из трёх agent skill и одного конфига clippy. Он учит ИИ-агентов писать, ревьюить и переносить в Rust правильный идиоматичный код. Скиллы работают с Claude Code, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI и любым другим агентом, который понимает формат Agent Skills. Каждый пример кода внутри скиллов компилируется на стабильном Rust, а каждое правило в конфиге проверено на текущей версии clippy.

Что входит в набор

• rust-best-practices — подключается всякий раз, когда агент пишет или меняет Rust-код, и ведёт его к устойчивому и поддерживаемому коду.
• rust-review — ревьюит существующий Rust-код: файл, крейт или diff. На выходе — отчёт по приоритетам, где каждая находка ссылается на нарушенное правило и показывает исправление.
• rust-port — переносит код с C, C++, Python, Go или JavaScript на идиоматичный Rust с тем же поведением. Сначала переносятся оригинальные тесты, чтобы можно было доказать совпадение.
• lints/ — готовый конфиг clippy, который держит машинно-проверяемые правила под контролем в CI.

Ставить нужно все три скилла: ревью и перенос опираются на скилл лучших практик как на источник стиля.

Правила не придуманы с нуля. Они собраны из пяти источников, и рядом с каждым лежит сжатый пересказ, чтобы агент мог заглянуть в исходную логику:

• Google Rust Style Guide
• Rust API Guidelines — официальный чек-лист rust-lang
• Effective Rust Дэвида Драйсдейла
• Rust Design Patterns — идиомы, паттерны и антипаттерны
• Pragmatic Rust Guidelines от Microsoft

Если источники противоречат друг другу, скилл выбирает одну сторону и объясняет почему.

Что меняется на практике

Автор попросил агента написать маленькую библиотеку для разбора semver. Без скилла агент выдал работающий код с публичными полями, без секции # Errors в документации и с unwrap() в примерах. Тот же агент со скиллом спрятал поля, описал режимы отказа и написал примеры, которые можно спокойно копировать.

// Without the skill
/// A semantic version. The fields are public for convenience.
pub struct Version {
    pub major: u64,
    pub minor: u64,
    pub patch: u64,
    pub pre: Vec<Identifier>,
    pub build: Vec<String>,
}

impl Version {
    /// Parses a version string.
    ///
    /// S0S1S2
    pub fn parse(s: &str) -> Result<Version, ParseError> { /* ... */ }
}

// With the skill
/// A semantic version. Equality, hashing, and ordering ignore build metadata.
pub struct Version {
    major: u64,
    minor: u64,
    patch: u64,
    pre: Vec<Identifier>,
    build: Vec<String>,
}

impl Version {
    /// Parses a version string according to SemVer 2.0.0.
    ///
    /// # Errors
    ///
    /// Returns [S0] if the string is empty, a numeric part has a
    /// leading zero or overflows S1, or an identifier contains invalid characters.
    ///
    /// S2S3S4
    pub fn parse(s: &str) -> Result<Self, ParseVersionError> { /* ... */ }

    /// Returns the major version number.
    pub fn major(&self) -> u64 { self.major }
}

Установка

Каждый скилл — это папка внутри skills/. Все способы установки просто кладут эти папки туда, где их ищет ваш агент.

Универсальный вариант — установщик skills, поддерживающий большинство агентов (нужен Node 22.20+):

npx skills add morganlinton/BeautifulRust

Флаг -g ставит скиллы для пользователя, -a <agent> выбирает агента, например -a codex или -a cursor.

Claude Code — установка как плагина:

claude plugin install beautiful-rust --marketplace morganlinton/BeautifulRust

GitHub Copilot — через GitHub CLI 2.90+:

gh skill install morganlinton/BeautifulRust rust-best-practices
gh skill install morganlinton/BeautifulRust rust-review
gh skill install morganlinton/BeautifulRust rust-port

Gemini CLI:

gemini skills install https://github.com/morganlinton/BeautifulRust --path skills/rust-best-practices
gemini skills install https://github.com/morganlinton/BeautifulRust --path skills/rust-review
gemini skills install https://github.com/morganlinton/BeautifulRust --path skills/rust-port

Остальные агенты — скопировать папки руками. Большинство агентов теперь читают общий каталог .agents/skills/:

git clone https://github.com/morganlinton/BeautifulRust
mkdir -p ~/.agents/skills
cp -R BeautifulRust/skills/rust-* ~/.agents/skills/

Claude Code каталог .agents/skills/ не читает — используйте его собственный каталог или плагин. Если скиллы не появились сразу, перезапустите агента.

Ревью существующего кода

Попросите агента: «review src/parser.rs» или «что бы ты поменял в этом PR». Скилл rust-review при наличии тулчейна сам запускает cargo fmt, clippy и тесты, затем пишет отчёт с тремя уровнями: must fix, should fix и consider. У каждой находки есть позиция file:line, ссылка на нарушенное правило с его источником — например код C-GETTER из API Guidelines, пункт Effective Rust, guideline Microsoft или линт clippy — и минимальное исправление. Отчёт всегда заканчивается тем, что в коде уже сделано хорошо.

Реальный пример такого отчёта — review-inventory.md: ревью нарочно запутанного модуля из тестовых сценариев.

Перенос кода в Rust

Попросите агента: «port parser.c to Rust» или «перепиши этот Python-сервис на Rust». Скилл rust-port читает оригинал вместе с тестами, сначала переносит тесты, затем проектирует Rust API, а не транслитерирует исходник, и в конце проверяет результат через cargo test и clippy.

Скилл знает, как перевести привычки каждого языка в Rust-эквиваленты: NULL и None превращаются в Option, коды ошибок и исключения — в enum ошибок, выходные параметры — в возвращаемые значения, флаги-числа и магические строки — в типизированные enum и опции. Даже порядок вставки в dict сохраняется через упорядоченную коллекцию, потому что обычный HashMap молча перемешал бы вывод. К каждому переносу прилагается PORTING.md: таблица соответствий старых и новых API и тестов плюс список всех осознанных отличий.

Принуждение к правилам через clippy

Скиллы учат правилам, а линты не дают им расползаться. Скопируйте clippy.toml рядом с вашим Cargo.toml и вставьте блок [lints] из lints.toml, затем запускайте:

cargo clippy --all-targets --all-features -- -D warnings

Конфиг ловит unwrap() вне тестов, блоки unsafe без комментария // SAFETY:, #[allow] без объяснения, любые булевы параметры функций, молчаливые потери данных в приведениях as, отсутствие секций # Errors и # Panics в документации, а также забытые dbg! и todo!. Линты с пометкой [lib] нужны только библиотекам — приложения могут их убрать.

Каждый линт в таблице проверен: отдельный крейт содержит ровно одно намеренное нарушение на каждый линт, а скрипт из корня репозитория доказывает, что все они срабатывают:

bash scripts/check-lints.sh

Скрипт падает, если линт перестал срабатывать, если сработало что-то лишнее или если копия таблицы в проверочном крейте разошлась с lints/lints.toml. Линтам allow_attributes и allow_attributes_without_reason нужен rust-version = "1.81" или новее: clippy отключает их для крейтов, которые не могут использовать #[expect].

Что покрывает скилл написания кода

skills/rust-best-practices/SKILL.md — это примерно 500 строк, устроенных так, чтобы агент мог быстро находить нужное во время работы:

1. Мышление: код в духе Rust, невалидные состояния невыразимы, приложение против библиотеки.
2. Чек-лист перед сдачей: fmt, clippy с -D warnings, тесты, документация.
3. Владение и заимствование: что делать вместо клонирования, чтобы угодить borrow checker.
4. Типы и дизайн API: имена, newtype-обёртки, общие трейты, билдеры, видимость, генерики против dyn.
5. Ошибки и паники: Option против Result против паники, типы ошибок для библиотек и приложений.
6. Повседневные идиомы: итераторы, комбинаторы, format!, импорты, drop-стражи.
7. Конкурентность и async: проверки Send, дисциплина блокировок, async fn, точки уступить потоку.
8. Unsafe и FFI: когда это допустимо, комментарии SAFETY:, корректность, bindgen.
9. Крейты, модули, зависимости: структура workspace, фичи, semver.
10. Документация и комментарии.
11. Тесты.
12. Производительность, по порядку важности.
13. Финальный чек-лист.

В references/ лежит отдельный пересказ каждого из пяти источников для глубоких справок.

Насколько это работает

В репозитории лежат тестовые сценарии в формате claude plugin eval: задача на дизайн библиотечного API, задача на CLI-приложение и задача «отрефактори этот модуль». Каждый сценарий содержит промпт, описание хорошего результата и по одному утверждению на файл.

Сравнение запускали с и без скилла. Скилл написания кода прошёл 29 из 30 проверок против 24 из 30 без него — ценой примерно трети лишних токенов на задачу. Скилл ревью прошёл 11 из 12 против 7 из 12, скилл переноса — 22 из 22 против 19 из 22. Это реальные запуски модели, и они стоят денег.

Лицензия и источники

Репозиторий распространяется под лицензией MIT (LICENSE). Все пять источников правил — опубликованные руководства с открытой лицензией, и каждое правило в скиллах обязано иметь источник. Правила предложить, сообщить о ложном срабатывании ревью или добавить тестовый сценарий можно по CONTRIBUTING.md; история версий ведётся в CHANGELOG.md.