CIAO - Code In Architecture Out - Automated Software Architecture Documentation with Large Language Models

📄 arXiv: 2604.08293v1 📥 PDF

作者: Marco De Luca, Tiziano Santilli, Domenico Amalfitano, Anna Rita Fasolino, Patrizio Pelliccione

分类: cs.SE, cs.AI

发布日期: 2026-04-09

备注: Manuscript accepted for the 23rd International Conference on Software Architecture (ICSA 2026)

💡 一句话要点

CIAO：利用大语言模型自动生成软件架构文档，提升系统可理解性。

🎯 匹配领域: 支柱九：具身大模型 (Embodied Foundation Models)

关键词: 软件架构文档 大语言模型 自动化文档生成 系统理解 软件维护

📋 核心要点

  1. 现有软件架构文档缺失或不完整，阻碍了系统理解和维护，而基于LLM的文档生成方法通常关注局部代码片段。
  2. CIAO流程利用LLM，结合ISO/IEC/IEEE 42010等标准，从代码仓库自动生成系统级的、结构化的架构文档。
  3. 实验表明，开发者认为CIAO生成的文档有价值且准确，同时指出了图表质量和高级上下文建模方面的改进空间。

📝 摘要（中文）

软件架构文档对于系统理解至关重要，但通常缺失或不完整。虽然最近基于大语言模型（LLM）的技术可以从代码生成文档，但它们通常针对局部工件，而不是生成连贯的系统级架构描述。本文提出了一种结构化的流程，称为CIAO（Code In Architecture Out），使用大语言模型直接从GitHub存储库自动生成系统级架构文档。该流程定义了一个基于LLM的工作流程，以存储库作为输入，并按照从ISO/IEC/IEEE 42010、SEI Views & Beyond和C4模型派生的模板生成系统级架构文档。生成的文档可以直接添加到目标存储库。我们通过一项有22名开发人员参与的研究评估了该流程，每位开发人员都审查了为其贡献的存储库生成的文档。评估表明，开发人员普遍认为生成的文档有价值、易于理解，并且在很大程度上与源代码准确对应，同时也强调了图表质量、高级上下文建模和部署视图方面的局限性。我们还评估了该流程的运营成本，发现生成完整的架构文档只需要几分钟，而且运行成本低廉。总体而言，结果表明，结构化的、面向标准的方法可以有效地指导LLM生成可用且经济高效的系统级架构文档。

🔬 方法详解

问题定义：论文旨在解决软件架构文档缺失或不完整的问题。现有的基于LLM的方法通常只关注代码的局部片段，无法生成系统级的、连贯的架构描述，导致开发者难以理解系统的整体结构和设计。

核心思路：核心思路是利用LLM的自然语言生成能力，结合软件架构文档的标准规范（如ISO/IEC/IEEE 42010、SEI Views & Beyond和C4模型），构建一个结构化的流程，将代码仓库作为输入，自动生成符合规范的系统级架构文档。这样设计的目的是为了保证生成的文档具有良好的结构性、可读性和准确性。

技术框架：CIAO流程包含以下主要阶段：1) 代码仓库分析：分析代码仓库的结构和内容，提取关键的软件组件和关系。2) 架构视图生成：根据提取的信息，利用LLM生成不同的架构视图，例如上下文视图、容器视图和组件视图。3) 文档组装：将生成的架构视图按照预定义的模板组装成完整的架构文档。4) 文档验证：对生成的文档进行验证，确保其符合规范和准确性。

关键创新：最重要的技术创新点在于将LLM与软件架构文档的标准规范相结合，构建了一个结构化的文档生成流程。与现有的方法相比，CIAO能够生成系统级的、连贯的架构描述，并且保证了文档的质量和可维护性。

关键设计：CIAO流程的关键设计包括：1) 架构视图的选择：根据不同的系统特点选择合适的架构视图。2) LLM的提示工程：设计合适的提示语，引导LLM生成高质量的架构描述。3) 文档模板的设计：设计清晰、易于理解的文档模板，方便开发者阅读和使用。

📊 实验亮点

研究通过对22名开发者的评估表明，CIAO生成的文档被普遍认为有价值、易于理解且与源代码准确对应。生成完整架构文档仅需几分钟，成本低廉。尽管在图表质量和高级上下文建模方面存在局限，但整体结果表明，结构化方法能有效指导LLM生成可用且经济高效的系统级架构文档。

🎯 应用场景

该研究成果可应用于软件开发和维护的各个阶段，帮助开发者快速理解系统架构，提高开发效率和代码质量。尤其适用于大型、复杂的软件系统，以及需要频繁维护和升级的系统。未来可进一步扩展到其他类型的软件文档生成，例如API文档、用户手册等。

📄 摘要（原文）

Software architecture documentation is essential for system comprehension, yet it is often unavailable or incomplete. While recent LLM-based techniques can generate documentation from code, they typically address local artifacts rather than producing coherent, system-level architectural descriptions. This paper presents a structured process for automatically generating system-level architectural documentation directly from GitHub repositories using Large Language Models. The process, called CIAO (Code In Architecture Out), defines an LLM-based workflow that takes a repository as input and produces system-level architectural documentation following a template derived from ISO/IEC/IEEE 42010, SEI Views \& Beyond, and the C4 model. The resulting documentation can be directly added to the target repository. We evaluated the process through a study with 22 developers, each reviewing the documentation generated for a repository they had contributed to. The evaluation shows that developers generally perceive the produced documentation as valuable, comprehensible, and broadly accurate with respect to the source code, while also highlighting limitations in diagram quality, high-level context modeling, and deployment views. We also assessed the operational cost of the process, finding that generating a complete architectural document requires only a few minutes and is inexpensive to run. Overall, the results indicate that a structured, standards-oriented approach can effectively guide LLMs in producing system-level architectural documentation that is both usable and cost-effective.