1. 项目概述：用AI智能体重构整个应用生态的实践

最近几个月，我和团队一直在啃一块硬骨头：如何在不中断现有业务、不投入大量新人力的情况下，将一个庞大、耦合度高的遗留应用生态系统，系统性地迁移到一个现代化、可维护的架构上。我们面对的是一个典型的“历史包袱”：一个拥有130多屏的React Native前端，一个后端由近7000行纯JavaScript业务逻辑堆砌而成，包含65个以上端点，却缺乏清晰的架构分层。业务在跑，需求在提，我们不可能停下所有新功能开发，专门抽调几个人干上一年半载来做重构。这既不现实，也不符合商业逻辑。

正是在这种压力下，我们开始探索一条新路： 将AI智能体（AI Agents）深度整合到软件开发生命周期中，构建一个由规格驱动开发（Spec-Driven Development, SDD）和自动化测试驱动开发（TDD）支撑的、高度结构化的智能开发流水线。 这不是要取代开发者，而是打造一个“超级副驾驶”系统，让智能体们负责那些重复、繁琐且认知负荷高的任务——比如逆向工程分析遗留代码、根据规范生成详细技术方案、编写初始测试用例、甚至完成基础模块的实现——而人类开发者则聚焦于核心的架构决策、业务逻辑审查和最终的质量把关。

我们的技术栈围绕TypeScript生态展开，采用Monorepo管理，核心是 Turborepo + pnpm workspaces 。前端包括基于Expo的跨平台移动应用和React管理后台，后端则采用NestJS作为主BFF和Serverless风格的轻量级API。整个流水线的目标很明确： 在保证高质量、高可测试性和完整可追溯性的前提下，大幅提升大规模重构和日常功能开发的效率与一致性。

2. 核心架构设计与思路拆解

2.1 为什么选择“智能体协作流水线”而非单纯代码生成？

市面上已有不少基于大模型的代码生成工具，它们能根据自然语言描述生成代码片段。但在复杂的、上下文丰富的企业级应用重构中，这种“一次性生成”模式存在几个致命问题：

1. 缺乏上下文连续性 ：每次对话都是孤立的，模型不了解整个项目的架构约定、历史决策和业务领域知识。
2. 输出不可预测且难以约束 ：生成的代码风格、架构模式可能每次都不一样，需要人工大量修正，反而增加负担。
3. 无法执行复杂工作流 ：重构涉及分析、设计、实现、测试多个阶段，单一模型难以胜任。

因此，我们的设计思路是 “分工与协作” 。我们创建了一系列 高度专业化 的AI智能体，每个智能体只负责一个明确定义的、单一的任务，并且被赋予了特定的“技能”（Skills）和“护栏”（Guardrails）。这就像组建了一个数字化的开发团队，有专门的需求分析师、架构师、测试工程师和开发工程师，他们在严格的流程控制下协同工作。

2.2 Monorepo架构：统一与隔离的平衡

重构的基石是新的Monorepo架构。选择Monorepo而非多仓库，核心是为了解决 共享代码的版本同步 和 跨服务变更的原子性 问题。在重构过程中，前端和后端的接口契约（Contracts）会频繁变动，Monorepo能确保所有相关改动在一次提交中完成，避免出现“前端用了新接口，后端还没更新”的集成故障。

我们的工作区结构设计遵循了清晰的关注点分离原则：

monorepo/
├── apps/
│   ├── @mobile/       # 跨平台客户端 (Expo + Gluestack UI + Zustand)
│   ├── @api/          # 主BFF服务 (NestJS + Prisma)
│   ├── @backoffice/   # 管理后台前端 (React + shadcn/ui)
│   └── @backoffice-api/ # 管理后台API (Hono.js + Serverless)
└── packages/
    ├── @types/        # 共享的TypeScript类型定义（核心领域实体）
    ├── @contracts/    # API契约 (Zod Schemas & DTOs)
    └── @utils/        # 共享工具函数

这里有一条 黄金法则 ： @types 包只存放纯粹的类型定义（Interfaces, Types）， @contracts 包只存放用于运行时验证和数据传输的Zod模式（Schemas）和DTO。任何应用或服务都 禁止 自行定义重复的类型或契约，必须从这两个包中导入。这从根本上杜绝了“接口漂移”（Interface Drift），保证了整个系统数据模型的一致性。例如，一个 User 对象的形状，在移动端、管理后台和后端服务中，其TypeScript类型和运行时验证逻辑都来自同一个源头。

2.3 规格驱动开发（SDD）与自动化TDD的结合

SDD是我们的“设计蓝图”阶段。它要求在任何代码编写之前，必须先产出经过评审的、机器可读（同时也是人可读）的规格文档。这不仅仅是写需求，而是将业务需求转化为包含 可测试业务规则 和 详细技术实施方案 的系列文档。

自动化TDD则是我们的“施工与质检”阶段。但这里的TDD是升级版： 测试用例由AI智能体根据SDD产出的规格自动生成 （Red Phase），然后由另一个开发智能体去实现功能以满足这些测试（Green Phase），接着还有专门的智能体进行代码审查。这形成了一个闭环的质量保障机制。

两者的结合点在于“契约” 。SDD阶段在 @contracts 包中定义的Zod Schema，直接成为前后端开发和自动化测试的“唯一事实来源”。前端测试（Playwright/Maestro）会基于这些契约模拟数据，后端测试会验证接口是否符合契约。这种从设计到测试的全程契约化，是保证重构质量的关键。

3. 智能体协作流水线详解

整个流水线由一系列AI智能体在人类指挥下按顺序协作完成。你可以将其理解为一个高度自动化的软件工厂流水线。

3.1 第一阶段：遗留系统发现与逆向工程

一切始于一个命令： /spec-write --legacy [功能描述] 。 --legacy 标志会激活 Legacy Discoverer （遗留系统发现者） 智能体。

这个智能体是“只读”专家，它的唯一任务就是深入遗留代码库（我们有两个独立的旧仓库：前端和后端），像一位经验丰富的考古学家一样，绘制出完整的“代码地图”。它被赋予了 legacy-knowledge 技能包，里面包含了项目术语表、代码提示、项目概览以及那65个以上端点的完整映射表。

它的工作分为五个精密阶段：

1. 吸收上下文 ：首先读取 legacy-knowledge 技能，理解这个项目的“方言”和整体结构。
2. 识别范围 ：根据传入的功能描述（例如“用户个人资料编辑”），使用Glob/Grep模式在前端代码中搜索相关屏幕、React Context、自定义Hook、API调用；在后端搜索相关的端点、控制器、服务类和数据访问层。
3. 追踪完整代码流 ：这是最核心的一步。它需要构建一个从用户界面到数据库再返回的完整调用链。例如： ProfileEditScreen.js -> 调用 useUserProfileContext -> 调用 userApi.updateProfile() -> 发送请求到 PATCH /api/user/profile -> 后端路由指向 UserDomain.updateProfile 处理函数 -> 调用 UserRepository.save -> 返回数据 -> 前端Context更新状态 -> 屏幕重渲染。这个链条必须被完整地梳理出来。
4. 映射到新Monorepo ：将旧系统中的每个部件，对应到新架构的目标位置。例如：旧的React Context映射到新的Zustand Store；旧的 src/screens/Profile.js 映射到 apps/@mobile/app/screens/profile/ ；旧的后端处理函数映射到 apps/@api/src/modules/user/services/ 下的NestJS Service。
5. 生成遗留系统发现报告 ：最终产出一个结构化的JSON或Markdown报告，详细记录了所有发现、映射关系和待决策点。这份报告是下一阶段的唯一输入。

实操心得 ： Legacy Discoverer 的准确性直接决定后续所有工作的根基。我们花了大量时间优化其 legacy-knowledge 技能，特别是那个端点映射表。我们不仅列出了URL和方法，还附上了每个端点的 业务目的简述 和 关键请求/响应字段示例 。这极大地帮助了AI理解“这段代码是干什么的”，而不仅仅是“这段代码是什么”。

3.2 第二阶段：规格与方案设计

Legacy Discovery Report 被传递给 Spec Writer （规格撰写者） 智能体。我们为这个关键角色配备了能力更强的模型（如Claude 3 Opus），因为它需要进行深度推理和架构决策。

Spec Writer 的工作分为两大步骤，且每一步都需要人类批准：

步骤一：撰写业务规格（spec.md） Spec Writer 会吸收 project-brain （项目大脑，包含架构原则、技术选型原因）和 integration-contracts （集成契约初稿）技能，然后产出 spec.md 。这份文档是纯业务视角的，包含：

• 业务目标 ：用一两句话说明这个功能的价值。
• 用户角色 ：涉及哪些用户。
• 可测试的业务规则 ：每条规则都以“RULE-”编号，并且表述必须清晰到可以直接转化为测试用例。例如：“RULE-1: 用户只能编辑自己的个人资料，尝试编辑他人资料应返回403错误。”
• BDD验收场景 ：使用Given/When/Then格式描述核心用户流程。
• 遗留代码迁移映射与待决策项 ：明确指出从旧系统迁移时需要做的决定，并用 [DECISÃO NECESSÁRIA] （[必要决策]）标签标出，等待人类拍板。

接着， Spec Reviewer （规格审查者） 智能体会出场，对 spec.md 进行质量门禁检查。它依据一个包含9项检查（S1-S9）的清单进行验证，例如：“S2: 所有业务规则是否都具备可测试性？”、“S5: BDD场景是否覆盖了成功和失败路径？”。如果发现高优先级问题， Spec Writer 必须修改，直到通过审查，才会提交给人类产品负责人或架构师进行最终批准。

步骤二：撰写技术实施方案（plan-{stack}.md） 一旦业务规格获批， Spec Writer 会为每个技术栈（如NestJS, Expo, React）生成独立的 plan-{stack}.md 文件。这份文档是给开发者看的详细设计图，包含：

• 架构决策及理由 ：例如，“为什么在这里使用Zustand而不是Context API？因为该状态需要在多个非父子组件间共享，且更新逻辑较复杂。”
• 组件/服务设计与端到端数据流 ：画出简单的数据流示意图（用文字描述），说明数据从哪里来，经过哪些处理，到哪里去。
• 反模式警示（“禁止事项”） ：明确列出在本功能中应避免的做法，比如“禁止在组件内直接调用Prisma Client”、“禁止在非服务层进行Zod验证”。
• 单元测试规格 ：明确规定每个服务至少3个测试、每个实体类至少2个测试、每个UI组件至少2个测试，并给出测试要点。
• 生成任务清单（tasks.md） ：将上述方案拆解成一个具体的、可执行的开发任务列表。

同样， Spec Reviewer 会再次以“PLAN模式”对每个技术方案进行审查，依据另一套包含13项技术检查（P1-P13）和6项跨文档一致性检查（X1-X6）的清单。例如，“P8: 数据流设计是否避免了不必要的重新渲染？”、“X2: 前端组件定义的Props类型是否与 @types 包中的接口一致？”

3.3 第三阶段：基于TDD的自动化实现

这是代码开始产生的阶段。人类开发者只需运行一个命令： /run-feature FEAT-XXX （XXX是JIRA任务号）。这个命令会触发一个复杂的、自动化的TDD流水线。

1. 环境准备 ：流水线首先在Git中创建一个独立的分支和一个隔离的工作树（worktree），确保与主开发环境互不干扰。
2. 契约与类型先行 ：严格执行“契约 > 后端 > 前端”的顺序。智能体会首先检查或创建/更新 @contracts 和 @types 包中的相关定义。 在接口定义未稳定之前，任何后端或前端代码都不会开始编写。
3. 后端TDD循环（红-绿-审-验） ：
   • 红（Red） ： Backend Test Writer （后端测试编写者） 智能体读取 plan-backend.md 和 @contracts ，为新的API端点或服务方法编写单元测试和集成测试。这些测试 必须失败 ，因为功能尚未实现。
   • 绿（Green） ： API Dev （API开发者） 或 Serverless Dev （Serverless开发者） 智能体（根据技术栈选择）接手，查看失败的测试和 plan-backend.md ，开始实现NestJS Controller、Service或Hono.js路由，直到所有测试通过。
   • 审（Review） ： Backend Reviewer （后端审查者） 智能体对生成的代码进行审查，检查其是否符合架构规范、TypeScript配置是否严格、有无潜在的性能问题（如N+1查询）、是否遵循了项目约定的代码风格。
   • 验（Verify） ： Test Runner （测试运行者） 智能体启动开发服务器，并运行所有相关的单元测试和集成测试（有时会通过cURL调用实际端点进行快速的功能验证），确保一切正常。
4. 前端TDD循环 ：采用与后端完全相同的“红-绿-审-验”流程。 Frontend Test Writer 会利用MCP（Model Context Protocol）连接Playwright（用于Web）和Maestro（用于移动端）来编写端到端（E2E）测试。 Platform Dev （Expo移动端开发者）或 Backoffice Dev （管理后台开发者）智能体则负责实现UI组件和前端逻辑。

3.4 第四阶段：人工验证与最终提交

这是整个流水线中人类掌控力最强的环节，也是“零自动提交”原则的体现。 在所有自动化步骤完成后，流水线会暂停，并向人类开发者呈现一个完整的验证报告：

1. 构建状态 ：显示 pnpm build 在所有相关应用和包上的执行结果。
2. 类型检查 ：显示全局 pnpm type-check 的结果。
3. 变更展示 ：以清晰的diff格式展示所有将被提交的代码更改。
4. 测试结果 ：汇总所有单元测试、集成测试和E2E测试的运行结果。
5. 学习点记录 ：流水线会生成一份“Learnings”文档，记录本次实现过程中遇到的新模式、解决的边界情况或做出的次要设计决策，这些内容会被吸收到 project-brain 或 learnings 技能中，用于优化未来的任务。

此时，人类开发者有三个选择：

• 批准 ：点击批准，流水线会自动将隔离工作树中的更改合并到功能分支，并创建清晰的提交信息。
• 要求修改 ：指出代码或设计中的问题，流水线会将任务退回给相应的智能体进行修正。
• 取消 ：放弃所有更改，不会有任何代码被提交。

4. 智能体生态、技能与工作流

4.1 智能体角色矩阵

我们构建了一个由14个各司其职的智能体组成的“数字团队”。下表概述了它们的核心职责：

智能体名称	主要模型	核心职能	是否只读
Legacy Discoverer	Claude 3 Sonnet	逆向工程，分析遗留代码	是
Spec Writer	Claude 3 Opus	撰写业务规格和技术方案	是
Spec Reviewer	Claude 3 Sonnet	审查规格与方案的质量	是
Backend Test Writer	Claude 3 Sonnet	为后端功能编写初始（失败）测试	否
Frontend Test Writer	Claude 3 Sonnet	为前端功能编写初始（失败）测试	否
API Dev	Claude 3 Sonnet	实现NestJS后端代码	否
Serverless Dev	Claude 3 Sonnet	实现Hono.js Serverless API代码	否
Platform Dev	Claude 3 Sonnet	实现Expo移动端代码	否
Backoffice Dev	Claude 3 Sonnet	实现React管理后台代码	否
Backend Reviewer	Claude 3 Sonnet	审查后端代码质量	是
Frontend Reviewer	Claude 3 Sonnet	审查前端代码质量	是
Test Runner	Claude 3 Sonnet	执行测试套件并报告结果	是
Validation Gate	Claude 3 Sonnet	执行构建、类型检查、契约验证	是
QA Reviewer	Claude 3 Sonnet	在人工QA后，验证Bug修复	是

4.2 技能、工作流与规则

为了让智能体们高效工作，我们为其装备了“技能”和定义了“工作流”：

• 六大核心技能 ：这是智能体的长期记忆和知识库。

  • project-brain : 项目架构、技术决策历史、设计模式偏好。
  • legacy-knowledge : 遗留系统的详细信息，是 Legacy Discoverer 的弹药库。
  • integration-contracts : 系统间集成接口的当前定义和演进历史。
  • backend-conventions : 后端代码风格、目录结构、最佳实践。
  • frontend-conventions : 前端代码风格、组件规范、状态管理规则。
  • learnings : 从过往任务中积累的经验、教训和解决方案模式。

• 五大工作流命令 ：这是人类与智能体生态交互的主要接口。

  • /spec-write : 启动规格撰写流程（可带 --legacy 标志）。
  • /run-feature : 启动一个完整功能的自动化TDD实现流程。
  • /validate : 仅对当前代码运行验证门禁（构建、测试、类型检查）。
  • /health-check : 检查整个智能体生态系统和依赖项的状态。
  • /jira : 与JIRA任务同步状态，更新日志。

• 七条硬性规则 ：这是确保输出一致性的“护栏”。例如：“所有TypeScript配置必须使用 strict: true ”、“所有API响应必须通过Zod Schema验证”、“组件Props必须使用 interface 而非 type 定义（除非需要联合类型）”。这些规则被嵌入到每个代码生成和审查智能体的上下文中。

5. 实践中的挑战与应对策略

5.1 智能体的“幻觉”与一致性维护

即便使用最先进的模型，智能体在生成代码或方案时也可能出现“幻觉”，即产生看似合理但不符合项目特定约定或存在细微错误的输出。我们的应对策略是多层审查：

1. 规格层审查 ： Spec Reviewer 的检查清单（S1-S9, P1-P13）旨在从设计源头遏制不合理方案。
2. 代码层审查 ： Backend Reviewer 和 Frontend Reviewer 专注于代码级别的合规性，它们内置了项目的ESLint规则和自定义规则集。
3. 自动化验证 ： Validation Gate 执行的构建和类型检查是硬性防线，编译错误或类型冲突会直接导致流程中断。
4. 人工最终把关 ：最终的“批准”按钮始终在人类手中。我们要求开发者在审核时，特别关注业务逻辑的正确性和架构设计的合理性，这是AI目前较难完全把握的。

5.2 性能与成本考量

运行一整套智能体流水线，尤其是使用Opus等大型模型进行深度推理，会产生显著的Token消耗和较长的运行时间。我们通过以下方式优化：

• 精准的上下文管理 ：严格控制每次调用智能体时附带的上下文信息，只提供完成任务所必需的文件和技能，避免无关信息的冗余。
• 缓存与复用 ：对于 Legacy Discovery Report 、批准的 spec.md 和 plan-*.md 等中间产物，进行缓存。后续阶段直接引用，无需重新生成。
• 任务并行化 ：在安全的前提下，让一些独立的任务并行执行。例如，在 Spec Writer 生成不同技术栈的方案时，可以并行处理。
• 模型分级使用 ：将最需要深度推理的任务（如架构设计）分配给能力更强、更贵的模型（Opus），而将模式更固定、更重复的任务（如代码审查、测试运行）分配给性价比更高的模型（Sonnet）。

5.3 团队文化与流程适应

引入这样一套高度自动化的系统，对团队来说是一个变革。初期最大的阻力不是技术，而是心理和流程上的。

• 开发者角色的转变 ：开发者从“代码编写者”更多地转变为“流程设计者”、“规格制定者”和“质量仲裁者”。我们需要花时间让团队理解，他们的价值不是被降低了，而是被提升了——他们现在专注于更高层次的设计、决策和复杂问题解决。
• 信任的建立 ：我们通过“影子模式”启动。即让智能体流水线并行运行，但其产出仅供参考，不直接合并。让团队成员对比AI的产出和自己的实现，逐步建立对系统能力的信任。同时，坚持“零自动提交”原则，让团队始终感到掌控权在自己手中。
• 技能库的持续维护 ： project-brain 、 conventions 等技能库不是一成不变的。我们设立了一个定期回顾机制，由技术负责人牵头，团队共同评审和更新这些知识库，确保智能体们学到的始终是最新、最好的实践。

6. 成效与未来展望

经过几个月的实践，这套系统已经开始深刻改变我们的开发方式：

• 重构速度与质量 ：过去评估需要数周才能完成的遗留功能迁移，现在通过流水线可以在几天内产出高质量、高测试覆盖率的可交付代码块。更重要的是，每个迁移步骤都有完整的规格和测试作为依据，风险可控。
• 知识沉淀与传承 ：所有关于“为什么这么做”的架构决策和业务规则，都通过 spec.md 、 plan-*.md 和 learnings 技能被固化下来。新成员加入项目时，不再需要花费大量时间阅读零散的代码和文档，而是可以通过这些结构化的产出快速理解系统。
• 开发一致性 ：无论由哪位开发者（或智能体）执行任务，产出的代码都遵循相同的模式和规范，极大提升了代码库的整体一致性和可维护性。
• 人类专注高价值活动 ：团队成员得以从繁琐的重复性编码、简单的CRUD接口编写、基础的测试用例构造中解放出来，将更多精力投入到复杂的业务逻辑设计、性能优化、用户体验打磨和技术难点攻关上。

这不是关于用AI取代开发者，而是关于用AI赋能开发者。 我们构建的，是一个将人类专家的战略思维、架构判断和创造力，与AI智能体的执行力、一致性和不知疲倦的特性相结合的系统。代码的最终责任仍然在人类肩上，但实现代码的过程，因为有了这些高度专业化、严格受控的智能体伙伴，而变得前所未有的高效、可靠和可追溯。这条路还在探索中，但我们已经看到了它改变软件工程范式的巨大潜力。