[Paper] AgenticAKM：通往 Agentic 架构知识管理之路

Source: arXiv - 2602.04445v1

概述

论文 AgenticAKM: Enroute to Agentic Architecture Knowledge Management 解决了开发者和架构师长期面临的一个痛点：保持软件架构文档的最新。通过编排多个专门的基于大语言模型（LLM）的“代理”，这些代理协同进行提取、检索、生成和验证架构知识，作者展示了一种实用的方法，可直接从代码仓库自动生成架构决策记录（ADRs）。

关键贡献

• Agentic workflow for AKM – 引入一个多代理流水线（Extraction, Retrieval, Generation, Validation），将架构恢复的复杂任务分解为可处理的子任务。
• Prototype for ADR generation – 在真实的 GitHub 仓库上实现该工作流，自动生成捕获设计决策的 ADR。
• Empirical user study – 在 29 个开源项目上评估该方法，显示出相较于单一提示基线更高质量的 ADR。
• Open discussion of prompt engineering limits – 阐明了为何天真的“一刀切提示”策略在分布式架构知识中会失败。

方法论

1. 问题分解 – 作者将架构知识管理视为一系列步骤，而不是单一的查询。
2. 专用代理
   • Extraction Agent 扫描代码库（例如构建文件、配置、源代码），提取低层次的工件（组件、依赖、模式）。
   • Retrieval Agent 搜索现有文档、问题跟踪系统和提交信息，以定位任何先前的架构理由。
   • Generation Agent 将收集到的工件输入 LLM 提示，起草 ADR，遵循标准模板（Context、Decision、Status、Consequences）。
   • Validation Agent 进行一致性检查（例如，ADR 是否引用了现有代码？必填字段是否完整？），并在需要时请求 LLM 对草稿进行完善。
3. 迭代循环 – 如果验证失败，重新调用 Generation Agent 并提供额外上下文，模拟人工审阅者的来回交流。
4. 实现 – 原型使用 OpenAI 的 GPT‑4 API、一个简单的文件系统爬虫以及用于检索的向量存储。整个流水线通过轻量级任务队列进行编排。

结果与发现

• 质量提升 – 在用户研究中，78 % 的 AgenticAKM 生成的 ADR 被参与者评为“有用”或“非常有用”，而单提示基线仅为 52 %。
• 降低人工工作量 – 参与者报告称，当可以从代理生成的草稿开始时，撰写 ADR 所花费的时间下降了 40 %。
• 更高的覆盖率 – 多代理系统在 29 个代码库中有 6 个发现了原始文档中完全缺失的架构决策。
• 提示长度管理 – 通过将问题拆分，每次 LLM 调用都保持在令牌限制之内，避免了笨拙方法中出现的截断问题。

实际意义

• Automated ADR pipelines – Teams can plug AgenticAKM into CI/CD to continuously generate or update ADRs as code evolves, keeping documentation in sync without extra overhead.
• On‑boarding acceleration – New hires get instant, LLM‑generated summaries of key design choices, shortening the learning curve.
• Compliance & audit readiness – Regular, machine‑produced architecture records help satisfy regulatory or internal governance requirements.
• Extensible to other artefacts – The same agentic pattern could be repurposed for generating design docs, API contracts, or migration guides, making it a reusable building block for knowledge automation.

局限性与未来工作

• LLM 幻觉风险 – 虽然验证代理缓解了明显错误，但系统仍可能产生看似合理却不正确的推理，尤其是当源代码缺乏明确模式时。
• 领域特异性 – 原型在开源 Java/JavaScript 项目上进行评估；在遗留代码库、微服务生态系统或底层系统上的表现仍未测试。
• 检索可扩展性 – 当前的向量存储适用于中等规模的代码库；更大的单体仓库可能需要更复杂的索引和分块策略。
• 未来方向 – 作者计划 (1) 集成静态分析工具以提取更丰富的制品，(2) 试验微调的 LLM 以降低幻觉，(3) 将评估范围扩大到具有更严格安全约束的工业环境。

作者

• Rudra Dhar
• Karthik Vaidhyanathan
• Vasudeva Varma

论文信息

• arXiv ID: 2602.04445v1
• 分类: cs.SE
• 出版日期: 2026年2月4日
• PDF: Download PDF