一、问题从哪来：训练语料偏「教程」，仓库偏「契约」

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

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

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

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

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

---

二、unwrap / expect：不是语法问题，是「错误语义」被删掉

2.1 为什么模型爱用 unwrap

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

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

2.2 SkillLite 的硬规则（节选）

在 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<Config> {
    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 不是风格偏好，是合入红线。

---

三、严格的分层与 crate 依赖：没有「地图」就容易抄近道

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 留痕，从流程上抬高「宣布完成」的成本。

---

五、发散：还有哪些 Spec 化「护栏」值得做

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

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

---

六、Spec 注入在研发流程中的位置（总览）

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 的硬规则、一张 依赖方向图、以及一条 「声称完成必须附命令输出」 的反幻觉门槛——它们成本不高，却能显著拉齐人与模型的「工程默认值」。

参考项目：SkillLite