# google-rust-style

将 [Google Rust Style Guide](https://google.github.io/styleguide/rustguide.html) 提炼成的 **Agent Skill**——写代码、做 code review 时由 AI 编程助手自动加载，按谷歌规范约束 Rust 的 API 设计、代码组织、命名、文档与实现细节。

> An Agent Skill that distills Google's Rust Style Guide for AI coding agents. Works with any tool that supports the open Agent Skills format (a folder with `SKILL.md`), including ZCode, DSH (DeepSeek Harness), OpenCode and Codex.

## 背景

Google 对 "style" 的定义不止代码格式，还涵盖 API 与实现设计。本仓库把整份指南做成渐进式加载的技能：触发时只载入速查与索引，按具体任务再读分主题的参考文件，另附原文机器提取稿用于核对。

提炼时保留了指南的三个关键机制：

- 每条规则的**例外情况**（例外也是规则的一部分）
- `[chrome]` / `[Fuchsia]` 专属规则标记（只适用于对应代码库，通用项目不套用）
- "库代码强制、应用代码建议"的执行总纲

## 文件结构

| 文件 | 内容 |
|---|---|
| `SKILL.md` | 触发描述、库/应用代码定位、高频规则速查、主题索引 |
| `references/organization-and-formatting.md` | crate 划分、模块/文件布局、imports 规则、rustfmt 配置 |
| `references/api-design.md` | 函数输入输出、错误上报、trait 设计、getter/setter、`#[non_exhaustive]`、`#[must_use]`、unsafe |
| `references/naming-and-documentation.md` | 命名（`as_`/`to_`/`into_`、构造器、生命周期）与文档注释规范 |
| `references/implementation.md` | `Rc`/`Arc`、clone、模式匹配、断言上下文、迭代器链、测试框架 |
| `references/source-text.md` | 原指南全文机器提取稿（英文，核对用） |

## 安装

适用于支持 Agent Skills 目录约定（技能目录 + `SKILL.md`）的工具：

| 工具 | 技能目录 |
|---|---|
| ZCode | `~/.zcode/skills/` 或 `~/.agents/skills/` |
| DSH (DeepSeek Harness) | `~/.agents/skills/`（放入后重启 dsh） |
| OpenCode | `~/.config/opencode/skills/`（全局）或 `.opencode/skills/`（项目） |
| Codex | `~/.codex/skills/` |

```bash
git clone https://github.com/LOWRUI/google-rust-style.git ~/.agents/skills/google-rust-style
```

Windows PowerShell：

```powershell
git clone https://github.com/LOWRUI/google-rust-style.git $env:USERPROFILE\.agents\skills\google-rust-style
```

安装后无需手动调用：用 Rust 写代码、review、讨论 rustfmt / clippy / 谷歌 Rust 规范时自动触发。

## 来源与许可

- 规则内容提炼、转述自 [Google Rust Style Guide](https://google.github.io/styleguide/rustguide.html)。原指南内容 © Google，以 [CC BY 3.0](https://creativecommons.org/licenses/by/3.0/) 发布；`references/source-text.md` 为其机器提取稿，版权归 Google，仅随技能作核对用途。
- 本仓库的提炼与撰写部分以 [MIT License](LICENSE) 发布。

## 更新说明

基于 2026-10 抓取的指南版本提炼。原指南更新后欢迎提 issue / PR 同步。