BeautifulRust

Beautiful Rust
코딩 에이전트가 관용적인 Rust를 작성, 리뷰, 포팅, 강제하도록 가르치는 세 가지 표준 Agent Skill과 lints 설정:

rust-best-practices는 에이전트가 Rust를 작성하거나 변경할 때마다 로드되어, 관용적이고 견고하며 유지보수 가능한 코드로 이끕니다.
rust-review는 기존 Rust 코드, 파일, 크레이트 또는 diff를 리뷰하고, 모든 발견 사항이 위반한 규칙을 인용하고 수정 방법을 보여주는 우선순위 리포트를 작성합니다.
rust-port는 C, C++, Python, Go, JavaScript를 동일한 동작의 관용적 Rust로 포팅하며, 원본 테스트를 먼저 포팅하여 두 구현이 일치함을 증명할 수 있게 합니다.
lints/는 CI에서 기계적으로 검사 가능한 규칙을 강제하는 드롭인 clippy 설정입니다.

이들은 Claude Code, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, 그리고 Agent Skills 형식을 읽는 다른 모든 에이전트와 함께 작동합니다. 스킬의 모든 코드 예제는 stable Rust에서 컴파일되며, 설정의 모든 lint는 현재 clippy에 대해 검증되었습니다.

가이던스는 다섯 가지 출처에서 정제되었으며, 각 출처의 축약된 다이제스트가 스킬에 포함되어 있어 에이전트가 필요할 때 원본 근거를 참조할 수 있습니다:

Google Rust Style Guide
Rust API Guidelines (공식 rust-lang 체크리스트)
David Drysdale의 Effective Rust
Rust Design Patterns (관용구, 패턴, 안티패턴)
Microsoft Pragmatic Rust Guidelines

출처가 서로 다를 경우, 스킬은 한쪽을 선택하고 그 이유를 설명합니다.

무엇이 달라지는가
작은 semver 파싱 라이브러리를 요청했을 때, 스킬이 없는 에이전트는 public 필드, # Errors 문서 없음, doc 예제에 unwrap()이 있는 동작하는 코드를 생성했습니다. 스킬이 있으면 같은 에이전트가 필드를 private으로 유지하고, 실패 모드를 문서화하며, 사용자가 안전하게 복사할 수 있는 doc 예제를 작성했습니다. 두 실행에서 축약한 내용:

// 스킬 없이
/// 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.
///
/// ```
/// let v = Version::parse("1.2.3").unwrap();
/// ```
pub fn parse ( s : & str ) -> Result < Version , ParseError > { /* ... */ }
}
// 스킬 사용
/// 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 [`ParseVersionError`] if the string is empty, a numeric part has a
/// leading zero or overflows `u64`, or an identifier contains invalid characters.
///
/// ```
/// # use semver_lite::Version;
/// # fn main() -> Result<(), semver_lite::ParseVersionError> {
/// let v = Version::parse("1.2.3-beta.1")?;
/// assert_eq!(v.major(), 1);
/// # Ok(())
/// # }
/// ```
pub fn parse ( s : & str ) -> Result < Self , ParseVersionError > { /* ... */ }

/// Returns the major version number.
pub fn major ( & self ) -> u64 { self . major }
}
세 가지 테스트 작업(라이브러리, CLI, 지저분한 모듈 리팩터링)에서 스킬은 30개 검사 중 29개를 통과했고, 없을 때는 30개 중 24개를 통과했습니다. Testing the skills를 참고하세요.

설치
각 스킬은 skills/ 아래의 폴더입니다: rust-best-practices/, rust-review/, rust-port/. 아래의 모든 옵션은 해당 폴더를 에이전트가 스킬을 찾는 위치에 배치합니다. 세 가지를 모두 설치하세요; review와 port 스킬은 스타일을 위해 best-practices 스킬에 의존합니다.

모든 에이전트, 명령 하나
스킬 설치 프로그램은 대부분의 에이전트를 지원합니다 (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
세션 내에서는 같은 작업입니다:

/plugin marketplace add morganlinton/BeautifulRust
/plugin install beautiful-rust@beautiful-rust

이것은 세 가지 스킬을 모두 설치합니다. /beautiful-rust:rust-best-practices, /beautiful-rust:rust-review, /beautiful-rust:rust-port로 나타나지만, 스스로 트리거되므로 직접 호출할 일은 거의 없습니다. 설치 없이 한 세션 동안 시험해 보려면 저장소를 클론하고 claude --plugin-dir ./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
기본적으로 현재 프로젝트에 설치됩니다. 사용자용으로 설치하려면 --scope user를, 다른 에이전트용으로 설치하려면 --agent <name>을 추가하세요.

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
OpenAI Codex, Cursor, 또는 그 외: 폴더 복사
저장소를 클론하고 세 스킬 폴더를 에이전트의 skills 디렉터리에 복사하세요. 대부분의 에이전트는 이제 공유 .agents/skills/ 위치를 읽습니다:

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

Agent
사용자 디렉터리
프로젝트 디렉터리

Claude Code
~/.claude/skills/
.claude/skills/

OpenAI Codex
~/.agents/skills/
.agents/skills/

GitHub Copilot
~/.copilot/skills/ 또는 ~/.agents/skills/
.github/skills/ 또는 .agents/skills/

Cursor
~/.cursor/skills/ 또는 ~/.agents/skills/
.cursor/skills/ 또는 .agents/skills/

Gemini CLI
~/.gemini/skills/ 또는 ~/.agents/skills/
.gemini/skills/ 또는 .agents/skills/

Claude Code는 .agents/skills/를 읽지 않으므로 자체 디렉터리나 플러그인을 사용하세요. 스킬이 바로 나타나지 않으면 에이전트를 재시작하세요.

claude.ai
claude.ai는 스킬당 하나의 zip을 받으며, 스킬 폴더가 zip 루트입니다:

cd skills
zip -r ../rust-best-practices.zip rust-best-practices -x ' *.DS_Store ' -x ' */evals/* '
zip -r ../rust-review.zip rust-review -x ' *.DS_Store ' -x ' */evals/* '
zip -r ../rust-port.zip rust-port -x ' *.DS_Store ' -x ' */evals/* '
각각을 Customize > Skills 아래에 업로드하세요. 먼저 코드 실행이 활성화되어 있어야 합니다.

기존 코드 리뷰
에이전트에게 파일, 크레이트 또는 diff를 리뷰하도록 요청하세요. 예: "review src/parser.rs" 또는 "what would you change in this PR". rust-review 스킬은 툴체인이 사용 가능할 때 cargo fmt, clippy, 테스트를 실행한 다음, 세 계층으로 된 리포트를 작성합니다: must fix, should fix, consider. 모든 발견 사항은 file:line 위치, 위반한 규칙과 그 출처(예: C-GETTER 같은 API Guidelines 코드, Effective Rust 항목, Microsoft 가이드라인, 또는 clippy lint), 그리고 이를 수정하는 최소한의 코드 변경을 제공합니다. 각 리포트는 코드가 이미 잘하고 있는 것으로 끝납니다.

examples/review-inventory.md는 eval 케이스의 의도적으로 지저분한 모듈에 대해 스킬이 생성한 실제 리뷰입니다.

Rust로 코드 포팅
에이전트에게 모듈을 포팅하도록 요청하세요. 예: "port parser.c to Rust" 또는 "rewrite this Python service in Rust". rust-port 스킬은 원본과 그 테스트를 읽고, 테스트를 먼저 포팅하고, 원본을 음차하는 대신 Rust API를 설계하며, cargo test와 clippy로 검증합니다. 각 언어의 관습을 Rust 대응물로 매핑합니다: NULL과 None은 Option으로, 에러 코드와 예외는 에러 enum으로, 출력 파라미터는 반환값으로, 플래그 int와 매직 문자열은 타입이 있는 enum과 옵션으로, dict 삽입 순서는 출력을 조용히 재정렬할 HashMap 대신 순서 있는 컬렉션으로. 각 포트에는 이전 API와 테스트를 새 것으로 매핑하고 모든 의도적 차이를 나열하는 PORTING.md가 함께 제공됩니다.

Bevy
Bevy는 시스템을 호출하고 그 인자를 구성하므로, 일부 일반적인 Rust 조언은 Bevy에 맞지 않습니다. 액면 그대로 받아들이면 스킬은 에이전트에게 Res<Time>을 참조로 바꾸고, use bevy::prelude::*를 명시적 import로 교체하고, clippy를 조용히 하기 위해 시스템을 분할하라고 말할 것입니다. 크레이트가 bevy 또는 bevy_ecs에 의존할 때, 작성 및 리뷰 스킬 모두 이제 references/bevy.md를 먼저 읽습니다. 이는 Bevy 0.20을 다루며 두 가지를 합니다:

그대로 두어야 할 관습을 명시합니다: 값으로 받는 시스템 파라미터, Bevy prelude, 일반 데이터 컴포넌트의 public 필드, 복잡한 쿼리 타입.
깔끔하게 컴파일되는 ECS 버그를 나열합니다. 같은 컴포넌트를 모두 변경할 수 있는 두 쿼리는 첫 프레임에서 에러 B0001과 함께 패닉합니다. 한 시스템은 다른 시스템의 Commands가 적용되기 전에 world를 읽을 수 있습니다. 서로 의존하는 시스템 사이에는 순서가 없을 수 있습니다. .single().unwrap()은 플레이어가 죽으면 게임을 크래시시킵니다.

참조의 모든 동작은 bevy 0.20.0에 대한 테스트로 검증되었습니다. 두 개의 eval 케이스가 이를 다룹니다: 그 버그 중 두 개를 심어둔 전투 플러그인의 리뷰, 그리고 수정된 플러그인에 추가된 기능으로, 에이전트가 Bevy의 관습을 유지하는지 확인합니다.

clippy로 규칙 강제
스킬은 규칙을 가르치고, lints는 규칙이 다시 미끄러지지 않게 합니다. lints/clippy.toml을 Cargo.toml 옆에 복사하고 lints/lints.toml의 [lints] 블록을 붙여넣은 다음 실행하세요:

cargo clippy --all-targets --all-features -- -D warnings
테스트 외부의 unwrap(), // SAFETY: 주석이 없는 unsafe 블록, 이유 없는 #[allow], 모든 bool 함수 파라미터, 조용한 손실 as 캐스트, 누락된 # Errors 및 # Panics 문서, 남은 dbg!와 todo!를 플래그합니다. 파일에서 [lib]로 표시된 lint는 라이브러리용이며, 애플리케이션은 이를 제거할 수 있습니다. Bevy 크레이트는 네 가지 추가 allow가 필요하며, Bevy 참조에 나열되어 있습니다. 그렇지 않으면 테이블이 모든 관용적 시스템 시그니처를 플래그하기 때문입니다.

테이블의 모든 lint는 발동함이 증명됩니다. lints/check/는 lint당 하나의 의도적 위반이 있는 작은 크레이트이며, 이 스크립트는 저장소 루트에서 clippy를 실행합니다:

bash scripts/check-lints.sh
lint가 발동을 멈추거나, 예상치 못한 것이 발동하거나, check 크레이트의 테이블 사본이 lints/lints.toml과 어긋나면 실패합니다. allow_attributes와 allow_attributes_without_reason은 rust-version = "1.81" 이상이 필요합니다. clippy가 #[expect]를 사용할 수 없는 크레이트에 대해 이들을 끄기 때문입니다.

작성 스킬이 다루는 내용
skills/rust-best-practices/SKILL.md는 약 500줄이며, 에이전트가 코딩 중에 훑어볼 수 있도록 구성되어 있습니다:

마인드셋: Rust다운 코드, 표현 불가능한 무효 상태, 애플리케이션 vs 라이브러리
인계 전 체크리스트: fmt, -D warnings를 사용한 clippy, test, doc; lint 정책
소유권과 빌림: borrow checker 대신 복제하는 것에 대한 대안
타입과 API 설계: 네이밍, newtype, 공통 트레이트, 빌더, 가시성, 제네릭 vs dyn
에러와 패닉: Option vs Result vs panic, 라이브러리 vs 애플리케이션 에러 타입
일상적 관용구: 이터레이터, 컴비네이터, format!, import, drop guard
동시성과 async: Send 단언, 락 규율, async fn, 양보 지점
Unsafe와 FFI: 허용되는 경우, SAFETY: 주석, 건전성, bindgen
크레이트, 모듈, 의존성: 워크스페이스 레이아웃, 기능, semver
문서와 주석
테스트
성능, 순서대로
최종 체크리스트

skills/rust-best-practices/references/는 더 깊은 조회를 위해 출처당 하나의 다이제스트를 담고 있습니다.

레이아웃
BeautifulRust/
├── .claude-plugin/
│ ├── plugin.json 플러그인 매니페스트
│ └── marketplace.json 이 저장소가 자체 마켓플레이스 역할을 하게 함
├── skills/
│ ├── rust-best-practices/ 작성 스킬
│ │ ├── SKILL.md
│ │ ├── references/ 출처당 하나의 다이제스트, 그리고 bevy.md
│ │ └── evals/
│ ├── rust-review/ 리뷰 스킬
│ │ ├── SKILL.md
│ │ └── evals/
│ └── rust-port/ 포팅 스킬
│ ├── SKILL.md
│ └── evals/ 포팅할 C 모듈과 Python 모듈
├── lints/
│ ├── lints.toml Cargo.toml용 [lints] 블록
│ ├── clippy.toml clippy 임계값
│ └── check/ lint당 하나의 의도적 위반
├── scripts/
│ ├── check-skill.py 스킬, eval, 매니페스트 검증
│ ├── check-lints.sh 테이블의 모든 lint가 발동함을 증명
│ ├── check-examples.py 문서의 모든 Rust 예제 컴파일
│ └── examples.json 조각 예제가 컴파일되게 하는 컨텍스트
├── benchmarks/
│ └── cross-agent-2026-10/ Claude…