端到端交付2.0：像工业流水线一样的生产和交付需求

在聊2.0之前，先看看当前面对的局面。

1.0 端到端体系从25年12月开始建设，是基于Spec + Harness框架的需求生成模式。

整个链路聚焦在了能从需求按规范稳定的生成代码

这个过程在大部分应用沉淀了较充分的规范约束和技能（constitution、rules、skills），但本质上是"人操作Agent执行"——人是主角，在用Qoder、Cursor、CC等工具驱动Agent干活。

到今天，绝大部分需求在已经走Spec驱动的代码生成，但快起来之后问题也集中爆发了。

• 质量检查跟不上了 - Agent哗哗出代码，一个CR动不动几万行，但没有经过系统性检查，谁也不敢直接上线，最后还是要人逐行review、手动兜底。

• 信息处理的成本没有降低 - PRD的规范还没指定，Agent不能拿着要素缺失的需求就开始干，人还是得做澄清补全。更关键的是，信息从上游传到下游，每经过一个环节就会衰减——测试要看SRE保障需求，SRE要看研发变更影响，下游的各类要求没有一开始就确定，还是靠人来缝缝补补。

• 干复杂度高的事就像在抽卡 - 简单聚焦的事情，当下模型能处理得很好；但一旦复杂度升高、需要拆解分段来做就容易走偏。干到一半上下文丢了，模型偶尔还会随机"降智"，本该一步到位的逻辑有时效果很好，有时被拆得七零八落，最终又得靠人来缝缝补补。

• Top模型活干得好但太贵太脆 - 之前一直在用Opus和Codex作业，效果确实好，但动不动封号、服务不稳定、价格贵得离谱还随时可能被断供，不可能把整条生产线全押在上面。

• 是真的害怕带着Mac进电梯 -  人工本地跑Qoder、QoderWork，一断网会话就得重开—— 流水线全靠一个人在按电钮，网一断人离开整条线就停了，重启的credits如雪花般消逝。

• 没有人在看执行过程到底做得如何 - 每个Spec需求、每个应用、每次执行过程，重复遇到了多少问题？花了多少不该花的token？这些没有系统性的检查和反馈，出了问题靠人复盘，优化靠人经验。

一个工厂引进了最先进的数控机床，但质检靠目测、衔接靠人喊话、出了问题靠经验排查，关键设备随时可能被断供，而且整条产线只能在一台个人电脑上跑——车间还是手工作坊的管理方式。

我的判断是：AI Coding的真正瓶颈不是模型能力，而是缺少一套像工业流水线一样的交付体系。

回顾工业化的演进史，每一次跃迁的背后都有一条暗线：新的驱动力 + 新的生产组织方式。蒸汽机推动了工业1.0，电气化和流水线定义了工业2.0，电子信息和自动化带来了工业3.0，数据和智能正在催生工业4.0。100年前亨利·福特把汽车制造拆解成一条流水线——每个工位有明确的输入、输出和质检标准，零件沿着传送带流动，最终组装成一辆完整的车。这个思路不仅改变了制造业，也成为后来所有大规模生产的原型。

今天，信息和智能正在驱动软件工业化的下一次跃迁。我们逐渐意识到，好的交付体系应该做到：每个阶段有明确的产出物，每个产出物有质量卡点，整个过程可追溯、可验证、还能持续自优化。更重要的是，这套体系不能建立在对顶级模型能力的依赖上，就像成熟的工业流水线不会要求每个工位都是博士，而是靠工艺标准和流程设计让普通人也能稳定产出合格产品——好的交付体系应该让非顶配的模型也能在约束下可靠地完成工作。所以我们对端到端的交付体系提出一个设计原则：基于相对成熟模型的能力下限去设计、稳定安全优先、可持续有效输出、成本可控。

这里要厘清一个边界：模型能力下限的升级是模型团队的问题，端到端交付体系是我们自己的问题。 我们确实依赖模型能力，但不能把所有赌注都押在"等模型更强"上。模型在进步，那是它的课题；怎么在现有模型能力下把交付做稳、做快、做可验证，这是我们的课题。端到端交付体系要解决的是：怎么约束产出质量、怎么组织生产过程、怎么做阶段性质检、怎么驱动持续优化。把这两件事分开，我们才能专注把自己的体系建好，而不是天天追着模型版本跑。

这篇文章，是正在实践的——《端到端交付2.0体系》。

2.0 端到端体系从今年4月启动，走两轨并行：

• 第一轨：Agent自动化生产——云上Agent分身 + 钉钉，让非研发角色（产品、运营）也能直接提需求，系统自动走完全流程交付。目标是"分身全自动执行"，解除并发瓶颈，人从操作者变成监督者。

• 第二轨：端到端2.0新规范——工业流水线式的多Agent作业体系，定义从PRD到上线的全链路规范，包括Harness约束体系、Spec生产流程、自检机制、持续优化飞轮。

两轨的关系是：自动化生产先用1.0体系并行建设，同时2.0新规范体系在平行推进；等2.0规范体系成熟后，自动化生产轨道最终切换到2.0体系上来。简单说，1.0是当前的生产力，2.0新规范是升级后的生产力，自动化生产是跑在上面的业务目标——先骑旧车赶路，同时造新车，新车造好了就换过去。

2.0体系的核心架构可以拆成两条链路来看：正向链路和反向链路。

正向链路是生产过程，Agent贯穿全链路：

• 产品Agent：生成PRD，输出PRD文档和质检记录

• 设计Agent：生成技术方案，输出Spec（spec.md + plan.md）

• 编码Agent：生成代码，输出分批次tasks

• 自检Agent：生成自检报告，输出check_reports + ADR

• 测试Agent：生成测试用例并执行，输出用例与执行报告

反向链路是改进过程：阶段产出物检查 + Session log分析 → 发现问题 → 反哺物料优化和规则迭代。

这个架构有三个核心特征，可以概括为"三可"：

可追溯：需求id贯穿全链路——从PRD到代码到测试，一个aone_id串起所有产出物。Spec文档放在研发统一过程链里，任何时候都能回溯一个需求是怎么从一句话变成一段代码的。

可验证：研发自检 + 平台扫描，多重过程检查。不是等到上线后才发现bug，而是在流水线的每个阶段都有质检卡点。

可优化：Spec内容 + Session分析反哺物料优化、规则迭代。这不是一条静态的流水线，它会自己"长"——每一次执行都会留下session log，分析这些日志能发现物料缺陷和规则盲区，然后迭代优化。

还有一个贯穿所有Agent的关键架构原则：本地可执行 + 平台在线执行的双轨设计。 端到端体系中的每一个Agent——无论是编码Agent、自检Agent还是统计&Loop扫描——都必须同时支持两种执行方式。日常情况下，研发同学可以在本地的Qoder、QoderWork上直接跑、看结果、调物料，迭代效率最高；但最终的正式执行必须在组织平台的Agent上跑——平台有完整的执行记录采集、统计归集和合规审计能力，确保产出物的可追溯性和权威性。这就像本地开发环境可以随便调试，但代码合并必须走CI/CD流水线一样。

端到端交付这个课题，拆解成了7个子课题：

必选5个（构成主链路闭环）：Coding Agent、PRD生成&质检Agent、研发自检Agent、测试Agent、统计&Loop工程。这五个串起来就是从需求到交付的完整链路。

非必选2个（扩展能力）：领域知识库（给Agent提供充足的领域知识）、简单需求自动端到端生成（AI Native的云上交付路径）。

必选的5个是"主航道"，非必选的2个是"扩展包"。当前每个子课题都有对应的AI Native小组在推进，覆盖云通信的基础产品线先行。

当下展开其中最核心的四个课题：

• 【AI Native】数字分身的端到端交付

• 【2.0 规范】研发 Coding Agent - 生产物料体系（Harness & Spec工程）

• 【2.0 规范】研发自检Agent 

• 【2.0 规范】统计 & Loop工程

此外，知识库建设作为横向支撑能力，也会简要介绍其建设逻辑。

如果说前面三大块（物料体系、研发自检、统计&Loop）解决的是"怎么规范化地生产"，那这一块解决的是"谁来触发生产"——答案是：不一定非得是研发，但是一定是始于研发

真实场景是这样的：团队内部有大量运维类需求——补个监控面板、加个配置开关、做个取数功能、加个批量操作功能。这些需求不大，但数量多、排队久。研发觉得小活不值得专门排期测试，产品觉得小需求应该很快但就是排不上，日积月累，积压越来越多。

AI Native端到端交付要解决的就是这个问题：让产品或运营直接在钉钉里@数字分身提需求，系统自动走完从需求对焦到待交付的全过程，最终由研发review后交付上线。

整个流程分四个阶段：

• 阶段一：会话启动 形成在线会话链接（详见案例），开始 需求对焦——产品或运营在钉钉群聊或单聊中@数字分身，描述需求。协调者Agent（架构师角色）与用户多轮对话，澄清细节、确认边界，直到需求足够明确。这个阶段产出一份结构化的需求描述，等价于简化版spec。

• 阶段二：需求确认——协调者Agent把整理好的需求摘要发回给用户确认，用户确认OK后系统才往下走。这一步是人工卡点，防止Agent理解偏差后一路错下去。

• 阶段三：端到端自动生产——确认后系统启动7阶段自动流水线：需求接收→安全审核→技术方案→开发实施→测试验证→代码审查→部署上线。6个AI Agent按流水线阶段依次执行：

• 协调者（架构师）：整体统筹 + 用户交互，是用户唯一直接对话的角色

• 产品经理Agent：需求分析 + Aone读取，把模糊需求转化为结构化spec

• 后端工程师Agent：代码读写 + 终端命令，按spec执行开发

• 测试工程师Agent：跑测试、验证功能

• 代码审查Agent：Diff审计，独立视角检查代码质量

• 安全审核Agent：纯推理，合规评估

• 每个Agent最小权限、互不越权。执行过程中，用户可以通过Web实时面板（WebSocket推送）查看所有阶段进展和Agent对话记录。

• 阶段四：待交付——流水线跑完后，产出物进入"待交付"状态：代码已提交到分支、测试已通过、代码审查已完成，但还没有合并上线。最终由研发review产出物、确认无误后执行交付。这一步是必须的人工卡点——AI负责生产，人负责最终拍板。

真实案例：

整套系统运行在Devix云端安全工作空间里，每个用户独立隔离。核心编排引擎是team-manager（Python/FastAPI），内部由LangGraph StateGraph（9节点有向状态图）驱动编排，支持断点续跑——进程重启后从上次节点继续，不会因为网络波动丢失进度。Agent通过MCP协议对接集团内部工具（代码仓库、CI/CD、Aone、钉钉、语雀），实现真正的全链路自动化。

这也解释了为什么2.0体系是两轨并行而不是直接跳到全自动：先把规范体系建好、验证稳定，再把自动化生产轨道切过来。就像先造好流水线和工艺标准，再上自动化工位——工艺不达标就急着上自动化，只会批量产出废品。

当前的方案是：一个员工配一个数字分身，分身借用人的权限作业——代码提交用的是人的账号，CR发起用的是人的身份，Aone操作走的是人的权限。这样做的好处是快速启动，不需要额外的权限体系设计；坏处是分身的行为边界完全绑定在人身上，分身之间也无法协作。

长期的方向是把数字分身汇总为数字员工管理——一个组配几个数字员工，每个数字员工有独立的权限体系和身份标识，每个数字分身被数字员工使用，形成1：N结构。数字分身不再绑定某个具体的人，而是绑定某个角色和职责范围。比如"运维需求开发数字分身"有代码读写和CI/CD权限但没有生产环境操作权限，"测试数字分身"有测试执行权限但没有代码修改权限。到那个阶段，数字员工就是团队的正式成员，和人一样有工号、有权限、有考核。

扩展有两个维度：一是增加分身数量，从1人1个分身到1组N个数字员工，扩大并行处理能力；二是增加单个分身的需求并行度，当多个需求同时进来时，分身可以启动多组角色Agent并行作业——就像一个人同时开多个终端窗口，每个窗口处理一个需求。两层叠加起来，团队的吞吐量就不再受限于人头数了。

AI Native端到端交付不是另起炉灶，它遵循的仍然是2.0架构规范：Spec工程定义了"怎么一步步做"，Harness工程定义了"按什么标准做"，研发自检定义了"怎么验证做得对不对"，统计&Loop工程负责持续优化。唯一的区别是：执行者从"研发操作Agent"变成了"云端Agent自主执行"。

具体来说：云端Agent生成的spec文件夹结构和应用级完全一致（spec.md、plan.md、tasks.md、check_reports/、session/），自检Agent独立执行检查，统计&Loop工程的扫描同样覆盖云端产出物。这样保证了无论需求是研发手动跑的还是分身自动跑的，产出物标准统一、可追溯、可验证。

在讲具体的Harness和Spec之前，先讲清楚整个研发生产物料体系的全貌。

这套物料体系要解决的核心问题是：Agent在生产过程中需要遵循什么约束、产出什么标准物、怎么保证产出质量。 它由两大部分组成：

• Harness工程——定义Agent必须遵循的约束体系。包括四层约束（原则→宪法→规则→判例）、代码版本治理策略、以及落到代码仓库里的具体物料（App-Adr应用规约与技能、App-Desc应用说明、App-Research疑难杂症研究结果）。Harness回答的是"按什么标准做"。

• Spec工程——定义从需求到代码的生产过程。包括流水线分段（需求对齐→概设→详设→执行→检查）、每段的产出物标准（结果产出物+过程产出物+session log）、工作项分级管理。Spec回答的是"怎么一步步做"。

两者的关系是：Harness是工艺标准，Spec是流水线本身。

• 没有Harness约束的Spec就像没有工艺卡的流水线——能跑但产出不稳定；

• 没有Spec承载的Harness就像写满规章制度的白板——有标准但没有执行路径。

• 没有Spec+Harness约束的Agent：拿到需求直接写代码，产出不可控。今天写的和昨天写的风格不一致，命名随机，模块划分随心所欲。出了问题无法回溯——因为根本没有记录"它当时为什么这么写"。

• 有完整Spec+Harness约束的Agent：先对齐spec（做什么），再出plan（怎么做），再拆tasks（分步做），最后自检（做得对不对）。每一步都有产出物留痕，每一步都受Harness规则约束。出了问题翻session log就能定位根因。

可以说，Spec+Harness是端到端交付2.0的脊梁骨。没有它，后面所有的自检、Loop、平台扫描都没有锚点——你检查什么？回溯什么？优化什么？

在流水线上生产之前，你得先有工艺标准。Harness工程干的就是这件事——定义AI Agent在生产过程中必须遵循的约束体系。

"Harness"这个词来自马具。一匹好马（强大的模型能力）如果没有马具（约束规范），跑起来方向不定，还可能伤人。核心理念是：模型能力越强，约束体系越重要。

四层约束：原则→宪法→规则→判例

借一个类比来解释这个分层体系：把它想象成国家治理。四层从上到下是抽象等级递减、可执行性递增的关系。

原则（Principle）——顶层抽象概念 -> 相当于社会主义基本原则。从集团到部门到团队到应用，层层继承，是最顶层的价值导向。原则本身不告诉你怎么做，只告诉你什么不能违背。比如"代码必须向后兼容"、"新增接口必须有契约"这类不可商量的底线。

宪法（Constitution）——框架级抽象概念->相当于国家宪法。公共和抽象层面的约束，被各种执行工具（Qoder、Cursor、Codex等）自动加载。宪法是整个约束体系的中枢，它定义了Spec的逻辑（怎么组织需求文档）和Harness的逻辑（怎么约束执行行为），被所有下层规则所引用；但宪法仍然停留在"框架"层面，不直接指导具体作业。

规则（Rules）——实际指导作业的实现-> 相当于会计法、刑法。具体到某个角色的执行标准，是Agent真正落地时会加载和执行的约束。比如对研发的Maven构建规则、对测试的单测规范、对SRE的稳定性检查项。规则里每一条都能直接对应到"这一步该怎么做"。

判例（Cases）——具体规则操作的解读-> 相当于最高法判例。规则本身是文字描述，但具体到某个复杂场景怎么应用，往往需要看已有的案例。判例必须成对出现正例和反例——正例说明"符合规则的正确写法长这样"，反例说明"违反规则的常见错误长这样、错在哪里、正确的修正是什么"。只有正例，Agent容易依葫芦画瓢但抓不到本质；只有反例，Agent知道不能怎么写但不知道该怎么写。正反成对，才能把规则在实际场景中的边界和取舍讲清楚，避免Agent对规则的机械理解和过度演绎。

为什么要分四层？因为不同的抽象层级需要不同的治理频率。原则几乎不变，宪法偶尔调整，规则随业务频繁迭代，判例持续沉淀。如果全塞在一个文件里，改一条规则可能不小心影响了原则；反过来，一条判例的沉淀也很难反哺到抽象的原则层。分层之后，各层独立演进，互不干扰，而且每一层的读者都很明确——顶层给决策者看，宪法给架构师看，规则给Agent看，判例给需要参考的人看。

存量代码版本治理：像法律一样分"新法"和"旧法"

这里要单独聊一个Harness工程里特别重要的课题——存量代码的版本治理。

就像不同年代的法律对应不同的社会形态（82宪法、97刑法修正案、民法典），一个应用里的代码也有"新代码"和"老代码"之分。新代码遵循最新的架构规范和编码标准，老代码可能是三年前甚至十年前写的，遵循的是当时的规范。你不能拿今天的法律去判十年前的案子，同样也不能让Agent用新规则去改老代码——改着改着就炸了。

所以Harness工程里有一件事必须做清楚：优先把遵循新规的代码范围圈出来。具体来说：

• 新增逻辑怎么作业——新增的代码必须完全遵循最新的Harness规则。Agent在写新功能时，constitution、rules、skills全部按最新标准加载，没有任何历史包袱。这是最理想的场景，也是Harness发挥最大价值的地方。

• 涉及老代码怎么作业——当需求涉及修改老代码时，情况就复杂了。老代码可能不遵循COLA架构、可能没有DTO/Domain/DO分离、可能用的是过时的工具类。这时候Agent需要知道：哪些老代码是"已经规整清楚的"（已经按新标准重构过），哪些是"还没规整的"（还是老标准）。对于已经规整清楚的，按新规作业；对于还没规整的，Agent不能自作主张去"顺便重构"，而是要标记出来，交由人来决定。

• 哪些需要人兜底——老代码里那些还没被规则覆盖的"灰色地带"，就是人需要进去做研究分析的部分。Agent遇到这类代码时，应该停下来问："这段代码的历史背景是什么？为什么要这么写？如果要改，影响范围有多大？"而不是直接动手。这些需要人来兜底的范围，会随着Harness物料的持续完善而逐步缩小——每一次人做完研究分析，沉淀下来的结论就会变成新的规则或Skill，下次遇到类似场景Agent就能自己处理了。

这个治理过程的本质，就是把"人兜底"的范围逐步缩小，把"Agent自主"的范围逐步扩大。但不是一刀切——有些老代码可能永远不需要按新标准重构（稳定运行、不再迭代的模块），那就让它保持原样，在Harness里明确标记"此模块遵循旧规，不做改造"。

Harness工程的内容组成

约束体系不是写在PPT里的口号，而是实实在在落到代码仓库里的文件。每个应用的Harness物料分为三大件：App-Adr（应用规约与技能）、App-Desc（应用说明）、App-Research（疑难杂症研究结果）。

• App-Adr（应用规约与技能）——应用级的规范和技能集合，是Agent执行时自动加载的强制约束。App-Adr内部按角色再分成两个包：

• develop/——研发看自己的部分，告诉Agent"研发该怎么做设计、怎么做编码"。内部包含 develop-standards/（规范）和 skills/（技能）两个子目录。以短信监管应用为例，develop-standards里有S-001到S-011共11条标准，覆盖COLA架构规范、DTO/Domain/DO分离、Lombok数据对象规约、HSF接口规约、TDDL配置规范、Mapper设计、动态参数配置、日志规范、JUnit5单测规约等；skills里则是从应用中提炼的编码模式和最佳实践（如k001-gateway-pattern网关模式、k003-processor-framework处理器框架、k006-mapstruct-conversion对象转换规范），Agent加载后能直接按团队最佳实践写代码，而不是从零摸索。

• test/——研发看测试的部分，告诉Agent"研发自己该怎么测、测试环节有哪些要求规范"，同时覆盖流水线下游测试部分的内容物（用例设计规范、测试数据准备约定、Mock策略、覆盖率要求等）。内部同样包含 test-standards/（测试规范）和 skills/（测试技能）两个子目录。这一部分让Agent不仅"知道怎么写代码"，还"知道怎么把代码写得可测、测得放心"。

• 按develop/test分包的好处是：同一份Agent物料，服务研发和测试两条子链路的需求——研发Agent加载develop包做设计和编码，测试Agent加载test包做用例生成和执行验证，各取所需、互不干扰。

• App-Desc（应用说明）—— 相当于给Agent一张地图，让它不会在代码森林里迷路。包含应用的模块结构、包路径、关键DomainService类、依赖关系等，除此之外App-Desc还承载了前面讲到的代码版本治理的划分——哪些模块/包是遵循新规的"新法区"，哪些是已经规整过的"过渡区"，哪些是暂不改造的"旧法区"，都在这里明确标注。Agent进到某个包动手改代码之前，先查App-Desc就知道这块地皮是什么年代的、按什么标准作业、遇到不清楚的地方要不要停下来找人兜底。

• App-Research（疑难杂症研究结果）——专门存放对特定复杂问题的研究结论。有些问题不是一条规则就能讲清楚的，需要完整的背景调研、多方案对比、决策取舍过程。这些内容不适合塞进规则或技能里，就单独存到App-Research，作为Agent遇到相似复杂场景时的参考资料。它承担的是"经验沉淀"的角色——一个问题被人研究过一次，下次Agent或人再遇到时不用从头开始摸索。

如果说Harness是工艺标准，那Spec就是流水线本身——它定义了从需求到代码的生产过程：分几段、每段干什么、每段产出什么、怎么验证。

四条设计原则

• 遵循Spec原则（SDD + TDD）。SDD（Spec-Driven Development）意味着先写规格再写代码，TDD（Test-Driven Development）意味着先写测试用例再实现功能。不是Agent拿到需求就开始写代码，而是先把"要做什么、怎么做、怎么验证"写清楚，然后才动手。

• 遵循Harness驾驭工程。Spec的生产过程本身受Harness约束——模板怎么组织、文件怎么命名、检查报告怎么分类，都有规范。

• 不绑定Agent工具。物料和执行器解耦。同一套Spec物料，可以在Qoder里跑，也可以在Cursor、Codex、Claude Code里跑。团队按自己的偏好选工具，但产出的Spec文件标准统一。

• 不绑定Spec框架。内部用speckit，但也兼容openspec、superpowers、kiro等框架。只要产出确定的标准文件（spec.md、plan.md等），用什么框架生成不重要。目前团队内AI小组有两套实现并行：简单需求偏多用openspec——流程轻量、上手快；复杂需求偏多用speckit——分阶段更严谨、约束更充分。两套框架产出的spec文件夹结构统一，统计&Loop工程的扫描检查都能覆盖。

流水线分段：从需求对齐到检查

一条完整的生产流水线分五个阶段，每个阶段有明确的产出物：

• 阶段一：需求对齐——把模糊的需求转化为结构化的spec.md。spec.md里包含aone_id元数据、功能规格（FR功能需求 / SC成功标准 / Given-When-Then场景描述）、用户故事。这个阶段的产出物spec.md就是后续所有工作的"合同"。

• 阶段二：概设（技术方案）——根据spec.md生成plan.md（不同spec框架中也可能叫design.md，但在2.0规范中统一以plan.md为准）。

• plan.md聚焦技术方案的工程化拆分：系统结构怎么走、主流程怎么串、模块怎么划分、组件怎么定义。它走的是"从上到下拆结构"的逻辑——先看整体架构，再看模块边界，最后看组件交互。经过调优的plan模板核心思想是：按场景适配多模板，关注主逻辑主流程和模块合理拆分，剪枝低效内容。Plan注重设计层，不包含伪代码。

• 阶段三：详设&任务拆解——把plan拆解为可执行的tasks.md。

• tasks.md的设计要充分考虑执行层面的现实：分几个批次执行？每个批次的步频跨度多大？不要一次搞太复杂，每个batch的任务量和上下文复杂度要控制在模型能稳定处理的范围内。为什么？因为模型在执行过程中会面临上下文窗口压力，如果一个batch塞了太多任务或者跨度过大，就容易出现预期外的上下文压缩——前面的任务细节被挤掉，后面的执行就开始"忘事"、走偏。所以tasks.md的核心设计原则是：批次合理、步频可控、单批复杂度不超标。 遵循"Plan主导"原则——tasks是plan的细化，不能偏离plan的设计。

• 阶段四：执行——按tasks分批次执行代码生成。每批次完成后记录执行结果。

• 阶段五：检查——研发自检Agent生成check_reports，多角度验证产出物质量，沉淀spec的ADR 内容到应用级。

注意2个关键的 Checkpoint

• 提测前一切以概设为准 - 测试和研发的交互协议

• 发布前一切以代码为准 - 反向对所有文档内容进行检查对齐，防止有一些模型没有改全的情况

标准化的需求过程记录 - spec文件夹设计

这是Spec流水线跟普通AI写代码最大的区别。每次生产不仅产出代码（结果产出物），还留下完整的生产记录（过程产出物）和对话日志（session log）。

• 结果产出物：spec.md、plan.md、tasks.md、代码文件、check_reports/。这些是"交付件"，直接跟需求走。

• 过程产出物：research.md（调研分析）、data-model.md（数据模型）、contracts/（接口契约）、sql/（DDL/DML脚本）、adr/（架构决策记录）。这些是"过程件"，记录了生产过程中的思考和决策。

• Session Log：conversation-log.md，Agent对话全过程记录。这是最重要的"黑匣子"——当交付物出了问题，回溯session log就能定位是物料缺陷、需求模糊还是模型幻觉。

所有产出物统一放在Spec文件夹里，结构如下：

specs/{aoneID}_{需求名}/├── spec.md              (必须) 功能规格├── plan.md              (必须) 技术方案├── tasks.md             (推荐) 任务分解├── research.md          (推荐) 调研分析├── data-model.md        (推荐) 数据模型├── contracts/           (推荐) 接口契约├── check_reports/       (必须) 研发自检报告│   ├── check.summary.md (必须) 检查汇总│   ├── 00-主链路检查报告  (强制) 端到端主链路│   └── 按角色扩展        (按需) 产品视角/研发视角/安全SRE视角├── test/                (推荐) 用例分析+报告└── session/             (必须) Agent会话记录└── conversation-log.md

[图：spec文件夹实拍——某个真实需求的specs/目录截图，展示完整的产出物清单]

工作项分级：三档管理

不是所有工作都需要走完整流水线。按复杂度和影响范围把工作项分成三档：

• 标准需求——有PRD或技术方案，需评审，>5人日。强制要求完整的Spec文件夹：spec文件 + 概设 + 全部检查报告 + 交付文档。

• 简单需求——研发可自测，不需正式评审，≤5人日。走简化版流水线：spec文件 + 概设 + 简化的检查报告（以单测为主）。

• 一般任务——零散技术任务（补单测、修字段等），不计入指标。无Spec文件夹要求。

这种分级的好处是：大需求重管、小需求轻管、杂活不管。避免了"杀鸡用牛刀"的过度工程。

打游戏的都懂：Solo能打小怪，但Boss战必须开团。而且团本不是随便凑五个人就行的——你得有MT扛伤害、近战DPS贴脸输出、远程DPS站桩输出、法系DPS控场AOE、奶妈加血保人，不同职业有不同的装备要求和操作规范，但团队目标一致、指挥统一、信息共享，才能通关。

AI Coding也一样。单应用Agent就是Solo——一个研发在一个应用里独立完成全流程，自己的规范自己说了算。但现实中的需求往往不止涉及一个应用。比如一个短信报备功能，可能同时涉及消息服务（alicom-message-service）、监管平台（alicom-message-supervise2）、计费引擎（alicom-billing-engine）三个应用联动变更——就像组了一个MT+远程DPS+奶妈的三人小队，每个应用有自己的技术栈和规范（相当于不同职业的装备和操作规范），但需要统一的项目级spec来对齐目标。

这时候就需要一套更高级别的物料——项目级物料（内部叫speckit-p）。项目级物料在应用级物料的基础上增加了三样东西：项目级宪法（constitution-p.md，最高优先级，覆盖应用级宪法）、跨应用接口契约（contracts/api.md）、以及Pre-check机制（检查各参战应用的物料是否就绪）。

• 准入条件——不是所有应用都能直接加入项目级联合作战。每个参战应用必须具备完整的AI Coding物料（App-Adr、App-Desc、App-Research、.specify、.qoder），Pre-check会逐个扫描，物料不齐的应用不能纳入联合开发。这就像打团本，组员等级和装备要够门槛才能进组。

• 统一指挥——单应用时，应用负责人就是"玩家"，自己决定怎么打。项目级时，需要架构师和PM角色来统一指挥：架构师负责跨应用的技术方案对齐和接口契约定义（相当于团队指挥喊技能CD），PM负责需求拆分、Phase编排和进度协调。各应用的研发还是各自执行，但大的方向和节奏是统一的。

• 信息互通——项目级spec文档随项目git分支管理，每个应用独立git仓库但共享项目级spec和接口契约。任何跨应用的接口变更都在contracts/api.md里定义，所有参战应用都能看到、都能对齐。

用一个具体例子来说明。假设有一个"短信网关全链路优化"的需求，涉及3个应用联合开发：

案例：

从实施效果看，项目级物料收益最大的两类场景：

• 前后端应用协作——涉及大量简单需求的快速落地。前端和后端接口对齐是AI Coding最容易出问题的地方，项目级接口契约把RPC/MQ定义清楚，前后端Agent各自生成代码时就不会"各说各话"

• 2-3个应用的中等规模跨领域需求——比如一个涉及消息服务+监管平台的功能改造，单靠人脑对齐接口和时序太费劲，项目级spec把跨应用的变更范围和数据流向统一描述清楚，各应用Agent按契约各自执行，效率远高于串行沟通。

这里可能有人会问：为什么不把所有单应用需求也套上项目级的结构？统一一套不是更规范吗？背后的考虑是奥卡姆剃刀——如无必要，勿增实体。在非协同的场景下，一个研发在一个应用里独立完成需求，没必要给自己套上项目级宪法、Pre-check、跨应用契约这些额外的约束。项目级物料是为了解决多应用协同的复杂度而生的，如果不存在这个复杂度，硬加上去就是自己给自己加活——流程更重、维护成本更高、执行效率更低。单应用需求走应用级物料，简单直接，够用就好；多应用协同需求才升级到项目级物料，按需升配。

Harness和Spec的物料体系讲完了，但一个实际问题摆在面前：一个新应用或者一个还没接入AI Coding的老应用，怎么快速配齐这套物料？以及物料建好之后，怎么持续迭代？

从0到1：两种安装模式

提供两种模式：

• 复刻模式——适用于相似框架的应用。从已成熟的应用直接copy核心物料（constitution.md、template文件夹、App-Adr、App-Desc、App-Research），然后根据新应用的样例代码结构做本地化适配，这类方式可以把一个应用快速复刻到中等成熟度。Agent会分析新应用的module结构、package结构、关键domain类，自动调整物料内容，整个过程Agent自动完成，只需要人review最终结果。

• 扫描安装&更新模式——适用于异构或全新应用的0-1。Agent扫描应用代码，自动识别架构模式和编码惯例，沉淀成Skills和Rules，然后生成对应的constitution和template。这个模式需要"重新认识"应用，所以耗时更长，但能产出更贴合实际的物料。

采用skill方式作业 - 详见 Skill市场。不管用哪种模式安装完物料，都不能直接上生产线。还得走三步：先检查、再热车、最后逐步上强度。

安装完成后，首先用统计&Loop工程对spec和harness物料做一轮完整性检查——constitution是否齐全、rules是否和最新规范对齐、skills是否覆盖了应用的核心编码模式。检查通过后，挑一两个简单需求（小功能、补单测这类）走一遍完整的spec生产流程，算是一次"热车"。热车的目的是验证物料在实际生产中能不能跑通、Agent在约束下产出的代码质量是否达标。

热车完成后，研发负责人评估一下：技能覆盖是否相对周全？常见编码模式有没有被遗漏？检查报告能不能有效发现问题？评估通过后，再逐步接更大的需求——从简单需求到标准需求，从单模块变更到跨模块改造。就像玩游戏打怪练级，先在"新手村"把装备和技能都凑齐了，确认能稳定输出了，再出去打Boss。

持续调优闭环

物料包不是"建一次就完事"的。它需要一个持续调优的闭环：

逐层适配（集团规范→部门规范→团队规范→应用自身规范） → 扫描式生成（提供最新代码示例，从原则落地到具体规则） → 执行过程中总结 → 优化规范和沉淀Skills → 下个需求验证效果。

这个闭环和后面要讲的统计&Loop工程紧密配合——统计&Loop工程发现的问题会直接反馈到Harness物料里，驱动规则迭代。

流水线上的产品，不能等到出厂了才检测。在汽车工厂里，每个工位完成后都有质检员检查——焊装完查焊点，涂装完查漆面，总装完查功能。研发自检Agent就是2.0体系里的"质检工位"。

这里要先厘清一个架构关系：研发自检Agent遵循Spec规范，但它是一个独立的体系。 用Java的术语来说，Spec工程定义了一套SPI（Service Provider Interface）——spec文件夹结构、check_reports/的格式规范、check_summary.md的判定标准，这些都是"接口定义"。研发自检Agent是这个接口的一个"实现"，它按照Spec的标准产出检查报告，但它本身的运行逻辑、检查策略、执行环境完全独立于编码Agent。除此之外还可以有其他"实现"——比如平台扫描、自动化测试、SRE合规检查——它们都遵循同一套Spec接口标准，但各自独立运行。这种解耦带来的好处是：编码Agent不需要知道自检Agent怎么工作，自检Agent也不需要知道编码Agent当时怎么想的，双方只通过Spec标准"对话"。

这是最关键的设计决策：自检Agent必须在独立会话和独立工作区中运行，不共享编码Agent的上下文。

为什么？因为让编码Agent自己检查自己，就像让厨师给自己的菜打分。它刚刚花了两小时写出这段代码，现在你让它找自己的bug？大概率它会告诉你"代码看起来没问题"。这不是能力问题，是心理学上的"确认偏差"——人会不自觉地为自己的决策辩护。

所以做法是：启动一个全新的Agent会话，给它全新的工作区，让它用"局外人"的视角审视变更。这个Agent不知道编码Agent当时为什么这么写，它只看到diff、spec、harness规则和知识库——然后独立做出判断。

• 挑战一：扫描范围要拉全。 一个需求变更的影响范围远不止当前应用的diff——产品层面的功能变更、关联应用的主干分支、外部接口和消息依赖，都得纳入检查范围。漏掉任何一个维度，就可能出现"改了A系统，B系统挂了但没人发现"的情况。解决方案是把检查范围精确推断出来：联合Review范围 = 本应用diff + 关联应用分支 + 知识库上下文 + spec/plan。具体来说，自检Agent从git diff入手（这次改了什么），结合spec（本来要做什么），再拉取关联应用的分支（上下游有没有被影响），最后叠加知识库上下文（这个应用的特殊约定和历史坑）；同时依赖注册中心的元数据自动发现上下游依赖，结合代码库扫描识别外部接口和消息引用，确保检查范围既精准又全面。

• 挑战二：多视角检查，不能只看代码。 研发自己看代码只看逻辑对不对，但产品关心的是功能覆盖全不全，测试关心的是用例场景够不够，SRE关心的是可运维性和安全合规。每个角色关注点不同，检查维度也不同。自检Agent必须模拟多个角色的视角，分别出具检查报告，而不是用一个"代码没问题"就交差。具体展开见下节"多角色检查报告"。

• 挑战三：控制信息量，不能一次塞太多。 这和Spec工程的tasks.md设计是同一个道理——一次性检查太多内容，模型的上下文窗口扛不住，容易出现信息压缩，前面的检查结果被挤掉，后面就开始"忘事"。当前的策略是先确认主干逻辑，再分而治之：先跑主链路检查（端到端的功能覆盖），确认主干没问题后，再按模块逐个检查细节。这样既保证关键路径不出错，又避免信息过载。

质检不是一个人说了算。按角色分成多个检查维度：

• 产品视角：需求-功能-组件逻辑覆盖完备性。 检查实现是否覆盖了spec中定义的所有需求点。有没有遗漏的功能？用户故事里的Given-When-Then场景是否都被实现了？

• 研发视角：架构合理性 + 代码质量 + 变更内容检查。 架构是否符合Harness定义的规范（比如COLA分层有没有违反）？代码有没有编码规范问题、逻辑矛盾？变更内容是否完整（TODO有没有遗留、注释掉的代码有没有清理）？

• 安全/SRE视角：外部影响 + 可运维&安全合规。 上下游依赖和接口变更有没有影响其他系统？新增的接口有没有做参数校验？数据库变更有没有向后兼容？日志规范有没有遵守？可运维性（监控、告警、回滚方案）是否到位？

每个维度独立出一份报告，最终汇总成check_summary.md，标注overall_result：

PASS：全部通过，可以进入下一阶段

CONDITIONAL_PASS：有非阻塞性问题，修复后可继续

FAIL：存在阻塞性问题，必须修复后重新自检

问题需要带上证据，所有报告写入check_reports/目录，除了固定的check.summary.md和主链路检查报告外，其他报告按角色扩展（产品视角/研发视角/安全SRE视角），避免检查内容过于细碎。

案例：

如果说Spec工程是"生产"、研发自检是"质检"，那统计&Loop工程就是"质量改进部门"——它不生产产品，但它让整个流水线越跑越好。

在真正的工厂里，流水线不只是"跑生产"，还有一套完整的日志分析和持续改进体系。丰田的"5Why分析法"追问五层才找到根因，西门子的产线用帕累托分析锁定导致80%故障的那20%关键设备，六西格玛的DMAIC方法（定义→测量→分析→改进→控制）把每一次异常都变成可复用的改进案例。这些方法论的共性是：不是出了问题才修，而是盯着数据找规律，把隐性缺陷变成显性改进。

统计&Loop工程干的就是这件事——对流水线上的物料体系、过程文档、执行日志做多维度检查，发现问题，反向优化整个生产飞轮。

统计&Loop工程的核心是"4+1"——前4个维度是发现问题、驱动优化的检查闭环，+1是度量合规执行率的统计维度。两者的目的和产出不同：前者输出"改进建议"，后者输出"指标数据"。

4个问题检查维度：

案例：

+1 统计维度：Agent生成判定

怎么判断一个需求是不是"Agent端到端生成"的？四个硬性条件必须同时满足：

• aone_id：spec.md元数据头中的aone_id可在Aone系统中匹配到

• spec.md：存在且内容校验通过

• plan.md：存在且内容校验通过

• check_reports/：存在且内容校验通过

四个条件同时满足才计入"Agent生成需求"的分子。

session/目前作为强制上传要求，但暂不作为判定条件——思路是先把需求的相关会话数据收上来再推进问题的分析

举一个飞轮验证的真实案例：实践中发现某类需求的session log里，Agent总是在"数据模型设计"阶段反复修改，对话轮次异常高。分析后定位到原因——plan模板里缺少"枚举定义"这个章节，Agent在写plan时没有显式列出枚举值，到tasks阶段才发现枚举不全，回头改plan，再改tasks，循环了三四次。改进方案很简单：在plan模板里加上"枚举定义"章节。改完之后，基于近20个同类需求的对比统计，对话轮次下降了约40%。这就是飞轮转起来的效果——发现问题、改进模板、验证有效、反哺全局。

统计&Loop工程的扫描检查可以在两个地方执行：

本地执行：通过QoderWork的e2e-scanner技能，在研发本地直接跑扫描。适合单应用、单需求的快速检查，出结果快，反馈即时。

平台执行：交由统一平台批量执行。适合跨应用、跨产品线的全量扫描和统计分析。平台会把扫描结果汇总，生成产品线和团队维度的统计报告——哪个团队的Spec完整率最高？哪个应用的Session对话轮次最少？哪些规则被违反最频繁？

把4+1串起来，统计&Loop工程的完整闭环是：

统计&Loop工程是整个2.0体系里最难建设但价值最大的部分。 Spec工程和Harness工程是"基础设施"，建好了就能用；研发自检是"质检工位"，加上去就能拦问题；但统计&Loop工程是"飞轮"，它需要数据积累、需要分析能力、需要组织层面的闭环机制。

前面讲的Harness和Spec解决的是"怎么约束Agent的行为"，但Agent要写出贴合业务的代码，还需要充足的领域知识——这个应用有哪些核心DomainService？历史上踩过哪些坑？某个业务概念的准确定义是什么？

知识库分本地和远程两层：

• 本地精炼知识库——每个产品/应用维护一份非常小的知识文档（.md，

• 远程kbase知识库——用于收集现有的领域知识文档、历史需求归档、架构设计文档等。kbase是知识的"蓄水池"，核心信息会定期同步精炼到本地知识库中，形成"远程收集→精炼沉淀→本地加载"的知识流转闭环。

这块目前正在筹划建设中，还没有完全落地。但方向是明确的：Agent不能只靠规范干活，还得有领域记忆——就像一个新员工不光要看编码规范，还得了解业务是怎么回事。

这套体系还在持续建设和打磨，远没到终态，但方向是确定的：AI Coding的未来不是"更快的代码生成器"，而是"更好的交付体系"。

最后分享两个观察到的趋势：

• 过去一个研发用一个Agent工具干所有事，未来会是用不同的工具和模型做不同事情 ，比如CC适合做需求分析和设计、Qoder做分批次执行、Codex 查bug能突出适合代码review——各有所长，成本不一，这块需要在全链路上做好选择。

• mac 作业最终会变成云上作业，随着Qoder Cloud Agent ，Devix，A2A 安全网关等配套完善, 工作环境可能变成1本地拖N云上。 研发从"操作Agent"变成"监督Agent"，最终变成"审批Agent"。简单需求甚至不需要研发介入，产品/运营直接通过数字分身驱动交付。

如果你也在探索AI Coding的端到端交付，欢迎交流。这个系列后续会展开产品PRD生成&质检、测试用例执行、长时间自主生成等子课题的详细设计