用一句话概括：当任务越完整、规模越大、越能抽象为稳定流程时，对话式AI Coding的局限性就越发明显，而此时Harness工程的价值才真正得以体现。

这正是应用宝活动平台团队在上半年对整个系统进行重构时所面对的核心课题。借着重构的契机，团队将Harness Engineering的理念引入新活动平台系统，初步搭建了一套AI端到端的开发流程。本文不仅记录了一次技术升级，更是一次关于“如何在真实业务研发中落地Harness工程”的实践复盘。

一、为何要实践 Harness Engineering

项目启动时，我们和许多团队一样，先尝试了对话式AI Coding。结合CodeBuddy + Plan Mode、Rules与Prompt、AI辅助编码以及人工Review这套策略，项目总算顺利起步。

坦白说，在处理一次性任务和小型需求时，效率确实令人惊喜。但随着项目复杂度持续攀升，问题开始接连涌现。我们归纳出以下四个核心痛点。

1.1 单窗口上下文快速膨胀

为了让AI充分理解业务背景、代码规范与项目结构，每次对话都需在Prompt中重新输入这些信息。后来团队学聪明了，将背景知识、规范、生成规则等沉淀为文档或rules，每次对话时直接加载。

然而，随着项目持续迭代，这些背景和规则越来越多。很多时候，窗口尚未真正开始工作，上下文就已不堪重负。更棘手的是，同一窗口中多轮交互后，上下文进一步膨胀，出现有损压缩，导致AI遗忘早期指令或偏离既定规则。

1.2 缺乏完整的业务知识

每次开发新需求，都需要有人在Prompt中清晰阐述需求背景、相关业务知识以及服务间的协作关系。一个需求往往横跨多个服务，这些服务如何串联、如何协作，全靠人工梳理后再喂给AI。构造一份完整的上下文，所耗费的精力远超想象。

1.3 缺乏工程上的自动化闭环

对话式AI Coding仅能在编码环节提升效率。一个需求的完整交付，还包含需求分析拆解、测试环境部署、接口验证、测试等多个环节。这些环节仍需人工亲自执行和验证。要让AI在这些环节真正提效，必须从工程层面实现全流程的AI能力集成，构建从需求到上线的完整闭环。

1.4 单窗口无法并行

在一个窗口中与AI对话，一次只能处理一件事。如果一个需求涉及三个独立的开发任务（如三个互不依赖的接口），要么逐一排队让AI处理，要么同时开启三个窗口并行推进。而人工需要不断在这些窗口间切换、对话，推动整个流程向前。

二、整体架构：知识库工程 ✖️ 端到端开发工程

应用宝活动平台的Harness工程，最终被拆解为两大核心能力板块：知识库工程，以及在此基础上构建的端到端开发工程。

知识库工程负责将散落在代码、文档、可观测系统中的工程知识，按照统一结构进行沉淀和持续更新，然后供给上层的端到端开发工程使用。

而端到端开发工程，以“状态文件”为驱动核心。一个需求从需求拆解→需求澄清→任务拆解→并行开发→单测校验→代码审查→测试环境部署→用例请求构造→接口验证→提交代码，全流程由AI自动执行。人在其中的角色，仅负责核心关键阶段的决策与信息补充。

目前，这套体系已沉淀800+份结构化文档，知识范围覆盖后台90+个微服务；端到端流程中内置了12个专家Agent、30多个业务相关Skill以及10+个固定流程脚本。

由此可见，知识库工程是整个体系的基石——上层端到端开发流程的每一个环节，从需求拆解到接口验证，都离不开它提供的准确、结构化的业务上下文。因此，我们先从知识库工程说起。

三、Knowledge Engineering——让 AI 真正懂业务

在复杂业务系统中，AI最大的问题从来不是“不会写代码”，而是它缺乏真实、准确、持续更新的业务知识作为背景。

回顾对话式AI Coding的核心痛点，实质就在这里：每次开发需求，都需要人工将多个服务、业务背景、接口调用关系等逐一梳理清楚，再喂给AI。更关键的是，这份上下文是一次性的，用完即弃。下次换个需求、换个窗口，一切又得从头开始。没有系统化的知识管理机制，AI每次执行任务，都相当于重新学习业务。

因此，知识库是整个Harness工程体系的基石。它直接决定了AI在需求拆解、技术方案制定、代码生成、接口验证等每个环节中，能否获取正确且充分的上下文。但不得不说，知识库体系的建设，目前也是业界公认的难点。在我们团队实践中，主要卡在以下几个问题上：

• 冷启动涉及的知识数据规模大：应用宝游戏研发后台覆盖了游戏宝券/礼包、活动平台、私域运营、微下载等多个业务域，维护着数百个微服务。每个服务少则十几个接口，多则二十个。仅接口文档的梳理编写，工作量就极其惊人，更不用说业务逻辑、领域知识等内容。
• 大量知识背景下如何精确提取：在如此庞大的知识库中，如何针对每次问答精准命中所需内容，是一个必须解决的难题。
• 知识更新迭代快，过期风险高：产品在持续迭代，代码和业务形态更新极快。过去“代码改了文档没改”几乎是常态。一份半年前的业务梳理文档，大概率已与当前逻辑严重脱节。

我们借鉴了LLM Wiki和Obsidian-Wiki的方法论与实践，搭建了一套结构化知识库，由两部分协同构成：

• 自动生成部分：通过Skill体系让AI自动读取代码、自动生成结构化文档、自动维护新鲜度。
• 手工沉淀部分：由人在custom.md和common/中沉淀业务背景、架构决策、使用规范等AI难以从代码中直接提取的知识。

两者结合，形成了“AI生产 + 人工补充 + AI消费”的闭环，为Harness工程提供持续更新的知识信息。

3.1 整体目录结构

知识库结构分为三层：

• 总览层 backend/overview.md：描述所有业务域的关键词与服务范围，是知识库查询的第一入口。
• 域层 {group}/meta.yaml + {group}/custom/：机器可读的服务索引 + 业务域级别的手工沉淀文档。
• 服务层 {service}/*.md + {service}/custom/：每个服务8类自动生成文档 + 手工补充文档。

文档文件分为两类：

手工沉淀文档：

自动生成文档：

手工沉淀文档与自动生成文档地位等同，kb-query在查询时会同时考虑两类来源。

3.2 知识生成：从代码到结构化文档的自动化流水线

我们定义了两个skill：gen-project-docs和batch-doc-generator，分别支持单服务和批量多服务的文档生成。

生成时，以服务入口文件为起点，通过import追踪找到所有接口注册点，再从go.mod定位proto包提取接口定义。每类文档按规范模板写作，并进行增量融合——如果服务已有文档，新生成的内容会保留人工补充的业务注释，只更新代码层面的事实性信息（接口增删、参数变更）。

为区分接口是线上实际在用，还是已废弃或低频使用，我们以“接口调用量”为指标，在文档生成前查询伽利略上的调用信息，并在文档中标注接口活跃度。

知识库通过meta.yaml作为注册中心，记录每个服务的文档状态和git hash等信息。skill会根据git hash变更判断是否需要重新生成（增量模式）。对于全新增的知识，支持仓库导入模式：直接从Git URL导入仓库，自动完成克隆、文档生成、业务域归属分析和meta.yaml更新。

3.3 知识检索：渐进式加载

知识的提取查询一直是个热门话题，现在业界逐渐形成一种共识：采用层次化加载结合大模型探索的方式，替代传统的RAG检索。

这种方式之所以更优，是因为它复刻了人类专家学习复杂资料的真实习惯：

1. 精准定位而非模糊匹配：标准RAG依赖向量算相似度，往往不够精确。层次化加载基于知识的真实逻辑与引用关系进行寻址，能剔除无关信息，避免污染大模型上下文。
2. 自顶向下的按需吸收：人类学习总是先抓框架再看细节。“全局大纲-核心摘要-底层明细”的知识金字塔，让大模型顺着脉络按需加载，既不会在海量长文本中迷失，又能大幅节省token。
3. 变“被动查”为“主动探索”：RAG往往是一次性被动检索，而探索机制让Agent能像专家研究课题一样，根据初步线索在知识网络里顺藤摸瓜、多步跳转，自主拼凑出最精准的上下文。
4. 向量库系统维护成本高：知识库天天更新，维护一套RAG向量库的同步成本太高。直接依托结构化的知识本体进行探索，系统架构也更轻盈。

在我们的知识库工程中，同样采用渐进式分层加载+grep的方式实现结构化知识的检索：

设计思路是：

• 第一层几乎总是加载（文件很小），通过关键词匹配缩小到1-2个业务域。
• 第二层用grep在meta.yaml里精确筛选，避免加载整个域的服务文档。
• 第三层根据查询模式只加载必要的文档类型——接口搜索连overview.md都不读。

同时，提供了四种查询模式：

• 模式A：产品需求拆解。将PRD分解为可执行的后端Story。输入自然语言需求描述，输出包含：涉及服务列表、Story拆解（用户故事格式）、每个Story可复用的现有接口和需要新增/改造的点。
• 模式B：技术方案拆解。针对具体技术目标生成技术方案文档，包含时序图、任务拆解表、接口调用关系及关键注意事项。
• 模式C：接口搜索。最轻量，适合“找到对应接口就行”的场景。
• 模式D：知识库问答。适用于询问业务概念、业务流程、字段含义、表结构、逻辑细节等知识性问题，按需加载多个服务文档，结合custom_docs.md中的人工经验给出准确回答。对细节性问题，还能自动下载代码进行回答。

3.4 文档新鲜度检测：过期知识比没有知识更危险

前面提到，知识更新迭代快，容易过期。过期知识比没有知识更危险。如果AI引入了一份过期的知识，可能导致整个流程被误导，而且排查起来极为困难。

我们切身体会过这种痛苦：一次开发需求中，让AI调用一个接口，由于知识库没更新，AI调了一个老接口。整个链路都通了，但始终拿不到预期结果。排查了很久才发现是调到了老接口上。

为此，我们引入了文档新鲜度检测任务。其工作原理是比较两个git hash：meta.yaml中记录的git_hash（上次生成文档时的代码版本）和仓库当前HEAD的hash。当差异超过阈值（可配置，如超过一定天数或commit数）时，文档会被标记为过期，生成任务json，然后派发codebuddy命令行以增量模式更新生成文档。

增量模式的关键是最小改动原则+人工批注保留：增量生成把git diff的内容喂给大模型，同时让模型读取已有文档，根据diff对文档进行最小幅度修改。同时识别其中人工添加的业务背景说明、使用示例等“高价值内容”，在新文档中予以保留。这避免了“每次更新都要重新补充上下文”的重复劳动。

另外，log.md历史保护机制确保了可审计性：每次生成都向log.md追加一条记录（含git_hash、执行时间、变更摘要），严禁覆盖历史条目。即使某次生成出错，也能通过log.md结合git追溯到上次成功状态。

目前，这套知识库工程已覆盖应用宝游戏后台包括活动、福利、商城、增长等在内的4个业务领域，涵盖90多个微服务，800+份结构化文档。

四、端到端开发工程建设——从“写代码”到“交需求”

要突破对话式AI Coding的瓶颈，核心不在于模型本身有多聪明，而在于将开发模式从“一个对话窗口”升级为一套工程系统——这正是Harness Engineering的核心思想。在我们的端到端开发工程中，围绕这个思想，主要做了以下几件事：

• 拆分上下文替代单窗口累计：把长的开发流程拆成多个聚焦的、相对独立的子任务，由单独的子agent执行，每个子agent只加载它当前需要的信息。
• 以状态文件替代容易被压缩的对话历史：将开发流程的进度、每一步的产出等信息持久化，使整个执行流程具备可观测、可中断、可恢复、可协同的能力。
• 用确定性编排替代概率性发挥：把需求拆解→开发→单测→代码评审→部署→接口验证等流程固化为按序推进、带质量验证的流水线，每一步不达标则不往下推进。
• 用DAG + 多Agent并行替代单线程串行执行：自动识别任务间的依赖关系，编排为DAG拓扑结构，同一层的任务分发给并发agent在隔离环境中同时开发，再统一收口。
• 打通从开发到提交代码的全流程：集成TAPD、123、03、rick、伽利略、七彩石、无极等各大平台的能力，打通需求实现各环节与外部依赖。

4.1 状态文件驱动：让流程脱离对话窗口而独立存在

在对话式AI Coding中，整个开发过程依赖对话历史传递上下文。随着开发推进，对话历史迅速膨胀，引发三个典型问题：

1. 上下文有损压缩导致AI遗忘早期信息或偏离既定规则；
2. 流程中断后无法恢复——一旦对话窗口关闭或上下文被截断，所有中间状态全部丢失；
3. 流程推进缺乏可观测性，人和AI都不知道执行到哪一步了。

解决思路很明确：长链路必须状态化。把开发流程的每一步进度、产出、依赖关系持久化到文件中，让上下文脱离对话窗口独立存在。

4.1.1 状态文件：流程的唯一真相源

整个端到端开发流程的状态被持久化在两类结构化JSON文件中：

• product-state.json：用于产品需求拆解后的多Story并行开发流程，记录拆解阶段（breakdown）、并行分叉阶段（forking）、合并收口阶段（joining）等状态；
• e2e-state.json：用于单Story的端到端开发流程，记录当前所处的Phase（0~7）、每步的产出、接口验证结果等。

每个子Agent在独立上下文中执行完毕后，将结果写入状态文件的对应字段。主调度器不依赖对话记忆，而是直接读取状态文件确定“现在到哪一步了、下一步该干什么”。状态文件落盘，流程自然可中断、可恢复、可观测。

4.1.2 激活标志 + hook 机制：强制流程推进

光有状态文件还不够——AI可能在流程还没结束时“偷懒”停止。为确保流程能按照状态文件完整驱动执行，并且每个子Agent执行后能准确将状态和结果落地，我们引入了hook机制，在三个事件（Stop、SessionStart、SessionEnd）中注入脚本逻辑：

• Stop Hook：流程不可被主调度器“偷懒式”提前停止
• SessionStart Hook：跨会话断点可自动恢复
• SessionEnd Hook：会话结束后清理残留状态，不污染下一个无关会话

4.2 专家 Agent 体系：每个专家只做一件事

流程拆分成多个步骤后，最直接的做法是让同一个Agent依次执行每一步。但实践中发现两个问题：

• Agent在角色频繁切换时行为不稳定——可能在开发步骤里越权去修改协议，也可能在审查步骤里顺手改了代码。
• 不同步骤对模型能力的要求差异很大：简单的状态解析用便宜模型即可，复杂的需求拆解则需要更强的推理模型。

因此，我们基于以下原则设计了一套专家Agent体系：

1. 单一职责：一个Agent只干一件事。code-reviewer只评不改，interface-verifier只诊断不改，code-fixer只在收到问题清单后才动手。
2. 上下文隔离：每个Agent在独立上下文执行，只看自己该看的输入。既避免注意力稀释，也避免上游噪音污染下游判断。
3. 工具最小权限：按职责裁剪工具集，审查类不给写文件权限，规划类不给发布权限，从机制上禁止越权操作。
4. 确定性的输入输出：Agent之间不靠“对话”传递信息，而是靠结构化状态文件。输入是明确字段，输出也是明确字段，可被脚本解析、可被断点恢复。
5. 模型可插拔：职责边界清晰后，每个Agent可独立选模型——简单步骤用便宜模型，复杂推理用更强模型。

通过角色定义 + 工具约束 + 知识隔离，我们为每个阶段设计了专门的专家Agent：

对比直接调用子Agent执行，这套体系带来了三个实际收益：

• 通过角色定义，AI的执行行为更加稳定。
• 通过预先内置Prompt，避免每次执行都需要主调度器临时拼凑，减少调度器的负担和抖动。
• 便于独立维护和更新迭代：可以单独修改某个专家的行为而不影响其他流程；针对不同专家，可以选择不同模型来执行。

4.3 从串行到并行：DAG 编排 + Fork-Join

一个业务需求被拆分成若干子需求，每个子需求又被拆成多个开发任务后，如果全部串行执行，耗时会非常长。同时，主流程下的上下文信息也会快速膨胀。为此，我们从两个维度做了优化。

4.3.1 Worktree 隔离：同一需求内的多任务并行

即使单个需求内部，多个独立接口或模块之间也往往没有先后依赖，完全可以同时开发。

我们定义了task-planner这个Agent，专门负责任务拆解与并发编排规划。它会根据需求文档和实现方案，按接口、功能模块拆解任务，并标注每个任务的依赖关系及预测需要修改的目录文件，最终将所有任务按依赖关系构建成DAG拓扑分层。同一层的任务可以并发执行。主调度器根据拆解结果，为并发执行的任务分配不同的worktree给开发Agent，并在所有开发Agent执行完成后，统一执行merge操作收口。

4.3.2 Fork-Join：多需求的并行开发与统一收口

产品需求复杂时，通常先拆成多个story单，再依次完成。如果需求涉及多人协作，由于整个需求需要一起提测，往往会拉一个临时分支，大家把开发代码都往上合，然后统一发布到测试环境测试。

我们的实现也类似。在原有流程基础上，前置了一个需求拆解阶段。这一阶段结合建设的业务知识库，对需求进行分析，并经过与人的多轮交互澄清，将一个完整的产品需求拆分成多个子需求。

之后，调度器进入Fork并行开发阶段，执行从任务拆解到代码CR的流程。其中拆解的多个任务，仍然按上述逻辑并行开发：

Phase 1: 任务拆解 → Phase 2: 波次开发(并发) → Phase 3: 单元测试 → Phase 4: 代码审查

所有代码开发完成后，调度器进入Join阶段，完成后续合并、发布、验证、提交等流程。

4.3.3 冲突治理：事前隔离与串行收口

并行不是把任务拆开就完事。多个Agent同时修改代码，不可避免会产生冲突。处理不当，会导致编译失败、代码被错误覆盖等问题。我们对四类冲突分别制定了策略，核心思路就一个：能事前隔离的就事前隔离，必须共享的就串行收口。

4.4 脚本化执行：确定性操作交给脚本

跑通流程后复盘发现一个现象：整个端到端流程中，大量步骤其实是确定性操作——解析状态文件的JSON、创建git worktree、执行编译命令、调用发布工具等。这些操作不需要推理，只需要执行。让AI来做这些，不仅白白消耗token，还引入了不必要的随机性——AI可能写错shell语法、用错参数、或者在无关步骤上发散。同一需求多次跑、不同模型跑，token消耗和结果都可能不一致。

由此得出一个重要结论：AI负责认知，脚本负责执行。AI的价值在于判断、分析、生成这类需要“想”的动作，而确定性的执行操作，应当交给脚本。

我们将端到端开发流程中固定操作步骤脚本化，前后沉淀了接近15个脚本。每个流程中，具有明确输入输出、或操作路径非常清晰的步骤，都改为用脚本执行，在消除不确定性的同时，也省下了不必要的token消耗：

• 状态机解析执行脚本e2e-dev.py：主调度器读取状态文件、解析和确认下一步状态，改为调用脚本直接拿到结果。
• 多任务并行开发worktree脚本worktree.sh/sub_worktree.sh：将git worktree的创建/merge/多分支集成/清理等操作封装成脚本一键执行。
• 编译发布脚本build-and-publish.sh：将服务编译发布抽取为通用脚本，一键发布。
• 知识库一键初始化/更新脚本kb-init.sh：每次使用知识库检索前，在本地进行初始化或更新。
• ……

4.5 打通最后一公里：将 AI 嵌入 DevOps 全流程

端到端开发的流程远不止写代码。一个需求的完整交付，还涉及TAPD创建子需求、Rick平台修改协议、123平台发布服务、七彩石修改配置、伽利略查看日志等等。如果这些环节都需要人手动在不同平台之间切换，AI就只能起到局部加速的作用。

因此，我们将公司内各平台的能力进行了系统化集成，让AI在流程中经人工确认后，可以直接完成跨平台的读写操作。

4.5.1 tRPC-Gateway：让本地 AI 能调通内网接口

后台服务部署在123平台上，属于内网idc环境，但AI的执行是在本地电脑上。如何实现idc环境调用？针对每个服务申请白名单显然不够通用。最终通过tRPC-Gateway解决。

4.5.2 Codar：AI 写的代码，让 AI 来审

AI自身缺乏全局视角，对结合业务逻辑边界的隐含bug识别能力弱。一种直接方式是：自己沉淀一套与业务逻辑相关的CR规则集，并持续更新。但在活动平台系统重构之初，团队就和Codar团队合作，在代码MR环节引入Codar的CR流水线。实践下来发现Codar对隐含业务逻辑漏洞的识别能力出色。因此进一步合作，将Codar CR skill集成到我们的CR步骤中。

CR环节，AI除了根据现有代码规范进行CR外，还通过Codar提供的CLI工具对增量代码进行CR，将问题和风险级别返回给主调度器，由Fix Agent针对问题修改。

4.5.3 多平台读写集成

一个需求的开发流程中，涉及TAPD创建子需求单、Rick平台更新协议、123发布服务、七彩石修改配置、伽利略监控等。目前，大部分平台都提供了相应的MCP服务或Skill来实现AI集成，基本可以在Knot平台和03平台上找到这些功能。我们的端到端开发工程也已基本集成上述平台的能力，AI在流程中经人工确认后，可直接在相应平台上执行读取/写入操作。

五、复盘、规划与思考

5.1 实践复盘：核心工程原则

经过多轮调试与架构演进，以下是一些核心经验与优化建议。

应对异构服务拓扑，构建目录解析抽象层：实际业务中的代码组织形式复杂多样，涵盖单仓单服务（Multi-repo）、单仓多独立服务目录、以及共享go.mod与底层公共包但具备多main.go入口的Monorepo架构。直接依赖Agent Skill来兼容这些异构拓扑，会成倍放大调试成本。建议在工程架构初期，优先建立统一的目录解析抽象层。

调度架构演进：从 Agent 驱动转向强类型代码编排：早期基于Claude与Skill机制构建更新流时，就已发现指令依从性不足的问题。为控制成本引入hy3-preview后，进一步暴露出流程失控（如子Agent越界接管主链路）及调试周期过长等痛点。为此在知识库工程上优先做了两个调整：

• 弃用主子Agent模式：改由外部主程序编排全局流程，通过代码直接调度Codebuddy CLI，实现职责解耦——hy3-preview专注局部服务文档生成，Claude负责高维度的域及全局架构综述。
• 弃用Shell脚本：大模型生成的Shell脚本常潜藏隐性语法错误或边界逻辑漏洞，且往往在长链路末端才抛出异常，极耗排查时间。最终将驱动层全面重构为Go代码，利用强类型语言的特性保障执行控制流的严密性与稳定性。

严格禁用项目级 Memory 以保障状态隔离：全局Memory机制会引入不可控的上下文串扰，导致Agent偏离既定职责，并严重破坏单一子任务的幂等性与可复现性。在构建强确定性的自动化流程时，必须彻底关闭该功能。

引入 Mock 机制，分离调度逻辑与生成耗时：自动化构建流水线主要由“流程调度”与“文档生成”构成。调度逻辑最为复杂，而生成任务耗时最长。及早引入Mock机制，通过模拟或跳过大模型的实际生成环节，能以极低成本快速验证、迭代调度链路。

如果上面这些是具体场景下的经验，那么再往上抽象一层，可以提炼出几条贯穿整套Harness工程的核心原则：

• AI负责认知，脚本负责执行——工程的核心思想
• 长链路必须状态化——状态脱离上下文落盘，才能稳定续传
• 知识库必须结构化——业务知识结构化，AI才能精准检索
• Agent必须职责隔离——单一职责、上下文隔离、最小权限
• 执行步骤必须脚本化——执行问题不要交给推理
• Workflow比Prompt更重要——流程编排的确定性，胜过反复打磨prompt
• 终局认知：未来比拼的不是“用了多少AI”，而是能否把AI当作一个工程系统来设计

5.2 下一步：从“能跑”到“跑得好”

目前这套Harness工程，仅仅处于“能跑”的起步阶段，很多地方还有待完善：

• 缺少自我复盘迭代的自进化能力，每次跑完流程后，依赖人工发现并修复问题。
• 缺乏一套完善的评估体系，来评估AI端到端开发流程的稳定性、开发效果、token成本消耗等。
• 整套体系重度依赖codebuddy cli工具运行，还未实现工程与工具的解耦。
• ……

最近Claude发布的Workflow模式，也给我们带来新的启发。团队正在尝试将流程编排引入这套工程实践，把原来“AI自己根据状态文件串联流程，必要时由AI调用脚本”的方式，改为“由脚本实现流程串联，必要时由脚本调用AI”。至于哪种方式才是业界的标准答案，目前没有定论，大家都在摸索。但方向是一致的——让确定性的归脚本，让认知的归AI。

5.3 一些开放性思考

5.3.1 TDD 在 AI 时代：先写测试还是先写代码？

TDD是软件工程中令人向往的开发模式，但在实际代码开发中很难践行——接口字段、校验规则、依赖接口，甚至很多业务逻辑，往往都要等代码和协议落地后才能确定，提前写单测极易返工。

因此，在我们的实践中，TDD的落地不在代码层面，而是集中在接口测试用例上：在一开始的需求方案设计环节，便会根据需求生成一份需求级测试用例，包含输入输出的预期。在流程后面的请求验证环节，便基于这份测试用例构造请求，并判断结果是否符合预期。

5.3.2 AI 工程的架构分层：我们缺的不只是好 Agent，还有好架构

传统软件工程中，代码如何组织、架构如何设计，有非常成熟的方法论：MVC、DDD、Clean Architecture等。但对于AI工程，架构上如何设计，Agent、Skill之间如何组织，AI工程与AI工具如何解耦，Agent与Skill如何插拔式组合——当下似乎还没有成熟的方法论或实践规范。更多是结合Code工具的规范，定义一个skill目录、一个agent目录，然后就往里加。我们这套工程中的组织方式，也有同样的问题。工程与工具的解耦、Agent/Skill的分层与插拔式组合，是后续要重点优化的方向。

5.3.3 代码还重要吗？——从“代码为王”到“架构为王”

在AI生产代码效率越来越高的当下，有一种说法是“忘记代码的存在”：人不再逐行审查AI写的代码，只关心运行结果是否符合预期。

但是，我们面对的并不是一个工具系统，而是一个涉及多微服务、调用链路复杂、有高并发高性能要求的复杂在线业务系统。就现阶段来说，保持高质量的代码架构依旧非常重要：

1. AI代码腐化速度非常快，哪怕是现在的Claude Opus 4.8，放任迭代也会很快偏离既定规范。
2. 高质量的代码和架构会反哺AI，让AI生成的代码质量更高，这是一个正反馈过程。
3. 一旦人对代码失去掌控，线上出问题就只能完全靠AI排查定位。

但不能否认这个观点的前瞻性。在我们团队内部也有类似的实践：重构后的活动平台系统，在With平台搭建了一套统一的集成看板，集成了在线活动一览、活动实时参与情况监控、活动消耗实时监控、活动诊断、活动复盘等能力，实现全活动生命周期的一站式运营。

这套看板代码100%由AI通过对话式Vibe Coding生成，没有一个人去CR过它的代码。前端、后台、产品、运营，任何同学只要有活动看板的需求，都可以在上面通过对话方式集成。

区别在哪里？看板这类“结果导向、容错率高、无强一致性要求”的系统，适合黑盒化；而核心在线业务系统，现阶段仍需要人守住架构这条线。

而这条线，或许也会随着AI的进化不断后撤。或许终有一天，代码会像汇编语言那样，从开发者手中精心雕琢的核心资产，退场为智能体之间无声流动的中间表达——被生成，被消费，却不再被凝视。

从“逐行审查”到“忘记代码”，变化的从来不是代码的价值，而是人在系统中的位置。这条边界还会继续移动，而我们能做的，是始终想清楚：此刻，人究竟该站在哪一侧。