Clear Rust 是一套关于如何编写“朴素 Rust”的实践准则，核心目标是让代码的行为、所有权、失败处理和控制流都易于看清。它适用于任何源码、测试、宏、Cargo crate 或 API 相关工作。使用时应遵循仓库自身的契约、MSRV、约定以及经过测量的性能要求；在评审或诊断场景中，应先评估代码而不重写，除非被明确要求，并保留已经清晰的选择。
代码形态
优先从函数、结构体和枚举开始，而不是注册表、工厂、插件层或类似框架的间接结构。只有当当前的可变性或公开契约确实需要时，才增加一层抽象。从具体实现起步，当 trait、泛型参数或 trait 对象表达了当前代码实际使用的真实契约时才引入它们，并将约束限制在实现真正用到的能力范围内。
对于小而稳定的重复代码，如果提取会导致不相关的流程耦合，或迫使读者在文件之间跳转，可以保留重复；当重复代码代表一个连贯概念、只有一个变更原因时才提取。当分支、可变性或错误上下文重要时，使用 if、match、for 和具名中间值；保持简短、线性的迭代器管道，将密集或带副作用的链拆分为具名步骤或循环。
按职责边界而非任意大小限制来拆分函数和模块；当分离会隐藏流程时，应让逻辑保持在一起。使用最简单的实用枚举、结构体或 newtype 让有意义的非法状态无法表示；将 typestate 和泛型状态机保留给其价值足以证明其机制合理的不变量。在能保持实现清晰的前提下，优先使用标准库和已有依赖；当某个 crate 能消除项目不应承担的持久复杂性时再添加它，并检查其维护状况、特性、MSRV 和公开 API 影响。
保持所有权可见
当调用方应保留所有权时使用借用；必须存储或生命周期超出调用的值则取得所有权。返回值而不是添加输出参数。当有意的、有界的克隆能显著提升所有权清晰度且成本可接受时，可以接受它；对于大型或热路径数据的克隆，应深入调查，而不是仅用它来让借用检查器闭嘴。让生命周期省略处理常规签名；当编译器要求或关系本身需要解释时才命名生命周期。将共享所有权和内部可变性限制在狭窄边界内；当所有权或并发模型确实需要时，才使用 Rc、Arc、RefCell、锁或原子类型。
让失败与安全显式化
对于可预期的运行时失败返回 Result，即使当前层只能报告错误并退出；对于预期的缺失使用 Option；将有意 panic 保留给被违反的不变量和程序员错误。在测试、原型或局部明显不可能失败的情况下使用 unwrap 或 expect；在 expect 消息或相邻说明中陈述不明显的不变量。遵循项目的错误模型，保留有用的源错误，并在边界处添加上下文可操作的错误信息，避免过早将不同失败折叠为无差别的字符串。在边界处验证输入；当小型类型能防止真实误用时，用它们编码稳定的领域区分。
当维护良好的安全抽象能完成任务时，保持安全 Rust。当必须使用 unsafe 时，保持块小，在 SAFETY 注释中陈述不变量，尽可能暴露安全接口，并在公开的 # Safety 部分记录每个调用方义务。当并发不是需求时，保持顺序或同步代码；当需要 async 时，保留既有运行时，保持同步/异步边界可见，并让阻塞工作远离异步执行路径。
有意识地使用宏
正常使用既有宏，如标准 derive、println!、vec!、断言、格式化宏和常规框架宏。当普通函数、类型、trait 和控制流能清晰表达项目自有行为时，就用它们。当接口确实需要语法、可变参数数量或机械重复，且展开结果保持明显时，使用小型声明式宏。对过程宏和嵌入式 DSL 要求更强的现实需求；保持自定义语法接近普通 Rust，生成行为不令人意外，生成名称抗冲突，路径显式，诊断可操作。测试有代表性的自定义宏调用和失败情况，让生成行为无需逆向宏即可理解。
保持 API 惯例
公开接口不应大于当前调用方所需；除非直接表示访问是契约的一部分，否则使用私有字段。在合适处使用标准命名、转换 trait 和常见派生 trait；将具有明确接收者的操作做成方法，保持运算符重载不令人意外，仅为智能指针行为实现 Deref。记录公开的错误、panic 和安全条件；在能说明为何或如何使用 API 时添加示例。注释应说明不变量、意图和权衡，而不是复述语法。
按比例验证
优先使用仓库自身的命令。否则，在修改代码后，运行 cargo fmt --check、cargo check、聚焦测试和 cargo clippy 中适用的子集。将配置的 lint 和 Clippy 默认组视为基线；仅当项目已经启用，或在针对当前代码库评估个别 lint 之后，才启用 pedantic、restriction 或 nursery lint。相比为了满足有主见的 lint 而扭曲清晰代码，更倾向于有正当理由的局部 lint 豁免，并记录该例外为何正确。