让AI当架构师：技术方案设计Agent落地教程

一、教程目标

用AI从零写一个小系统，效果往往惊艳；但把AI扔进运行多年的大型存量分布式系统，效果立刻开始飘忽。AI写代码本身并不慢，真正慢的是它不知道从哪里开始，也不知道哪些地方绝对不能动。

本教程要解决的就是这个问题：如何让大型存量系统变成AI可理解、可推理、可验证的工程系统，让AI Agent真正承担「架构师」的核心职能，独立产出可执行、可验证、可审计的技术方案。

完成本教程后，你将能够：

1. 理解AI在存量系统失效的根本原因——上下文缺口，而非模型能力；
2. 为存量系统构建四类结构化的工程知识库；
3. 搭建一条从需求输入到方案产出的Agent工作流；
4. 建立约束校验、影响面分析与人工审计机制；
5. 在需求完整度较高、知识库体系完备的前提下，将AI原生技术方案的完备度稳定提升到95%以上。

二、适用场景与读者

适合的读者：

• 在大型存量系统上持续迭代的开发工程师与技术负责人；
• 希望把AI Coding从「写代码」升级为「做方案」的工程效能团队；
• 负责知识管理、研发流程与平台建设的架构师。

适合的场景：

• 微服务数量多、调用关系复杂、存在大量历史约束与隐性约定的分布式系统；
• 需求变更频繁、新人上手成本高、方案评审反复返工的团队；
• 已在局部使用AI辅助编码、但方案质量不稳定的团队。

不太适合的场景： 没有存量约束的全新绿地项目、代码量极小的小型工具系统——这类场景直接让AI编码即可，不需要本教程的完整体系。

三、先理解问题：AI在存量系统里为什么会「翻车」

先给结论：这不是模型能力问题，而是上下文缺口问题。

当前主流大模型的代码生成能力已经足够强：局部修改、补测试、解释调用链，都做得不错。真正的困难在于——复杂系统里最重要的知识，并不完整地存在于代码中。

举几个典型例子：

• 一个字段为什么不能删？删掉它可能打断依赖它的离线任务；
• 一条消息队列的消息为什么只能新增字段、不能改语义？因为还有历史下游在消费旧格式；
• 某个接口为什么不能在网关层做校验？因为上游存在特殊的调用约定；
• 某个配置为什么必须与灰度发布一起生效？因为这是历史事故留下的教训。

这些信息散落在历史方案文档、事故复盘、配置平台、老员工经验和从未被正式记录的团队约定里。人类工程师靠长期参与和「事故记忆」补齐了这部分上下文；AI没有这些事实，只能基于局部代码做推断。

所以AI在存量系统里最典型的错误不是语法错误，而是「局部正确、整体错误」。三个真实工程案例：

1. 删掉一个看似无用的字段，结果打断了依赖它的离线任务；
2. 新增一个看似方便的同步RPC调用，结果吃掉了核心链路的超时预算；
3. 修改消息队列的消息语义，结果坑了还在消费旧格式的历史下游。

更要命的是，AI Coding的效率会同时放大方案的正确与错误：方向对了，产能倍增；方向错了，AI只会更快地把错误落实成大量代码。

一个直观对比：同一名工程师，用AI一周可以从零写出类似某成熟CRM系统的原型；但让他在一个已运行多年的同类大型商业系统上做一次中等规模迭代，一周反而搞不定。原因在于：新系统是白纸，存量系统是旧城——旧城改造必须先摸清地下管线，而这正是本教程要系统化解决的问题。

一句话总结：代码能解释实现，架构才能支撑判断。让AI当架构师，前提是先把「判断所需的上下文」工程化。

四、前置准备

在动手搭建之前，请确认以下条件：

1. 知识资产盘点权限

• 能访问代码仓库、接口文档、历史技术方案、事故复盘记录、配置中心与发布记录；
• 建议指定一名「知识守门人」，负责知识条目的准确性与更新节奏。

2. 基础工程环境

• 一个可用的向量检索或全文检索服务，用于知识库查询；
• 一个可调用大模型能力的运行环境（私有化部署或云端接入均可）；
• 知识库本身纳入版本管理，做到每次变更可追溯。

3. 组织与流程前提

• 团队认可「方案先于编码」的研发流程；
• 已有固定的方案评审环节，可作为人机协同的切入点；
• 原始需求具备基本完整度（业务目标、功能点、边界说明）。

4. 基础知识要求

• 了解大模型的基本使用方式与提示词工程；
• 熟悉自家系统的模块级整体架构；
• 理解检索增强生成的基本概念。

五、实施步骤

步骤1：识别并建模四类核心知识

做什么： 把影响方案设计的知识分为四类，逐一盘点。
为什么做： 这是整个体系的地基。Agent判断质量的上限，由知识库的覆盖度决定，而不是由模型决定。

大型分布式系统中至少有四类知识同时影响方案设计：

1. 业务知识： 产品说「优化退款体验」，这里的业务对象、状态含义和边界，并不等同于代码里的类名和字段名。需要把业务术语表、状态机、流程规则沉淀为文档。
2. 系统与架构知识： 模块边界、服务依赖、调用链路、超时预算、容量上限。这类知识一部分在代码里，一部分在架构图和文档里，需要统一整理。
3. 历史决策与约束知识： 「为什么当时这么设计」「哪些地方绝对不能动」。包括历史方案、事故复盘、遗留兼容约束。这是存量系统中最稀缺、也最值钱的知识。
4. 运行时与数据知识： 流量特征、数据规模与分布、下游消费者的存量情况、离线任务的依赖关系。方案可行与否往往取决于这些运行时事实。

注意： 不要追求一步到位。建议先覆盖核心链路相关的知识，再逐步向边缘模块扩展。

步骤2：构建AI可理解的结构化知识库

做什么： 把四类知识结构化入库，并建立按需检索机制。
为什么做： 模型的上下文容量有限，必须按需检索注入，而不是全量塞入。

知识条目建议采用结构化格式，示例：

knowledge_entry:
  id: KD-2024-017
  type: constraint            # business / architecture / constraint / runtime
  title: 订单结果消息体字段约束
  content: >
    订单结果消息已有多个历史下游在消费。只允许新增可选字段，
    不允许修改既有字段语义或删除字段，否则历史消费者解析失败。
  source: 2023年Q2 事故复盘记录
  scope: [order-service, message-consumer-group]
  confidence: confirmed       # confirmed / pending
  last_verified: 2024-06-01

入库时的三个要点：

• 每条知识标注来源（事故复盘、历史方案、口头确认），区分「已确认」与「待确认」；
• 标注作用域（影响哪些服务、哪些数据流），便于后续影响面检索；
• 通过last_verified字段定期校验，及时淘汰过期知识。

检索机制建议：

• 按需求涉及的业务对象、服务名、接口名做关键词加语义的混合检索；
• 检索结果按「约束 > 架构 > 业务 > 运行时」的优先级排序后注入上下文。

agent-">步骤3：设计技术方案Agent的六阶段工作流

做什么： 把人类架构师做方案的过程，拆解为Agent可执行的分阶段流水线。
为什么做： 一次性让AI「写个方案」，只会得到泛泛而谈的通用方案；拆解为阶段任务，才能保证每个环节的深度。

阶段1，需求理解与澄清： Agent解析需求文档，抽取业务目标、功能点、非功能要求，并列出「信息缺口清单」反问需求方。需求完整度低时，宁可先澄清，不要硬编。

阶段2，上下文检索与组装： 根据需求涉及的对象与服务，从知识库检索四类知识，组装成带来源标注的上下文包。

阶段3，方案生成： 强制要求方案包含固定章节——现状分析、候选方案对比（至少两个）、选型理由、变更点清单、影响面分析、灰度与回滚设计。

阶段4，约束校验： 将方案的每个变更点，逐一与知识库中的约束条目比对，输出「冲突清单」。这是防止「局部正确、整体错误」的关键关卡。

阶段5，影响面分析： 基于调用链知识与下游消费关系，输出变更影响的完整清单并标注风险等级。

阶段6，审计报告输出： 输出可审计的方案文档，每个关键决策引用知识条目编号作为依据。

流水线伪代码示意：

def design_pipeline(requirement):
    goal, gaps = clarify(requirement)           # 阶段1：需求澄清
    if gaps.critical:
        return ask_back(gaps)                   # 主动澄清而非硬编
    context = retrieve_knowledge(goal)          # 阶段2：上下文组装
    draft = generate_design(goal, context)      # 阶段3：方案生成
    conflicts = check_constraints(draft)        # 阶段4：约束校验
    impacts = analyze_impact(draft)             # 阶段5：影响面分析
    if conflicts.blocking:
        draft = revise(draft, conflicts)        # 冲突迭代修正
    return audit_report(draft, conflicts, impacts)  # 阶段6：审计输出

步骤4：建立验证与审计机制

做什么： 让方案做到可验证、可审计。
为什么做： 可审计是信任的前提。没有依据的方案，评审环节无法判断对错。

三层验证设计：

1. 约束层： 方案是否违反知识库中的明确约束，机器可直接判定；
2. 一致性层： 方案内部逻辑是否自洽、变更点与影响面是否一一对应，机器辅助判定；
3. 合理性层： 选型是否匹配业务目标与技术演进方向，由人工判定。

审计要求：

• 方案中每个决策点必须挂接知识条目引用，可一键溯源；
• 无依据的关键决策统一标记为「待人工确认」；
• 保留Agent每次迭代的中间版本，便于事后复盘。

步骤5：人机协同评审与持续迭代

做什么： 把每次方案评审变成知识库的反哺入口。
为什么做： 评审中暴露的判断，往往正是知识库里缺失的条目；不回收，缺口永远补不上。

具体做法：

• 评审人对AI方案提出的修正意见，确认后回写为新的约束或业务知识条目；
• 线上事故复盘闭环时，第一时间入库；
• 每季度做一次知识库覆盖度巡检：抽查近期方案，统计「决策无依据」的比例并定向补齐。

六、配置说明

关键配置项及其含义与风险：

1. 知识条目结构： 必须包含type（四类知识之一）、scope（作用域）、source（来源）、confidence（可信级别）。缺少来源的条目，不允许进入约束校验环节，避免「传闻当约束」。
2. 检索召回数量： 注入上下文的知识条目建议控制在20～50条。太少会漏掉关键约束；太多会稀释关键信息，导致模型注意力被分散。
3. 约束校验严格度： 开发环境可设为「提示模式」，冲突仅提示不阻断；正式评审前设为「阻断模式」，存在已确认级别的约束冲突时，方案不允许进入评审流程。
4. 方案模板： 固定章节结构（现状、候选对比、选型理由、变更清单、影响面、灰度回滚、开放问题），保证多次输出之间可比、可评、可积累。

七、结果验证

如何判断这套体系是否真正跑通：

1. 单元级验证

• 输入一个已知存在约束的历史需求，检查方案是否正确识别并绕开约束（例如是否避免修改消息既有字段）；
• 构造「陷阱需求」：故意提出一个会触碰存量约束的改动，观察Agent是否在约束校验阶段报出冲突。

2. 指标级验证

• 方案完备度： 以评审通过的方案为样本，统计必备章节齐备且决策有依据的比例。在需求完整度较高、知识库体系完备的前提下，目标为稳定达到95%以上；
• 约束命中率： Agent识别出的约束数量除以评审中实际确认的约束数量；
• 返工率： 方案评审后的修改轮次是否持续下降。

3. 过程级验证

• 抽查审计报告，任意决策点应能溯源到知识条目，或被明确标记为人工确认项。

八、常见问题与排查

问题1：方案「看着都对，但很空洞」
原因：知识库覆盖不足，或检索召回的条目与需求无关。
排查：检查阶段2的检索命中情况；补充需求涉及范围内的知识条目；调整检索策略，优先对服务名、接口名做精确关键词匹配。

问题2：方案反复在同一处冲突打转
原因：知识库条目之间互相矛盾，或存在过时条目。
排查：按last_verified排序，优先复核最久未验证的条目；矛盾条目交由知识守门人裁决后更新。

问题3：约束校验误报过多
原因：条目scope设置过宽（例如写成了整个系统），导致不相关变更也被拦截。
排查：收窄条目作用域；为条目补充更精确的触发条件描述。

问题4：需求方反馈「AI总在问很初级的问题」
原因：业务知识条目缺失，Agent只能从零问起。
排查：把需求方回答中的通用信息沉淀为业务知识条目，同类问题不再重复出现——这正是知识库自我增强的良性循环。

问题5：方案完备度长期上不去
原因：通常是需求本身不完整，或历史决策类知识严重缺失。
排查：统计「待人工确认」决策的分布；对高频出现的无依据决策类型，定向补充对应知识条目。

九、优化建议

性能与成本：

• 对同一需求的多轮方案迭代复用检索结果，避免重复检索；
• 上下文按优先级裁剪：约束类知识全文保留，通用背景知识可摘要后注入。

安全与合规：

• 知识库权限分级：涉及资金、核心链路的敏感约束仅对授权角色可见；
• 方案输出时过滤敏感信息，避免内部拓扑与容量数据随文档外流。

可维护性：

• 知识更新绑定流程：事故复盘闭环时强制回写知识库，形成制度；
• 保留知识变更历史，某条约束被修改或废弃时可追溯到当时的决策记录。

组织协同：

• 让新人直接使用这套知识库上手系统，AI方案的引用链路天然构成一条高质量的「系统导览路径」；
• 把「AI方案完备度」纳入团队工程效能指标，持续观测与改进。

十、总结

本教程围绕「让AI在存量系统里当架构师」这一目标，给出了一条系统化落地路径：

• 问题本质是上下文缺口，而非模型能力：解法是把架构判断所需的四类知识（业务、架构、历史约束、运行时）工程化；
• 核心步骤：四类知识建模 → 结构化知识库入库 → 六阶段Agent工作流 → 约束校验与影响面分析 → 可审计输出 → 评审反哺闭环；
• 关键防线是约束校验关卡：它专门拦截「局部正确、整体错误」这类存量系统中最危险的错误；
• 效果基准：在需求完整度较高、知识库体系完备的前提下，AI原生技术方案的完备度可以稳定达到95%以上。

后续可以持续关注的方向包括：把影响面分析接通运行时链路数据，让分析从静态知识走向实时事实；从代码与配置变更历史中自动挖掘隐性约束，降低知识库的冷启动成本；以及让同一套上下文体系贯通「方案设计到编码实现」的完整链路，使AI架构师与AI编码真正协同工作。