ml-adoption-playbook

name	ml-adoption-playbook
description	面向 AI 智能体和软件工程师的端到端方法论，用于把机器学习算法加入现有非 ML 代码库。覆盖问题界定、数据就绪度、架构解耦和基线模型集成。
origin	ECC

ML Adoption Playbook

此技能提供一种自适应方法，用于把机器学习模型实现到现有软件工程项目中。它通过结构化 ML 应如何研究、解耦、训练和集成，连接传统 SWE 与 MLOps。

何时激活

• 用户要求向现有代码库“add ML”或“add an algorithm”。
• 规划把新模型（如推荐、分类、预测）集成进非 ML 应用。
• 为智能体构建、训练、部署 ML 组件设计自适应工作流。

Phase 1：问题界定与可行性

写模型代码前，先明确“为什么”和“怎么做”。

• Heuristic Check： 询问用户简单 heuristic（例如 regex、基于规则排序）是否能更快解决问题。如果可以，从那里开始。
• Metric Definition： 定义 ML 模型试图改善的业务指标（例如 click-through rate、延迟降低）。
• Mistake Budget： 定义“坏”预测是什么，以及系统应如何处理它。

Phase 2：数据就绪度

没有干净、可访问的数据，ML 没用。

• Audit Data Sources： 识别训练数据在哪里。是 live database、静态 CSV，还是 API？
• Data Contract： 为输入数据建立 schema。需要哪些 features？feature 缺失时会怎样？
• Leakage Prevention： 确保用户提议的数据切分不会意外把未来信息泄漏进训练集（例如时间序列数据要按时间切分）。

Phase 3：架构集成与解耦

不要把模型推理紧耦合到核心业务逻辑。

• API Boundary： 建议把模型放在 API endpoint 后面（例如使用 fastapi-patterns 或 django-patterns），或放进专用 service class。
• Fallback Mechanisms： 设计默认状态。如果模型响应过慢或抛错，系统必须优雅回退到硬编码规则。
• Feature Flags： 用 feature flag 包裹新的 ML inference call，便于安全发布或回滚。

Phase 4：模型实现与训练

让代码可复现、可迭代。

• Start Simple： 先构建基线模型（例如简单 scikit-learn Logistic Regression，或最小 PyTorch linear layer）。
• Reproducibility： 应用 pytorch-patterns 或类似最佳实践：固定 random seeds、让代码 device-agnostic、明确记录 tensor/array shapes。
• Automated Evidence： 要求为 data transforms 和 inference schema 写测试。没有评估脚本把模型与 baseline 对比，就不要接受模型。

Phase 5：交接给 MLOps

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

• 参考 mle-workflow： 引导用户设置 experiment tracking、model registries 和 drift detection。
• CI/CD： 把模型评估步骤加入现有 CI pipeline，确保未来 commit 不会降低模型性能。

迭代式智能体工作流

使用此 playbook 协助用户时，智能体应：

1. 在提出架构前，提出澄清问题完成 Phase 1。
2. 在 Phase 2 草拟 data contract，交给用户批准。
3. 在编写 training loop 前，在 Phase 3 编写解耦接口（API/Service）。
4. 在 Phase 4 交付可复现脚本，用于训练模型并保存 artifact。