GitButler 仓库 Agent 协作指南Repo Map、指令优先级与分层规范体系全解读【免费下载链接】gitbutlerThe GitButler version control client, backed by Git, powered by Tauri/Rust/Svelte项目地址: https://gitcode.com/GitHub_Trending/gi/gitbutlerGitButler 是一个以 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 指令层级。当多个指令文件的内容发生冲突时必须按下述顺序裁决显式的人类指令Explicit human instructions——优先级最高即用户直接下达的、与文件指令冲突的要求以用户为准最近的嵌套AGENTS.mdNearest nestedAGENTS.md——即距离当前工作目录最近的、作用域更细的AGENTS.md例如crates/AGENTS.md之于crates/下的 Rust 代码、apps/lite/AGENTS.md之于 Lite 客户端代码本文件claude.md/ 根目录AGENTS.md——作为全局兜底默认。这一设计的本质是作用域越窄、约束越具体、优先级越高全局文件只描述仓库地图与通用工作风格而把 Rust、Lite、CLI 等子域的具体规范下沉到各自目录避免单个巨型指令文件互相打架。从仓库文件布局可以验证这一点根目录下同时存在AGENTS.md与claude.md内容一致crates/下存在 crates/AGENTS.md 与 crates/CLAUDE.mdapps/lite/下存在 apps/lite/AGENTS.md 与 apps/lite/CLAUDE.mdcrates/but/下还有更细的 crates/but/AGENTS.md。同一目录下的 AGENTS 与 CLAUDE 文件互为镜像说明这是同一套规范为不同 Agent 工具提供的双份入口。二、Repo Map一张图定位整个 monorepoclaude.md用六个顶层目录概括了整个仓库的物理结构这也是 Agent 进入仓库后首先要建立的全局认知目录技术栈定位crates/Rust核心后端包含butCLI、but-api、but-workspace、but-graph、but-rebase、but-db等数十个 crateapps/desktop/Tauri Svelte TypeScript桌面客户端通过 Rust 后端提供 GUIapps/web/SvelteWeb 应用apps/lite/Electron React TypeScript另一套轻量桌面客户端Litepackages/TypeScript共享包包括gitbutler/but-sdkSDK 等e2e/TypeScriptPlaywright、WebdriverIO 与 blackbox 端到端测试从仓库实际结构看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.mdLite 相关改动遵循 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::GraphGit 图/历史/ref 重写优先使用but_rebase::graph_rebase::Editorbut_graph::Workspace与but_workspace::RefInfo仅是展示/兼容视图。Git 仓库语义业务逻辑中不自行重新发现仓库显式传递 repo/context优先使用仓库 API 而非 shell 调githook、调试工具、测试等 shell/可执行边界除外新仓库逻辑统一用gixgit2与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说明快照为何成立用SNAPSHOTSoverwrite重新生成内联快照断言前先剔除不稳定输出id/时间戳/路径可借助but_testsupport的辅助函数需要精确匹配时给snapbox::str!追加.raw()。六、纵深二LiteElectron/React侧规范apps/lite/AGENTS.md的核心约束apps/lite/AGENTS.md与 apps/lite/CLAUDE.md 镜像规定了 Lite 前端的工程纪律特色鲜明Memoization 与状态管理由于项目使用 React CompileruseMemo、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 namefolder-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_DEBUG1让重复获取 guard 直接 panic 而非无限阻塞配合 backtrace 定位嵌套获取点例如BUT_WS_LOCK_DEBUG1 RUST_BACKTRACE1 cargo run -p but -- -C repo commandCLI 测试方面crates/but/tests/优先使用env.but(...).assert().success()/failure()配合stdout_eq/stderr_eq快照断言用[..]/...通配不稳定片段而非削弱断言用SNAPSHOTSoverwrite 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考