Claw Code 的 Rust 工作区指引文件：CLAUDE.md 如何规定校验命令、格式化入口与协作约定

本文以 rust/ 目录下的 rust/CLAUDE.md 为主体，逐条解读这份面向编码 Agent 的工作区指引：它如何声明技术栈、如何规定唯一的格式化入口与严格校验命令、以及“共享默认值放 .claw.json、本地覆盖放 .claw/settings.local.json、不自动改写指引文件”三条协作约定的落地方式。读完后，你能掌握在一个多 crate Rust 工作区中为 Agent 编写可执行、可验证指引文件的方法，并能结合仓库源码核对每一条约定的实际实现。

指引文件的定位：嵌套工作区中的 Agent 上下文

rust/CLAUDE.md 的第一句话就明确了它的服务对象：“This file provides guidance to Claw Code (clawcode.dev) when working with code in this repository.”——它不是面向人类读者的项目说明，而是编码 Agent 进入 rust/ 目录工作时加载的操作手册。

这个仓库存在两级指引文件，分工清晰：

• 根目录 CLAUDE.md 面向 Claude Code（claude.ai/code），描述仓库整体形态：rust/ 存放 Rust 工作区与活跃的 CLI/runtime 实现，src/ 与 tests/ 是需要与代码变更同步维护的校验面；
• rust/ 下的 rust/CLAUDE.md 面向 Claw Code，聚焦 Rust 工作区内部的校验与约定。

从源码结构看，这类文件本身就是 claw CLI 初始化流程的产物。init.rs 中的初始化逻辑会在当前目录创建 CLAUDE.md（含“created / skipped (already exists)”的状态汇报），并在 第 289 行 把“Do not overwrite existing CLAUDE.md content automatically”这条约定直接写进生成的模板正文——约定与生成逻辑互为镜像，确保新初始化的项目天然继承同一套规则。相关的行为契约在 output_format_contract.rs 中有测试覆盖，包括父目录与子项目 CLAUDE.md 的层级发现逻辑。

Detected stack：技术栈声明段

原文档的“Detected stack”一节只有两条：

- Languages: Rust.
- Frameworks: none detected from the supported starter markers.

这段内容看似简短，却是指引文件的标准骨架之一：它告诉 Agent “这是一个纯 Rust 项目，不要套用 Web 框架项目的前端构建/测试假设”。这一声明与仓库实际结构吻合——rust/Cargo.toml 定义了一个 members = ["crates/*"] 的 Cargo 工作区，版本 0.1.3、edition 2021、publish = false，没有任何第三方框架依赖的痕迹。rust/AGENTS.md 进一步列出了工作区内 11 个 crate 的职责划分（rusty-claude-cli 为主二进制、runtime 为核心库、api 为提供方客户端等），可作为理解“Detected stack”语境的延伸阅读。

Verification：格式化、Lint 与测试的三条硬规则

这是 rust/CLAUDE.md 中最具操作价值的部分，原文规定了三个要点：

1. 从仓库根目录执行格式化：运行 scripts/fmt.sh（CI 风格检查用 scripts/fmt.sh --check）；
2. 从 rust/ 目录执行的等价命令是 ../scripts/fmt.sh；
3. 根目录的 cargo fmt --manifest-path rust/Cargo.toml 不是受支持的格式化命令——这是原文档明确写出的反模式。

fmt.sh 到底做了什么

为什么“受支持的命令”只有 scripts/fmt.sh 这一个入口？答案藏在脚本本身，全文只有 7 行（scripts/fmt.sh）：

#!/usr/bin/env bash
set -euo pipefail

SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
REPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
cd "$REPO_ROOT/rust"
exec cargo fmt "$@"

它做三件事：

• 通过 BASH_SOURCE 定位脚本自身，再向上推导出仓库根目录 REPO_ROOT，不依赖调用者当前所在目录——这就是为什么从根目录 scripts/fmt.sh 和从 rust/ 目录 ../scripts/fmt.sh 两种写法语义完全等价；
• cd "$REPO_ROOT/rust" 把工作目录固定到工作区所在目录，保证 cargo fmt 以工作区根为基准解析所有成员 crate；
• exec cargo fmt "$@" 透传参数，因此 --check 只是原样转发给 cargo fmt 的标准参数。

这套设计的实际含义是：格式化的“入口”被脚本收口为唯一事实来源。如果哪天工作区布局变化（比如 crate 挪目录），只需改脚本；而 cargo fmt --manifest-path rust/Cargo.toml 虽然表面上也能格式化，但它绕开了这层收口，属于“能跑但不在约定内”的写法。rust/AGENTS.md 的 ANTI-PATTERNS 一节用同样的措辞再次强调了这一点（“Don't run cargo fmt --manifest-path rust/Cargo.toml from the repo root. Use ../scripts/fmt.sh instead.”）。

严格校验：clippy 与测试

原文档规定的 Rust 校验命令为（均在 rust/ 目录下执行）：

cargo clippy --workspace --all-targets -- -D warnings
cargo test --workspace

两条命令的要点：

• --workspace --all-targets：覆盖工作区内全部 crate、全部 target（lib、bin、test、bench），不留死角；
• -- -D warnings：把所有 warning 提升为 error，即“零警告”门槛。rust/AGENTS.md 特别注明：CI 的 clippy 步骤并不带 -D warnings，所以本地这条命令比 CI 门禁更严格——Agent 在本地先过这一关，推到 CI 才不会翻车。

“零警告”并非空话，它由工作区 lint 配置强制：rust/Cargo.toml 中声明了

[workspace.lints.rust]
unsafe_code = "forbid"

[workspace.lints.clippy]
all = { level = "warn", priority = -1 }
pedantic = { level = "allow", priority = -1 }
module_name_repetitions = "allow"
missing_panics_doc = "allow"
missing_errors_doc = "allow"

其中 unsafe_code = "forbid" 是最高等级——forbid 比 deny 更严，连 #[allow] 都无法豁免。也就是说，-D warnings 之下任何一条 clippy 告警、加上从源头禁死的 unsafe 代码，共同构成了 cargo test --workspace 之前的质量基线。工作区内各 crate 通过 [lints] workspace = true 统一继承这套配置（见 rust/AGENTS.md 的 CONVENTIONS 一节）。

与 CI 的对应关系

rust/AGENTS.md 提到 CI 定义在 .github/workflows/rust-ci.yml（fmt、clippy、test、docs、Windows smoke 五步）与 release.yml。仓库内确实存在这两个工作流文件（.github/workflows/rust-ci.yml、.github/workflows/release.yml）。对 Agent 而言，CLAUDE.md 的 Verification 一节就是这份 CI 契约的本地化副本：本地命令与 CI 步骤一一对应，且刻意比 CI 更严。

Working agreement：三条协作约定的落地证据

原文档的“Working agreement”一节给出三条约定，逐条都可以在仓库里找到对应物：

1. 小步变更，保持引导文件与工作流对齐

Prefer small, reviewable changes and keep generated bootstrap files aligned with actual repo workflows.

这条约定针对的是“引导文件腐化”问题：CLAUDE.md、AGENTS.md 这类文件如果是自动生成物，一旦仓库工作流变了（比如格式化入口换了脚本），而引导文件没跟着更新，Agent 就会按过时指令行事。本仓库的做法是让 rust/CLAUDE.md、rust/AGENTS.md 与根目录 AGENTS.md、CLAUDE.md 中的命令描述互相一致（均指向 scripts/fmt.sh 与同一组 clippy/test 命令），一致性本身就是可检查的事实。

2. 共享默认值在 .claw.json，机器本地覆盖在 .claw/settings.local.json

Keep shared defaults in .claw.json; reserve .claw/settings.local.json for machine-local overrides.

这是典型的“全局共享配置 vs 本地覆盖”分层。仓库根目录确实存在 .claw.json，当前内容为：

{
  "aliases": {
    "quick": "haiku"
  }
}

即提交到仓库的共享默认值（此处定义了一个模型别名 quick -> haiku）；而 .claw/settings.local.json 则属于不入库的机器级覆盖位。对 Agent 的意义在于：改配置前先判断“这是团队共享的默认值还是我这台机器的偏好”，避免把本地偏好提交进共享文件。根目录还存在 .claude/ 目录（当前包含 sessions/ 子目录），是运行时产生的会话状态区，与配置分层互不干扰。

3. 不自动覆盖已有 CLAUDE.md，仅在仓库工作流变化时有意更新

Do not overwrite existing CLAUDE.md content automatically; update it intentionally when repo workflows change.

这条约定在前文已提到：它既写在了 rust/CLAUDE.md 正文里，也作为字面量被写进了 init.rs 的模板生成逻辑，并在初始化路径中以“skipped (already exists)”的行为兑现——对已存在的 CLAUDE.md 只跳过、不重写（init.rs 的测试断言了这一行为）。换言之，这条“约定”同时是：文档层规则、模板层内容、代码层行为三位一体。

如何在自己的 Rust 工作区复用这套模式

基于本仓库的实证，把 rust/CLAUDE.md 当作模板移植到自己的 Rust 工作区时，可复制的骨架是：

1. Detected stack 段：只写语言与框架两行，且必须是 Agent 可据此排除假设的事实（“无框架”同样是有用信息）；
2. Verification 段：把格式化收口到一个小脚本（固定工作目录 + 透传参数 + exec），在指引中同时写明“受支持入口”与“不受支持的等价命令”，并把 clippy 本地门槛设为 -D warnings 这种可执行判据；
3. Working agreement 段：每条约定都应能在仓库中找到落点——配置文件（如 .claw.json）、生成代码行为（如初始化跳过逻辑）或测试断言，避免写出无法被验证的空话。

需要注意的适用前提：本指引文件描述的是当前仓库的实际工作流（rust/ 工作区布局、scripts/fmt.sh 入口、workspace lints 配置），其命令与路径仅在遵循相同布局的项目中可直接复用；lint 严格度（如 unsafe_code = "forbid"）与工作区版本（当前 0.1.3、publish = false）则以 rust/Cargo.toml 的实际内容为准。

小结

rust/CLAUDE.md 全文虽不足 20 行，却示范了 Agent 指引文件的关键质量：每一句都指向可执行命令或可核对的仓库事实——格式化入口由 scripts/fmt.sh 收口、零警告门槛由 rust/Cargo.toml 的 workspace lints 与 -- -D warnings 共同兑现、三条协作约定分别对应 .claw.json、初始化逻辑与测试契约。延伸阅读可参考同目录的 rust/AGENTS.md（crate 结构、命名与反模式全集）与 rust/README.md。