dbt Core v2Rust 重写版的 AGENTS.md 开发规范全解为 AI 编码代理定制的工作流指南【免费下载链接】dbtdbt enables data analysts and engineers to transform their data using the same practices that software engineers use to build applications.项目地址: https://gitcode.com/GitHub_Trending/db/dbt导读本指南以 dbt Core v2Rust 重写版仓库根目录的 AGENTS.md 为骨架完整解读这份面向 AI 编码代理Codex CLI、Claude Code 等的项目级开发规范。你将掌握三类关键信息其一硬性规则——代码风格、Changelog 生成、cargo 命令的使用边界其二任务导向的下一步去哪看索引——adapter、telemetry/tracing、docs-server 三大任务域的入口文档与 crate 清单其三仓库的协作机制——CLAUDE.md符号链接、.agents/目录、嵌套 AGENTS.md 与.agents/skills/技能系统。读完本文无论是人工还是 Agent 参与 dbt-core 开发都能快速对齐仓库的提交纪律与代码约定。说明dbt Core v2 将核心逻辑从 Python 重写为 Rust仓库采用 Cargo workspace 组织全部核心 crate 位于 crates/ 目录。本文中所有相对路径均以仓库根目录为基准。一、AGENTS.md 是什么给 AI 编码代理看的项目宪法根目录的 AGENTS.md 是一份只有 44 行的精炼文件明确声明其读者是编码代理Codex CLI、Claude Code 等而非人类开发者。它的定位决定了它的行文风格指令化全部是祈使句规则Never manually create…、Always use changie new…不解释背景路径基准化文件与.agents/目录内的路径均相对于文件所在目录即仓库根目录克制化只在规则与索引层面给出约束深度的技术背景全部外置到.agents/子文档。两个值得注意的仓库细节CLAUDE.md是AGENTS.md的符号链接CLAUDE.md - AGENTS.md因此 Claude Code 与 Codex CLI 读到的内容完全一致规则单一来源仓库采用根 AGENTS.md .agents/任务文档 嵌套 AGENTS.md三级结构根文件负责总纲.agents/负责任务细分adapters.md、telemetry-tracing.md、dbt-docs-server.md各 crate 内部再以嵌套 AGENTS.md 补充局部纪律。这种设计对大型 Rust workspace 尤为重要单个 crate 的维护者可以把领域约束写进子目录的 AGENTS.md而不污染根文件。二、Hard Rules四条不可逾越的硬性纪律2.1 代码风格跟随 crate 既有模式拒绝炫技Follow existing code style and patterns in the given crate/module. Keep changes minimal and focused to the task at hand. Prefer simple, readable code over clever or complex solutions.三条规则对应三个层次兼容性跟随所在 crate/module 的既有风格而非全局统一风格、最小化改动聚焦于当前任务、可读性简单直白的代码优于巧妙复杂的解法。对 Rust 仓库来说这意味着修改crates/dbt-*任一 crate 时应先阅读该 crate 现有代码再动手避免引入与局部风格冲突的重构。2.2 Changelog禁止手写强制使用 changie这是整份文档中最具操作性的规则核心要点绝不手动创建或编写 changelog YAML 文件一律用changie new生成必须在仓库根目录执行必须携带完整 flags--kind、--body、--custom projectproject、--custom issuenumber、--custom authorhandle、--interactivefalse可选空字段issue、author的处理本地运行时应询问用户或传一个空格如--custom issue 随后编辑生成的文件把 替换为。官方给出的完整命令模板changie new \ --kind kind \ --body description \ --custom projectproject \ --custom issuenumber \ --custom authorhandle \ --interactivefalse仓库根目录的 .changie.yaml 为这条命令提供了完整上下文结合源码可进一步补充细节kinds变更类型Breaking Changes、Features、Fixes、Under the Hood、Dependencies、Security六种对应 changelog 中### {Kind}级别的分组标题custom 字段issue可选dbt-core issue 号多个以单个空格分隔与author可选不带的 GitHub 用户名二者在.changie.yaml中均声明为required: false输出位置变更文件写入 .changes/unreleased/最终渲染进根目录 CHANGELOG.md另有 CHANGELOG-fusion.md 记录内部版本线渲染规则changeFormat模板只对project dbt-core的变更渲染 issue 链接footerFormat模板自动生成 Contributors 章节——可通过环境变量FUSION_TEAM空格分隔的维护者 handle排除维护者并内置排除dependabot[bot]。2.3 运行开发命令永远限定 crate 范围Never run blanketcargocommands without-p crateunless explicitly asked. Avoid context pollution: dont paste long logs; prefer LLM-friendly JSONL output and short excerpts. Avoid full builds and full test runs during iteration; keep commands scoped and fast.三条命令纪律的价值在于缩短迭代回路所有 cargo 命令必须带-p crate限定目标 crate禁止裸跑全 workspace 的cargo build/cargo test输出要LLM 友好倾向 JSONL 输出与短摘要不粘贴长日志避免污染上下文窗口迭代期避免全量构建与全量测试保持命令小且快。这与.agents/telemetry-tracing.md中给出的 scoped 测试命令一脉相承见下文 4.4 节也与crates/dbt-tracing/AGENTS.md的验证命令cargo xtask check-llm -p dbt-tracing、cargo xtask test --llm --no-external-deps -p dbt-tracing共同构成限定范围的完整实践。三、Where To Look Next任务导向的查阅索引AGENTS.md 的核心实用价值在于下一步去哪看清单。它承认 Agent 无法一次读完整个仓库因此按任务域给出入口任务入口文档涉及 cratesAdapters.agents/adapters.mddbt-adapter、dbt-adapter-core、dbt-adapter-sql、dbt-auth、dbt-sql-keywords、dbt-adbcTelemetry/Tracing.agents/telemetry-tracing.mddbt-tracing、dbt-telemetry、dbt-common::tracing、vortex-client、vortex-events、proto-rustdbt-docs-server.agents/dbt-docs-server.mddbt-docs-server、dbt-index-core此外三条兜底规则尊重作者偏好可选/本地AGENTS.local.md修改过的子目录必须检查嵌套 AGENTS.md——仓库中已确认存在crates/dbt-adbc/AGENTS.md、crates/dbt-auth/AGENTS.md、crates/dbt-auth/src/snowflake/AGENTS.md、crates/dbt-tracing/AGENTS.md四份嵌套文件上下文不足时最后的手段是读 README.md 获取仓库总览与架构。四、三大任务域的纵深.agents/ 子文档内容详解4.1 Adapters垂直化架构与 crate 分层.agents/adapters.md 描述了 Core v2 与 v1 的本质差异——adapter 垂直化verticalized按 auth、增量物化、relation 配置等功能垂直切分各平台尽量共享代码、只实现差异部分。自底向上的 crate 栈dbt-adbc基于 Arrow ADBC 的底层数据库连接负责驱动安装/加载暴露Statement、Connection、Database原语。铁律绝不允许向此 crate 添加任何新方法/特性/功能唯一例外是 ADBC option key 常量如bigquery.rs、databricks.rs中的定义。平台差异应通过 ADBC database/connection/statement options 由应用层调优dbt-adapter-core极轻量 crate仅用于打破依赖向全代码库暴露AdapterType等广泛类型。同样避免新增内容dbt-adapter-sql语句切分、引号处理等 SQL 基础能力。所有 SQL 解析相关内容应在此以接收adapter_type参数的通用方法实现dbt-sql-keywords与dbt-adapter-sql类似的方言工具但专司关键字识别新关键字检测逻辑放这里dbt-auth校验profiles.yml并翻译为 ADBC 连接选项是dbt 认证世界到ADBC 认证世界的桥梁MUST NOT包含与此无关的内容。其嵌套 AGENTS.mdcrates/dbt-auth/AGENTS.md进一步强调此 crate 编码了认证语义AuthIR枚举与配置访问器承载的是语义真相任何清理型改动都可能造成行为回归同时要求保持零拷贝/借用数据设计优先str、Optionstr、Cowa, str并晚归一化——仅在最终外部边界做字符串转换与所有权分配。crates/dbt-auth/src/snowflake/AGENTS.md甚至记录了 Snowflake 认证中故意存在的 stub 行为如ADBC_STUB_PASSWORD用于 keypair/SSO 等场景满足下游 builder 的 username/password 形态并明确 OAuth 流程不得注入 stub 凭据——这类看起来像 bug 实则是有意设计的约束正是嵌套 AGENTS.md 存在的意义dbt-adapteradapter 逻辑的主战场内部再分三层见 4.2。4.2 dbt-adapter 的三层结构Adapter暴露adapterJinja 接口如adapter.execute()及RelationConfig、Column、Relation等 adapter 持有的 Jinja 对象负责把无类型的 Jinja 函数调用翻译成强类型的 Rust 调用。对应源码 crates/dbt-adapter/src/adapter/ 目录AdapterImpl被Adapter调用实现 dbt adapter API 的强类型方法。由于 v1 时代 API 有机增长这里存在多种做同一件事的路径理想情况下AdapterImpl是历史遗留 API 与跨平台共享实现之间的桥梁必要时通过match adapter_type分平台处理。其代码本质上驱动所有宏调用力求镜像 v1 的 dbt adapters。对应源码 crates/dbt-adapter/src/adapter/adapter_impl.rsAdapterEngine对dbt-adbc的更高级抽象按用户配置设置特定 options 后发起数据库调用是注入 query comments、tags 等连接/语句属性的一层。对应源码 crates/dbt-adapter/src/engine/含adapter_engine.rs、query_comment.rs等。adapters.md 还列出了 6 条 adapter 开发的硬性规则值得全文引用Unsupported adapter gate实验性 adapterpostgres、trino 等在 profile 加载时即被拦截本地运行或更新 goldies 时可设DBT_ALLOW_EXPERIMENTAL_ADAPTERSyes绕过CI 会自动设置No new deps未经许可绝不允许给任何 crate 新增依赖包括 workspace 依赖或兄弟 crateNo platform-specific types禁止BigqueryFoo/SnowflakeBar这类平台专有类型应写GenericFoo并match adapter_type。已有类似逻辑则加AdapterType检查并重命名为GenericXYZ全新逻辑可对未支持的平台unimplemented!()。共享类型示例见 crates/dbt-adapter/src/column/types.rs 与 crates/dbt-adapter/src/relation/relation_impl.rsJinja 到 Rust 类型转换的两层规则adapter.rs、relation_object.rs负责把minijinja::Value转换为 Rust 类型adapter_impl.rs、relation_impl.rs只使用强类型 Rust不得出现Value/ValueMapJinja 对象必须有测试实现impl Object或DynJinjaObject时须补jinja_assert()单元测试示例见 crates/dbt-adapter/src/relation/config_v2.rs在adapter_impl.rs中标注 v1 一致性引用为平滑 v1→v2 迁移需在adapter_impl.rs代码中标注上游 dbt-adapters Python 参考链接使用/adapters-annotate-referencesskill 完成修改宏未经用户明确允许不得触碰crates/dbt-loader/src/dbt_macro_assets 中的任何宏若确实修改须用现有测试套件补测试示例见 crates/dbt-loader/tests/自我评审提交给用户评审前先用/adapters-criticskill 评审自己的改动并迭代至通过。4.3 dbt-docs-server静态站点 浏览器内 DuckDB-WASM.agents/dbt-docs-server.md 描述了 Core v1dbt docs generate/dbt docs serve在 Rust v2 运行时中的继任者位于 crates/dbt-docs-server/。它的核心设计极其反直觉dbt docs generate生成静态站点没有服务端查询引擎也没有 HTTP API。crate 把 parquet 导出在 React SPA 旁边浏览器从 CDN 加载 DuckDB-WASM 并在本地执行所有查询输出目录可直接部署到任何纯静态文件宿主GitLab Pages、GitHub Pages、S3无进程、无状态关键约束完全不读manifest.json——Rust 侧和浏览器侧都不读。数据来自target/info_schema/vn/下的dbt information schemadbt.*.parquetviews.sql。导出器通过dbt-index-core::BackendDuckDbInfoSchemaBackend读取浏览器通过 HTTP 抓取同一批文件浏览器不编写视图 SQL只抓取并执行views.sql中的语句见 web/src/shared/data-sources/duckdb/viewsSql.ts保证页面查询的 relations 与旁边的 parquet 一致——在客户端写CREATE VIEW曾被认定为schema 的第二个定义而禁止dbt docs generate每次都会先编译它合成一次compile --write-index调用交给普通 phase pipelinebuild_index_for_docs见 crates/dbt-main/src/dbt_lib.rs再从元数据构建 information schemabuild_info_schema_for_docs因此新 clone 一条命令即可--no-compile可退出编译回到纯导出模式--compile作为隐藏 no-op 兼容 v1 脚本能力检测capability gatingcrate 只依赖dbt-index-core的公开 traits哪些 parquet 存在取决于索引如何生成因此特性是检测而非假设且检测发生在浏览器侧。例如has_column_lineage依据dbt.column_lineage是否有行来判断——因为 information schema 即使零行也会写出每个表以保证views.sql总能解析文件存在性与文件大小都不再是可靠信号。文档还提供了典型的本地验证循环可完整复现dbtd docs generate # 先编译再写入 target/ cd target python3 -m http.server # 无 SPA rewrite、无 ranges 的纯文件宿主需要列级血缘column lineage或想迭代导出器而避免每次都编译时可分开执行dbtd compile --generate-info-schema --static-analysis strict dbtd docs generate --no-compile关键经验最后一步是承重检查——http.server下能跑通GitLab Pages 上就能跑通。前端为 React 19 TypeScript Vite独立 pnpm 项目不属于任何 workspace使用HashRouterbase: ./保证任意子路径静态托管下深链刷新不 404后端为axumtokioarrow-arrayrust-embedsrc/server.rs是一个没有任何路由的路由器只有静态 fallback。4.4 Telemetry/Tracing结构化追踪与事件注册.agents/telemetry-tracing.md 首先给出决策树让 Agent 按任务性质选择入口通用追踪基础设施 →crates/dbt-tracing/AGENTS.md与crates/dbt-tracing/README.mddbt CLI 输出、日志格式化、middleware 行为、layer 组装、dbt fallback 属性 →crates/dbt-common/src/tracing/README.md结构化事件 schema、事件注册表、Arrow 属性 →crates/dbt-telemetry/README.md通过 Vortex 的匿名产品使用遥测 → 在crates/vortex-client/、crates/vortex-events/、crates/proto-rust/工作不要把 Vortex 工作当作dbt-tracing工作。架构边界被严格划分dbt-tracing通用结构化追踪库拥有数据层、记录信封、emit API、middleware/consumer traits、过滤器、通用输出层、Arrow 序列化与 OTLP 序列化dbt-telemetry拥有事件 schema、helper 实现、Arrow 属性形态与事件注册表dbt-common::tracing拥有 dbt 运行时集成——FsTraceConfig、init_tracing、dbt fallback 回调、面向用户的输出、dbt 专用 layer/middleware/formatterVortex 匿名遥测与上述结构化追踪/导出栈完全分离。crates/dbt-tracing/AGENTS.md将这一边界落实为实现规则crate 必须保持通用可复用不添加 dbt 事件 schema、CLI 配置、Fusion formatter、fallback 事件类型或匿名遥测边界处优先使用回调/traits 而非硬编码下游事件类型输出层保持通用由下游 crate 提供注册表、具体 Arrow schema、JSON 事件反序列化器等。常用工作流含可复现命令包括新增一个事件8 步编辑 crates/dbt-telemetry/include/dbtlabs/proto/public/v1/events/fusion/ 下的 proto → 重新生成 Rust 绑定生成代码已提交走 workspace proto codegen 任务→ 在crates/dbt-telemetry/src/schemas/增补 schema 实现 → 按需在crates/dbt-telemetry/src/impls/添加 helper → 在crates/dbt-telemetry/src/attributes/registry.rs注册 first-class 事件 → 仅在需要刻意公开的 Parquet 列时才更新crates/dbt-telemetry/src/serialize/arrow.rs→ 更新 registry 覆盖与 Arrow roundtrip 测试 → 运行dbt-telemetry的 scoped 检查/测试改动 CLI 或用户可见格式工作在 crates/dbt-common/src/tracing/formatters/ 与crates/dbt-common/src/tracing/layers/middleware 行为在crates/dbt-common/src/tracing/middlewares/测试在crates/dbt-common/src/tracing/tests/增改通用输出行为JSONL、Parquet、OTLP、pretty writer 在 crates/dbt-tracing/src/layers/源码中实际包含jsonl_writer.rs、parquet_writer.rs、otlp.rs、pretty_writer.rs、data_layer.rsArrow/JSON envelope/OTLP 序列化在crates/dbt-tracing/src/serialize/通用 layer 必须保持与 dbt 事件名、CLI 行为、Vortex 无关用 Jaeger 本地调试 tracesdocker run -d --rm --name jaeger -p 4318:4318 -p 16686:16686 \ cr.jaegertracing.io/jaegertracing/jaeger:2.10.0 OTEL_EXPORTER_OTLP_ENDPOINThttp://localhost:4318 \ cargo run -p dbt-sa-cli -- --export-to-otlp your-dbt-commands docker stop jaeger然后打开http://localhost:16686查看。注意命令要求带-p dbt-sa-cli与 AGENTS.mdcargo 必须限定 crate的硬规则一致CLI 入口对应 crates/dbt-sa-cli/跨 async/task/thread 边界的 span 传播用tracing::Instrument、Span::current().enter()或 crates/dbt-tracing/src/async_tracing.rs 中的辅助函数保留当前 span。文档还给出了有用路径速查与遥测测试全量扫命令cargo nextest run \ -E package(dbt-tracing) | package(dbt-common) | package(dbt-telemetry)其中关键路径包括proto 目录crates/dbt-telemetry/include/dbtlabs/proto/public/v1/events/fusion/、通用 emit helper crates/dbt-tracing/src/emit.rs、dbt emit 便捷封装 crates/dbt-common/src/tracing/dbt_emit.rs、通用数据层 crates/dbt-tracing/src/layers/data_layer.rs、通用 middleware/consumer traits crates/dbt-tracing/src/layer.rs、dbt layer 组装 crates/dbt-common/src/tracing/config.rs。五、.agents/skills/随附的 Agent 技能.agents/skills/ 目录存放项目自带的 Claude Code / Codex 技能skills已确认存在两个adapters-annotate-references在adapter_impl.rs中标注上游 dbt-adapters Python 参考链接时使用见 adapters.md 的 v1 一致性引用规则adapters-criticadapter 改动自我评审用评审通过后再提交给用户。这两个 skill 与.agents/*.md文档形成闭环文档定义做什么、为什么skill 提供如何自动执行。对于接入 Agent 工具的开发者可以把它们理解为仓库自带的领域专用插件。六、对开发者的实践建议进入任何 crate 前先读它的 AGENTS.md根文件只保证大方向crates/dbt-adbc/AGENTS.md、crates/dbt-auth/AGENTS.md、crates/dbt-tracing/AGENTS.md这类嵌套文件承载着看似可优化实则是行为契约的细节如 Snowflake 的ADBC_STUB_PASSWORD提交前走 changie 而非手写 YAMLchangie new的参数顺序与空字段处理传空格后替换为是仓库约定的标准流程kinds六选一projectdbt-core时 issue 链接才会渲染命令一律-p crate无论构建、测试还是运行 CLI都要限定 crate避免全 workspace 构建拖慢迭代改动 adapter 时优先通用化用GenericFoo match adapter_type而非平台专有类型并自觉运行/adapters-critic与jinja_assert()测试遥测与追踪改动先对号入座按决策树判断改动落在dbt-tracing通用、dbt-telemetry事件 schema/注册表还是dbt-common::tracingdbt 集成并注意新增事件走 proto → 生成绑定 → schema → registry的完整链路。七、小结AGENTS.md 用极短的篇幅把一个大型 Rust workspace 的 AI 协作约定压缩成了硬规则 任务索引两层结构硬规则管住代码风格、changelog 纪律与命令范围任务索引则把 adapter、遥测、docs-server 三大复杂域各自导向专门的.agents/文档与嵌套 AGENTS.md。对于希望接入 dbt-core 开发的 Agent 或人工开发者按这份文件的指引对号入座再深入对应子文档是成本最低、最不容易踩坑的路径。【免费下载链接】dbtdbt enables data analysts and engineers to transform their data using the same practices that software engineers use to build applications.项目地址: https://gitcode.com/GitHub_Trending/db/dbt创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
