mle-workflow

机器学习工程工作流 (Machine Learning Engineering Workflow)

使用此 Skill 将模型研发转化为规范的生产级 ML 系统，具备清晰的数据契约、可复现的训练流程、量化的质量卡口（Quality Gates）、可部署的产物以及完善的运维监控。

触发时机

• 规划或评审生产级 ML 功能、模型更新、排序系统、推荐系统、分类器、向量 Embedding 工作流或预测流水线（Forecasting Pipeline）时
• 将 Jupyter Notebook 实验代码重构为可复用的训练、评估、批量推理（Batch Inference）或在线推理（Online Inference）流水线时
• 设计模型晋级（Promotion）标准、离线/在线评估、实验追踪（Experiment Tracking）或回滚路径时
• 排查因数据漂移（Data Drift）、标签泄露（Label Leakage）、特征陈旧、产物不匹配或训练与在线预测逻辑不一致引发的故障时
• 引入模型监控、灰度发布（Canary Rollout）、影子流量（Shadow Traffic）或上线后质量检查时

作用域裁定 (Scope Calibration)

根据当前具体的系统形态，按需选用对应的流水线分支。本 Skill 适用于排序、搜索、推荐、分类器、预测、Embedding、LLM 工作流、异常检测和批处理分析等场景，但不应将单一架构强行套用于所有场景。

• 不要假设每个模型都具备监督标签、在线服务、特征存储（Feature Store）、PyTorch、GPU、人工复核、A/B 测试或实时反馈机制。
• 如果简单的数据契约、基线模型、评估脚本和回滚说明就已经能满足代码评审需求，就不要引入过于沉重的 MLOps 组件。
• 当项目缺乏明确的标签、滞后结果、分片定义（Slice Definitions）、生产流量或监控责任人时，务必将相关假设显式梳理出来。
• 将示例视为可替换的脚手架。根据项目实际情况，将其替换为工程原生的指标、服务模式、数据存储和发布机制。

关联 Skill

• python-patterns 与 python-testing：用于 Python 代码实现与 pytest 测试覆盖
• pytorch-patterns：用于深度学习模型、数据加载器（Data Loader）、设备调度及训练循环
• eval-harness 与 ai-regression-testing：用于模型晋级卡口及 Agent 辅助的回归测试
• database-migrations、postgres-patterns 与 clickhouse-io：用于数据存储与分析层
• deployment-patterns、docker-patterns 与 security-review：用于服务化、密钥管理、容器化及生产加固

复用软件工程（SWE）基建

不要把 MLE 与常规软件工程割裂开来。ECC 中的绝大多数 SWE 工作流均可直接应用于 ML 系统，且通常伴随着更严苛的失效模式：

推荐安装 minimal --with capability:machine-learning，以在本 Skill 旁边保留核心 Agent 能力。对于仅支持 Skill 或受限的测试环境，可在目标环境支持 Agent 时，将 skill:mle-workflow 与 agent:mle-reviewer 搭配使用。

SWE 能力项	在 MLE 中的应用
product-capability / architecture-decision-records	将模型研发转化为明确的产品契约，并记录不可逆的数据、模型及发布决策
repo-scan / codebase-onboarding / code-tour	在引入并行 ML 技术栈前，梳理既有的训练、特征、服务、评估与监控路径
plan / feature-dev	将模型变更作为产品功能进行范围拆解，明确数据、评估、服务及回滚等阶段
tdd-workflow / python-testing	在编码实现前，测试特征转换、数据集划分逻辑、指标计算、产物加载和推理 Schema
code-reviewer / mle-reviewer	评审代码质量，并排查 ML 专属的数据泄露、可复现性、晋级与监控风险
build-fix / pr-test-analyzer	诊断构建中断的 CI、不稳定的评估、缺失的 Test Fixture，以及特定环境下的模型或依赖故障
quality-gate / test-coverage	为转换逻辑、评估指标、推理契约、晋级卡口和回滚行为强制要求自动化验证证据
eval-harness / verification-loop	将离线指标、分片检查、时延预算（Latency Budgets）和回滚演练转化为可复现的质量卡口
ai-regression-testing	将每个线上 Bug 转为回归测试用例：如特征缺失、标签陈旧、坏产物、Schema 漂移或线上线下不一致
api-design / backend-patterns	设计预测 API、批处理任务、幂等重训 Endpoint 以及响应 Envelope
database-migrations / postgres-patterns / clickhouse-io	对标签、特征快照、预测日志、实验指标及漂移分析进行版本控制
deployment-patterns / docker-patterns	打包可复现的训练和服务镜像，包含健康检查、资源限制及回滚配置
canary-watch / dashboard-builder	打造涵盖模型版本、数据分片、漂移、时延、成本及滞后标签的可视化发布监控看板
security-review / security-scan	检查模型产物、Notebook、Prompt、数据集及日志中的密钥泄漏、PII、不安全反序列化及供应链风险
e2e-testing / browser-qa / accessibility	测试消费预测结果的关键产品链路，包括可解释性 UI 与降级兜底状态
benchmark / performance-optimizer	评估吞吐量、P95 时延、内存占用、GPU 利用率以及单次预测/重训成本
cost-aware-llm-pipeline / token-budget-advisor	结合效果、时延与预算灵活路由 LLM/Embedding 任务，避免盲目使用最大模型
documentation-lookup / search-first	在编写代码前，先查阅验证模型服务、特征存储、向量数据库及评估工具的最新库行为
git-workflow / github-ops / opensource-pipeline	以清晰的范围打包 MLE 变更提交评审，排除生成的产物，并附带可复现的测试证据
strategic-compact / dmux-workflows	将漫长的 ML 研发拆解为并行 Track：数据契约、评估套件、服务路径、监控与文档

十个 MLE 任务模拟场景 (Ten MLE Task Simulations)

在规划或评审 MLE 工作时，使用这些模拟场景作为覆盖率检查清单。一个成熟的 MLE 工作流应当能够把每个任务收敛为明确的契约、可复用的 SWE 工具链、自动化验证证据和可评审的产物。

编号	常见 MLE 任务	提效后的 ECC 路径	必需的输出产物	覆盖的流水线环节
MLE-01	抽象模糊的预测、排序、推荐、分类、Embedding 或预测（Forecast）功能需求	product-capability, plan, architecture-decision-records, mle-workflow	迭代契约文档（Iteration Compact）：明确利益相关方、决策责任人、成功指标、不可接受的错误、假设、约束及首次实验方案	产品契约、干系人损益、风险控制、发布策略
MLE-02	定义指标目标、样本标签、数据源及错误预算（Mistake Budget）	repo-scan, database-reviewer, database-migrations, postgres-patterns, clickhouse-io	数据与指标契约：涵盖实体粒度、标签时序、标签置信度、特征时序、时点联接（Point-in-time Join）、划分策略及数据集快照	数据契约、指标设计、防泄露、可复现性
MLE-03	在增加复杂度前，先构建基线模型（Baseline）与打分路径	tdd-workflow, python-testing, python-patterns, code-reviewer	基线打分器：附带混淆矩阵、校准说明、时延/成本预估、已知缺陷，以及针对打分 Output 结构和确定性的测试用例	基线模型、打分链路、测试覆盖、服务一致性
MLE-04	基于“区分结果成因”的假设构建特征	python-patterns, pytorch-patterns, docker-patterns, deployment-patterns	特征规划与转换模块：覆盖信号源、缺失值处理、异常值、相关性分析、泄露检查及训练/预测一致性保证	特征流水线、防泄露、模型训练、产物管理
MLE-05	在多重权衡（Tradeoffs）下调优阈值、配置及模型复杂度	eval-harness, ai-regression-testing, quality-gate, test-coverage	阈值/配置报告：综合对比 精准率（Precision）、召回率（Recall）、F1、AUC、校准度、群体切片（Slices）、时延、成本、复杂度及可接受的错误类别	模型评估、阈值决策、晋级门槛、回归测试
MLE-06	进行归因分析（Error Analysis），将错误转化为下一次实验输入	eval-harness, ai-regression-testing, mle-reviewer, silent-failure-hunter	错题聚类报告：针对假阳性（FP）、假阴性（FN）、模糊标签、陈旧特征、缺失信号进行分析，附带链路追查与经验沉淀	错误分析、Bug 溯源、迭代闭环、回归防范
MLE-07	打包模型产物以供离线批处理或在线推理使用	api-design, backend-patterns, security-review, security-scan	带版本控制的产物包：集成预处理逻辑、配置、依赖约束、Schema 校验、安全加载及 PII 脱敏日志	产物规范、安全审查、推理契约
MLE-08	上线在线服务或批处理打分，并捕获反馈数据	api-design, backend-patterns, e2e-testing, browser-qa, accessibility	预测 API 端点或批处理 Job：包含响应 Envelope、超时控制、Batch 化处理、降级兜底、模型版本、置信度、反馈日志及端到端业务流测试	在线服务、批处理推理、降级兜底、用户链路
MLE-09	通过影子流量、灰度发布、A/B 测试或回滚方案发布模型	canary-watch, dashboard-builder, verification-loop, performance-optimizer	上线发布方案：指明流量切分规则、监控看板、P95 时延、成本、质量护栏、回滚镜像/产物及触发回滚的条件	部署策略、灰度控制、回滚演练
MLE-10	运行、排查并持续更新上线后的生产模型	silent-failure-hunter, dashboard-builder, mle-reviewer, doc-updater, github-ops	观测日志与更新计划：包含漂移检测、滞后标签健康度监控、告警责任人、Runbook 更新、重训触发条件及 PR 变更证据	运维监控、故障响应、模型重训

迭代契约 (Iteration Compact)

在动笔写模型代码前，先把工作收敛成一份可供评审的契约文档。它应该足够精简，以便直接放入 PR Description 之中；同时又足够精确，能让其他工程师对其权衡取舍提出质询。

目标 Goal:
利益相关方 Who cares:
决策责任人 Decision owner:
由模型改变的用户/系统行为 User or system action changed by the model:
核心成功指标 Success metric:
护栏指标 Guardrail metrics:
错误预算 Mistake budget:
不可接受的错误 Unacceptable mistakes:
可接受的错误 Acceptable mistakes:
前置假设 Assumptions:
约束条件 Constraints:
标签与数据快照 Labels and data snapshot:
基线模型 Baseline:
候选信号源 Candidate signals:
阈值/配置计划 Threshold or config plan:
评估切片 Eval slices:
已知风险 Known risks:
下一次实验计划 Next experiment:
回滚或降级方案 Rollback or fallback:

这份契约是 MLE 领域对标优秀 SWE 设计文档的核心机制。它能防止团队去优化无人关心的指标、添加无法解决实际错误的特征，或是发布无法一键回滚的复杂系统。

决策大脑 (Decision Brain)

每当遇到模糊、高影响或指标导向的任务时，运行此环路：

1. 从决策出发，而非从模型出发。明确定义要改变的下游动作。
2. 明确谁在乎以及为什么在乎。不同的利益相关方对于假阳性、假阴性、时延、算力开销、不可解释性或错失机会所付出的代价大不相同。
3. 把模糊的需求转化为假说。思考什么信号能够区分结果成因？什么证据能推翻它？什么样的简单基线模型应当很难被击败？
4. 在研发自定义系统前，先调研现有方案或邻近已知问题。
5. 使用 (概率, 置信度) x (成本, 严重性, 重要性, 影响) 对各种可选方案进行评估打分。
6. 考量对抗行为、利益驱动、选择性披露、分布偏移（Distribution Shift）及反馈环路（Feedback Loops）。
7. 优先选择能最大化减少最关键错误的极简方案。追求简单绝非偷懒，而是保全快速迭代速度的同时降本增效、减少失误的最优解。
8. 记录决策依据、验证证据、反例质询以及下一个可逆的步骤。

指标与错误的经济学 (Metric and Mistake Economics)

根据故障代价选择评估指标，而不是出于习惯：

• 早早期就引入混淆矩阵（Confusion Matrix），以便团队能就具体的假阳性和假阴性展开讨论。