企业官网建设流程全解析

GitButler 仓库 Agent 协作指南：Repo Map、指令优先级与分层规范体系全解读

【免费下载链接】gitbutlerThe GitButler version control client, backed by Git, powered by Tauri/Rust/Svelte项目地址: https://gitcode.com/GitHub_Trending/gi/gitbutler

GitButler 是一个以 Git 为核心、由 Tauri/Rust/Svelte 驱动、并同时维护 Electron/React 客户端与butCLI 的 monorepo 版本控制项目。本篇文章以仓库根目录的 claude.md（与 AGENTS.md 内容一致）为骨架，完整解读其中的指令解析优先级、Repo Map 目录地图与工作风格要求，并结合crates/、apps/lite/下的分层指令文件，说明 Agent（或 AI 编码助手）应当如何在这样一个多语言、多前端栈的大型仓库中定位模块、遵守规范、编写测试并安全提交代码。读完本文，你将掌握 GitButler 仓库对 Agent 的全部硬性约束与实操入口。

一、指令体系的解析优先级：冲突时听谁的

claude.md的开篇明确定义了 GitButler 仓库的 Agent 指令层级。当多个指令文件的内容发生冲突时，必须按下述顺序裁决：

1. 显式的人类指令（Explicit human instructions）——优先级最高，即用户直接下达的、与文件指令冲突的要求，以用户为准；
2. 最近的嵌套AGENTS.md（Nearest nestedAGENTS.md）——即距离当前工作目录最近的、作用域更细的AGENTS.md，例如crates/AGENTS.md之于crates/下的 Rust 代码、apps/lite/AGENTS.md之于 Lite 客户端代码；
3. 本文件（claude.md/ 根目录AGENTS.md）——作为全局兜底默认。

这一设计的本质是"作用域越窄、约束越具体、优先级越高"：全局文件只描述仓库地图与通用工作风格，而把 Rust、Lite、CLI 等子域的具体规范下沉到各自目录，避免单个巨型指令文件互相打架。从仓库文件布局可以验证这一点：根目录下同时存在AGENTS.md与claude.md（内容一致），crates/下存在 crates/AGENTS.md 与 crates/CLAUDE.md，apps/lite/下存在 apps/lite/AGENTS.md 与 apps/lite/CLAUDE.md，crates/but/下还有更细的 crates/but/AGENTS.md。同一目录下的 AGENTS 与 CLAUDE 文件互为镜像，说明这是同一套规范为不同 Agent 工具提供的双份入口。

二、Repo Map：一张图定位整个 monorepo

claude.md用六个顶层目录概括了整个仓库的物理结构，这也是 Agent 进入仓库后首先要建立的全局认知：

从仓库实际结构看，crates/下的 crate 命名清晰地划分了分层职责：but-api是所有调用方（Tauri、Electron/N-API、CLI、TUI）共享的 API 表面层；but-*系列（but-workspace、but-graph、but-rebase、but-db等）是新一代领域实现；而gitbutler-*系列（如gitbutler-branch、gitbutler-repo）属于 legacy 边界。apps/lite/内部还细分为electron/、harness/、ui/与e2e/，其中ui/下的src/包含 155 个.tsx组件与 164 个.ts文件，是 React 前端的核心资产。

对于 Agent 而言，这个 Repo Map 的意义在于：改动前先判断自己落在哪一层——是 Rust crate、桌面 Svelte UI、Lite React UI，还是共享 TS 包——再决定遵守哪一份作用域规范、运行哪一条验证命令。

三、Working Style：改动前的六条行为基线

claude.md的 Working Style 部分是所有子域规范之上的通用底线，逐条展开如下：

• 只读优先：把关于代码库的问题视为只读操作，除非用户明确要求修改，否则不擅自改动文件；
• 聚焦可审查的改动：只做与当前任务直接相关的修改，避免无关重写（unrelated rewrites）；
• 最简设计：使用能解决实际问题的最简方案，不添加投机性机制，并删除因改动而不再需要的旧机制；
• 先看邻近代码：引入新模式前，先检查附近的既有代码，优先复用现有 API、测试与约定；
• 多端契约同步：在宣布共享行为完成之前，必须逐一检查 desktop、web、Lite、CLI/TUI、N-API、SDK 与文档这些受影响面，要么更新对应实现，要么明确论证其不受影响——这正是 monorepo 中共享代码改动的最大陷阱；
• 以测试驱动修复：修复行为 bug 时，先写一个可复现失败的测试，再审视目标文件中的既有循环与分类逻辑作为候选宿主，让测试（而非先入为主的诊断）决定修复需要多少实现量；若修复需要新机制（新模块、新公共 API 或并行的遍历逻辑），先提出设计轮廓再动手实现。

这几条基线在仓库中都有可验证的落点：例如共享 SDK 契约的同步体现在 crates/AGENTS.md 中"修改经@gitbutler/but-sdk暴露的 Rust API 后必须运行pnpm build:sdk && pnpm format以更新packages/but-sdk/src/generated"的硬性要求；"以测试驱动修复"则与crates/but/tests/下大量基于env.but(...).assert()的 CLI 快照测试相呼应。

四、Scoped Instructions：两条作用域入口

claude.md给出的作用域指令只有两条，却分别指向两份内容详实的子规范：

• Rust 相关改动遵循 crates/AGENTS.md；
• Lite 相关改动遵循 apps/lite/AGENTS.md。

值得注意的是，仓库中实际存在的指令文件远比这两条多：crates/but/下还有针对butCLI 的 crates/but/AGENTS.md，以及针对内置 skill 编辑的 crates/but/skill/AGENTS.md。它们都是"最近的嵌套 AGENTS.md"规则的自然延伸——作用域越小，约束越具体。

五、纵深一：Rust 侧规范（crates/AGENTS.md）的核心约束

crates/AGENTS.md（与 crates/CLAUDE.md 镜像）是 Rust 开发者的主战场规范，其要点可归为五类：

API 边界与 legacy 策略：gitbutler-*crate 被明确标注为"legacy-heavy"，局部修复时应保留其所有权结构与邻近模式，不引入新的gitbutler-*用法；but-api是 Tauri、Electron/N-API、CLI、TUI 共用的 API 表面，外层调用方优先复用既有but-api函数，但底层 crate 不得反向依赖but-api。传输层 DTO 应留在 API 边界（常见于各 crate 的本地json模块），在调用底层 crate 前转换为领域类型。涉及权限的函数遵循既有组合形态：在 wrapper 附近获取权限，委托给_with_perm实现；已持有 guard 的调用方应使用_with_perm变体以避免重复加锁与死锁风险。

图/工作区模型参考：任何涉及 graph/workspace/branch/stack/commit 关系、可达性、依赖、排序、操作目标或 Git 图/历史/ref 放置变更的改动，必须先以 crates/WORKSPACE_MODEL.md 为参考。其简版原则是：API 边界优先使用 commit ID 与 ref；编辑器支撑的操作内部转换为操作局部选择器；关系/可达性问题使用but_graph::Graph；Git 图/历史/ref 重写优先使用but_rebase::graph_rebase::Editor；but_graph::Workspace与but_workspace::RefInfo仅是展示/兼容视图。

Git 仓库语义：业务逻辑中不自行"重新发现"仓库，显式传递 repo/context；优先使用仓库 API 而非 shell 调git（hook、调试工具、测试等 shell/可执行边界除外）；新仓库逻辑统一用gix，git2与Context::git2_repo仅作为 legacy/边界逃生口；Git 路径、refname、提交信息与 diff 载荷在到达 UI/API 边界前保持字节级原样，避免有损的String转换；可测试业务逻辑中避免隐式SystemTime::now()，需要确定性时显式传入时间；错误处理使用anyhow::Context说明失败原因，需要前端分类时使用既有but_error::Code模式，禁止让消费者匹配错误字符串。

数据库迁移（but-db）：迁移必须保持前向兼容，停留在当前SchemaVersion，被新代码弃用的列/表保留原位；提升版本号会锁死所有旧二进制，只留给计划内、协调好的破坏性变更，绝不用于日常清理。

版本控制与提交：假设工作区可能含有其他 Agent 的改动，不覆盖、不清理、不暂存、不提交、不 amend 非自己产生的改动；需要分支/提交/push/开 PR 时优先使用 GitButler 自带的butCLI 工作流；用户说 "ship it" 时在会话分支上提交（必要时新建）、push 并打开或更新 PR，能复用既有分支/PR 就复用；自己分支上的小清理用 amend 更整洁；提交信息与 PR 描述保持简洁——只写 why、impact 与核心决策，不列出本地验证命令，不加 AI co-author 尾注或工具品牌标识。

测试与验证：先跑最窄的相关测试，例如cargo test -p <crate> <test-name>或cargo check -p <crate> --all-targets；图/rebase/工作区行为优先使用 fixture 支撑的前后快照对比加结构化断言；快照输出不稳定时应稳定输入或归一化输出，而非用含糊断言替代强快照；cargo fmt负责格式化且避免污染无关文件；cargo clippy --fix --allow-dirty仅在检查 diff 范围后才使用；依赖变更后运行cargo machete。断言部分还有两条细则：普通断言用末位消息参数说明其成立原因（如assert!(1!=2, "arithmetic unit on CPU works")）；快照断言使用snapbox::assert_data_eq!并以行上// comment说明快照为何成立，用SNAPSHOTS=overwrite重新生成内联快照，断言前先剔除不稳定输出（id/时间戳/路径，可借助but_testsupport的辅助函数），需要精确匹配时给snapbox::str!追加.raw()。

六、纵深二：Lite（Electron/React）侧规范（apps/lite/AGENTS.md）的核心约束

apps/lite/AGENTS.md（与 apps/lite/CLAUDE.md 镜像）规定了 Lite 前端的工程纪律，特色鲜明：

Memoization 与状态管理：由于项目使用 React Compiler，useMemo、useCallback、React.memo通常冗余，仅在编译器无法判定计算为纯函数的热路径上才需要，且必须直接对照 React Compiler 验证其 memo 属性；规避此问题时，仅事件时需要的 Redux store 值优先用useAppStore而非useAppSelector订阅，React Query 同理；useEffect被明确视为反模式，除非反复论证后确实最优并征得同意，否则不引入。

数据获取与持久化：React 中的数据获取统一走 React Query，需要抽象时先从提取 query options 开始；所有非设置类的持久化客户端状态应存放在 IndexedDB；任何持久化状态都要考虑向后兼容。

图标工作流：仓库存在两套图标集、两套独立脚本，且互不越界——Lite 图标位于apps/lite/ui/src/components/icons/*.svg，归属pnpm -F @gitbutler/lite optimize-icons；共享 Svelte UI 图标位于packages/ui/src/lib/icons/svg/*.svg，归属pnpm -F @gitbutler/ui optimize-ui-icons。把 SVG 放进错误的目录是图标"无法优化"的最常见原因；文件图标（ui/src/components/file-icons/）刻意不跑任何脚本，因为统一重着色为currentColor会毁掉它们。新增 Lite 图标的流程是：从 Figma 以 16×16 导出 SVG → 以 kebab-case 命名存入ui/src/components/icons/（文件名即图标名，folder-lock.svg→<Icon name="folder-lock" />）→ 运行pnpm -F @gitbutler/lite optimize-icons→ 同时提交 SVG 与重新生成的ui/src/components/iconNames.ts。iconNames.ts是生成文件，禁止手改；图标以原始字符串内联进 bundle 并通过dangerouslySetInnerHTML注入，这正是脚本要压缩它们的原因。底层脚本为 apps/lite/scripts/optimize-icons.mjs，幂等可随时重跑，其头部注释记录了每个变换及其无法修复的导出问题。视觉规范本体在 apps/lite/DESIGN.md，改动任何用户可见内容前必须先读。

验证命令：Lite 开发态可通过 CDP 在 9222 端口自动化访问；验证命令必须原样执行——类型检查pnpm -F @gitbutler/lite check；单元测试用 Vitest、E2E 用 Playwright，分别对应pnpm -F @gitbutler/lite test与pnpm -F @gitbutler/lite test:e2e；功能完成后依次运行pnpm oxlint:fix、pnpm knip:prod、pnpm knip:non-prod、pnpm exec oxfmt apps/lite、pnpm exec prettier --write apps/lite。

七、纵深三：but CLI 与内置 skill 的专项规范

crates/but/下的两份指令进一步展示了"最近嵌套 AGENTS.md"的极致细分：

crates/but/AGENTS.md（与 crates/but/CLAUDE.md 镜像）针对butCLI 开发：新命令的写法参考cli-commandsskill；部分命令在crates/but/src/args/定义了ERROR_EXAMPLES，解析出错时展示，改动参数时必须同步更新；doc 注释会经but skill reference打印给 Agent 阅读，因此要先说命令做什么，并在"省略参数在终端与非交互运行下行为不同"时同时说明两种情况；仅终端（TUI 或编辑器）下才有效的 flag 加help_heading = "Interactive"。工作树 guard 必须在操作顶部获取并把派生权限沿调用链下传，优先使用*_with_perm(...)；怀疑工作树锁死锁时，用调试构建并设置BUT_WS_LOCK_DEBUG=1让重复获取 guard 直接 panic 而非无限阻塞，配合 backtrace 定位嵌套获取点，例如：

BUT_WS_LOCK_DEBUG=1 RUST_BACKTRACE=1 cargo run -p but -- -C <repo> <command>

CLI 测试方面：crates/but/tests/优先使用env.but(...).assert().success()/failure()配合stdout_eq/stderr_eq快照断言，用[..]/...通配不稳定片段而非削弱断言；用SNAPSHOTS=overwrite cargo test -p but更新快照（尽量限定测试名），彩色终端输出断言用snapbox::file!["snapshots/<test-name>/<invocation>.stdout.term.svg"]；用沙箱辅助函数env.invoke_bash(...)/env.invoke_git(...)代替直接std::process::Command::new("git")；避免env.but(...).output()后直接断言 stdout/stderr；测试内用assert!/assert_eq!/assert_ne!等 panic 型断言而非anyhow::ensure!。改动 CLI 命令或工作流后，还要同步更新crates/but/skill/下的捆绑技能。

crates/but/skill/AGENTS.md 则规定了内置 skill 的编辑纪律：SKILL.md与references/会原样安装进用户的 Agent 环境，写错一行会误导所有用户仓库中的所有 Agent；只有SKILL_FILES（定义于crates/but/src/command/skill/mod.rs）列出的文件才会随包发布，新增 reference 文件必须先在此注册；stub.md是单文件 stub 安装的正文，只指向but skill命令。四条铁律：绝不记录任何会阻塞在 TTY 上的操作（编辑器或交互选择器会永久挂起 Agent，必须给出-m、--no-message、-F、-t、--yes等非交互形式，并对裸but push这类"省略一个参数就会阻塞"的变体明确点名警告）；绝不记录未经观察验证的内容（构建 CLI 并在临时仓库实测，用E2E_TEST_APP_DATA_DIR指向临时目录以免污染真实数据，示例输出同样是主张，需要证据）；绝不记录 Agent 不应运行的命令（crates/but/src/args/中hide = true的子命令与 flag，以及 TUI/GUI 表面）；绝不提及--format json或其他输出格式。另外，version: 0.0.0必须原样保留（inject_version会在安装时字符串替换它），frontmatter 的description必须小于 1024 字符（超出后 Codex 直接丢弃、Claude Code 截断，技能会失去触发文本且无任何报错）。

八、总结：一份可复用的 monorepo Agent 协作范式

从 claude.md 出发，GitButler 仓库给出了一套完整、可复用的 Agent 协作范式：一条优先级裁决链（人类指令 > 最近嵌套 AGENTS.md > 全局文件）让多份规范并行不悖；一张 Repo Map让 Agent 秒级定位 Rust/Tauri/Svelte/Electron/React/SDK/E2E 各层资产；一组工作风格基线约束改动范围、设计与验证方式；层层递进的作用域规范把 Rust 语义、Lite 前端纪律、CLI 开发流程与 skill 编辑细节分别沉淀在离代码最近的目录中。对任何准备为 GitButler 贡献代码或为其编写 Agent 集成的开发者而言，按"先读全局、再读作用域、最后跑最小验证"的顺序进入仓库，是成本最低、正确率最高的路径。

【免费下载链接】gitbutlerThe GitButler version control client, backed by Git, powered by Tauri/Rust/Svelte项目地址: https://gitcode.com/GitHub_Trending/gi/gitbutler