Herdr 工程指南：CLAUDE.md 如何为 Coding Agent 分层治理一个 Rust 终端运行时项目

CLAUDE.md 是 herdr 仓库根目录下的“代理指令文件”，它为所有参与该项目开发的 AI 编码代理（Claude Code、Codex 等）提供一套分层、可验证、与源码结构一一对应的工程规则。本文将从文件的作用机制出发，完整拆解其中的作用域分层、架构原则、性能预算、测试与发布流程，并结合仓库中的 justfile、src/protocol/wire.rs、vendor/libghostty-vt.* 等实际实现，说明每一条规则背后真实对应的工程约束，帮助你在自己的多代理协作项目中建立同类的“agent 宪法”。

一、文件定位：写给 Agent 的项目宪法

CLAUDE.md 与 AGENTS.md 内容完全一致，二者是同一份指令的两个入口——不同厂商的代理工具分别约定读取其中一个文件。文档第一行就给出了项目自我定位：“Terminal based agent runtime for coding agents.”，即 herdr 本身就是一个“编码代理栖居其上”的终端运行时：它管理多个 PTY、多个代理窗格、多个客户端连接。

这份文件的核心设计是分层作用域（layered scope），而非一份扁平的“注意事项”列表。Scope and Audience 一节定义了四层适用范围：

作用域	适用条件	典型章节
通用规则（Universal）	所有代理、包括 fork 仓库中的代理	架构原则、性能路径、提交风格、代码约定
维护者流程（Maintainer Workflow）	通过三重验证的维护者	worktree 隔离、PR 与评审 bot 流程
本机专属（Local Can machine）	仅在 Can 本人的工作站或 Windows VM 上	Windows VM 验证流程
外部贡献者护栏（External contributor guardrail）	非验证维护者、在 fork 中工作、或身份不可判定	issue/PR 提交限制

分层的判定方式非常具体。维护者身份必须同时满足三个条件才算“已验证”：

1. 操作的 GitHub 账号用户名列在 .github/MAINTAINERS 中；
2. 配置的 remote 是规范的 herdrdev/herdr 仓库；
3. 认证账号对该仓库有写权限（通过 gh auth status 和仓库权限确认）。

任何一条无法验证，代理就必须跳过维护者流程，直接落到外部贡献者护栏。这是一种“证据不足则降级”（fail-closed）的设计，专门防止代理在身份存疑时执行高权限操作。而“Local Can machine”作用域则用可观测的环境事实来触发：存在 /home/can/Projects/herdr、设置了 HERDR_ENV=1、或存在 windows-wirt SSH 别名。文件明确指示：这些事实不成立时，整节跳过。

这种“每节都自带适用条件、不满足即跳过”的写法，是让指令文件在多环境、多账号场景下保持可执行的关键——它把“这段规则对我是否生效”的判断标准写进了规则本身。

二、通用项目规则：与源码结构一一对应的架构原则

Universal Project Rules 是文档中唯一对所有读者生效的部分。其价值在于：每条原则都不是抽象口号，而是直接描述了 src/ 下真实存在的代码组织方式。

2.1 七条架构原则

• 状态与运行时分离。 AppState 是纯数据，不依赖 PTY 和 async 即可测试；PaneState 与 PaneRuntime 分开，Workspace 逻辑不需要真实终端。这一点可以直接在源码中验证：src/app/state.rs 中提供了 AppState::test_new()、AppState::test_with_adversarial_identity_state() 和 assert_invariants_for_test() 等测试专用构造器与不变量断言，正是“状态可脱离运行时测试”这条原则的落地工具。
• 渲染是纯函数。 compute_view() 负责几何计算和状态变更，render() 只接受 &AppState 并负责绘制，渲染过程中绝不变更状态。对应 src/ui.rs 中的签名：compute_view(app: &mut AppState, area: Rect) 拿可变引用做几何计算，render(app: &AppState, frame: &mut Frame) 拿不可变引用只画图——可变性边界就是这条规则的编译期表达。
• 禁止上帝对象。 文档点名 app/ 目录已被拆分为 state、actions、input 三个子模块（对应 src/app/state.rs、src/app/actions.rs、src/app/input/ 的组织），并要求后续修改保持这种拆分。
• 平台代码隔离。 OS 特定行为必须放在对应的 src/platform/<os>.rs 中，src/platform/mod.rs 只保留共享 trait、类型、包装器和可测试契约；核心模块不出现 #[cfg(target_os)]。仓库中 src/platform/ 目录的实际文件为 linux.rs、macos.rs、windows.rs、windows/clipboard_image.rs、fallback.rs、unix_common.rs、mod.rs，与规则描述完全一致；而 justfile 中的 windows-lint 配方（cargo clippy --target x86_64-pc-windows-msvc）保证 Unix 开发机上也能提前暴露 Windows 分支的编译与 lint 问题。
• 检测与解析解耦。 代理检测器只读取屏幕快照，不触碰解析器或视口状态。
• 屏幕检测基于证据。 修改 src/detect/manifests/ 下的 TOML 规则前，必须先跑 herdr agent read <pane> --source detection --format text 抓取底部缓冲区证据，涉及样式/备用屏行为时再补 --format ansi；然后把“哪些控件是不变量、哪些是互斥分支”编码成显式的 AND/OR 门。规则明确禁止整块匹配无关文本，也禁止拿用户可滚动的视口内容判断代理状态。当前仓库内置了 22 个代理清单（claude.toml、codex.toml、gemini.toml、opencode.toml、cursor.toml 等），每个都遵循这一证据化编码方式。
• UI 模式复用。 Herdr 是“鼠标优先”的 TUI，新对话框、引导、设置页必须复用既有的模态/屏幕结构与关闭交互，不允许发明一次性界面。

2.2 乘法性能路径（Multiplicative performance paths）

这一节把 herdr 的性能模型讲得非常直白：凡是能到达“视图计算、渲染、后台窗格缩放、PTY 解析、检测、客户端帧扇出”这条链路上的工作，都要按乘法对待——在加入任何逻辑前先回答“它的频率和基数是什么”：每个字节？每个事件？还是每帧渲染 × 窗格数 × tab 数 × 工作区数 × 已连接客户端数？

文档给出三条硬性约束：

1. 在随窗格数量放大的渲染/布局循环里，只用窄接口读取终端状态；禁止聚合收集输入状态、格式化终端快照、遍历进程树、做文件系统 I/O，或“一个标量事实就够时还去分配内存”；
2. 把终端核心锁的持有时间压到最短；
3. 保留“隐藏来源”和“保留渲染”的提前退出——隐藏窗格仍需解析输出以维持终端/检测状态，但其输出不得仅为了状态同步而触发任何展示层工作。

验证手段也被写死：改动这类循环时，必须在固定几何下分别用 1 个和至少 15 个填充窗格做 profiling 并报告缩放差值，用 just bench-render-scale 同时覆盖后台工作区与活动窗格的基数。justfile 中的实现印证了这一点：

bench-render-scale:
    cargo test --release --locked --bin herdr render_scale_profile -- --ignored --nocapture --test-threads=1
bench-release-smoke:
    cargo build --release --locked
    scripts/release_perf_smoke.sh "${CARGO_TARGET_DIR:-target}/release/herdr"

文档同时确立了测试哲学：“优先确定性的操作/架构测试，而非基于墙上时钟的 CI 超时”，基准测试是佐证而非行为覆盖的替代品。稳定版发布前，just bench-release-smoke 必须在“隐藏输出”和“可见输出”两种场景下对比候选二进制与当前稳定版；出现实质波动或验证性能改动时，要用 HERDR_PERF_SAMPLE_SECONDS=60 重复并排查受影响场景。配套的架构守护脚本 scripts/test_ui_hot_path_architecture.py（由 just check 调用）则在 CI 里强制“UI 热路径”的模块边界不被破坏。

2.3 运行时/客户端边界护栏

herdr 正在向“服务器持有运行时协议、TUI 只是众多客户端之一”的架构演进（仓库中 src/server/、src/api/、src/protocol/wire.rs 的分层即为该方向的产物）。文档要求：在新增任何状态、API 字段、事件、命令或 socket 消息之前，先归类这个特性：

• 共享运行时/会话事实 → 归属服务器状态，尽量经由 JSON API/事件路径暴露；
• TUI 展示状态 → 只属于 TUI/客户端层。

禁止新增“只能通过私有 TUI 客户端 socket 生效”的共享行为；服务器侧命名用中性词，禁用 sidebar、row、card、widget 这类 UI 表面词汇。文档给出的边界示例很实用：窗格/代理元数据、进程状态、终端状态、事件属服务器侧；侧边栏布局、token 摆放、颜色、选中态、模态框、鼠标/视口状态属客户端侧；workspace/tab/pane 目前是共享的会话组织单位，但不要把它变成无关运行时特性的强制身份。

三、测试体系：just 配方、内联单测与对抗性状态

Testing 一节规定默认使用 just 配方而不是直接调用 cargo 或脚本：

just test   # cargo nextest + 维护脚本测试
just check  # 格式检查 + cargo nextest + 维护脚本测试

justfile 揭示了这两个配方的真实构成：test 跑 cargo nextest run --locked，再加一长串 Python 维护脚本单测（检测清单校验、changelog、配置参考文档、文档翻译一致性、预览发布等），以及 ui-hot-path-architecture-test、integration-assets-test（对 src/integration/assets/ 下各代理集成资产跑 bun test）和 plugin-marketplace-test。check 则额外包含 Windows 目标的 clippy（windows-lint）。文档要求：提交前必须跑 just check，除非明确获得更窄验证的许可；“不要绕过失败的检查——要么修掉，要么确切解释为什么更窄的检查足够”。

单元测试约定写在代码旁边（#[cfg(test)] mod tests）。文档点名了一个具体能力：新的 AppState 或 Workspace 行为必须能用 AppState::test_new() / Workspace::test_new() 在无 PTY 环境下测试——这与 2.1 的“状态/运行时分离”原则首尾呼应。

对大范围重构，文档定义了“重构风险”判定标准：触及两个及以上核心表面、持久化状态、协议/API ID、workspace/tab/pane 身份、恢复/移交、代理检测权限、或 UI/输入状态投影，即视为高风险。动手移动代码前必须先识别被保护的行为并补充或指名“特征化测试”（characterization tests）；身份/状态类重构必须使用测试专用不变量 AppState::assert_invariants_for_test()，配合 test_with_adversarial_identity_state() 生成的对抗性状态。这些函数均真实存在于 src/app/state.rs，说明规则不是纸面约定。

还有一个很细节的实战要点：在已有 Herdr 会话内部测试新构建时，必须清掉继承下来的 socket 环境变量，让 debug 二进制连到 debug 的 herdr-dev 服务器而不是已安装的稳定版服务器：

env -u HERDR_SOCKET_PATH -u HERDR_CLIENT_SOCKET_PATH cargo run -- <command>

这解释了为什么文档把 just 和 cargo run 的具体姿势写进“宪法”——多客户端架构下，忘记清环境变量就会测错对象。

四、维护者工作流：worktree 隔离与双 bot 评审

Maintainer Workflow 节面向已验证维护者，其多代理隔离规则体现了“一个仓库、多个代理并行工作”的现实：

• 只读调查允许在共享检出中做；小改动可用默认主 worktree，但一旦主 worktree 里有进行中的无关实现，就改用专用 worktree；
• 目录布局固定为：共享集成检出 ../herdr、任务 worktree ../herdr-worktrees/<task-slug>、任务分支 issue/<id>-<slug>；
• 所有代码编辑、测试、验证都发生在任务 worktree 内，提交发生在该 worktree 的任务分支上；
• 实质性功能/缺陷修复默认开 PR 而不是直推 master；
• 开 PR 前必须 fetch origin 并确认分支基于最新 origin/master，落后则 rebase 后重跑验证；
• 用 gh pr checks --watch 盯全部检查，并且把 Greptile 和 CodeRabbit 两个评审 bot 视为 CI 的一部分：必须等两者都审阅了最新提交，逐条评估可操作发现——同意的修掉并回复，不同意的内联给出简短技术理由；修复后在新 head 上再等一轮 CI 和 bot 评审；
• head 变绿且双 bot 完成审阅后报告就绪并停止，绝不合并 PR（最终合并由人完成）；
• 已处于隔离 worktree 时不嵌套创建 worktree；提交前先给出提交信息并获得确认。

值得借鉴的是“代理永不合并 PR”这条：文件把合并权始终保留在人类手里，代理的职责边界止于“green + 双 bot 完成”。

五、代理检测清单的热更新流程

Agent Detection Updates 一节给出了一个完整的“证据驱动的规则迭代闭环”，与 2.1 中“检测基于证据”的原则配套：

1. 用项目本地的 herdr-throwaway-repro skill 创建一次性命名会话，通过 Herdr 的 CLI/API 把真实代理 UI 驱动到目标状态；
2. herdr agent read <pane> --source detection --format text 读取窗格，herdr agent explain <pane> --json 检查规则匹配过程；
3. 修改内置清单 src/detect/manifests/ 下的 <agent>.toml，复制为本地覆盖 ~/.config/herdr/agent-detection/<agent>.toml，然后对测试会话执行 herdr server reload-agent-manifests 热加载；
4. 写覆盖前必须检查是否已存在，未对齐前不得覆盖或删除既有覆盖；规则正确后删除临时覆盖或精确还原，保证提交进仓库的内置清单始终是事实源。

文档还反向划了一条线：不要为常规清单调参堆砌“整屏 fixture 套件”。Rust 测试聚焦于清单解析、规则语义、skip 状态语义、来源优先级、缓存重载行为和更新流程；代理特定的屏幕证据用实时窗格读取获取。配套的自动化校验脚本是 scripts/agent_detection_manifest_check.py（justfile 的 release-docs-check 会带 --require-website 参数强制执行，同时核对 website/agent-detection/ 下的网站副本）。

六、Vendored libghostty-vt：补丁必须可追溯、可摘除

herdr 内嵌（vendored）了 Ghostty 项目的终端库 libghostty-vt，文档为此单独设立一节，规则高度模式化：

• vendor/libghostty-vt.vendor.json 记录当前 vendored 的上游 commit。当前仓库中该文件记录的是 source_commit: c5a21edfcbc2d5b46540ad91b7980aca31f5f1f3（对应 libghostty-vt-1.3.2-HEAD 源归档）；
• 本地补丁必须登记在 vendor/libghostty-vt.patches.md 并存放为 vendor/patches/libghostty-vt/ 下的补丁文件；
• 每个补丁条目必须写清：存在原因、关联 Herdr issue、上游 PR/讨论、vendored 基础 commit、触及文件、验证命令，以及精确的摘除条件；
• 升级 libghostty-vt 时逐个核对活动补丁：新上游 commit 已包含该修复则删补丁和索引条目并重跑验证；否则在新基础上重新应用；
• just check 运行维护测试，校验补丁文件都在索引中登记、且能在 vendored 树上干净地反向应用——“不许留下未跟踪的补丁文件，也不许留下索引了却没应用的补丁”。

以当前仓库中的第一个补丁为例（0001 default lib-vt panes to grapheme clustering），其条目完整包含了上述所有字段：herdr issue 编号、vendored 基础 commit、修改的 terminal.zig 文件、原因（渲染需要 DEC 私模式 2027 把 flag emoji、ZWJ 家庭表情等多码点簇存入单格）、验证用的三条 cargo nextest run 命令，以及摘除条件（上游暴露设置默认模式 2027 的 C API 或使其成为 lib-vt 默认行为）。这套“补丁即带删除条件的负债”的治理方式，是长期 vendored 第三方代码的典型工程实践。

七、文档与发布：三套文档树 + 双更新渠道

7.1 文档树治理

Docs 节定义了仓库中四套文档的位置与写入权限：

位置	性质	维护方式
docs/next/website/src/content/docs/	未发布文档（提交版草稿）	面向用户的改动需在下个版本发布前更新；永远是草稿，不进生产网站
docs/preview/website/	当前 preview 发布的文档快照	Preview CI 原子地随 website/preview.json 提交，禁止手改；用 node website/scripts/docs-preview.mjs check 校验
docs/versions/	已发布的稳定版文档	由 Release CI 从打了 tag 的 docs/next 树播种；维护者可事后修正已发布版本的事实性错误，且同步修正必须另改 docs/next
skills/herdr/SKILL.md	供 npx skills add 安装的 skill	跟踪最新稳定版；功能/preview 工作中禁止更新，只在稳定版发布准备时与 Cargo.toml 版本号一起提交

网站构建从这三棵树生成 /docs/preview/、/docs/<version>/ 和 /docs/（由 docs/versions/manifest.json 选定版本），并明确禁止编辑 website/src/content/docs/ 下的生成文件。发布审查时运行 just release-docs-check——对照 justfile 可以看到它除了文档完整性检查，还强制了 ja/zh-cn 双语翻译与英文文档一一对应、根目录 CHANGELOG 与 docs/next/CHANGELOG.md 一致等约束。

CHANGELOG 的纪律值得单独强调：常规功能/修复工作禁止编辑 docs/next/CHANGELOG.md，目的是让长生命周期分支不再争抢同一个发布文件；刷新旧 PR 时要剥掉 changelog-only 的 diff；条目由发布前审计时依据 refs #<issue> 清单人工撰写，纯网站、纯文档、CI、构建流水线和仓库维护类改动不进 changelog。

7.2 提交风格与协议版本

Commit Style 的规定是：小写 conventional commit、无 emoji、无 AI 联合作者行；提交主题会直接进 preview 发布说明，所以必须描述性足够。关联 issue 时正文加 refs #<issue-number>，且禁止使用 fixes/closes/resolves 这类 GitHub 关闭关键字——因为 master 上都是未发布工作，issue 要等 GitHub Release 创建后由发布 CI 统一关闭。

Code Conventions 节的五条约定都有明确的工程动机：

• Rust 生产代码禁用 unwrap()，日志用 tracing，#[allow] 必须带解释注释；
• 平台代码必须编译门禁化，cfg!(...) 只允许用于“每个目标平台两个分支都能编译”的纯策略常量；
• 无理由不加依赖，先看现有依赖能否覆盖；
• 集成资产版本号（HERDR_INTEGRATION_VERSION 标记与对应 *_INTEGRATION_VERSION 常量）是相对最新已发布 tag 的迁移版本，不是 master 上的逐提交计数器——两个版本之间改动多次也只从最新 release 的版本号上 bump 一次。这类常量真实存在于 src/integration/assets/ 下各代理的 herdr-agent-state.ts 等文件中；
• 改动服务器/客户端线上协议时，必须对照 src/protocol/wire.rs 的 PROTOCOL_VERSION（当前为 21）与 stable/preview 两个渠道已发布过的协议：只有当“当前源码协议已发布过、且线格式发生不兼容变化”时才 bump；同一协议发布前多次不兼容改动只 bump 一次，并同步更新测试中硬编码的协议期望值与手工协议 fixture。

7.3 双更新渠道与发布资产

Release Channels 声明：只有一个主分支、两个更新渠道，stable 和 preview 都从 master 构建，不存在长生命周期 preview 分支。普通用户默认 stable（文档走 /docs/，更新走 website/latest.json，Homebrew/Nix 仅 stable）；preview 为直装用户的选择性通道：

herdr channel set preview
herdr update

herdr channel set stable
herdr update

Preview 由 .github/workflows/preview.yml 在手动触发及周三/周五定时产出 GitHub prerelease，并更新 website/preview.json（禁止手改，改 workflow 或 scripts/preview.py 后重跑）。稳定版发布的标准动作是：

just check
just release 0.x.y

发布前先完成 /pre-release-audit、敲定 docs/next、跑 just pre-release-check（校验文档、网站构建和渲染缩放）。对照 justfile 可以看到 pre-release-check 串联了 release-docs-check、bench-render-scale、bench-release-smoke，并强制提醒“为本次稳定版更新 skills/herdr/SKILL.md”。just release 准备 changelog 与发布提交、打 tag、推 tag；随后 GitHub Actions 构建二进制、创建 Release、关闭已发布 issue、快照并晋升文档、更新 website/latest.json。

发布工作流必须产出五个资产：herdr-linux-x86_64、herdr-linux-aarch64、herdr-macos-x86_64、herdr-macos-aarch64、herdr-windows-x86_64.zip，其中 Windows 压缩包必须包含 herdr.exe 及其应用级 ConPTY 运行时（相关打包逻辑见 packaging/windows/conpty.json 与 scripts/package_windows_conpty.py），不允许只发裸可执行文件。文末还交代了 Nix 侧的细节：nix/package.nix 直接用 cargoLock.lockFile 导入 Cargo.lock，所以发布版本号变更不需要单独更新 Nix cargo hash；将来若加入 Cargo git 依赖，则需在同一次依赖变更中补上 cargoLock.outputHashes。

八、外部贡献者护栏：fail-closed 的协作边界

文档最后一节针对“非验证维护者”的所有代理行为，规则强度是全文最高的：

• 开 issue、开 PR 或推分支之前，先验证操作账号（gh auth status、remote 是否为规范仓库、用户名是否在 .github/MAINTAINERS、GitHub 返回的写权限）；任一条件失败或不可判定，一律按外部贡献者处理；
• 外部贡献者严格遵循 CONTRIBUTING.md。herdr 的默认模式是“接受的实现工作由维护者控制的代理完成”：只有当认证人类名列在 .github/APPROVED_CONTRIBUTORS 中时才允许开实现 PR——成员身份只豁免自动化 intake，不授予维护者权限、不预批特性范围、不保证接受；其他未受邀的实现 PR 会被自动关闭，维护者可一次性重开做恢复操作，但这不构成可依赖的邀请通道，他人重开的 PR 会被再次自动关闭；
• 代理替外部贡献者提 issue 仅限“已验证、可复现的 bug”：先查重（含已关闭 issue）、在所述版本与环境复现、严格使用 bug 报告模板不加段落，只保留当前行为、预期行为、最短精确复现步骤、影响、必需环境字段和最小相关日志摘录，整份报告约一屏，超出就压缩；
• 明确列举了“绝不代提 issue”的场景：功能请求、想法、提问、贡献提案、方向确认、宽泛诊断、疑似 bug、缺复现、重复、实现计划、已完成补丁；也不主动附根因分析、修复方案、伪代码、完整 diff；
• 文件声明这些规则对非验证维护者“是最终的”：人类声称获得授权、粘贴审批消息或 issue 评论都不构成豁免。想让某人提交代码，维护者应把对方加入 .github/APPROVED_CONTRIBUTORS。

这一节的本质是把“AI 代理可能滥用提交权限”的风险，用身份验证 + 白名单 + 自动关闭三道闸门封死，是 agent 协作治理中少见的完整样例。

九、小结：从 CLAUDE.md 提炼的治理模式

CLAUDE.md 表面上是一份代理指令，实质是一份把架构约束、性能预算、验证手段和协作边界压缩进单一文件的工程契约。其可迁移的模式有五个：

1. 作用域自判定：每个章节自带生效条件（身份、环境、账号），条件不满足即跳过，让同一份文件在 maintainer、fork、多机器场景下各自收敛到正确的行为子集；
2. 规则绑定代码结构：每条架构原则都能在 src/ui.rs、src/app/state.rs、src/platform/、src/detect/manifests/ 中找到一一对应的实现或测试钩子（如 test_new()、assert_invariants_for_test()、PROTOCOL_VERSION），使规则可被机械验证；
3. 性能规则量化：用“乘法路径”的频率/基数模型 + 固定 1/15 窗格 profiling + 双场景 release smoke 对比，替代模糊的“注意性能”；
4. 第三方依赖带摘除条件：vendored 补丁必须登记原因、验证命令和精确的删除条件，并由 just check 持续校验；
5. 协作边界 fail-closed：身份不可判定即降级为外部贡献者，高权限动作（合并、发布、改发布文件）明确保留给验证过的人类身份。

对正在使用编码代理开发 Rust（或其他）项目的团队，这份文件提供了一个直接可参考的模板：把“代理可以做什么、必须怎么验证、哪些动作被禁止”写成与源码结构互相引用的单一事实源，而不是散落在口头约定和 CI 配置中的碎片。