实践旁注｜Skill 仓库交付闭环

本文件是 实践案例｜从多维表需求到 MR 与上线 的章节化阅读入口。案例基于内部实践，经过去标识化和教学重构；后文统一简称“实践案例”。

正文继续使用“澄川工业”演示完整方法；本旁注保留实践中的不规则性：业务人员在多维表提交需求，编排平台调用 Skill 分析并修改代码，维护者审核 MR，CI 和测试环境负责确定性验证。简单需求可以快速交付，复杂需求则因缺少业务建模持续被拒绝。

旁注不新增另一套方法。它用于回答：第 5—10 章的方法在内部研发与 Skill 仓库场景中分别长什么样。

---

对应第 5 章：复杂需求为什么不能直接进入代码生成

相关正文：第 5 章｜从工具愿望到可验证场景

现场现象

协作表格中的需求往往只有一句话。例如：

• 上传 Skill 时增加飞书文档说明；
• Skill Hub 增加 Skill Package；
• 让 Agent 自动完成后续开发。

三句话都使用了产品或技术名词，却没有同样的可实施程度。

“增加飞书文档说明”已经接近任务：对象是现有 Skill，变化是增加一个属性，输入是文档链接，验收可以检查上传、保存、读取和展示。

“增加 Skill Package”仍是一个概念愿望。Package 可能代表分组、依赖包、安装单元或发布单元。对象、关系、生命周期、权限、迁移和兼容都没有决定。此时生成代码，不是在实现需求，而是在让模型替组织做产品定义。

Builder 的判断

需求是否进入快车道，不应由“模型觉得可信”决定。至少检查：

检查项	可进入快车道的信号	应进入探索车道的信号
业务对象	已存在，含义稳定	新对象或定义有争议
对象关系	不改变或已有模式	新增一对多、多对多、依赖关系
用户流程	局部修改	改变多个角色的主流程
数据	无迁移或简单兼容	需要历史迁移、版本策略
权限	沿用已有权限	新增创建、发布、删除或跨团队权限
验收	可写成确定性示例	多个合理结果仍未取舍
回滚	局部、可逆	影响共享数据或不可逆动作

本章练习补充

把一个待开发需求删掉产品名和“AI”后重写：

当谁在什么事件下完成什么任务时，当前出现了什么可观察问题？本次只改变什么行为，明确不改变什么？

如果删除产品名后无法说明任务，当前问题还不值得进入流程设计；如果对象、关系和验收仍然含糊，不应进入编码。

---

对应第 6 章：业务人员不需要迁移到 Agent 平台

相关正文：第 6 章｜重构人—AI—系统工作流

现场现象

业务人员已经习惯在多维表记录问题。若为了“AI Native”要求他们进入新的 Agent 工作台，项目会同时承担两类改变：

1. 改造需求交付流程；
2. 改变所有提交人的工作入口。

当前实践选择保留多维表，把它作为控制面。编排平台在后台拉取任务、调用 Skill、维护状态；代码托管和 CI 负责确定性执行。用户看到的仍然是自己熟悉的表格、字段、状态和反馈。

目标工作流

业务提交人填写需求
→ 系统检查字段和附件
→ AI 识别目标、未知项和影响范围
→ 信息不足则生成澄清问题
→ 提交人补充业务事实
→ 系统按复杂度分流
→ 快车道生成 MR；探索车道生成方案与决策材料
→ 人工 Review
→ CI / 测试环境验证
→ 发布或回退

人、AI、系统责任

工作	人	AI	确定性系统
提供业务事实	提交人负责	识别缺口，不得编造	表格保存原始输入
选择方案	业务与技术 Owner	提供选项和影响分析	保存 Decision Record
修改代码	技术 Reviewer 承担最终责任	生成修改与测试	分支、MR 和权限隔离
质量验证	人判断业务语义	辅助 Review 和失败分类	单测、集成测试、CI
发布	发布 Owner 批准	生成摘要与检查项	部署、观察和回滚

本章练习补充

不要把流程图只画成“多维表 → Agent → MR”。至少补齐：

• 哪些字段缺失会停止；
• 谁回答澄清问题；
• 怎样判断快车道与探索车道；
• Review 不通过后从哪里继续；
• 测试失败和部署未知分别进入什么状态；
• 哪些动作不能由 AI 自动执行。

---

对应第 6A 章：把需求流程写成智能体约束

相关正文：第 6A 章｜从 SOP 到智能体约束

从流程图补到约束卡

“多维表 → Agent → MR”只表达了组件顺序，没有说明什么条件允许任务进入自动交付。进入第 7 章前，需要先把当前实践整理成业务约束版：

约束元素	当前实践中的工作定义
触发	授权表格中的需求达到可分析状态，必要字段和附件可以读取
不触发	缺少业务目标、输入样例、验收方式或授权材料
分流判断	是否引入新对象、关系、权限、迁移或跨团队依赖
AI 可做	识别缺口、搜索授权仓库、生成影响分析、准备代码和 MR
AI 不做	编造业务语义、直接修改 main、自动合并高风险 MR 或跳过发布批准
人工责任	提交人补充业务事实；维护者确认分流和架构；Reviewer 与发布 Owner 承担最终决定
异常	信息不足进入 needs_information；复杂需求进入探索车道；部署结果不明进入 unknown

本章练习补充

选择一条已经处理过的需求，填写 SOP 到智能体约束转化卡。如果约束只能写成“Agent 自行判断”，或异常没有接收人和恢复条件，就不要把它交给第 7 章做系统契约。

---

对应第 7 章：需求也需要契约、对象和状态机

相关正文：第 7 章｜把业务变成可运行系统

需求不是一段文本

一条需求进入运行系统后，应被转换为可以检查的对象。建议定义 DeliveryRequest：

{
  "request_id": "REQ-DEMO-017",
  "submitter": "user-id",
  "business_goal": "为 Skill 上传增加可引用的使用说明",
  "current_behavior": "只能上传 Skill 文件，说明散落在聊天和文档中",
  "target_behavior": "上传时可关联一份授权文档并在详情中读取",
  "non_goals": ["不实现 Package", "不改变发布权限"],
  "risk_level": "low",
  "delivery_lane": "fast_track",
  "status": "ready_for_implementation"
}

复杂需求还应拥有 DecisionRecord、DomainObjectDraft、AcceptanceExample 和 MigrationPlan 等对象，避免把所有未决问题塞回一段自然语言。

状态机

submitted
→ analyzing
→ needs_information
→ ready_for_implementation
→ coding
→ waiting_for_review
→ changes_requested
→ testing
→ staging
→ deployed

异常状态：

• blocked：依赖、权限或业务定义无法满足；
• rejected：业务或技术评审明确拒绝；
• cancelled：提交人或 Owner 终止；
• unknown：外部动作可能发生但结果无法确认。

changes_requested 应保留原 MR、审核意见和修改范围。修复完成后回到 waiting_for_review，而不是重新创建一条无关联任务。

工具契约

工具应窄而明确，例如：

工具	允许动作	不允许动作
get_request_context	读取当前任务和授权附件	读取提交人的全部文档
search_repository	搜索授权仓库和路径	跨组织搜索私有代码
create_work_branch	为任务创建隔离分支	直接修改 main
open_merge_request	提交 MR 和说明	自动合并高风险变更
get_ci_status	查询测试和检查结果	把“正在运行”当作通过
deploy_to_staging	部署批准版本到测试环境	未经批准进入生产

本章练习补充

选择一条真实需求，分别写：任务契约、对象、工具、状态、权限和轨迹。若只能写“Agent 分析后继续执行”，说明系统边界仍然不可检查。

---

对应第 8 章：Agent 自省不能替代独立质量检查

相关正文：第 8 章｜用评估与治理证明系统可控

现场误区

一个 Agent 在完成修改后继续运行 Review Prompt，并输出“检查通过”，很容易被称为“自省”。这仍然是同一执行系统对自己的陈述，不能单独证明：

• 需求理解正确；
• 代码符合仓库架构；
• 自动化测试覆盖失败路径；
• 环境发生了预期改变；
• 业务提交人接受目标行为。

四类独立检查

检查	主要问题	证据
需求检查	做的是被确认的需求吗？	目标行为、非目标、验收示例
代码检查	实现是否符合架构与兼容？	MR diff、静态检查、Reviewer 意见
测试检查	正常、边界和回归是否通过？	CI、单测、集成测试、失败记录
业务验收	最终行为是否可用且符合责任？	提交人或业务负责人验收

高风险失败不能被平均通过率抵消。例如十个需求中九个局部修改通过，一个权限变更绕过审批，不能报告“90% 可用”。

失败 taxonomy

建议至少区分：

REQ-MISSING       信息不足
REQ-MODEL         新业务对象或关系未定义
IMPACT-MISS       影响范围遗漏
CODE-DEFECT       代码实现错误
CONTRACT-BREAK    API / 数据兼容被破坏
TEST-FAIL         自动化测试失败
REVIEW-REJECT     设计或业务语义被拒绝
DEPLOY-UNKNOWN    部署结果未知
PRODUCTION-ROLLBACK 上线后回滚

每个失败类型都应有 Owner、严重度、修复版本和回归样本。

本章练习补充

不要只记录“MR 最终合并”。保留第一次失败：哪一个节点发现、什么证据触发、谁作出停止决定、修复后运行了哪些回归。

---

对应第 9 章：持续运行不等于形成采用

相关正文：第 9 章｜从试点到真实采用

现场现象

案例中有人提交需求，部分需求走到上线阶段。这段过程用于展示采用问题，但还不能回答：

• 有多少提交人完成过完整流程？
• 有多少人重复使用？
• 多少需求需要维护者介入？
• 自动化节省的时间是否超过 Review、陪跑和修复？
• 哪类需求真正适合该系统？

采用漏斗

建议以真实需求为单位记录：

符合范围的需求
→ 已提交
→ 信息完整
→ 完成分流
→ 进入实施
→ 产生可审核 MR
→ 通过 Review
→ 通过测试
→ 部署上线
→ 未回滚

提交或登录只是浅层入口指标。稳定采用应至少包含：同一提交人能够在后期较少依赖维护者，多次完成符合范围的需求。

净负担

当前净价值
= 自动化减少的分析、编码与测试时间
− 提交人补充信息时间
− 维护者 Review 与修复时间
− 测试、发布和运行维护成本
− 失败与回滚成本

对首个阶段，不必急于计算货币 ROI。先记录分流比例、人工介入时间和端到端周期，避免只计算模型生成速度。

本章练习补充

至少按“局部字段 / Bug / 新 Skill / 新业务概念 / 权限与迁移”分组报告。不同类型混在同一个通过率中，会让小需求的成功掩盖复杂需求的边界。

---

对应第 10 章：什么时候才算组织资产

相关正文：第 10 章｜把一次项目变成组织能力

现场风险

当前 Skill 仓库主要由一名维护者负责。Agent 可以加速产生 MR，但以下判断仍集中在该维护者：

• 需求是否完整；
• 应走哪条车道；
• 架构是否合理；
• MR 是否通过；
• 测试失败怎样恢复；
• 是否发布和回滚；
• Skill 是否升级、兼容或退役。

当自动化提高吞吐，审核队列可能成为新瓶颈。个人效率提升不能自动变成组织能力。

资产化门槛

维度	个人工具	组织资产
Owner	原作者默认负责	业务、Skill、技术、Eval、发布责任明确
适用范围	靠作者口头判断	触发和非触发范围可检查
版本	当前文件即最新版	版本、变更说明和升级影响明确
质量	作者试用	正负样本、回归、发布条件
失败	修好后删除过程	失败 taxonomy、事件卡和回归样本
复用	复制文件	第二团队可以独立配置、运行和解释
维护	出问题找作者	支持、升级、暂停和退役机制

共享核心与本地适配

可共享核心可能包括：

• 需求状态机；
• 分支和 MR 工具；
• Review、测试和发布检查；
• 失败 taxonomy；
• 需求分流检查器；
• Trace 与指标结构。

本地适配包括：

• 业务对象和术语；
• 仓库结构和代码规范；
• 权限与发布流程；
• 验收样例；
• 风险级别和人工责任。

不能为了“可配置”把安全不变量变成开关。例如禁止 Agent 直接合并高风险 MR、禁止状态未知时重复部署，应保留为共享核心的硬约束。

本章练习补充

让第二名维护者只使用仓库文档和测试环境处理三条需求。记录：独立完成比例、原作者介入时间、未说明依赖和错误分流。最终跑通不能覆盖过程中的依赖。

---

跨章节结论

这个案例没有证明“Agent 能替代完整研发团队”。它证明了另一件更重要的事：

AI Native Builder 的工作不是把越来越多步骤交给一个更自主的 Agent，而是把问题、对象、状态、权限、质量和责任逐步变成可以由人、AI 与确定性系统共同执行的契约。

配套填写材料见：练习册扩展｜需求分流与自动交付。