复杂业务团队的AI Coding交付实践

本文作者寂秋，来自淘天集团-物流技术团队。一支专注于物流订单履约业务研发的技术团队。依托多元业务场景，我们持续探索与迭代技术能力，长期投入稳定性建设及智能化建设，为数百万商家提供稳定可靠的订单履约与物流体验，为数亿包裹安全高效流转保驾护航。

1.整体背景

过去一段时间，复杂业务场景下的 AI 研发交付逐渐形成了一些共识：通过 Wiki 补齐团队上下文，通过 skills 和研发模板约束 AI 的分析、拆解和编码过程，再通过知识回补把需求里的经验沉淀下来。

在真正进入落地阶段后，每个团队都会遇到自己的具体问题，业务复杂度不同，应用数量不同，历史包袱不同，组织分工不同，发布和质量要求也不同。Wiki 怎么建，skills 怎么写，研发模板怎么拆，review 点放在哪里，最终都会有差异。

所以这篇文章主要讲我们团队是怎么设计的。

2.基础介绍

我们是一个复杂业务后端团队，系统中存在多个业务域、多个应用、多个模块，日常研发也会按应用、按模块、按业务方向协同。同时为了支撑各种繁杂的业务、保障稳定性、避免故障和资损，我们在架构上做了许多妥协，部分需求最终改动的代码可能不多，但前面的理解、拆解、确认和 review 链路会比较复杂，代码不仅要会写，还要写在对的位置上，延迟系统腐化，所以某种程度上也比较依赖开发者的经验。

考虑到这种复杂性，也为了能够平稳落地，所以我们没有一开始就奔着"短时间全自动化"去做，而是把 AI 研发流程的落地分成了三个阶段。第一阶段先打底：建设知识库，沉淀团队上下文；再用 Coding Agent CLI + skills + Markdown 模板，把需求分析、应用拆解、实现校验和知识回补这条链路跑通。

我们内部把这套流程叫 RD，也就是 Research Development。

名字是我们取的，本质上它就是一组 skills、命令协议和 md 文档。当前主要通过 Coding Agent CLI 来执行，但它并不和某一个 Coding Agent 强绑定。只要其他 Agent 能读取这些 Markdown 文件，理解里面的 requirement、analysis、implementation-check 和 continue-prompt，也可以接着干活。

这也是我们最开始先做 Wiki + skills + RD 流程的原因。

通用 Coding Agent 会越来越强，模型能力也会快速变化，新产品也会不断出现。业务团队很难长期押注某一个工具形态。真正值得花时间打磨的，是那些最有团队特征、最难被通用工具直接替代的东西：业务知识、应用边界、研发规范、质量门禁、跨应用协作方式和历史经验。

工具可以换，模型可以升级，底层的团队上下文和研发协议需要自己沉淀。

我们这套实践可以概括成三步：

知识库 + 工具链  -> 自动化流程  -> 自主协同交付

第一阶段先把知识库和 RD 流程跑稳。第二阶段再把更多流程动作交给 Agent 自动推进。第三阶段才是更完整的协同交付，包括开发、测试、发布、观测、回滚等生产链路。

这篇先讲第一阶段，也是我们认为最值得投入的底座部分，二三阶段我们正在开发中，后续也会有文章发出来分享。

3.总体设计

三层资产

当前这套系统可以理解成三层：

命令协议层  -> .agents/commands/  -> .agents/skills/
知识资产层  -> knowledge/
RD 过程资产层  -> rd/requirements/{requirementId}/

命令协议层定义 /kb:* 和 /rd:* 命令怎么工作。例如先读哪些规则文件，什么时候要澄清，什么时候必须停止，产物写到哪里，哪些事情可以继续执行，哪些事情需要人工确认。
知识资产层放在 knowledge/ 下。这里沉淀正式知识、候选知识、个人经验、模板、路由规则。
RD 过程资产层放在 rd/requirements/{requirementId}/ 下。这里保存某一个需求从输入、材料、澄清、分析、拆解、实现校验到知识回补的全过程产物，这些产物在设计上着重做了可以「跨会话执行」，解决上下文压缩导致的漂移问题。

用流程表示，大概是：

需求 / PRD / Bug / 变更
  -> /rd:verify-prd            - 前置输入质量提升
  -> /rd:work                  - 通用 rd 命令，自动引导下一步
  -> /rd:clarify               - 需求澄清，结合知识库补充不确定点
  -> /rd:analyze               - 需求分析，产出模块需求摘要
  -> /rd:decompose             - 需求拆解，生成 by 应用的 requirement
  -> /rd:verify-requirement    - 确认需求无遗漏
  -> 业务应用仓库开发
  -> /rd:apply                 - 代码实现
  -> /rd:validate              - 对比需求和代码，更新实现状态
  -> /rd:code-review           - 结合原始需求与研发规范，对代码进行 CR
  -> /rd:release-plan          - 生成发布计划与待确认点
  -> 发布
  -> 知识回补

这里的每个命令都不是为了多生成一个文档。它们更像研发过程里的检查点，把原来散落在聊天记录、人脑和临时文档里的判断，落到可以复用、可以 review、可以接续的文件里。

同时为了降低使用难度，将 /rd:work 命令作为路由命令，其他命令作为原子能力。

这套方法并不是为了替代所有研发流程，也不是说所有需求都要完整跑一遍 RD。对于很小的局部修复、纯样式调整、一次性脚本、低风险工具需求，直接让 Agent 修改再人工 review，最后使用 kb 命令入一下知识库，可能就足够了。

RD 更适合这类场景：需求跨多个应用，业务状态和上下游协议复杂，历史兼容逻辑多，发布风险高，或者需求本身需要多轮澄清和拆解，在这种场景下进行高质量的交付。

我们真正想解决的，是"复杂需求容易在理解、拆解和扩展点选择上走偏"的问题。

整体架构

整体架构示意：

整体架构

研发流程

研发流程示意：

研发流程

4.知识库设计：先分层，再进入研发流程

很多团队做 LLM Wiki 时，会先从"把文档整理给 AI 看"开始。这个方向没问题，但在复杂业务团队里，很快会遇到几个问题：

知识到底准不准；
哪些知识经过 owner 确认；
哪些只是历史材料里的线索；
哪些内容必须回到当前代码核对；
一个需求进来后，应该先读哪部分；
应用级知识和全局业务知识怎么区分；
个人经验、候选知识、正式知识怎么流转；
模板和目录规则怎么强约束。

如果这些问题不先设计清楚，Wiki 很容易变成另一堆"看起来有用、实际不知道怎么用"的文档。

所以我们把 knowledge/ 设计成一个比较完整的知识资产目录，而不是只做应用文档集合。

当前核心目录是：

knowledge/
├── main/
├── applications/
├── candidate/
├── personal/
├── template/
├── INDEX.md
├── README.md
├── KNOWLEDGE-RULES.md
└── ROUTING.md

知识库分层架构

main：沉淀业务域内的通用知识

knowledge/main/ 放的是跨应用、跨系统、跨业务线的通用知识。例如：

业务域内的核心术语；
跨应用流程；
通用状态定义；
全局技术约束；
多应用都要遵守的业务规则。

这类知识不能归到单个应用里。main/ 更像整个业务领域的"公共语境"。

applications：应用范围内的知识

knowledge/applications/ 放每个应用自己的知识。一个应用目录大致长这样：

knowledge/applications/application-xxx/
├── application-xxx.md
├── INDEX.md
├── domain/
│   ├── product/
│   ├── solution/
│   └── base/
└── tech/

application-xxx.md — 应用总览，说明负责什么、不负责什么、上下游、核心模块。
INDEX.md — 应用内导航，AI 先读 INDEX，再按需读取。
domain/product/ — 产品能力知识，如创单、取消、下发、回告、状态流转等。
domain/solution/ — 解决方案知识，某个业务身份对 product 能力的差异化扩展。
domain/base/ — 基础索引，如 API、消息、模型、Repository、表、字段语义等。
tech/ — 技术相关知识，如架构约束、异常处理、事务边界、MQ 规范等。

一个示意性的应用目录结构：

knowledge/applications/application-core/
├── INDEX.md
├── application-core.md
├── domain/
│   ├── product/
│   │   ├── flow-create-order.md
│   │   ├── flow-cancel-order.md
│   │   ├── flow-dispatch-order.md
│   │   ├── flow-operation-report.md
│   │   ├── flow-update-address.md
│   │   ├── flow-order-control.md
│   │   ├── state-order-lifecycle.md
│   │   └── state-unit-lifecycle.md
│   ├── solution/
│   │   ├── solution-A/
│   │   ├── solution-B/
│   │   ├── solution-C/
│   │   ├── solution-D/
│   │   └── legacy-adapter/
│   ├── base/
│   │   ├── api.md
│   │   ├── msg.md
│   │   ├── model.md
│   │   └── repository.md
│   └── README.md
└── tech/
    ├── tech-architecture-constraint.md
    ├── tech-framework-architecture.md
    ├── tech-process-routing.md
    ├── tech-product-extension.md
    ├── tech-error-mq-handling.md
    └── tech-scheduler-task.md

AI 读应用知识时有明确路径：

先看应用职责  -> 再看 product 主干能力  -> 再看 solution 差异逻辑
 -> 再看 base 里的接口/消息/模型/Repository
 -> 必要时读取 tech 里的研发规范和技术约束
 -> 最后回到当前代码确认

KB 提供稳定上下文，当前代码仍然是实现事实。

candidate：候选知识暂存区

knowledge/candidate/ 是候选知识区。需求执行过程中，AI 会分析出很多有价值的信息，这些内容不应该全部直接写进正式知识库。有些结论来自当前需求上下文，有些只是推断，有些还没有 owner 确认。

待合并知识先放这里，标清来源、证据、可信度和待确认项。后续经过 review，确认是稳定知识，再合并到 main/ 或 applications/ 里。

personal：个人研发经验和踩坑记录

knowledge/personal/ 放个人经验，例如某类线上问题的排查经验、某个模块的踩坑记录、个人对某条链路的理解草稿。如果某条 personal 经验被多次验证，或被 owner 确认，就可以转成 candidate，再进入正式知识库。

template：强约束的知识写作模板

knowledge/template/ 放各类文档模板，例如 application 模板、domain 模板、flow 模板、state 模板、rule 模板、code 模板、tech 模板。

模板不是建议格式，而是强约束。YAML Front Matter 里的字段让 AI 能判断知识的类型、可信度、证据来源等。

application 模板示例（YAML Front Matter）：

---
id: KB-APPLICATION-{DOMAIN}-{SEQ}
type: application
domain: {domain}
application: {appCode}
appType: 后端应用
status: DRAFT
sourceType: official
owner: {userId}
version: 1
updatedAt: YYYY-MM-DD HH:MM:SS
confidence: medium
stability: evolving
evidence:
  - code: {核心模块或仓库路径}
  - doc: {应用文档或系统说明}
  - human: {确认人/时间}
tags:
  - {tag1}
  - {tag2}
anchors:
  - APPLICATION:{appCode}
  - BIZ_IDENTITY:{identity1}
---

ROUTING：让 AI 先定位，再读取

knowledge/ROUTING.md 是知识库里非常关键的入口。收到一个需求后，AI 不应该全量读取 knowledge/。它应该先抽取关键词、业务身份、应用名、Topic、接口名、状态名、模型名、表名等，然后通过 ROUTING 定位。

ROUTING 路由示意图

例如，需求里出现某个 Topic：

Topic  -> ROUTING 定位目标应用  -> 读取 application INDEX
 -> 读取 domain/base/msg.md  -> 找到 Producer/Consumer
 -> 进入相关 product flow 或 solution flow
 -> 回到代码确认消费入口

知识回补

对于知识库来说最怕的不是不完整，而是错误知识长期存在。所以通过 candidate 承接，只有具备明确证据来源、经过 owner 确认、且被认为具备一定稳定性的内容，才会进入正式知识库。

personal 个人经验  -> candidate 候选知识  -> owner review
 -> official 正式知识  -> 需求执行中被引用
 -> 代码或业务变化后更新/deprecated

知识回补流程

5.RD 流程：用 Markdown 承载研发状态

知识库解决的是稳定上下文来源，RD 流程解决的是复杂需求怎么推进。

RD 流程产物目录结构：

rd/requirements/{requirementId}/
├── source/
│   ├── input.md
│   ├── input.summary.md
│   ├── changes.md
│   ├── materials.yaml
│   └── materials/
├── clarification.md
├── execution-plan.md
├── analysis.md
├── analysis/
│   ├── application-a.md
│   └── application-b.md
├── decomposition.yaml
├── requirement-model.yaml
├── status.md
├── knowledge-backfill.md
└── applications/
    ├── application-a/
    │   ├── requirement.md
    │   ├── implementation-check.md
    │   └── continue-prompt.md
    └── application-b/
        └── requirement.md

这样做有几个好处：

长会话可以拆开 — 大需求不需要在一个会话里从 PRD 一路写到代码。
新会话可以接上 — 上下文不依赖聊天历史，而是依赖落盘文件。
人可以 review — 每个阶段的关键判断都在文件里，不会藏在模型的中间推理里。
其他工具可以接入 — 当前用某一款 Coding Agent CLI，后面也可以切到别的。

1. 原始需求不能直接进入编码

第一步通常是 /rd:verify-prd，检查 PRD 或需求输入里有没有明显缺口。然后进入 /rd:work，保存原始输入和材料。接着通过 /rd:clarify 做澄清，/rd:analyze 做知识检索和代码 explore，/rd:decompose 拆应用级 requirement。

fail-fast：能在 PRD 阶段暴露的问题，不拖到 requirement。能在 requirement 阶段暴露的问题，不拖到编码。

2. requirement.md 是应用级开发契约

一份合格的 requirement.md 至少要说清楚：

这个应用在本需求里的目标；
非目标和不能碰的边界；
相关知识依据和代码证据；
涉及哪些接口、消息、状态、字段和规则；
需要改哪些模块；
编码前优先阅读哪些入口；
需要满足哪些验收标准；
还有哪些问题没确认；
哪些稳定结论后续要回补知识库。

3. validate 解决接续和对账问题

/rd:validate 会拿应用级 requirement.md 和当前本地分支 diff 做对账，判断每个需求项状态：

done：已经完成
partial：部分完成
todo：还没做
changed：需求或代码发生变化，需要更新 requirement
blocked：存在阻塞，需要人工确认

validate 之后会产出 implementation-check.md 和 continue-prompt.md。

开发可以中断，研发上下文不能丢。

6.质量门禁：把人机 review 放在关键位置

当前比较重要的门禁包括：

/rd:verify-prd — 输入质量门禁
clarify review — 阻塞问题和业务口径确认
analysis / routing review — 应用边界和影响范围确认
/rd:verify-requirement — 编码前开发契约确认
方案 review — 扩展点、架构路径、兼容策略确认
/rd:validate — requirement 与代码 diff 对账
/rd:code-review — 发布前代码质量和方案一致性确认
/rd:release-plan — 发布、灰度、回滚、观测确认
knowledge backfill — 稳定经验回补知识库

这里的人机 review 不是让人把 AI 做过的事情重做一遍。它更像交付系统里的关键检查点。人只在高价值位置介入，确认那些最容易造成返工和事故的业务事实。

我们也不追求 100% 全 AI。如果 AI 做到 95%，剩下只是简单改两行，研发同学手改更快，那就手改。复杂业务交付的目标是总成本更低、质量更稳、风险更可控，不是追求"代码全部由 AI 生成"的纯度。

7.案例：一次跨阶段的真实交付

需求背景

上游服务商通过一个新的回告状态触发"差异调整"，要求当前应用在主流程入口处做一系列前置校验，校验通过后落差异数据，并以事件驱动方式异步调用既有的订正流程。

需求功能点

第一轮：覆盖了大部分功能，但关键扩展点偏了

工具：Coding Agent CLI，最高能力档模型
需求拆解基本准确，但漏掉了"重量大于 0 的校验"
AI 自己 review 出 7 个需要确认的点，进行了人工澄清
但方案设计阶段仍然有两个明显丢失

第一轮 AI 代码分析结果：

第一轮AI代码分析结果

第一轮结论：

第一轮结论

AI 代码采纳率：约 75%
根本原因：PRD、澄清及设计过程均未明确需要在特定位置执行前置校验逻辑

第二轮：把关键约束写进 requirement，并加强 review

关键变化：把"两阶段异步架构"明确写进了 requirement 和方案输入里
人工 review 补充了历史业务身份兼容等信息

第二轮 AI 代码分析结果：

第二轮AI代码分析结果

汇总结果：

第二轮汇总结果

代码采纳率：95% 以上
中断次数：3（问题澄清 1 次、Review 调整 2 次）

没有继续追求 100%。到 95% 以后，剩下如果只是简单问题，手改更快就手改。

关键指标

我们更关注几个更贴近交付质量的指标：

PRD 阶段发现了多少 open item；
requirement 阶段拦截了多少不清晰项；
validate 阶段发现了多少 requirement 与代码 diff 不一致；
代码采纳率大概是多少；
人工中断发生在哪些阶段；
问题是 PRD 表达不清、知识库缺失、扩展点判断错误，还是纯编码问题；
需求结束后回补了多少稳定知识。

8.为什么我们先打底，再自动化

做 AI 研发交付，很容易一上来就想做自动化。但这些能力我们也会做，但不会把它们放在最前面。

因为自动化流程跑得越快，对底座的要求越高。如果知识库不准，requirement 不清楚，review 点没有设计好，自动化只会把错误更快地执行完。

第一阶段，我们更愿意把时间花在三件事上：

知识库要打磨 — 让团队经验逐步变成可检索、可路由、可验证的知识资产。
RD 流程要打磨 — 让需求输入、澄清、分析、拆解、实现校验和知识回补变成稳定协议。
质量门禁要打磨 — 让人机 review 点放在最关键的位置，尽早发现高返工成本问题。

9.走向 AI 研发 Harness

后面会继续把这套实践往 Harness 化推进。Harness 可以理解成一个确定性的研发交付环境，它会把知识库、工具链、权限、流程状态、质量门禁、验证规则和发布约束统一收进去，让 Agent 在团队定义好的轨道里工作。

第一层是运行环境的确定性：Agent 进入一个需求时，应该知道本地应用仓库在哪里、使用哪些命令、先读哪些知识库入口、requirement 写在哪里、哪些动作必须停下来等人确认。

第二层是研发协议的确定性：Agent 不能拿到需求就直接写代码，它应该沿着团队定义好的路径推进。

另外，在真实落地时也会控制 AI 访问边界：只让 Agent 读取当前需求需要的仓库和知识目录；敏感文档、线上数据、密钥、客户信息不进入 prompt；对外分享时需脱敏。

10.写在最后

目前复杂业务下的 AI 研发交付，Wiki + skills + 研发模板已经逐渐成为共识。真正拉开差异的地方，在具体怎么设计、怎么治理、怎么进入团队研发流程。

几个明确的判断：

知识库要分层 — main 放全局业务知识，applications 放应用范围知识，candidate 承接待确认知识，personal 保留个人经验，template 约束知识写作结构。
RD 流程要文件化 — Coding Agent CLI + skills 只是当前执行方式，底层产物是 Markdown。后续切换工具会更顺。
质量门禁要前置 — 复杂业务里，晚发现的问题通常更贵。
人机协同 review 是交付系统的一部分 — AI 负责大部分分析和实现，人负责关键判断和最终质量。
不追求 100% 全 AI — AI 研发交付的价值不在"纯度"，在总交付成本、质量稳定性和风险可控性。

这套东西看起来比"直接让 AI 写代码"慢一些。但在复杂业务团队里，前面多花一点时间把知识、流程和质量门禁设计好，后面才能少返工、少走偏、少靠 owner 临时救火。

AI 发展很快，工具和模型都会继续变化。团队自己的业务上下文、研发协议和质量门禁，越早沉淀，越容易跟上后面的变化。