夜雨聆风软件工程映射：当执行者从人变成 AI
"
“他山之石，可以攻玉。” — 《诗经·小雅》
系列：《面向软件工程的 AI 编程范式》第 3 篇
关键词：软件工程、范式映射、契约先行、评审闭环、对齐门禁、交付即沉淀
一个被忽视的事实
软件工程有六十多年的积累。从瀑布到敏捷，从 UML 到微服务，从 Code Review 到 CI/CD——这些实践不是凭空发明的，它们是在无数次项目失败中提炼出来的。
当 AI 成为主要编码者时，一个常见的误解是："软件工程过时了，AI 不需要这些。"
这是错的。
软件工程的核心问题没有变——怎么让代码在长周期里保持可维护、可追溯、可审计。变的只是执行者：从人变成了 AI。
当执行者从人变成 AI，软件工程的经典实践不是消失了——它们需要适配。就像数据库从 Oracle 迁移到 PostgreSQL，SQL 语法变了，但关系模型没变。
这篇要做的事是：把软件工程的经典实践，逐一映射到我们的 AI 编程范式中，看看哪些是直接继承、哪些需要适配、哪些是全新发明。
核心映射表
在底座平台的实践中，我们建立了一张完整的映射表。这张表不是理论推演——它是从 72 份文档、14 次评审、9 条 ADR 的实际操作中提炼出来的。
这张表揭示了一个重要的事实：我们的范式不是"发明了新东西"——它是把软件工程的经典实践，重新适配到"AI 是主要编码者"的场景。
注意映射的覆盖范围：不只是“需求→架构→代码”的主干链路——需求调研、概要设计、详细设计、UI 设计、原型设计、测试、开发计划、任务分解，这些在经典软件工程中不可或缺但常被忽视的环节，在这里全部有对应。
逐一拆解：每个映射怎么工作
1. 需求调研 → 调研专题 + 调研笔记
经典作用：需求调研是软件开发的起点——在写任何代码之前，先理解问题域。通过访谈、竞品分析、技术验证等方式，弄清楚“要解决什么问题”“有哪些约束”“行业怎么做的”。
AI 编程中的适配：需求调研的角色不变，但它的产出形式变了。传统调研的产出是“调研报告”——给人看的文档。AI 编程中，调研的产出是“可被 AI 消费的结构化知识”——调研笔记、技术对比表、可行性结论。
关键差异：传统调研是“一次性的”——调研完就归档，后续开发很少回看。AI 编程中，调研是“持续引用的”——调研笔记会被评审、被提炼为 ADR、被引用到任务卡中。它是 AI 的“知识库”。
底座平台实例：4 个调研专题（微前端方案 / 认证方案 / 底座架构 / 应用接入），12 篇调研笔记。每篇笔记经过评审后，沉淀为 ADR 决策（如 ADR-04 选择 wujie、ADR-06 继承建模认证）。AI 在写代码时，可以回溯到调研笔记，理解“为什么这么选”。
2. 需求规格说明 → L1 PRD
经典作用：需求规格说明（SRS）定义了系统"做什么"——功能需求、非功能需求、验收标准。它是需求的"法律"。
AI 编程中的适配：PRD 的角色不变，但格式需要更精确。传统 SRS 可以用自然语言描述，AI 需要可测试的验收标准。
关键差异：底座平台的 PRD 有 27 条 AC（验收标准），每条都是可测试的。不是"系统应该支持用户登录"，而是"AC-01：登录底座一次，接入应用免登录访问；退出时全部应用同时登出"。
为什么需要更精确：AI 不会"理解"模糊的需求。"系统应该高性能"对 AI 来说没有意义。"NFR-01：P99 响应时间 < 200ms"才有意义。
3. 架构设计文档 → L2 架构 + ADR
经典作用：架构设计文档定义了系统“怎么做”——模块划分、技术选型、接口设计。ADR（Architecture Decision Record）记录“为什么这么做”。
AI 编程中的适配：架构文档的角色不变，但 ADR 的重要性大幅提升。
为什么 ADR 更重要：AI 有一个倾向——每次面对选型问题时，它都会从训练数据中重新探索所有可能性。如果你不告诉它“qiankun 已经被否决了”，AI 完全可能在下一轮迭代中推荐 qiankun。ADR 的“被否决方案”就是 AI 的防护栏。
底座平台实例：ADR-06 记录了“继承建模认证”的决策，包括 5 条理由和 3 个被否决的方案（自研 / 第三方 IdP / 全部迁移完再接应用）。AI 读到 ADR-06，就知道不需要重新论证认证方案。
4. 概要设计（HLD）→ L2 概要设计
经典作用：概要设计（High-Level Design）定义了系统的模块划分、关键流程、接口边界。它回答“系统由哪几块组成？块之间怎么交互？”
AI 编程中的适配：概要设计的角色不变，但它成了 AI 编码的“导航图”。AI 在写代码前，先读概要设计了解全局结构，再深入具体模块。
关键差异：传统概要设计是给人看的，重点是“让人理解”。AI 概要设计是“给 AI 导航的”，重点是“模块边界清晰、接口定义明确”。
底座平台实例：422 行的概要设计文档，包含 11 个模块的概要描述（认证中心 / 应用注册 / SSO 会话 / 审计日志 / 前端壳 / 等）+ 4 条关键流程（登录流程 / 应用注册流程 / 退出流程 / 审计流程）。AI 读完概要设计，就知道整个系统的骨架。
5. 详细设计（LLD）→ L2 详细设计
经典作用：详细设计（Low-Level Design）定义了类级实现细节——数据表结构、接口签名、模块内部逻辑。它回答“具体怎么写？”
AI 编程中的适配：详细设计的角色不变，但它成了 AI 编码的“直接输入”。AI 写代码时，不是从概要设计推导细节——而是直接读详细设计。
关键差异：传统详细设计是“可选的”——简单的功能可以跳过。AI 编程中，详细设计是“必须的”——因为 AI 不会“自行设计”类结构、接口参数、错误处理。这些必须由详细设计决定。
底座平台实例：862 行的详细设计文档，包含 12 张数据表 DDL + 12 组接口定义 + 18 个模块的类级设计。每个任务卡都明确引用详设的具体段落（如“详设 §3.1”）。AI 写 SsoSessionService时，直接读详设 §3.1，不需要“自行设计”类结构。
6. UI 设计 → L2 UI 设计
经典作用：UI 设计定义了视觉规范——颜色、字体、间距、组件样式。它确保不同开发者写的界面风格一致。
AI 编程中的适配：UI 设计的角色不变，但它成了 AI 生成前端代码的“约束”。没有 UI 设计，AI 会“自行发挥”——每次生成的界面风格可能不一样。
关键差异：传统 UI 设计是“参考性的”——开发者可以参考但不必须遵守。AI 编程中，UI 设计是“强制性的”——AI 必须按设计 Token 生成代码，否则每次生成的结果不一致。
底座平台实例：364 行的 UI 设计文档，包含设计 Token（主色 / 辅色 / 字体 / 间距 / 圆角）+ 组件规范（按钮 / 表单 / 表格 / 弹窗）+ 布局规范。AI 写前端时，读 UI 设计文档，确保每次生成的界面风格一致。
7. 原型设计 → L2 页面原型
经典作用：原型设计定义了交互流程——页面布局、元素位置、交互逻辑。它回答“用户看到什么？怎么操作？”
AI 编程中的适配：原型设计的角色不变，但它成了 AI 生成前端页面的“蓝图”。没有原型，AI 不知道“登录页应该长什么样”。
关键差异：传统原型是“参考性的”——开发者可以参考但不必须完全照搬。AI 编程中，原型是“强制性的”——AI 必须按原型生成页面，否则每次生成的结果不一致。
底座平台实例：794 行的页面原型文档，包含全部页面的线框图 + 交互说明。每个任务卡都明确引用原型的具体章节（如“原型 §3.2”）。AI 写登录页时，直接读原型 §3.2，不需要“自行设计”页面布局。
8. 数据库 Schema → L0 契约
经典作用：数据库 Schema 定义了表的结构——字段名、类型、约束、索引。它是数据层的“宪法”，任何 DML 操作都不能违反 Schema。
AI 编程中的适配：当 AI 成为编码者时，Schema 的角色不变——但承载形式变了。在底座平台中，17 条 CT 条款就是 Schema 的 AI 适配版。
关键差异：传统 Schema 只管数据库层。CT 条款管的是全部数据流——API 接口、消息信封、会话令牌、审计日志、外部 API。它比 Schema 的覆盖面更广。
底座平台实例：CT-01 定义了应用注册的 11 个字段、类型、必选性、质量语义、错误码。AI 在写 AppService.java时，不需要“发明”字段格式——CT-01 已经决定了。
9. 技术选型报告 → ADR
经典作用：技术选型报告记录了“为什么选了这个技术”——对比分析、优缺点、最终决策。
AI 编程中的适配：ADR 的角色不变，但格式更严格。每条 ADR 必须有四要素：结论 / 理由 / 被否决的方案 / 适用边界。
为什么“被否决的方案”更重要：AI 的训练数据包含了所有可能的方案——包括那些你经过深思熟虑后否决的方案。如果你不告诉 AI“qiankun 被否决了”，AI 完全可能在某次迭代中推荐 qiankun。被否决的方案是 AI 的防护栏。
底座平台实例：ADR-05 取代 ADR-04 的载体条款（iframe → wujie），明确标注“被取代的”和“不被取代的”。AI 读到 ADR-04 时，看到“已被 ADR-05 取代”的标注，不会按 iframe 去写代码。
10. 编码规范 → L3 指南
经典作用：编码规范定义了代码"长什么样子"——命名规则、缩进、注释风格、分支策略。
AI 编程中的适配：编码规范的角色不变，但承载形式变了。传统编码规范是给人看的文档，AI 编码工具需要持久化指令文件。
底座平台实例：17 号规约（AI 编程规约）+ 15 号分支规范。这些文档定义了 L0~L3 的格式、编号规则、评审检查点、任务卡模板。
与工具的关系：CLAUDE.md / .cursor/rules / AGENTS.md 是 L3 指南层的工具化实现。但我们的 L3 不只是"风格指南"——它还包括方法论（17 号规约）和流程规范（15 号分支规范）。
11. 外键约束 → 编号体系
经典作用：外键约束确保表与表之间的引用一致性。如果表 A 引用了表 B 的记录，那么表 B 的记录必须存在。
AI 编程中的适配：编号体系（AC-XX / CT-XX / ADR-XX / T-XXX）就是文档之间的"外键"。它确保文档之间的引用一致性。
为什么需要编号：自然语言描述是模糊的。"这个接口的字段要和那个表对齐"——哪个接口？哪个表？编号是精确的。"CT-02 定义了 SSO 会话的 5 个字段"——没有歧义。
底座平台实例：任务卡 T-1A01 的三段式追溯（T-1A01 / ADR-06 / CT-02）就是三个"外键"——它把代码锚定在任务、决策、契约三个维度上。
12. 开发计划 → 任务卡波次排期
经典作用：开发计划定义了项目的进度安排——什么时候做什么、谁做什么、依赖关系是什么。
AI 编程中的适配：开发计划的角色不变，但它成了 AI 编码的“执行顺序”。AI 不会“自己决定先做什么”——它按波次排期执行。
关键差异：传统开发计划是“建议性的”——开发者可以根据实际情况调整。AI 编程中，开发计划是“强制性的”——AI 必须按波次顺序执行，否则可能产生依赖冲突。
底座平台实例：109 行的开发计划文档，包含 5 个波次的排期 + 25 张任务卡全景。每个波次有明确的依赖关系（如“波次 2 依赖波次 1 的 T-1A01”）。AI 读到开发计划，就知道先做什么、后做什么。
13. 任务分解（WBS）→ 任务卡（T-XXX）
经典作用：任务分解（Work Breakdown Structure）把大任务拆成小任务——每个小任务有明确的输入、输出、验收标准。
AI 编程中的适配：任务卡（T-XXX）就是 WBS 的 AI 适配版。每张任务卡有：三段式追溯（T/ADR/CT）+ DoD 清单 + 依赖关系 + 验收场景。
关键差异：传统 WBS 是“管理工具”——主要用于进度跟踪。AI 编程中，任务卡是“执行指令”——AI 按任务卡的内容直接编码。
底座平台实例：25 张任务卡（T-1A01 ~ T-1C02），每张包含：三段式追溯（任务编号 / 决策编号 / 契约条款）+ DoD 清单（4~5 条）+ 依赖关系（前置任务）+ 验收场景（可测试的检查点）。AI 读到任务卡 T-1A01，就知道要写什么代码、怎么验收。
14. 测试计划 → DoD 清单 + 验收场景
经典作用：测试计划定义了“怎么验证代码是对的”——测试用例、测试数据、预期结果。
AI 编程中的适配：DoD（Definition of Done）清单 + 验收场景就是测试计划的 AI 适配版。每张任务卡的 DoD 定义了“什么算完成”，验收场景定义了“怎么验证”。
关键差异：传统测试计划是“事后的”——代码写完了才写测试。AI 编程中，DoD 是“事前的”——在任务卡中预先定义，AI 写代码时就按 DoD 验收。
底座平台实例：任务卡 T-1A01 的 DoD 包含 5 条：1）实现 SSO 会话服务；2）实现 JWT 签发/验证；3）单测覆盖率 > 80%；4）通过验收场景（登录/退出/超时）；5）代码头注释包含三段式追溯。AI 写完代码后，逐条检查 DoD，确保全部通过。
15. Code Review → 评审闭环
经典作用：Code Review 是代码质量的守门人——在代码合并前，由其他人检查代码的正确性、一致性、可维护性。
AI 编程中的适配：评审的对象从"代码"扩展到"文档"。在底座平台中，14 份评审报告覆盖了从调研到设计的全部文档层级。
关键差异：传统 Code Review 是"事后检查"——代码写完了才 Review。我们的评审闭环是"事前+事中+事后"——调研结论要评审、PRD 要评审、设计要评审、详设要评审。评审驱动文档持续生长。
底座平台实例：09 号评审发现 PRD 的 F6 能力域没有 AC 验收标准（P2-1），同时发现契约里没有对应条款（C-1）。这份评审同时驱动了 PRD v0.8 和契约 v0.4 的修订。
16. 数据迁移脚本 → 对齐门禁
经典作用：数据迁移脚本处理"旧数据结构"到"新数据结构"的转换。它承认"现实和理想有差距"，但提供了显式的转换路径。
AI 编程中的适配：对齐门禁处理"设计"到"实现"的偏差。它承认"实现可能比设计更好"，但要求显式记录偏差。
关键差异：数据迁移脚本是"一次性的"——迁移完就归档。对齐门禁是"持续的"——每次迭代都可能产生新的偏差，每次偏差都需要记录。
底座平台实例：详设说"wujie alive:false 节省内存"，但评审 13 号发现 alive:false 与 NFR-03 矛盾。对齐门禁的处理方式是：实现赢（改为 alive:true），但文档记录偏差。
17. CI/CD 门禁 → 交付门禁
经典作用：CI/CD 门禁确保代码在合并/部署前通过一系列检查——编译、测试、代码扫描、安全审计。
AI 编程中的适配：交付门禁确保里程碑退出前完成一系列检查——文档回写、Exit Report、CHANGELOG 登记、遗留留痕。
关键差异：CI/CD 门禁检查的是"代码质量"。交付门禁检查的是"文档与代码的同步性"——确保交付时文档没有过期。
底座平台实例：M1 里程碑退出时，四道门禁确保：文档与代码同步（文档回写）、交付可审计（Exit Report）、变更可追溯（CHANGELOG）、遗留不丢失（双向留痕）。
18. 需求追溯矩阵 → 三段式追溯
经典作用：需求追溯矩阵（RTM）确保每个需求都有对应的实现和测试。它回答"这个需求做了吗？怎么验证的？"
AI 编程中的适配：三段式追溯（T/ADR/CT）是 RTM 的代码级实现。每行代码的头注释都标注了任务编号、决策编号、契约条款。
关键差异：传统 RTM 是"文档级的"——需求→设计→测试的映射。三段式追溯是"代码级的"——每个类、每个方法都有追溯信息。
底座平台实例：SsoSessionService的头注释标注了 T-1A01 / ADR-06 / CT-02。半年后有人问"这个类为什么用 JWT HS256"，沿着 ADR-06 就能找到答案。
三类映射：继承、适配、创新
把 18 个映射放在一起看，它们分为三类：
直接继承（不需要改变）
适配（需要改变形式）
全新发明（经典 SE 中没有对应）
为什么这个映射很重要
这个映射表的价值不在于"学术分类"——它回答了一个实际问题：
"这套范式是凭空发明的，还是有根的？"
答案是：有根的。它不是凭空发明的新东西——它是把软件工程六十年的积累，适配到"AI 是主要编码者"的场景。
Schema 约束人的编码行为 → CT 条款约束 AI 的生成行为 Code Review 检查人的代码 → 评审闭环检查 AI 的文档 CI/CD 门禁确保人的交付质量 → 交付门禁确保 AI 的交付可追溯
机制是一样的——只是执行者从人变成了 AI。
这意味着：这套范式不是"AI 时代的新发明"，而是"软件工程在 AI 时代的自然延伸"。
小结
软件工程映射的核心结论：
- 执行者变了，问题没变
：代码怎么在长周期里保持可维护、可追溯、可审计——这个问题不会因为 AI 的出现而消失 - 经典实践需要适配
：Schema → CT、Code Review → 评审闭环、CI/CD → 交付门禁、详设从可选变必须——形式变了，本质没变 - 有些是全新发明
：对齐门禁、三段式追溯、评审驱动文档生长——这些是 AI 编程场景下的新需求 - 覆盖全流程
：不只是“需求→架构→代码”的主干链路——需求调研、概要设计、详细设计、UI 设计、原型、测试、开发计划、任务分解全部有对应 - 范式是有根的
：它不是凭空发明的，而是软件工程六十年积累的 AI 适配版
下一篇，我们将深入这个适配的具体结构：L0~L3 四层金字塔模型——文档操作系统的核心设计。
面向软件工程的 AI 编程范式 · 系列文章
