ZenML 代码库的 AI 协作工程规范：CLAUDE.md 开发指南深度解读

ZenML 代码库的 AI 协作工程规范CLAUDE.md 开发指南深度解读【免费下载链接】zenmlZenML : One AI Platform from Pipelines to Agents. https://zenml.io.项目地址: https://gitcode.com/GitHub_Trending/ze/zenmlZenML 仓库根目录下的 CLAUDE.md 是一份面向 AI 编码助手Claude Code的工程规范文档但它实际上浓缩了整个项目的开发约定项目结构、代码风格、注释政策、质量门禁、依赖约束、测试与 CI 流程、分支管理和 PR 规范。读完本篇并结合仓库中的脚本与源码佐证你将掌握在 ZenML 代码库中进行开发、格式化、跑测试、提交迁移和发起 PR 的完整标准动作以及“哪些代码是公共 API、哪些边界不能越”的关键判断依据。CLAUDE.md 在仓库中的定位这份文档的开篇即点明项目定位ZenML is an extensible, open-source MLOps framework for creating production-ready ML pipelines.它不是给人看的入门教程面向人类贡献者的入口是 CONTRIBUTING.md而是一份规则契约让 AI Agent 在改动这个复杂代码库时遵循与人类维护者完全一致的约束。仓库中还有一份姊妹文件 AGENTS.md面向 Codex Agent两条规则线高度重合US English 拼写、Python 3.10、类型注解、Google 风格 docstring、私有方法边界等说明这些是全仓库统一执行的硬约束而非某个 Agent 的专属偏好。此外规则采用根目录总纲 子系统细则的分层结构。仓库内共有 9 个 AGENTS.md除根目录外还分布在文档与核心子系统中各自管辖一个目录的边界规则docs/book/AGENTS.md — 文档源文件、GitBook 约定、toc.md处理与链接检查src/zenml/cli/AGENTS.md — CLI 导入规则与 filter/client 耦合src/zenml/integrations/AGENTS.md — 集成 flavor 的导入规则src/zenml/models/AGENTS.md — 领域模型兼容性与过滤字段src/zenml/orchestrators/AGENTS.md — orchestrator ID 与动态 pipelinesrc/zenml/zen_server/AGENTS.md — FastAPI 路由、服务、错误处理与校验约定src/zenml/zen_stores/migrations/AGENTS.md — Alembic 迁移指导src/zenml/zen_stores/schemas/AGENTS.md — ORM schema 与 SQL 导入规则项目结构速览CLAUDE.md 给出的目录地图与仓库实际一致路径内容src/zenml/核心源码CLI、orchestrator、integrations、zen_server、zen_stores 等tests/测试套件tests/unit/单元、tests/integration/集成、tests/harness/测试脚手架docs/book/文档源文件examples/示例项目quickstart、e2e、llm_finetuning 等 20 余个scripts/开发工具脚本format.sh、lint.sh、迁移检查等环境准备安装、环境变量与文档查询开发模式安装开发环境的最基本动作是安装开发依赖集pip install -e .[dev].[dev]对应的依赖清单定义在 pyproject.toml 的[project.optional-dependencies]段包含 ruff、yamlfix、zizmor、mypy锁定1.18.2、pydoclint、pytest 系列插件、mkdocs 工具链等——这正是format.sh/lint.sh/lint.sh中各检查器能直接运行的前提。CLAUDE.md 同时强调项目推荐使用uv安装包CI 同样使用 uv理由是依赖解析更快更可靠且能解决 pip 处理困难或耗时长得多的依赖冲突。开发期环境变量以下环境变量在开发期反复使用其中最后两项是必须设置的变量作用ZENML_LOGGING_VERBOSITYDEBUG控制日志详细程度ZENML_ANALYTICS_OPT_INfalse禁用遥测分析MLSTACKS_ANALYTICS_OPT_OUTtrue禁用 MLStacks 分析AUTO_OPEN_DASHBOARDfalse阻止自动打开 DashboardZENML_ENABLE_RICH_TRACEBACKfalse禁用 rich traceback 格式化TOKENIZERS_PARALLELISMfalse避免 tokenizer 并行化告警ZENML_DEBUGtrue必设使用开发版分析服务器避免把遥测发到官方服务器CLAUDE.md 对ZENML_DEBUGtrue有一条容易被忽略的解释即使在 client-server 架构中你设置了ZENML_ANALYTICS_OPT_INtrue也必须设置ZENML_DEBUGtrue因为在客户端-服务端模式下是服务端控制客户端的 analytics 开关状态。通过 MCP 实时查询官方文档为避免 AI 在编码时幻觉出过时的 APICLAUDE.md 建议把 ZenML 官方文档注册为 MCP server基于 GitBook 的 MCP 端点HTTP 传输一条命令即可claude mcp add zenmldocs --transport http ZenML 文档 GitBook MCP 端点这里有两个关键前提该 MCP server 索引的是最新已发布版本的文档而非develop分支——如果你正在改一个尚未发布的新特性以源码为准完整配置细节和其他编辑器的替代方案参见仓库内的 docs/book/reference/llms-txt.md。代码风格与质量门禁US English 拼写所有代码、注释、docstring 和文档一律使用美式拼写initialize、stabilize、colorCI 通过typos工具强制执行配置位于 .typos.toml。注释政策解释 why而不是 what这是 CLAUDE.md 着墨最多的风格条款之一核心原则是为六个月后的读者写注释该用的地方复杂逻辑/算法、不显而易见的设计决策、业务规则/约束、API 目的/契约、边界情况不该用的地方变更跟踪式注释Updated from previous version、Refactored this section、复述代码显然含义的单行注释increment x。文档给出的正例/反例# Bad x x 1 # increment x # Good count 1另一条规则禁止用多行 banner 注释给类/函数分组应使用简洁的模块级 docstring 或拆分到独立模块# Bad Dataset Loaders class CSVLoader: ... class ParquetLoader: ... # Good (module-level docstring at top) Dataset loaders used by data ingestion (CSV, Parquet). class CSVLoader: ... class ParquetLoader: ...format.sh 与 lint.sh两条命令覆盖质量门禁提交前格式化bash scripts/format.sh。阅读 scripts/format.sh 可以看到它实际做的事情默认作用于src/zenml tests examples docs/mkdocstrings_helper.py docs/link_checker.py scripts也可传参指定目录ruff check --select F401,F841 --fix作为 autoflake 的替代品清理未使用的 import 和变量排除__init__.pyruff check --select I --fix排序 importruff format格式化用yamlfix标准化.github与tests下的 CI YAML排除若干特定工作流文件若未跳过版本检查--no-upgrade会用uv pip install .[dev] --dry-run --upgrade比对本地 ruff/yamlfix 与锁定的版本版本过旧会直接警告可能导致 CI 失败——这是一个防止本地通过、CI 挂掉的实用设计。质量检查bash scripts/lint.sh。与 format.sh 不同它不自动修复只报告问题。从 scripts/lint.sh 的实现可确认完整检查链ruff check对src/zenml tests/harness对tests examples额外--extend-ignore D放宽 docstring 规则并排除 notebookpydoclint校验src/zenml tests/harness的 docstring 与签名一致性未使用 import/变量检查与ruff format --checkmypy对整个src/zenml tests/harness做类型检查yamlfix --check检查 YAML 格式zizmor检查 GitHub Actions 工作流的安全问题SHA pinning、版本不匹配等需要GH_TOKEN。CLAUDE.md 特别提示mypy 全量检查很慢针对单个文件可以直接跑mypy src/zenml/path/to/file.py加速。底层风格参数由 pyproject.toml 的[tool.ruff]段决定其中line-length 79比常见的 88 更严格与target-version py310与Python 3.10 兼容的要求互相印证。Python 标准Python 3.10 兼容代码Google Python 风格 docstring函数契约需要Args、Returns、Yields、Raises时必须包含相应段落不允许用只写摘要来省略这些段落这也是pydoclint会拦截的点所有函数参数与返回值必须有类型注解函数体量尽量控制在 50 行以内允许例外。优先静态类型而非动态属性探测当静态类型能表达契约时不要用getattr/hasattr做能力探测。优先使用 Protocol/ABC、Union isinstance 收窄或用带类型的适配器包裹第三方无类型对象实在绕不开时把getattr/hasattr隔离进一个小 helper 并暴露类型化接口。文档中的示例# Bad if hasattr(handler, close): handler.close() # Good from typing import Protocol class Closable(Protocol): def close(self) - None: ... def shutdown(h: Closable) - None: h.close()工具函数放哪里、私有 API 的边界Util 函数放置准则判断一个 helper 该放 utils 文件还是类上CLAUDE.md 给出两条准则方法只在类的上下文中才有意义→ 放类上静态/工具方法被子类大量使用→ 放父类上。放类上的理由为用户和子类省 import子类可以直接self.something()调用相关功能就近内聚。文档举的例子是BaseOrchestrator.requires_resources_in_orchestration_environment在当前源码中确实以staticmethod形式定义在 src/zenml/orchestrators/base_orchestrator.py并被本地 orchestrator 子类以self.requires_resources_in_orchestration_environment(step)的方式调用见 local_orchestrator.py 与 local_docker_orchestrator.py与文档描述完全吻合staticmethod def requires_resources_in_orchestration_environment(step: Step) - bool: Check whether a step needs special orchestration resources. if step.config.step_operator: return False return not step.config.resource_settings.emptyutils 文件留给真正跨无关模块复用的通用函数、逻辑上不属于任何类的函数、纯工具函数字符串处理、日期格式化等。仓库中 utils 的常见落点src/zenml/utils/— 通用工具src/zenml/orchestrators/utils.py— orchestrator 专用src/zenml/orchestrators/step_run_utils.py— step 执行工具src/zenml/orchestrators/publish_utils.py— 状态/元数据发布私有方法与 API 稳定性_前缀的方法/函数是私有的不应从所在类/模块之外调用文档也坦诚说明并非总有一致执行但这是约定。变更公共 API 与否的判断表符号类型属于公共 API修改是否破坏兼容在zenml.__init__中导出的类/函数是确定公共是——需要走弃用流程这些类上的公共方法是是——需要走弃用流程深层内部方法无下划线不面向用户否——更新所有内部调用处即可_private_method()否否——可自由修改改动任何非下划线方法的步骤1) 查该类/函数是否导出在zenml.__init__是则为公共 API2) 在 ZenML 代码库内搜索全部用法3) 更新所有内部调用4) 未从根包导出的内部代码无需弃用。文档还给出一个面向集成的前瞻性警告Integrations should avoid using ZenML private methods核心考量是未来问题当集成最终从主仓库拆分为外部包时mypy 无法检测到你依赖的私有方法被改了会造成静默破坏。即使集成目前仍在仓库内只用公共 API 也是好的实践为这种过渡做准备。文档的示例对比了集成代码调用self._some_private_helper()反例与只调用self.public_method()正例。依赖栈与运行时约束CLAUDE.md 明确锁定了 ZenML OSS 的技术栈FastAPI Pydantic v2 SQLAlchemy 2.0 SQLModel。这条在 pyproject.toml 中有精确的版本证据sqlmodel0.0.38、sqlalchemy2.0.0,3.0.0、fastapi0.138.0,0.139.0server extra。引入任何新依赖前必须先与pyproject.toml的既定集合核对。几条有强约束力的运行时规则同步优先禁止 async I/O尽管 FastAPI 原生支持 asyncZenML OSS 的 handler 一律实现为同步def后台/长耗时工作交给 worker 或依赖注入的服务处理——这条压过任何泛泛的 async 建议。依赖注入优先于模块级单例client、缓存、repository 都应通过 DI 管理保证状态可测试。缓存与懒加载静态或高频访问数据做依赖作用域内存缓存重量级资源懒加载以控制冷启动延迟。OpenTelemetry 版本联动升级 fastapi 或数据库库版本时必须检查 OTel SDK、exporter 与 instrumentation 依赖是否需要同步更新且保持 OTel SDK/exporter 与对应 instrumentation beta 版本线对齐。pyproject.toml的otelextra 正是这种对齐的体现exporter 锁定1.43.x而 instrumentation 锁定0.64b0的 beta 线。服务端src/zenml/zen_server/的 Router、service、错误处理与校验约定不在这份文档展开而是由 src/zenml/zen_server/AGENTS.md 承载——在该目录下工作时会自动加载。测试策略与 CI 双轨制测试布局与运行纪律测试位于tests/结构松松地镜像主代码库单元测试 →tests/unit/集成测试 →tests/integration/tests/harness/是测试脚手架tests/harness/harness.py 等最关键的纪律是不要在本地跑全量测试套件——许多测试需要特殊环境。正确做法是跑定向测试pytest tests/unit/path/to/test_file.py pytest tests/unit/path/to/test_file.py::test_specific_function全量覆盖交给 CI。多数新代码要求有测试覆盖例外是与外部服务集成的代码这类通常依赖本地 CI 的大量验证。两级 CIFast CI所有 PR 自动触发基础测试、linting、类型检查Full CI包含集成测试、tutorial pipeline 回归测试用当前分支跑所有 VSCode 教程示例以捕获破坏性变更等更广泛覆盖run-slow-ci标签触发 Full CI合并前必须有如果你的改动触及集成或核心功能应在 PR 中明确说明需要跑 Full CI。分支、提交与 PR 流程分支管理develop才是主工作分支不是main所有改动从develop拉分支所有 PR 指向developmain只在发布流程中更新基于某个 feature 分支的相关改动可以直接从该 feature 分支再拉。提交前的固定动作bash scripts/format.sh每次提交前必跑跑定向测试验证改动面向用户的改动同步更新文档或确认没有破坏任何东西;开 PR 或做大批量提交前跑/simplify审查改动代码的复用机会、质量问题与效率改进把发现的问题修完再提交。安全底线永不提交密钥、API key、token、密码敏感数据走环境变量或 ZenML 的 secret 管理提交前审查是否意外暴露凭据意外泄露立即通知团队访问控制遵循最小权限原则校验并净化所有用户输入。数据库与 Alembic 迁移schema 变更必须走 Alembic 迁移用描述性命名创建alembic revision -m Add X to Y table测试升级路径alembic upgrade head降级测试可选——ZenML 多数情况不支持降级永不修改已在 main/develop 上的迁移文件滚动部署场景必须考虑向后兼容需要时同时包含 schema 变更与数据迁移跑 scripts/check-alembic-branches.sh 验证迁移一致性。Commit message 规范首行 50 字符以内的祈使句摘要Add feature 而非 Added feature必要时引用 issue 号Fix user auth bug (#1234)多行消息在摘要后空一行。标准示例Add retry logic to artifact upload Previously, artifact uploads would fail immediately on network errors. This adds exponential backoff retry logic to handle transient failures. Fixes #1234PR 规范与 Release Notes 标签PR 标题人类可读不加feat:、doc:这类前缀描述要写清改动做什么、为什么需要、关键实现决策、需要评审者特别关注的地方详尽的 PR 描述同时服务于评审与 release note 生成可选标签internal、documentation、bug、dependencies、enhancement硬性要求每个 PR 必须且只能有release-notes或no-release-notes二选一。用户可见特性、重要更新用release-notes内部改动、CI 修复、重构、纯文档用no-release-notes。缺标签会被 CI 直接阻止合并。核心概念速查术语、架构与关键抽象CLAUDE.md 用一节Core Concepts给新成员和 Agent扫清代码库中最容易踩的坑model 一词有三种含义读码写码时必须显式区分Pydantic models— 贯穿代码库的数据结构如PipelineModelML models— 真正的机器学习模型PyTorch、sklearn 等ZenML models— 把 artifact、元数据等资源按 ML 模型分组的命名空间。Pipeline 架构是一条清晰的职责链Pipeline 由 Step 组成 → Step 生产/消费 artifact → artifact 由 Materializer 负责序列化/反序列化 → Pipeline 由 Orchestrator 执行 → 存储、编排等能力由 Stack 组件提供。关键抽象StackComponent栈组件基类、Pipelinepipeline 定义、BaseStepstep 实现、BaseMaterializerartifact 序列化、BaseOrchestratorpipeline 执行、BaseStepOperator远程 step 执行的 submit/status/wait/cancel 生命周期。添加集成与评审者检查清单添加新集成的标准路径在src/zenml/integrations/下创建集成包实现所需抽象并注册 flavor在tests/integration/中添加测试在docs/book/component-guide/中添加文档。修改核心功能时则要求先评估对现有组件的影响、尽可能保持向后兼容、补齐测试覆盖、更新类型注解与文档。PR 评审者速查清单CLAUDE.md 末尾的 Reviewer Checklist 是一份高价值的评审对照表每项都指向承载细则的子系统 AGENTS.md集成 PRflavor 文件中不得出现集成库的 import细则见 src/zenml/integrations/AGENTS.mdOrchestrator PRget_orchestrator_run_id每次 run 唯一、但同一 run 内所有 step 相同src/zenml/orchestrators/AGENTS.mdFilter 模型变更对应 client 方法必须同步更新src/zenml/models/AGENTS.md私有方法变更检查所有内部用法导入边界zen_server之外禁止 importzen_serversrc/zenml/zen_server/AGENTS.md导入边界zen_stores之外禁止直接 import SQL 相关代码src/zenml/zen_stores/schemas/AGENTS.md模型变更新增属性可以删除属性/改为可选属于破坏性变更依赖升级丢弃旧版本支持即为破坏性变更调度变更必须同时覆盖 legacy schedule 与 trigger 两套栈CLI client server models schemasStep operator 变更检查BaseStepOperator、StepLauncher及至少一个具体集成实现结语从规则文档到可执行工作流CLAUDE.md 的价值在于它把在这个代码库里正确做事的所有隐性知识显性化了哪条分支是工作分支、哪个脚本是提交前门禁、mypy 为什么建议按文件跑、model一词为何危险、哪个 import 边界不能越。对开发者而言这份文档同样是一份可直接执行的贡献手册——配合 AGENTS.md 与 8 个目录级 AGENTS.md 细则、scripts/下的自动化脚本以及 tests/ 中说明的测试框架架构构成了一套从本地开发、格式化、定向测试、迁移检查到两级 CI 的完整闭环。遵循它你的每一个 PR 都会站在与维护者相同的标准上。【免费下载链接】zenmlZenML : One AI Platform from Pipelines to Agents. https://zenml.io.项目地址: https://gitcode.com/GitHub_Trending/ze/zenml创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考