7.5 万行 Rust 的 Spec 工程实践：用大模型写 Rust 时，如何把「教程味」挡在仓库外

大家好，我是讯享网，很高兴认识大家。这里提供最前沿的Ai技术和互联网信息。

摘要：大模型写 Rust 时常见 unwrap/expect 走捷径、忽略 crate 分层边界、以及「单测绿了但业务契约漂移」的局部最优。本文以开源项目 SkillLite （全仓 .rs 约 7.5 万行，不含 target/）为例，说明如何用 Spec 注入 、架构边界 spec 、任务制品（tasks） 与 可机械验证的完成门槛，把工程约束「写进提示词之前」，让 AI 辅助开发更像「带护栏的结对编程」，而不是「会编译的草稿生成器」。

关键词：Rust；Spec 工程；大模型辅助编程；unwrap；crate 分层；局部最优；Clippy；thiserror

Rust 教程与示例为了可读性，大量使用：

unwrap() / expect("...")：把错误路径折叠掉，读者一眼看到主流程；
anyhow::Result + ?：快速原型里很顺手；
单文件小例子：没有「跨 crate 依赖方向」「入口层路由」「沙箱不变量」这类组织级约束。

工程仓库恰恰相反：错误是类型系统里的一等公民，分层是编译期就应收束的架构，业务上还有「多端一致」「自进化 pending 父根」等平台契约。模型若只从统计模式上「像教程那样写」，就会在 PR 里反复制造三类技术债：

可恢复失败被伪装成 panic（unwrap 偷懒）；
为了赶进度穿透 crate 边界（依赖图变成意大利面）；
局部指标最优 （Clippy 零告警、单测全绿）但 全局契约劣化（文档、schema、运行时行为不一致）。

下面三节分别对应这三类问题，并给出 SkillLite 里可复制的 spec 对策；第四节补充若干「发散」方案；第五节为总结与反思。

对模型而言，unwrap 是最短可执行路径 ：少写枚举分支、少设计 Error 变体、少起名字。训练分布里它又高频出现，于是形成强先验：能编译 + 主路径演示跑通 ≈ 完成任务。

对工程而言，这等价于把 「失败时系统该如何表现」 从 API 契约里删掉：调用方无法通过类型表达假设，运维无法区分「预期内的用户输入错误」与「应当告警的缺陷」。

在 spec/rust-conventions.md 中，项目把生产路径上的 unwrap 直接列为 Must Not （仅测试代码允许），并强制 crate 级 Error + Result 与 thiserror、?、.with_context() 的错误链习惯。

对照阅读 crates/skilllite-core/src/error.rs 可以看到「教程式 anyhow 一把梭」与「工程式分层错误」的差异：统一 Error 枚举、Validation 表达领域规则、Other(#[from] anyhow::Error) 兼顾渐进迁移。

 
    
    
       
       // 教程/草稿里极常见：错误语义被吞掉，panic 边界外溢到运行时  
       fn load_config(path: &Path) -> Config { 
       let raw = std::fs::read_to_string(path).expect("read config"); serde_json::from_str(&raw).unwrap()  
       } 
       // 工程向：失败可传播、可分类、可在上层汇总展示 use crate::{Error, Result}; 
       fn load_config(path: &Path) -> Result 
        
          { 
         
       let raw = std::fs::read_to_string(path)?; serde_json::from_str(&raw).map_err(Error::from)  
       }

 Spec 的价值 在于：把「Must / Must Not」从口头 code review 变成 每次改 Rust 必注入的短规范 ，模型在写第一行业务代码前就被提醒：unwrap 不是风格偏好，是合入红线。

Rust 的模块与 workspace 让依赖方向 非常具体：谁在 Cargo.toml 里 depend 谁，编译器会认真执行。大模型若没有「全仓分层地图」，常见失误包括：

为了让某个函数「能调到」底层能力，反向让 core 依赖 agent；
在 agent_loop 里不断堆 if tool_name == "xxx"，而不是走扩展注册点；
把平台细节（macOS/Linux）渗进上层业务 crate。

SkillLite 在 spec/architecture-boundaries.md 里用一句话钉死主依赖链（节选含义）：

entry -> commands -> agent -> executor -> sandbox -> core，core 保持纯净、不得依赖上层。

这对 AI 辅助改动的意义是：在检索与推理之前先注入架构 spec，模型更少提出「在 core 里直接调 Tauri / MCP」这类结构上不可能或不该出现的方案；即便提出来，review 也有显式条文可引用。

实践要点 ：任何会动 workspace 布局、crate 依赖、入口路由的任务，在 spec/README.md 的映射里都会叠加 architecture-boundaries.md，并与 docs-sync.md 联动（中英文架构文档同步），避免「代码已改、文档仍画旧图」的二次迷路。

局部最优在 AI 辅助场景里特别隐蔽，因为模型极擅长优化 可立即度量的目标：

cargo test 全绿；
cargo clippy – -D warnings 无告警；
某个 bug 的复现步骤被「绕开」。

但工程上真正关心的是 契约全集：用户可见行为、环境变量、命令行、schema、安全沙箱不变量、跨端一致（例如技能发现单点 SSOT）。若缺少「反幻觉」与「反假阳性测试」的规范，很容易出现：

测试断言的是模型臆想的错误文案，而不是真实错误路径；
为了通过测试放宽校验，根因未修；
文档与代码漂移，review 难以一眼看出。

SkillLite 用 spec/verification-integrity.md 把完成定义改成：可独立验证的证据 优先于模型自述。并与 tasks/ 工作流结合：非琐碎改动要求 TASK.md 验收标准、PRD.md/CONTEXT.md 记录决策与边界、STATUS.md/REVIEW.md 留痕，从流程上抬高「宣布完成」的成本。

除本文主线外，SkillLite 仓库里还有几条可推广的组合拳（具体条文见对应 spec/*.md）：

按任务类型注入 spec （spec/README.md）：architecture、security、agent 等映射不同组合，避免「一条超长 AGENTS.md 没人读完」。
structured-signal-first：核心行为优先结构化运行时信号，正则与文本规则只做兜底，减轻「模型爱写脆弱字符串匹配」的维护压力。
docs-sync：行为、命令、环境变量变更强制中英文档对齐，把文档从「事后补写」变成合入条件。
testing-policy ：按变更类型要求最低测试集，和 verification-integrity 一起压制「假绿」。
CI 与本地一致 ：cargo fmt –check、clippy -D warnings、cargo test 作为共同语言；spec 里写清 Quick Verify，减少「我本地过了」的争议空间。

Cursor 侧通过 .cursor/rules/spec-injection-index.mdc 要求：凡改 Rust，必带 rust-conventions 与 testing-policy，从编辑器入口再次强化「规范不是文档角落里的摆设」。

unwrap/expect 的本质 是删掉错误语义；大模型因训练分布偏教程而高发；用 Must Not + CI + spec 注入 比事后 grep 更有效。
Rust crate 图 是严格的架构载体；architecture spec 相当于给模型一张「dependency DAG 说明书」，降低穿透分层、临时耦合的概率。
局部最优 在 AI 场景下表现为「指标绿 + 自述完成」；用 verification-integrity 与 任务制品 把「完成」定义成可审计证据链，才能保护业务契约。
长期看，Spec 工程不是增加文档负担，而是 把重复的人类唠叨变成可组合、可路由、可机器引用的短规范，让大模型在仓库里的行为更稳定、可预期。

如果你也在维护中大型 Rust monorepo，不妨从三件事起步：一条 禁止生产 unwrap 的硬规则、一张 依赖方向图 、以及一条 「声称完成必须附命令输出」 的反幻觉门槛——它们成本不高，却能显著拉齐人与模型的「工程默认值」。

项目地址：github.com/EXboys/skil…

7.5 万行 Rust 的 Spec 工程实践：用大模型写 Rust 时，如何把「教程味」挡在仓库外

相关推荐