LLM项目中架构决策记录（ADR）的工程化实践与价值

1. 项目概述：从ADR到智能决策的工程化实践

最近在整理过往项目文档时，我重新审视了一个名为“ADR”的文件夹。这个文件夹隶属于一个更大的项目“sirius-777-llm”，乍一看，这个命名充满了神秘感，像是某个科幻项目的一部分。实际上，它指向了一个在现代软件工程，尤其是涉及大型语言模型（LLM）的复杂系统中，至关重要但常被忽视的环节：架构决策记录（Architecture Decision Record， ADR）。如果你正在或即将参与一个技术栈复杂、迭代快速、团队协作紧密的项目，尤其是在AI应用开发领域，那么理解并实践ADR，很可能会成为你项目成功与否的分水岭。

简单来说，ADR不是一份事无巨细的设计文档，也不是一份会议纪要。它是一份轻量级、版本化、面向未来的决策日志。它的核心价值在于，当项目进行到第N个月，有新成员加入，或者老成员回头审视某个令人费解的技术选型时，能够通过查阅ADR，迅速理解“当初我们为什么选择了A方案，而不是看起来更优的B方案”。在“sirius-777-llm”这类项目中，技术决策点密集且关键，例如：为什么选择特定的LLM API供应商？为什么设计这样的提示词工程流水线？为什么采用某种特定的向量数据库分片策略？这些决策背后往往有复杂的权衡，ADR就是记录这些权衡过程的“黑匣子”。

这个项目（或这个文件夹）的存在，本身就暗示了一个成熟的工程实践：将决策过程显式化、文档化，并将其作为核心资产进行管理。它解决的痛点非常明确——避免“决策失忆”，确保团队认知对齐，并为未来的架构演进提供可靠的历史上下文。接下来，我将结合自身在多个AI项目中的实战经验，深入拆解如何构建一个真正有用、而非流于形式的ADR体系。

2. ADR的核心价值与在LLM项目中的特殊意义

2.1 为什么传统文档在LLM项目中“失灵”？

在常规的软件开发中，我们习惯撰写详尽的技术设计文档（Technical Design Document, TDD）。这类文档通常追求全面、静态和最终性。然而，在“sirius-777-llm”这类快速演进的LLM应用项目中，这种模式面临巨大挑战。

首先，技术生态迭代极快。新的模型、框架、优化工具几乎每周都在涌现。上个月的最优解，这个月可能就有了更高效的替代品。一份试图涵盖所有细节的静态设计文档，很可能在写完之时就已部分过时。其次，需求与能力的探索性极强。很多LLM应用的功能边界是在试错中明确的，最初的架构假设可能会被实际验证推翻。最后，决策的权衡因素更加多维。除了性能、成本、可维护性这些传统维度，我们还需要考虑模型输出稳定性（幻觉率）、提示词维护成本、上下文窗口限制、微调数据准备难度等全新维度。

ADR恰恰是针对这种动态、不确定环境而生的利器。它不追求描绘一个完美的终态，而是忠实记录在某个特定时间点，基于当时已知的信息和约束，团队是如何做出选择的。每一份ADR都是一个决策的“快照”。

2.2 ADR为LLM项目带来的四大核心收益

基于在多个AI项目中的实践，我总结出实施ADR能带来的最直接的四大收益：

1. 构建团队集体记忆与上下文：这是最根本的价值。LLM项目的技术栈通常很新，很多决策依赖于前期的小规模实验（POC）结果。例如，为什么选择ChatGPT的API而非Claude？可能不是因为前者绝对更好，而是因为在POC阶段，前者在特定任务上的输出格式更稳定，方便后续解析。这个细节如果不记录，三个月后新来的工程师可能会提议切换，团队需要重新花费时间解释甚至重新验证，造成资源浪费。

2. 促进理性、结构化的决策过程：ADR的模板强制要求填写“考虑的方案”、“决策结果”、“决策依据”等字段。这无形中要求决策者在会议或思考时，必须系统地罗列选项、对比优劣，而不是凭直觉或“我觉得”来做决定。例如，在选择向量数据库时，ADR会要求你列出对比Milvus、Pinecone、Weaviate的详细维度（部署复杂度、云服务成本、社区支持、与现有系统的集成度等），从而使决策更加客观。

3. 为新成员提供高效入职路径：一份组织良好的ADR目录，是新成员理解系统架构精髓的最佳教材。他们可以按时间顺序阅读，像看故事一样了解系统是如何一步步演化到今天这个样子的，理解每一个“奇怪”设计背后的历史原因，这比阅读一份庞大的、已经失去上下文的静态架构图要有效得多。

4. 为架构重构和审计提供依据：当业务发展需要重构系统时，ADR是宝贵的审计线索。我们可以回顾当初决策所依赖的条件（如“当时模型X的上下文窗口只有4K”）是否已经改变（现在模型Y支持128K）。如果核心约束条件已不复存在，那么推翻旧决策、进行架构演进就具备了充分理由。

注意：切忌把ADR写成“事后找补”的合理化说明。它的灵魂在于记录决策时的真实思考过程，包括那些被放弃的、看似有吸引力的选项。记录下“我们曾考虑过方案B，它简单且成本低，但因为无法满足未来6个月预计增长10倍的并发要求而放弃”，远比只歌颂已选方案A的优点更有价值。

3. 如何设计一份务实可用的ADR文档模板

一个糟糕的模板会让ADR写作变成负担，一个好模板则能引导思考。经过多个项目的迭代，我目前使用的ADR模板包含以下核心部分，它平衡了完备性和写作成本：

# [ADR-001] 为LLM服务层选择gRPC作为主要通信协议 ## 状态 提议 | 已接受 | 已弃用 | 已取代 **当前状态：** 已接受 (2023-10-26) ## 决策背景 我们正在构建“sirius-777-llm”项目的核心推理服务。该服务需要被多个上游业务模块（如Web后端、数据流水线、内部工具）以低延迟、高并发的形式调用。当前使用HTTP/JSON的临时方案在压测下出现了性能瓶颈和序列化开销问题。 ## 考虑的方案 1. **方案A：继续使用HTTP/JSON RESTful API** * **优点**：实现简单，通用性强，易于调试（可直接用curl或Postman）。 * **缺点**：序列化/反序列化开销大，头部冗长，缺乏强类型约束，双向流支持复杂。 2. **方案B：采用gRPC框架** * **优点**：基于HTTP/2，多路复用降低延迟；使用Protocol Buffers二进制序列化，效率极高；自动生成强类型客户端/服务端代码，减少错误；原生支持双向流，为未来实时交互功能预留空间。 * **缺点**：需要定义.proto文件，学习曲线稍陡；浏览器直接调用需要grpc-web网关；调试不如HTTP直观。 3. **方案C：使用GraphQL** * **优点**：客户端可精确查询所需数据，避免过度获取；单一端点。 * **缺点**：对于以“请求-响应”模式为主的LLM推理场景优势不明显；服务端实现复杂度高；缓存机制更复杂。 ## 决策结果 我们决定采用 **方案B：gRPC框架**。 ## 决策依据 1. **性能是核心关切**：压测数据显示，在相同负载下，gRPC相比HTTP/JSON的延迟降低约60%，吞吐量提升约3倍。这对于LLM推理这种计算密集型服务的响应时间至关重要。 2. **强类型保障系统健壮性**：LLM服务的输入输出结构复杂（可能包含多轮对话历史、系统指令、工具调用规范等）。.proto文件可以作为唯一的、版本化的接口契约，防止前后端数据结构不一致导致的运行时错误。 3. **面向未来扩展**：原生双向流支持为后续实现“流式Token输出”、“服务端推送中断信号”等高级特性提供了基础设施，无需重构通信层。 4. **团队能力可覆盖**：团队中有成员具备gRPC经验，且主流编程语言都有成熟支持，学习成本可控。对于浏览器调用需求，可通过轻量的grpc-web网关解决，影响面有限。 ## 影响与后果 ### 正面影响 * 服务间调用性能显著提升。 * 接口定义更加清晰和稳定。 * 为实现流式输出打下了基础。 ### 负面影响 * 前端同学需要适应通过grpc-web网关进行调用，调试流程需要调整。 * 需要引入新的工具链（protoc编译器、相关插件）并整合到CI/CD中。 ## 相关决策链接 * [ADR-000]：项目初始技术栈选型 * [PROTO-001]：LLM推理服务核心接口定义

模板使用心得：

• 标题编号：使用ADR-001这样的序列号，便于索引和引用。
• 状态跟踪：“状态”字段至关重要。决策可能被后续的新ADR推翻（状态变为“已取代”），明确状态可以避免团队参考过时的决策。
• 背景清晰：用简练语言说明“当时遇到了什么问题”，这是理解后续所有内容的基石。
• 方案对比表格化：在“考虑的方案”部分，我习惯用列表清晰罗列，关键优缺点一目了然。避免大段散文式描述。
• 依据量化优先：在“决策依据”中，尽可能使用数据（如压测结果、成本估算）说话。其次是可推导的逻辑（如“为未来特性预留空间”）。最次是主观判断（如“团队更熟悉”），但即便如此，也要写明是哪些成员熟悉，熟悉到什么程度。
• 不回避负面影响：诚实地记录“负面影响”，这既是风险管理，也为后续可能出现的“为什么我们当初要选这个麻烦东西”的质疑提供了预先答复。

4. ADR在LLM项目中的典型应用场景与实操记录

在“sirius-777-llm”这类项目中，哪些决策值得被记录成ADR？以下是我从实际项目中提炼出的几个高价值场景及其实操要点。

4.1 场景一：核心模型API供应商选型

这是LLM项目的基石级决策。记录此ADR时，重点不在于罗列所有供应商，而在于阐明评估框架和关键决胜因素。

实操记录：我们当时面临的选择包括OpenAI GPT-4、Anthropic Claude、以及国内的一些大模型API。在ADR中，我们首先明确了评估维度：

1. 能力维度：在特定任务（如长文本总结、代码生成、逻辑推理）上的基准测试分数。
2. 成本维度：按我们的预估调用量，月度成本测算。
3. 稳定性与运维维度：API的SLA承诺、历史故障率、监控工具生态。
4. 合规与数据安全维度：数据出境政策、供应商的数据处理协议。
5. 生态与工具链：SDK成熟度、是否有针对性的优化工具（如LangChain集成深度）。

决策过程关键点：我们并没有单纯选择“能力最强”或“最便宜”的模型。我们设计了一个加权评分卡。例如，对于我们的核心场景（客服对话摘要），能力权重占40%，成本占30%，稳定性占20%，其他占10%。然后为每个候选者在每个维度上打分。最终，模型A虽然在绝对能力上得分第二，但其极高的成本拉低了总分；模型B能力第一且成本适中，但在稳定性历史上得分较低；模型C能力稍逊（但仍超过基线），但成本最优且稳定性满分。经过激烈讨论，我们选择了模型C。

ADR记录的核心：在ADR的“决策依据”中，我们详细记录了这张评分卡、权重设定的理由（为什么客服场景下稳定性权重高达20%？因为服务中断直接影响客户体验），以及最终选择模型C的决定性因素：在满足能力基线的前提下，其卓越的性价比和稳定性承诺，为我们项目初期的快速迭代和成本控制提供了坚实保障。同时，我们也记录了“我们计划每季度重新评估此决策”，为未来切换供应商埋下伏笔。

4.2 场景二：提示词（Prompt）工程与管理策略

提示词是LLM应用的“源代码”。如何管理这些不断迭代、版本繁多的提示词，是一个必须通过ADR明确的重要工程决策。

实操记录：我们考虑了三种方案：

1. 方案A：硬编码在业务代码中。简单，但任何修改都需要重新部署服务，难以进行A/B测试，且容易在代码中散落得到处都是。
2. 方案B：存储在关系型数据库（如PostgreSQL）中。便于动态更新和版本管理，但缺乏对结构化内容（如few-shot示例）的良好查询支持。
3. 方案C：使用专门的配置中心或文档数据库（如MongoDB），并建立Git仓库同步机制。将提示词视为独立的配置文件，存储在Git中实现版本控制，通过配置中心下发到应用，数据库仅作缓存和元数据管理。

决策与实施细节：我们选择了方案C，并设计了具体的工作流：

• 每个提示词模板是一个YAML文件，包含id、描述、系统指令、用户指令模板、few_shot_examples、版本、创建者等字段。
• 这些YAML文件存放在一个独立的Git仓库中，通过Pull Request进行变更评审，CI会自动进行基础的语法检查和模板变量验证。
• 服务启动时，从配置中心拉取最新版本的提示词配置并缓存。配置中心后端与Git仓库同步。
• 在数据库中，我们只存储prompt_id和version，以及每次调用的日志（用于后续分析和提示词优化）。

ADR记录的价值：这份ADR不仅记录了选择方案C，更重要的是记录了这个工作流的设计细节和选型理由。例如，为什么选择YAML而不是JSON？因为YAML支持多行字符串，更适合编写长篇提示词。为什么引入Git PR流程？因为提示词的调整需要算法工程师、产品经理和业务方共同评审，Git的协作流程最成熟。这份ADR成为了后续所有提示词开发者的操作手册，避免了每个人用不同的方式管理提示词导致的混乱。

4.3 场景三：向量数据库的选型与部署模式

当项目涉及RAG（检索增强生成）时，向量数据库的选型至关重要。这个决策涉及技术、运维和成本的多重考量。

实操记录：我们对比了Pinecone（全托管）、Weaviate（自托管/托管均可）、Qdrant（自托管）和PGVector（PostgreSQL扩展）。在ADR中，我们创建了一个详细的对比表格：

决策的深层逻辑：经过讨论，我们排除了PGVector，因为预计的向量数据量和查询QPS较高，担心对现有业务数据库造成冲击。在Pinecone和自托管方案之间，我们产生了分歧。支持Pinecone的理由是“让专业的人做专业的事”，团队可以聚焦业务逻辑。支持自托管（最终选了Qdrant）的理由则基于两点：1)成本控制：长期来看，自托管的服务器成本远低于SaaS服务费，且我们的数据量增长可预测；2)数据主权与网络延迟：所有数据留在自有环境，且服务间内网调用延迟极低、更稳定。

ADR如何记录权衡：在“决策依据”部分，我们没有简单地写“选择了Qdrant”。我们写道：“在项目初期，快速启动和降低运维负担是优先项，Pinecone是更优选择。但基于本项目的长期规划（3年）、对数据隐私的较高要求、以及团队具备容器化运维能力，我们决定承担初期更高的搭建成本，以换取长期的技术自主权和更低的TCO（总拥有成本）。选择Qdrant而非Weaviate，是因为其架构更简洁，文档清晰，且基准测试中在过滤查询场景下性能表现更符合我们的业务查询模式。” 这样的记录，即使未来有人质疑“当初为什么不用更省事的Pinecone”，也能一目了然。

5. ADR工作流的建立与团队文化培育

有了好的模板和场景，如何让ADR真正融入团队的工作流，而不是沦为“额外的文档负担”？这是成败的关键。

5.1 将ADR嵌入开发流程

我们的实践是，将ADR的创建和评审作为技术设计方案评审（Tech Design Review）的强制性产出物。

1. 触发时机：当一项技术决策满足以下任一条件时，必须发起ADR流程：

   • 影响系统核心架构（如通信协议、数据存储方案）。
   • 引入新的重大技术依赖（如新的数据库、中间件、第三方服务）。
   • 涉及显著的跨团队协作或长期维护成本。
   • 存在多个可行方案且各有优劣，需要正式记录选择理由。

2. 流程闭环：

   • 提案：决策发起人根据模板起草ADR，状态标记为“提议”。
   • 讨论与评审：在技术评审会议上，围绕ADR文档展开讨论。重点审查“考虑的方案”是否全面，“决策依据”是否充分。
   • 记录与归档：会议达成一致后，更新ADR状态为“已接受”，并合并到项目代码仓库的docs/adr/目录下（与代码版本一同管理）。
   • 通知：将已接受的ADR链接同步到相关项目的README或架构概览文档中。

5.2 工具链支持

• 版本控制：ADR必须放在Git仓库中（如docs/adr/）。这样它们就有了历史版本，可以追溯修改，并且与相关的代码变更通过Commit关联起来。
• 目录与索引：在docs/adr/目录下维护一个README.md或index.md文件，以表格形式列出所有ADR，包含编号、标题、状态、日期和简短摘要。这相当于决策日志的目录。

  | 编号 | 标题 | 状态 | 日期 | 摘要 | |------|------|------|------|------| | 0001 | 选择gRPC作为主要通信协议 | 已接受 | 2023-10-26 | 为提升性能与强类型约束... | | 0002 | LLM API供应商选型 | 已接受 | 2023-11-05 | 基于多维度评估选择模型C... | | 0003 | 提示词管理策略 | 已接受 | 2023-11-20 | 采用Git+配置中心管理提示词... |

• 轻量级工具：对于小型团队，Markdown文件加Git就足够了。如果追求更自动化，可以考虑使用像adr-tools这样的命令行工具来生成模板和管理状态。

5.3 培育“决策透明”的团队文化

这是最难但最重要的一环。管理者和技术负责人需要以身作则：

• 自上而下推行：在项目启动初期，由架构师或技术负责人撰写最初几份关键的ADR，作为范本。
• 强调价值，而非负担：在团队内部分享因缺乏ADR而导致的“历史之谜”和沟通成本，让大家切身感受到其价值。例如：“还记得我们上周花了半天时间争论为什么不用Redis而用Memcached吗？如果当时有ADR，5分钟就能搞清楚。”
• 鼓励挑战与更新：明确ADR不是“圣旨”。当有新的事实、技术或需求出现时，鼓励团队成员提出新的ADR来挑战或取代旧的决策。将状态更新为“已取代”不是失败，而是架构健康演进的标志。
• 在入职流程中引入：要求新成员在熟悉代码前，先阅读核心的ADR索引，让他们快速理解系统的设计脉络。

6. 常见陷阱、问题排查与进阶技巧

即使理解了ADR的价值和流程，在实际操作中仍会踩坑。以下是一些常见问题及应对策略。

6.1 常见陷阱

1. ADR过于冗长或过于简略：

   • 问题：要么像写论文，事无巨细；要么只有一句话结论。
   • 排查：检查是否遵循了模板。核心应聚焦在“背景”、“方案对比”、“决策依据”和“影响”。技术细节可以链接到详细设计文档。
   • 技巧：假设读者是一个一年后的新同事。他需要多少信息才能理解这个决策？以此为尺度来把握详略。

2. 把ADR写成“事后诸葛亮”或“邀功报告”：

   • 问题：只记录最终成功的方案和它的优点，对当初的犹豫、被否定的优秀方案闭口不谈。
   • 排查：检查“考虑的方案”部分是否真诚地列出了其他选项及其真实优点。“决策依据”是否承认了已选方案的缺点？
   • 技巧：在评审时，可以特意问：“我们当时有没有考虑过XX方案？为什么没选它？” 把讨论过程记录下来。

3. 有始无终，状态永不更新：

   • 问题：ADR写完就扔进文件夹，决策被推翻了也没人更新状态。
   • 排查：建立定期（如每季度）回顾ADR的机制。在涉及重大架构变更的代码评审中，要求关联的ADR必须被提及和评估。
   • 技巧：在团队看板或Wiki首页设置一个“待回顾ADR”列表，提醒大家哪些决策可能因条件变化而需要重新审视。

4. 与代码和现实脱节：

   • 问题：ADR记录的选择是A，但实际代码中实现的是B，或者参数已经完全不同。
   • 排查：在代码的关键部分（如配置定义、初始化模块）添加注释，引用相关的ADR编号。例如：// 使用gRPC通信，详见 ADR-001。
   • 技巧：将ADR检查纳入发布流程或关键合并请求（Merge Request）的检查项中，确保重大变更都有文档依据。

6.2 进阶技巧：让ADR发挥更大价值

1. 决策日志与项目周报/月报结合：在项目定期同步中，不仅同步完成了什么功能，也同步做出了什么重要技术决策（附上ADR链接）。这能让所有干系人，包括非技术成员，理解技术演进的脉络。

2. 建立ADR间的关联网络：一份ADR可能会引用或影响另一份。在ADR中通过“相关决策链接”字段建立这种关联。例如，一份关于“引入缓存”的ADR，可能会链接到之前关于“数据库选型”和“API设计”的ADR。这有助于构建一个立体的决策知识图谱。

3. 用于风险评估和预案制定：在记录“负面影响”时，其实就是在进行风险识别。团队可以基于此，提前制定缓解预案。例如，选择了自托管向量数据库，负面影响是“运维负担高”，那么预案可以是“编写详细的运维手册，并安排专人负责头三个月的监控和调优”。

4. 作为技术债的“借条”：有时，我们不得不为了赶工期而做出一个次优的短期决策（例如，先使用简单的文件存储，而不是上数据库）。在ADR中，诚实记录这是一个“临时方案”，并明确记录“技术债条目：需要在Q3前重构为数据库存储，详见未来ADR”。这使技术债显性化、可追踪。

回顾“sirius-777-llm/ADR”这个项目，它代表的不仅仅是一个存放文档的文件夹，更是一种面向复杂性和不确定性的工程哲学。在技术日新月异、需求快速变化的今天，尤其是AI原生应用开发领域，我们无法依靠一份完美的前期设计图走到终点。我们需要的是一套机制，能够持续地、结构化地记录我们如何在每一个岔路口做出选择，以及为什么这么选。这套机制就是ADR。它让团队的智慧得以沉淀，让系统的演进有迹可循，最终让“sirius-777-llm”这样的复杂项目，从一个充满未知的探索，变成一场步步为营的扎实建设。开始为你的下一个重要决策写一份ADR吧，这是你送给未来自己和团队的一份宝贵礼物。