用途:为 codex-rs/ 各 crate 编写、评审或修改 Rust 代码时提供符合 Codex-RS 仓库约定的结构化规则,每条规则附来自真实代码的正误示例。适用时机包括新增功能到 app-server 协议或 TUI、修改配置类型/特性开关/依赖、调试错误处理或异步任务协调。
主要能力:共 40 条规则,按优先级分 8 类。错误处理(err-,关键,6 条):每个可失败操作使用 .context()、写描述性上下文字符串、非关键发送失败用 let _ =、生产代码避免 unwrap()、在 CodexErr 定义领域错误变体、平台相关变体用 #[cfg] 门控。类型设计(type-,关键,6 条):用枚举代替布尔参数、不透明字面量前用 /param_name/ 注释、穷尽匹配不用通配符、优先 BTreeMap 保证确定性、领域标识用 newtype、返回具名结构体代替元组。模块组织(mod-,高,5 条):模块不超 500 行、用 #[path = "..."] 同级测试文件、避免单次使用辅助方法、crate 名加 codex- 前缀、抽离模块时同步搬移测试与文档。Serde 与线格式(serde-,高,6 条):线类型用 rename_all camelCase、Params/Response/Notification 命名、v2 API 字段不用 skip_serializing_if、serde 与 ts-rs 注解对齐、判别联合使用显式 tag、API 边界用普通 String ID。异步与并发(async-,中高,5 条):大异步栈帧用 Box::pin、选择合适的 channel 类型、用 CancellationToken 协调关闭、用 Arc Notify 通知任务完成、即发即弃用 let _ = tx.send()。配置系统(cfg-,中,4 条):改配置后运行 just write-config-schema、改依赖后运行 just bazel-lock-update、遵循特性开关生命周期、编译期文件访问需更新 BUILD.bazel。TUI 约定(tui-,中,4 条):用 ratatui Stylize 辅助方法、避免硬编码 .white()、用 textwrap 与 word_wrap_lines、tui 与 tui_app_server 改动保持镜像。构建与 CI(ci-,中低,4 条):改 Rust 后运行 just fmt、用范围化 just fix -p 跑 Clippy、合并嵌套 if、format! 参数内联。
使用方式:编码前先看关键规则;实现中遵循模块与 Serde 规则;提交前运行 just fmt 和 just fix -p <crate>;改配置或依赖时遵循配置系统规则避免 CI 失败。参考文件含 references/_sections.md 及各前缀规则文件。
适用场景与限制:仅面向 Codex-RS 仓库贡献者;其他项目仅可参考。资料未提供安装命令、收费与授权信息,暂未提供。