目录一、什么是架构总览二、架构总览的知识模板如何定义2.1 总览页设计2.2 服务清单字段(最重要的模板)2.3 依赖图(dependency-graph.md)结构2.4 技术栈矩阵(tech-stack.md)结构2.5 部署拓扑(deployment.md)结构三、架构总览的更新机制应该如何落地3.1 关键设计点3.2 反模式四、架构总览的质量标准应该如何定义4.1 3 个反向指标(出现就告警)4.2 准入与淘汰门槛一、什么是架构总览它是什么它不是什么系统当前的地图系统的历史(那是 ADR)LLM 自动生成的影子人手画的愿景图给人和 Agent 共同消费的查询表给人读的散文式设计文档强结构化(图、表、清单)湿润化(大量解释文字)核心判断:架构总览 代码的影子,不是人写的文档。人手画的架构图 100% 跟代码脱节。LLM 从代码/配置/部署文件抽取,人 review,这是它和知识词典的本质区别——词典是对齐,架构总览是反射。二、架构总览的知识模板如何定义核心判断强结构化,几乎全用表格/列表。 架构总览不是读的,是查的。核心包含5类模板模板文件位置内容总览页20-architecture/overview.md系统一句话、规模、技术栈、部署环境、更新时间服务清单20-architecture/services/[name].md每个服务一个文件依赖图20-architecture/dependency-graph.md服务间调用关系技术栈矩阵20-architecture/tech-stack.md服务 × 技术栈二维表部署拓扑20-architecture/deployment.md环境 × 部署方式2.1 总览页设计字段类型来源必填系统名称string配置✓业务域划分list代码✓服务数量numberLLM 自动✓主要技术栈listLLM 自动✓部署环境列表listK8s✓上次自动生成时间datetime工具✓上次架构师 review 时间date人工✓2.2 服务清单字段(最重要的模板)字段类型来源必填备注服务名string服务注册✓唯一业务域enum配置✓业务域分类负责人user/teamCODEOWNERS✓技术栈list代码✓语言/框架/DB主要职责string(≤30字)LLM 草拟 人工审✓一句话上游依赖list[link]LLM 自动✓调用谁下游被调用list[link]LLM 自动✓谁调用我关键 APIlist[link]链接到 30-api/✓部署位置listK8s✓哪些环境SLOobject监控×可用性/延迟监控链接linkDatadog/Prometheus✓关联 ADRlist[link]人工补×关键决策关联 Runbooklist[link]链接到 40-runbooks/×告警处理关键路径标记enum人工标×P0/P1/P2最后更新datetime工具✓2.3 依赖图(dependency-graph.md)结构元素表示数据来源节点服务 / 数据库 / 外部依赖服务注册 schema边调用方向、协议、流量量级LLM 从 trace 抽节点颜色内部服务 / 外部 / 存储规则化边颜色同步 / 异步 / 批处理协议推断关键路径高亮P0 服务和它们的链路人工标数据来源自动生成工具上次生成时间datetime工具2.4 技术栈矩阵(tech-stack.md)结构务/组件语言框架数据库消息队列缓存部署方式镜像api-gatewayGoKong 自研插件——Redis 7K8sregistry.example.com/gateway:v3.2.1user-serviceJava 17Spring Boot 3.2MySQL 8.0(主从)Kafka 3.6Redis 7K8sregistry.example.com/user:v2.8.02.5 部署拓扑(deployment.md)结构环境部署方式入口域名/网关数据隔离监控告警通道local-dev(本地开发)Docker Compose Tilt*.localhost:3000每人独立 MySQL/Redis 实例,本地 mock 第三方无(只本地 stdout 日志)integration(集成测试)K8s namespace(PR merge 自动部署)integration.internal.example.com完全独立 cluster,合成数据,无生产数据Slack#alerts-integration(只 P0)staging(预发)K8s 独立 cluster(蓝绿)staging.example.com与生产物理隔离,每日 02:00 从生产脱敏同步Slack#alerts-staging 值班人飞书(仅 P0/P1)三、架构总览的更新机制应该如何落地核心判断架构总览 代码的影子。代码动,它动。没有自动化的影子,影子就是假的。包含4 个触发器触发器触发条件动作责任方PR-ingestPR 改动服务结构/依赖/部署配置LLM 重生成对应章节,diff 化,走 PR自动每日重建每日定时全文重建,做 diff 检视自动重大变更触发新服务/下线服务/关键依赖变化/改 SLO必须人工 review,可能触发 ADR人工 LLM手动触发架构师发现需要更新立即触发重建人工3.1 关键设计点设计点具体要求写入通道所有生成走 PR(包括 LLM 自动)变更可见性PR 必须显示diff(哪变了),人 review 时只看 diff稳定时 auto-merge如果重建后无 diff,自动跳过重大变更必人审新服务/下线/关键依赖变化,SLA 24h 内 review日常变更抽样审LLM 自动审 10%,架构师扫一遍每周全量 review架构师每周一次全量扫架构总览,10-30 分钟ADR 联动重大变更 PR 自动建议是否需要写 ADR影子回写 Raw架构总览有孤儿服务时告警(代码里没有但总览里有)3.2 反模式反模式后果让人手改架构总览改完就脱节LLM 直接写主分支失治理,2 周后没人信不做 diff,全文覆盖看不见哪变了,review 不可能重建频率太低(月级)期间变更会大量丢失重建频率太高(分钟级)噪声淹没信号,review 疲劳关键路径长期不标值班时不知道 P0 路径,救火慢四、架构总览的质量标准应该如何定义核心判断架构总览的质量 跟代码的同步度 关键信息完整度。不是图漂不漂亮。5 个核心指标指标定义健康值测量方式同步延迟代码变更到架构总览更新的时间≤ 24hPR 时间戳 vs 重建时间戳链接有效性架构总览中所有链接 100% 解析≥ 99%自动化服务覆盖率已部署服务在总览中出现的比例100%对照服务注册ADR 关联率关键决策(选型/架构)有 ADR 链接的比例≥ 90%抽样审关键路径标注完整度P0 服务都被标注关键路径100%人工核查4.1 3 个反向指标(出现就告警)反向指标告警触发修复动作漏抽代码里有新服务但总览没有触发新服务检测流水线,补源数据幽灵服务总览里有但服务注册里没有触发服务下线检测,确认是否真下线决策脱节关键选型(语言/中间件)没 ADR 链接提示架构师补 ADR4.2 准入与淘汰门槛门槛触发动作新服务准入服务注册新增服务,但总览缺自动告警,要求 owner 补全服务清单服务下线淘汰服务注册移除服务,但总览还在30 天未处理,自动标 deprecatedADR 缺失关键决策无 ADR 链接季度审查时列出,要求补幽灵服务总览有但运行时没有立即告警,要么补回,要么归档
Agent开发系列（十）-知识库建设（架构总览）
目录一、什么是架构总览二、架构总览的知识模板如何定义2.1 总览页设计2.2 服务清单字段(最重要的模板)2.3 依赖图(dependency-graph.md)结构2.4 技术栈矩阵(tech-stack.md)结构2.5 部署拓扑(deployment.md)结构三、架构总览的更新机制应该如何落地3.1 关键设计点3.2 反模式四、架构总览的质量标准应该如何定义4.1 3 个反向指标(出现就告警)4.2 准入与淘汰门槛一、什么是架构总览它是什么它不是什么系统当前的地图系统的历史(那是 ADR)LLM 自动生成的影子人手画的愿景图给人和 Agent 共同消费的查询表给人读的散文式设计文档强结构化(图、表、清单)湿润化(大量解释文字)核心判断:架构总览 代码的影子,不是人写的文档。人手画的架构图 100% 跟代码脱节。LLM 从代码/配置/部署文件抽取,人 review,这是它和知识词典的本质区别——词典是对齐,架构总览是反射。二、架构总览的知识模板如何定义核心判断强结构化,几乎全用表格/列表。 架构总览不是读的,是查的。核心包含5类模板模板文件位置内容总览页20-architecture/overview.md系统一句话、规模、技术栈、部署环境、更新时间服务清单20-architecture/services/[name].md每个服务一个文件依赖图20-architecture/dependency-graph.md服务间调用关系技术栈矩阵20-architecture/tech-stack.md服务 × 技术栈二维表部署拓扑20-architecture/deployment.md环境 × 部署方式2.1 总览页设计字段类型来源必填系统名称string配置✓业务域划分list代码✓服务数量numberLLM 自动✓主要技术栈listLLM 自动✓部署环境列表listK8s✓上次自动生成时间datetime工具✓上次架构师 review 时间date人工✓2.2 服务清单字段(最重要的模板)字段类型来源必填备注服务名string服务注册✓唯一业务域enum配置✓业务域分类负责人user/teamCODEOWNERS✓技术栈list代码✓语言/框架/DB主要职责string(≤30字)LLM 草拟 人工审✓一句话上游依赖list[link]LLM 自动✓调用谁下游被调用list[link]LLM 自动✓谁调用我关键 APIlist[link]链接到 30-api/✓部署位置listK8s✓哪些环境SLOobject监控×可用性/延迟监控链接linkDatadog/Prometheus✓关联 ADRlist[link]人工补×关键决策关联 Runbooklist[link]链接到 40-runbooks/×告警处理关键路径标记enum人工标×P0/P1/P2最后更新datetime工具✓2.3 依赖图(dependency-graph.md)结构元素表示数据来源节点服务 / 数据库 / 外部依赖服务注册 schema边调用方向、协议、流量量级LLM 从 trace 抽节点颜色内部服务 / 外部 / 存储规则化边颜色同步 / 异步 / 批处理协议推断关键路径高亮P0 服务和它们的链路人工标数据来源自动生成工具上次生成时间datetime工具2.4 技术栈矩阵(tech-stack.md)结构务/组件语言框架数据库消息队列缓存部署方式镜像api-gatewayGoKong 自研插件——Redis 7K8sregistry.example.com/gateway:v3.2.1user-serviceJava 17Spring Boot 3.2MySQL 8.0(主从)Kafka 3.6Redis 7K8sregistry.example.com/user:v2.8.02.5 部署拓扑(deployment.md)结构环境部署方式入口域名/网关数据隔离监控告警通道local-dev(本地开发)Docker Compose Tilt*.localhost:3000每人独立 MySQL/Redis 实例,本地 mock 第三方无(只本地 stdout 日志)integration(集成测试)K8s namespace(PR merge 自动部署)integration.internal.example.com完全独立 cluster,合成数据,无生产数据Slack#alerts-integration(只 P0)staging(预发)K8s 独立 cluster(蓝绿)staging.example.com与生产物理隔离,每日 02:00 从生产脱敏同步Slack#alerts-staging 值班人飞书(仅 P0/P1)三、架构总览的更新机制应该如何落地核心判断架构总览 代码的影子。代码动,它动。没有自动化的影子,影子就是假的。包含4 个触发器触发器触发条件动作责任方PR-ingestPR 改动服务结构/依赖/部署配置LLM 重生成对应章节,diff 化,走 PR自动每日重建每日定时全文重建,做 diff 检视自动重大变更触发新服务/下线服务/关键依赖变化/改 SLO必须人工 review,可能触发 ADR人工 LLM手动触发架构师发现需要更新立即触发重建人工3.1 关键设计点设计点具体要求写入通道所有生成走 PR(包括 LLM 自动)变更可见性PR 必须显示diff(哪变了),人 review 时只看 diff稳定时 auto-merge如果重建后无 diff,自动跳过重大变更必人审新服务/下线/关键依赖变化,SLA 24h 内 review日常变更抽样审LLM 自动审 10%,架构师扫一遍每周全量 review架构师每周一次全量扫架构总览,10-30 分钟ADR 联动重大变更 PR 自动建议是否需要写 ADR影子回写 Raw架构总览有孤儿服务时告警(代码里没有但总览里有)3.2 反模式反模式后果让人手改架构总览改完就脱节LLM 直接写主分支失治理,2 周后没人信不做 diff,全文覆盖看不见哪变了,review 不可能重建频率太低(月级)期间变更会大量丢失重建频率太高(分钟级)噪声淹没信号,review 疲劳关键路径长期不标值班时不知道 P0 路径,救火慢四、架构总览的质量标准应该如何定义核心判断架构总览的质量 跟代码的同步度 关键信息完整度。不是图漂不漂亮。5 个核心指标指标定义健康值测量方式同步延迟代码变更到架构总览更新的时间≤ 24hPR 时间戳 vs 重建时间戳链接有效性架构总览中所有链接 100% 解析≥ 99%自动化服务覆盖率已部署服务在总览中出现的比例100%对照服务注册ADR 关联率关键决策(选型/架构)有 ADR 链接的比例≥ 90%抽样审关键路径标注完整度P0 服务都被标注关键路径100%人工核查4.1 3 个反向指标(出现就告警)反向指标告警触发修复动作漏抽代码里有新服务但总览没有触发新服务检测流水线,补源数据幽灵服务总览里有但服务注册里没有触发服务下线检测,确认是否真下线决策脱节关键选型(语言/中间件)没 ADR 链接提示架构师补 ADR4.2 准入与淘汰门槛门槛触发动作新服务准入服务注册新增服务,但总览缺自动告警,要求 owner 补全服务清单服务下线淘汰服务注册移除服务,但总览还在30 天未处理,自动标 deprecatedADR 缺失关键决策无 ADR 链接季度审查时列出,要求补幽灵服务总览有但运行时没有立即告警,要么补回,要么归档
