阿里妹导读
文章内容基于作者个人技术实践与独立思考，旨在分享经验，仅代表个人观点。
前言
当前，AI 尚难完全理解“复杂技术系统”并独立完成完善的技术方案设计，“架构师”角色仍由人类担任。面对繁忙的业务，架构师需参与大量技术讨论与决策，人力瓶颈显著。
虽然单个系统内的 AI 逻辑推理已有落地，但针对“跨复杂业务系统的架构理解与设计”缺乏系统性解决方案。这是迈向 7x24 小时 Agentic Coding 的必经之路：AI 唯有深刻理解复杂系统，方能精准设计方案、排查问题乃至实现无人值守的自动化迭代。
我们的目标是：让大型存量分布式系统成为 AI 可理解、可推理、可验证的工程系统，使 AI Agent 真正具备“架构师”能力。
1.AI 仍难以理解复杂系统架构
团队初次使用 AI Coding 时常发现：从零构建小系统效果惊艳，但在运行多年的大型系统中，效果往往不稳定。小系统中 AI 能快速搭建全栈功能；而在大型系统中，看似简单的需求可能涉及多仓库、多接口及复杂的异步链路。AI 编码速度不慢，难点在于无法确定起始点及不可触碰的禁区。
这并非单纯的模型能力问题。代码生成已足够强大，困难在于复杂系统的关键知识并不完整存在于代码中。字段删除限制、历史分支保留原因、消息语义约束、网关校验规则等信息，往往散落在历史方案、事故复盘、配置平台及隐性经验中。人类工程师靠长期参与补齐上下文，而 AI 若缺乏这些事实，仅凭局部代码推断极易出错。
AI 在存量系统中最常见的错误是“局部正确、整体错误”：如逻辑错配服务、同步调用消耗核心链路预算、误删兼容逻辑破坏下游任务等。技术方案设计决定了需求落点、改动层级及复用策略，方向错误会被 AI 迅速放大为大量错误代码。
复杂存量分布式系统的核心难题在于：AI 必须跨越业务语言、架构链路及多个服务获取足够上下文。目前主流做法仍是由架构师完成人工方案，再交由 AI 编码。技术方案设计仍是人工介入最深、最需要架构师强力把控的环节。
2.白纸与旧城：新系统容易，存量系统困难
新系统与存量系统对 AI 的挑战差异巨大。在 AI 加持下，工程师一周可构建类似 Salesforce 的基础系统；但在已有系统上进行中等规模迭代，可能耗时更久。核心差别在于历史上下文的认知与生效方式。
新系统如同“白纸”，边界、模块、接口均可新建，调整成本可控。而存量系统像一座“旧城”，路网、管线、旧建筑及居民习惯共同决定了现状。不能仅看局部代码就断定其决策权或随意改动底层管线。
大型分布式系统的方案设计受四类知识共同影响：
- 业务知识：产品语言（如“优化退款”）对应的业务对象、状态含义及边界，需与代码类名进行消歧映射。
- 架构知识：请求链路、服务主责、一致性要求等，决定变更落点及影响范围。
- 服务内部知识：API 契约、状态机、缓存策略等，决定具体修改的安全性。
- 工程与组织知识：超时、重试、灰度、发布及安全审批规则，直接决定方案能否上线。
“存量复杂系统”的困难不在于代码量，而在于知识彼此断裂。代码仅表达部分事实，文档、配置与经验各自为政。若无机制将其组织，AI 难以从 PRD 推导出完整方案。
解决痛点在于：让存量系统不再仅存于少数人脑中，而是成为 AI 可全方位理解的工程系统。技术方案设计是 AI Coding 的核心源头，尽管实现难度大，但这确是“难而正确的事”。
3.难而正确的事：行业走到了哪里
从 Spec、Harness 到系统理解
调研显示，业界已意识到直接将自然语言需求交给 Coding Agent 并不稳定，主要探索方向包括：
- Spec-Driven Development：如 GitHub Spec Kit 和 Kiro，将流程结构化为 Spec→Plan→Tasks→Implement，强调阶段性审阅。
- 长程 Agent 的 Harness：Anthropic 提出通过初始化、任务拆分和结构化交接，解决长周期执行中的上下文连续性问题。
- Agent-friendly Repository：OpenAI 实践强调提供“地图”而非“说明书”，利用短小的 AGENTS.md 路由，配合结构化文档承载事实。
现有实践多局限于单个微服务内部，缺乏跨复杂多系统的工业级细节设计。我们致力于向前一步，让 AI 具备“复杂系统理解”能力，实现类人类架构师的跨系统设计、推理与决策。
4.从技术方案设计 Agent 开始
为避免空泛，我们从架构师的核心职能——技术方案设计切入，逐步落地“架构师 Agent"。
技术方案设计是 AI Coding 及 Agentic Coding 的必经之路。我们的思路是系统化地让 AI 完成设计：理解需求→理解业务系统→回源代码配置→产出可执行方案。关键在于持续演进的知识工程与 Agent 迭代路径，核心抓手包括：需求质量、分层知识库、LLM 基模能力及产出规范。
第一步落地重点在于知识库建设。
5.知识库的系统性建设落地
相较于单纯依赖 RAG（检索增强生成），我们认为知识库建设的第一层应是“领域”，即结构化的设计。
注：引用上一篇文章原图，蓝色背景框为高性价比模块。
5.1 知识库应该首先“对齐领域”：结构化的设计
随着大模型能力提升，AI 已从“小学生”进化为“大学生”，具备较强的内化理解力。但实践中，仍应将其视为聪明的实习生引导。结构性强的文档比海量文档库更能高效引导 AI 工作。
借鉴 DDD（领域驱动设计）方法论，架构天然具有领域边界。为提高 AI 理解效率，应强烈推荐让 AI 理解“强结构化的领域知识”，而非让其自行搜索杂乱知识库。
5.2 反直觉设计：为什么不首推 RAG
RAG 虽有用，但不适合作为复杂系统知识建设的首选。检索解决的是“找相关内容”，无法保证“知识集合的完整性与工程相关性”。非结构化文档入库常导致：
- 颗粒度不一致：片段知识密度差异大，命中不代表涵盖关键边界。
- 语义相似不等于工程相关：检索可能找到大量相似描述，却遗漏决定方案正确性的约束（如状态机跳转限制）。
- Top K 缺乏结构性保证：返回碎片化文档可能导致上下文冗长且矛盾，降低推理效率。
知识是有结构的，更适合被结构化索引；信息才是松散平铺的。RAG 适合作为长尾资料发现和证据补充，但不能替代知识骨架。
5.3“蒸馏架构师的大脑” —— 业务知识库的建设
业务知识库的目标是将架构师脑中的隐性知识显性化，形成文档。我们开发了 business-knowledge-distill skill，用于从技术方案、稳定性梳理文档中蒸馏出强结构化的 business-knowledge，并能解析交互图转为结构化内容。
以高德实时公交业务为例，蒸馏后的知识库结构如下：
.
├── evidence (图片证据)
├── history (历史记录)
├── index.md
├── meta (业务元语、核心对象)
├── practice (历史决策、事故教训)
├── principle (领域原则：幂等、降级等)
├── reference (跨领域关系契约)
├── scenario (业务场景映射)
└── source-manifest.yaml该结构强制 AI 按确定路径阅读：先读元语防混淆，再读场景定落点，遇原则查约束，需历史看实践。固定结构提供了“知识覆盖约束”，告诉 AI 解决问题至少需理解哪些方面。
理想关系是：固定结构知识库定义核心事实 + 架构图谱服务寻址 + 服务知识库约束验证 + RAG 发现补证。
5.4 知识正确性需要维护机制，而不是一次性生成
知识库最大风险是过期误导 AI。维护机制需融入研发流程：
- 联动代码变更：通过 Git Hook 或 CI 识别变更影响，生成待更新候选项，人工确认高风险语义。
- 日常增量维护：关键链路变化时关联蒸馏，未确认内容标记待审核。
- 周期性校准：利用大促保障、复盘资料等高价值内容进行跨系统知识校准。
每条知识应记录来源、确认时间及负责人，避免成为“文档墓地”。
5.5 service-knowledge 到底有没有用？
针对单个微服务的 service-knowledge 设计，解答如下：
- 是否同 Repo：不一定。同 Repo 方便 Agent 快速摸底，也可通过 Runtime 关联。
- 一致性保证：首次生成全覆盖，增量生成关联 Git Hook 或 Coding Agent Hook。
- 与 LLM Wiki 差异：基于 DDD 等方法论设计，屏蔽模型差异；YAML 格式结构性更强，信息密度更高。
- 存在必要性：
- Code Indexing：高效理解代码结构，提升效率至少 25%。
- 实体抽取：避免重复分析，节省 Token 成本。
- 多服务友好：解决 Context Window 限制，避免记忆压缩导致信息丢失。
5.6 渐进式披露：强结构化的知识路径
AI 不应一次性加载所有文档，而应采用渐进式披露，按需加载知识。路径分为四层：
| 层级 | AI 回答问题 | 主要知识来源 | 迭代频率 |
| 业务层 | 为什么改，业务落点 | business-knowledge (蒸馏) | 低 |
| 架构层 | 涉及哪些系统，影响谁 | aitom、服务图谱 | 中 |
| 系统层 | 单服务如何安全修改 | AGENTS.md、.knowledge/ (生成) | 高 |
| 基建层 | 工程底线和上线规则 | 中间件规范、发布流程 | 很低 |
遵循原则：不同事实回到不同来源确认。代码为准生产行为，产品为准业务意图，实践记录为准历史原因。此机制能主动发现“知识漂移”，修正设计偏差。
6.技术方案设计 Agent 落地
在完成知识库建设后，进入技术方案设计 Agent 的核心落地环节。
6.1 让 PRD 准入为技术设计的输入
技术方案设计不能始于原始 PRD。prd-digest 承担需求准入职责：检查问题与方案匹配度、价值依据及范围受控情况。输出结构化需求包（可验收目标、不做项、阻断项等），避免 AI 将含糊愿望翻译成跑偏的实现。
6.2 新名词：产品需求增强
除需求准入外，还存在“需求增强”机制，即帮助 PRD 更健全以利研发落地。关于职责归属（研发 vs 产品），更适合的解决方案是由架构师 Agent承担。具备技术方案设计能力的 Agent 可自然拓展此边界。
6.3 Agent Context 与 Runtime
各项能力收敛为面向跨系统设计的 Agent Runtime，包含五层：
- 业务理解层：基于 KBase MCP，提供结构化业务知识。
- 系统分析层：基于 AITOM，提供 API 检索与链路追踪。
- 架构推理层：技术方案设计 Skill，定义工作方式与验证逻辑。
- 服务知识层：各微服务的 Service Knowledge。
- 事实验证层：基于 Git Repository 的代码上下文。
6.4 AI 实现技术方案设计
设计过程是一套有输入、检索、验证的推理流程：
- 读取准入 PRD，提取目标与风险。
- 解析业务知识库中的元语与场景。
- 通过架构图谱定位候选服务与链路。
- 进入候选仓库，读取服务知识并回源代码。
- 形成 Gap 分析（复用/改造/新建）。
- 生成完整方案（改动点、影响、测试、发布等）。
采用渐进式披露动态加载上下文：
技术方案设计 Skill → 需求理解 → 按需加载业务知识 → 定位场景 →
调用 AITOM 分析 → 按需加载 Service Knowledge → 发现缺口 →
回源 Git 验证 → 形成方案 → 证据验证人类角色转变为裁决事实缺口和承担关键决策，而非替 AI 收集资料。
6.5 什么样的方案才算可执行
可执行方案需包含：
- 明确范围：涉及仓库、参与方及不在覆盖内的工作。
- 术语对照：PRD、业务名与代码名的映射。
- Gap 组织：复用、改造、新建的依据与边界。
- 影响分析：调用方、异常传播及存量行为保护。
- 验证计划：单测、契约测试、回归矩阵及配置开关。
- 未知登记：明确列出待确认项，不伪装事实。
通过五个问题自检：改哪里？为什么改？影响谁？如何验证？还有什么没确认？
6.6 AI 设计技术方案完备度衡量
目标设定为技术方案完善度 95% 以上，指在关键知识回源、代码核查及人工评审后，对主要工程问题的覆盖程度。六维指标包括：需求覆盖、系统覆盖、证据覆盖、风险覆盖、验证覆盖及不确定性治理。剩余不确定性主要来自跨团队决策等本就不应由模型单独决定的领域。
7.知识库体系是“多场景 Agent"基建
知识库体系不仅服务于技术方案设计，也是线上排查、事故复盘及新人理解的共同底座。方案设计与线上排查底层能力接近（业务元语、场景映射、架构图谱、服务知识），一次显性化投入可在多环节复用。
8.从“技术方案设计 Agent"到“架构师 Agent"
技术方案设计是架构师最核心的系统性判断工作。本实践通过将需求准入、隐性知识、图谱、约束及验证连接成可执行的生产线，逐步补齐 AI 的架构判断能力。
技术方案设计 Agent 是起点而非终点。同一套系统理解能力可扩展至需求增强、架构评审、线上排查及 Coding Agent 规划。只需赋予 LogHouse MCP 等新能力，即可轻松扩展“架构师 Agent"边界。
本文价值在于验证一种系统性的工程创新方法：将分散的知识与流程显性化、结构化，组织成 AI 可理解、推理和验证的工程系统。
参考资料
[1] GitHub. Spec Kit Documentation.
[2] Kiro. Specs.
[3] Kiro. Spec Best Practices.
[4] Anthropic. Effective harnesses for long-running agents.
[5] 分解一座冰山：后端系统「AI 知识库体系」建设实践。
[6] 后端架构 AI Friendly 的标准与路径：面向无人值守开发时代的系统重构。