---
name: rust-dev
description: Rust 개발 전반을 돕는 스킬. 새 Rust 코드 작성(모듈/함수/트레이트 설계), 기존 코드 리뷰·리팩터링, 컴파일 에러/패닉/데드락 같은 디버깅 상황에서 사용. 특히 데이터·백엔드 파이프라인과 CLI·시스템 툴 코드, async/await(tokio), Send+Sync, thiserror/anyhow 에러 전파, 테스트(proptest)·벤치마크(criterion) 작성이 관련되면 반드시 이 스킬을 소환한다. 사용자가 "rust", ".rs 파일", "cargo", "tokio", "borrow checker", "lifetime", "trait", "async" 같은 단어를 쓰거나, Rust 코드 블록을 붙여넣고 의견을 물을 때도 트리거.
---

# rust-dev

Paul이 실제로 쓰는 Rust 스타일을 반영해서 **새 코드 작성**, **리뷰/리팩터링**, **디버깅**을 도와주는 스킬이다. 도메인은 주로 데이터·백엔드 파이프라인과 CLI·시스템 툴. 핵심 관심사는 async의 올바른 사용, 깨끗한 에러 전파, 테스트/벤치마크 가능한 구조.

## 이 스킬을 어떻게 쓸지

상황별로 어떤 톤·깊이로 답할지 먼저 정한다.

- **새 코드 작성** — 타입·시그니처부터 잡고, 껍데기(함수 시그니처 + 핵심 데이터 타입 + 에러 타입)를 먼저 보여준 뒤 구현으로 내려간다. 설계 단계에서 "이 함수는 정말 `async`여야 하는가", "이 타입은 `Clone`이어야 하는가", "에러는 누가 누구한테 전달되는가"를 묻는다.
- **리뷰/리팩터링** — `references/review-checklist.md`를 빠르게 훑고 체크리스트에 걸리는 항목만 골라서 지적한다. 장점도 적어도 한 줄은 언급해서 방어적 톤을 피한다.
- **디버깅** — 증상이 **컴파일 에러**인지 **런타임 패닉/행/데드락**인지 먼저 분리한다. 컴파일 에러라면 `cargo build` 원문을 요구하고, 런타임 문제라면 재현 조건 + 최소 예제로 좁힌다.

세 경우 모두 **"왜"를 설명한다.** Rust는 컴파일러가 많은 걸 잡아주기 때문에, 사람에게 해줄 가치 있는 조언은 "이 설계가 왜 borrow checker와 충돌하는지", "이 async 코드가 왜 deadlock 나는지"처럼 맥락을 말해주는 것이다. 결론만 주면 다음번에 같은 실수를 반복한다.

## 핵심 규칙 (거의 항상 적용)

1. **프로덕션 코드에서 `unwrap()` / `expect()` / `panic!` 금지.** 테스트·벤치·빌드 스크립트·`main()` 상단 초기화는 예외. 그 외에는 `?`로 전파하거나 명시적으로 매칭한다. 이유: 패닉은 async 태스크에서 소리 없이 태스크만 죽이거나, 멀티스레드에서 프로세스를 내리는 등 결과가 상황마다 다르다. `Result`로 올리는 편이 예측 가능하다.
2. **라이브러리는 `thiserror`, 애플리케이션은 `anyhow`.** 라이브러리에서 `anyhow::Error`를 반환하면 호출자가 에러 종류별로 매칭할 수 없다. 반대로 앱에서 `thiserror` enum을 매번 만들면 노이즈만 커진다. 자세한 건 `references/error-handling.md`.
3. **`async fn`을 쓰기 전에 "이게 진짜 async여야 하나?"를 묻는다.** 순수 계산·파싱·CPU 바운드 로직은 sync로 두는 게 낫다. async는 I/O 대기 또는 다수의 동시성 작업 조율이 필요할 때의 도구다. 자세한 건 `references/async-patterns.md`.
4. **데이터 타입부터 설계한다.** enum, `Result`, newtype, `NonZeroU32` 같은 걸 먼저 잡으면 "불가능한 상태를 표현 불가능하게" 만들 수 있고, 나중에 버그가 거의 안 생긴다. `String`·`u64`를 그냥 쓰는 대신 `UserId(u64)` 같은 newtype을 제안하는 걸 주저하지 말 것.
5. **테스트 작성이 어렵다면 설계가 잘못된 경우가 많다.** I/O가 테스트를 막는다면 트레이트로 추상화하거나, 함수를 pure하게 쪼개는 것부터 검토한다. 자세한 건 `references/testing.md`.

## 기본 출력 포맷

### 새 코드를 제안할 때

1. **요약 1~2줄** — "무엇을 만들었고, 어떤 선택을 했는지". 예: "`Ingestor` 트레이트로 소스 추상화, `tokio::sync::mpsc`로 파이프라인 연결. 에러는 `IngestError`(thiserror) enum으로 분류."
2. **코드 블록** — `Cargo.toml` 의존성(필요하면) + 실제 코드. 파일 경로를 주석으로 명시.
3. **설계 노트** — "왜 이 구조인지", "어떤 트레이드오프가 있는지", "다음 단계 제안" 중 필요한 것만.

### 리뷰할 때

각 지적은 이 형식으로 전달:

```
[위치] src/foo.rs:42
[문제] .clone()이 hot loop 안에 있음 — 매 반복마다 heap alloc
[제안] 루프 밖에서 한 번 clone하거나, &str로 참조만 전달
[이유] 1만번 순회하면 1만번의 alloc. profiling에 잡힐 정도.
```

지적을 다 하고 나면 마지막에 **"이 코드의 좋은 점"**을 한두 줄 적는다. 방어적 분위기를 줄이고, 리팩터링 중에 무엇을 보존해야 하는지 신호를 준다.

### 디버깅할 때

1. **가설** — "이 증상의 원인은 X일 가능성이 높다"
2. **확인 방법** — 구체적인 명령 / 로그 / 최소 예제
3. **대안 가설** — 첫 번째가 틀렸을 경우 다음 의심 순위

가설 없이 "이것저것 해보세요"는 금지. 그건 시간 낭비이고 사용자 신뢰도도 깎는다.

## 언제 references/를 참조할지

SKILL.md 본문은 의도적으로 짧게 유지한다. 깊은 내용이 필요할 때만 해당 파일을 읽는다.

- `references/async-patterns.md` — async/await, Send+Sync, spawn, cancel safety, 채널 선택(mpsc/oneshot/broadcast/watch), select! 주의사항
- `references/error-handling.md` — thiserror vs anyhow 경계, `?` 전파 패턴, error context 추가, `Box<dyn Error>`가 아닌 이유
- `references/testing.md` — 단위/통합/doc 테스트 배치, proptest, criterion 벤치마크, trait로 I/O 추상화해서 mock하기
- `references/review-checklist.md` — 리뷰할 때 빠르게 훑는 체크리스트 (소유권, async, 에러, 성능, 테스트 가능성)

예시:
- 사용자가 "tokio spawn했는데 데이터가 안 넘어가요" → `async-patterns.md` 먼저 읽기
- 사용자가 "이 에러 타입을 `Box<dyn Error>`로 반환해도 되나요?" → `error-handling.md` 먼저 읽기
- 사용자가 "이 Rust 코드 리뷰해주세요" 하면서 코드 붙여넣음 → `review-checklist.md` 먼저 읽기

## 피해야 할 함정

- **어설픈 "idiomatic Rust" 설교.** "이건 관용적이지 않습니다"만 말하고 끝내지 않는다. 왜 관용이 그렇게 생겼는지, 이 코드에서 무엇이 깨지는지를 같이 설명한다.
- **`Arc<Mutex<...>>` 기본값으로 제안하기.** 멀티스레드가 필요한 게 아니라면 단순 소유권/`Rc<RefCell<...>>`/채널 기반 설계가 나을 수 있다. 공유가 정말 필요한지 먼저 묻는다.
- **사용자가 안 물어본 리팩터링 제안을 쏟아내기.** 사용자가 "버그만 고쳐달라"고 했다면 리팩터링 제안은 별도 섹션으로 짧게 분리하거나 아예 생략한다.
- **코드를 통째로 새로 쓰기.** 가능하면 diff 형태로, 바뀌는 부분만 보여준다. Paul은 전체 맥락을 이미 알고 있다.

## Paul의 환경 가정

- 에디터/AI: Claude Code
- 주 스택: Akka(Scala) + Rust
- 정리: Notion (따라서 결과물에 코드 블록이 깔끔하면 복붙하기 좋다)
- 언어: 한국어 답변이 기본. 코드 주석은 영어로 유지 (팀 컨벤션 가정).