ml-adoption-playbook

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

ML Adoption Playbook

机器学习采纳指南

This skill provides an adaptive methodology for implementing machine learning models into existing software engineering projects. It bridges the gap between traditional SWE and MLOps by structuring how ML should be researched, decoupled, trained, and integrated.

本Skill为将机器学习模型应用到现有软件工程项目中提供了一套自适应方法。它通过构建机器学习的研究、解耦、训练和集成流程，填补了传统软件工程（SWE）与机器学习运维（MLOps）之间的差距。

When to Activate

适用场景

A user asks to "add ML" or "add an algorithm" to their existing codebase.
Planning the integration of a new model (e.g., recommendation, classification, forecasting) into a non-ML application.
Structuring a workflow for an agent to build, train, and deploy an ML component adaptively.

用户要求为现有代码库“添加机器学习功能”或“添加算法”时。
计划将新模型（如推荐模型、分类模型、预测模型）集成到非机器学习应用中时。
为Agent构建自适应的机器学习组件构建、训练和部署工作流时。

Phase 1: Problem Framing & Feasibility

第一阶段：问题框架构建与可行性分析

Before writing model code, establish the "why" and "how".

Heuristic Check: Ask the user if a simple heuristic (e.g., regex, rule-based sorting) could solve the problem faster. If yes, start there.
Metric Definition: Define what business metric the ML model is trying to improve (e.g., click-through rate, reduced latency).
Mistake Budget: Define what a "bad" prediction looks like and how the system should handle it.

在编写模型代码之前，先明确“目的”和“实现方式”。

启发式检查： 询问用户是否可以通过简单的启发式方法（如正则表达式、基于规则的排序）更快地解决问题。如果可以，优先采用该方法。
指标定义： 明确机器学习模型旨在提升的业务指标（如点击率、延迟降低）。
错误容忍度： 定义“不良预测”的表现形式，以及系统应如何处理此类情况。

Phase 2: Data Readiness

第二阶段：数据准备

ML is useless without clean, accessible data.

Audit Data Sources: Identify where the training data lives. Is it a live database, a static CSV, or an API?
Data Contract: Establish a schema for the input data. What features are required? What happens if a feature is missing?
Leakage Prevention: Ensure the user's proposed data split does not accidentally leak future information into the training set (e.g., chronological splitting for time-series data).

没有干净、可访问的数据，机器学习便毫无用处。

数据源审计： 确定训练数据的存储位置。是实时数据库、静态CSV文件还是API接口？
数据契约： 确定输入数据的 schema。需要哪些特征？如果某个特征缺失该如何处理？
防止数据泄露： 确保用户提出的数据划分方式不会将未来信息意外泄露到训练集中（例如，时间序列数据需按时间顺序划分）。

Phase 3: Architectural Integration & Decoupling

第三阶段：架构集成与解耦

Do not tightly couple model inference to core business logic.

API Boundary: Suggest placing the model behind an API endpoint (e.g., using
```
fastapi-patterns
```
or
```
django-patterns
```
) or a dedicated service class.
Fallback Mechanisms: Design a default state. If the model takes too long to respond or throws an error, the system must gracefully fall back to a hardcoded rule.
Feature Flags: Wrap the new ML inference call in a feature flag so it can be rolled out (or rolled back) safely.

不要将模型推理与核心业务逻辑紧密耦合。

API边界： 建议将模型部署在API端点之后（例如使用
```
fastapi-patterns
```
或
```
django-patterns
```
），或使用专用服务类。
** fallback机制：** 设计默认状态。如果模型响应过慢或抛出错误，系统必须优雅地回退到硬编码规则。
功能开关： 将新的机器学习推理调用包裹在功能开关中，以便安全地推出（或回滚）功能。

Phase 4: Model Implementation & Training

第四阶段：模型实现与训练

Structure the code for reproducibility and iteration.

Start Simple: Build a baseline model first (e.g., a simple scikit-learn Logistic Regression or a barebones PyTorch linear layer).
Reproducibility: Apply
```
pytorch-patterns
```
or similar best practices: fix random seeds, make code device-agnostic, and explicitly document tensor/array shapes.
Automated Evidence: Require tests for the data transforms and inference schema. Do not accept a model without an evaluation script comparing it against the baseline.

构建可复现、可迭代的代码结构。

从简入手： 先构建基线模型（例如简单的scikit-learn Logistic Regression或基础PyTorch线性层）。
可复现性： 应用
```
pytorch-patterns
```
或类似最佳实践：固定随机种子、使代码与设备无关、明确记录张量/数组形状。
自动化验证： 要求为数据转换和推理schema编写测试。未提供与基线模型对比的评估脚本的模型不予通过。

Phase 5: Handoff to MLOps

第五阶段：移交至MLOps团队

Once the baseline model is integrated, shift focus to continuous operations.

Refer to
mle-workflow
: Guide the user toward setting up experiment tracking, model registries, and drift detection.
CI/CD: Add the model evaluation step to the existing CI pipeline to ensure future commits do not degrade model performance.

基线模型集成完成后，将重点转向持续运维。

参考
mle-workflow
：指导用户设置实验跟踪、模型注册和漂移检测。
CI/CD： 将模型评估步骤添加到现有CI流水线中，确保未来提交不会降低模型性能。

Iterative Agent Workflow

Agent迭代工作流

When assisting a user via this playbook, agents should:

Ask clarifying questions to complete Phase 1 before proposing architectures.
Draft a data contract in Phase 2 for user approval.
Write the decoupling interface (API/Service) in Phase 3 before writing the training loop.
Deliver a reproducible script in Phase 4 that trains the model and saves the artifact.

通过本指南协助用户时，Agent应：

提出澄清问题，完成第一阶段后再提出架构方案。
在第二阶段起草数据契约，供用户审批。
在第三阶段编写解耦接口（API/服务），之后再编写训练循环。
在第四阶段交付可复现脚本，用于训练模型并保存模型工件。