基于 C4 模型的自底向上架构文档生成工作流在 agentic-awesome-skills 中为仓库生成 Context-Container-Component-Code 四级架构文档【免费下载链接】agentic-awesome-skillsAAS Core is the local, agent-first control plane for complete catalog discovery, agent-owned selection, stack validation, and planning, backed by 2,600 agentic skills. Includes CLI, local MCP, catalog, plugins, and Workbench.项目地址: https://gitcode.com/GitHub_Trending/an/agentic-awesome-skills导读本文讲解 agentic-awesome-skills 仓库中c4-architecture-c4-architecture技能位于 SKILL.md所定义的一套完整 C4 架构文档工作流它以自底向上bottom-up的方式依次从最深代码目录开始生成 Code 级文档再逐层综合出 Component、Container 与 Context 级文档最终在仓库根目录生成一套C4-Documentation/文档集。读完本文你将掌握如何对一个既有仓库执行这套四阶段流程、如何调度四个专用 C4 子代理、如何产出 OpenAPI 3.1 接口规范与 Mermaid C4 图以及该工作流的配置项、成功标准与适用边界。C4 模型与本工作流的设计思想C4 模型由四个抽象层级组成Context系统上下文→ Container容器→ Component组件→ Code代码从宏观到微观逐层放大系统。本技能的核心工作流正是围绕这四个层级展开其设计上有两个鲜明特征自底向上Bottom-Up不同于先画系统框再拆细节的传统自上而下思路该工作流先扫描仓库中每一个代码目录从最深目录开始逐个产出 Code 级文档保证每个代码元素都被文档化之后再向上综合出更高层抽象。这一方式特别适合对既有仓库/代码库进行逆向梳理因为所有高层结论都有底层代码作为证据支撑。多代理协作工作流协调四个专用子代理完成整套文档产出——c4-code代码级、c4-component组件级、c4-container容器级、c4-context系统上下文级分别对应仓库中的 c4-code/SKILL.md、c4-component/SKILL.md、c4-container/SKILL.md、c4-context/SKILL.md。主文档还特别提示根据 C4 模型官方建议并非所有团队都需要画全四个层级的图——对于大多数软件开发团队系统上下文图与容器图通常已经足够本工作流为完整性起见生成全部层级团队可以按需选用。使用时机与边界技能头部定义了清晰的适用范围便于 Agent 判断何时激活该技能适用场景正在执行 c4 架构文档工作流类任务需要 c4 架构文档工作流的指南、最佳实践或检查清单。不适用场景任务与 c4 架构文档工作流无关需要本范围之外的领域或工具。此外技能在 Instructions 一节要求 Agent 先澄清目标、约束与必要输入再应用相关最佳实践并验证产出当需要详细示例时应打开resources/implementation-playbook.md。Phase 1Code 级文档自底向上分析1.1 发现全部子目录工作流第一步是对仓库进行目录盘点使用代码库搜索识别仓库中所有子目录按目录深度排序最深的优先以支持自底向上处理过滤常见非代码目录node_modules、.git、build、dist等生成待处理目录清单。这一步骤的意义在于建立完整覆盖的前提——只有先穷举全部目录才能保证后续每个代码目录都有一份 Code 级文档与之对应。1.2 逐目录处理自底向上对每个目录从最深开始使用 Task 工具并以subagent_typec4-architecture::c4-code调度子代理其提示词要求产出四部分内容Overview 概览Name该代码目录的描述性名称、Description简述其功能、Location相对仓库根目录的目录路径链接、Language主要编程语言、Purpose该代码完成什么。Code Elements 代码元素文档化所有函数/方法要求包含完整签名函数名、参数含类型、返回类型、功能描述、位置文件路径与行号、依赖文档化所有类/模块类名、描述、位置、方法及其签名、依赖。Dependencies 依赖内部依赖仓库内其他代码与外部依赖库、框架、服务。Relationships 关系关系复杂时可选配 Mermaid 图。输出保存为C4-Documentation/c4-code-[directory-name].md文件名使用清洗后的目录名/替换为-去除特殊字符。文档必须包含完整函数签名、指向真实源码位置的链接、全部内外部依赖、清晰描述性命名。重复对每个子目录执行直到所有目录都有对应的c4-code-*.md文件。预期产出即C4-Documentation/下每个目录一份c4-code-目录名.md。Code 级文档的 Mermaid 图选择配套的 c4-code/SKILL.md 给出了代码级图表选型指南Code 图展示单个组件的内部结构应根据编程范式选择图类型代码风格首选图适用场景OOP类、接口classDiagram展示继承、组合、接口实现FP纯函数、管道flowchart展示数据变换与函数组合FP带导出的模块带module的classDiagram展示模块结构与依赖过程式结构体函数classDiagram展示数据结构及关联函数混合风格组合使用必要时使用多张图同时提供三种可直接套用的 Mermaid 模板OOP 的classDiagram含namespace、interface、implements/uses关系、FP 的模块结构图module标记导出函数、以及数据流/函数依赖flowchart图subgraph组织 Input/Transform/Output 或 Public API/Internal/Pure Utilities。子代理还给出关键区分说明Code 代理聚焦单个代码元素Component 代理将多个代码文件综合为组件Container 代理把组件映射为部署单元Context 代理则创建高层系统图。Phase 2Component 级综合2.1 分析全部 Code 级文档收集 Phase 1 生成的c4-code-*.md文件分析代码结构、依赖与关系并依据三种边界识别逻辑组件领域边界相关的业务功能技术边界共享框架、库组织边界团队归属若可见。2.2 生成组件文档对每个识别出的组件使用 Task 工具调度subagent_typec4-architecture::c4-component提示词要求产出OverviewName有意义的组件名、Description、TypeApplication/Service/Library 等、Technology主要技术。Purpose组件做什么、解决什么问题、在系统中的角色。Software Features组件提供的全部软件功能及简述。Code Elements列出组件包含的所有c4-code-*.md文件并链接、简述。Interfaces文档化组件接口——接口名、协议REST/GraphQL/gRPC/Events 等、描述、操作函数签名、端点等。Dependencies使用的组件、外部系统数据库、API、服务。Component Diagram展示该组件及其关系的 Mermaid 图。输出保存为C4-Documentation/c4-component-[component-name].md使用清洗后的组件名预期每个组件一份文件。配套的 c4-component/SKILL.md 提供了C4Component图的 Mermaid 模板在Container_Boundary内放置Component与ComponentDb元素用Rel表达组件间调用、读写与对外部容器/系统的 API 依赖。其关键原则是组件图展示单个容器内部的逻辑组件聚焦组件职责、接口与交互并包含外部依赖其他容器、外部系统。2.3 创建主组件索引同样使用c4-architecture::c4-component子代理基于所有c4-component-*.md生成主索引C4-Documentation/c4-component.md包含System Components全部组件清单——组件名、简述、指向组件文档的链接Component Relationships Diagram展示所有组件间依赖关系及外部系统依赖的 Mermaid 图。Phase 3Container 级综合3.1 分析组件与部署定义回顾全部c4-component-*.md文件并搜索部署/基础设施定义DockerfileKubernetes 清单deployments、services 等Docker Compose 文件Terraform/CloudFormation 配置云服务定义AWS Lambda、Azure Functions 等CI/CD 管道定义。3.2 将组件映射到容器使用 Task 工具调度subagent_typec4-architecture::c4-container提示词要求产出Containers每个容器Name、Description用途与部署方式、TypeWeb Application/API/Database/Message Queue 等、TechnologyNode.js/Python/PostgreSQL 等、DeploymentDocker/Kubernetes/云服务等。Purpose容器做什么、如何部署、在系统中的角色。Components部署在该容器中的组件清单及其文档链接。Interfaces文档化容器 API——接口名、协议、描述、指向 OpenAPI/Swagger 规范文件的链接、端点/操作清单。API Specifications为每个容器 API 创建OpenAPI 3.1规范保存为C4-Documentation/apis/[container-name]-api.yaml包含全部端点及方法GET/POST 等、请求/响应 schema、认证要求、错误响应。Dependencies被依赖的容器、外部系统数据库、第三方 API、通信协议。Infrastructure指向部署配置Dockerfile、K8s 清单等的链接、扩缩容策略、资源需求CPU、内存、存储。Container Diagram展示全部容器及其关系、通信协议、外部依赖的 Mermaid 图。输出为C4-Documentation/c4-container.md预期包含全部容器与 API 规范。配套的 c4-container/SKILL.md 给出了C4Container图模板Person通过 HTTPS 访问System_Boundary内的ContainerWeb 应用、API 应用、ContainerDb数据库、Container_Queue消息队列各容器间用带协议的Rel连接JSON/HTTPS、SQL、消息发布并可与System_Ext外部系统交互。其关键原则容器层是技术选择细节归属的地方展示跨容器的职责分配、容器类型、通信协议与外部系统。该文件还提供了一份可直接复制的OpenAPI 3.1.0 规范模板含info、servers、paths下的get、parameters、responses结构作为每个容器 API 规范的起点。Phase 4Context 级文档4.1 分析系统文档回顾容器与组件文档并搜索系统级资料README、架构文档、需求文档、设计文档、测试文件用于理解系统行为、API 文档、用户文档。4.2 创建上下文文档使用 Task 工具调度subagent_typec4-architecture::c4-context提示词要求产出System Overview一句话短描述 详细长描述系统目的、能力、解决的问题。Personas对每个人物人类用户与程序化用户记录——人物名、类型Human User / Programmatic User / External System、描述是谁、需要什么、目标、使用的主要功能。System Features每个高层功能——功能名、描述、使用者哪些人物使用、指向用户旅程图的链接。User Journeys对每个关键功能与人物生成逐步旅程功能名-人物名 Journey包含系统全部触点对程序化用户外部系统、API则记录分步集成旅程。External Systems and Dependencies每个外部系统——系统名、类型Database/API/Service/Message Queue 等、描述提供什么、集成类型API/Events/File Transfer 等、目的系统为何依赖它。System Context Diagram使用 MermaidC4Context记号绘制——系统居中的方框、四周的人物、四周的外部系统、关系与数据流。Related Documentation指向容器与组件文档的链接。输出为C4-Documentation/c4-context.md。文档必须让非技术人员也能理解聚焦系统目的、用户与外部关系包含完整的用户旅程图识别全部外部系统与依赖。配套的 c4-context/SKILL.md 给出了C4Context图模板Person(user, User, ...)、System(system, ...)、System_Ext(...)、SystemDb(...)配合Rel表达使用与数据流关系。其关键原则源自 c4model.com 的 System Context 图定义聚焦人与软件系统而非技术、清晰展示系统边界、包含全部用户人类与程序化、包含系统交互的全部外部系统、保持对非技术受众友好、避免展示技术/协议/底层细节。配置选项主文档在工作流末尾汇总了五个可调配置项便于在不同仓库规模与目标下调整执行配置项含义默认值target_directory待分析的根目录当前仓库根目录exclude_patterns排除模式node_modules、.git、build、dist等output_directoryC4 文档输出位置C4-Documentation/include_tests是否分析测试文件以获取上下文trueapi_formatAPI 规范格式openapi输出结构工作流最终在仓库根目录生成如下文档集C4-Documentation/ ├── c4-code-*.md # Code 级文档每个目录一份 ├── c4-component-*.md # Component 级文档每个组件一份 ├── c4-component.md # 主组件索引 ├── c4-container.md # Container 级文档 ├── c4-context.md # Context 级文档 └── apis/ # API 规范 ├── [container]-api.yaml # 每个容器的 OpenAPI 规范 └── ...成功标准工作流定义了完整的验收清单可用于在收尾阶段逐项核验产出质量✅ 每个子目录都有对应的c4-code-*.md文件✅ 所有代码级文档包含完整函数签名✅ 组件按清晰边界进行逻辑分组✅ 所有组件都有接口文档✅ 已创建带关系图的主组件索引✅ 容器映射到实际部署单元✅ 所有容器 API 均以 OpenAPI/Swagger 规范文档化✅ 容器图展示部署架构✅ 系统上下文包含全部人物人类与程序化✅ 所有关键功能都记录了用户旅程✅ 全部外部系统与依赖均已识别✅ 上下文图展示系统、用户与外部系统✅ 文档统一组织在C4-Documentation/目录中。协调注意事项多代理、多阶段工作流对执行顺序与一致性有严格要求主文档给出七条协调准则自底向上处理按目录从最深到最浅依次处理增量综合每一层都建立在前一层文档之上完整覆盖综合之前每个目录必须已有代码级文档链接一致性所有文档文件之间需相互适当链接API 文档容器 API 必须有 OpenAPI/Swagger 规范利益相关者友好上下文文档应能被非技术利益相关者理解Mermaid 图所有图使用规范的 C4 Mermaid 记号。使用示例在 Claude Code 中可通过技能斜杠命令直接触发整套流程/c4-architecture:c4-architecture该命令将依次执行自底向上遍历全部子目录 → 为每个目录创建c4-code-*.md→ 综合为组件 → 映射到带 API 文档的容器 → 创建带人物与旅程的系统上下文。所有文档写入C4-Documentation/。限制与使用前提技能末尾明确了三条边界使用时必须遵守仅在任务与上述范围明确匹配时使用本技能不要将产出视为环境特定验证、测试或专家评审的替代品当缺少必要输入、权限、安全边界或成功标准时停下来请求澄清。结合配套子代理文档还可以看到本工作流的定位是文档生成与综合而非验证与评审四个子代理c4-code、c4-component、c4-container、c4-context均声明其产出不能替代环境特定验证、测试或专家评审。因此实践中建议将生成的C4-Documentation/作为架构沟通与评审的起点再结合实际部署环境与领域专家意见进行复核。结语从既有代码库到可沟通的架构视图本工作流把 C4 模型从画图方法论落地为可重复执行的 Agent 流程以自底向上的目录遍历保证证据完备以四个专用子代理的分工保证每层文档的专业深度以统一的C4-Documentation/输出结构与成功标准保证交付物的一致性与可验收性。无论你的仓库是单体、微服务还是混合架构这套流程都能帮助团队在数十分钟内获得一套覆盖 Code→Component→Container→Context 四级的、可链接、可检索、可评审的架构文档集。【免费下载链接】agentic-awesome-skillsAAS Core is the local, agent-first control plane for complete catalog discovery, agent-owned selection, stack validation, and planning, backed by 2,600 agentic skills. Includes CLI, local MCP, catalog, plugins, and Workbench.项目地址: https://gitcode.com/GitHub_Trending/an/agentic-awesome-skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
