
Databend Agent 协作开发指南仓库工作流、AI 策略与提交规范【免费下载链接】databendData Agent Ready Warehouse : One for Analytics, Search, AI, Python Sandbox. — rebuilt from scratch. Unified architecture on your S3.项目地址: https://gitcode.com/GitHub_Trending/da/databend本文是 Databend 开源仓库Data Agent Ready Warehouse基于 Rust 多 crate workspace 的云原生数据仓库面向 AI 编码 Agent 与人类开发者的顶层协作指南解读。它系统讲解在 Databend 仓库中如何正确构建上下文、遵循提交意图、使用make命令链完成构建与验证以及 AI 辅助贡献必须遵守的人类问责与质量关卡。读完本文你将掌握 Databend 仓库的文档金字塔读取顺序、核心工作流原则、完整命令矩阵以及一套可落地的 AI 协助 PR 提交规范。CLAUDE.md 的定位仓库级 Agent 操作手册CLAUDE.md位于仓库根目录是整个仓库面向编码 Agent 的顶层操作指南它解决的关键问题是当 Agent 开始处理一个任务时应该按什么顺序建立上下文、遵循什么工作规则以及最终的产出物应该达到什么质量。它明确了文档的优先级原则先确认目标工作区域以及该分支最终会保留哪些产出物优先阅读更贴近具体模块的AGENTS.md仓库根目录、src/meta/AGENTS.md、src/query/AGENTS.md、tests/AGENTS.md均存在然后阅读agents/目录下的配套细节文档当维护者的明确指示与仓库文档或现行实践冲突时以维护者的显式指示为意图的第一来源。这一文档金字塔结构在 agents/agents-md-alignment.md 中有更完整的阐述AGENTS.md位于金字塔顶端agents/*.md补充细节与判断而由agents/*.md引用的文档则可以更偏向人类读者。agents-md-alignment.md还给出了评审AGENTS.md时的检查清单——顶层规则是否与维护者意图一致、是否与agents/*.md一致、是否与仓库实际实践一致、是否把硬规则与局部模式混淆。Core Workflow核心工作流的六条原则CLAUDE.md将 Agent 在仓库内工作的核心流程提炼为六条原则每条都直接对应 Databend 仓库的实际工程形态先建立代码库上下文。Databend 是一个多 crate 的 Rust workspace根Cargo.toml统一管理改动前必须先理解受影响模块的边界。这一点与 agents/repository-structure.md 的指引一致先判断改动属于查询引擎src/query/还是元数据系统src/meta/再阅读最近的模块 README而非仅凭目录名推断结构。PR 必须指定负责任的人类作者。Agent 可以直接开 PR但每个 PR 的 author 一侧必须有一名读过完整 diff、能解释改动、并能回答评审问题的真人。同时必须填写 PR 模板中的 AI assistance 部分。具体规则见 AI_POLICY.md 与 agents/commit-and-pr.md。默认做根因分析。仓库内的代码问题应尽最大努力做根因定位不能只在表面打补丁——只要合理调查能触及底层原因就不要止步于修症状。识别而非假设冲突。当指引、底层文档与仓库实践冲突或模糊时要明确指出影响当前决策的具体冲突点而不是默认某一份来源自动正确。增量验证。尽早运行最小的相关检查并把验证规模扩展到会保留在分支中、进入评审的部分。把测试视为变更的一部分。Planner、执行器、存储与行为类改动都应附带回归覆盖而不是把测试当作可选项。Submission Intent以留在分支、进入评审为质量标尺CLAUDE.md强调判断质量高低的标准是最终会保留在分支中并进入评审的部分而不是任务标签本身。这带来几个实操推论临时调查产出笔记、日志、测量数据、临时脚本只需要目的驱动的打磨但仍应得出正确结论一旦这些临时产出要变成保留在分支中的代码、测试或文档就必须在交接前提升到仓库的正常评审标准如果仓库已有相关模式遵循它不要把局部模式夸大成全局硬规则如果没有清晰模式要明确指出缺口、请求缺失的指引并用自己能辩护的最佳判断处理如果约束迫使只做部分修复要记录约束并让未解决问题保持可见。这套逻辑与 agents/debug-and-validation.md 中的临时调查产出与分支保留变更两档验证标准完全同构临时调查只跑足以得出结论的检查而一旦转入正式提交就切换到完整的提交级测试门槛。Common Commands开发命令矩阵CLAUDE.md给出了三个核心命令并与根目录 Makefile 中的真实目标一一对应命令作用Makefile 中的实现make build构建本地开发用的 debug 二进制调用bash ./scripts/build/build-debug.sh产出target/下的databend-{query,meta,metactl}make run-debug构建并启动本地 standalone 部署build后执行bash ./scripts/ci/deploy/databend-query-standalone.shmake lint运行格式化、clippy 与仓库 lintercargo fmt --all、cargo clippy --workspace --all-targets -- -D warnings、cargo machete未用依赖检查、typos、taplo fmt、shfmt -l -w scripts/*其他常用目标还包括make setup安装 cargo 组件及taplo、shfmt、typos、machete、ruff等 linter、make build-release、make unit-test、make stateless-test、make sqllogic-test、make metactl-test、make stateless-cluster-test含 TLS 变体stateless-cluster-test-tls以及make test默认 CI 测试矩阵unit-test → stateless-test → sqllogic-test → metactl-test。更多命令与选择指引见 agents/development-commands.md。Repository Gotchas仓库注意事项CLAUDE.md特别提醒整个 workspace 的干净全量构建大约需要 20 分钟。因此推荐的策略是优先跑最小的相关构建或测试步骤然后在交接前逐步扩大验证规模。这与 Makefile 中lint先跑cargo fmt再跑 clippy 的先快后慢节奏一致也与 agents/debug-and-validation.md 的先部分验证、交接前加强覆盖原则呼应。Detail Index配套文档索引解读CLAUDE.md末尾维护了一份配套文档索引是深入仓库协作规则的入口文档主题AI_POLICY.mdAI 辅助贡献规则人类问责、声明机制、什么情况会被关闭 PRagents/repository-structure.mdworkspace 布局代码、测试、工具与 fixtures 存放位置agents/development-commands.md安装、构建、运行、测试、格式化与 lint 命令agents/coding-style.mdRust、Python、Shell 的命名、错误处理与可观测性约定agents/debug-and-validation.mdclippy 预期与测试策略agents/commit-and-pr.md提交格式、PR 要求与 Databend PR 模板示例agents/agents-md-alignment.md保持AGENTS.md与维护者意图、仓库实践、下层文档对齐如果重要开发或测试指引缺失且上述文档无法覆盖应当明确指出缺口、请求补充并在总结中保持该问题可见。AI 协作策略AI_POLICY.md 核心规则AI_POLICY.md 是CLAUDE.md引用的AI 辅助贡献规则主体其核心是五条原则AI 是普通工程工具——只要提升质量或速度就鼓励使用人类保持问责——谁开 PR 谁拥有这个变更正确性、安全性、兼容性、测试与后续修复理解是强制的——不能用自己语言解释的改动就不该提交评审者时间稀缺——把真正的评审负担转嫁给维护者的低质量 AI 输出通常会被关闭数据库语义需要证据——Planner、执行器、存储、meta 与 SQL 行为变更必须有能证伪实现的测试而不是凭感觉。允许探索代码库并形成根因假设、起草实现/重构/测试/文档/基准、生成候选设计供人比较、辅助格式化与机械编辑、开 PR 前协助本地评审。通常会导致关闭的行为无主自治贡献PR 没有能解释 diff 的真人、用 AI 对话替代思考把模型回复粘贴成对维护者的回答、Slop 提交编译不过、lint 失败、只镜像实现的假测试、混入无关重构的大 diff、许可证不兼容的粘贴代码、绕过协作规范跳过 issue/RFC 讨论、忽略 CLA/PR 模板/CODEOWNERS。人类问责要求与 AI 声明每个 PR——无论由谁产生——都必须有一名负责任的人类PR 作者或 bot PR 正文中点名的人其义务包括读过最终 diff 的每一行——没读过的代码不进评审diff 大到读不完就说明太大了要拆分能用大白话说明用户可见或开发者可见的问题能解释为什么这个方案对 Databend 架构是正确的能指出如果修复错了哪些测试或手工验证会失败回答评审问题时不把答复外包给模型转录承担生产风险兼容性、升级/迁移、性能与数据安全。PR 必须填写模板中的## AI assistance部分。有效示例来自 agents/commit-and-pr.md 与 .github/PULL_REQUEST_TEMPLATE.md## AI assistance - AI usage: An AI coding agent drafted the storage iterator patch; I reworked the error paths and added logic tests - Responsible human: your-actual-github-id - [x] The responsible human has read every line of this diff and can explain each change无实质性 AI 参与时写AI usage: None。声明只说明变更如何产生不降低人类责任对高风险区域catalog/meta、存储正确性、事务、planner 语义、安全边界维护者还可以要求作者做现场讲解。提交与 PR 规范落地agents/commit-and-pr.md 将提交规范细化到可直接执行Commit采用 Conventional 风格主题如fix(storage): avoid stale snapshot (#19174)或feat: support self join elimination (#19169)首行祈使句且不超过 72 字符每个 commit 只含一个逻辑变更集格式化与 lint 更新并入同一 patch。PR 标题允许类型为rfc、feat、fix、refactor、ci、docs、chore纯测试/CI 变更优先用ci可选 scope 只能含小写字母、数字与连字符如query、admin-status。PR 内容说明动机、实现要点与验证命令关联 issue/RFC遵循 .github/PULL_REQUEST_TEMPLATE.md 的复选框、验证与截图要求UI/SQL 计划/系统表变更需附截图或示例查询标注回滚风险迁移、配置开关、回填。Agent 开 PR必须先填 AI assistance 部分并指定负责任人类在打开或更新 PR 前把完整 diff 呈现给负责任人类阅读——不要请求评审任何人类没读过的代码。领域评审由 .github/CODEOWNERS 声明的 domain 所有者负责。编码风格与验证标准agents/coding-style.md 定义了与工具链强绑定的风格基线Rust遵循rustfmt.toml4 空格缩进、100 列宽cargo clippy -- -D warnings必须通过模块/文件用snake_case公开类型与 trait 用CamelCase错误处理优先使用common/exception的 helper可观测性场景使用tracingspan迭代风格上优先惰性迭代器链与借用迭代避免为了单次检查而collect()出Vec/HashSet避免仅为查看/过滤而克隆共享结构。Pythontests/下的 Python 工具需满足 Ruff 默认规则。Shell脚本需能通过shfmt -l -w往返格式化。测试与 fixtures 的前缀需与tests/suites/中现有数字序号保持一致。agents/debug-and-validation.md 进一步给出测试策略分支保留的变更在受影响 crate 内用#[cfg(test)]模块放单元测试集成行为放入相关 SQL 套件或 meta 测试框架如tests/metactl、tests/meta-kvapi每个 planner/executor/storage 变更在确定性场景下至少加一个回归 SQL 文件及期望输出涉及协调、事务或鉴权时使用 cluster 变体如make stateless-cluster-test与 TLS 模式新 fixtures 或配置在测试文档或行内注释中说明保证 CI 可复现。仓库结构与模块组织速览agents/repository-structure.md 给出了快速定位的框架这也是CLAUDE.md先建立代码库上下文原则的落点src/query/主查询引擎——SQL 解析、规划、优化、表达式求值、执行 pipeline、查询服务集成与表/存储面向行为全部汇聚于此改动 SQL 行为先读 src/query/README.mdsrc/meta/元数据侧——元数据类型、协议定义、兼容层、支撑工具与 meta-service 二进制涉及 catalog/schema 元数据、protobuf 兼容或databend-meta工具先读 src/meta/README.md注意core meta-service 实现已迁移到独立的databend-meta仓库src/common/共享 cratesrc/binaries/二进制入口tests/测试含tests/suites/的 SQL 套件与 sqllogic 用例benchmark/性能实验scripts/与docker/工具与部署辅助根Makefile列出受支持的顶层任务。结语CLAUDE.md的价值在于把在 Databend 这样的多 crate Rust 仓库中高效、安全地协作压缩成一份可执行的 Agent 操作手册先按文档金字塔建立上下文遵循根因分析与增量验证的工作流用make命令链完成构建与验证再通过负责任人类 AI 声明 回归测试三道关卡把 AI 辅助产出安全地送进评审。对任何希望以 Agent 或 AI 辅助方式向 Databend 提交代码的开发者这套规则既是效率指南也是质量底线。【免费下载链接】databendData Agent Ready Warehouse : One for Analytics, Search, AI, Python Sandbox. — rebuilt from scratch. Unified architecture on your S3.项目地址: https://gitcode.com/GitHub_Trending/da/databend创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考