（3056期）Jarvis Api Contract Guard 01 – API 契约设计与兼容性验证工作流

API 契约设计与兼容性验证工作流 结构化 API 契约设计与验证工作流，确保向后兼容性，提供可重复的执行步骤、质量门禁和可直接落地的交付物。 使用说明 核心用法 Jarvis Api Contract Guard 01 是一套面向 API 开发的工程化工作流技能，专注于契约设计与向后兼容性验证。其使用场景涵盖 API 迭代开发、版本迁移、第三方集成等需要严格质量控制的工程任务。 标准执行流程： 输入收束：明确期望产出与截止日期，梳理时间/工具/风险承受度等约束条件，清点现有资产（代码、文档、截图、日志） 成功定义：将抽象目标转化为可量化的成败标准 最小路径验证：先构建最小可行执行路径，验证可行性后再规模化投入 分段执行与证据留存：按检查点推进，每个阶段产出可追溯的证据 质量门禁：最终建议需通过多重质量关卡方可输出 交付闭环：返回可直接实施的产出物及明确的后续行动项 输出规范严格遵循五要素结构： 情境摘要（≤5行） 按影响排序的核心发现 分阶段行动计划（今日/本周） 风险识别与缓解策略 精确检查清单或可执行命令 显著优点 工程化严谨性：内置质量门禁（Evidence-backed claims、显式假设与权衡、优先可逆操作、责任人+ETA、备选方案），大幅降低返工风险 风险前置设计：强制要求在最小程序路径阶段暴露风险，避免后期沉没成本 可追溯性保障：检查点证据留存机制支持审计与复盘 即拿即用：输出格式高度结构化，可直接转化为 Jira/Notion/Trello 等工具的任务卡片 潜在缺点与局限性 启动成本较高：小型 API 变更可能觉得流程过重，存在"用大炮打蚊子"的摩擦 依赖输入质量：若用户提供的"可用资产"不完整，第一阶段可能消耗较多时间进行信息补全 未覆盖自动化验证：当前描述侧重流程与文档，未明确提及 OpenAPI diff 工具、Pact 契约测试等自动化手段的集成 向后兼容判定标准需外部输入：本身不提供语义化版本控制或破坏性变更的自动检测逻辑 适合人群 技术负责人/架构师：需要为团队建立 API 变更的标准作业程序 后端工程师：处理跨版本 API 兼容，特别是存在多版本并行服务的场景 DevOps/平台工程师：设计 CI/CD 中的 API 质量门禁 技术项目经理：需要将技术任务拆解为可跟踪、可验收的执行单元 常规风险 | 风险类型 | 说明 | 建议缓解 ||---------|------|---------|| 流程僵化 | 过度遵循流程导致响应速度下降 | 根据变更规模灵活裁剪检查点数量 || 假设失效 | 显式假设在实际执行中被证伪 | 每个假设配套快速验证实验 || 证据造假 | 检查点记录流于形式 | 引入 peer review 或自动化证据抓取 || 备选方案未激活 | 主计划失败后才发现备选不可行 | 主备方案同步进行可行性预检 | 该技能本质上是一套结构化的问题解决框架，其价值不在于替代专业 API 工具，而在于确保"人"的执行过程具备可预测性和可改进性。 原始说明 Design and verify API contracts for backward compatibility. Use when handling development work that needs repeatable steps, quality gates, and practical outp...